Hour


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   * Hour.java
28   * ---------
29   * (C) Copyright 2001-2004, by Object Refinery Limited.
30   *
31   * Original Author:  David Gilbert (for Object Refinery Limited);
32   * Contributor(s):   -;
33   *
34   * $Id: Hour.java,v 1.5 2005/05/19 10:35:27 mungady Exp $
35   *
36   * Changes
37   * -------
38   * 11-Oct-2001 : Version 1 (DG);
39   * 18-Dec-2001 : Changed order of parameters in constructor (DG);
40   * 19-Dec-2001 : Added a new constructor as suggested by Paul English (DG);
41   * 14-Feb-2002 : Fixed bug in Hour(Date) constructor (DG);
42   * 26-Feb-2002 : Changed getStart(), getMiddle() and getEnd() methods to 
43   *               evaluate with reference to a particular time zone (DG);
44   * 15-Mar-2002 : Changed API (DG);
45   * 16-Apr-2002 : Fixed small time zone bug in constructor (DG);
46   * 10-Sep-2002 : Added getSerialIndex() method (DG);
47   * 07-Oct-2002 : Fixed errors reported by Checkstyle (DG);
48   * 10-Jan-2003 : Changed base class and method names (DG);
49   * 13-Mar-2003 : Moved to com.jrefinery.data.time package, and implemented 
50   *               Serializable (DG);
51   * 21-Oct-2003 : Added hashCode() method, and new constructor for 
52   *               convenience (DG);
53   * 30-Sep-2004 : Replaced getTime().getTime() with getTimeInMillis() (DG);
54   * 04-Nov-2004 : Reverted change of 30-Sep-2004, because it won't work for 
55   *               JDK 1.3 (DG);
56   *
57   */
58  
59  package org.jfree.data.time;
60  
61  import java.io.Serializable  ;
62  import java.util.Calendar  ;
63  import java.util.Date  ;
64  import java.util.TimeZone  ;
65  
66  /**
67   * Represents an hour in a specific day.  This class is immutable, which is a 
68   * requirement for all {@link RegularTimePeriod} subclasses.
69   */
70  public class Hour extends RegularTimePeriod implements Serializable   {
71  
72      /** For serialization. */
73      private static final long serialVersionUID = -835471579831937652L;
74      
75      /** Useful constant for the first hour in the day. */
76      public static final int FIRST_HOUR_IN_DAY = 0;
77  
78      /** Useful constant for the last hour in the day. */
79      public static final int LAST_HOUR_IN_DAY = 23;
80  
81      /** The day. */
82      private Day day;
83  
84      /** The hour. */
85      private int hour;
86  
87      /**
88       * Constructs a new Hour, based on the system date/time.
89       */
90      public Hour() {
91          this(new Date  ());
92      }
93  
94      /**
95       * Constructs a new Hour.
96       *
97       * @param hour  the hour (in the range 0 to 23).
98       * @param day  the day (<code>null</code> not permitted).
99       */
100     public Hour(int hour, Day day) {
101         if (day == null) {
102             throw new IllegalArgumentException  ("Null 'day' argument.");
103         }
104         this.hour = hour;
105         this.day = day;
106     }
107 
108     /**
109      * Creates a new hour.
110      * 
111      * @param hour  the hour (0-23).
112      * @param day  the day (1-31).
113      * @param month  the month (1-12).
114      * @param year  the year (1900-9999).
115      */
116     public Hour(int hour, int day, int month, int year) {
117         this(hour, new Day(day, month, year));
118     }
119     
120     /**
121      * Constructs a new Hour, based on the supplied date/time.
122      *
123      * @param time  the date-time (<code>null</code> not permitted).
124      */
125     public Hour(Date   time) {
126         // defer argument checking...
127         this(time, RegularTimePeriod.DEFAULT_TIME_ZONE);
128     }
129 
130     /**
131      * Constructs a new Hour, based on the supplied date/time evaluated in the
132      * specified time zone.
133      *
134      * @param time  the date-time (<code>null</code> not permitted).
135      * @param zone  the time zone (<code>null</code> not permitted).
136      */
137     public Hour(Date   time, TimeZone   zone) {
138         if (time == null) {
139             throw new IllegalArgumentException  ("Null 'time' argument.");
140         }
141         if (zone == null) {
142             throw new IllegalArgumentException  ("Null 'zone' argument.");
143         }
144         Calendar   calendar = Calendar.getInstance(zone);
145         calendar.setTime(time);
146         this.hour = calendar.get(Calendar.HOUR_OF_DAY);
147         this.day = new Day(time, zone);
148     }
149 
150     /**
151      * Returns the hour.
152      *
153      * @return The hour (0 <= hour <= 23).
154      */
155     public int getHour() {
156         return this.hour;
157     }
158 
159     /**
160      * Returns the day in which this hour falls.
161      *
162      * @return The day.
163      */
164     public Day getDay() {
165         return this.day;
166     }
167 
168     /**
169      * Returns the year in which this hour falls.
170      *
171      * @return The year.
172      */
173     public int getYear() {
174         return this.day.getYear();
175     }
176 
177     /**
178      * Returns the month in which this hour falls.
179      *
180      * @return The month.
181      */
182     public int getMonth() {
183         return this.day.getMonth();
184     }
185 
186     /**
187      * Returns the day-of-the-month in which this hour falls.
188      *
189      * @return The day-of-the-month.
190      */
191     public int getDayOfMonth() {
192         return this.day.getDayOfMonth();
193     }
194 
195     /**
196      * Returns the hour preceding this one.
197      *
198      * @return The hour preceding this one.
199      */
200     public RegularTimePeriod previous() {
201 
202         Hour result;
203         if (this.hour != FIRST_HOUR_IN_DAY) {
204             result = new Hour(this.hour - 1, this.day);
205         }
206         else { // we are at the first hour in the day...
207             Day prevDay = (Day) this.day.previous();
208             if (prevDay != null) {
209                 result = new Hour(LAST_HOUR_IN_DAY, prevDay);
210             }
211             else {
212                 result = null;
213             }
214         }
215         return result;
216 
217     }
218 
219     /**
220      * Returns the hour following this one.
221      *
222      * @return The hour following this one.
223      */
224     public RegularTimePeriod next() {
225 
226         Hour result;
227         if (this.hour != LAST_HOUR_IN_DAY) {
228             result = new Hour(this.hour + 1, this.day);
229         }
230         else { // we are at the last hour in the day...
231             Day nextDay = (Day) this.day.next();
232             if (nextDay != null) {
233                 result = new Hour(FIRST_HOUR_IN_DAY, nextDay);
234             }
235             else {
236                 result = null;
237             }
238         }
239         return result;
240 
241     }
242 
243     /**
244      * Returns a serial index number for the hour.
245      *
246      * @return The serial index number.
247      */
248     public long getSerialIndex() {
249         return this.day.getSerialIndex() * 24L + this.hour;
250     }
251 
252     /**
253      * Returns the first millisecond of the hour.
254      *
255      * @param calendar  the calendar/timezone.
256      *
257      * @return The first millisecond.
258      */
259     public long getFirstMillisecond(Calendar   calendar) {
260 
261         int year = this.day.getYear();
262         int month = this.day.getMonth() - 1;
263         int dom = this.day.getDayOfMonth();
264 
265         calendar.set(year, month, dom, this.hour, 0, 0);
266         calendar.set(Calendar.MILLISECOND, 0);
267 
268         //return calendar.getTimeInMillis();  // this won't work for JDK 1.3
269         return calendar.getTime().getTime();
270 
271     }
272 
273     /**
274      * Returns the last millisecond of the hour.
275      *
276      * @param calendar  the calendar/timezone.
277      *
278      * @return The last millisecond.
279      */
280     public long getLastMillisecond(Calendar   calendar) {
281 
282         int year = this.day.getYear();
283         int month = this.day.getMonth() - 1;
284         int dom = this.day.getDayOfMonth();
285 
286         calendar.set(year, month, dom, this.hour, 59, 59);
287         calendar.set(Calendar.MILLISECOND, 999);
288 
289         //return calendar.getTimeInMillis();  // this won't work for JDK 1.3
290         return calendar.getTime().getTime();
291 
292     }
293 
294     /**
295      * Tests the equality of this object against an arbitrary Object.
296      * <P>
297      * This method will return true ONLY if the object is an Hour object
298      * representing the same hour as this instance.
299      *
300      * @param obj  the object to compare (<code>null</code> permitted).
301      *
302      * @return <code>true</code> if the hour and day value of the object
303      *      is the same as this.
304      */
305     public boolean equals(Object   obj) {
306         if (obj == this) {
307             return true;
308         }
309         if (!(obj instanceof Hour)) {
310             return false;
311         }
312         Hour that = (Hour) obj;
313         if (this.hour != that.hour) {
314             return false;
315         }
316         if (!this.day.equals(that.day)) {
317             return false;
318         }
319         return true;
320     }
321 
322     /**
323      * Returns a hash code for this object instance.  The approach described by 
324      * Joshua Bloch in "Effective Java" has been used here:
325      * <p>
326      * <code>http://developer.java.sun.com/developer/Books/effectivejava
327      * /Chapter3.pdf</code>
328      * 
329      * @return A hash code.
330      */
331     public int hashCode() {
332         int result = 17;
333         result = 37 * result + this.hour;
334         result = 37 * result + this.day.hashCode();
335         return result;
336     }
337 
338     /**
339      * Returns an integer indicating the order of this Hour object relative to
340      * the specified object:
341      *
342      * negative == before, zero == same, positive == after.
343      *
344      * @param o1  the object to compare.
345      *
346      * @return negative == before, zero == same, positive == after.
347      */
348     public int compareTo(Object   o1) {
349 
350         int result;
351 
352         // CASE 1 : Comparing to another Hour object
353         // -----------------------------------------
354         if (o1 instanceof Hour) {
355             Hour h = (Hour) o1;
356             result = getDay().compareTo(h.getDay());
357             if (result == 0) {
358                 result = this.hour - h.getHour();
359             }
360         }
361 
362         // CASE 2 : Comparing to another TimePeriod object
363         // -----------------------------------------------
364         else if (o1 instanceof RegularTimePeriod) {
365             // more difficult case - evaluate later...
366             result = 0;
367         }
368 
369         // CASE 3 : Comparing to a non-TimePeriod object
370         // ---------------------------------------------
371         else {
372             // consider time periods to be ordered after general objects
373             result = 1;
374         }
375 
376         return result;
377 
378     }
379 
380     /**
381      * Creates an Hour instance by parsing a string.  The string is assumed to
382      * be in the format "YYYY-MM-DD HH", perhaps with leading or trailing
383      * whitespace.
384      *
385      * @param s  the hour string to parse.
386      *
387      * @return <code>null</code> if the string is not parseable, the hour 
388      *         otherwise.
389      */
390     public static Hour parseHour(String   s) {
391 
392         Hour result = null;
393         s = s.trim();
394 
395         String   daystr = s.substring(0, Math.min(10, s.length()));
396         Day day = Day.parseDay(daystr);
397         if (day != null) {
398             String   hourstr = s.substring(
399                 Math.min(daystr.length() + 1, s.length()), s.length()
400             );
401             hourstr = hourstr.trim();
402             int hour = Integer.parseInt(hourstr);
403             // if the hour is 0 - 23 then create an hour
404             if ((hour >= FIRST_HOUR_IN_DAY) && (hour <= LAST_HOUR_IN_DAY)) {
405                 result = new Hour(hour, day);
406             }
407         }
408 
409         return result;
410 
411     }
412 
413 }
414
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags