Source for org.jfree.data.time.TimeSeriesDataItem

   1: /* ===========================================================
   2:  * JFreeChart : a free chart library for the Java(tm) platform
   3:  * ===========================================================
   4:  *
   5:  * (C) Copyright 2000-2007, by Object Refinery Limited and Contributors.
   6:  *
   7:  * Project Info:  http://www.jfree.org/jfreechart/index.html
   8:  *
   9:  * This library is free software; you can redistribute it and/or modify it 
  10:  * under the terms of the GNU Lesser General Public License as published by 
  11:  * the Free Software Foundation; either version 2.1 of the License, or 
  12:  * (at your option) any later version.
  13:  *
  14:  * This library is distributed in the hope that it will be useful, but 
  15:  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
  16:  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 
  17:  * License for more details.
  18:  *
  19:  * You should have received a copy of the GNU Lesser General Public
  20:  * License along with this library; if not, write to the Free Software
  21:  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 
  22:  * USA.  
  23:  *
  24:  * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 
  25:  * in the United States and other countries.]
  26:  *
  27:  * -----------------------
  28:  * TimeSeriesDataItem.java
  29:  * -----------------------
  30:  * (C) Copyright 2001-2007, by Object Refinery Limited.
  31:  *
  32:  * Original Author:  David Gilbert (for Object Refinery Limited);
  33:  * Contributor(s):   -;
  34:  *
  35:  * Changes
  36:  * -------
  37:  * 11-Oct-2001 : Version 1 (DG);
  38:  * 15-Nov-2001 : Updated Javadoc comments (DG);
  39:  * 29-Nov-2001 : Added cloning (DG);
  40:  * 24-Jun-2002 : Removed unnecessary import (DG);
  41:  * 07-Oct-2002 : Fixed errors reported by Checkstyle (DG);
  42:  * 13-Mar-2003 : Renamed TimeSeriesDataPair --> TimeSeriesDataItem, moved to
  43:  *               com.jrefinery.data.time package, implemented Serializable (DG)
  44:  */
  45: 
  46: package org.jfree.data.time;
  47: 
  48: import java.io.Serializable;
  49: 
  50: /**
  51:  * Represents one data item in a time series.
  52:  * <P>
  53:  * The time period can be any of the following:
  54:  * <ul>
  55:  * <li>{@link Year}</li>
  56:  * <li>{@link Quarter}</li>
  57:  * <li>{@link Month}</li>
  58:  * <li>{@link Week}</li>
  59:  * <li>{@link Day}</li>
  60:  * <li>{@link Hour}</li>
  61:  * <li>{@link Minute}</li>
  62:  * <li>{@link Second}</li>
  63:  * <li>{@link Millisecond}</li>
  64:  * <li>{@link FixedMillisecond}</li>
  65:  * </ul>
  66:  *
  67:  * The time period is an immutable property of the data item.  Data items will
  68:  * often be sorted within a list, and allowing the time period to be changed
  69:  * could destroy the sort order.
  70:  * <P>
  71:  * Implements the <code>Comparable</code> interface so that standard Java 
  72:  * sorting can be used to keep the data items in order.
  73:  *
  74:  */
  75: public class TimeSeriesDataItem implements Cloneable, Comparable, Serializable {
  76: 
  77:     /** For serialization. */
  78:     private static final long serialVersionUID = -2235346966016401302L;
  79:     
  80:     /** The time period. */
  81:     private RegularTimePeriod period;
  82: 
  83:     /** The value associated with the time period. */
  84:     private Number value;
  85: 
  86:     /**
  87:      * Constructs a new data item that associates a value with a time period.
  88:      *
  89:      * @param period  the time period (<code>null</code> not permitted).
  90:      * @param value  the value (<code>null</code> permitted).
  91:      */
  92:     public TimeSeriesDataItem(RegularTimePeriod period, Number value) {
  93:         if (period == null) {
  94:             throw new IllegalArgumentException("Null 'period' argument.");   
  95:         }
  96:         this.period = period;
  97:         this.value = value;
  98:     }
  99: 
 100:     /**
 101:      * Constructs a new data item that associates a value with a time period.
 102:      *
 103:      * @param period  the time period (<code>null</code> not permitted).
 104:      * @param value  the value associated with the time period.
 105:      */
 106:     public TimeSeriesDataItem(RegularTimePeriod period, double value) {
 107:         this(period, new Double(value));
 108:     }
 109: 
 110:     /**
 111:      * Returns the time period.
 112:      *
 113:      * @return The time period (never <code>null</code>).
 114:      */
 115:     public RegularTimePeriod getPeriod() {
 116:         return this.period;
 117:     }
 118: 
 119:     /**
 120:      * Returns the value.
 121:      *
 122:      * @return The value (<code>null</code> possible).
 123:      */
 124:     public Number getValue() {
 125:         return this.value;
 126:     }
 127: 
 128:     /**
 129:      * Sets the value for this data item.
 130:      *
 131:      * @param value  the value (<code>null</code> permitted).
 132:      */
 133:     public void setValue(Number value) {
 134:         this.value = value;
 135:     }
 136: 
 137:     /**
 138:      * Tests this object for equality with an arbitrary object.
 139:      *
 140:      * @param o  the other object.
 141:      *
 142:      * @return A boolean.
 143:      */
 144:     public boolean equals(Object o) {
 145:         if (this == o) {
 146:             return true;
 147:         }
 148:         if (!(o instanceof TimeSeriesDataItem)) {
 149:             return false;
 150:         }
 151:         TimeSeriesDataItem timeSeriesDataItem = (TimeSeriesDataItem) o;
 152:         if (this.period != null) {
 153:             if (!this.period.equals(timeSeriesDataItem.period)) {
 154:                 return false;
 155:             }
 156:         }
 157:         else if (timeSeriesDataItem.period != null) {
 158:            return false;
 159:         }
 160:         
 161:         if (this.value != null) {
 162:             if (!this.value.equals(timeSeriesDataItem.value)) {
 163:                 return false;
 164:             }
 165:         }
 166:         else if (timeSeriesDataItem.value != null) {
 167:             return false;
 168:         }
 169: 
 170:         return true;
 171:     }
 172: 
 173:     /**
 174:      * Returns a hash code.
 175:      * 
 176:      * @return A hash code.
 177:      */
 178:     public int hashCode() {
 179:         int result;
 180:         result = (this.period != null ? this.period.hashCode() : 0);
 181:         result = 29 * result + (this.value != null ? this.value.hashCode() : 0);
 182:         return result;
 183:     }
 184: 
 185:     /**
 186:      * Returns an integer indicating the order of this data pair object
 187:      * relative to another object.
 188:      * <P>
 189:      * For the order we consider only the timing:
 190:      * negative == before, zero == same, positive == after.
 191:      *
 192:      * @param o1  The object being compared to.
 193:      *
 194:      * @return An integer indicating the order of the data item object 
 195:      *         relative to another object.
 196:      */
 197:     public int compareTo(Object o1) {
 198: 
 199:         int result;
 200: 
 201:         // CASE 1 : Comparing to another TimeSeriesDataItem object
 202:         // -------------------------------------------------------
 203:         if (o1 instanceof TimeSeriesDataItem) {
 204:             TimeSeriesDataItem datapair = (TimeSeriesDataItem) o1;
 205:             result = getPeriod().compareTo(datapair.getPeriod());
 206:         }
 207: 
 208:         // CASE 2 : Comparing to a general object
 209:         // ---------------------------------------------
 210:         else {
 211:             // consider time periods to be ordered after general objects
 212:             result = 1;
 213:         }
 214: 
 215:         return result;
 216: 
 217:     }
 218: 
 219:     /**
 220:      * Clones the data item.  Note: there is no need to clone the period or 
 221:      * value since they are immutable classes.
 222:      *
 223:      * @return A clone of the data item.
 224:      */
 225:     public Object clone() {
 226:         Object clone = null;
 227:         try {
 228:             clone = super.clone();
 229:         }
 230:         catch (CloneNotSupportedException e) { // won't get here...
 231:             e.printStackTrace();
 232:         }
 233:         return clone;
 234:     }
 235: 
 236: }