001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2017, by Object Refinery Limited and Contributors.
006 *
007 * Project Info:  http://www.jfree.org/jfreechart/index.html
008 *
009 * This library is free software; you can redistribute it and/or modify it
010 * under the terms of the GNU Lesser General Public License as published by
011 * the Free Software Foundation; either version 2.1 of the License, or
012 * (at your option) any later version.
013 *
014 * This library is distributed in the hope that it will be useful, but
015 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
016 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
017 * License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this library; if not, write to the Free Software
021 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
022 * USA.
023 *
024 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 
025 * Other names may be trademarks of their respective owners.]
026 *
027 * ------------
028 * Quarter.java
029 * ------------
030 * (C) Copyright 2001-2012, by Object Refinery Limited.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   -;
034 *
035 * Changes
036 * -------
037 * 11-Oct-2001 : Version 1 (DG);
038 * 18-Dec-2001 : Changed order of parameters in constructor (DG);
039 * 19-Dec-2001 : Added a new constructor as suggested by Paul English (DG);
040 * 29-Jan-2002 : Added a new method parseQuarter(String) (DG);
041 * 14-Feb-2002 : Fixed bug in Quarter(Date) constructor (DG);
042 * 26-Feb-2002 : Changed getStart(), getMiddle() and getEnd() methods to
043 *               evaluate with reference to a particular time zone (DG);
044 * 19-Mar-2002 : Changed API for TimePeriod classes (DG);
045 * 24-Jun-2002 : Removed main method (just test code) (DG);
046 * 10-Sep-2002 : Added getSerialIndex() method (DG);
047 * 07-Oct-2002 : Fixed errors reported by Checkstyle (DG);
048 * 10-Jan-2003 : Changed base class and method names (DG);
049 * 13-Mar-2003 : Moved to com.jrefinery.data.time package, and implemented
050 *               Serializable (DG);
051 * 21-Oct-2003 : Added hashCode() method (DG);
052 * 10-Dec-2005 : Fixed argument checking bug (1377239) in constructor (DG);
053 * ------------- JFREECHART 1.0.x ---------------------------------------------
054 * 05-Oct-2006 : Updated API docs (DG);
055 * 06-Oct-2006 : Refactored to cache first and last millisecond values (DG);
056 * 16-Sep-2008 : Deprecated DEFAULT_TIME_ZONE (DG);
057 * 25-Nov-2008 : Added new constructor with Locale (DG);
058 * 05-Jul-2012 : REmoved JDK 1.3.1 supporting code (DG);
059 *
060 */
061
062package org.jfree.data.time;
063
064import java.io.Serializable;
065import java.util.Calendar;
066import java.util.Date;
067import java.util.Locale;
068import java.util.TimeZone;
069import org.jfree.chart.date.MonthConstants;
070import org.jfree.chart.date.SerialDate;
071
072/**
073 * Defines a quarter (in a given year).  The range supported is Q1 1900 to
074 * Q4 9999.  This class is immutable, which is a requirement for all
075 * {@link RegularTimePeriod} subclasses.
076 */
077public class Quarter extends RegularTimePeriod implements Serializable {
078
079    /** For serialization. */
080    private static final long serialVersionUID = 3810061714380888671L;
081
082    /** Constant for quarter 1. */
083    public static final int FIRST_QUARTER = 1;
084
085    /** Constant for quarter 4. */
086    public static final int LAST_QUARTER = 4;
087
088    /** The first month in each quarter. */
089    public static final int[] FIRST_MONTH_IN_QUARTER = {
090        0, MonthConstants.JANUARY, MonthConstants.APRIL, MonthConstants.JULY,
091        MonthConstants.OCTOBER
092    };
093
094    /** The last month in each quarter. */
095    public static final int[] LAST_MONTH_IN_QUARTER = {
096        0, MonthConstants.MARCH, MonthConstants.JUNE, MonthConstants.SEPTEMBER,
097        MonthConstants.DECEMBER
098    };
099
100    /** The year in which the quarter falls. */
101    private short year;
102
103    /** The quarter (1-4). */
104    private byte quarter;
105
106    /** The first millisecond. */
107    private long firstMillisecond;
108
109    /** The last millisecond. */
110    private long lastMillisecond;
111
112    /**
113     * Constructs a new Quarter, based on the current system date/time.
114     */
115    public Quarter() {
116        this(new Date());
117    }
118
119    /**
120     * Constructs a new quarter.
121     *
122     * @param year  the year (1900 to 9999).
123     * @param quarter  the quarter (1 to 4).
124     */
125    public Quarter(int quarter, int year) {
126        if ((quarter < FIRST_QUARTER) || (quarter > LAST_QUARTER)) {
127            throw new IllegalArgumentException("Quarter outside valid range.");
128        }
129        this.year = (short) year;
130        this.quarter = (byte) quarter;
131        peg(Calendar.getInstance());
132    }
133
134    /**
135     * Constructs a new quarter.
136     *
137     * @param quarter  the quarter (1 to 4).
138     * @param year  the year (1900 to 9999).
139     */
140    public Quarter(int quarter, Year year) {
141        if ((quarter < FIRST_QUARTER) || (quarter > LAST_QUARTER)) {
142            throw new IllegalArgumentException("Quarter outside valid range.");
143        }
144        this.year = (short) year.getYear();
145        this.quarter = (byte) quarter;
146        peg(Calendar.getInstance());
147    }
148
149    /**
150     * Constructs a new instance, based on a date/time and the default time
151     * zone.
152     *
153     * @param time  the date/time ({@code null} not permitted).
154     *
155     * @see #Quarter(Date, TimeZone, Locale)
156     */
157    public Quarter(Date time) {
158        this(time, TimeZone.getDefault(), Locale.getDefault());
159    }
160
161    /**
162     * Creates a new {@code Quarter} instance, using the specified
163     * zone and locale.
164     *
165     * @param time  the current time.
166     * @param zone  the time zone.
167     * @param locale  the locale.
168     *
169     * @since 1.0.12
170     */
171    public Quarter(Date time, TimeZone zone, Locale locale) {
172        Calendar calendar = Calendar.getInstance(zone, locale);
173        calendar.setTime(time);
174        int month = calendar.get(Calendar.MONTH) + 1;
175        this.quarter = (byte) SerialDate.monthCodeToQuarter(month);
176        this.year = (short) calendar.get(Calendar.YEAR);
177        peg(calendar);
178    }
179
180    /**
181     * Returns the quarter.
182     *
183     * @return The quarter.
184     */
185    public int getQuarter() {
186        return this.quarter;
187    }
188
189    /**
190     * Returns the year.
191     *
192     * @return The year.
193     */
194    public Year getYear() {
195        return new Year(this.year);
196    }
197
198    /**
199     * Returns the year.
200     *
201     * @return The year.
202     *
203     * @since 1.0.3
204     */
205    public int getYearValue() {
206        return this.year;
207    }
208
209    /**
210     * Returns the first millisecond of the quarter.  This will be determined
211     * relative to the time zone specified in the constructor, or in the
212     * calendar instance passed in the most recent call to the
213     * {@link #peg(Calendar)} method.
214     *
215     * @return The first millisecond of the quarter.
216     *
217     * @see #getLastMillisecond()
218     */
219    @Override
220    public long getFirstMillisecond() {
221        return this.firstMillisecond;
222    }
223
224    /**
225     * Returns the last millisecond of the quarter.  This will be
226     * determined relative to the time zone specified in the constructor, or
227     * in the calendar instance passed in the most recent call to the
228     * {@link #peg(Calendar)} method.
229     *
230     * @return The last millisecond of the quarter.
231     *
232     * @see #getFirstMillisecond()
233     */
234    @Override
235    public long getLastMillisecond() {
236        return this.lastMillisecond;
237    }
238
239    /**
240     * Recalculates the start date/time and end date/time for this time period
241     * relative to the supplied calendar (which incorporates a time zone).
242     *
243     * @param calendar  the calendar ({@code null} not permitted).
244     *
245     * @since 1.0.3
246     */
247    @Override
248    public void peg(Calendar calendar) {
249        this.firstMillisecond = getFirstMillisecond(calendar);
250        this.lastMillisecond = getLastMillisecond(calendar);
251    }
252
253    /**
254     * Returns the quarter preceding this one.
255     *
256     * @return The quarter preceding this one (or {@code null} if this is
257     *     Q1 1900).
258     */
259    @Override
260    public RegularTimePeriod previous() {
261        Quarter result;
262        if (this.quarter > FIRST_QUARTER) {
263            result = new Quarter(this.quarter - 1, this.year);
264        }
265        else {
266            if (this.year > 1900) {
267                result = new Quarter(LAST_QUARTER, this.year - 1);
268            }
269            else {
270                result = null;
271            }
272        }
273        return result;
274    }
275
276    /**
277     * Returns the quarter following this one.
278     *
279     * @return The quarter following this one (or null if this is Q4 9999).
280     */
281    @Override
282    public RegularTimePeriod next() {
283        Quarter result;
284        if (this.quarter < LAST_QUARTER) {
285            result = new Quarter(this.quarter + 1, this.year);
286        }
287        else {
288            if (this.year < 9999) {
289                result = new Quarter(FIRST_QUARTER, this.year + 1);
290            }
291            else {
292                result = null;
293            }
294        }
295        return result;
296    }
297
298    /**
299     * Returns a serial index number for the quarter.
300     *
301     * @return The serial index number.
302     */
303    @Override
304    public long getSerialIndex() {
305        return this.year * 4L + this.quarter;
306    }
307
308    /**
309     * Tests the equality of this Quarter object to an arbitrary object.
310     * Returns {@code true} if the target is a Quarter instance
311     * representing the same quarter as this object.  In all other cases,
312     * returns {@code false}.
313     *
314     * @param obj  the object ({@code null} permitted).
315     *
316     * @return {@code true} if quarter and year of this and the object are
317     *         the same.
318     */
319    @Override
320    public boolean equals(Object obj) {
321
322        if (obj != null) {
323            if (obj instanceof Quarter) {
324                Quarter target = (Quarter) obj;
325                return (this.quarter == target.getQuarter()
326                        && (this.year == target.getYearValue()));
327            }
328            else {
329                return false;
330            }
331        }
332        else {
333            return false;
334        }
335
336    }
337
338    /**
339     * Returns a hash code for this object instance.  The approach described by
340     * Joshua Bloch in "Effective Java" has been used here:
341     * <p>
342     * {@code http://developer.java.sun.com/developer/Books/effectivejava
343     * /Chapter3.pdf}
344     *
345     * @return A hash code.
346     */
347    @Override
348    public int hashCode() {
349        int result = 17;
350        result = 37 * result + this.quarter;
351        result = 37 * result + this.year;
352        return result;
353    }
354
355    /**
356     * Returns an integer indicating the order of this Quarter object relative
357     * to the specified object:
358     *
359     * negative == before, zero == same, positive == after.
360     *
361     * @param o1  the object to compare
362     *
363     * @return negative == before, zero == same, positive == after.
364     */
365    @Override
366    public int compareTo(Object o1) {
367
368        int result;
369
370        // CASE 1 : Comparing to another Quarter object
371        // --------------------------------------------
372        if (o1 instanceof Quarter) {
373            Quarter q = (Quarter) o1;
374            result = this.year - q.getYearValue();
375            if (result == 0) {
376                result = this.quarter - q.getQuarter();
377            }
378        }
379
380        // CASE 2 : Comparing to another TimePeriod object
381        // -----------------------------------------------
382        else if (o1 instanceof RegularTimePeriod) {
383            // more difficult case - evaluate later...
384            result = 0;
385        }
386
387        // CASE 3 : Comparing to a non-TimePeriod object
388        // ---------------------------------------------
389        else {
390            // consider time periods to be ordered after general objects
391            result = 1;
392        }
393
394        return result;
395
396    }
397
398    /**
399     * Returns a string representing the quarter (e.g. "Q1/2002").
400     *
401     * @return A string representing the quarter.
402     */
403    @Override
404    public String toString() {
405        return "Q" + this.quarter + "/" + this.year;
406    }
407
408    /**
409     * Returns the first millisecond in the Quarter, evaluated using the
410     * supplied calendar (which determines the time zone).
411     *
412     * @param calendar  the calendar ({@code null} not permitted).
413     *
414     * @return The first millisecond in the Quarter.
415     *
416     * @throws NullPointerException if {@code calendar} is
417     *     {@code null}.
418     */
419    @Override
420    public long getFirstMillisecond(Calendar calendar) {
421        int month = Quarter.FIRST_MONTH_IN_QUARTER[this.quarter];
422        calendar.set(this.year, month - 1, 1, 0, 0, 0);
423        calendar.set(Calendar.MILLISECOND, 0);
424        return calendar.getTimeInMillis();
425    }
426
427    /**
428     * Returns the last millisecond of the Quarter, evaluated using the
429     * supplied calendar (which determines the time zone).
430     *
431     * @param calendar  the calendar ({@code null} not permitted).
432     *
433     * @return The last millisecond of the Quarter.
434     *
435     * @throws NullPointerException if {@code calendar} is
436     *     {@code null}.
437     */
438    @Override
439    public long getLastMillisecond(Calendar calendar) {
440        int month = Quarter.LAST_MONTH_IN_QUARTER[this.quarter];
441        int eom = SerialDate.lastDayOfMonth(month, this.year);
442        calendar.set(this.year, month - 1, eom, 23, 59, 59);
443        calendar.set(Calendar.MILLISECOND, 999);
444        return calendar.getTimeInMillis();
445    }
446
447    /**
448     * Parses the string argument as a quarter.
449     * <P>
450     * This method should accept the following formats: "YYYY-QN" and "QN-YYYY",
451     * where the "-" can be a space, a forward-slash (/), comma or a dash (-).
452     * @param s A string representing the quarter.
453     *
454     * @return The quarter.
455     */
456    public static Quarter parseQuarter(String s) {
457
458        // find the Q and the integer following it (remove both from the
459        // string)...
460        int i = s.indexOf("Q");
461        if (i == -1) {
462            throw new TimePeriodFormatException("Missing Q.");
463        }
464
465        if (i == s.length() - 1) {
466            throw new TimePeriodFormatException("Q found at end of string.");
467        }
468
469        String qstr = s.substring(i + 1, i + 2);
470        int quarter = Integer.parseInt(qstr);
471        String remaining = s.substring(0, i) + s.substring(i + 2, s.length());
472
473        // replace any / , or - with a space
474        remaining = remaining.replace('/', ' ');
475        remaining = remaining.replace(',', ' ');
476        remaining = remaining.replace('-', ' ');
477
478        // parse the string...
479        Year year = Year.parseYear(remaining.trim());
480        Quarter result = new Quarter(quarter, year);
481        return result;
482
483    }
484
485}