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 * Millisecond.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 * 19-Dec-2001 : Added new constructors as suggested by Paul English (DG);
039 * 26-Feb-2002 : Added new getStart() and getEnd() methods (DG);
040 * 29-Mar-2002 : Fixed bug in getStart(), getEnd() and compareTo() methods (DG);
041 * 10-Sep-2002 : Added getSerialIndex() method (DG);
042 * 07-Oct-2002 : Fixed errors reported by Checkstyle (DG);
043 * 10-Jan-2003 : Changed base class and method names (DG);
044 * 13-Mar-2003 : Moved to com.jrefinery.data.time package and implemented
045 * Serializable (DG);
046 * 21-Oct-2003 : Added hashCode() method (DG);
047 * ------------- JFREECHART 1.0.x ---------------------------------------------
048 * 05-Oct-2006 : Updated API docs (DG);
049 * 06-Oct-2006 : Refactored to cache first and last millisecond values (DG);
050 * 04-Apr-2007 : In Millisecond(Date, TimeZone), peg milliseconds to the
051 * specified zone (DG);
052 * 06-Jun-2008 : Added handling for general RegularTimePeriod in compareTo()
053 * method:
054 * see http://www.jfree.org/phpBB2/viewtopic.php?t=24805 (DG);
055 * 16-Sep-2008 : Deprecated DEFAULT_TIME_ZONE (DG);
056 *
057 */
058
059 package org.jfree.data.time;
060
061 import java.io.Serializable;
062 import java.util.Calendar;
063 import java.util.Date;
064 import java.util.TimeZone;
065
066 /**
067 * Represents a millisecond. This class is immutable, which is a requirement
068 * for all {@link RegularTimePeriod} subclasses.
069 */
070 public class Millisecond extends RegularTimePeriod implements Serializable {
071
072 /** For serialization. */
073 static final long serialVersionUID = -5316836467277638485L;
074
075 /** A constant for the first millisecond in a second. */
076 public static final int FIRST_MILLISECOND_IN_SECOND = 0;
077
078 /** A constant for the last millisecond in a second. */
079 public static final int LAST_MILLISECOND_IN_SECOND = 999;
080
081 /** The day. */
082 private Day day;
083
084 /** The hour in the day. */
085 private byte hour;
086
087 /** The minute. */
088 private byte minute;
089
090 /** The second. */
091 private byte second;
092
093 /** The millisecond. */
094 private int millisecond;
095
096 /**
097 * The pegged millisecond.
098 */
099 private long firstMillisecond;
100
101 /**
102 * Constructs a millisecond based on the current system time.
103 */
104 public Millisecond() {
105 this(new Date());
106 }
107
108 /**
109 * Constructs a millisecond.
110 *
111 * @param millisecond the millisecond (0-999).
112 * @param second the second.
113 */
114 public Millisecond(int millisecond, Second second) {
115 this.millisecond = millisecond;
116 this.second = (byte) second.getSecond();
117 this.minute = (byte) second.getMinute().getMinute();
118 this.hour = (byte) second.getMinute().getHourValue();
119 this.day = second.getMinute().getDay();
120 peg(Calendar.getInstance());
121 }
122
123 /**
124 * Creates a new millisecond.
125 *
126 * @param millisecond the millisecond (0-999).
127 * @param second the second (0-59).
128 * @param minute the minute (0-59).
129 * @param hour the hour (0-23).
130 * @param day the day (1-31).
131 * @param month the month (1-12).
132 * @param year the year (1900-9999).
133 */
134 public Millisecond(int millisecond, int second, int minute, int hour,
135 int day, int month, int year) {
136
137 this(millisecond, new Second(second, minute, hour, day, month, year));
138
139 }
140
141 /**
142 * Constructs a new millisecond using the default time zone.
143 *
144 * @param time the time.
145 *
146 * @see #Millisecond(Date, TimeZone)
147 */
148 public Millisecond(Date time) {
149 this(time, TimeZone.getDefault());
150 }
151
152 /**
153 * Creates a millisecond.
154 *
155 * @param time the instant in time.
156 * @param zone the time zone.
157 */
158 public Millisecond(Date time, TimeZone zone) {
159 // FIXME: need a locale as well as a timezone
160 Calendar calendar = Calendar.getInstance(zone);
161 calendar.setTime(time);
162 this.millisecond = calendar.get(Calendar.MILLISECOND);
163 this.second = (byte) calendar.get(Calendar.SECOND);
164 this.minute = (byte) calendar.get(Calendar.MINUTE);
165 this.hour = (byte) calendar.get(Calendar.HOUR_OF_DAY);
166 this.day = new Day(time, zone);
167 peg(calendar);
168 }
169
170 /**
171 * Returns the second.
172 *
173 * @return The second.
174 */
175 public Second getSecond() {
176 return new Second(this.second, this.minute, this.hour,
177 this.day.getDayOfMonth(), this.day.getMonth(),
178 this.day.getYear());
179 }
180
181 /**
182 * Returns the millisecond.
183 *
184 * @return The millisecond.
185 */
186 public long getMillisecond() {
187 return this.millisecond;
188 }
189
190 /**
191 * Returns the first millisecond of the second. This will be determined
192 * relative to the time zone specified in the constructor, or in the
193 * calendar instance passed in the most recent call to the
194 * {@link #peg(Calendar)} method.
195 *
196 * @return The first millisecond of the second.
197 *
198 * @see #getLastMillisecond()
199 */
200 public long getFirstMillisecond() {
201 return this.firstMillisecond;
202 }
203
204 /**
205 * Returns the last millisecond of the second. This will be
206 * determined relative to the time zone specified in the constructor, or
207 * in the calendar instance passed in the most recent call to the
208 * {@link #peg(Calendar)} method.
209 *
210 * @return The last millisecond of the second.
211 *
212 * @see #getFirstMillisecond()
213 */
214 public long getLastMillisecond() {
215 return this.firstMillisecond;
216 }
217
218 /**
219 * Recalculates the start date/time and end date/time for this time period
220 * relative to the supplied calendar (which incorporates a time zone).
221 *
222 * @param calendar the calendar (<code>null</code> not permitted).
223 *
224 * @since 1.0.3
225 */
226 public void peg(Calendar calendar) {
227 this.firstMillisecond = getFirstMillisecond(calendar);
228 }
229
230 /**
231 * Returns the millisecond preceding this one.
232 *
233 * @return The millisecond preceding this one.
234 */
235 public RegularTimePeriod previous() {
236
237 RegularTimePeriod result = null;
238
239 if (this.millisecond != FIRST_MILLISECOND_IN_SECOND) {
240 result = new Millisecond(this.millisecond - 1, getSecond());
241 }
242 else {
243 Second previous = (Second) getSecond().previous();
244 if (previous != null) {
245 result = new Millisecond(LAST_MILLISECOND_IN_SECOND, previous);
246 }
247 }
248 return result;
249
250 }
251
252 /**
253 * Returns the millisecond following this one.
254 *
255 * @return The millisecond following this one.
256 */
257 public RegularTimePeriod next() {
258
259 RegularTimePeriod result = null;
260 if (this.millisecond != LAST_MILLISECOND_IN_SECOND) {
261 result = new Millisecond(this.millisecond + 1, getSecond());
262 }
263 else {
264 Second next = (Second) getSecond().next();
265 if (next != null) {
266 result = new Millisecond(FIRST_MILLISECOND_IN_SECOND, next);
267 }
268 }
269 return result;
270
271 }
272
273 /**
274 * Returns a serial index number for the millisecond.
275 *
276 * @return The serial index number.
277 */
278 public long getSerialIndex() {
279 long hourIndex = this.day.getSerialIndex() * 24L + this.hour;
280 long minuteIndex = hourIndex * 60L + this.minute;
281 long secondIndex = minuteIndex * 60L + this.second;
282 return secondIndex * 1000L + this.millisecond;
283 }
284
285 /**
286 * Tests the equality of this object against an arbitrary Object.
287 * <P>
288 * This method will return true ONLY if the object is a Millisecond object
289 * representing the same millisecond as this instance.
290 *
291 * @param obj the object to compare
292 *
293 * @return <code>true</code> if milliseconds and seconds of this and object
294 * are the same.
295 */
296 public boolean equals(Object obj) {
297 if (obj == this) {
298 return true;
299 }
300 if (!(obj instanceof Millisecond)) {
301 return false;
302 }
303 Millisecond that = (Millisecond) obj;
304 if (this.millisecond != that.millisecond) {
305 return false;
306 }
307 if (this.second != that.second) {
308 return false;
309 }
310 if (this.minute != that.minute) {
311 return false;
312 }
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 hashcode.
330 */
331 public int hashCode() {
332 int result = 17;
333 result = 37 * result + this.millisecond;
334 result = 37 * result + getSecond().hashCode();
335 return result;
336 }
337
338 /**
339 * Returns an integer indicating the order of this Millisecond object
340 * relative to the specified object:
341 *
342 * negative == before, zero == same, positive == after.
343 *
344 * @param obj the object to compare
345 *
346 * @return negative == before, zero == same, positive == after.
347 */
348 public int compareTo(Object obj) {
349
350 int result;
351 long difference;
352
353 // CASE 1 : Comparing to another Second object
354 // -------------------------------------------
355 if (obj instanceof Millisecond) {
356 Millisecond ms = (Millisecond) obj;
357 difference = getFirstMillisecond() - ms.getFirstMillisecond();
358 if (difference > 0) {
359 result = 1;
360 }
361 else {
362 if (difference < 0) {
363 result = -1;
364 }
365 else {
366 result = 0;
367 }
368 }
369 }
370
371 // CASE 2 : Comparing to another TimePeriod object
372 // -----------------------------------------------
373 else if (obj instanceof RegularTimePeriod) {
374 RegularTimePeriod rtp = (RegularTimePeriod) obj;
375 final long thisVal = this.getFirstMillisecond();
376 final long anotherVal = rtp.getFirstMillisecond();
377 result = (thisVal < anotherVal ? -1
378 : (thisVal == anotherVal ? 0 : 1));
379 }
380
381 // CASE 3 : Comparing to a non-TimePeriod object
382 // ---------------------------------------------
383 else {
384 // consider time periods to be ordered after general objects
385 result = 1;
386 }
387
388 return result;
389
390 }
391
392 /**
393 * Returns the first millisecond of the time period.
394 *
395 * @param calendar the calendar (<code>null</code> not permitted).
396 *
397 * @return The first millisecond of the time period.
398 *
399 * @throws NullPointerException if <code>calendar</code> is
400 * <code>null</code>.
401 */
402 public long getFirstMillisecond(Calendar calendar) {
403 int year = this.day.getYear();
404 int month = this.day.getMonth() - 1;
405 int day = this.day.getDayOfMonth();
406 calendar.clear();
407 calendar.set(year, month, day, this.hour, this.minute, this.second);
408 calendar.set(Calendar.MILLISECOND, this.millisecond);
409 //return calendar.getTimeInMillis(); // this won't work for JDK 1.3
410 return calendar.getTime().getTime();
411 }
412
413 /**
414 * Returns the last millisecond of the time period.
415 *
416 * @param calendar the calendar (<code>null</code> not permitted).
417 *
418 * @return The last millisecond of the time period.
419 *
420 * @throws NullPointerException if <code>calendar</code> is
421 * <code>null</code>.
422 */
423 public long getLastMillisecond(Calendar calendar) {
424 return getFirstMillisecond(calendar);
425 }
426
427 }