org.jfree.data.time

Class TimeSeries

public class TimeSeries extends Series implements Cloneable, Serializable

Represents a sequence of zero or more data items in the form (period, value).
Field Summary
protected Listdata
The list of data items in the series.
protected static StringDEFAULT_DOMAIN_DESCRIPTION
Default value for the domain description.
protected static StringDEFAULT_RANGE_DESCRIPTION
Default value for the range description.
protected ClasstimePeriodClass
The type of period for the data.
Constructor Summary
TimeSeries(Comparable name)
Creates a new (empty) time series.
TimeSeries(Comparable name, Class timePeriodClass)
Creates a new (empty) time series with the specified name and class of RegularTimePeriod.
TimeSeries(Comparable name, String domain, String range, Class timePeriodClass)
Creates a new time series that contains no data.
Method Summary
voidadd(TimeSeriesDataItem item)
Adds a data item to the series and sends a SeriesChangeEvent to all registered listeners.
voidadd(TimeSeriesDataItem item, boolean notify)
Adds a data item to the series and sends a SeriesChangeEvent to all registered listeners.
voidadd(RegularTimePeriod period, double value)
Adds a new data item to the series and sends a SeriesChangeEvent to all registered listeners.
voidadd(RegularTimePeriod period, double value, boolean notify)
Adds a new data item to the series and sends a SeriesChangeEvent to all registered listeners.
voidadd(RegularTimePeriod period, Number value)
Adds a new data item to the series and sends a SeriesChangeEvent to all registered listeners.
voidadd(RegularTimePeriod period, Number value, boolean notify)
Adds a new data item to the series and sends a SeriesChangeEvent to all registered listeners.
TimeSeriesaddAndOrUpdate(TimeSeries series)
Adds or updates data from one series to another.
TimeSeriesDataItemaddOrUpdate(RegularTimePeriod period, double value)
Adds or updates an item in the times series and sends a SeriesChangeEvent to all registered listeners.
TimeSeriesDataItemaddOrUpdate(RegularTimePeriod period, Number value)
Adds or updates an item in the times series and sends a SeriesChangeEvent to all registered listeners.
voidclear()
Removes all data items from the series and sends a SeriesChangeEvent to all registered listeners.
Objectclone()
Returns a clone of the time series.
TimeSeriescreateCopy(int start, int end)
Creates a new timeseries by copying a subset of the data in this time series.
TimeSeriescreateCopy(RegularTimePeriod start, RegularTimePeriod end)
Creates a new timeseries by copying a subset of the data in this time series.
voiddelete(RegularTimePeriod period)
Deletes the data item for the given time period and sends a SeriesChangeEvent to all registered listeners.
voiddelete(int start, int end)
Deletes data from start until end index (end inclusive).
booleanequals(Object object)
Tests the series for equality with an arbitrary object.
TimeSeriesDataItemgetDataItem(int index)
Returns a data item for the series.
TimeSeriesDataItemgetDataItem(RegularTimePeriod period)
Returns the data item for a specific period.
StringgetDomainDescription()
Returns the domain description.
intgetIndex(RegularTimePeriod period)
Returns the index for the item (if any) that corresponds to a time period.
intgetItemCount()
Returns the number of items in the series.
ListgetItems()
Returns the list of data items for the series (the list contains TimeSeriesDataItem objects and is unmodifiable).
longgetMaximumItemAge()
Returns the maximum item age (in time periods) for the series.
intgetMaximumItemCount()
Returns the maximum number of items that will be retained in the series.
RegularTimePeriodgetNextTimePeriod()
Returns a time period that would be the next in sequence on the end of the time series.
StringgetRangeDescription()
Returns the range description.
RegularTimePeriodgetTimePeriod(int index)
Returns the time period at the specified index.
ClassgetTimePeriodClass()
Returns the time period class for this series.
CollectiongetTimePeriods()
Returns a collection of all the time periods in the time series.
CollectiongetTimePeriodsUniqueToOtherSeries(TimeSeries series)
Returns a collection of time periods in the specified series, but not in this series, and therefore unique to the specified series.
NumbergetValue(int index)
Returns the value at the specified index.
NumbergetValue(RegularTimePeriod period)
Returns the value for a time period.
inthashCode()
Returns a hash code value for the object.
voidremoveAgedItems(boolean notify)
Age items in the series.
voidremoveAgedItems(long latest, boolean notify)
Age items in the series.
voidsetDomainDescription(String description)
Sets the domain description and sends a PropertyChangeEvent (with the property name Domain) to all registered property change listeners.
voidsetMaximumItemAge(long periods)
Sets the number of time units in the 'history' for the series.
voidsetMaximumItemCount(int maximum)
Sets the maximum number of items that will be retained in the series.
voidsetRangeDescription(String description)
Sets the range description and sends a PropertyChangeEvent (with the property name Range) to all registered listeners.
voidupdate(RegularTimePeriod period, Number value)
Updates (changes) the value for a time period.
voidupdate(int index, Number value)
Updates (changes) the value of a data item.

Field Detail

data

protected List data
The list of data items in the series.

DEFAULT_DOMAIN_DESCRIPTION

protected static final String DEFAULT_DOMAIN_DESCRIPTION
Default value for the domain description.

DEFAULT_RANGE_DESCRIPTION

protected static final String DEFAULT_RANGE_DESCRIPTION
Default value for the range description.

timePeriodClass

protected Class timePeriodClass
The type of period for the data.

Constructor Detail

TimeSeries

public TimeSeries(Comparable name)
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.

Parameters: name the series name (null not permitted).

TimeSeries

public TimeSeries(Comparable name, Class timePeriodClass)
Creates a new (empty) time series with the specified name and class of RegularTimePeriod.

Parameters: name the series name (null not permitted). timePeriodClass the type of time period (null not permitted).

TimeSeries

public TimeSeries(Comparable name, String domain, String range, Class timePeriodClass)
Creates a new time series that contains no data.

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.

Parameters: name the name of the series (null not permitted). domain the domain description (null permitted). range the range description (null permitted). timePeriodClass the type of time period (null not permitted).

Method Detail

add

public void add(TimeSeriesDataItem item)
Adds a data item to the series and sends a SeriesChangeEvent to all registered listeners.

Parameters: item the (timeperiod, value) pair (null not permitted).

add

public void add(TimeSeriesDataItem item, boolean notify)
Adds a data item to the series and sends a SeriesChangeEvent to all registered listeners.

Parameters: item the (timeperiod, value) pair (null not permitted). notify notify listeners?

add

public void add(RegularTimePeriod period, double value)
Adds a new data item to the series and sends a SeriesChangeEvent to all registered listeners.

Parameters: period the time period (null not permitted). value the value.

add

public void add(RegularTimePeriod period, double value, boolean notify)
Adds a new data item to the series and sends a SeriesChangeEvent to all registered listeners.

Parameters: period the time period (null not permitted). value the value. notify notify listeners?

add

public void add(RegularTimePeriod period, Number value)
Adds a new data item to the series and sends a SeriesChangeEvent to all registered listeners.

Parameters: period the time period (null not permitted). value the value (null permitted).

add

public void add(RegularTimePeriod period, Number value, boolean notify)
Adds a new data item to the series and sends a SeriesChangeEvent to all registered listeners.

Parameters: period the time period (null not permitted). value the value (null permitted). notify notify listeners?

addAndOrUpdate

public TimeSeries addAndOrUpdate(TimeSeries series)
Adds or updates data from one series to another. Returns another series containing the values that were overwritten.

Parameters: series the series to merge with this.

Returns: A series containing the values that were overwritten.

addOrUpdate

public TimeSeriesDataItem addOrUpdate(RegularTimePeriod period, double value)
Adds or updates an item in the times series and sends a SeriesChangeEvent to all registered listeners.

Parameters: period the time period to add/update (null not permitted). value the new value.

Returns: A copy of the overwritten data item, or null if no item was overwritten.

addOrUpdate

public TimeSeriesDataItem addOrUpdate(RegularTimePeriod period, Number value)
Adds or updates an item in the times series and sends a SeriesChangeEvent to all registered listeners.

Parameters: period the time period to add/update (null not permitted). value the new value (null permitted).

Returns: A copy of the overwritten data item, or null if no item was overwritten.

clear

public void clear()
Removes all data items from the series and sends a SeriesChangeEvent to all registered listeners.

clone

public Object clone()
Returns a clone of the time series.

Notes:

Returns: A clone of the time series.

Throws: CloneNotSupportedException not thrown by this class, but subclasses may differ.

createCopy

public TimeSeries createCopy(int start, int end)
Creates a new timeseries by copying a subset of the data in this time series.

Parameters: start the index of the first time period to copy. end the index of the last time period to copy.

Returns: A series containing a copy of this times series from start until end.

Throws: CloneNotSupportedException if there is a cloning problem.

createCopy

public TimeSeries createCopy(RegularTimePeriod start, RegularTimePeriod end)
Creates a new timeseries by copying a subset of the data in this time series.

Parameters: start the first time period to copy (null not permitted). end the last time period to copy (null not permitted).

Returns: A time series containing a copy of this time series from start until end.

Throws: CloneNotSupportedException if there is a cloning problem.

delete

public void delete(RegularTimePeriod period)
Deletes the data item for the given time period and sends a SeriesChangeEvent to all registered listeners. If there is no item with the specified time period, this method does nothing.

Parameters: period the period of the item to delete (null not permitted).

delete

public void delete(int start, int end)
Deletes data from start until end index (end inclusive).

Parameters: start the index of the first period to delete. end the index of the last period to delete.

equals

public boolean equals(Object object)
Tests the series for equality with an arbitrary object.

Parameters: object the object to test against (null permitted).

Returns: A boolean.

getDataItem

public TimeSeriesDataItem getDataItem(int index)
Returns a data item for the series.

Parameters: index the item index (zero-based).

Returns: The data item.

See Also: getDataItem

getDataItem

public TimeSeriesDataItem getDataItem(RegularTimePeriod period)
Returns the data item for a specific period.

Parameters: period the period of interest (null not allowed).

Returns: The data item matching the specified period (or null if there is no match).

See Also: TimeSeries

getDomainDescription

public String getDomainDescription()
Returns the domain description.

Returns: The domain description (possibly null).

See Also: setDomainDescription

getIndex

public int getIndex(RegularTimePeriod period)
Returns the index for the item (if any) that corresponds to a time period.

Parameters: period the time period (null not permitted).

Returns: The index.

getItemCount

public int getItemCount()
Returns the number of items in the series.

Returns: The item count.

getItems

public List getItems()
Returns the list of data items for the series (the list contains TimeSeriesDataItem objects and is unmodifiable).

Returns: The list of data items.

getMaximumItemAge

public long getMaximumItemAge()
Returns the maximum item age (in time periods) for the series.

Returns: The maximum item age.

See Also: TimeSeries

getMaximumItemCount

public int getMaximumItemCount()
Returns the maximum number of items that will be retained in the series. The default value is Integer.MAX_VALUE.

Returns: The maximum item count.

See Also: TimeSeries

getNextTimePeriod

public RegularTimePeriod getNextTimePeriod()
Returns a time period that would be the next in sequence on the end of the time series.

Returns: The next time period.

getRangeDescription

public String getRangeDescription()
Returns the range description.

Returns: The range description (possibly null).

See Also: setRangeDescription

getTimePeriod

public RegularTimePeriod getTimePeriod(int index)
Returns the time period at the specified index.

Parameters: index the index of the data item.

Returns: The time period.

getTimePeriodClass

public Class getTimePeriodClass()
Returns the time period class for this series.

Only one time period class can be used within a single series (enforced). If you add a data item with a Year for the time period, then all subsequent data items must also have a Year for the time period.

Returns: The time period class (never null).

getTimePeriods

public Collection getTimePeriods()
Returns a collection of all the time periods in the time series.

Returns: A collection of all the time periods.

getTimePeriodsUniqueToOtherSeries

public Collection getTimePeriodsUniqueToOtherSeries(TimeSeries series)
Returns a collection of time periods in the specified series, but not in this series, and therefore unique to the specified series.

Parameters: series the series to check against this one.

Returns: The unique time periods.

getValue

public Number getValue(int index)
Returns the value at the specified index.

Parameters: index index of a value.

Returns: The value (possibly null).

getValue

public Number getValue(RegularTimePeriod period)
Returns the value for a time period. If there is no data item with the specified period, this method will return null.

Parameters: period time period (null not permitted).

Returns: The value (possibly null).

hashCode

public int hashCode()
Returns a hash code value for the object.

Returns: The hashcode

removeAgedItems

public void removeAgedItems(boolean notify)
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.

Parameters: notify controls whether or not a SeriesChangeEvent is sent to registered listeners IF any items are removed.

removeAgedItems

public void removeAgedItems(long latest, boolean notify)
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.

Parameters: latest the time to be compared against when aging data (specified in milliseconds). notify controls whether or not a SeriesChangeEvent is sent to registered listeners IF any items are removed.

setDomainDescription

public void setDomainDescription(String description)
Sets the domain description and sends a PropertyChangeEvent (with the property name Domain) to all registered property change listeners.

Parameters: description the description (null permitted).

See Also: getDomainDescription

setMaximumItemAge

public void setMaximumItemAge(long periods)
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.

Parameters: periods the number of time periods.

See Also: getMaximumItemAge

setMaximumItemCount

public void setMaximumItemCount(int maximum)
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.

Parameters: maximum the maximum (requires >= 0).

See Also: getMaximumItemCount

setRangeDescription

public void setRangeDescription(String description)
Sets the range description and sends a PropertyChangeEvent (with the property name Range) to all registered listeners.

Parameters: description the description (null permitted).

See Also: getRangeDescription

update

public void update(RegularTimePeriod period, Number value)
Updates (changes) the value for a time period. Throws a SeriesException if the period does not exist.

Parameters: period the period (null not permitted). value the value (null permitted).

update

public void update(int index, Number value)
Updates (changes) the value of a data item.

Parameters: index the index of the data item. value the new value (null permitted).