001: /* ===========================================================
002: * JFreeChart : a free chart library for the Java(tm) platform
003: * ===========================================================
004: *
005: * (C) Copyright 2000-2005, 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: * TimeSeriesDataItem.java
029: * -----------------------
030: * (C) Copyright 2001-2005, by Object Refinery Limited.
031: *
032: * Original Author: David Gilbert (for Object Refinery Limited);
033: * Contributor(s): -;
034: *
035: * $Id: TimeSeriesDataItem.java,v 1.5.2.1 2005/10/25 21:35:24 mungady Exp $
036: *
037: * Changes
038: * -------
039: * 11-Oct-2001 : Version 1 (DG);
040: * 15-Nov-2001 : Updated Javadoc comments (DG);
041: * 29-Nov-2001 : Added cloning (DG);
042: * 24-Jun-2002 : Removed unnecessary import (DG);
043: * 07-Oct-2002 : Fixed errors reported by Checkstyle (DG);
044: * 13-Mar-2003 : Renamed TimeSeriesDataPair --> TimeSeriesDataItem, moved to
045: * com.jrefinery.data.time package, implemented Serializable (DG)
046: */
047:
048: package org.jfree.data.time;
049:
050: import java.io.Serializable;
051:
052: /**
053: * Represents one data item in a time series.
054: * <P>
055: * The time period can be any of the following:
056: * <ul>
057: * <li>{@link Year}</li>
058: * <li>{@link Quarter}</li>
059: * <li>{@link Month}</li>
060: * <li>{@link Week}</li>
061: * <li>{@link Day}</li>
062: * <li>{@link Hour}</li>
063: * <li>{@link Minute}</li>
064: * <li>{@link Second}</li>
065: * <li>{@link Millisecond}</li>
066: * <li>{@link FixedMillisecond}</li>
067: * </ul>
068: *
069: * The time period is an immutable property of the data item. Data items will
070: * often be sorted within a list, and allowing the time period to be changed
071: * could destroy the sort order.
072: * <P>
073: * Implements the <code>Comparable</code> interface so that standard Java
074: * sorting can be used to keep the data items in order.
075: *
076: */
077: public class TimeSeriesDataItem implements Cloneable, Comparable,
078: Serializable {
079:
080: /** For serialization. */
081: private static final long serialVersionUID = -2235346966016401302L;
082:
083: /** The time period. */
084: private RegularTimePeriod period;
085:
086: /** The value associated with the time period. */
087: private Number value;
088:
089: /**
090: * Constructs a new data item that associates a value with a time period.
091: *
092: * @param period the time period (<code>null</code> not permitted).
093: * @param value the value (<code>null</code> permitted).
094: */
095: public TimeSeriesDataItem(RegularTimePeriod period, Number value) {
096: if (period == null) {
097: throw new IllegalArgumentException(
098: "Null 'period' argument.");
099: }
100: this .period = period;
101: this .value = value;
102: }
103:
104: /**
105: * Constructs a new data item that associates a value with a time period.
106: *
107: * @param period the time period (<code>null</code> not permitted).
108: * @param value the value associated with the time period.
109: */
110: public TimeSeriesDataItem(RegularTimePeriod period, double value) {
111: this (period, new Double(value));
112: }
113:
114: /**
115: * Returns the time period.
116: *
117: * @return The time period (never <code>null</code>).
118: */
119: public RegularTimePeriod getPeriod() {
120: return this .period;
121: }
122:
123: /**
124: * Returns the value.
125: *
126: * @return The value (<code>null</code> possible).
127: */
128: public Number getValue() {
129: return this .value;
130: }
131:
132: /**
133: * Sets the value for this data item.
134: *
135: * @param value the value (<code>null</code> permitted).
136: */
137: public void setValue(Number value) {
138: this .value = value;
139: }
140:
141: /**
142: * Tests this object for equality with an arbitrary object.
143: *
144: * @param o the other object.
145: *
146: * @return A boolean.
147: */
148: public boolean equals(Object o) {
149: if (this == o) {
150: return true;
151: }
152: if (!(o instanceof TimeSeriesDataItem)) {
153: return false;
154: }
155: TimeSeriesDataItem timeSeriesDataItem = (TimeSeriesDataItem) o;
156: if (this .period != null) {
157: if (!this .period.equals(timeSeriesDataItem.period)) {
158: return false;
159: }
160: } else if (timeSeriesDataItem.period != null) {
161: return false;
162: }
163:
164: if (this .value != null) {
165: if (!this .value.equals(timeSeriesDataItem.value)) {
166: return false;
167: }
168: } else if (timeSeriesDataItem.value != null) {
169: return false;
170: }
171:
172: return true;
173: }
174:
175: /**
176: * Returns a hash code.
177: *
178: * @return A hash code.
179: */
180: public int hashCode() {
181: int result;
182: result = (this .period != null ? this .period.hashCode() : 0);
183: result = 29 * result
184: + (this .value != null ? this .value.hashCode() : 0);
185: return result;
186: }
187:
188: /**
189: * Returns an integer indicating the order of this data pair object
190: * relative to another object.
191: * <P>
192: * For the order we consider only the timing:
193: * negative == before, zero == same, positive == after.
194: *
195: * @param o1 The object being compared to.
196: *
197: * @return An integer indicating the order of the data item object
198: * relative to another object.
199: */
200: public int compareTo(Object o1) {
201:
202: int result;
203:
204: // CASE 1 : Comparing to another TimeSeriesDataItem object
205: // -------------------------------------------------------
206: if (o1 instanceof TimeSeriesDataItem) {
207: TimeSeriesDataItem datapair = (TimeSeriesDataItem) o1;
208: result = getPeriod().compareTo(datapair.getPeriod());
209: }
210:
211: // CASE 2 : Comparing to a general object
212: // ---------------------------------------------
213: else {
214: // consider time periods to be ordered after general objects
215: result = 1;
216: }
217:
218: return result;
219:
220: }
221:
222: /**
223: * Clones the data item. Note: there is no need to clone the period or
224: * value since they are immutable classes.
225: *
226: * @return A clone of the data item.
227: */
228: public Object clone() {
229: Object clone = null;
230: try {
231: clone = super .clone();
232: } catch (CloneNotSupportedException e) { // won't get here...
233: e.printStackTrace();
234: }
235: return clone;
236: }
237:
238: }
|