001 /* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2007, 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 * DateTickUnit.java
029 * -----------------
030 * (C) Copyright 2000-2007, by Object Refinery Limited.
031 *
032 * Original Author: David Gilbert (for Object Refinery Limited);
033 * Contributor(s): Chris Boek;
034 *
035 * $Id: DateTickUnit.java,v 1.7.2.3 2007/04/04 10:58:19 mungady Exp $
036 *
037 * Changes (from 8-Nov-2002)
038 * --------------------------
039 * 08-Nov-2002 : Moved to new package com.jrefinery.chart.axis (DG);
040 * 27-Nov-2002 : Added IllegalArgumentException to getMillisecondCount()
041 * method (DG);
042 * 26-Mar-2003 : Implemented Serializable (DG);
043 * 12-Nov-2003 : Added roll fields that can improve the labelling on segmented
044 * date axes (DG);
045 * 03-Dec-2003 : DateFormat constructor argument is now filled with an default
046 * if null (TM);
047 * 07-Dec-2003 : Fixed bug (null pointer exception) in constructor (DG);
048 * ------------- JFREECHART 1.0.x ---------------------------------------------
049 * 21-Mar-2007 : Added toString() for debugging (DG);
050 * 04-Apr-2007 : Added new methods addToDate(Date, TimeZone) and rollDate(Date,
051 * TimeZone) (CB);
052 *
053 */
054
055 package org.jfree.chart.axis;
056
057 import java.io.Serializable;
058 import java.text.DateFormat;
059 import java.util.Calendar;
060 import java.util.Date;
061 import java.util.TimeZone;
062
063 import org.jfree.util.ObjectUtilities;
064
065 /**
066 * A tick unit for use by subclasses of {@link DateAxis}. Instances of this
067 * class are immutable.
068 */
069 public class DateTickUnit extends TickUnit implements Serializable {
070
071 /** For serialization. */
072 private static final long serialVersionUID = -7289292157229621901L;
073
074 /** A constant for years. */
075 public static final int YEAR = 0;
076
077 /** A constant for months. */
078 public static final int MONTH = 1;
079
080 /** A constant for days. */
081 public static final int DAY = 2;
082
083 /** A constant for hours. */
084 public static final int HOUR = 3;
085
086 /** A constant for minutes. */
087 public static final int MINUTE = 4;
088
089 /** A constant for seconds. */
090 public static final int SECOND = 5;
091
092 /** A constant for milliseconds. */
093 public static final int MILLISECOND = 6;
094
095 /** The unit. */
096 private int unit;
097
098 /** The unit count. */
099 private int count;
100
101 /** The roll unit. */
102 private int rollUnit;
103
104 /** The roll count. */
105 private int rollCount;
106
107 /** The date formatter. */
108 private DateFormat formatter;
109
110 /**
111 * Creates a new date tick unit. The dates will be formatted using a
112 * SHORT format for the default locale.
113 *
114 * @param unit the unit.
115 * @param count the unit count.
116 */
117 public DateTickUnit(int unit, int count) {
118 this(unit, count, null);
119 }
120
121 /**
122 * Creates a new date tick unit. You can specify the units using one of
123 * the constants YEAR, MONTH, DAY, HOUR, MINUTE, SECOND or MILLISECOND.
124 * In addition, you can specify a unit count, and a date format.
125 *
126 * @param unit the unit.
127 * @param count the unit count.
128 * @param formatter the date formatter (defaults to DateFormat.SHORT).
129 */
130 public DateTickUnit(int unit, int count, DateFormat formatter) {
131
132 this(unit, count, unit, count, formatter);
133
134 }
135
136 /**
137 * Creates a new unit.
138 *
139 * @param unit the unit.
140 * @param count the count.
141 * @param rollUnit the roll unit.
142 * @param rollCount the roll count.
143 * @param formatter the date formatter (defaults to DateFormat.SHORT).
144 */
145 public DateTickUnit(int unit, int count, int rollUnit, int rollCount,
146 DateFormat formatter) {
147 super(DateTickUnit.getMillisecondCount(unit, count));
148 this.unit = unit;
149 this.count = count;
150 this.rollUnit = rollUnit;
151 this.rollCount = rollCount;
152 this.formatter = formatter;
153 if (formatter == null) {
154 this.formatter = DateFormat.getDateInstance(DateFormat.SHORT);
155 }
156 }
157
158 /**
159 * Returns the date unit. This will be one of the constants
160 * <code>YEAR</code>, <code>MONTH</code>, <code>DAY</code>,
161 * <code>HOUR</code>, <code>MINUTE</code>, <code>SECOND</code> or
162 * <code>MILLISECOND</code>, defined by this class. Note that these
163 * constants do NOT correspond to those defined in Java's
164 * <code>Calendar</code> class.
165 *
166 * @return The date unit.
167 */
168 public int getUnit() {
169 return this.unit;
170 }
171
172 /**
173 * Returns the unit count.
174 *
175 * @return The unit count.
176 */
177 public int getCount() {
178 return this.count;
179 }
180
181 /**
182 * Returns the roll unit. This is the amount by which the tick advances if
183 * it is "hidden" when displayed on a segmented date axis. Typically the
184 * roll will be smaller than the regular tick unit (for example, a 7 day
185 * tick unit might use a 1 day roll).
186 *
187 * @return The roll unit.
188 */
189 public int getRollUnit() {
190 return this.rollUnit;
191 }
192
193 /**
194 * Returns the roll count.
195 *
196 * @return The roll count.
197 */
198 public int getRollCount() {
199 return this.rollCount;
200 }
201
202 /**
203 * Formats a value.
204 *
205 * @param milliseconds date in milliseconds since 01-01-1970.
206 *
207 * @return The formatted date.
208 */
209 public String valueToString(double milliseconds) {
210 return this.formatter.format(new Date((long) milliseconds));
211 }
212
213 /**
214 * Formats a date using the tick unit's formatter.
215 *
216 * @param date the date.
217 *
218 * @return The formatted date.
219 */
220 public String dateToString(Date date) {
221 return this.formatter.format(date);
222 }
223
224 /**
225 * Calculates a new date by adding this unit to the base date.
226 *
227 * @param base the base date.
228 *
229 * @return A new date one unit after the base date.
230 *
231 * @see #addToDate(Date, TimeZone)
232 */
233 public Date addToDate(Date base) {
234 Calendar calendar = Calendar.getInstance();
235 calendar.setTime(base);
236 calendar.add(getCalendarField(this.unit), this.count);
237 return calendar.getTime();
238 }
239
240 /**
241 * Calculates a new date by adding this unit to the base date.
242 *
243 * @param base the base date.
244 * @param zone the time zone for the date calculation.
245 *
246 * @return A new date one unit after the base date.
247 *
248 * @since 1.0.6
249 * @see #addToDate(Date)
250 */
251 public Date addToDate(Date base, TimeZone zone) {
252 Calendar calendar = Calendar.getInstance(zone);
253 calendar.setTime(base);
254 calendar.add(getCalendarField(this.unit), this.count);
255 return calendar.getTime();
256 }
257
258 /**
259 * Rolls the date forward by the amount specified by the roll unit and
260 * count.
261 *
262 * @param base the base date.
263
264 * @return The rolled date.
265 *
266 * @see #rollDate(Date, TimeZone)
267 */
268 public Date rollDate(Date base) {
269 Calendar calendar = Calendar.getInstance();
270 calendar.setTime(base);
271 calendar.add(getCalendarField(this.rollUnit), this.rollCount);
272 return calendar.getTime();
273 }
274
275 /**
276 * Rolls the date forward by the amount specified by the roll unit and
277 * count.
278 *
279 * @param base the base date.
280 * @param zone the time zone.
281 *
282 * @return The rolled date.
283 *
284 * @since 1.0.6
285 * @see #rollDate(Date)
286 */
287 public Date rollDate(Date base, TimeZone zone) {
288 Calendar calendar = Calendar.getInstance(zone);
289 calendar.setTime(base);
290 calendar.add(getCalendarField(this.rollUnit), this.rollCount);
291 return calendar.getTime();
292 }
293
294 /**
295 * Returns a field code that can be used with the <code>Calendar</code>
296 * class.
297 *
298 * @return The field code.
299 */
300 public int getCalendarField() {
301 return getCalendarField(this.unit);
302 }
303
304 /**
305 * Returns a field code (that can be used with the Calendar class) for a
306 * given 'unit' code. The 'unit' is one of: {@link #YEAR}, {@link #MONTH},
307 * {@link #DAY}, {@link #HOUR}, {@link #MINUTE}, {@link #SECOND} and
308 * {@link #MILLISECOND}.
309 *
310 * @param tickUnit the unit.
311 *
312 * @return The field code.
313 */
314 private int getCalendarField(int tickUnit) {
315
316 switch (tickUnit) {
317 case (YEAR):
318 return Calendar.YEAR;
319 case (MONTH):
320 return Calendar.MONTH;
321 case (DAY):
322 return Calendar.DATE;
323 case (HOUR):
324 return Calendar.HOUR_OF_DAY;
325 case (MINUTE):
326 return Calendar.MINUTE;
327 case (SECOND):
328 return Calendar.SECOND;
329 case (MILLISECOND):
330 return Calendar.MILLISECOND;
331 default:
332 return Calendar.MILLISECOND;
333 }
334
335 }
336
337 /**
338 * Returns the (approximate) number of milliseconds for the given unit and
339 * unit count.
340 * <P>
341 * This value is an approximation some of the time (e.g. months are
342 * assumed to have 31 days) but this shouldn't matter.
343 *
344 * @param unit the unit.
345 * @param count the unit count.
346 *
347 * @return The number of milliseconds.
348 */
349 private static long getMillisecondCount(int unit, int count) {
350
351 switch (unit) {
352 case (YEAR):
353 return (365L * 24L * 60L * 60L * 1000L) * count;
354 case (MONTH):
355 return (31L * 24L * 60L * 60L * 1000L) * count;
356 case (DAY):
357 return (24L * 60L * 60L * 1000L) * count;
358 case (HOUR):
359 return (60L * 60L * 1000L) * count;
360 case (MINUTE):
361 return (60L * 1000L) * count;
362 case (SECOND):
363 return 1000L * count;
364 case (MILLISECOND):
365 return count;
366 default:
367 throw new IllegalArgumentException(
368 "DateTickUnit.getMillisecondCount() : unit must "
369 + "be one of the constants YEAR, MONTH, DAY, HOUR, MINUTE, "
370 + "SECOND or MILLISECOND defined in the DateTickUnit "
371 + "class. Do *not* use the constants defined in "
372 + "java.util.Calendar."
373 );
374 }
375
376 }
377
378 /**
379 * Tests this unit for equality with another object.
380 *
381 * @param obj the object (<code>null</code> permitted).
382 *
383 * @return <code>true</code> or <code>false</code>.
384 */
385 public boolean equals(Object obj) {
386 if (obj == this) {
387 return true;
388 }
389 if (!(obj instanceof DateTickUnit)) {
390 return false;
391 }
392 if (!super.equals(obj)) {
393 return false;
394 }
395 DateTickUnit that = (DateTickUnit) obj;
396 if (this.unit != that.unit) {
397 return false;
398 }
399 if (this.count != that.count) {
400 return false;
401 }
402 if (!ObjectUtilities.equal(this.formatter, that.formatter)) {
403 return false;
404 }
405 return true;
406 }
407
408 /**
409 * Returns a hash code for this object.
410 *
411 * @return A hash code.
412 */
413 public int hashCode() {
414 int result = 19;
415 result = 37 * result + this.unit;
416 result = 37 * result + this.count;
417 result = 37 * result + this.formatter.hashCode();
418 return result;
419 }
420
421 /**
422 * Strings for use by the toString() method.
423 */
424 private static final String[] units = {"YEAR", "MONTH", "DAY", "HOUR",
425 "MINUTE", "SECOND", "MILLISECOND"};
426
427 /**
428 * Returns a string representation of this instance, primarily used for
429 * debugging purposes.
430 *
431 * @return A string representation of this instance.
432 */
433 public String toString() {
434 return "DateTickUnit[" + DateTickUnit.units[this.unit] + ", "
435 + this.count + "]";
436 }
437
438 }