Minute


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