org.jfree.data.time

Class TimeSeries

java.lang.Object

org.jfree.data.general.Series

org.jfree.data.time.TimeSeries

All Implemented Interfaces:

Serializable, Cloneable

public class TimeSeries
extends Series
implements Cloneable, Serializable

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.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
TimeSeries(Comparable name) Creates a new (empty) time series.
TimeSeries(Comparable name, Class timePeriodClass) 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) Creates a new time series that contains no data.
TimeSeries(Comparable name, String domain, String range, Class timePeriodClass) 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.

Method Summary

Modifier and Type	Method and Description
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(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) Adds a 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, double value) Adds or updates an item in the times series and sends a SeriesChangeEvent to all registered listeners.
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(TimeSeriesDataItem item) 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(int start, int end, boolean notify) 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 obj) Tests the series for equality with an arbitrary object.
Range	findValueRange() Returns the range of y-values in the time series.
Range	findValueRange(Range xRange, TimePeriodAnchor xAnchor, TimeZone zone) Finds the range of y-values that fall within the specified range of x-values (where the x-values are interpreted as milliseconds since the epoch and converted to time periods using the specified timezone).
Range	findValueRange(Range xRange, TimeZone timeZone) Returns the range of y-values in the time series that fall within the specified range of x-values.
TimeSeriesDataItem	getDataItem(int index) Returns a data item from the dataset.
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.
double	getMaxY() Returns the largest y-value in the series, ignoring any null and Double.NaN values.
double	getMinY() Returns the smallest y-value in the series, ignoring any null and Double.NaN values.
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(int index, Number value) Updates (changes) the value of a data item.
void	update(RegularTimePeriod period, double value) Updates (changes) the value for a time period.
void	update(RegularTimePeriod period, Number value) Updates (changes) the value for a time period.

Methods inherited from class org.jfree.data.general.Series

addChangeListener, addPropertyChangeListener, addVetoableChangeListener, fireSeriesChanged, getDescription, getKey, getNotify, isEmpty, removeChangeListener, removePropertyChangeListener, removeVetoableChangeListener, setDescription, setKey, setNotify

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

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

Since:

1.0.13

TimeSeries

public TimeSeries(Comparable name,
                  Class timePeriodClass)

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

TimeSeries

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

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

Method Detail

getDomainDescription

public String getDomainDescription()

Returns the domain description.

Returns:

The domain description (possibly null).

See Also:

setDomainDescription(String)

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

getRangeDescription

public String getRangeDescription()

Returns the range description.

Returns:

The range description (possibly null).

See Also:

setRangeDescription(String)

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

getItemCount

public int getItemCount()

Returns the number of items in the series.

Specified by:

getItemCount in class 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.

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:

setMaximumItemCount(int)

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

getMaximumItemAge

public long getMaximumItemAge()

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

Returns:

The maximum item age.

See Also:

setMaximumItemAge(long)

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

findValueRange

public Range findValueRange()

Returns the range of y-values in the time series. Any null data values in the series will be ignored (except for the special case where all data values are null, in which case the return value is Range(Double.NaN, Double.NaN)). If the time series contains no items, this method will return null.

Returns:

The range of y-values in the time series (possibly null).

Since:

1.0.18

findValueRange

public Range findValueRange(Range xRange,
                            TimeZone timeZone)

Returns the range of y-values in the time series that fall within the specified range of x-values. This is equivalent to findValueRange(xRange, TimePeriodAnchor.MIDDLE, timeZone).

Parameters:

xRange - the subrange of x-values (null not permitted).

timeZone - the time zone used to convert x-values to time periods (null not permitted).

Returns:

The range.

Since:

1.0.18

findValueRange

public Range findValueRange(Range xRange,
                            TimePeriodAnchor xAnchor,
                            TimeZone zone)

Finds the range of y-values that fall within the specified range of x-values (where the x-values are interpreted as milliseconds since the epoch and converted to time periods using the specified timezone).

Parameters:

xRange - the subset of x-values to use (null not permitted).

xAnchor - the anchor point for the x-values (null not permitted).

zone - the time zone (null not permitted).

Returns:

The range of y-values.

Since:

1.0.18

getMinY

public double getMinY()

Returns the smallest y-value in the series, ignoring any null and Double.NaN values. This method returns Double.NaN if there is no smallest y-value (for example, when the series is empty).

Returns:

The smallest y-value.

Since:

1.0.14

See Also:

getMaxY()

getMaxY

public double getMaxY()

Returns the largest y-value in the series, ignoring any null and Double.NaN values. This method returns Double.NaN if there is no largest y-value (for example, when the series is empty).

Returns:

The largest y-value.

Since:

1.0.14

See Also:

getMinY()

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

getDataItem

public TimeSeriesDataItem getDataItem(int index)

Returns a data item from the dataset. Note that the returned object is a clone of the item in the series, so modifying it will have no effect on the data series.

Parameters:

index - the item index.

Returns:

The data item.

getDataItem

public TimeSeriesDataItem getDataItem(RegularTimePeriod period)

Returns the data item for a specific period. Note that the returned object is a clone of the item in the series, so modifying it will have no effect on the data series.

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:

getDataItem(int)

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.

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.

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.

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.

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

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?

update

public void update(RegularTimePeriod period,
                   double 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.

Since:

1.0.14

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

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.

addOrUpdate

public TimeSeriesDataItem addOrUpdate(TimeSeriesDataItem item)

Adds or updates an item in the times series and sends a SeriesChangeEvent to all registered listeners.

Parameters:

item - the data item (null not permitted).

Returns:

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

Since:

1.0.14

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.

clear

public void clear()

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

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.

delete

public void delete(int start,
                   int end,
                   boolean notify)

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.

notify - notify listeners?

Since:

1.0.14

clone

public Object clone()
             throws CloneNotSupportedException

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

Overrides:

clone in class Series

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)
                      throws CloneNotSupportedException

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)
                      throws CloneNotSupportedException

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.

equals

public boolean equals(Object obj)

Tests the series for equality with an arbitrary object.

Overrides:

equals in class Series

Parameters:

obj - the object to test against (null permitted).

Returns:

A boolean.

hashCode

public int hashCode()

Returns a hash code value for the object.

Overrides:

hashCode in class Series

Returns:

The hashcode