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