    001    /* ===========================================================
    002     * JFreeChart : a free chart library for the Java(tm) platform
    003     * ===========================================================
    004     *
    005     * (C) Copyright 2000-2007, 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     * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
    025     * in the United States and other countries.]
    026     *
    027     * ----------
    028     * Month.java
    029     * ----------
    030     * (C) Copyright 2001-2007, by Object Refinery Limited and Contributors.
    031     *
    032     * Original Author:  David Gilbert (for Object Refinery Limited);
    033     * Contributor(s):   Chris Boek;
    034     *
    035     * Changes
    036     * -------
    037     * 11-Oct-2001 : Version 1 (DG);
    038     * 14-Nov-2001 : Added method to get year as primitive (DG);
    039     *               Override for toString() method (DG);
    040     * 18-Dec-2001 : Changed order of parameters in constructor (DG);
    041     * 19-Dec-2001 : Added a new constructor as suggested by Paul English (DG);
    042     * 29-Jan-2002 : Worked on the parseMonth() method (DG);
    043     * 14-Feb-2002 : Fixed bugs in the Month constructors (DG);
    044     * 26-Feb-2002 : Changed getStart(), getMiddle() and getEnd() methods to
    045     *               evaluate with reference to a particular time zone (DG);
    046     * 19-Mar-2002 : Changed API for TimePeriod classes (DG);
    047     * 10-Sep-2002 : Added getSerialIndex() method (DG);
    048     * 04-Oct-2002 : Fixed errors reported by Checkstyle (DG);
    049     * 10-Jan-2003 : Changed base class and method names (DG);
    050     * 13-Mar-2003 : Moved to com.jrefinery.data.time package, and implemented
    051     *               Serializable (DG);
    052     * 21-Oct-2003 : Added hashCode() method (DG);
    053     * 01-Nov-2005 : Fixed bug 1345383 (argument check in constructor) (DG);
    054     * ------------- JFREECHART 1.0.x ---------------------------------------------
    055     * 05-Oct-2006 : Updated API docs (DG);
    056     * 06-Oct-2006 : Refactored to cache first and last millisecond values (DG);
    057     * 04-Apr-2007 : Fixed bug in Month(Date, TimeZone) constructor (CB);
    058     *
    059     */
    060
    061    package org.jfree.data.time;
    062
    063    import java.io.Serializable;
    064    import java.util.Calendar;
    065    import java.util.Date;
    066    import java.util.TimeZone;
    067
    068    import org.jfree.date.MonthConstants;
    069    import org.jfree.date.SerialDate;
    070
    071    /**
    072     * Represents a single month.  This class is immutable, which is a requirement
    073     * for all {@link RegularTimePeriod} subclasses.
    074     */
    075    public class Month extends RegularTimePeriod implements Serializable {
    076
    077        /** For serialization. */
    078        private static final long serialVersionUID = -5090216912548722570L;
    079
    080        /** The month (1-12). */
    081        private int month;
    082
    083        /** The year in which the month falls. */
    084        private int year;
    085
    086        /** The first millisecond. */
    087        private long firstMillisecond;
    088
    089        /** The last millisecond. */
    090        private long lastMillisecond;
    091
    092        /**
    093         * Constructs a new Month, based on the current system time.
    094         */
    095        public Month() {
    096            this(new Date());
    097        }
    098
    099        /**
    100         * Constructs a new month instance.
    101         *
    102         * @param month  the month (in the range 1 to 12).
    103         * @param year  the year.
    104         */
    105        public Month(int month, int year) {
    106            if ((month < 1) || (month > 12)) {
    107                throw new IllegalArgumentException("Month outside valid range.");
    108            }
    109            this.month = month;
    110            this.year = year;
    111            peg(Calendar.getInstance());
    112        }
    113
    114        /**
    115         * Constructs a new month instance.
    116         *
    117         * @param month  the month (in the range 1 to 12).
    118         * @param year  the year.
    119         */
    120        public Month(int month, Year year) {
    121            if ((month < 1) || (month > 12)) {
    122                throw new IllegalArgumentException("Month outside valid range.");
    123            }
    124            this.month = month;
    125            this.year = year.getYear();
    126            peg(Calendar.getInstance());
    127        }
    128
    129        /**
    130         * Constructs a new <code>Month</code> instance, based on a date/time and
    131         * the default time zone.
    132         *
    133         * @param time  the date/time.
    134         */
    135        public Month(Date time) {
    136            this(time, RegularTimePeriod.DEFAULT_TIME_ZONE);
    137        }
    138
    139        /**
    140         * Constructs a new <code>Month</code> instance, based on a date/time and
    141         * a time zone.  The first and last millisecond values are initially
    142         * pegged to the given time zone also.
    143         *
    144         * @param time  the date/time.
    145         * @param zone  the time zone (<code>null</code> not permitted).
    146         */
    147        public Month(Date time, TimeZone zone) {
    148            Calendar calendar = Calendar.getInstance(zone);
    149            calendar.setTime(time);
    150            this.month = calendar.get(Calendar.MONTH) + 1;
    151            this.year = calendar.get(Calendar.YEAR);
    152            peg(calendar);
    153        }
    154
    155        /**
    156         * Returns the year in which the month falls.
    157         *
    158         * @return The year in which the month falls (as a Year object).
    159         */
    160        public Year getYear() {
    161            return new Year(this.year);
    162        }
    163
    164        /**
    165         * Returns the year in which the month falls.
    166         *
    167         * @return The year in which the month falls (as an int).
    168         */
    169        public int getYearValue() {
    170            return this.year;
    171        }
    172
    173        /**
    174         * Returns the month.  Note that 1=JAN, 2=FEB, ...
    175         *
    176         * @return The month.
    177         */
    178        public int getMonth() {
    179            return this.month;
    180        }
    181
    182        /**
    183         * Returns the first millisecond of the month.  This will be determined
    184         * relative to the time zone specified in the constructor, or in the
    185         * calendar instance passed in the most recent call to the
    186         * {@link #peg(Calendar)} method.
    187         *
    188         * @return The first millisecond of the month.
    189         *
    190         * @see #getLastMillisecond()
    191         */
    192        public long getFirstMillisecond() {
    193            return this.firstMillisecond;
    194        }
    195
    196        /**
    197         * Returns the last millisecond of the month.  This will be
    198         * determined relative to the time zone specified in the constructor, or
    199         * in the calendar instance passed in the most recent call to the
    200         * {@link #peg(Calendar)} method.
    201         *
    202         * @return The last millisecond of the month.
    203         *
    204         * @see #getFirstMillisecond()
    205         */
    206        public long getLastMillisecond() {
    207            return this.lastMillisecond;
    208        }
    209
    210        /**
    211         * Recalculates the start date/time and end date/time for this time period
    212         * relative to the supplied calendar (which incorporates a time zone).
    213         *
    214         * @param calendar  the calendar (<code>null</code> not permitted).
    215         *
    216         * @since 1.0.3
    217         */
    218        public void peg(Calendar calendar) {
    219            this.firstMillisecond = getFirstMillisecond(calendar);
    220            this.lastMillisecond = getLastMillisecond(calendar);
    221        }
    222
    223        /**
    224         * Returns the month preceding this one.
    225         *
    226         * @return The month preceding this one.
    227         */
    228        public RegularTimePeriod previous() {
    229            Month result;
    230            if (this.month != MonthConstants.JANUARY) {
    231                result = new Month(this.month - 1, this.year);
    232            }
    233            else {
    234                if (this.year > 1900) {
    235                    result = new Month(MonthConstants.DECEMBER, this.year - 1);
    236                }
    237                else {
    238                    result = null;
    239                }
    240            }
    241            return result;
    242        }
    243
    244        /**
    245         * Returns the month following this one.
    246         *
    247         * @return The month following this one.
    248         */
    249        public RegularTimePeriod next() {
    250            Month result;
    251            if (this.month != MonthConstants.DECEMBER) {
    252                result = new Month(this.month + 1, this.year);
    253            }
    254            else {
    255                if (this.year < 9999) {
    256                    result = new Month(MonthConstants.JANUARY, this.year + 1);
    257                }
    258                else {
    259                    result = null;
    260                }
    261            }
    262            return result;
    263        }
    264
    265        /**
    266         * Returns a serial index number for the month.
    267         *
    268         * @return The serial index number.
    269         */
    270        public long getSerialIndex() {
    271            return this.year * 12L + this.month;
    272        }
    273
    274        /**
    275         * Returns a string representing the month (e.g. "January 2002").
    276         * <P>
    277         * To do: look at internationalisation.
    278         *
    279         * @return A string representing the month.
    280         */
    281        public String toString() {
    282            return SerialDate.monthCodeToString(this.month) + " " + this.year;
    283        }
    284
    285        /**
    286         * Tests the equality of this Month object to an arbitrary object.
    287         * Returns true if the target is a Month instance representing the same
    288         * month as this object.  In all other cases, returns false.
    289         *
    290         * @param obj  the object (<code>null</code> permitted).
    291         *
    292         * @return <code>true</code> if month and year of this and object are the
    293         *         same.
    294         */
    295        public boolean equals(Object obj) {
    296
    297            if (obj != null) {
    298                if (obj instanceof Month) {
    299                    Month target = (Month) obj;
    300                    return (this.month == target.getMonth()
    301                            && (this.year == target.getYearValue()));
    302                }
    303                else {
    304                    return false;
    305                }
    306            }
    307            else {
    308                return false;
    309            }
    310
    311        }
    312
    313        /**
    314         * Returns a hash code for this object instance.  The approach described by
    315         * Joshua Bloch in "Effective Java" has been used here:
    316         * <p>
    317         * <code>http://developer.java.sun.com/developer/Books/effectivejava
    318         * /Chapter3.pdf</code>
    319         *
    320         * @return A hash code.
    321         */
    322        public int hashCode() {
    323            int result = 17;
    324            result = 37 * result + this.month;
    325            result = 37 * result + this.year;
    326            return result;
    327        }
    328
    329        /**
    330         * Returns an integer indicating the order of this Month object relative to
    331         * the specified
    332         * object: negative == before, zero == same, positive == after.
    333         *
    334         * @param o1  the object to compare.
    335         *
    336         * @return negative == before, zero == same, positive == after.
    337         */
    338        public int compareTo(Object o1) {
    339
    340            int result;
    341
    342            // CASE 1 : Comparing to another Month object
    343            // --------------------------------------------
    344            if (o1 instanceof Month) {
    345                Month m = (Month) o1;
    346                result = this.year - m.getYearValue();
    347                if (result == 0) {
    348                    result = this.month - m.getMonth();
    349                }
    350            }
    351
    352            // CASE 2 : Comparing to another TimePeriod object
    353            // -----------------------------------------------
    354            else if (o1 instanceof RegularTimePeriod) {
    355                // more difficult case - evaluate later...
    356                result = 0;
    357            }
    358
    359            // CASE 3 : Comparing to a non-TimePeriod object
    360            // ---------------------------------------------
    361            else {
    362                // consider time periods to be ordered after general objects
    363                result = 1;
    364            }
    365
    366            return result;
    367
    368        }
    369
    370        /**
    371         * Returns the first millisecond of the month, evaluated using the supplied
    372         * calendar (which determines the time zone).
    373         *
    374         * @param calendar  the calendar (<code>null</code> not permitted).
    375         *
    376         * @return The first millisecond of the month.
    377         *
    378         * @throws NullPointerException if <code>calendar</code> is
    379         *     <code>null</code>.
    380         */
    381        public long getFirstMillisecond(Calendar calendar) {
    382            calendar.set(this.year, this.month - 1, 1, 0, 0, 0);
    383            calendar.set(Calendar.MILLISECOND, 0);
    384            // in the following line, we'd rather call calendar.getTimeInMillis()
    385            // to avoid object creation, but that isn't supported in Java 1.3.1
    386            return calendar.getTime().getTime();
    387        }
    388
    389        /**
    390         * Returns the last millisecond of the month, evaluated using the supplied
    391         * calendar (which determines the time zone).
    392         *
    393         * @param calendar  the calendar (<code>null</code> not permitted).
    394         *
    395         * @return The last millisecond of the month.
    396         *
    397         * @throws NullPointerException if <code>calendar</code> is
    398         *     <code>null</code>.
    399         */
    400        public long getLastMillisecond(Calendar calendar) {
    401            int eom = SerialDate.lastDayOfMonth(this.month, this.year);
    402            calendar.set(this.year, this.month - 1, eom, 23, 59, 59);
    403            calendar.set(Calendar.MILLISECOND, 999);
    404            // in the following line, we'd rather call calendar.getTimeInMillis()
    405            // to avoid object creation, but that isn't supported in Java 1.3.1
    406            return calendar.getTime().getTime();
    407        }
    408
    409        /**
    410         * Parses the string argument as a month.
    411         * <P>
    412         * This method is required to accept the format "YYYY-MM".  It will also
    413         * accept "MM-YYYY". Anything else, at the moment, is a bonus.
    414         *
    415         * @param s  the string to parse.
    416         *
    417         * @return <code>null</code> if the string is not parseable, the month
    418         *         otherwise.
    419         */
    420        public static Month parseMonth(String s) {
    421
    422            Month result = null;
    423            if (s != null) {
    424
    425                // trim whitespace from either end of the string
    426                s = s.trim();
    427
    428                int i = Month.findSeparator(s);
    429                if (i != -1) {
    430                    String s1 = s.substring(0, i).trim();
    431                    String s2 = s.substring(i + 1, s.length()).trim();
    432
    433                    Year year = Month.evaluateAsYear(s1);
    434                    int month;
    435                    if (year != null) {
    436                        month = SerialDate.stringToMonthCode(s2);
    437                        if (month == -1) {
    438                            throw new TimePeriodFormatException(
    439                                "Can't evaluate the month."
    440                            );
    441                        }
    442                        result = new Month(month, year);
    443                    }
    444                    else {
    445                        year = Month.evaluateAsYear(s2);
    446                        if (year != null) {
    447                            month = SerialDate.stringToMonthCode(s1);
    448                            if (month == -1) {
    449                                throw new TimePeriodFormatException(
    450                                    "Can't evaluate the month."
    451                                );
    452                            }
    453                            result = new Month(month, year);
    454                        }
    455                        else {
    456                            throw new TimePeriodFormatException(
    457                                "Can't evaluate the year."
    458                            );
    459                        }
    460                    }
    461
    462                }
    463                else {
    464                    throw new TimePeriodFormatException(
    465                        "Could not find separator."
    466                    );
    467                }
    468
    469            }
    470            return result;
    471
    472        }
    473
    474        /**
    475         * Finds the first occurrence of ' ', '-', ',' or '.'
    476         *
    477         * @param s  the string to parse.
    478         *
    479         * @return <code>-1</code> if none of the characters where found, the
    480         *      position of the first occurence otherwise.
    481         */
    482        private static int findSeparator(String s) {
    483
    484            int result = s.indexOf('-');
    485            if (result == -1) {
    486                result = s.indexOf(',');
    487            }
    488            if (result == -1) {
    489                result = s.indexOf(' ');
    490            }
    491            if (result == -1) {
    492                result = s.indexOf('.');
    493            }
    494            return result;
    495        }
    496
    497        /**
    498         * Creates a year from a string, or returns null (format exceptions
    499         * suppressed).
    500         *
    501         * @param s  the string to parse.
    502         *
    503         * @return <code>null</code> if the string is not parseable, the year
    504         *         otherwise.
    505         */
    506        private static Year evaluateAsYear(String s) {
    507
    508            Year result = null;
    509            try {
    510                result = Year.parseYear(s);
    511            }
    512            catch (TimePeriodFormatException e) {
    513                // suppress
    514            }
    515            return result;
    516
    517        }
    518
    519    }