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 * TimeTableXYDataset.java 029 * ----------------------- 030 * (C) Copyright 2004, 2005, by Andreas Schroeder and Contributors. 031 * 032 * Original Author: Andreas Schroeder; 033 * Contributor(s): David Gilbert (for Object Refinery Limited); 034 * 035 * $Id: TimeTableXYDataset.java,v 1.10.2.1 2005/10/25 21:35:24 mungady Exp $ 036 * 037 * Changes 038 * ------- 039 * 01-Apr-2004 : Version 1 (AS); 040 * 05-May-2004 : Now implements AbstractIntervalXYDataset (DG); 041 * 15-Jul-2004 : Switched getX() with getXValue() and getY() with 042 * getYValue() (DG); 043 * 15-Sep-2004 : Added getXPosition(), setXPosition(), equals() and 044 * clone() (DG); 045 * 17-Nov-2004 : Updated methods for changes in DomainInfo interface (DG); 046 * 25-Nov-2004 : Added getTimePeriod(int) method (DG); 047 * 11-Jan-2005 : Removed deprecated code in preparation for the 1.0.0 048 * release (DG); 049 * 27-Jan-2005 : Modified to use TimePeriod rather than RegularTimePeriod (DG); 050 * 051 */ 052 053 package org.jfree.data.time; 054 055 import java.util.Calendar; 056 import java.util.List; 057 import java.util.Locale; 058 import java.util.TimeZone; 059 060 import org.jfree.data.DefaultKeyedValues2D; 061 import org.jfree.data.DomainInfo; 062 import org.jfree.data.Range; 063 import org.jfree.data.general.DatasetChangeEvent; 064 import org.jfree.data.xy.AbstractIntervalXYDataset; 065 import org.jfree.data.xy.IntervalXYDataset; 066 import org.jfree.data.xy.TableXYDataset; 067 import org.jfree.util.PublicCloneable; 068 069 /** 070 * A dataset for regular time periods that implements the 071 * {@link TableXYDataset} interface. 072 * 073 * @see org.jfree.data.xy.TableXYDataset 074 * @author andreas.schroeder 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 * Returns the time period for the specified item. Bear in mind that all 255 * series share the same set of time periods. 256 * 257 * @param item the item index (0 <= i <= {@link #getItemCount()}). 258 * 259 * @return The time period. 260 */ 261 public TimePeriod getTimePeriod(int item) { 262 return (TimePeriod) this.values.getRowKey(item); 263 } 264 265 /** 266 * Returns the number of items in ALL series. 267 * 268 * @return The item count. 269 */ 270 public int getItemCount() { 271 return this.values.getRowCount(); 272 } 273 274 /** 275 * Returns the number of items in a series. This is the same value 276 * that is returned by {@link #getItemCount()} since all series 277 * share the same x-values (time periods). 278 * 279 * @param series the series (zero-based index, ignored). 280 * 281 * @return The number of items within the series. 282 */ 283 public int getItemCount(int series) { 284 return getItemCount(); 285 } 286 287 /** 288 * Returns the number of series in the dataset. 289 * 290 * @return The series count. 291 */ 292 public int getSeriesCount() { 293 return this.values.getColumnCount(); 294 } 295 296 /** 297 * Returns the key for a series. 298 * 299 * @param series the series (zero-based index). 300 * 301 * @return The key for the series. 302 */ 303 public Comparable getSeriesKey(int series) { 304 return this.values.getColumnKey(series); 305 } 306 307 /** 308 * Returns the x-value for an item within a series. The x-values may or 309 * may not be returned in ascending order, that is up to the class 310 * implementing the interface. 311 * 312 * @param series the series (zero-based index). 313 * @param item the item (zero-based index). 314 * 315 * @return The x-value. 316 */ 317 public Number getX(int series, int item) { 318 return new Double(getXValue(series, item)); 319 } 320 321 /** 322 * Returns the x-value (as a double primitive) for an item within a series. 323 * 324 * @param series the series index (zero-based). 325 * @param item the item index (zero-based). 326 * 327 * @return The value. 328 */ 329 public double getXValue(int series, int item) { 330 TimePeriod period = (TimePeriod) this.values.getRowKey(item); 331 return getXValue(period); 332 } 333 334 /** 335 * Returns the starting X value for the specified series and item. 336 * 337 * @param series the series (zero-based index). 338 * @param item the item within a series (zero-based index). 339 * 340 * @return The starting X value for the specified series and item. 341 */ 342 public Number getStartX(int series, int item) { 343 return new Double(getStartXValue(series, item)); 344 } 345 346 /** 347 * Returns the start x-value (as a double primitive) for an item within 348 * a series. 349 * 350 * @param series the series index (zero-based). 351 * @param item the item index (zero-based). 352 * 353 * @return The value. 354 */ 355 public double getStartXValue(int series, int item) { 356 TimePeriod period = (TimePeriod) this.values.getRowKey(item); 357 return period.getStart().getTime(); 358 } 359 360 /** 361 * Returns the ending X value for the specified series and item. 362 * 363 * @param series the series (zero-based index). 364 * @param item the item within a series (zero-based index). 365 * 366 * @return The ending X value for the specified series and item. 367 */ 368 public Number getEndX(int series, int item) { 369 return new Double(getEndXValue(series, item)); 370 } 371 372 /** 373 * Returns the end x-value (as a double primitive) for an item within 374 * a series. 375 * 376 * @param series the series index (zero-based). 377 * @param item the item index (zero-based). 378 * 379 * @return The value. 380 */ 381 public double getEndXValue(int series, int item) { 382 TimePeriod period = (TimePeriod) this.values.getRowKey(item); 383 return period.getEnd().getTime(); 384 } 385 386 /** 387 * Returns the y-value for an item within a series. 388 * 389 * @param series the series (zero-based index). 390 * @param item the item (zero-based index). 391 * 392 * @return The y-value (possibly <code>null</code>). 393 */ 394 public Number getY(int series, int item) { 395 return this.values.getValue(item, series); 396 } 397 398 /** 399 * Returns the starting Y value for the specified series and item. 400 * 401 * @param series the series (zero-based index). 402 * @param item the item within a series (zero-based index). 403 * 404 * @return The starting Y value for the specified series and item. 405 */ 406 public Number getStartY(int series, int item) { 407 return getY(series, item); 408 } 409 410 /** 411 * Returns the ending Y value for the specified series and item. 412 * 413 * @param series the series (zero-based index). 414 * @param item the item within a series (zero-based index). 415 * 416 * @return The ending Y value for the specified series and item. 417 */ 418 public Number getEndY(int series, int item) { 419 return getY(series, item); 420 } 421 422 /** 423 * Returns the x-value for a time period. 424 * 425 * @param period the time period. 426 * 427 * @return The x-value. 428 */ 429 private long getXValue(TimePeriod period) { 430 long result = 0L; 431 if (this.xPosition == TimePeriodAnchor.START) { 432 result = period.getStart().getTime(); 433 } 434 else if (this.xPosition == TimePeriodAnchor.MIDDLE) { 435 long t0 = period.getStart().getTime(); 436 long t1 = period.getEnd().getTime(); 437 result = t0 + (t1 - t0) / 2L; 438 } 439 else if (this.xPosition == TimePeriodAnchor.END) { 440 result = period.getEnd().getTime(); 441 } 442 return result; 443 } 444 445 /** 446 * Returns the minimum x-value in the dataset. 447 * 448 * @param includeInterval a flag that determines whether or not the 449 * x-interval is taken into account. 450 * 451 * @return The minimum value. 452 */ 453 public double getDomainLowerBound(boolean includeInterval) { 454 double result = Double.NaN; 455 Range r = getDomainBounds(includeInterval); 456 if (r != null) { 457 result = r.getLowerBound(); 458 } 459 return result; 460 } 461 462 /** 463 * Returns the maximum x-value in the dataset. 464 * 465 * @param includeInterval a flag that determines whether or not the 466 * x-interval is taken into account. 467 * 468 * @return The maximum value. 469 */ 470 public double getDomainUpperBound(boolean includeInterval) { 471 double result = Double.NaN; 472 Range r = getDomainBounds(includeInterval); 473 if (r != null) { 474 result = r.getUpperBound(); 475 } 476 return result; 477 } 478 479 /** 480 * Returns the range of the values in this dataset's domain. 481 * 482 * @param includeInterval a flag that controls whether or not the 483 * x-intervals are taken into account. 484 * 485 * @return The range. 486 */ 487 public Range getDomainBounds(boolean includeInterval) { 488 List keys = this.values.getRowKeys(); 489 if (keys.isEmpty()) { 490 return null; 491 } 492 493 TimePeriod first = (TimePeriod) keys.get(0); 494 TimePeriod last = (TimePeriod) keys.get(keys.size() - 1); 495 496 if (!includeInterval || this.domainIsPointsInTime) { 497 return new Range(getXValue(first), getXValue(last)); 498 } 499 else { 500 return new Range( 501 first.getStart().getTime(), last.getEnd().getTime() 502 ); 503 } 504 } 505 506 /** 507 * Tests this dataset for equality with an arbitrary object. 508 * 509 * @param obj the object (<code>null</code> permitted). 510 * 511 * @return A boolean. 512 */ 513 public boolean equals(Object obj) { 514 if (obj == this) { 515 return true; 516 } 517 if (!(obj instanceof TimeTableXYDataset)) { 518 return false; 519 } 520 TimeTableXYDataset that = (TimeTableXYDataset) obj; 521 if (this.domainIsPointsInTime != that.domainIsPointsInTime) { 522 return false; 523 } 524 if (this.xPosition != that.xPosition) { 525 return false; 526 } 527 if (!this.workingCalendar.getTimeZone().equals( 528 that.workingCalendar.getTimeZone()) 529 ) { 530 return false; 531 } 532 if (!this.values.equals(that.values)) { 533 return false; 534 } 535 return true; 536 } 537 538 /** 539 * Returns a clone of this dataset. 540 * 541 * @return A clone. 542 * 543 * @throws CloneNotSupportedException if the dataset cannot be cloned. 544 */ 545 public Object clone() throws CloneNotSupportedException { 546 TimeTableXYDataset clone = (TimeTableXYDataset) super.clone(); 547 clone.values = (DefaultKeyedValues2D) this.values.clone(); 548 clone.workingCalendar = (Calendar) this.workingCalendar.clone(); 549 return clone; 550 } 551 552 }