/* ===========================================================
* JFreeChart : a free chart library for the Java(tm) platform
* ===========================================================
*
* (C) Copyright 2000-2008, by Object Refinery Limited and Contributors.
*
* Project Info: http://www.jfree.org/jfreechart/index.html
*
* This library is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation; either version 2.1 of the License, or
* (at your option) any later version.
*
* This library is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
* License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
* USA.
*
* [Java is a trademark or registered trademark of Sun Microsystems, Inc.
* in the United States and other countries.]
*
* ---------------
* TimeSeries.java
* ---------------
* (C) Copyright 2001-2008, by Object Refinery Limited.
*
* Original Author: David Gilbert (for Object Refinery Limited);
* Contributor(s): Bryan Scott;
* Nick Guenther;
*
* Changes
* -------
* 11-Oct-2001 : Version 1 (DG);
* 14-Nov-2001 : Added listener mechanism (DG);
* 15-Nov-2001 : Updated argument checking and exceptions in add() method (DG);
* 29-Nov-2001 : Added properties to describe the domain and range (DG);
* 07-Dec-2001 : Renamed TimeSeries --> BasicTimeSeries (DG);
* 01-Mar-2002 : Updated import statements (DG);
* 28-Mar-2002 : Added a method add(TimePeriod, double) (DG);
* 27-Aug-2002 : Changed return type of delete method to void (DG);
* 04-Oct-2002 : Added itemCount and historyCount attributes, fixed errors
* reported by Checkstyle (DG);
* 29-Oct-2002 : Added series change notification to addOrUpdate() method (DG);
* 28-Jan-2003 : Changed name back to TimeSeries (DG);
* 13-Mar-2003 : Moved to com.jrefinery.data.time package and implemented
* Serializable (DG);
* 01-May-2003 : Updated equals() method (see bug report 727575) (DG);
* 14-Aug-2003 : Added ageHistoryCountItems method (copied existing code for
* contents) made a method and added to addOrUpdate. Made a
* public method to enable ageing against a specified time
* (eg now) as opposed to lastest time in series (BS);
* 15-Oct-2003 : Added fix for setItemCount method - see bug report 804425.
* Modified exception message in add() method to be more
* informative (DG);
* 13-Apr-2004 : Added clear() method (DG);
* 21-May-2004 : Added an extra addOrUpdate() method (DG);
* 15-Jun-2004 : Fixed NullPointerException in equals() method (DG);
* 29-Nov-2004 : Fixed bug 1075255 (DG);
* 17-Nov-2005 : Renamed historyCount --> maximumItemAge (DG);
* 28-Nov-2005 : Changed maximumItemAge from int to long (DG);
* 01-Dec-2005 : New add methods accept notify flag (DG);
* ------------- JFREECHART 1.0.x ---------------------------------------------
* 24-May-2006 : Improved error handling in createCopy() methods (DG);
* 01-Sep-2006 : Fixed bugs in removeAgedItems() methods - see bug report
* 1550045 (DG);
* 22-Mar-2007 : Simplified getDataItem(RegularTimePeriod) - see patch 1685500
* by Nick Guenther (DG);
* 31-Oct-2007 : Implemented faster hashCode() (DG);
* 21-Nov-2007 : Fixed clone() method (bug 1832432) (DG);
* 10-Jan-2008 : Fixed createCopy(RegularTimePeriod, RegularTimePeriod) (bug
* 1864222) (DG);
*
*/
package com.positive.charts.data.time;
import java.io.Serializable;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.util.Collection;
import java.util.Collections;
import java.util.Date;
import java.util.List;
import java.util.TimeZone;
import com.positive.charts.common.SeriesException;
import com.positive.charts.data.general.Series;
import com.positive.charts.data.util.ObjectUtilities;
import com.positive.charts.event.SeriesChangeEvent;
/**
* Represents a sequence of zero or more data items in the form (period, value).
*/
public class TimeSeries extends Series implements Cloneable, Serializable {
/** For serialization. */
private static final long serialVersionUID = -5032960206869675528L;
/** Default value for the domain description. */
protected static final String DEFAULT_DOMAIN_DESCRIPTION = "Time";
/** Default value for the range description. */
protected static final String DEFAULT_RANGE_DESCRIPTION = "Value";
/** A description of the domain. */
private String domain;
/** A description of the range. */
private String range;
/** The type of period for the data. */
protected Class timePeriodClass;
/** The list of data items in the series. */
protected List data;
/** The maximum number of items for the series. */
private int maximumItemCount;
/**
* The maximum age of items for the series, specified as a number of time
* periods.
*/
private long maximumItemAge;
/**
* Creates a new (empty) time series. By default, a daily time series is
* created. Use one of the other constructors if you require a different
* time period.
*
* @param name
* the series name (<code>null</code> not permitted).
*/
public TimeSeries(final Comparable name) {
this(name, DEFAULT_DOMAIN_DESCRIPTION, DEFAULT_RANGE_DESCRIPTION,
Day.class);
}
/**
* Creates a new (empty) time series with the specified name and class of
* {@link RegularTimePeriod}.
*
* @param name
* the series name (<code>null</code> not permitted).
* @param timePeriodClass
* the type of time period (<code>null</code> not permitted).
*/
public TimeSeries(final Comparable name, final Class timePeriodClass) {
this(name, DEFAULT_DOMAIN_DESCRIPTION, DEFAULT_RANGE_DESCRIPTION,
timePeriodClass);
}
/**
* Creates a new time series that contains no data.
* <P>
* Descriptions can be specified for the domain and range. One situation
* where this is helpful is when generating a chart for the time series -
* axis labels can be taken from the domain and range description.
*
* @param name
* the name of the series (<code>null</code> not permitted).
* @param domain
* the domain description (<code>null</code> permitted).
* @param range
* the range description (<code>null</code> permitted).
* @param timePeriodClass
* the type of time period (<code>null</code> not permitted).
*/
public TimeSeries(final Comparable name, final String domain,
final String range, final Class timePeriodClass) {
super(name);
this.domain = domain;
this.range = range;
this.timePeriodClass = timePeriodClass;
this.data = new java.util.ArrayList();
this.maximumItemCount = Integer.MAX_VALUE;
this.maximumItemAge = Long.MAX_VALUE;
}
/**
* Adds a new data item to the series and sends a {@link SeriesChangeEvent}
* to all registered listeners.
*
* @param period
* the time period (<code>null</code> not permitted).
* @param value
* the value.
*/
public void add(final RegularTimePeriod period, final double value) {
// defer argument checking...
this.add(period, value, true);
}
/**
* Adds a new data item to the series and sends a {@link SeriesChangeEvent}
* to all registered listeners.
*
* @param period
* the time period (<code>null</code> not permitted).
* @param value
* the value.
* @param notify
* notify listeners?
*/
public void add(final RegularTimePeriod period, final double value,
final boolean notify) {
// defer argument checking...
final TimeSeriesDataItem item = new TimeSeriesDataItem(period, value);
this.add(item, notify);
}
/**
* Adds a new data item to the series and sends a
* {@link org.jfree.data.general.SeriesChangeEvent} to all registered
* listeners.
*
* @param period
* the time period (<code>null</code> not permitted).
* @param value
* the value (<code>null</code> permitted).
*/
public void add(final RegularTimePeriod period, final Number value) {
// defer argument checking...
this.add(period, value, true);
}
/**
* Adds a new data item to the series and sends a
* {@link org.jfree.data.general.SeriesChangeEvent} to all registered
* listeners.
*
* @param period
* the time period (<code>null</code> not permitted).
* @param value
* the value (<code>null</code> permitted).
* @param notify
* notify listeners?
*/
public void add(final RegularTimePeriod period, final Number value,
final boolean notify) {
// defer argument checking...
final TimeSeriesDataItem item = new TimeSeriesDataItem(period, value);
this.add(item, notify);
}
/**
* Adds a data item to the series and sends a
* {@link org.jfree.data.general.SeriesChangeEvent} to all registered
* listeners.
*
* @param item
* the (timeperiod, value) pair (<code>null</code> not
* permitted).
*/
public void add(final TimeSeriesDataItem item) {
this.add(item, true);
}
/**
* Adds a data item to the series and sends a
* {@link org.jfree.data.general.SeriesChangeEvent} to all registered
* listeners.
*
* @param item
* the (timeperiod, value) pair (<code>null</code> not
* permitted).
* @param notify
* notify listeners?
*/
public void add(final TimeSeriesDataItem item, final boolean notify) {
if (item == null) {
throw new IllegalArgumentException("Null 'item' argument.");
}
if (!item.getPeriod().getClass().equals(this.timePeriodClass)) {
final StringBuffer b = new StringBuffer();
b.append("You are trying to add data where the time period class ");
b.append("is ");
b.append(item.getPeriod().getClass().getName());
b.append(", but the TimeSeries is expecting an instance of ");
b.append(this.timePeriodClass.getName());
b.append(".");
throw new SeriesException(b.toString());
}
// make the change (if it's not a duplicate time period)...
boolean added = false;
final int count = this.getItemCount();
if (count == 0) {
this.data.add(item);
added = true;
} else {
final RegularTimePeriod last = this.getTimePeriod(this
.getItemCount() - 1);
if (item.getPeriod().compareTo(last) > 0) {
this.data.add(item);
added = true;
} else {
final int index = Collections.binarySearch(this.data, item);
if (index < 0) {
this.data.add(-index - 1, item);
added = true;
} else {
final StringBuffer b = new StringBuffer();
b.append("You are attempting to add an observation for ");
b.append("the time period ");
b.append(item.getPeriod().toString());
b.append(" but the series already contains an observation");
b.append(" for that time period. Duplicates are not ");
b.append("permitted. Try using the addOrUpdate() method.");
throw new SeriesException(b.toString());
}
}
}
if (added) {
// check if this addition will exceed the maximum item count...
if (this.getItemCount() > this.maximumItemCount) {
this.data.remove(0);
}
this.removeAgedItems(false); // remove old items if necessary, but
// don't notify anyone, because that
// happens next anyway...
if (notify) {
this.fireSeriesChanged();
}
}
}
/**
* Adds or updates data from one series to another. Returns another series
* containing the values that were overwritten.
*
* @param series
* the series to merge with this.
*
* @return A series containing the values that were overwritten.
*/
public TimeSeries addAndOrUpdate(final TimeSeries series) {
final TimeSeries overwritten = new TimeSeries(
"Overwritten values from: " + this.getKey(), series
.getTimePeriodClass());
for (int i = 0; i < series.getItemCount(); i++) {
final TimeSeriesDataItem item = series.getDataItem(i);
final TimeSeriesDataItem oldItem = this.addOrUpdate(item
.getPeriod(), item.getValue());
if (oldItem != null) {
overwritten.add(oldItem);
}
}
return overwritten;
}
/**
* Adds or updates an item in the times series and sends a
* {@link org.jfree.data.general.SeriesChangeEvent} to all registered
* listeners.
*
* @param period
* the time period to add/update (<code>null</code> not
* permitted).
* @param value
* the new value.
*
* @return A copy of the overwritten data item, or <code>null</code> if no
* item was overwritten.
*/
public TimeSeriesDataItem addOrUpdate(final RegularTimePeriod period,
final double value) {
return this.addOrUpdate(period, new Double(value));
}
/**
* Adds or updates an item in the times series and sends a
* {@link org.jfree.data.general.SeriesChangeEvent} to all registered
* listeners.
*
* @param period
* the time period to add/update (<code>null</code> not
* permitted).
* @param value
* the new value (<code>null</code> permitted).
*
* @return A copy of the overwritten data item, or <code>null</code> if no
* item was overwritten.
*/
public TimeSeriesDataItem addOrUpdate(final RegularTimePeriod period,
final Number value) {
if (period == null) {
throw new IllegalArgumentException("Null 'period' argument.");
}
TimeSeriesDataItem overwritten = null;
final TimeSeriesDataItem key = new TimeSeriesDataItem(period, value);
final int index = Collections.binarySearch(this.data, key);
if (index >= 0) {
final TimeSeriesDataItem existing = (TimeSeriesDataItem) this.data
.get(index);
overwritten = (TimeSeriesDataItem) existing.clone();
existing.setValue(value);
this.removeAgedItems(false); // remove old items if necessary, but
// don't notify anyone, because that
// happens next anyway...
this.fireSeriesChanged();
} else {
this.data.add(-index - 1, new TimeSeriesDataItem(period, value));
// check if this addition will exceed the maximum item count...
if (this.getItemCount() > this.maximumItemCount) {
this.data.remove(0);
}
this.removeAgedItems(false); // remove old items if necessary, but
// don't notify anyone, because that
// happens next anyway...
this.fireSeriesChanged();
}
return overwritten;
}
/**
* Removes all data items from the series and sends a
* {@link SeriesChangeEvent} to all registered listeners.
*/
public void clear() {
if (this.data.size() > 0) {
this.data.clear();
this.fireSeriesChanged();
}
}
/**
* Returns a clone of the time series.
* <P>
* Notes:
* <ul>
* <li>no need to clone the domain and range descriptions, since String
* object is immutable;</li>
* <li>we pass over to the more general method clone(start, end).</li>
* </ul>
*
* @return A clone of the time series.
*
* @throws CloneNotSupportedException
* not thrown by this class, but subclasses may differ.
*/
public Object clone() throws CloneNotSupportedException {
final TimeSeries clone = (TimeSeries) super.clone();
clone.data = (List) ObjectUtilities.deepClone(this.data);
return clone;
}
/**
* Creates a new timeseries by copying a subset of the data in this time
* series.
*
* @param start
* the index of the first time period to copy.
* @param end
* the index of the last time period to copy.
*
* @return A series containing a copy of this times series from start until
* end.
*
* @throws CloneNotSupportedException
* if there is a cloning problem.
*/
public TimeSeries createCopy(final int start, final int end)
throws CloneNotSupportedException {
if (start < 0) {
throw new IllegalArgumentException("Requires start >= 0.");
}
if (end < start) {
throw new IllegalArgumentException("Requires start <= end.");
}
final TimeSeries copy = (TimeSeries) super.clone();
copy.data = new java.util.ArrayList();
if (this.data.size() > 0) {
for (int index = start; index <= end; index++) {
final TimeSeriesDataItem item = (TimeSeriesDataItem) this.data
.get(index);
final TimeSeriesDataItem clone = (TimeSeriesDataItem) item
.clone();
try {
copy.add(clone);
} catch (final SeriesException e) {
e.printStackTrace();
}
}
}
return copy;
}
/**
* Creates a new timeseries by copying a subset of the data in this time
* series.
*
* @param start
* the first time period to copy (<code>null</code> not
* permitted).
* @param end
* the last time period to copy (<code>null</code> not
* permitted).
*
* @return A time series containing a copy of this time series from start
* until end.
*
* @throws CloneNotSupportedException
* if there is a cloning problem.
*/
public TimeSeries createCopy(final RegularTimePeriod start,
final RegularTimePeriod end) throws CloneNotSupportedException {
if (start == null) {
throw new IllegalArgumentException("Null 'start' argument.");
}
if (end == null) {
throw new IllegalArgumentException("Null 'end' argument.");
}
if (start.compareTo(end) > 0) {
throw new IllegalArgumentException(
"Requires start on or before end.");
}
boolean emptyRange = false;
int startIndex = this.getIndex(start);
if (startIndex < 0) {
startIndex = -(startIndex + 1);
if (startIndex == this.data.size()) {
emptyRange = true; // start is after last data item
}
}
int endIndex = this.getIndex(end);
if (endIndex < 0) { // end period is not in original series
endIndex = -(endIndex + 1); // this is first item AFTER end period
endIndex = endIndex - 1; // so this is last item BEFORE end
}
if ((endIndex < 0) || (endIndex < startIndex)) {
emptyRange = true;
}
if (emptyRange) {
final TimeSeries copy = (TimeSeries) super.clone();
copy.data = new java.util.ArrayList();
return copy;
} else {
return this.createCopy(startIndex, endIndex);
}
}
/**
* Deletes data from start until end index (end inclusive).
*
* @param start
* the index of the first period to delete.
* @param end
* the index of the last period to delete.
*/
public void delete(final int start, final int end) {
if (end < start) {
throw new IllegalArgumentException("Requires start <= end.");
}
for (int i = 0; i <= (end - start); i++) {
this.data.remove(start);
}
this.fireSeriesChanged();
}
/**
* Deletes the data item for the given time period and sends a
* {@link SeriesChangeEvent} to all registered listeners. If there is no
* item with the specified time period, this method does nothing.
*
* @param period
* the period of the item to delete (<code>null</code> not
* permitted).
*/
public void delete(final RegularTimePeriod period) {
final int index = this.getIndex(period);
if (index >= 0) {
this.data.remove(index);
this.fireSeriesChanged();
}
}
/**
* Tests the series for equality with an arbitrary object.
*
* @param object
* the object to test against (<code>null</code> permitted).
*
* @return A boolean.
*/
public boolean equals(final Object object) {
if (object == this) {
return true;
}
if (!(object instanceof TimeSeries) || !super.equals(object)) {
return false;
}
final TimeSeries s = (TimeSeries) object;
if (!ObjectUtilities.equal(this.getDomainDescription(), s
.getDomainDescription())) {
return false;
}
if (!ObjectUtilities.equal(this.getRangeDescription(), s
.getRangeDescription())) {
return false;
}
if (!this.getClass().equals(s.getClass())) {
return false;
}
if (this.getMaximumItemAge() != s.getMaximumItemAge()) {
return false;
}
if (this.getMaximumItemCount() != s.getMaximumItemCount()) {
return false;
}
final int count = this.getItemCount();
if (count != s.getItemCount()) {
return false;
}
for (int i = 0; i < count; i++) {
if (!this.getDataItem(i).equals(s.getDataItem(i))) {
return false;
}
}
return true;
}
/**
* Returns a data item for the series.
*
* @param index
* the item index (zero-based).
*
* @return The data item.
*
* @see #getDataItem(RegularTimePeriod)
*/
public TimeSeriesDataItem getDataItem(final int index) {
return (TimeSeriesDataItem) this.data.get(index);
}
/**
* Returns the data item for a specific period.
*
* @param period
* the period of interest (<code>null</code> not allowed).
*
* @return The data item matching the specified period (or <code>null</code>
* if there is no match).
*
* @see #getDataItem(int)
*/
public TimeSeriesDataItem getDataItem(final RegularTimePeriod period) {
final int index = this.getIndex(period);
if (index >= 0) {
return (TimeSeriesDataItem) this.data.get(index);
} else {
return null;
}
}
/**
* Returns the domain description.
*
* @return The domain description (possibly <code>null</code>).
*
* @see #setDomainDescription(String)
*/
public String getDomainDescription() {
return this.domain;
}
/**
* Returns the index for the item (if any) that corresponds to a time
* period.
*
* @param period
* the time period (<code>null</code> not permitted).
*
* @return The index.
*/
public int getIndex(final RegularTimePeriod period) {
if (period == null) {
throw new IllegalArgumentException("Null 'period' argument.");
}
final TimeSeriesDataItem dummy = new TimeSeriesDataItem(period,
Integer.MIN_VALUE);
return Collections.binarySearch(this.data, dummy);
}
/**
* Returns the number of items in the series.
*
* @return The item count.
*/
public int getItemCount() {
return this.data.size();
}
/**
* Returns the list of data items for the series (the list contains
* {@link TimeSeriesDataItem} objects and is unmodifiable).
*
* @return The list of data items.
*/
public List getItems() {
return Collections.unmodifiableList(this.data);
}
/**
* Returns the maximum item age (in time periods) for the series.
*
* @return The maximum item age.
*
* @see #setMaximumItemAge(long)
*/
public long getMaximumItemAge() {
return this.maximumItemAge;
}
/**
* Returns the maximum number of items that will be retained in the series.
* The default value is <code>Integer.MAX_VALUE</code>.
*
* @return The maximum item count.
*
* @see #setMaximumItemCount(int)
*/
public int getMaximumItemCount() {
return this.maximumItemCount;
}
/**
* Returns a time period that would be the next in sequence on the end of
* the time series.
*
* @return The next time period.
*/
public RegularTimePeriod getNextTimePeriod() {
final RegularTimePeriod last = this
.getTimePeriod(this.getItemCount() - 1);
return last.next();
}
/**
* Returns the range description.
*
* @return The range description (possibly <code>null</code>).
*
* @see #setRangeDescription(String)
*/
public String getRangeDescription() {
return this.range;
}
/**
* Returns the time period at the specified index.
*
* @param index
* the index of the data item.
*
* @return The time period.
*/
public RegularTimePeriod getTimePeriod(final int index) {
return this.getDataItem(index).getPeriod();
}
/**
* Returns the time period class for this series.
* <p>
* Only one time period class can be used within a single series (enforced).
* If you add a data item with a {@link Year} for the time period, then all
* subsequent data items must also have a {@link Year} for the time period.
*
* @return The time period class (never <code>null</code>).
*/
public Class getTimePeriodClass() {
return this.timePeriodClass;
}
/**
* Returns a collection of all the time periods in the time series.
*
* @return A collection of all the time periods.
*/
public Collection getTimePeriods() {
final Collection result = new java.util.ArrayList();
for (int i = 0; i < this.getItemCount(); i++) {
result.add(this.getTimePeriod(i));
}
return result;
}
/**
* Returns a collection of time periods in the specified series, but not in
* this series, and therefore unique to the specified series.
*
* @param series
* the series to check against this one.
*
* @return The unique time periods.
*/
public Collection getTimePeriodsUniqueToOtherSeries(final TimeSeries series) {
final Collection result = new java.util.ArrayList();
for (int i = 0; i < series.getItemCount(); i++) {
final RegularTimePeriod period = series.getTimePeriod(i);
final int index = this.getIndex(period);
if (index < 0) {
result.add(period);
}
}
return result;
}
/**
* Returns the value at the specified index.
*
* @param index
* index of a value.
*
* @return The value (possibly <code>null</code>).
*/
public Number getValue(final int index) {
return this.getDataItem(index).getValue();
}
/**
* Returns the value for a time period. If there is no data item with the
* specified period, this method will return <code>null</code>.
*
* @param period
* time period (<code>null</code> not permitted).
*
* @return The value (possibly <code>null</code>).
*/
public Number getValue(final RegularTimePeriod period) {
final int index = this.getIndex(period);
if (index >= 0) {
return this.getValue(index);
} else {
return null;
}
}
/**
* Returns a hash code value for the object.
*
* @return The hashcode
*/
public int hashCode() {
int result = super.hashCode();
result = 29 * result
+ (this.domain != null ? this.domain.hashCode() : 0);
result = 29 * result + (this.range != null ? this.range.hashCode() : 0);
result = 29
* result
+ (this.timePeriodClass != null ? this.timePeriodClass
.hashCode() : 0);
// it is too slow to look at every data item, so let's just look at
// the first, middle and last items...
final int count = this.getItemCount();
if (count > 0) {
final TimeSeriesDataItem item = this.getDataItem(0);
result = 29 * result + item.hashCode();
}
if (count > 1) {
final TimeSeriesDataItem item = this.getDataItem(count - 1);
result = 29 * result + item.hashCode();
}
if (count > 2) {
final TimeSeriesDataItem item = this.getDataItem(count / 2);
result = 29 * result + item.hashCode();
}
result = 29 * result + this.maximumItemCount;
result = 29 * result + (int) this.maximumItemAge;
return result;
}
/**
* Age items in the series. Ensure that the timespan from the youngest to
* the oldest record in the series does not exceed maximumItemAge time
* periods. Oldest items will be removed if required.
*
* @param notify
* controls whether or not a {@link SeriesChangeEvent} is sent to
* registered listeners IF any items are removed.
*/
public void removeAgedItems(final boolean notify) {
// check if there are any values earlier than specified by the history
// count...
if (this.getItemCount() > 1) {
final long latest = this.getTimePeriod(this.getItemCount() - 1)
.getSerialIndex();
boolean removed = false;
while ((latest - this.getTimePeriod(0).getSerialIndex()) > this.maximumItemAge) {
this.data.remove(0);
removed = true;
}
if (removed && notify) {
this.fireSeriesChanged();
}
}
}
/**
* Age items in the series. Ensure that the timespan from the supplied time
* to the oldest record in the series does not exceed history count. oldest
* items will be removed if required.
*
* @param latest
* the time to be compared against when aging data (specified in
* milliseconds).
* @param notify
* controls whether or not a {@link SeriesChangeEvent} is sent to
* registered listeners IF any items are removed.
*/
public void removeAgedItems(final long latest, final boolean notify) {
// find the serial index of the period specified by 'latest'
long index = Long.MAX_VALUE;
try {
final Method m = RegularTimePeriod.class.getDeclaredMethod(
"createInstance", new Class[] { Class.class, Date.class,
TimeZone.class });
final RegularTimePeriod newest = (RegularTimePeriod) m.invoke(
this.timePeriodClass, new Object[] { this.timePeriodClass,
new Date(latest), TimeZone.getDefault() });
index = newest.getSerialIndex();
} catch (final NoSuchMethodException e) {
e.printStackTrace();
} catch (final IllegalAccessException e) {
e.printStackTrace();
} catch (final InvocationTargetException e) {
e.printStackTrace();
}
// check if there are any values earlier than specified by the history
// count...
boolean removed = false;
while ((this.getItemCount() > 0)
&& ((index - this.getTimePeriod(0).getSerialIndex()) > this.maximumItemAge)) {
this.data.remove(0);
removed = true;
}
if (removed && notify) {
this.fireSeriesChanged();
}
}
/**
* Sets the domain description and sends a <code>PropertyChangeEvent</code>
* (with the property name <code>Domain</code>) to all registered property
* change listeners.
*
* @param description
* the description (<code>null</code> permitted).
*
* @see #getDomainDescription()
*/
public void setDomainDescription(final String description) {
final String old = this.domain;
this.domain = description;
this.firePropertyChange("Domain", old, description);
}
/**
* Sets the number of time units in the 'history' for the series. This
* provides one mechanism for automatically dropping old data from the time
* series. For example, if a series contains daily data, you might set the
* history count to 30. Then, when you add a new data item, all data items
* more than 30 days older than the latest value are automatically dropped
* from the series.
*
* @param periods
* the number of time periods.
*
* @see #getMaximumItemAge()
*/
public void setMaximumItemAge(final long periods) {
if (periods < 0) {
throw new IllegalArgumentException("Negative 'periods' argument.");
}
this.maximumItemAge = periods;
this.removeAgedItems(true); // remove old items and notify if necessary
}
/**
* Sets the maximum number of items that will be retained in the series. If
* you add a new item to the series such that the number of items will
* exceed the maximum item count, then the FIRST element in the series is
* automatically removed, ensuring that the maximum item count is not
* exceeded.
*
* @param maximum
* the maximum (requires >= 0).
*
* @see #getMaximumItemCount()
*/
public void setMaximumItemCount(final int maximum) {
if (maximum < 0) {
throw new IllegalArgumentException("Negative 'maximum' argument.");
}
this.maximumItemCount = maximum;
final int count = this.data.size();
if (count > maximum) {
this.delete(0, count - maximum - 1);
}
}
/**
* Sets the range description and sends a <code>PropertyChangeEvent</code>
* (with the property name <code>Range</code>) to all registered listeners.
*
* @param description
* the description (<code>null</code> permitted).
*
* @see #getRangeDescription()
*/
public void setRangeDescription(final String description) {
final String old = this.range;
this.range = description;
this.firePropertyChange("Range", old, description);
}
/**
* Updates (changes) the value of a data item.
*
* @param index
* the index of the data item.
* @param value
* the new value (<code>null</code> permitted).
*/
public void update(final int index, final Number value) {
final TimeSeriesDataItem item = this.getDataItem(index);
item.setValue(value);
this.fireSeriesChanged();
}
/**
* Updates (changes) the value for a time period. Throws a
* {@link SeriesException} if the period does not exist.
*
* @param period
* the period (<code>null</code> not permitted).
* @param value
* the value (<code>null</code> permitted).
*/
public void update(final RegularTimePeriod period, final Number value) {
final TimeSeriesDataItem temp = new TimeSeriesDataItem(period, value);
final int index = Collections.binarySearch(this.data, temp);
if (index >= 0) {
final TimeSeriesDataItem pair = (TimeSeriesDataItem) this.data
.get(index);
pair.setValue(value);
this.fireSeriesChanged();
} else {
throw new SeriesException(
"TimeSeries.update(TimePeriod, Number): period does not exist.");
}
}
}