KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jfree > data > time > Year


1 /* ===========================================================
2  * JFreeChart : a free chart library for the Java(tm) platform
3  * ===========================================================
4  *
5  * (C) Copyright 2000-2005, by Object Refinery Limited and Contributors.
6  *
7  * Project Info: http://www.jfree.org/jfreechart/index.html
8  *
9  * This library is free software; you can redistribute it and/or modify it
10  * under the terms of the GNU Lesser General Public License as published by
11  * the Free Software Foundation; either version 2.1 of the License, or
12  * (at your option) any later version.
13  *
14  * This library is distributed in the hope that it will be useful, but
15  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
16  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
17  * License for more details.
18  *
19  * You should have received a copy of the GNU Lesser General Public License
20  * along with this library; if not, write to the Free Software Foundation,
21  * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
22  *
23  * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
24  * in the United States and other countries.]
25  *
26  * ---------
27  * Year.java
28  * ---------
29  * (C) Copyright 2001-2005, by Object Refinery Limited.
30  *
31  * Original Author: David Gilbert (for Object Refinery Limited);
32  * Contributor(s): -;
33  *
34  * $Id: Year.java,v 1.9 2005/05/19 10:35:27 mungady Exp $
35  *
36  * Changes
37  * -------
38  * 11-Oct-2001 : Version 1 (DG);
39  * 14-Nov-2001 : Override for toString() method (DG);
40  * 19-Dec-2001 : Added a new constructor as suggested by Paul English (DG);
41  * 29-Jan-2002 : Worked on parseYear() method (DG);
42  * 14-Feb-2002 : Fixed bug in Year(Date) constructor (DG);
43  * 26-Feb-2002 : Changed getStart(), getMiddle() and getEnd() methods to
44  * evaluate with reference to a particular time zone (DG);
45  * 19-Mar-2002 : Changed API for TimePeriod classes (DG);
46  * 10-Sep-2002 : Added getSerialIndex() method (DG);
47  * 04-Oct-2002 : Fixed errors reported by Checkstyle (DG);
48  * 10-Jan-2003 : Changed base class and method names (DG);
49  * 05-Mar-2003 : Fixed bug in getFirstMillisecond() picked up in JUnit
50  * tests (DG);
51  * 13-Mar-2003 : Moved to com.jrefinery.data.time package, and implemented
52  * Serializable (DG);
53  * 21-Oct-2003 : Added hashCode() method (DG);
54  *
55  */
56
57 package org.jfree.data.time;
58
59 import java.io.Serializable JavaDoc;
60 import java.util.Calendar JavaDoc;
61 import java.util.Date JavaDoc;
62 import java.util.TimeZone JavaDoc;
63
64 import org.jfree.date.MonthConstants;
65 import org.jfree.date.SerialDate;
66
67 /**
68  * Represents a year in the range 1900 to 9999. This class is immutable, which
69  * is a requirement for all {@link RegularTimePeriod} subclasses.
70  */
71 public class Year extends RegularTimePeriod implements Serializable JavaDoc {
72
73     /** For serialization. */
74     private static final long serialVersionUID = -7659990929736074836L;
75     
76     /** The year. */
77     private int year;
78
79     /**
80      * Creates a new <code>Year</code>, based on the current system date/time.
81      */
82     public Year() {
83         this(new Date JavaDoc());
84     }
85
86     /**
87      * Creates a time period representing a single year.
88      *
89      * @param year the year.
90      */
91     public Year(int year) {
92
93         // check arguments...
94 if ((year < SerialDate.MINIMUM_YEAR_SUPPORTED)
95             || (year > SerialDate.MAXIMUM_YEAR_SUPPORTED)) {
96
97             throw new IllegalArgumentException JavaDoc(
98                 "Year constructor: year (" + year + ") outside valid range.");
99         }
100
101         // initialise...
102 this.year = year;
103
104     }
105
106     /**
107      * Creates a new <code>Year</code>, based on a particular instant in time,
108      * using the default time zone.
109      *
110      * @param time the time.
111      */
112     public Year(Date JavaDoc time) {
113         this(time, RegularTimePeriod.DEFAULT_TIME_ZONE);
114     }
115
116     /**
117      * Constructs a year, based on a particular instant in time and a time zone.
118      *
119      * @param time the time.
120      * @param zone the time zone.
121      */
122     public Year(Date JavaDoc time, TimeZone JavaDoc zone) {
123
124         Calendar JavaDoc calendar = Calendar.getInstance(zone);
125         calendar.setTime(time);
126         this.year = calendar.get(Calendar.YEAR);
127
128     }
129
130     /**
131      * Returns the year.
132      *
133      * @return The year.
134      */
135     public int getYear() {
136         return this.year;
137     }
138
139     /**
140      * Returns the year preceding this one.
141      *
142      * @return The year preceding this one (or <code>null</code> if the
143      * current year is 1900).
144      */
145     public RegularTimePeriod previous() {
146         if (this.year > SerialDate.MINIMUM_YEAR_SUPPORTED) {
147             return new Year(this.year - 1);
148         }
149         else {
150             return null;
151         }
152     }
153
154     /**
155      * Returns the year following this one.
156      *
157      * @return The year following this one (or <code>null</code> if the current
158      * year is 9999).
159      */
160     public RegularTimePeriod next() {
161         if (this.year < SerialDate.MAXIMUM_YEAR_SUPPORTED) {
162             return new Year(this.year + 1);
163         }
164         else {
165             return null;
166         }
167     }
168
169     /**
170      * Returns a serial index number for the year.
171      * <P>
172      * The implementation simply returns the year number (e.g. 2002).
173      *
174      * @return The serial index number.
175      */
176     public long getSerialIndex() {
177         return this.year;
178     }
179
180     /**
181      * Returns the first millisecond of the year, evaluated using the supplied
182      * calendar (which determines the time zone).
183      *
184      * @param calendar the calendar.
185      *
186      * @return The first millisecond of the year.
187      */
188     public long getFirstMillisecond(Calendar JavaDoc calendar) {
189         Day jan1 = new Day(1, MonthConstants.JANUARY, this.year);
190         return jan1.getFirstMillisecond(calendar);
191     }
192
193     /**
194      * Returns the last millisecond of the year, evaluated using the supplied
195      * calendar (which determines the time zone).
196      *
197      * @param calendar the calendar.
198      *
199      * @return The last millisecond of the year.
200      */
201     public long getLastMillisecond(Calendar JavaDoc calendar) {
202         Day dec31 = new Day(31, MonthConstants.DECEMBER, this.year);
203         return dec31.getLastMillisecond(calendar);
204     }
205
206     /**
207      * Tests the equality of this <code>Year</code> object to an arbitrary
208      * object. Returns <code>true</code> if the target is a <code>Year</code>
209      * instance representing the same year as this object. In all other cases,
210      * returns <code>false</code>.
211      *
212      * @param object the object.
213      *
214      * @return <code>true</code> if the year of this and the object are the
215      * same.
216      */
217     public boolean equals(Object JavaDoc object) {
218         if (object != null) {
219             if (object instanceof Year) {
220                 Year target = (Year) object;
221                 return (this.year == target.getYear());
222             }
223             else {
224                 return false;
225             }
226         }
227         else {
228             return false;
229         }
230     }
231     
232     /**
233      * Returns a hash code for this object instance. The approach described by
234      * Joshua Bloch in "Effective Java" has been used here:
235      * <p>
236      * <code>http://developer.java.sun.com/developer/Books/effectivejava
237      * /Chapter3.pdf</code>
238      *
239      * @return A hash code.
240      */
241     public int hashCode() {
242         int result = 17;
243         int c = this.year;
244         result = 37 * result + c;
245         return result;
246     }
247
248     /**
249      * Returns an integer indicating the order of this <code>Year</code> object
250      * relative to the specified object:
251      *
252      * negative == before, zero == same, positive == after.
253      *
254      * @param o1 the object to compare.
255      *
256      * @return negative == before, zero == same, positive == after.
257      */
258     public int compareTo(Object JavaDoc o1) {
259
260         int result;
261
262         // CASE 1 : Comparing to another Year object
263 // -----------------------------------------
264 if (o1 instanceof Year) {
265             Year y = (Year) o1;
266             result = this.year - y.getYear();
267         }
268
269         // CASE 2 : Comparing to another TimePeriod object
270 // -----------------------------------------------
271 else if (o1 instanceof RegularTimePeriod) {
272             // more difficult case - evaluate later...
273 result = 0;
274         }
275
276         // CASE 3 : Comparing to a non-TimePeriod object
277 // ---------------------------------------------
278 else {
279             // consider time periods to be ordered after general objects
280 result = 1;
281         }
282
283         return result;
284
285     }
286
287     /**
288      * Returns a string representing the year..
289      *
290      * @return A string representing the year.
291      */
292     public String JavaDoc toString() {
293         return Integer.toString(this.year);
294     }
295
296     /**
297      * Parses the string argument as a year.
298      * <P>
299      * The string format is YYYY.
300      *
301      * @param s a string representing the year.
302      *
303      * @return <code>null</code> if the string is not parseable, the year
304      * otherwise.
305      */
306     public static Year parseYear(String JavaDoc s) {
307
308         // parse the string...
309 int y;
310         try {
311             y = Integer.parseInt(s.trim());
312         }
313         catch (NumberFormatException JavaDoc e) {
314             throw new TimePeriodFormatException("Cannot parse string.");
315         }
316
317         // create the year...
318 try {
319             return new Year(y);
320         }
321         catch (IllegalArgumentException JavaDoc e) {
322             throw new TimePeriodFormatException("Year outside valid range.");
323         }
324     }
325
326 }
327
Popular Tags