KickJava   Java API By Example, From Geeks To Geeks.

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


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  * RegularTimePeriod.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: RegularTimePeriod.java,v 1.6 2005/03/15 21:50:37 mungady Exp $
35  *
36  * Changes
37  * -------
38  * 11-Oct-2001 : Version 1 (DG);
39  * 26-Feb-2002 : Changed getStart(), getMiddle() and getEnd() methods to
40  * evaluate with reference to a particular time zone (DG);
41  * 29-May-2002 : Implemented MonthConstants interface, so that these constants
42  * are conveniently available (DG);
43  * 10-Sep-2002 : Added getSerialIndex() method (DG);
44  * 10-Jan-2003 : Renamed TimePeriod --> RegularTimePeriod (DG);
45  * 13-Mar-2003 : Moved to com.jrefinery.data.time package (DG);
46  * 29-Apr-2004 : Changed getMiddleMillisecond() methods to fix bug 943985 (DG);
47  * 25-Nov-2004 : Added utility methods (DG);
48  *
49  */
50
51 package org.jfree.data.time;
52
53 import java.lang.reflect.Constructor JavaDoc;
54 import java.util.Calendar JavaDoc;
55 import java.util.Date JavaDoc;
56 import java.util.TimeZone JavaDoc;
57
58 import org.jfree.date.MonthConstants;
59
60 /**
61  * An abstract class representing a unit of time. Convenient methods are
62  * provided for calculating the next and previous time periods. Conversion
63  * methods are defined that return the first and last milliseconds of the time
64  * period. The results from these methods are timezone dependent.
65  * <P>
66  * This class is immutable, and all subclasses should be immutable also.
67  */
68 public abstract class RegularTimePeriod implements TimePeriod, Comparable JavaDoc,
69                                                    MonthConstants {
70
71     /**
72      * Creates a time period that includes the specified millisecond, assuming
73      * the given time zone.
74      *
75      * @param c the time period class.
76      * @param millisecond the time.
77      * @param zone the time zone.
78      *
79      * @return The time period.
80      */
81     public static RegularTimePeriod createInstance(Class JavaDoc c, Date JavaDoc millisecond,
82                                                    TimeZone JavaDoc zone) {
83         RegularTimePeriod result = null;
84         try {
85             Constructor JavaDoc constructor = c.getDeclaredConstructor(
86                 new Class JavaDoc[] {Date JavaDoc.class, TimeZone JavaDoc.class}
87             );
88             result = (RegularTimePeriod) constructor.newInstance(
89                 new Object JavaDoc[] {millisecond, zone}
90             );
91         }
92         catch (Exception JavaDoc e) {
93             // do nothing, so null is returned
94 }
95         return result;
96     }
97     
98     /**
99      * Returns a subclass of {@link RegularTimePeriod} that is smaller than
100      * the specified class.
101      *
102      * @param c a subclass of {@link RegularTimePeriod}.
103      *
104      * @return A class.
105      */
106     public static Class JavaDoc downsize(Class JavaDoc c) {
107         if (c.equals(Year.class)) {
108             return Quarter.class;
109         }
110         else if (c.equals(Quarter.class)) {
111             return Month.class;
112         }
113         else if (c.equals(Month.class)) {
114             return Day.class;
115         }
116         else if (c.equals(Day.class)) {
117             return Hour.class;
118         }
119         else if (c.equals(Hour.class)) {
120             return Minute.class;
121         }
122         else if (c.equals(Minute.class)) {
123             return Second.class;
124         }
125         else if (c.equals(Second.class)) {
126             return Millisecond.class;
127         }
128         else {
129             return Millisecond.class;
130         }
131     }
132     
133     /**
134      * Returns the time period preceding this one, or <code>null</code> if some
135      * lower limit has been reached.
136      *
137      * @return The previous time period (possibly <code>null</code>).
138      */
139     public abstract RegularTimePeriod previous();
140
141     /**
142      * Returns the time period following this one, or <code>null</code> if some
143      * limit has been reached.
144      *
145      * @return The next time period (possibly <code>null</code>).
146      */
147     public abstract RegularTimePeriod next();
148
149     /**
150      * Returns a serial index number for the time unit.
151      *
152      * @return The serial index number.
153      */
154     public abstract long getSerialIndex();
155
156     //////////////////////////////////////////////////////////////////////////
157
158     /** The default time zone. */
159     public static final TimeZone JavaDoc DEFAULT_TIME_ZONE = TimeZone.getDefault();
160
161     /** A working calendar (recycle to avoid unnecessary object creation). */
162     public static final Calendar JavaDoc WORKING_CALENDAR
163         = Calendar.getInstance(DEFAULT_TIME_ZONE);
164
165     /**
166      * Returns the date/time that marks the start of the time period.
167      *
168      * @return The start date/time.
169      */
170     public Date JavaDoc getStart() {
171         return new Date JavaDoc(getFirstMillisecond());
172     }
173
174     /**
175      * Returns the date/time that marks the end of the time period.
176      *
177      * @return The end date/time.
178      */
179     public Date JavaDoc getEnd() {
180         return new Date JavaDoc(getLastMillisecond());
181     }
182
183     /**
184      * Returns the first millisecond of the time period, evaluated in the
185      * default time zone.
186      *
187      * @return The first millisecond of the time period.
188      */
189     public long getFirstMillisecond() {
190         return getFirstMillisecond(DEFAULT_TIME_ZONE);
191     }
192
193     /**
194      * Returns the first millisecond of the time period, evaluated within a
195      * specific time zone.
196      *
197      * @param zone the time zone.
198      *
199      * @return The first millisecond of the time period.
200      */
201     public long getFirstMillisecond(TimeZone JavaDoc zone) {
202         WORKING_CALENDAR.setTimeZone(zone);
203         return getFirstMillisecond(WORKING_CALENDAR);
204     }
205
206     /**
207      * Returns the first millisecond of the time period, evaluated using the
208      * supplied calendar (which incorporates a timezone).
209      *
210      * @param calendar the calendar.
211      *
212      * @return The first millisecond of the time period.
213      */
214     public abstract long getFirstMillisecond(Calendar JavaDoc calendar);
215
216     /**
217      * Returns the last millisecond of the time period, evaluated in the
218      * default time zone.
219      *
220      * @return The last millisecond of the time period.
221      */
222     public long getLastMillisecond() {
223         return getLastMillisecond(DEFAULT_TIME_ZONE);
224     }
225
226     /**
227      * Returns the last millisecond of the time period, evaluated within a
228      * specific time zone.
229      *
230      * @param zone the time zone.
231      *
232      * @return The last millisecond of the time period.
233      */
234     public long getLastMillisecond(TimeZone JavaDoc zone) {
235         WORKING_CALENDAR.setTimeZone(zone);
236         return getLastMillisecond(WORKING_CALENDAR);
237     }
238
239     /**
240      * Returns the last millisecond of the time period, evaluated using the
241      * supplied calendar (which incorporates a timezone).
242      *
243      * @param calendar the calendar.
244      *
245      * @return The last millisecond of the time period.
246      */
247     public abstract long getLastMillisecond(Calendar JavaDoc calendar);
248
249     /**
250      * Returns the millisecond closest to the middle of the time period,
251      * evaluated in the default time zone.
252      *
253      * @return The middle millisecond.
254      */
255     public long getMiddleMillisecond() {
256         long m1 = getFirstMillisecond();
257         long m2 = getLastMillisecond();
258         return m1 + (m2 - m1) / 2;
259     }
260
261     /**
262      * Returns the millisecond closest to the middle of the time period,
263      * evaluated within a specific time zone.
264      *
265      * @param zone the time zone.
266      *
267      * @return The middle millisecond.
268      */
269     public long getMiddleMillisecond(TimeZone JavaDoc zone) {
270         long m1 = getFirstMillisecond(zone);
271         long m2 = getLastMillisecond(zone);
272         return m1 + (m2 - m1) / 2;
273     }
274
275     /**
276      * Returns the millisecond closest to the middle of the time period,
277      * evaluated using the supplied calendar (which incorporates a timezone).
278      *
279      * @param calendar the calendar.
280      *
281      * @return The middle millisecond.
282      */
283     public long getMiddleMillisecond(Calendar JavaDoc calendar) {
284         long m1 = getFirstMillisecond(calendar);
285         long m2 = getLastMillisecond(calendar);
286         return m1 + (m2 - m1) / 2;
287     }
288
289     /**
290      * Returns a string representation of the time period.
291      *
292      * @return The string.
293      */
294     public String JavaDoc toString() {
295         return String.valueOf(getStart());
296     }
297
298 }
299
Popular Tags