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     * Year.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     * 14-Nov-2001 : Override for toString() method (DG);
039     * 19-Dec-2001 : Added a new constructor as suggested by Paul English (DG);
040     * 29-Jan-2002 : Worked on parseYear() method (DG);
041     * 14-Feb-2002 : Fixed bug in Year(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     * 10-Sep-2002 : Added getSerialIndex() method (DG);
046     * 04-Oct-2002 : Fixed errors reported by Checkstyle (DG);
047     * 10-Jan-2003 : Changed base class and method names (DG);
048     * 05-Mar-2003 : Fixed bug in getFirstMillisecond() picked up in JUnit
049     *               tests (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     * ------------- 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 : Extended range of valid years, and deprecated 
057     *               DEFAULT_TIME_ZONE (DG);
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    /**
069     * Represents a year in the range -9999 to 9999.  This class is immutable,
070     * which is a requirement for all {@link RegularTimePeriod} subclasses.
071     */
072    public class Year extends RegularTimePeriod implements Serializable {
073    
074        /**
075         * The minimum year value.
076         *
077         * @since 1.0.11
078         */
079        public static final int MINIMUM_YEAR = -9999;
080    
081        /**
082         * The maximum year value.
083         *
084         * @since 1.0.11
085         */
086        public static final int MAXIMUM_YEAR = 9999;
087    
088        /** For serialization. */
089        private static final long serialVersionUID = -7659990929736074836L;
090    
091        /** The year. */
092        private short year;
093    
094        /** The first millisecond. */
095        private long firstMillisecond;
096    
097        /** The last millisecond. */
098        private long lastMillisecond;
099    
100        /**
101         * Creates a new <code>Year</code>, based on the current system date/time.
102         */
103        public Year() {
104            this(new Date());
105        }
106    
107        /**
108         * Creates a time period representing a single year.
109         *
110         * @param year  the year.
111         */
112        public Year(int year) {
113            if ((year < Year.MINIMUM_YEAR) || (year > Year.MAXIMUM_YEAR)) {
114                throw new IllegalArgumentException(
115                    "Year constructor: year (" + year + ") outside valid range.");
116            }
117            this.year = (short) year;
118            peg(Calendar.getInstance());
119        }
120    
121        /**
122         * Creates a new <code>Year</code>, based on a particular instant in time,
123         * using the default time zone.
124         *
125         * @param time  the time (<code>null</code> not permitted).
126         *
127         * @see #Year(Date, TimeZone)
128         */
129        public Year(Date time) {
130            this(time, TimeZone.getDefault());
131        }
132    
133        /**
134         * Constructs a year, based on a particular instant in time and a time zone.
135         *
136         * @param time  the time.
137         * @param zone  the time zone.
138         */
139        public Year(Date time, TimeZone zone) {
140            // FIXME:  needs a locale as well as a timezone
141            Calendar calendar = Calendar.getInstance(zone);
142            calendar.setTime(time);
143            this.year = (short) calendar.get(Calendar.YEAR);
144            peg(calendar);
145        }
146    
147        /**
148         * Returns the year.
149         *
150         * @return The year.
151         */
152        public int getYear() {
153            return this.year;
154        }
155    
156        /**
157         * Returns the first millisecond of the year.  This will be determined
158         * relative to the time zone specified in the constructor, or in the
159         * calendar instance passed in the most recent call to the
160         * {@link #peg(Calendar)} method.
161         *
162         * @return The first millisecond of the year.
163         *
164         * @see #getLastMillisecond()
165         */
166        public long getFirstMillisecond() {
167            return this.firstMillisecond;
168        }
169    
170        /**
171         * Returns the last millisecond of the year.  This will be
172         * determined relative to the time zone specified in the constructor, or
173         * in the calendar instance passed in the most recent call to the
174         * {@link #peg(Calendar)} method.
175         *
176         * @return The last millisecond of the year.
177         *
178         * @see #getFirstMillisecond()
179         */
180        public long getLastMillisecond() {
181            return this.lastMillisecond;
182        }
183    
184        /**
185         * Recalculates the start date/time and end date/time for this time period
186         * relative to the supplied calendar (which incorporates a time zone).
187         *
188         * @param calendar  the calendar (<code>null</code> not permitted).
189         *
190         * @since 1.0.3
191         */
192        public void peg(Calendar calendar) {
193            this.firstMillisecond = getFirstMillisecond(calendar);
194            this.lastMillisecond = getLastMillisecond(calendar);
195        }
196    
197        /**
198         * Returns the year preceding this one.
199         *
200         * @return The year preceding this one (or <code>null</code> if the
201         *         current year is -9999).
202         */
203        public RegularTimePeriod previous() {
204            if (this.year > Year.MINIMUM_YEAR) {
205                return new Year(this.year - 1);
206            }
207            else {
208                return null;
209            }
210        }
211    
212        /**
213         * Returns the year following this one.
214         *
215         * @return The year following this one (or <code>null</code> if the current
216         *         year is 9999).
217         */
218        public RegularTimePeriod next() {
219            if (this.year < Year.MAXIMUM_YEAR) {
220                return new Year(this.year + 1);
221            }
222            else {
223                return null;
224            }
225        }
226    
227        /**
228         * Returns a serial index number for the year.
229         * <P>
230         * The implementation simply returns the year number (e.g. 2002).
231         *
232         * @return The serial index number.
233         */
234        public long getSerialIndex() {
235            return this.year;
236        }
237    
238        /**
239         * Returns the first millisecond of the year, evaluated using the supplied
240         * calendar (which determines the time zone).
241         *
242         * @param calendar  the calendar (<code>null</code> not permitted).
243         *
244         * @return The first millisecond of the year.
245         *
246         * @throws NullPointerException if <code>calendar</code> is
247         *     <code>null</code>.
248         */
249        public long getFirstMillisecond(Calendar calendar) {
250            calendar.set(this.year, Calendar.JANUARY, 1, 0, 0, 0);
251            calendar.set(Calendar.MILLISECOND, 0);
252            // in the following line, we'd rather call calendar.getTimeInMillis()
253            // to avoid object creation, but that isn't supported in Java 1.3.1
254            return calendar.getTime().getTime();
255        }
256    
257        /**
258         * Returns the last millisecond of the year, evaluated using the supplied
259         * calendar (which determines the time zone).
260         *
261         * @param calendar  the calendar (<code>null</code> not permitted).
262         *
263         * @return The last millisecond of the year.
264         *
265         * @throws NullPointerException if <code>calendar</code> is
266         *     <code>null</code>.
267         */
268        public long getLastMillisecond(Calendar calendar) {
269            calendar.set(this.year, Calendar.DECEMBER, 31, 23, 59, 59);
270            calendar.set(Calendar.MILLISECOND, 999);
271            // in the following line, we'd rather call calendar.getTimeInMillis()
272            // to avoid object creation, but that isn't supported in Java 1.3.1
273            return calendar.getTime().getTime();
274        }
275    
276        /**
277         * Tests the equality of this <code>Year</code> object to an arbitrary
278         * object.  Returns <code>true</code> if the target is a <code>Year</code>
279         * instance representing the same year as this object.  In all other cases,
280         * returns <code>false</code>.
281         *
282         * @param obj  the object (<code>null</code> permitted).
283         *
284         * @return <code>true</code> if the year of this and the object are the
285         *         same.
286         */
287        public boolean equals(Object obj) {
288            if (obj == this) {
289                return true;
290            }
291            if (!(obj instanceof Year)) {
292                return false;
293            }
294            Year that = (Year) obj;
295            return (this.year == that.year);
296        }
297    
298        /**
299         * Returns a hash code for this object instance.  The approach described by
300         * Joshua Bloch in "Effective Java" has been used here:
301         * <p>
302         * <code>http://developer.java.sun.com/developer/Books/effectivejava
303         *     /Chapter3.pdf</code>
304         *
305         * @return A hash code.
306         */
307        public int hashCode() {
308            int result = 17;
309            int c = this.year;
310            result = 37 * result + c;
311            return result;
312        }
313    
314        /**
315         * Returns an integer indicating the order of this <code>Year</code> object
316         * relative to the specified object:
317         *
318         * negative == before, zero == same, positive == after.
319         *
320         * @param o1  the object to compare.
321         *
322         * @return negative == before, zero == same, positive == after.
323         */
324        public int compareTo(Object o1) {
325    
326            int result;
327    
328            // CASE 1 : Comparing to another Year object
329            // -----------------------------------------
330            if (o1 instanceof Year) {
331                Year y = (Year) o1;
332                result = this.year - y.getYear();
333            }
334    
335            // CASE 2 : Comparing to another TimePeriod object
336            // -----------------------------------------------
337            else if (o1 instanceof RegularTimePeriod) {
338                // more difficult case - evaluate later...
339                result = 0;
340            }
341    
342            // CASE 3 : Comparing to a non-TimePeriod object
343            // ---------------------------------------------
344            else {
345                // consider time periods to be ordered after general objects
346                result = 1;
347            }
348    
349            return result;
350    
351        }
352    
353        /**
354         * Returns a string representing the year..
355         *
356         * @return A string representing the year.
357         */
358        public String toString() {
359            return Integer.toString(this.year);
360        }
361    
362        /**
363         * Parses the string argument as a year.
364         * <P>
365         * The string format is YYYY.
366         *
367         * @param s  a string representing the year.
368         *
369         * @return <code>null</code> if the string is not parseable, the year
370         *         otherwise.
371         */
372        public static Year parseYear(String s) {
373    
374            // parse the string...
375            int y;
376            try {
377                y = Integer.parseInt(s.trim());
378            }
379            catch (NumberFormatException e) {
380                throw new TimePeriodFormatException("Cannot parse string.");
381            }
382    
383            // create the year...
384            try {
385                return new Year(y);
386            }
387            catch (IllegalArgumentException e) {
388                throw new TimePeriodFormatException("Year outside valid range.");
389            }
390        }
391    
392    }