    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     * Millisecond.java
    029     * ----------------
    030     * (C) Copyright 2001-2008, 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     * 19-Dec-2001 : Added new constructors as suggested by Paul English (DG);
    039     * 26-Feb-2002 : Added new getStart() and getEnd() methods (DG);
    040     * 29-Mar-2002 : Fixed bug in getStart(), getEnd() and compareTo() methods (DG);
    041     * 10-Sep-2002 : Added getSerialIndex() method (DG);
    042     * 07-Oct-2002 : Fixed errors reported by Checkstyle (DG);
    043     * 10-Jan-2003 : Changed base class and method names (DG);
    044     * 13-Mar-2003 : Moved to com.jrefinery.data.time package and implemented
    045     *               Serializable (DG);
    046     * 21-Oct-2003 : Added hashCode() method (DG);
    047     * ------------- JFREECHART 1.0.x ---------------------------------------------
    048     * 05-Oct-2006 : Updated API docs (DG);
    049     * 06-Oct-2006 : Refactored to cache first and last millisecond values (DG);
    050     * 04-Apr-2007 : In Millisecond(Date, TimeZone), peg milliseconds to the
    051     *               specified zone (DG);
    052     * 06-Jun-2008 : Added handling for general RegularTimePeriod in compareTo()
    053     *               method:
    054     *               see http://www.jfree.org/phpBB2/viewtopic.php?t=24805 (DG);
    055     *
    056     */
    057
    058    package org.jfree.data.time;
    059
    060    import java.io.Serializable;
    061    import java.util.Calendar;
    062    import java.util.Date;
    063    import java.util.TimeZone;
    064
    065    /**
    066     * Represents a millisecond.  This class is immutable, which is a requirement
    067     * for all {@link RegularTimePeriod} subclasses.
    068     */
    069    public class Millisecond extends RegularTimePeriod implements Serializable {
    070
    071        /** For serialization. */
    072        static final long serialVersionUID = -5316836467277638485L;
    073
    074        /** A constant for the first millisecond in a second. */
    075        public static final int FIRST_MILLISECOND_IN_SECOND = 0;
    076
    077        /** A constant for the last millisecond in a second. */
    078        public static final int LAST_MILLISECOND_IN_SECOND = 999;
    079
    080        /** The day. */
    081        private Day day;
    082
    083        /** The hour in the day. */
    084        private byte hour;
    085
    086        /** The minute. */
    087        private byte minute;
    088
    089        /** The second. */
    090        private byte second;
    091
    092        /** The millisecond. */
    093        private int millisecond;
    094
    095        /**
    096         * The pegged millisecond.
    097         */
    098        private long firstMillisecond;
    099
    100        /**
    101         * Constructs a millisecond based on the current system time.
    102         */
    103        public Millisecond() {
    104            this(new Date());
    105        }
    106
    107        /**
    108         * Constructs a millisecond.
    109         *
    110         * @param millisecond  the millisecond (0-999).
    111         * @param second  the second.
    112         */
    113        public Millisecond(int millisecond, Second second) {
    114            this.millisecond = millisecond;
    115            this.second = (byte) second.getSecond();
    116            this.minute = (byte) second.getMinute().getMinute();
    117            this.hour = (byte) second.getMinute().getHourValue();
    118            this.day = second.getMinute().getDay();
    119            peg(Calendar.getInstance());
    120        }
    121
    122        /**
    123         * Creates a new millisecond.
    124         *
    125         * @param millisecond  the millisecond (0-999).
    126         * @param second  the second (0-59).
    127         * @param minute  the minute (0-59).
    128         * @param hour  the hour (0-23).
    129         * @param day  the day (1-31).
    130         * @param month  the month (1-12).
    131         * @param year  the year (1900-9999).
    132         */
    133        public Millisecond(int millisecond, int second, int minute, int hour,
    134                           int day, int month, int year) {
    135
    136            this(millisecond, new Second(second, minute, hour, day, month, year));
    137
    138        }
    139
    140        /**
    141         * Constructs a millisecond.
    142         *
    143         * @param time  the time.
    144         */
    145        public Millisecond(Date time) {
    146            this(time, RegularTimePeriod.DEFAULT_TIME_ZONE);
    147        }
    148
    149        /**
    150         * Creates a millisecond.
    151         *
    152         * @param time  the instant in time.
    153         * @param zone  the time zone.
    154         */
    155        public Millisecond(Date time, TimeZone zone) {
    156            Calendar calendar = Calendar.getInstance(zone);
    157            calendar.setTime(time);
    158            this.millisecond = calendar.get(Calendar.MILLISECOND);
    159            this.second = (byte) calendar.get(Calendar.SECOND);
    160            this.minute = (byte) calendar.get(Calendar.MINUTE);
    161            this.hour = (byte) calendar.get(Calendar.HOUR_OF_DAY);
    162            this.day = new Day(time, zone);
    163            peg(calendar);
    164        }
    165
    166        /**
    167         * Returns the second.
    168         *
    169         * @return The second.
    170         */
    171        public Second getSecond() {
    172            return new Second(this.second, this.minute, this.hour,
    173                    this.day.getDayOfMonth(), this.day.getMonth(),
    174                    this.day.getYear());
    175        }
    176
    177        /**
    178         * Returns the millisecond.
    179         *
    180         * @return The millisecond.
    181         */
    182        public long getMillisecond() {
    183            return this.millisecond;
    184        }
    185
    186        /**
    187         * Returns the first millisecond of the second.  This will be determined
    188         * relative to the time zone specified in the constructor, or in the
    189         * calendar instance passed in the most recent call to the
    190         * {@link #peg(Calendar)} method.
    191         *
    192         * @return The first millisecond of the second.
    193         *
    194         * @see #getLastMillisecond()
    195         */
    196        public long getFirstMillisecond() {
    197            return this.firstMillisecond;
    198        }
    199
    200        /**
    201         * Returns the last millisecond of the second.  This will be
    202         * determined relative to the time zone specified in the constructor, or
    203         * in the calendar instance passed in the most recent call to the
    204         * {@link #peg(Calendar)} method.
    205         *
    206         * @return The last millisecond of the second.
    207         *
    208         * @see #getFirstMillisecond()
    209         */
    210        public long getLastMillisecond() {
    211            return this.firstMillisecond;
    212        }
    213
    214        /**
    215         * Recalculates the start date/time and end date/time for this time period
    216         * relative to the supplied calendar (which incorporates a time zone).
    217         *
    218         * @param calendar  the calendar (<code>null</code> not permitted).
    219         *
    220         * @since 1.0.3
    221         */
    222        public void peg(Calendar calendar) {
    223            this.firstMillisecond = getFirstMillisecond(calendar);
    224        }
    225
    226        /**
    227         * Returns the millisecond preceding this one.
    228         *
    229         * @return The millisecond preceding this one.
    230         */
    231        public RegularTimePeriod previous() {
    232
    233            RegularTimePeriod result = null;
    234
    235            if (this.millisecond != FIRST_MILLISECOND_IN_SECOND) {
    236                result = new Millisecond(this.millisecond - 1, getSecond());
    237            }
    238            else {
    239                Second previous = (Second) getSecond().previous();
    240                if (previous != null) {
    241                    result = new Millisecond(LAST_MILLISECOND_IN_SECOND, previous);
    242                }
    243            }
    244            return result;
    245
    246        }
    247
    248        /**
    249         * Returns the millisecond following this one.
    250         *
    251         * @return The millisecond following this one.
    252         */
    253        public RegularTimePeriod next() {
    254
    255            RegularTimePeriod result = null;
    256            if (this.millisecond != LAST_MILLISECOND_IN_SECOND) {
    257                result = new Millisecond(this.millisecond + 1, getSecond());
    258            }
    259            else {
    260                Second next = (Second) getSecond().next();
    261                if (next != null) {
    262                    result = new Millisecond(FIRST_MILLISECOND_IN_SECOND, next);
    263                }
    264            }
    265            return result;
    266
    267        }
    268
    269        /**
    270         * Returns a serial index number for the millisecond.
    271         *
    272         * @return The serial index number.
    273         */
    274        public long getSerialIndex() {
    275            long hourIndex = this.day.getSerialIndex() * 24L + this.hour;
    276            long minuteIndex = hourIndex * 60L + this.minute;
    277            long secondIndex = minuteIndex * 60L + this.second;
    278            return secondIndex * 1000L + this.millisecond;
    279        }
    280
    281        /**
    282         * Tests the equality of this object against an arbitrary Object.
    283         * <P>
    284         * This method will return true ONLY if the object is a Millisecond object
    285         * representing the same millisecond as this instance.
    286         *
    287         * @param obj  the object to compare
    288         *
    289         * @return <code>true</code> if milliseconds and seconds of this and object
    290         *      are the same.
    291         */
    292        public boolean equals(Object obj) {
    293            if (obj == this) {
    294                return true;
    295            }
    296            if (!(obj instanceof Millisecond)) {
    297                return false;
    298            }
    299            Millisecond that = (Millisecond) obj;
    300            if (this.millisecond != that.millisecond) {
    301                return false;
    302            }
    303            if (this.second != that.second) {
    304                return false;
    305            }
    306            if (this.minute != that.minute) {
    307                return false;
    308            }
    309            if (this.hour != that.hour) {
    310                return false;
    311            }
    312            if (!this.day.equals(that.day)) {
    313                return false;
    314            }
    315            return true;
    316        }
    317
    318        /**
    319         * Returns a hash code for this object instance.  The approach described by
    320         * Joshua Bloch in "Effective Java" has been used here:
    321         * <p>
    322         * <code>http://developer.java.sun.com/developer/Books/effectivejava
    323         * /Chapter3.pdf</code>
    324         *
    325         * @return A hashcode.
    326         */
    327        public int hashCode() {
    328            int result = 17;
    329            result = 37 * result + this.millisecond;
    330            result = 37 * result + getSecond().hashCode();
    331            return result;
    332        }
    333
    334        /**
    335         * Returns an integer indicating the order of this Millisecond object
    336         * relative to the specified object:
    337         *
    338         * negative == before, zero == same, positive == after.
    339         *
    340         * @param obj  the object to compare
    341         *
    342         * @return negative == before, zero == same, positive == after.
    343         */
    344        public int compareTo(Object obj) {
    345
    346            int result;
    347            long difference;
    348
    349            // CASE 1 : Comparing to another Second object
    350            // -------------------------------------------
    351            if (obj instanceof Millisecond) {
    352                Millisecond ms = (Millisecond) obj;
    353                difference = getFirstMillisecond() - ms.getFirstMillisecond();
    354                if (difference > 0) {
    355                    result = 1;
    356                }
    357                else {
    358                    if (difference < 0) {
    359                        result = -1;
    360                    }
    361                    else {
    362                        result = 0;
    363                    }
    364                }
    365            }
    366
    367            // CASE 2 : Comparing to another TimePeriod object
    368            // -----------------------------------------------
    369            else if (obj instanceof RegularTimePeriod) {
    370                    RegularTimePeriod rtp = (RegularTimePeriod) obj;
    371                    final long thisVal = this.getFirstMillisecond();
    372                    final long anotherVal = rtp.getFirstMillisecond();
    373                    result = (thisVal < anotherVal ? -1
    374                                    : (thisVal == anotherVal ? 0 : 1));
    375            }
    376
    377            // CASE 3 : Comparing to a non-TimePeriod object
    378            // ---------------------------------------------
    379            else {
    380                // consider time periods to be ordered after general objects
    381                result = 1;
    382            }
    383
    384            return result;
    385
    386        }
    387
    388        /**
    389         * Returns the first millisecond of the time period.
    390         *
    391         * @param calendar  the calendar (<code>null</code> not permitted).
    392         *
    393         * @return The first millisecond of the time period.
    394         *
    395         * @throws NullPointerException if <code>calendar</code> is
    396         *     <code>null</code>.
    397         */
    398        public long getFirstMillisecond(Calendar calendar) {
    399            int year = this.day.getYear();
    400            int month = this.day.getMonth() - 1;
    401            int day = this.day.getDayOfMonth();
    402            calendar.clear();
    403            calendar.set(year, month, day, this.hour, this.minute, this.second);
    404            calendar.set(Calendar.MILLISECOND, this.millisecond);
    405            //return calendar.getTimeInMillis();  // this won't work for JDK 1.3
    406            return calendar.getTime().getTime();
    407        }
    408
    409        /**
    410         * Returns the last millisecond of the time period.
    411         *
    412         * @param calendar  the calendar (<code>null</code> not permitted).
    413         *
    414         * @return The last millisecond of the time period.
    415         *
    416         * @throws NullPointerException if <code>calendar</code> is
    417         *     <code>null</code>.
    418         */
    419        public long getLastMillisecond(Calendar calendar) {
    420            return getFirstMillisecond(calendar);
    421        }
    422
    423    }