    001    /* ===========================================================
    002     * JFreeChart : a free chart library for the Java(tm) platform
    003     * ===========================================================
    004     *
    005     * (C) Copyright 2000-2008, 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     * DateTickUnit.java
    029     * -----------------
    030     * (C) Copyright 2000-2008, by Object Refinery Limited.
    031     *
    032     * Original Author:  David Gilbert (for Object Refinery Limited);
    033     * Contributor(s):   Chris Boek;
    034     *
    035     * Changes
    036     * -------
    037     * 08-Nov-2002 : Moved to new package com.jrefinery.chart.axis (DG);
    038     * 27-Nov-2002 : Added IllegalArgumentException to getMillisecondCount()
    039     *               method (DG);
    040     * 26-Mar-2003 : Implemented Serializable (DG);
    041     * 12-Nov-2003 : Added roll fields that can improve the labelling on segmented
    042     *               date axes (DG);
    043     * 03-Dec-2003 : DateFormat constructor argument is now filled with an default
    044     *               if null (TM);
    045     * 07-Dec-2003 : Fixed bug (null pointer exception) in constructor (DG);
    046     * ------------- JFREECHART 1.0.x ---------------------------------------------
    047     * 21-Mar-2007 : Added toString() for debugging (DG);
    048     * 04-Apr-2007 : Added new methods addToDate(Date, TimeZone) and rollDate(Date,
    049     *               TimeZone) (CB);
    050     * 09-Jun-2008 : Deprecated addToDate(Date) (DG);
    051     *
    052     */
    053
    054    package org.jfree.chart.axis;
    055
    056    import java.io.Serializable;
    057    import java.text.DateFormat;
    058    import java.util.Calendar;
    059    import java.util.Date;
    060    import java.util.TimeZone;
    061
    062    import org.jfree.util.ObjectUtilities;
    063
    064    /**
    065     * A tick unit for use by subclasses of {@link DateAxis}. Instances of this
    066     * class are immutable.
    067     */
    068    public class DateTickUnit extends TickUnit implements Serializable {
    069
    070        /** For serialization. */
    071        private static final long serialVersionUID = -7289292157229621901L;
    072
    073        /** A constant for years. */
    074        public static final int YEAR = 0;
    075
    076        /** A constant for months. */
    077        public static final int MONTH = 1;
    078
    079        /** A constant for days. */
    080        public static final int DAY = 2;
    081
    082        /** A constant for hours. */
    083        public static final int HOUR = 3;
    084
    085        /** A constant for minutes. */
    086        public static final int MINUTE = 4;
    087
    088        /** A constant for seconds. */
    089        public static final int SECOND = 5;
    090
    091        /** A constant for milliseconds. */
    092        public static final int MILLISECOND = 6;
    093
    094        /** The unit. */
    095        private int unit;
    096
    097        /** The unit count. */
    098        private int count;
    099
    100        /** The roll unit. */
    101        private int rollUnit;
    102
    103        /** The roll count. */
    104        private int rollCount;
    105
    106        /** The date formatter. */
    107        private DateFormat formatter;
    108
    109        /**
    110         * Creates a new date tick unit.  The dates will be formatted using a
    111         * SHORT format for the default locale.
    112         *
    113         * @param unit  the unit.
    114         * @param count  the unit count.
    115         */
    116        public DateTickUnit(int unit, int count) {
    117            this(unit, count, null);
    118        }
    119
    120        /**
    121         * Creates a new date tick unit.  You can specify the units using one of
    122         * the constants YEAR, MONTH, DAY, HOUR, MINUTE, SECOND or MILLISECOND.
    123         * In addition, you can specify a unit count, and a date format.
    124         *
    125         * @param unit  the unit.
    126         * @param count  the unit count.
    127         * @param formatter  the date formatter (defaults to DateFormat.SHORT).
    128         */
    129        public DateTickUnit(int unit, int count, DateFormat formatter) {
    130
    131            this(unit, count, unit, count, formatter);
    132
    133        }
    134
    135        /**
    136         * Creates a new unit.
    137         *
    138         * @param unit  the unit.
    139         * @param count  the count.
    140         * @param rollUnit  the roll unit.
    141         * @param rollCount  the roll count.
    142         * @param formatter  the date formatter (defaults to DateFormat.SHORT).
    143         */
    144        public DateTickUnit(int unit, int count, int rollUnit, int rollCount,
    145                            DateFormat formatter) {
    146            super(DateTickUnit.getMillisecondCount(unit, count));
    147            this.unit = unit;
    148            this.count = count;
    149            this.rollUnit = rollUnit;
    150            this.rollCount = rollCount;
    151            this.formatter = formatter;
    152            if (formatter == null) {
    153                this.formatter = DateFormat.getDateInstance(DateFormat.SHORT);
    154            }
    155        }
    156
    157        /**
    158         * Returns the date unit.  This will be one of the constants
    159         * <code>YEAR</code>, <code>MONTH</code>, <code>DAY</code>,
    160         * <code>HOUR</code>, <code>MINUTE</code>, <code>SECOND</code> or
    161         * <code>MILLISECOND</code>, defined by this class.  Note that these
    162         * constants do NOT correspond to those defined in Java's
    163         * <code>Calendar</code> class.
    164         *
    165         * @return The date unit.
    166         */
    167        public int getUnit() {
    168            return this.unit;
    169        }
    170
    171        /**
    172         * Returns the unit count.
    173         *
    174         * @return The unit count.
    175         */
    176        public int getCount() {
    177            return this.count;
    178        }
    179
    180        /**
    181         * Returns the roll unit.  This is the amount by which the tick advances if
    182         * it is "hidden" when displayed on a segmented date axis.  Typically the
    183         * roll will be smaller than the regular tick unit (for example, a 7 day
    184         * tick unit might use a 1 day roll).
    185         *
    186         * @return The roll unit.
    187         */
    188        public int getRollUnit() {
    189            return this.rollUnit;
    190        }
    191
    192        /**
    193         * Returns the roll count.
    194         *
    195         * @return The roll count.
    196         */
    197        public int getRollCount() {
    198            return this.rollCount;
    199        }
    200
    201        /**
    202         * Formats a value.
    203         *
    204         * @param milliseconds  date in milliseconds since 01-01-1970.
    205         *
    206         * @return The formatted date.
    207         */
    208        public String valueToString(double milliseconds) {
    209            return this.formatter.format(new Date((long) milliseconds));
    210        }
    211
    212        /**
    213         * Formats a date using the tick unit's formatter.
    214         *
    215         * @param date  the date.
    216         *
    217         * @return The formatted date.
    218         */
    219        public String dateToString(Date date) {
    220            return this.formatter.format(date);
    221        }
    222
    223        /**
    224         * Calculates a new date by adding this unit to the base date, with
    225         * calculations performed in the default timezone and locale.
    226         *
    227         * @param base  the base date.
    228         *
    229         * @return A new date one unit after the base date.
    230         *
    231         * @see #addToDate(Date, TimeZone)
    232         *
    233         * @deprecated As of JFreeChart 1.0.10, this method is deprecated - you
    234         *     should use {@link #addToDate(Date, TimeZone)} instead.
    235         */
    236        public Date addToDate(Date base) {
    237            return addToDate(base, TimeZone.getDefault());
    238        }
    239
    240        /**
    241         * Calculates a new date by adding this unit to the base date.
    242         *
    243         * @param base  the base date.
    244         * @param zone  the time zone for the date calculation.
    245         *
    246         * @return A new date one unit after the base date.
    247         *
    248         * @since 1.0.6
    249         */
    250        public Date addToDate(Date base, TimeZone zone) {
    251            // as far as I know, the Locale for the calendar only affects week
    252            // number calculations, and since DateTickUnit doesn't do week
    253            // arithmetic, the default locale (whatever it is) should be fine
    254            // here...
    255            Calendar calendar = Calendar.getInstance(zone);
    256            calendar.setTime(base);
    257            calendar.add(getCalendarField(this.unit), this.count);
    258            return calendar.getTime();
    259        }
    260
    261        /**
    262         * Rolls the date forward by the amount specified by the roll unit and
    263         * count.
    264         *
    265         * @param base  the base date.
    266
    267         * @return The rolled date.
    268         *
    269         * @see #rollDate(Date, TimeZone)
    270         */
    271        public Date rollDate(Date base) {
    272            return rollDate(base, TimeZone.getDefault());
    273        }
    274
    275        /**
    276         * Rolls the date forward by the amount specified by the roll unit and
    277         * count.
    278         *
    279         * @param base  the base date.
    280         * @param zone  the time zone.
    281         *
    282         * @return The rolled date.
    283         *
    284         * @since 1.0.6
    285         */
    286        public Date rollDate(Date base, TimeZone zone) {
    287            // as far as I know, the Locale for the calendar only affects week
    288            // number calculations, and since DateTickUnit doesn't do week
    289            // arithmetic, the default locale (whatever it is) should be fine
    290            // here...
    291            Calendar calendar = Calendar.getInstance(zone);
    292            calendar.setTime(base);
    293            calendar.add(getCalendarField(this.rollUnit), this.rollCount);
    294            return calendar.getTime();
    295        }
    296
    297        /**
    298         * Returns a field code that can be used with the <code>Calendar</code>
    299         * class.
    300         *
    301         * @return The field code.
    302         */
    303        public int getCalendarField() {
    304            return getCalendarField(this.unit);
    305        }
    306
    307        /**
    308         * Returns a field code (that can be used with the Calendar class) for a
    309         * given 'unit' code.  The 'unit' is one of:  {@link #YEAR}, {@link #MONTH},
    310         * {@link #DAY}, {@link #HOUR}, {@link #MINUTE}, {@link #SECOND} and
    311         * {@link #MILLISECOND}.
    312         *
    313         * @param tickUnit  the unit.
    314         *
    315         * @return The field code.
    316         */
    317        private int getCalendarField(int tickUnit) {
    318
    319            switch (tickUnit) {
    320                case (YEAR):
    321                    return Calendar.YEAR;
    322                case (MONTH):
    323                    return Calendar.MONTH;
    324                case (DAY):
    325                    return Calendar.DATE;
    326                case (HOUR):
    327                    return Calendar.HOUR_OF_DAY;
    328                case (MINUTE):
    329                    return Calendar.MINUTE;
    330                case (SECOND):
    331                    return Calendar.SECOND;
    332                case (MILLISECOND):
    333                    return Calendar.MILLISECOND;
    334                default:
    335                    return Calendar.MILLISECOND;
    336            }
    337
    338        }
    339
    340        /**
    341         * Returns the (approximate) number of milliseconds for the given unit and
    342         * unit count.
    343         * <P>
    344         * This value is an approximation some of the time (e.g. months are
    345         * assumed to have 31 days) but this shouldn't matter.
    346         *
    347         * @param unit  the unit.
    348         * @param count  the unit count.
    349         *
    350         * @return The number of milliseconds.
    351         */
    352        private static long getMillisecondCount(int unit, int count) {
    353
    354            switch (unit) {
    355                case (YEAR):
    356                    return (365L * 24L * 60L * 60L * 1000L) * count;
    357                case (MONTH):
    358                    return (31L * 24L * 60L * 60L * 1000L) * count;
    359                case (DAY):
    360                    return (24L * 60L * 60L * 1000L) * count;
    361                case (HOUR):
    362                    return (60L * 60L * 1000L) * count;
    363                case (MINUTE):
    364                    return (60L * 1000L) * count;
    365                case (SECOND):
    366                    return 1000L * count;
    367                case (MILLISECOND):
    368                    return count;
    369                default:
    370                    throw new IllegalArgumentException(
    371                        "DateTickUnit.getMillisecondCount() : unit must "
    372                        + "be one of the constants YEAR, MONTH, DAY, HOUR, MINUTE, "
    373                        + "SECOND or MILLISECOND defined in the DateTickUnit "
    374                        + "class. Do *not* use the constants defined in "
    375                        + "java.util.Calendar."
    376                    );
    377            }
    378
    379        }
    380
    381        /**
    382         * Tests this unit for equality with another object.
    383         *
    384         * @param obj  the object (<code>null</code> permitted).
    385         *
    386         * @return <code>true</code> or <code>false</code>.
    387         */
    388        public boolean equals(Object obj) {
    389            if (obj == this) {
    390                return true;
    391            }
    392            if (!(obj instanceof DateTickUnit)) {
    393                return false;
    394            }
    395            if (!super.equals(obj)) {
    396                return false;
    397            }
    398            DateTickUnit that = (DateTickUnit) obj;
    399            if (this.unit != that.unit) {
    400                return false;
    401            }
    402            if (this.count != that.count) {
    403                return false;
    404            }
    405            if (!ObjectUtilities.equal(this.formatter, that.formatter)) {
    406                return false;
    407            }
    408            return true;
    409        }
    410
    411        /**
    412         * Returns a hash code for this object.
    413         *
    414         * @return A hash code.
    415         */
    416        public int hashCode() {
    417            int result = 19;
    418            result = 37 * result + this.unit;
    419            result = 37 * result + this.count;
    420            result = 37 * result + this.formatter.hashCode();
    421            return result;
    422        }
    423
    424        /**
    425         * Strings for use by the toString() method.
    426         */
    427        private static final String[] units = {"YEAR", "MONTH", "DAY", "HOUR",
    428                "MINUTE", "SECOND", "MILLISECOND"};
    429
    430        /**
    431         * Returns a string representation of this instance, primarily used for
    432         * debugging purposes.
    433         *
    434         * @return A string representation of this instance.
    435         */
    436        public String toString() {
    437            return "DateTickUnit[" + DateTickUnit.units[this.unit] + ", "
    438                    + this.count + "]";
    439        }
    440
    441    }