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, Serializable { 078 079 /** For serialization. */ 080 private static final long serialVersionUID = -2235346966016401302L; 081 082 /** The time period. */ 083 private RegularTimePeriod period; 084 085 /** The value associated with the time period. */ 086 private Number value; 087 088 /** 089 * Constructs a new data item that associates a value with a time period. 090 * 091 * @param period the time period (<code>null</code> not permitted). 092 * @param value the value (<code>null</code> permitted). 093 */ 094 public TimeSeriesDataItem(RegularTimePeriod period, Number value) { 095 if (period == null) { 096 throw new IllegalArgumentException("Null 'period' argument."); 097 } 098 this.period = period; 099 this.value = value; 100 } 101 102 /** 103 * Constructs a new data item that associates a value with a time period. 104 * 105 * @param period the time period (<code>null</code> not permitted). 106 * @param value the value associated with the time period. 107 */ 108 public TimeSeriesDataItem(RegularTimePeriod period, double value) { 109 this(period, new Double(value)); 110 } 111 112 /** 113 * Returns the time period. 114 * 115 * @return The time period (never <code>null</code>). 116 */ 117 public RegularTimePeriod getPeriod() { 118 return this.period; 119 } 120 121 /** 122 * Returns the value. 123 * 124 * @return The value (<code>null</code> possible). 125 */ 126 public Number getValue() { 127 return this.value; 128 } 129 130 /** 131 * Sets the value for this data item. 132 * 133 * @param value the value (<code>null</code> permitted). 134 */ 135 public void setValue(Number value) { 136 this.value = value; 137 } 138 139 /** 140 * Tests this object for equality with an arbitrary object. 141 * 142 * @param o the other object. 143 * 144 * @return A boolean. 145 */ 146 public boolean equals(Object o) { 147 if (this == o) { 148 return true; 149 } 150 if (!(o instanceof TimeSeriesDataItem)) { 151 return false; 152 } 153 TimeSeriesDataItem timeSeriesDataItem = (TimeSeriesDataItem) o; 154 if (this.period != null) { 155 if (!this.period.equals(timeSeriesDataItem.period)) { 156 return false; 157 } 158 } 159 else if (timeSeriesDataItem.period != null) { 160 return false; 161 } 162 163 if (this.value != null) { 164 if (!this.value.equals(timeSeriesDataItem.value)) { 165 return false; 166 } 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 + (this.value != null ? this.value.hashCode() : 0); 184 return result; 185 } 186 187 /** 188 * Returns an integer indicating the order of this data pair object 189 * relative to another object. 190 * <P> 191 * For the order we consider only the timing: 192 * negative == before, zero == same, positive == after. 193 * 194 * @param o1 The object being compared to. 195 * 196 * @return An integer indicating the order of the data item object 197 * relative to another object. 198 */ 199 public int compareTo(Object o1) { 200 201 int result; 202 203 // CASE 1 : Comparing to another TimeSeriesDataItem object 204 // ------------------------------------------------------- 205 if (o1 instanceof TimeSeriesDataItem) { 206 TimeSeriesDataItem datapair = (TimeSeriesDataItem) o1; 207 result = getPeriod().compareTo(datapair.getPeriod()); 208 } 209 210 // CASE 2 : Comparing to a general object 211 // --------------------------------------------- 212 else { 213 // consider time periods to be ordered after general objects 214 result = 1; 215 } 216 217 return result; 218 219 } 220 221 /** 222 * Clones the data item. Note: there is no need to clone the period or 223 * value since they are immutable classes. 224 * 225 * @return A clone of the data item. 226 */ 227 public Object clone() { 228 Object clone = null; 229 try { 230 clone = super.clone(); 231 } 232 catch (CloneNotSupportedException e) { // won't get here... 233 e.printStackTrace(); 234 } 235 return clone; 236 } 237 238 }