Frames | No Frames |
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: * TimeTableXYDataset.java 29: * ----------------------- 30: * (C) Copyright 2004, 2005, 2007, by Andreas Schroeder and Contributors. 31: * 32: * Original Author: Andreas Schroeder; 33: * Contributor(s): David Gilbert (for Object Refinery Limited); 34: * Rob Eden; 35: * 36: * Changes 37: * ------- 38: * 01-Apr-2004 : Version 1 (AS); 39: * 05-May-2004 : Now implements AbstractIntervalXYDataset (DG); 40: * 15-Jul-2004 : Switched getX() with getXValue() and getY() with 41: * getYValue() (DG); 42: * 15-Sep-2004 : Added getXPosition(), setXPosition(), equals() and 43: * clone() (DG); 44: * 17-Nov-2004 : Updated methods for changes in DomainInfo interface (DG); 45: * 25-Nov-2004 : Added getTimePeriod(int) method (DG); 46: * 11-Jan-2005 : Removed deprecated code in preparation for the 1.0.0 47: * release (DG); 48: * 27-Jan-2005 : Modified to use TimePeriod rather than RegularTimePeriod (DG); 49: * 02-Feb-2007 : Removed author tags all over JFreeChart sources (DG); 50: * 25-Jul-2007 : Added clear() method by Rob Eden, see patch 1752205 (DG); 51: * 52: */ 53: 54: package org.jfree.data.time; 55: 56: import java.util.Calendar; 57: import java.util.List; 58: import java.util.Locale; 59: import java.util.TimeZone; 60: 61: import org.jfree.data.DefaultKeyedValues2D; 62: import org.jfree.data.DomainInfo; 63: import org.jfree.data.Range; 64: import org.jfree.data.general.DatasetChangeEvent; 65: import org.jfree.data.xy.AbstractIntervalXYDataset; 66: import org.jfree.data.xy.IntervalXYDataset; 67: import org.jfree.data.xy.TableXYDataset; 68: import org.jfree.util.PublicCloneable; 69: 70: /** 71: * A dataset for regular time periods that implements the 72: * {@link TableXYDataset} interface. 73: * 74: * @see org.jfree.data.xy.TableXYDataset 75: */ 76: public class TimeTableXYDataset extends AbstractIntervalXYDataset 77: implements Cloneable, PublicCloneable, 78: IntervalXYDataset, 79: DomainInfo, 80: TableXYDataset { 81: 82: /** 83: * The data structure to store the values. Each column represents 84: * a series (elsewhere in JFreeChart rows are typically used for series, 85: * but it doesn't matter that much since this data structure is private 86: * and symmetrical anyway), each row contains values for the same 87: * {@link RegularTimePeriod} (the rows are sorted into ascending order). 88: */ 89: private DefaultKeyedValues2D values; 90: 91: /** 92: * A flag that indicates that the domain is 'points in time'. If this flag 93: * is true, only the x-value (and not the x-interval) is used to determine 94: * the range of values in the domain. 95: */ 96: private boolean domainIsPointsInTime; 97: 98: /** 99: * The point within each time period that is used for the X value when this 100: * collection is used as an {@link org.jfree.data.xy.XYDataset}. This can 101: * be the start, middle or end of the time period. 102: */ 103: private TimePeriodAnchor xPosition; 104: 105: /** A working calendar (to recycle) */ 106: private Calendar workingCalendar; 107: 108: /** 109: * Creates a new dataset. 110: */ 111: public TimeTableXYDataset() { 112: // defer argument checking 113: this(TimeZone.getDefault(), Locale.getDefault()); 114: } 115: 116: /** 117: * Creates a new dataset with the given time zone. 118: * 119: * @param zone the time zone to use (<code>null</code> not permitted). 120: */ 121: public TimeTableXYDataset(TimeZone zone) { 122: // defer argument checking 123: this(zone, Locale.getDefault()); 124: } 125: 126: /** 127: * Creates a new dataset with the given time zone and locale. 128: * 129: * @param zone the time zone to use (<code>null</code> not permitted). 130: * @param locale the locale to use (<code>null</code> not permitted). 131: */ 132: public TimeTableXYDataset(TimeZone zone, Locale locale) { 133: if (zone == null) { 134: throw new IllegalArgumentException("Null 'zone' argument."); 135: } 136: if (locale == null) { 137: throw new IllegalArgumentException("Null 'locale' argument."); 138: } 139: this.values = new DefaultKeyedValues2D(true); 140: this.workingCalendar = Calendar.getInstance(zone, locale); 141: this.xPosition = TimePeriodAnchor.START; 142: } 143: 144: /** 145: * Returns a flag that controls whether the domain is treated as 'points in 146: * time'. 147: * <P> 148: * This flag is used when determining the max and min values for the domain. 149: * If true, then only the x-values are considered for the max and min 150: * values. If false, then the start and end x-values will also be taken 151: * into consideration. 152: * 153: * @return The flag. 154: */ 155: public boolean getDomainIsPointsInTime() { 156: return this.domainIsPointsInTime; 157: } 158: 159: /** 160: * Sets a flag that controls whether the domain is treated as 'points in 161: * time', or time periods. A {@link DatasetChangeEvent} is sent to all 162: * registered listeners. 163: * 164: * @param flag the new value of the flag. 165: */ 166: public void setDomainIsPointsInTime(boolean flag) { 167: this.domainIsPointsInTime = flag; 168: notifyListeners(new DatasetChangeEvent(this, this)); 169: } 170: 171: /** 172: * Returns the position within each time period that is used for the X 173: * value. 174: * 175: * @return The anchor position (never <code>null</code>). 176: */ 177: public TimePeriodAnchor getXPosition() { 178: return this.xPosition; 179: } 180: 181: /** 182: * Sets the position within each time period that is used for the X values, 183: * then sends a {@link DatasetChangeEvent} to all registered listeners. 184: * 185: * @param anchor the anchor position (<code>null</code> not permitted). 186: */ 187: public void setXPosition(TimePeriodAnchor anchor) { 188: if (anchor == null) { 189: throw new IllegalArgumentException("Null 'anchor' argument."); 190: } 191: this.xPosition = anchor; 192: notifyListeners(new DatasetChangeEvent(this, this)); 193: } 194: 195: /** 196: * Adds a new data item to the dataset and sends a 197: * {@link org.jfree.data.general.DatasetChangeEvent} to all registered 198: * listeners. 199: * 200: * @param period the time period. 201: * @param y the value for this period. 202: * @param seriesName the name of the series to add the value. 203: */ 204: public void add(TimePeriod period, double y, String seriesName) { 205: add(period, new Double(y), seriesName, true); 206: } 207: 208: /** 209: * Adds a new data item to the dataset. 210: * 211: * @param period the time period (<code>null</code> not permitted). 212: * @param y the value for this period (<code>null</code> permitted). 213: * @param seriesName the name of the series to add the value 214: * (<code>null</code> not permitted). 215: * @param notify whether dataset listener are notified or not. 216: */ 217: public void add(TimePeriod period, Number y, String seriesName, 218: boolean notify) { 219: this.values.addValue(y, period, seriesName); 220: if (notify) { 221: fireDatasetChanged(); 222: } 223: } 224: 225: /** 226: * Removes an existing data item from the dataset. 227: * 228: * @param period the (existing!) time period of the value to remove 229: * (<code>null</code> not permitted). 230: * @param seriesName the (existing!) series name to remove the value 231: * (<code>null</code> not permitted). 232: */ 233: public void remove(TimePeriod period, String seriesName) { 234: remove(period, seriesName, true); 235: } 236: 237: /** 238: * Removes an existing data item from the dataset. 239: * 240: * @param period the (existing!) time period of the value to remove 241: * (<code>null</code> not permitted). 242: * @param seriesName the (existing!) series name to remove the value 243: * (<code>null</code> not permitted). 244: * @param notify whether dataset listener are notified or not. 245: */ 246: public void remove(TimePeriod period, String seriesName, boolean notify) { 247: this.values.removeValue(period, seriesName); 248: if (notify) { 249: fireDatasetChanged(); 250: } 251: } 252: 253: /** 254: * Removes all data items from the dataset and sends a 255: * {@link DatasetChangeEvent} to all registered listeners. 256: * 257: * @since 1.0.7 258: */ 259: public void clear() { 260: if (this.values.getRowCount() > 0) { 261: this.values.clear(); 262: fireDatasetChanged(); 263: } 264: } 265: 266: /** 267: * Returns the time period for the specified item. Bear in mind that all 268: * series share the same set of time periods. 269: * 270: * @param item the item index (0 <= i <= {@link #getItemCount()}). 271: * 272: * @return The time period. 273: */ 274: public TimePeriod getTimePeriod(int item) { 275: return (TimePeriod) this.values.getRowKey(item); 276: } 277: 278: /** 279: * Returns the number of items in ALL series. 280: * 281: * @return The item count. 282: */ 283: public int getItemCount() { 284: return this.values.getRowCount(); 285: } 286: 287: /** 288: * Returns the number of items in a series. This is the same value 289: * that is returned by {@link #getItemCount()} since all series 290: * share the same x-values (time periods). 291: * 292: * @param series the series (zero-based index, ignored). 293: * 294: * @return The number of items within the series. 295: */ 296: public int getItemCount(int series) { 297: return getItemCount(); 298: } 299: 300: /** 301: * Returns the number of series in the dataset. 302: * 303: * @return The series count. 304: */ 305: public int getSeriesCount() { 306: return this.values.getColumnCount(); 307: } 308: 309: /** 310: * Returns the key for a series. 311: * 312: * @param series the series (zero-based index). 313: * 314: * @return The key for the series. 315: */ 316: public Comparable getSeriesKey(int series) { 317: return this.values.getColumnKey(series); 318: } 319: 320: /** 321: * Returns the x-value for an item within a series. The x-values may or 322: * may not be returned in ascending order, that is up to the class 323: * implementing the interface. 324: * 325: * @param series the series (zero-based index). 326: * @param item the item (zero-based index). 327: * 328: * @return The x-value. 329: */ 330: public Number getX(int series, int item) { 331: return new Double(getXValue(series, item)); 332: } 333: 334: /** 335: * Returns the x-value (as a double primitive) for an item within a series. 336: * 337: * @param series the series index (zero-based). 338: * @param item the item index (zero-based). 339: * 340: * @return The value. 341: */ 342: public double getXValue(int series, int item) { 343: TimePeriod period = (TimePeriod) this.values.getRowKey(item); 344: return getXValue(period); 345: } 346: 347: /** 348: * Returns the starting X value for the specified series and item. 349: * 350: * @param series the series (zero-based index). 351: * @param item the item within a series (zero-based index). 352: * 353: * @return The starting X value for the specified series and item. 354: */ 355: public Number getStartX(int series, int item) { 356: return new Double(getStartXValue(series, item)); 357: } 358: 359: /** 360: * Returns the start x-value (as a double primitive) for an item within 361: * a series. 362: * 363: * @param series the series index (zero-based). 364: * @param item the item index (zero-based). 365: * 366: * @return The value. 367: */ 368: public double getStartXValue(int series, int item) { 369: TimePeriod period = (TimePeriod) this.values.getRowKey(item); 370: return period.getStart().getTime(); 371: } 372: 373: /** 374: * Returns the ending X value for the specified series and item. 375: * 376: * @param series the series (zero-based index). 377: * @param item the item within a series (zero-based index). 378: * 379: * @return The ending X value for the specified series and item. 380: */ 381: public Number getEndX(int series, int item) { 382: return new Double(getEndXValue(series, item)); 383: } 384: 385: /** 386: * Returns the end x-value (as a double primitive) for an item within 387: * a series. 388: * 389: * @param series the series index (zero-based). 390: * @param item the item index (zero-based). 391: * 392: * @return The value. 393: */ 394: public double getEndXValue(int series, int item) { 395: TimePeriod period = (TimePeriod) this.values.getRowKey(item); 396: return period.getEnd().getTime(); 397: } 398: 399: /** 400: * Returns the y-value for an item within a series. 401: * 402: * @param series the series (zero-based index). 403: * @param item the item (zero-based index). 404: * 405: * @return The y-value (possibly <code>null</code>). 406: */ 407: public Number getY(int series, int item) { 408: return this.values.getValue(item, series); 409: } 410: 411: /** 412: * Returns the starting Y value for the specified series and item. 413: * 414: * @param series the series (zero-based index). 415: * @param item the item within a series (zero-based index). 416: * 417: * @return The starting Y value for the specified series and item. 418: */ 419: public Number getStartY(int series, int item) { 420: return getY(series, item); 421: } 422: 423: /** 424: * Returns the ending Y value for the specified series and item. 425: * 426: * @param series the series (zero-based index). 427: * @param item the item within a series (zero-based index). 428: * 429: * @return The ending Y value for the specified series and item. 430: */ 431: public Number getEndY(int series, int item) { 432: return getY(series, item); 433: } 434: 435: /** 436: * Returns the x-value for a time period. 437: * 438: * @param period the time period. 439: * 440: * @return The x-value. 441: */ 442: private long getXValue(TimePeriod period) { 443: long result = 0L; 444: if (this.xPosition == TimePeriodAnchor.START) { 445: result = period.getStart().getTime(); 446: } 447: else if (this.xPosition == TimePeriodAnchor.MIDDLE) { 448: long t0 = period.getStart().getTime(); 449: long t1 = period.getEnd().getTime(); 450: result = t0 + (t1 - t0) / 2L; 451: } 452: else if (this.xPosition == TimePeriodAnchor.END) { 453: result = period.getEnd().getTime(); 454: } 455: return result; 456: } 457: 458: /** 459: * Returns the minimum x-value in the dataset. 460: * 461: * @param includeInterval a flag that determines whether or not the 462: * x-interval is taken into account. 463: * 464: * @return The minimum value. 465: */ 466: public double getDomainLowerBound(boolean includeInterval) { 467: double result = Double.NaN; 468: Range r = getDomainBounds(includeInterval); 469: if (r != null) { 470: result = r.getLowerBound(); 471: } 472: return result; 473: } 474: 475: /** 476: * Returns the maximum x-value in the dataset. 477: * 478: * @param includeInterval a flag that determines whether or not the 479: * x-interval is taken into account. 480: * 481: * @return The maximum value. 482: */ 483: public double getDomainUpperBound(boolean includeInterval) { 484: double result = Double.NaN; 485: Range r = getDomainBounds(includeInterval); 486: if (r != null) { 487: result = r.getUpperBound(); 488: } 489: return result; 490: } 491: 492: /** 493: * Returns the range of the values in this dataset's domain. 494: * 495: * @param includeInterval a flag that controls whether or not the 496: * x-intervals are taken into account. 497: * 498: * @return The range. 499: */ 500: public Range getDomainBounds(boolean includeInterval) { 501: List keys = this.values.getRowKeys(); 502: if (keys.isEmpty()) { 503: return null; 504: } 505: 506: TimePeriod first = (TimePeriod) keys.get(0); 507: TimePeriod last = (TimePeriod) keys.get(keys.size() - 1); 508: 509: if (!includeInterval || this.domainIsPointsInTime) { 510: return new Range(getXValue(first), getXValue(last)); 511: } 512: else { 513: return new Range(first.getStart().getTime(), 514: last.getEnd().getTime()); 515: } 516: } 517: 518: /** 519: * Tests this dataset for equality with an arbitrary object. 520: * 521: * @param obj the object (<code>null</code> permitted). 522: * 523: * @return A boolean. 524: */ 525: public boolean equals(Object obj) { 526: if (obj == this) { 527: return true; 528: } 529: if (!(obj instanceof TimeTableXYDataset)) { 530: return false; 531: } 532: TimeTableXYDataset that = (TimeTableXYDataset) obj; 533: if (this.domainIsPointsInTime != that.domainIsPointsInTime) { 534: return false; 535: } 536: if (this.xPosition != that.xPosition) { 537: return false; 538: } 539: if (!this.workingCalendar.getTimeZone().equals( 540: that.workingCalendar.getTimeZone()) 541: ) { 542: return false; 543: } 544: if (!this.values.equals(that.values)) { 545: return false; 546: } 547: return true; 548: } 549: 550: /** 551: * Returns a clone of this dataset. 552: * 553: * @return A clone. 554: * 555: * @throws CloneNotSupportedException if the dataset cannot be cloned. 556: */ 557: public Object clone() throws CloneNotSupportedException { 558: TimeTableXYDataset clone = (TimeTableXYDataset) super.clone(); 559: clone.values = (DefaultKeyedValues2D) this.values.clone(); 560: clone.workingCalendar = (Calendar) this.workingCalendar.clone(); 561: return clone; 562: } 563: 564: }