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 * Day.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 * 15-Nov-2001 : Updated Javadoc comments (DG);
039 * 04-Dec-2001 : Added static method to parse a string into a Day object (DG);
040 * 19-Dec-2001 : Added new constructor as suggested by Paul English (DG);
041 * 29-Jan-2002 : Changed getDay() method to getSerialDate() (DG);
042 * 26-Feb-2002 : Changed getStart(), getMiddle() and getEnd() methods to
043 * evaluate with reference to a particular time zone (DG);
044 * 19-Mar-2002 : Changed the API for the TimePeriod classes (DG);
045 * 29-May-2002 : Fixed bug in equals method (DG);
046 * 24-Jun-2002 : Removed unnecessary imports (DG);
047 * 10-Sep-2002 : Added getSerialIndex() method (DG);
048 * 07-Oct-2002 : Fixed errors reported by Checkstyle (DG);
049 * 10-Jan-2003 : Changed base class and method names (DG);
050 * 13-Mar-2003 : Moved to com.jrefinery.data.time package, and implemented
051 * Serializable (DG);
052 * 21-Oct-2003 : Added hashCode() method (DG);
053 * 30-Sep-2004 : Replaced getTime().getTime() with getTimeInMillis() (DG);
054 * 04-Nov-2004 : Reverted change of 30-Sep-2004, because it won't work for
055 * JDK 1.3 (DG);
056 * ------------- JFREECHART 1.0.x ---------------------------------------------
057 * 05-Oct-2006 : Updated API docs (DG);
058 * 06-Oct-2006 : Refactored to cache first and last millisecond values (DG);
059 * 16-Sep-2008 : Deprecated DEFAULT_TIME_ZONE (DG);
060 *
061 */
062
063 package org.jfree.data.time;
064
065 import java.io.Serializable;
066 import java.text.DateFormat;
067 import java.text.ParseException;
068 import java.text.SimpleDateFormat;
069 import java.util.Calendar;
070 import java.util.Date;
071 import java.util.TimeZone;
072
073 import org.jfree.date.SerialDate;
074
075 /**
076 * Represents a single day in the range 1-Jan-1900 to 31-Dec-9999. This class
077 * is immutable, which is a requirement for all {@link RegularTimePeriod}
078 * subclasses.
079 */
080 public class Day extends RegularTimePeriod implements Serializable {
081
082 /** For serialization. */
083 private static final long serialVersionUID = -7082667380758962755L;
084
085 /** A standard date formatter. */
086 protected static final DateFormat DATE_FORMAT
087 = new SimpleDateFormat("yyyy-MM-dd");
088
089 /** A date formatter for the default locale. */
090 protected static final DateFormat
091 DATE_FORMAT_SHORT = DateFormat.getDateInstance(DateFormat.SHORT);
092
093 /** A date formatter for the default locale. */
094 protected static final DateFormat
095 DATE_FORMAT_MEDIUM = DateFormat.getDateInstance(DateFormat.MEDIUM);
096
097 /** A date formatter for the default locale. */
098 protected static final DateFormat
099 DATE_FORMAT_LONG = DateFormat.getDateInstance(DateFormat.LONG);
100
101 /** The day (uses SerialDate for convenience). */
102 private SerialDate serialDate;
103
104 /** The first millisecond. */
105 private long firstMillisecond;
106
107 /** The last millisecond. */
108 private long lastMillisecond;
109
110 /**
111 * Creates a new instance, derived from the system date/time (and assuming
112 * the default timezone).
113 */
114 public Day() {
115 this(new Date());
116 }
117
118 /**
119 * Constructs a new one day time period.
120 *
121 * @param day the day-of-the-month.
122 * @param month the month (1 to 12).
123 * @param year the year (1900 <= year <= 9999).
124 */
125 public Day(int day, int month, int year) {
126 this.serialDate = SerialDate.createInstance(day, month, year);
127 peg(Calendar.getInstance());
128 }
129
130 /**
131 * Constructs a new one day time period.
132 *
133 * @param serialDate the day (<code>null</code> not permitted).
134 */
135 public Day(SerialDate serialDate) {
136 if (serialDate == null) {
137 throw new IllegalArgumentException("Null 'serialDate' argument.");
138 }
139 this.serialDate = serialDate;
140 peg(Calendar.getInstance());
141 }
142
143 /**
144 * Constructs a new instance, based on a particular date/time and the
145 * default time zone.
146 *
147 * @param time the time (<code>null</code> not permitted).
148 *
149 * @see #Day(Date, TimeZone)
150 */
151 public Day(Date time) {
152 // defer argument checking...
153 this(time, TimeZone.getDefault());
154 }
155
156 /**
157 * Constructs a new instance, based on a particular date/time and time zone.
158 *
159 * @param time the date/time.
160 * @param zone the time zone.
161 */
162 public Day(Date time, TimeZone zone) {
163 // FIXME: need a Locale as well as a TimeZone
164 if (time == null) {
165 throw new IllegalArgumentException("Null 'time' argument.");
166 }
167 if (zone == null) {
168 throw new IllegalArgumentException("Null 'zone' argument.");
169 }
170 Calendar calendar = Calendar.getInstance(zone);
171 calendar.setTime(time);
172 int d = calendar.get(Calendar.DAY_OF_MONTH);
173 int m = calendar.get(Calendar.MONTH) + 1;
174 int y = calendar.get(Calendar.YEAR);
175 this.serialDate = SerialDate.createInstance(d, m, y);
176 peg(calendar);
177 }
178
179 /**
180 * Returns the day as a {@link SerialDate}. Note: the reference that is
181 * returned should be an instance of an immutable {@link SerialDate}
182 * (otherwise the caller could use the reference to alter the state of
183 * this <code>Day</code> instance, and <code>Day</code> is supposed
184 * to be immutable).
185 *
186 * @return The day as a {@link SerialDate}.
187 */
188 public SerialDate getSerialDate() {
189 return this.serialDate;
190 }
191
192 /**
193 * Returns the year.
194 *
195 * @return The year.
196 */
197 public int getYear() {
198 return this.serialDate.getYYYY();
199 }
200
201 /**
202 * Returns the month.
203 *
204 * @return The month.
205 */
206 public int getMonth() {
207 return this.serialDate.getMonth();
208 }
209
210 /**
211 * Returns the day of the month.
212 *
213 * @return The day of the month.
214 */
215 public int getDayOfMonth() {
216 return this.serialDate.getDayOfMonth();
217 }
218
219 /**
220 * Returns the first millisecond of the day. This will be determined
221 * relative to the time zone specified in the constructor, or in the
222 * calendar instance passed in the most recent call to the
223 * {@link #peg(Calendar)} method.
224 *
225 * @return The first millisecond of the day.
226 *
227 * @see #getLastMillisecond()
228 */
229 public long getFirstMillisecond() {
230 return this.firstMillisecond;
231 }
232
233 /**
234 * Returns the last millisecond of the day. This will be
235 * determined relative to the time zone specified in the constructor, or
236 * in the calendar instance passed in the most recent call to the
237 * {@link #peg(Calendar)} method.
238 *
239 * @return The last millisecond of the day.
240 *
241 * @see #getFirstMillisecond()
242 */
243 public long getLastMillisecond() {
244 return this.lastMillisecond;
245 }
246
247 /**
248 * Recalculates the start date/time and end date/time for this time period
249 * relative to the supplied calendar (which incorporates a time zone).
250 *
251 * @param calendar the calendar (<code>null</code> not permitted).
252 *
253 * @since 1.0.3
254 */
255 public void peg(Calendar calendar) {
256 this.firstMillisecond = getFirstMillisecond(calendar);
257 this.lastMillisecond = getLastMillisecond(calendar);
258 }
259
260 /**
261 * Returns the day preceding this one.
262 *
263 * @return The day preceding this one.
264 */
265 public RegularTimePeriod previous() {
266
267 Day result;
268 int serial = this.serialDate.toSerial();
269 if (serial > SerialDate.SERIAL_LOWER_BOUND) {
270 SerialDate yesterday = SerialDate.createInstance(serial - 1);
271 return new Day(yesterday);
272 }
273 else {
274 result = null;
275 }
276 return result;
277
278 }
279
280 /**
281 * Returns the day following this one, or <code>null</code> if some limit
282 * has been reached.
283 *
284 * @return The day following this one, or <code>null</code> if some limit
285 * has been reached.
286 */
287 public RegularTimePeriod next() {
288
289 Day result;
290 int serial = this.serialDate.toSerial();
291 if (serial < SerialDate.SERIAL_UPPER_BOUND) {
292 SerialDate tomorrow = SerialDate.createInstance(serial + 1);
293 return new Day(tomorrow);
294 }
295 else {
296 result = null;
297 }
298 return result;
299
300 }
301
302 /**
303 * Returns a serial index number for the day.
304 *
305 * @return The serial index number.
306 */
307 public long getSerialIndex() {
308 return this.serialDate.toSerial();
309 }
310
311 /**
312 * Returns the first millisecond of the day, evaluated using the supplied
313 * calendar (which determines the time zone).
314 *
315 * @param calendar calendar to use (<code>null</code> not permitted).
316 *
317 * @return The start of the day as milliseconds since 01-01-1970.
318 *
319 * @throws NullPointerException if <code>calendar</code> is
320 * <code>null</code>.
321 */
322 public long getFirstMillisecond(Calendar calendar) {
323 int year = this.serialDate.getYYYY();
324 int month = this.serialDate.getMonth();
325 int day = this.serialDate.getDayOfMonth();
326 calendar.clear();
327 calendar.set(year, month - 1, day, 0, 0, 0);
328 calendar.set(Calendar.MILLISECOND, 0);
329 //return calendar.getTimeInMillis(); // this won't work for JDK 1.3
330 return calendar.getTime().getTime();
331 }
332
333 /**
334 * Returns the last millisecond of the day, evaluated using the supplied
335 * calendar (which determines the time zone).
336 *
337 * @param calendar calendar to use (<code>null</code> not permitted).
338 *
339 * @return The end of the day as milliseconds since 01-01-1970.
340 *
341 * @throws NullPointerException if <code>calendar</code> is
342 * <code>null</code>.
343 */
344 public long getLastMillisecond(Calendar calendar) {
345 int year = this.serialDate.getYYYY();
346 int month = this.serialDate.getMonth();
347 int day = this.serialDate.getDayOfMonth();
348 calendar.clear();
349 calendar.set(year, month - 1, day, 23, 59, 59);
350 calendar.set(Calendar.MILLISECOND, 999);
351 //return calendar.getTimeInMillis(); // this won't work for JDK 1.3
352 return calendar.getTime().getTime();
353 }
354
355 /**
356 * Tests the equality of this Day object to an arbitrary object. Returns
357 * true if the target is a Day instance or a SerialDate instance
358 * representing the same day as this object. In all other cases,
359 * returns false.
360 *
361 * @param obj the object (<code>null</code> permitted).
362 *
363 * @return A flag indicating whether or not an object is equal to this day.
364 */
365 public boolean equals(Object obj) {
366
367 if (obj == this) {
368 return true;
369 }
370 if (!(obj instanceof Day)) {
371 return false;
372 }
373 Day that = (Day) obj;
374 if (!this.serialDate.equals(that.getSerialDate())) {
375 return false;
376 }
377 return true;
378
379 }
380
381 /**
382 * Returns a hash code for this object instance. The approach described by
383 * Joshua Bloch in "Effective Java" has been used here:
384 * <p>
385 * <code>http://developer.java.sun.com/developer/Books/effectivejava
386 * /Chapter3.pdf</code>
387 *
388 * @return A hash code.
389 */
390 public int hashCode() {
391 return this.serialDate.hashCode();
392 }
393
394 /**
395 * Returns an integer indicating the order of this Day object relative to
396 * the specified object:
397 *
398 * negative == before, zero == same, positive == after.
399 *
400 * @param o1 the object to compare.
401 *
402 * @return negative == before, zero == same, positive == after.
403 */
404 public int compareTo(Object o1) {
405
406 int result;
407
408 // CASE 1 : Comparing to another Day object
409 // ----------------------------------------
410 if (o1 instanceof Day) {
411 Day d = (Day) o1;
412 result = -d.getSerialDate().compare(this.serialDate);
413 }
414
415 // CASE 2 : Comparing to another TimePeriod object
416 // -----------------------------------------------
417 else if (o1 instanceof RegularTimePeriod) {
418 // more difficult case - evaluate later...
419 result = 0;
420 }
421
422 // CASE 3 : Comparing to a non-TimePeriod object
423 // ---------------------------------------------
424 else {
425 // consider time periods to be ordered after general objects
426 result = 1;
427 }
428
429 return result;
430
431 }
432
433 /**
434 * Returns a string representing the day.
435 *
436 * @return A string representing the day.
437 */
438 public String toString() {
439 return this.serialDate.toString();
440 }
441
442 /**
443 * Parses the string argument as a day.
444 * <P>
445 * This method is required to recognise YYYY-MM-DD as a valid format.
446 * Anything else, for now, is a bonus.
447 *
448 * @param s the date string to parse.
449 *
450 * @return <code>null</code> if the string does not contain any parseable
451 * string, the day otherwise.
452 */
453 public static Day parseDay(String s) {
454
455 try {
456 return new Day (Day.DATE_FORMAT.parse(s));
457 }
458 catch (ParseException e1) {
459 try {
460 return new Day (Day.DATE_FORMAT_SHORT.parse(s));
461 }
462 catch (ParseException e2) {
463 // ignore
464 }
465 }
466 return null;
467
468 }
469
470 }