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 &gt;= 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}