org.jfree.data.time
Class TimeSeries

java.lang.Object
  |
  +--org.jfree.data.Series
        |
        +--org.jfree.data.time.TimeSeries

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable

public class TimeSeries

extends Series

implements java.io.Serializable

Represents a sequence of zero or more data items in the form (period, value).

Author:

David Gilbert

See Also:

Serialized Form

Field Summary

protected static java.lang.String	DEFAULT_DOMAIN_DESCRIPTION Default value for the domain description.
protected static java.lang.String	DEFAULT_RANGE_DESCRIPTION Default value for the range description.

Constructor Summary

TimeSeries(java.lang.String name)
Creates a new (empty) time series.

TimeSeries(java.lang.String name, java.lang.Class timePeriodClass)
Creates a new (empty) time series.

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

Method Summary

void	add(RegularTimePeriod period, double value) Adds a new data item to the series.
void	add(RegularTimePeriod period, java.lang.Number value) Adds a new data item to the series.
void	add(TimeSeriesDataItem pair) Adds a data item to the series.
TimeSeries	addAndOrUpdate(TimeSeries series) Adds or updates data from one series to another.
TimeSeriesDataItem	addOrUpdate(RegularTimePeriod period, java.lang.Number value) Adds or updates the times series.
java.lang.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 data for the given time period.
boolean	equals(java.lang.Object target) Tests this time series for equality with another object.
TimeSeriesDataItem	getDataPair(int index) Returns one data pair for the series.
TimeSeriesDataItem	getDataPair(RegularTimePeriod period) Returns the data pair for a specific period.
java.lang.String	getDomainDescription() Returns the domain description.
int	getHistoryCount() Returns the history count for the series.
int	getIndex(RegularTimePeriod period) Returns the index of the specified time period.
int	getItemCount() Returns the number of items in 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.
java.lang.String	getRangeDescription() Returns the range description.
RegularTimePeriod	getTimePeriod(int index) Returns the time period at the specified index.
java.lang.Class	getTimePeriodClass() Returns the time period class for this series.
java.util.Collection	getTimePeriods() Returns a collection of all the time periods in the time series.
java.util.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.
java.lang.Number	getValue(int index) Returns the value at the specified index.
java.lang.Number	getValue(RegularTimePeriod period) Returns the value for a time period.
void	setDomainDescription(java.lang.String description) Sets the domain description.
void	setHistoryCount(int 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(java.lang.String description) Sets the range description.
void	update(int index, java.lang.Number value) Updates (changes) the value of a data pair.
void	update(RegularTimePeriod period, java.lang.Number value) Updates (changes) the value for a time period.

Methods inherited from class org.jfree.data.Series

addChangeListener, addPropertyChangeListener, firePropertyChange, fireSeriesChanged, getDescription, getName, notifyListeners, removeChangeListener, removePropertyChangeListener, setDescription, setName

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_DOMAIN_DESCRIPTION

protected static final java.lang.String DEFAULT_DOMAIN_DESCRIPTION

Default value for the domain description.

See Also:

Constant Field Values

DEFAULT_RANGE_DESCRIPTION

protected static final java.lang.String DEFAULT_RANGE_DESCRIPTION

Default value for the range description.

See Also:

Constant Field Values

Constructor Detail

TimeSeries

public TimeSeries(java.lang.String 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 name of the series.

TimeSeries

public TimeSeries(java.lang.String name,
                  java.lang.Class timePeriodClass)

Creates a new (empty) time series.

Parameters:

name - the series name.

timePeriodClass - the type of time period.

TimeSeries

public TimeSeries(java.lang.String name,
                  java.lang.String domain,
                  java.lang.String range,
                  java.lang.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.

domain - the domain description.

range - the range description.

timePeriodClass - the type of time period.

Method Detail

getDomainDescription

public java.lang.String getDomainDescription()

Returns the domain description.

Returns:

the domain description.

setDomainDescription

public void setDomainDescription(java.lang.String description)

Sets the domain description.

A property change event is fired, and an undoable edit is posted.

Parameters:

description - the new description.

getRangeDescription

public java.lang.String getRangeDescription()

Returns the range description.

Returns:

the range description.

setRangeDescription

public void setRangeDescription(java.lang.String description)

Sets the range description.

Registered listeners are notified of the change.

Parameters:

description - the new description.

getItemCount

public int getItemCount()

Returns the number of items in the series.

Returns:

the item count.

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.

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.

getHistoryCount

public int getHistoryCount()

Returns the history count for the series.

Returns:

the history count.

setHistoryCount

public void setHistoryCount(int 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.

getTimePeriodClass

public java.lang.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 for this series (null if the series is empty).

getDataPair

public TimeSeriesDataItem getDataPair(int index)

Returns one data pair for the series.

Parameters:

index - the item index (zero-based).

Returns:

one data pair for the series.

getDataPair

public TimeSeriesDataItem getDataPair(RegularTimePeriod period)

Returns the data pair for a specific period.

Parameters:

period - the period of interest.

Returns:

the data pair matching the specified period (or null if there is no match).

getTimePeriod

public RegularTimePeriod getTimePeriod(int index)

Returns the time period at the specified index.

Parameters:

index - the index of the data pair.

Returns:

the time period at the specified index.

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 java.util.Collection getTimePeriods()

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

Returns:

a collection of all the time periods.

getTimePeriodsUniqueToOtherSeries

public java.util.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 series minus 'this'.

getIndex

public int getIndex(RegularTimePeriod period)

Returns the index of the specified time period.

Parameters:

period - time period to lookup.

Returns:

the index of the specified time period.

getValue

public java.lang.Number getValue(int index)

Returns the value at the specified index.

Parameters:

index - index of a value.

Returns:

the value at the specified index.

getValue

public java.lang.Number getValue(RegularTimePeriod period)

Returns the value for a time period.

Parameters:

period - time period to lookup.

Returns:

the value or null if the time period is not in the series.

add

public void add(TimeSeriesDataItem pair)
         throws SeriesException

Adds a data item to the series.

Parameters:

pair - the (timeperiod, value) pair.

Throws:

SeriesException - if there is a problem adding the data.

add

public void add(RegularTimePeriod period,
                double value)
         throws SeriesException

Adds a new data item to the series.

Parameters:

period - the time period.

value - the value.

Throws:

SeriesException - if there is a problem adding the data.

add

public void add(RegularTimePeriod period,
                java.lang.Number value)
         throws SeriesException

Adds a new data item to the series.

Parameters:

period - the time period.

value - the value.

Throws:

SeriesException - if there is a problem adding the data.

update

public void update(RegularTimePeriod period,
                   java.lang.Number value)
            throws SeriesException

Updates (changes) the value for a time period. Ignores the update if the period does not exist.

Parameters:

period - the period to update.

value - the new value.

Throws:

SeriesException - if there is a problem adding the data.

update

public void update(int index,
                   java.lang.Number value)

Updates (changes) the value of a data pair.

Parameters:

index - the index of the data pair to update.

value - the new value.

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:

series containing the values that were overwritten.

addOrUpdate

public TimeSeriesDataItem addOrUpdate(RegularTimePeriod period,
                                      java.lang.Number value)

Adds or updates the times series.

Parameters:

period - the time period to add/update.

value - the new value.

Returns:

a copy of the overwritten data pair (or null).

delete

public void delete(RegularTimePeriod period)

Deletes data for the given time period.

Parameters:

period - period to delete.

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.

clone

public java.lang.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).

Overrides:

clone in class Series

Returns:

a clone of the time series.

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.

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.

end - the last time period to copy.

Returns:

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

equals

public boolean equals(java.lang.Object target)

Tests this time series for equality with another object.

Overrides:

equals in class java.lang.Object

Parameters:

target - the other object.

Returns:

A boolean.