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 * TimeTableXYDataset.java 029 * ----------------------- 030 * (C) Copyright 2004, 2005, 2007, by Andreas Schroeder and Contributors. 031 * 032 * Original Author: Andreas Schroeder; 033 * Contributor(s): David Gilbert (for Object Refinery Limited); 034 * Rob Eden; 035 * 036 * Changes 037 * ------- 038 * 01-Apr-2004 : Version 1 (AS); 039 * 05-May-2004 : Now implements AbstractIntervalXYDataset (DG); 040 * 15-Jul-2004 : Switched getX() with getXValue() and getY() with 041 * getYValue() (DG); 042 * 15-Sep-2004 : Added getXPosition(), setXPosition(), equals() and 043 * clone() (DG); 044 * 17-Nov-2004 : Updated methods for changes in DomainInfo interface (DG); 045 * 25-Nov-2004 : Added getTimePeriod(int) method (DG); 046 * 11-Jan-2005 : Removed deprecated code in preparation for the 1.0.0 047 * release (DG); 048 * 27-Jan-2005 : Modified to use TimePeriod rather than RegularTimePeriod (DG); 049 * 02-Feb-2007 : Removed author tags all over JFreeChart sources (DG); 050 * 25-Jul-2007 : Added clear() method by Rob Eden, see patch 1752205 (DG); 051 * 052 */ 053 054 package org.jfree.data.time; 055 056 import java.util.Calendar; 057 import java.util.List; 058 import java.util.Locale; 059 import java.util.TimeZone; 060 061 import org.jfree.data.DefaultKeyedValues2D; 062 import org.jfree.data.DomainInfo; 063 import org.jfree.data.Range; 064 import org.jfree.data.general.DatasetChangeEvent; 065 import org.jfree.data.xy.AbstractIntervalXYDataset; 066 import org.jfree.data.xy.IntervalXYDataset; 067 import org.jfree.data.xy.TableXYDataset; 068 import org.jfree.util.PublicCloneable; 069 070 /** 071 * A dataset for regular time periods that implements the 072 * {@link TableXYDataset} interface. 073 * 074 * @see org.jfree.data.xy.TableXYDataset 075 */ 076 public class TimeTableXYDataset extends AbstractIntervalXYDataset 077 implements Cloneable, PublicCloneable, 078 IntervalXYDataset, 079 DomainInfo, 080 TableXYDataset { 081 082 /** 083 * The data structure to store the values. Each column represents 084 * a series (elsewhere in JFreeChart rows are typically used for series, 085 * but it doesn't matter that much since this data structure is private 086 * and symmetrical anyway), each row contains values for the same 087 * {@link RegularTimePeriod} (the rows are sorted into ascending order). 088 */ 089 private DefaultKeyedValues2D values; 090 091 /** 092 * A flag that indicates that the domain is 'points in time'. If this flag 093 * is true, only the x-value (and not the x-interval) is used to determine 094 * the range of values in the domain. 095 */ 096 private boolean domainIsPointsInTime; 097 098 /** 099 * 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 }