001/* =========================================================== 002 * JFreeChart : a free chart library for the Java(tm) platform 003 * =========================================================== 004 * 005 * (C) Copyright 2000-2020, 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 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 025 * Other names may be trademarks of their respective owners.] 026 * 027 * --------------- 028 * TimeSeries.java 029 * --------------- 030 * (C) Copyright 2001-2015, by Object Refinery Limited. 031 * 032 * Original Author: David Gilbert (for Object Refinery Limited); 033 * Contributor(s): Bryan Scott; 034 * Nick Guenther; 035 * 036 * Changes 037 * ------- 038 * 11-Oct-2001 : Version 1 (DG); 039 * 14-Nov-2001 : Added listener mechanism (DG); 040 * 15-Nov-2001 : Updated argument checking and exceptions in add() method (DG); 041 * 29-Nov-2001 : Added properties to describe the domain and range (DG); 042 * 07-Dec-2001 : Renamed TimeSeries --> BasicTimeSeries (DG); 043 * 01-Mar-2002 : Updated import statements (DG); 044 * 28-Mar-2002 : Added a method add(TimePeriod, double) (DG); 045 * 27-Aug-2002 : Changed return type of delete method to void (DG); 046 * 04-Oct-2002 : Added itemCount and historyCount attributes, fixed errors 047 * reported by Checkstyle (DG); 048 * 29-Oct-2002 : Added series change notification to addOrUpdate() method (DG); 049 * 28-Jan-2003 : Changed name back to TimeSeries (DG); 050 * 13-Mar-2003 : Moved to com.jrefinery.data.time package and implemented 051 * Serializable (DG); 052 * 01-May-2003 : Updated equals() method (see bug report 727575) (DG); 053 * 14-Aug-2003 : Added ageHistoryCountItems method (copied existing code for 054 * contents) made a method and added to addOrUpdate. Made a 055 * public method to enable ageing against a specified time 056 * (eg now) as opposed to lastest time in series (BS); 057 * 15-Oct-2003 : Added fix for setItemCount method - see bug report 804425. 058 * Modified exception message in add() method to be more 059 * informative (DG); 060 * 13-Apr-2004 : Added clear() method (DG); 061 * 21-May-2004 : Added an extra addOrUpdate() method (DG); 062 * 15-Jun-2004 : Fixed NullPointerException in equals() method (DG); 063 * 29-Nov-2004 : Fixed bug 1075255 (DG); 064 * 17-Nov-2005 : Renamed historyCount --> maximumItemAge (DG); 065 * 28-Nov-2005 : Changed maximumItemAge from int to long (DG); 066 * 01-Dec-2005 : New add methods accept notify flag (DG); 067 * ------------- JFREECHART 1.0.x --------------------------------------------- 068 * 24-May-2006 : Improved error handling in createCopy() methods (DG); 069 * 01-Sep-2006 : Fixed bugs in removeAgedItems() methods - see bug report 070 * 1550045 (DG); 071 * 22-Mar-2007 : Simplified getDataItem(RegularTimePeriod) - see patch 1685500 072 * by Nick Guenther (DG); 073 * 31-Oct-2007 : Implemented faster hashCode() (DG); 074 * 21-Nov-2007 : Fixed clone() method (bug 1832432) (DG); 075 * 10-Jan-2008 : Fixed createCopy(RegularTimePeriod, RegularTimePeriod) (bug 076 * 1864222) (DG); 077 * 13-Jan-2009 : Fixed constructors so that timePeriodClass doesn't need to 078 * be specified in advance (DG); 079 * 26-May-2009 : Added cache for minY and maxY values (DG); 080 * 09-Jun-2009 : Ensure that TimeSeriesDataItem objects used in underlying 081 * storage are cloned to keep series isolated from external 082 * changes (DG); 083 * 10-Jun-2009 : Added addOrUpdate(TimeSeriesDataItem) method (DG); 084 * 31-Aug-2009 : Clear minY and maxY cache values in createCopy (DG); 085 * 03-Dec-2011 : Fixed bug 3446965 which affects the y-range calculation for 086 * the series (DG); 087 * 02-Jul-2013 : Use ParamChecks (DG); 088 * 06-Sep-2015 : Fix bug with Double.NaN values and findRangeBounds() (DG); 089 * 090 */ 091 092package org.jfree.data.time; 093 094import java.io.Serializable; 095import java.lang.reflect.InvocationTargetException; 096import java.lang.reflect.Method; 097import java.util.Calendar; 098import java.util.Collection; 099import java.util.Collections; 100import java.util.Date; 101import java.util.Iterator; 102import java.util.List; 103import java.util.Locale; 104import java.util.TimeZone; 105import org.jfree.chart.util.ObjectUtils; 106 107import org.jfree.chart.util.Args; 108import org.jfree.data.Range; 109import org.jfree.data.general.Series; 110import org.jfree.data.general.SeriesChangeEvent; 111import org.jfree.data.general.SeriesException; 112 113/** 114 * Represents a sequence of zero or more data items in the form (period, value) 115 * where 'period' is some instance of a subclass of {@link RegularTimePeriod}. 116 * The time series will ensure that (a) all data items have the same type of 117 * period (for example, {@link Day}) and (b) that each period appears at 118 * most one time in the series. 119 */ 120public class TimeSeries extends Series implements Cloneable, Serializable { 121 122 /** For serialization. */ 123 private static final long serialVersionUID = -5032960206869675528L; 124 125 /** Default value for the domain description. */ 126 protected static final String DEFAULT_DOMAIN_DESCRIPTION = "Time"; 127 128 /** Default value for the range description. */ 129 protected static final String DEFAULT_RANGE_DESCRIPTION = "Value"; 130 131 /** A description of the domain. */ 132 private String domain; 133 134 /** A description of the range. */ 135 private String range; 136 137 /** The type of period for the data. */ 138 protected Class timePeriodClass; 139 140 /** The list of data items in the series. */ 141 protected List data; 142 143 /** The maximum number of items for the series. */ 144 private int maximumItemCount; 145 146 /** 147 * The maximum age of items for the series, specified as a number of 148 * time periods. 149 */ 150 private long maximumItemAge; 151 152 /** 153 * The minimum y-value in the series. 154 * 155 * @since 1.0.14 156 */ 157 private double minY; 158 159 /** 160 * The maximum y-value in the series. 161 * 162 * @since 1.0.14 163 */ 164 private double maxY; 165 166 /** 167 * Creates a new (empty) time series. By default, a daily time series is 168 * created. Use one of the other constructors if you require a different 169 * time period. 170 * 171 * @param name the series name ({@code null} not permitted). 172 */ 173 public TimeSeries(Comparable name) { 174 this(name, DEFAULT_DOMAIN_DESCRIPTION, DEFAULT_RANGE_DESCRIPTION); 175 } 176 177 /** 178 * Creates a new time series that contains no data. 179 * <P> 180 * Descriptions can be specified for the domain and range. One situation 181 * where this is helpful is when generating a chart for the time series - 182 * axis labels can be taken from the domain and range description. 183 * 184 * @param name the name of the series ({@code null} not permitted). 185 * @param domain the domain description ({@code null} permitted). 186 * @param range the range description ({@code null} permitted). 187 * 188 * @since 1.0.13 189 */ 190 public TimeSeries(Comparable name, String domain, String range) { 191 super(name); 192 this.domain = domain; 193 this.range = range; 194 this.timePeriodClass = null; 195 this.data = new java.util.ArrayList(); 196 this.maximumItemCount = Integer.MAX_VALUE; 197 this.maximumItemAge = Long.MAX_VALUE; 198 this.minY = Double.NaN; 199 this.maxY = Double.NaN; 200 } 201 202 /** 203 * Returns the domain description. 204 * 205 * @return The domain description (possibly {@code null}). 206 * 207 * @see #setDomainDescription(String) 208 */ 209 public String getDomainDescription() { 210 return this.domain; 211 } 212 213 /** 214 * Sets the domain description and sends a {@code PropertyChangeEvent} 215 * (with the property name {@code Domain}) to all registered 216 * property change listeners. 217 * 218 * @param description the description ({@code null} permitted). 219 * 220 * @see #getDomainDescription() 221 */ 222 public void setDomainDescription(String description) { 223 String old = this.domain; 224 this.domain = description; 225 firePropertyChange("Domain", old, description); 226 } 227 228 /** 229 * Returns the range description. 230 * 231 * @return The range description (possibly {@code null}). 232 * 233 * @see #setRangeDescription(String) 234 */ 235 public String getRangeDescription() { 236 return this.range; 237 } 238 239 /** 240 * Sets the range description and sends a {@code PropertyChangeEvent} 241 * (with the property name {@code Range}) to all registered listeners. 242 * 243 * @param description the description ({@code null} permitted). 244 * 245 * @see #getRangeDescription() 246 */ 247 public void setRangeDescription(String description) { 248 String old = this.range; 249 this.range = description; 250 firePropertyChange("Range", old, description); 251 } 252 253 /** 254 * Returns the number of items in the series. 255 * 256 * @return The item count. 257 */ 258 @Override 259 public int getItemCount() { 260 return this.data.size(); 261 } 262 263 /** 264 * Returns the list of data items for the series (the list contains 265 * {@link TimeSeriesDataItem} objects and is unmodifiable). 266 * 267 * @return The list of data items. 268 */ 269 public List getItems() { 270 // FIXME: perhaps we should clone the data list 271 return Collections.unmodifiableList(this.data); 272 } 273 274 /** 275 * Returns the maximum number of items that will be retained in the series. 276 * The default value is {@code Integer.MAX_VALUE}. 277 * 278 * @return The maximum item count. 279 * 280 * @see #setMaximumItemCount(int) 281 */ 282 public int getMaximumItemCount() { 283 return this.maximumItemCount; 284 } 285 286 /** 287 * Sets the maximum number of items that will be retained in the series. 288 * If you add a new item to the series such that the number of items will 289 * exceed the maximum item count, then the FIRST element in the series is 290 * automatically removed, ensuring that the maximum item count is not 291 * exceeded. 292 * 293 * @param maximum the maximum (requires >= 0). 294 * 295 * @see #getMaximumItemCount() 296 */ 297 public void setMaximumItemCount(int maximum) { 298 if (maximum < 0) { 299 throw new IllegalArgumentException("Negative 'maximum' argument."); 300 } 301 this.maximumItemCount = maximum; 302 int count = this.data.size(); 303 if (count > maximum) { 304 delete(0, count - maximum - 1); 305 } 306 } 307 308 /** 309 * Returns the maximum item age (in time periods) for the series. 310 * 311 * @return The maximum item age. 312 * 313 * @see #setMaximumItemAge(long) 314 */ 315 public long getMaximumItemAge() { 316 return this.maximumItemAge; 317 } 318 319 /** 320 * Sets the number of time units in the 'history' for the series. This 321 * provides one mechanism for automatically dropping old data from the 322 * time series. For example, if a series contains daily data, you might set 323 * the history count to 30. Then, when you add a new data item, all data 324 * items more than 30 days older than the latest value are automatically 325 * dropped from the series. 326 * 327 * @param periods the number of time periods. 328 * 329 * @see #getMaximumItemAge() 330 */ 331 public void setMaximumItemAge(long periods) { 332 if (periods < 0) { 333 throw new IllegalArgumentException("Negative 'periods' argument."); 334 } 335 this.maximumItemAge = periods; 336 removeAgedItems(true); // remove old items and notify if necessary 337 } 338 339 /** 340 * Returns the range of y-values in the time series. Any {@code null} or 341 * {@code Double.NaN} data values in the series will be ignored (except for 342 * the special case where all data values are {@code null}, in which case 343 * the return value is {@code Range(Double.NaN, Double.NaN)}). If the time 344 * series contains no items, this method will return {@code null}. 345 * 346 * @return The range of y-values in the time series (possibly {@code null}). 347 * 348 * @since 1.0.18 349 */ 350 public Range findValueRange() { 351 if (this.data.isEmpty()) { 352 return null; 353 } 354 return new Range(this.minY, this.maxY); 355 } 356 357 /** 358 * Returns the range of y-values in the time series that fall within 359 * the specified range of x-values. This is equivalent to 360 * {@code findValueRange(xRange, TimePeriodAnchor.MIDDLE, timeZone)}. 361 * 362 * @param xRange the subrange of x-values ({@code null} not permitted). 363 * @param timeZone the time zone used to convert x-values to time periods 364 * ({@code null} not permitted). 365 * 366 * @return The range. 367 * 368 * @since 1.0.18 369 */ 370 public Range findValueRange(Range xRange, TimeZone timeZone) { 371 return findValueRange(xRange, TimePeriodAnchor.MIDDLE, timeZone); 372 } 373 374 /** 375 * Finds the range of y-values that fall within the specified range of 376 * x-values (where the x-values are interpreted as milliseconds since the 377 * epoch and converted to time periods using the specified timezone). 378 * 379 * @param xRange the subset of x-values to use ({@code null} not 380 * permitted). 381 * @param xAnchor the anchor point for the x-values ({@code null} 382 * not permitted). 383 * @param zone the time zone ({@code null} not permitted). 384 * 385 * @return The range of y-values. 386 * 387 * @since 1.0.18 388 */ 389 public Range findValueRange(Range xRange, TimePeriodAnchor xAnchor, 390 TimeZone zone) { 391 Args.nullNotPermitted(xRange, "xRange"); 392 Args.nullNotPermitted(xAnchor, "xAnchor"); 393 Args.nullNotPermitted(zone, "zone"); 394 if (this.data.isEmpty()) { 395 return null; 396 } 397 Calendar calendar = Calendar.getInstance(zone); 398 // since the items are ordered, we could be more clever here and avoid 399 // iterating over all the data 400 double lowY = Double.POSITIVE_INFINITY; 401 double highY = Double.NEGATIVE_INFINITY; 402 for (int i = 0; i < this.data.size(); i++) { 403 TimeSeriesDataItem item = (TimeSeriesDataItem) this.data.get(i); 404 long millis = item.getPeriod().getMillisecond(xAnchor, calendar); 405 if (xRange.contains(millis)) { 406 Number n = item.getValue(); 407 if (n != null) { 408 double v = n.doubleValue(); 409 lowY = minIgnoreNaN(lowY, v); 410 highY = maxIgnoreNaN(highY, v); 411 } 412 } 413 } 414 if (Double.isInfinite(lowY) && Double.isInfinite(highY)) { 415 if (lowY < highY) { 416 return new Range(lowY, highY); 417 } else { 418 return new Range(Double.NaN, Double.NaN); 419 } 420 } 421 return new Range(lowY, highY); 422 } 423 424 /** 425 * Returns the smallest y-value in the series, ignoring any 426 * {@code null} and {@code Double.NaN} values. This method 427 * returns {@code Double.NaN} if there is no smallest y-value (for 428 * example, when the series is empty). 429 * 430 * @return The smallest y-value. 431 * 432 * @see #getMaxY() 433 * 434 * @since 1.0.14 435 */ 436 public double getMinY() { 437 return this.minY; 438 } 439 440 /** 441 * Returns the largest y-value in the series, ignoring any 442 * {@code null} and {@code Double.NaN} values. This method 443 * returns {@code Double.NaN} if there is no largest y-value 444 * (for example, when the series is empty). 445 * 446 * @return The largest y-value. 447 * 448 * @see #getMinY() 449 * 450 * @since 1.0.14 451 */ 452 public double getMaxY() { 453 return this.maxY; 454 } 455 456 /** 457 * Returns the time period class for this series. 458 * <p> 459 * Only one time period class can be used within a single series (enforced). 460 * If you add a data item with a {@link Year} for the time period, then all 461 * subsequent data items must also have a {@link Year} for the time period. 462 * 463 * @return The time period class (may be {@code null} but only for 464 * an empty series). 465 */ 466 public Class getTimePeriodClass() { 467 return this.timePeriodClass; 468 } 469 470 /** 471 * Returns a data item from the dataset. Note that the returned object 472 * is a clone of the item in the series, so modifying it will have no 473 * effect on the data series. 474 * 475 * @param index the item index. 476 * 477 * @return The data item. 478 */ 479 public TimeSeriesDataItem getDataItem(int index) { 480 TimeSeriesDataItem item = (TimeSeriesDataItem) this.data.get(index); 481 return (TimeSeriesDataItem) item.clone(); 482 } 483 484 /** 485 * Returns the data item for a specific period. Note that the returned 486 * object is a clone of the item in the series, so modifying it will have 487 * no effect on the data series. 488 * 489 * @param period the period of interest ({@code null} not allowed). 490 * 491 * @return The data item matching the specified period (or 492 * {@code null} if there is no match). 493 * 494 * @see #getDataItem(int) 495 */ 496 public TimeSeriesDataItem getDataItem(RegularTimePeriod period) { 497 int index = getIndex(period); 498 if (index >= 0) { 499 return getDataItem(index); 500 } 501 return null; 502 } 503 504 /** 505 * Returns a data item for the series. This method returns the object 506 * that is used for the underlying storage - you should not modify the 507 * contents of the returned value unless you know what you are doing. 508 * 509 * @param index the item index (zero-based). 510 * 511 * @return The data item. 512 * 513 * @see #getDataItem(int) 514 * 515 * @since 1.0.14 516 */ 517 TimeSeriesDataItem getRawDataItem(int index) { 518 return (TimeSeriesDataItem) this.data.get(index); 519 } 520 521 /** 522 * Returns a data item for the series. This method returns the object 523 * that is used for the underlying storage - you should not modify the 524 * contents of the returned value unless you know what you are doing. 525 * 526 * @param period the item index (zero-based). 527 * 528 * @return The data item. 529 * 530 * @see #getDataItem(RegularTimePeriod) 531 * 532 * @since 1.0.14 533 */ 534 TimeSeriesDataItem getRawDataItem(RegularTimePeriod period) { 535 int index = getIndex(period); 536 if (index >= 0) { 537 return (TimeSeriesDataItem) this.data.get(index); 538 } 539 return null; 540 } 541 542 /** 543 * Returns the time period at the specified index. 544 * 545 * @param index the index of the data item. 546 * 547 * @return The time period. 548 */ 549 public RegularTimePeriod getTimePeriod(int index) { 550 return getRawDataItem(index).getPeriod(); 551 } 552 553 /** 554 * Returns a time period that would be the next in sequence on the end of 555 * the time series. 556 * 557 * @return The next time period. 558 */ 559 public RegularTimePeriod getNextTimePeriod() { 560 RegularTimePeriod last = getTimePeriod(getItemCount() - 1); 561 return last.next(); 562 } 563 564 /** 565 * Returns a collection of all the time periods in the time series. 566 * 567 * @return A collection of all the time periods. 568 */ 569 public Collection getTimePeriods() { 570 Collection result = new java.util.ArrayList(); 571 for (int i = 0; i < getItemCount(); i++) { 572 result.add(getTimePeriod(i)); 573 } 574 return result; 575 } 576 577 /** 578 * Returns a collection of time periods in the specified series, but not in 579 * this series, and therefore unique to the specified series. 580 * 581 * @param series the series to check against this one. 582 * 583 * @return The unique time periods. 584 */ 585 public Collection getTimePeriodsUniqueToOtherSeries(TimeSeries series) { 586 Collection result = new java.util.ArrayList(); 587 for (int i = 0; i < series.getItemCount(); i++) { 588 RegularTimePeriod period = series.getTimePeriod(i); 589 int index = getIndex(period); 590 if (index < 0) { 591 result.add(period); 592 } 593 } 594 return result; 595 } 596 597 /** 598 * Returns the index for the item (if any) that corresponds to a time 599 * period. 600 * 601 * @param period the time period ({@code null} not permitted). 602 * 603 * @return The index. 604 */ 605 public int getIndex(RegularTimePeriod period) { 606 Args.nullNotPermitted(period, "period"); 607 TimeSeriesDataItem dummy = new TimeSeriesDataItem( 608 period, Integer.MIN_VALUE); 609 return Collections.binarySearch(this.data, dummy); 610 } 611 612 /** 613 * Returns the value at the specified index. 614 * 615 * @param index index of a value. 616 * 617 * @return The value (possibly {@code null}). 618 */ 619 public Number getValue(int index) { 620 return getRawDataItem(index).getValue(); 621 } 622 623 /** 624 * Returns the value for a time period. If there is no data item with the 625 * specified period, this method will return {@code null}. 626 * 627 * @param period time period ({@code null} not permitted). 628 * 629 * @return The value (possibly {@code null}). 630 */ 631 public Number getValue(RegularTimePeriod period) { 632 int index = getIndex(period); 633 if (index >= 0) { 634 return getValue(index); 635 } 636 return null; 637 } 638 639 /** 640 * Adds a data item to the series and sends a {@link SeriesChangeEvent} to 641 * all registered listeners. 642 * 643 * @param item the (timeperiod, value) pair ({@code null} not permitted). 644 */ 645 public void add(TimeSeriesDataItem item) { 646 add(item, true); 647 } 648 649 /** 650 * Adds a data item to the series and sends a {@link SeriesChangeEvent} to 651 * all registered listeners. 652 * 653 * @param item the (timeperiod, value) pair ({@code null} not permitted). 654 * @param notify notify listeners? 655 */ 656 public void add(TimeSeriesDataItem item, boolean notify) { 657 Args.nullNotPermitted(item, "item"); 658 item = (TimeSeriesDataItem) item.clone(); 659 Class c = item.getPeriod().getClass(); 660 if (this.timePeriodClass == null) { 661 this.timePeriodClass = c; 662 } 663 else if (!this.timePeriodClass.equals(c)) { 664 StringBuilder b = new StringBuilder(); 665 b.append("You are trying to add data where the time period class "); 666 b.append("is "); 667 b.append(item.getPeriod().getClass().getName()); 668 b.append(", but the TimeSeries is expecting an instance of "); 669 b.append(this.timePeriodClass.getName()); 670 b.append("."); 671 throw new SeriesException(b.toString()); 672 } 673 674 // make the change (if it's not a duplicate time period)... 675 boolean added = false; 676 int count = getItemCount(); 677 if (count == 0) { 678 this.data.add(item); 679 added = true; 680 } 681 else { 682 RegularTimePeriod last = getTimePeriod(getItemCount() - 1); 683 if (item.getPeriod().compareTo(last) > 0) { 684 this.data.add(item); 685 added = true; 686 } 687 else { 688 int index = Collections.binarySearch(this.data, item); 689 if (index < 0) { 690 this.data.add(-index - 1, item); 691 added = true; 692 } 693 else { 694 StringBuilder b = new StringBuilder(); 695 b.append("You are attempting to add an observation for "); 696 b.append("the time period "); 697 b.append(item.getPeriod().toString()); 698 b.append(" but the series already contains an observation"); 699 b.append(" for that time period. Duplicates are not "); 700 b.append("permitted. Try using the addOrUpdate() method."); 701 throw new SeriesException(b.toString()); 702 } 703 } 704 } 705 if (added) { 706 updateBoundsForAddedItem(item); 707 // check if this addition will exceed the maximum item count... 708 if (getItemCount() > this.maximumItemCount) { 709 TimeSeriesDataItem d = (TimeSeriesDataItem) this.data.remove(0); 710 updateBoundsForRemovedItem(d); 711 } 712 713 removeAgedItems(false); // remove old items if necessary, but 714 // don't notify anyone, because that 715 // happens next anyway... 716 if (notify) { 717 fireSeriesChanged(); 718 } 719 } 720 721 } 722 723 /** 724 * Adds a new data item to the series and sends a {@link SeriesChangeEvent} 725 * to all registered listeners. 726 * 727 * @param period the time period ({@code null} not permitted). 728 * @param value the value. 729 */ 730 public void add(RegularTimePeriod period, double value) { 731 // defer argument checking... 732 add(period, value, true); 733 } 734 735 /** 736 * Adds a new data item to the series and sends a {@link SeriesChangeEvent} 737 * to all registered listeners. 738 * 739 * @param period the time period ({@code null} not permitted). 740 * @param value the value. 741 * @param notify notify listeners? 742 */ 743 public void add(RegularTimePeriod period, double value, boolean notify) { 744 // defer argument checking... 745 TimeSeriesDataItem item = new TimeSeriesDataItem(period, value); 746 add(item, notify); 747 } 748 749 /** 750 * Adds a new data item to the series and sends 751 * a {@link org.jfree.data.general.SeriesChangeEvent} to all registered 752 * listeners. 753 * 754 * @param period the time period ({@code null} not permitted). 755 * @param value the value ({@code null} permitted). 756 */ 757 public void add(RegularTimePeriod period, Number value) { 758 // defer argument checking... 759 add(period, value, true); 760 } 761 762 /** 763 * Adds a new data item to the series and sends a {@link SeriesChangeEvent} 764 * to all registered listeners. 765 * 766 * @param period the time period ({@code null} not permitted). 767 * @param value the value ({@code null} permitted). 768 * @param notify notify listeners? 769 */ 770 public void add(RegularTimePeriod period, Number value, boolean notify) { 771 // defer argument checking... 772 TimeSeriesDataItem item = new TimeSeriesDataItem(period, value); 773 add(item, notify); 774 } 775 776 /** 777 * Updates (changes) the value for a time period. Throws a 778 * {@link SeriesException} if the period does not exist. 779 * 780 * @param period the period ({@code null} not permitted). 781 * @param value the value. 782 * 783 * @since 1.0.14 784 */ 785 public void update(RegularTimePeriod period, double value) { 786 update(period, Double.valueOf(value)); 787 } 788 789 /** 790 * Updates (changes) the value for a time period. Throws a 791 * {@link SeriesException} if the period does not exist. 792 * 793 * @param period the period ({@code null} not permitted). 794 * @param value the value ({@code null} permitted). 795 */ 796 public void update(RegularTimePeriod period, Number value) { 797 TimeSeriesDataItem temp = new TimeSeriesDataItem(period, value); 798 int index = Collections.binarySearch(this.data, temp); 799 if (index < 0) { 800 throw new SeriesException("There is no existing value for the " 801 + "specified 'period'."); 802 } 803 update(index, value); 804 } 805 806 /** 807 * Updates (changes) the value of a data item. 808 * 809 * @param index the index of the data item. 810 * @param value the new value ({@code null} permitted). 811 */ 812 public void update(int index, Number value) { 813 TimeSeriesDataItem item = (TimeSeriesDataItem) this.data.get(index); 814 boolean iterate = false; 815 Number oldYN = item.getValue(); 816 if (oldYN != null) { 817 double oldY = oldYN.doubleValue(); 818 if (!Double.isNaN(oldY)) { 819 iterate = oldY <= this.minY || oldY >= this.maxY; 820 } 821 } 822 item.setValue(value); 823 if (iterate) { 824 updateMinMaxYByIteration(); 825 } 826 else if (value != null) { 827 double yy = value.doubleValue(); 828 this.minY = minIgnoreNaN(this.minY, yy); 829 this.maxY = maxIgnoreNaN(this.maxY, yy); 830 } 831 fireSeriesChanged(); 832 } 833 834 /** 835 * Adds or updates data from one series to another. Returns another series 836 * containing the values that were overwritten. 837 * 838 * @param series the series to merge with this. 839 * 840 * @return A series containing the values that were overwritten. 841 */ 842 public TimeSeries addAndOrUpdate(TimeSeries series) { 843 TimeSeries overwritten = new TimeSeries("Overwritten values from: " 844 + getKey()); 845 for (int i = 0; i < series.getItemCount(); i++) { 846 TimeSeriesDataItem item = series.getRawDataItem(i); 847 TimeSeriesDataItem oldItem = addOrUpdate(item.getPeriod(), 848 item.getValue()); 849 if (oldItem != null) { 850 overwritten.add(oldItem); 851 } 852 } 853 return overwritten; 854 } 855 856 /** 857 * Adds or updates an item in the times series and sends a 858 * {@link SeriesChangeEvent} to all registered listeners. 859 * 860 * @param period the time period to add/update ({@code null} not 861 * permitted). 862 * @param value the new value. 863 * 864 * @return A copy of the overwritten data item, or {@code null} if no 865 * item was overwritten. 866 */ 867 public TimeSeriesDataItem addOrUpdate(RegularTimePeriod period, 868 double value) { 869 return addOrUpdate(period, Double.valueOf(value)); 870 } 871 872 /** 873 * Adds or updates an item in the times series and sends a 874 * {@link SeriesChangeEvent} to all registered listeners. 875 * 876 * @param period the time period to add/update ({@code null} not 877 * permitted). 878 * @param value the new value ({@code null} permitted). 879 * 880 * @return A copy of the overwritten data item, or {@code null} if no 881 * item was overwritten. 882 */ 883 public TimeSeriesDataItem addOrUpdate(RegularTimePeriod period, 884 Number value) { 885 return addOrUpdate(new TimeSeriesDataItem(period, value)); 886 } 887 888 /** 889 * Adds or updates an item in the times series and sends a 890 * {@link SeriesChangeEvent} to all registered listeners. 891 * 892 * @param item the data item ({@code null} not permitted). 893 * 894 * @return A copy of the overwritten data item, or {@code null} if no 895 * item was overwritten. 896 * 897 * @since 1.0.14 898 */ 899 public TimeSeriesDataItem addOrUpdate(TimeSeriesDataItem item) { 900 901 Args.nullNotPermitted(item, "item"); 902 Class periodClass = item.getPeriod().getClass(); 903 if (this.timePeriodClass == null) { 904 this.timePeriodClass = periodClass; 905 } 906 else if (!this.timePeriodClass.equals(periodClass)) { 907 String msg = "You are trying to add data where the time " 908 + "period class is " + periodClass.getName() 909 + ", but the TimeSeries is expecting an instance of " 910 + this.timePeriodClass.getName() + "."; 911 throw new SeriesException(msg); 912 } 913 TimeSeriesDataItem overwritten = null; 914 int index = Collections.binarySearch(this.data, item); 915 if (index >= 0) { 916 TimeSeriesDataItem existing 917 = (TimeSeriesDataItem) this.data.get(index); 918 overwritten = (TimeSeriesDataItem) existing.clone(); 919 // figure out if we need to iterate through all the y-values 920 // to find the revised minY / maxY 921 boolean iterate = false; 922 Number oldYN = existing.getValue(); 923 double oldY = oldYN != null ? oldYN.doubleValue() : Double.NaN; 924 if (!Double.isNaN(oldY)) { 925 iterate = oldY <= this.minY || oldY >= this.maxY; 926 } 927 existing.setValue(item.getValue()); 928 if (iterate) { 929 updateMinMaxYByIteration(); 930 } 931 else if (item.getValue() != null) { 932 double yy = item.getValue().doubleValue(); 933 this.minY = minIgnoreNaN(this.minY, yy); 934 this.maxY = maxIgnoreNaN(this.maxY, yy); 935 } 936 } 937 else { 938 item = (TimeSeriesDataItem) item.clone(); 939 this.data.add(-index - 1, item); 940 updateBoundsForAddedItem(item); 941 942 // check if this addition will exceed the maximum item count... 943 if (getItemCount() > this.maximumItemCount) { 944 TimeSeriesDataItem d = (TimeSeriesDataItem) this.data.remove(0); 945 updateBoundsForRemovedItem(d); 946 } 947 } 948 removeAgedItems(false); // remove old items if necessary, but 949 // don't notify anyone, because that 950 // happens next anyway... 951 fireSeriesChanged(); 952 return overwritten; 953 954 } 955 956 /** 957 * Age items in the series. Ensure that the timespan from the youngest to 958 * the oldest record in the series does not exceed maximumItemAge time 959 * periods. Oldest items will be removed if required. 960 * 961 * @param notify controls whether or not a {@link SeriesChangeEvent} is 962 * sent to registered listeners IF any items are removed. 963 */ 964 public void removeAgedItems(boolean notify) { 965 // check if there are any values earlier than specified by the history 966 // count... 967 if (getItemCount() > 1) { 968 long latest = getTimePeriod(getItemCount() - 1).getSerialIndex(); 969 boolean removed = false; 970 while ((latest - getTimePeriod(0).getSerialIndex()) 971 > this.maximumItemAge) { 972 this.data.remove(0); 973 removed = true; 974 } 975 if (removed) { 976 updateMinMaxYByIteration(); 977 if (notify) { 978 fireSeriesChanged(); 979 } 980 } 981 } 982 } 983 984 /** 985 * Age items in the series. Ensure that the timespan from the supplied 986 * time to the oldest record in the series does not exceed history count. 987 * oldest items will be removed if required. 988 * 989 * @param latest the time to be compared against when aging data 990 * (specified in milliseconds). 991 * @param notify controls whether or not a {@link SeriesChangeEvent} is 992 * sent to registered listeners IF any items are removed. 993 */ 994 public void removeAgedItems(long latest, boolean notify) { 995 if (this.data.isEmpty()) { 996 return; // nothing to do 997 } 998 // find the serial index of the period specified by 'latest' 999 long index = Long.MAX_VALUE; 1000 try { 1001 Method m = RegularTimePeriod.class.getDeclaredMethod( 1002 "createInstance", new Class[] {Class.class, Date.class, 1003 TimeZone.class, Locale.class}); 1004 RegularTimePeriod newest = (RegularTimePeriod) m.invoke( 1005 this.timePeriodClass, new Object[] {this.timePeriodClass, 1006 new Date(latest), TimeZone.getDefault(), Locale.getDefault()}); 1007 index = newest.getSerialIndex(); 1008 } 1009 catch (NoSuchMethodException e) { 1010 throw new RuntimeException(e); 1011 } 1012 catch (IllegalAccessException e) { 1013 throw new RuntimeException(e); 1014 } 1015 catch (InvocationTargetException e) { 1016 throw new RuntimeException(e); 1017 } 1018 1019 // check if there are any values earlier than specified by the history 1020 // count... 1021 boolean removed = false; 1022 while (getItemCount() > 0 && (index 1023 - getTimePeriod(0).getSerialIndex()) > this.maximumItemAge) { 1024 this.data.remove(0); 1025 removed = true; 1026 } 1027 if (removed) { 1028 updateMinMaxYByIteration(); 1029 if (notify) { 1030 fireSeriesChanged(); 1031 } 1032 } 1033 } 1034 1035 /** 1036 * Removes all data items from the series and sends a 1037 * {@link SeriesChangeEvent} to all registered listeners. 1038 */ 1039 public void clear() { 1040 if (this.data.size() > 0) { 1041 this.data.clear(); 1042 this.timePeriodClass = null; 1043 this.minY = Double.NaN; 1044 this.maxY = Double.NaN; 1045 fireSeriesChanged(); 1046 } 1047 } 1048 1049 /** 1050 * Deletes the data item for the given time period and sends a 1051 * {@link SeriesChangeEvent} to all registered listeners. If there is no 1052 * item with the specified time period, this method does nothing. 1053 * 1054 * @param period the period of the item to delete ({@code null} not 1055 * permitted). 1056 */ 1057 public void delete(RegularTimePeriod period) { 1058 int index = getIndex(period); 1059 if (index >= 0) { 1060 TimeSeriesDataItem item = (TimeSeriesDataItem) this.data.remove( 1061 index); 1062 updateBoundsForRemovedItem(item); 1063 if (this.data.isEmpty()) { 1064 this.timePeriodClass = null; 1065 } 1066 fireSeriesChanged(); 1067 } 1068 } 1069 1070 /** 1071 * Deletes data from start until end index (end inclusive). 1072 * 1073 * @param start the index of the first period to delete. 1074 * @param end the index of the last period to delete. 1075 */ 1076 public void delete(int start, int end) { 1077 delete(start, end, true); 1078 } 1079 1080 /** 1081 * Deletes data from start until end index (end inclusive). 1082 * 1083 * @param start the index of the first period to delete. 1084 * @param end the index of the last period to delete. 1085 * @param notify notify listeners? 1086 * 1087 * @since 1.0.14 1088 */ 1089 public void delete(int start, int end, boolean notify) { 1090 if (end < start) { 1091 throw new IllegalArgumentException("Requires start <= end."); 1092 } 1093 for (int i = 0; i <= (end - start); i++) { 1094 this.data.remove(start); 1095 } 1096 updateMinMaxYByIteration(); 1097 if (this.data.isEmpty()) { 1098 this.timePeriodClass = null; 1099 } 1100 if (notify) { 1101 fireSeriesChanged(); 1102 } 1103 } 1104 1105 /** 1106 * Returns a clone of the time series. 1107 * <P> 1108 * Notes: 1109 * <ul> 1110 * <li>no need to clone the domain and range descriptions, since String 1111 * object is immutable;</li> 1112 * <li>we pass over to the more general method clone(start, end).</li> 1113 * </ul> 1114 * 1115 * @return A clone of the time series. 1116 * 1117 * @throws CloneNotSupportedException not thrown by this class, but 1118 * subclasses may differ. 1119 */ 1120 @Override 1121 public Object clone() throws CloneNotSupportedException { 1122 TimeSeries clone = (TimeSeries) super.clone(); 1123 clone.data = (List) ObjectUtils.deepClone(this.data); 1124 return clone; 1125 } 1126 1127 /** 1128 * Creates a new timeseries by copying a subset of the data in this time 1129 * series. 1130 * 1131 * @param start the index of the first time period to copy. 1132 * @param end the index of the last time period to copy. 1133 * 1134 * @return A series containing a copy of this times series from start until 1135 * end. 1136 * 1137 * @throws CloneNotSupportedException if there is a cloning problem. 1138 */ 1139 public TimeSeries createCopy(int start, int end) 1140 throws CloneNotSupportedException { 1141 if (start < 0) { 1142 throw new IllegalArgumentException("Requires start >= 0."); 1143 } 1144 if (end < start) { 1145 throw new IllegalArgumentException("Requires start <= end."); 1146 } 1147 TimeSeries copy = (TimeSeries) super.clone(); 1148 copy.minY = Double.NaN; 1149 copy.maxY = Double.NaN; 1150 copy.data = new java.util.ArrayList(); 1151 if (this.data.size() > 0) { 1152 for (int index = start; index <= end; index++) { 1153 TimeSeriesDataItem item 1154 = (TimeSeriesDataItem) this.data.get(index); 1155 TimeSeriesDataItem clone = (TimeSeriesDataItem) item.clone(); 1156 try { 1157 copy.add(clone); 1158 } 1159 catch (SeriesException e) { 1160 throw new RuntimeException(e); 1161 } 1162 } 1163 } 1164 return copy; 1165 } 1166 1167 /** 1168 * Creates a new timeseries by copying a subset of the data in this time 1169 * series. 1170 * 1171 * @param start the first time period to copy ({@code null} not 1172 * permitted). 1173 * @param end the last time period to copy ({@code null} not permitted). 1174 * 1175 * @return A time series containing a copy of this time series from start 1176 * until end. 1177 * 1178 * @throws CloneNotSupportedException if there is a cloning problem. 1179 */ 1180 public TimeSeries createCopy(RegularTimePeriod start, RegularTimePeriod end) 1181 throws CloneNotSupportedException { 1182 1183 Args.nullNotPermitted(start, "start"); 1184 Args.nullNotPermitted(end, "end"); 1185 if (start.compareTo(end) > 0) { 1186 throw new IllegalArgumentException( 1187 "Requires start on or before end."); 1188 } 1189 boolean emptyRange = false; 1190 int startIndex = getIndex(start); 1191 if (startIndex < 0) { 1192 startIndex = -(startIndex + 1); 1193 if (startIndex == this.data.size()) { 1194 emptyRange = true; // start is after last data item 1195 } 1196 } 1197 int endIndex = getIndex(end); 1198 if (endIndex < 0) { // end period is not in original series 1199 endIndex = -(endIndex + 1); // this is first item AFTER end period 1200 endIndex = endIndex - 1; // so this is last item BEFORE end 1201 } 1202 if ((endIndex < 0) || (endIndex < startIndex)) { 1203 emptyRange = true; 1204 } 1205 if (emptyRange) { 1206 TimeSeries copy = (TimeSeries) super.clone(); 1207 copy.data = new java.util.ArrayList(); 1208 return copy; 1209 } 1210 return createCopy(startIndex, endIndex); 1211 } 1212 1213 /** 1214 * Tests the series for equality with an arbitrary object. 1215 * 1216 * @param obj the object to test against ({@code null} permitted). 1217 * 1218 * @return A boolean. 1219 */ 1220 @Override 1221 public boolean equals(Object obj) { 1222 if (obj == this) { 1223 return true; 1224 } 1225 if (!(obj instanceof TimeSeries)) { 1226 return false; 1227 } 1228 TimeSeries that = (TimeSeries) obj; 1229 if (!ObjectUtils.equal(getDomainDescription(), 1230 that.getDomainDescription())) { 1231 return false; 1232 } 1233 if (!ObjectUtils.equal(getRangeDescription(), 1234 that.getRangeDescription())) { 1235 return false; 1236 } 1237 if (!ObjectUtils.equal(this.timePeriodClass, 1238 that.timePeriodClass)) { 1239 return false; 1240 } 1241 if (getMaximumItemAge() != that.getMaximumItemAge()) { 1242 return false; 1243 } 1244 if (getMaximumItemCount() != that.getMaximumItemCount()) { 1245 return false; 1246 } 1247 int count = getItemCount(); 1248 if (count != that.getItemCount()) { 1249 return false; 1250 } 1251 if (!ObjectUtils.equal(this.data, that.data)) { 1252 return false; 1253 } 1254 return super.equals(obj); 1255 } 1256 1257 /** 1258 * Returns a hash code value for the object. 1259 * 1260 * @return The hashcode 1261 */ 1262 @Override 1263 public int hashCode() { 1264 int result = super.hashCode(); 1265 result = 29 * result + (this.domain != null ? this.domain.hashCode() 1266 : 0); 1267 result = 29 * result + (this.range != null ? this.range.hashCode() : 0); 1268 result = 29 * result + (this.timePeriodClass != null 1269 ? this.timePeriodClass.hashCode() : 0); 1270 // it is too slow to look at every data item, so let's just look at 1271 // the first, middle and last items... 1272 int count = getItemCount(); 1273 if (count > 0) { 1274 TimeSeriesDataItem item = getRawDataItem(0); 1275 result = 29 * result + item.hashCode(); 1276 } 1277 if (count > 1) { 1278 TimeSeriesDataItem item = getRawDataItem(count - 1); 1279 result = 29 * result + item.hashCode(); 1280 } 1281 if (count > 2) { 1282 TimeSeriesDataItem item = getRawDataItem(count / 2); 1283 result = 29 * result + item.hashCode(); 1284 } 1285 result = 29 * result + this.maximumItemCount; 1286 result = 29 * result + (int) this.maximumItemAge; 1287 return result; 1288 } 1289 1290 /** 1291 * Updates the cached values for the minimum and maximum data values. 1292 * 1293 * @param item the item added ({@code null} not permitted). 1294 * 1295 * @since 1.0.14 1296 */ 1297 private void updateBoundsForAddedItem(TimeSeriesDataItem item) { 1298 Number yN = item.getValue(); 1299 if (item.getValue() != null) { 1300 double y = yN.doubleValue(); 1301 this.minY = minIgnoreNaN(this.minY, y); 1302 this.maxY = maxIgnoreNaN(this.maxY, y); 1303 } 1304 } 1305 1306 /** 1307 * Updates the cached values for the minimum and maximum data values on 1308 * the basis that the specified item has just been removed. 1309 * 1310 * @param item the item added ({@code null} not permitted). 1311 * 1312 * @since 1.0.14 1313 */ 1314 private void updateBoundsForRemovedItem(TimeSeriesDataItem item) { 1315 Number yN = item.getValue(); 1316 if (yN != null) { 1317 double y = yN.doubleValue(); 1318 if (!Double.isNaN(y)) { 1319 if (y <= this.minY || y >= this.maxY) { 1320 updateMinMaxYByIteration(); 1321 } 1322 } 1323 } 1324 } 1325 1326 /** 1327 * Finds the bounds of the x and y values for the series, by iterating 1328 * through all the data items. 1329 * 1330 * @since 1.0.14 1331 */ 1332 private void updateMinMaxYByIteration() { 1333 this.minY = Double.NaN; 1334 this.maxY = Double.NaN; 1335 Iterator iterator = this.data.iterator(); 1336 while (iterator.hasNext()) { 1337 TimeSeriesDataItem item = (TimeSeriesDataItem) iterator.next(); 1338 updateBoundsForAddedItem(item); 1339 } 1340 } 1341 1342 /** 1343 * A function to find the minimum of two values, but ignoring any 1344 * Double.NaN values. 1345 * 1346 * @param a the first value. 1347 * @param b the second value. 1348 * 1349 * @return The minimum of the two values. 1350 */ 1351 private double minIgnoreNaN(double a, double b) { 1352 if (Double.isNaN(a)) { 1353 return b; 1354 } 1355 if (Double.isNaN(b)) { 1356 return a; 1357 } 1358 return Math.min(a, b); 1359 } 1360 1361 /** 1362 * A function to find the maximum of two values, but ignoring any 1363 * Double.NaN values. 1364 * 1365 * @param a the first value. 1366 * @param b the second value. 1367 * 1368 * @return The maximum of the two values. 1369 */ 1370 private double maxIgnoreNaN(double a, double b) { 1371 if (Double.isNaN(a)) { 1372 return b; 1373 } 1374 if (Double.isNaN(b)) { 1375 return a; 1376 } 1377 else { 1378 return Math.max(a, b); 1379 } 1380 } 1381 1382}