public class

TimeSeries

extends Series
implements Serializable Cloneable
java.lang.Object
   ↳ org.jfree.data.general.Series
     ↳ org.jfree.data.time.TimeSeries

Class Overview

Represents a sequence of zero or more data items in the form (period, value) where 'period' is some instance of a subclass of RegularTimePeriod. The time series will ensure that (a) all data items have the same type of period (for example, Day) and (b) that each period appears at most one time in the series.

Summary

Constants
String DEFAULT_DOMAIN_DESCRIPTION Default value for the domain description.
String DEFAULT_RANGE_DESCRIPTION Default value for the range description.
Fields
protected List data The list of data items in the series.
protected Class timePeriodClass The type of period for the data.
Public Constructors
TimeSeries(Comparable name)
Creates a new (empty) time series.
TimeSeries(Comparable name, String domain, String range)
Creates a new time series that contains no data.
TimeSeries(Comparable name, Class timePeriodClass)
This constructor is deprecated. As of 1.0.13, it is not necessary to specify the timePeriodClass as this will be inferred when the first data item is added to the dataset.
TimeSeries(Comparable name, String domain, String range, Class timePeriodClass)
This constructor is deprecated. As of 1.0.13, it is not necessary to specify the timePeriodClass as this will be inferred when the first data item is added to the dataset.
Public Methods
void add(RegularTimePeriod period, double value)
Adds a new data item to the series and sends a SeriesChangeEvent to all registered listeners.
void add(RegularTimePeriod period, double value, boolean notify)
Adds a new data item to the series and sends a SeriesChangeEvent to all registered listeners.
void add(RegularTimePeriod period, Number value)
Adds a new data item to the series and sends a SeriesChangeEvent to all registered listeners.
void add(TimeSeriesDataItem item)
Adds a data item to the series and sends a SeriesChangeEvent to all registered listeners.
void add(RegularTimePeriod period, Number value, boolean notify)
Adds a new data item to the series and sends a SeriesChangeEvent to all registered listeners.
void add(TimeSeriesDataItem item, boolean notify)
Adds a data item to the series and sends a SeriesChangeEvent to all registered listeners.
TimeSeries addAndOrUpdate(TimeSeries series)
Adds or updates data from one series to another.
TimeSeriesDataItem addOrUpdate(RegularTimePeriod period, Number value)
Adds or updates an item in the times series and sends a SeriesChangeEvent to all registered listeners.
TimeSeriesDataItem addOrUpdate(RegularTimePeriod period, double value)
Adds or updates an item in the times series and sends a SeriesChangeEvent to all registered listeners.
void clear()
Removes all data items from the series and sends a SeriesChangeEvent to all registered listeners.
Object clone()
Returns a clone of the time series.
TimeSeries createCopy(int start, int end)
Creates a new timeseries by copying a subset of the data in this time series.
TimeSeries createCopy(RegularTimePeriod start, RegularTimePeriod end)
Creates a new timeseries by copying a subset of the data in this time series.
void delete(int start, int end)
Deletes data from start until end index (end inclusive).
void delete(RegularTimePeriod period)
Deletes the data item for the given time period and sends a SeriesChangeEvent to all registered listeners.
boolean equals(Object object)
Tests the series for equality with an arbitrary object.
TimeSeriesDataItem getDataItem(int index)
Returns a data item for the series.
TimeSeriesDataItem getDataItem(RegularTimePeriod period)
Returns the data item for a specific period.
String getDomainDescription()
Returns the domain description.
int getIndex(RegularTimePeriod period)
Returns the index for the item (if any) that corresponds to a time period.
int getItemCount()
Returns the number of items in the series.
List getItems()
Returns the list of data items for the series (the list contains TimeSeriesDataItem objects and is unmodifiable).
long getMaximumItemAge()
Returns the maximum item age (in time periods) for the series.
int getMaximumItemCount()
Returns the maximum number of items that will be retained in the series.
RegularTimePeriod getNextTimePeriod()
Returns a time period that would be the next in sequence on the end of the time series.
String getRangeDescription()
Returns the range description.
RegularTimePeriod getTimePeriod(int index)
Returns the time period at the specified index.
Class getTimePeriodClass()
Returns the time period class for this series.
Collection getTimePeriods()
Returns a collection of all the time periods in the time series.
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.
Number getValue(int index)
Returns the value at the specified index.
Number getValue(RegularTimePeriod period)
Returns the value for a time period.
int hashCode()
Returns a hash code value for the object.
void removeAgedItems(boolean notify)
Age items in the series.
void removeAgedItems(long latest, boolean notify)
Age items in the series.
void setDomainDescription(String description)
Sets the domain description and sends a PropertyChangeEvent (with the property name Domain) to all registered property change listeners.
void setMaximumItemAge(long periods)
Sets the number of time units in the 'history' for the series.
void setMaximumItemCount(int maximum)
Sets the maximum number of items that will be retained in the series.
void setRangeDescription(String description)
Sets the range description and sends a PropertyChangeEvent (with the property name Range) to all registered listeners.
void update(RegularTimePeriod period, Number value)
Updates (changes) the value for a time period.
void update(int index, Number value)
Updates (changes) the value of a data item.
[Expand]
Inherited Methods
From class org.jfree.data.general.Series
From class java.lang.Object

Constants

protected static final String DEFAULT_DOMAIN_DESCRIPTION

Default value for the domain description.

Constant Value: "Time"

protected static final String DEFAULT_RANGE_DESCRIPTION

Default value for the range description.

Constant Value: "Value"

Fields

protected List data

The list of data items in the series.

protected Class timePeriodClass

The type of period for the data.

Public Constructors

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).

public TimeSeries (Comparable name, String domain, String range)

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).

public TimeSeries (Comparable name, Class timePeriodClass)

This constructor is deprecated.
As of 1.0.13, it is not necessary to specify the timePeriodClass as this will be inferred when the first data item is added to the dataset.

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).

public TimeSeries (Comparable name, String domain, String range, Class timePeriodClass)

This constructor is deprecated.
As of 1.0.13, it is not necessary to specify the timePeriodClass as this will be inferred when the first data item is added to the dataset.

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).

Public Methods

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.

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?

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).

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).

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?

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?

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.

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.

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.

public void clear ()

Removes all data items from the series and sends a SeriesChangeEvent to all registered listeners.

public Object clone ()

Returns a clone of the time series.

Notes:

  • no need to clone the domain and range descriptions, since String object is immutable;
  • we pass over to the more general method clone(start, end).

Returns
  • A clone of the time series.
Throws
CloneNotSupportedException not thrown by this class, but subclasses may differ.

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.

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.

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.

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).

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.

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

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

public String getDomainDescription ()

Returns the domain description.

Returns
  • The domain description (possibly null).
See Also

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.

public int getItemCount ()

Returns the number of items in the series.

Returns
  • The item count.

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.

public long getMaximumItemAge ()

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

Returns
  • The maximum item age.
See Also

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

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.

public String getRangeDescription ()

Returns the range description.

Returns
  • The range description (possibly null).
See Also

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.

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 (may be null but only for an empty series).

public Collection getTimePeriods ()

Returns a collection of all the time periods in the time series.

Returns
  • A collection of all the time periods.

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.

public Number getValue (int index)

Returns the value at the specified index.

Parameters
index index of a value.
Returns
  • The value (possibly null).

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).

public int hashCode ()

Returns a hash code value for the object.

Returns
  • The hashcode

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.

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.

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

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

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

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

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).

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).