Package org.jfree.data.time
Class TimeSeries
- java.lang.Object
-
- org.jfree.data.general.Series
-
- org.jfree.data.time.TimeSeries
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Cloneable
public class TimeSeries extends Series implements java.lang.Cloneable, java.io.Serializable
Represents a sequence of zero or more data items in the form (period, value) where 'period' is some instance of a subclass ofRegularTimePeriod
. 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
-
-
Field Summary
Fields Modifier and Type Field Description protected java.util.List
data
The list of data items in the series.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.private java.lang.String
domain
A description of the domain.private long
maximumItemAge
The maximum age of items for the series, specified as a number of time periods.private int
maximumItemCount
The maximum number of items for the series.private double
maxY
The maximum y-value in the series.private double
minY
The minimum y-value in the series.private java.lang.String
range
A description of the range.private static long
serialVersionUID
For serialization.protected java.lang.Class
timePeriodClass
The type of period for the data.
-
Constructor Summary
Constructors Constructor Description TimeSeries(java.lang.Comparable name)
Creates a new (empty) time series.TimeSeries(java.lang.Comparable name, java.lang.String domain, java.lang.String range)
Creates a new time series that contains no data.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
add(RegularTimePeriod period, double value)
Adds a new data item to the series and sends aSeriesChangeEvent
to all registered listeners.void
add(RegularTimePeriod period, double value, boolean notify)
Adds a new data item to the series and sends aSeriesChangeEvent
to all registered listeners.void
add(RegularTimePeriod period, java.lang.Number value)
Adds a new data item to the series and sends aSeriesChangeEvent
to all registered listeners.void
add(RegularTimePeriod period, java.lang.Number value, boolean notify)
Adds a new data item to the series and sends aSeriesChangeEvent
to all registered listeners.void
add(TimeSeriesDataItem item)
Adds a data item to the series and sends aSeriesChangeEvent
to all registered listeners.void
add(TimeSeriesDataItem item, boolean notify)
Adds a data item to the series and sends aSeriesChangeEvent
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 aSeriesChangeEvent
to all registered listeners.TimeSeriesDataItem
addOrUpdate(RegularTimePeriod period, java.lang.Number value)
Adds or updates an item in the times series and sends aSeriesChangeEvent
to all registered listeners.TimeSeriesDataItem
addOrUpdate(TimeSeriesDataItem item)
Adds or updates an item in the times series and sends aSeriesChangeEvent
to all registered listeners.void
clear()
Removes all data items from the series and sends aSeriesChangeEvent
to all registered listeners.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(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 aSeriesChangeEvent
to all registered listeners.boolean
equals(java.lang.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, java.util.TimeZone timeZone)
Returns the range of y-values in the time series that fall within the specified range of x-values.Range
findValueRange(Range xRange, TimePeriodAnchor xAnchor, java.util.Calendar calendar)
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 calendar).Range
findValueRange(Range xRange, TimePeriodAnchor xAnchor, java.util.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).TimeSeriesDataItem
getDataItem(int index)
Returns a data item from the dataset.TimeSeriesDataItem
getDataItem(RegularTimePeriod period)
Returns the data item for a specific period.java.lang.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.java.util.List
getItems()
Returns the list of data items for the series (the list containsTimeSeriesDataItem
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 anynull
andDouble.NaN
values.double
getMinY()
Returns the smallest y-value in the series, ignoring anynull
andDouble.NaN
values.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.(package private) TimeSeriesDataItem
getRawDataItem(int index)
Returns a data item for the series.(package private) TimeSeriesDataItem
getRawDataItem(RegularTimePeriod period)
Returns a data item for the series.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.int
hashCode()
Returns a hash code value for the object.private double
maxIgnoreNaN(double a, double b)
A function to find the maximum of two values, but ignoring any Double.NaN values.private double
minIgnoreNaN(double a, double b)
A function to find the minimum of two values, but ignoring any Double.NaN values.void
removeAgedItems(boolean notify)
Age items in the series.void
removeAgedItems(long latest, boolean notify)
Age items in the series.void
setDomainDescription(java.lang.String description)
Sets the domain description and sends aPropertyChangeEvent
(with the property nameDomain
) 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(java.lang.String description)
Sets the range description and sends aPropertyChangeEvent
(with the property nameRange
) to all registered listeners.void
update(int index, java.lang.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, java.lang.Number value)
Updates (changes) the value for a time period.private void
updateBoundsForAddedItem(TimeSeriesDataItem item)
Updates the cached values for the minimum and maximum data values.private void
updateBoundsForRemovedItem(TimeSeriesDataItem item)
Updates the cached values for the minimum and maximum data values on the basis that the specified item has just been removed.private void
updateMinMaxYByIteration()
Finds the bounds of the x and y values for the series, by iterating through all the data items.-
Methods inherited from class org.jfree.data.general.Series
addChangeListener, addPropertyChangeListener, addVetoableChangeListener, canEqual, firePropertyChange, fireSeriesChanged, fireVetoableChange, getDescription, getKey, getNotify, isEmpty, notifyListeners, removeChangeListener, removePropertyChangeListener, removeVetoableChangeListener, setDescription, setKey, setNotify
-
-
-
-
Field Detail
-
serialVersionUID
private static final long serialVersionUID
For serialization.- See Also:
- Constant Field Values
-
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
-
domain
private java.lang.String domain
A description of the domain.
-
range
private java.lang.String range
A description of the range.
-
timePeriodClass
protected java.lang.Class timePeriodClass
The type of period for the data.
-
data
protected java.util.List data
The list of data items in the series.
-
maximumItemCount
private int maximumItemCount
The maximum number of items for the series.
-
maximumItemAge
private long maximumItemAge
The maximum age of items for the series, specified as a number of time periods.
-
minY
private double minY
The minimum y-value in the series.
-
maxY
private double maxY
The maximum y-value in the series.
-
-
Constructor Detail
-
TimeSeries
public TimeSeries(java.lang.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(java.lang.Comparable name, java.lang.String domain, java.lang.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).
-
-
Method Detail
-
getDomainDescription
public java.lang.String getDomainDescription()
Returns the domain description.- Returns:
- The domain description (possibly
null
). - See Also:
setDomainDescription(String)
-
setDomainDescription
public void setDomainDescription(java.lang.String description)
Sets the domain description and sends aPropertyChangeEvent
(with the property nameDomain
) to all registered property change listeners.- Parameters:
description
- the description (null
permitted).- See Also:
getDomainDescription()
-
getRangeDescription
public java.lang.String getRangeDescription()
Returns the range description.- Returns:
- The range description (possibly
null
). - See Also:
setRangeDescription(String)
-
setRangeDescription
public void setRangeDescription(java.lang.String description)
Sets the range description and sends aPropertyChangeEvent
(with the property nameRange
) 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 classSeries
- Returns:
- The item count.
-
getItems
public java.util.List getItems()
Returns the list of data items for the series (the list containsTimeSeriesDataItem
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 isInteger.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. Anynull
orDouble.NaN
data values in the series will be ignored (except for the special case where all data values arenull
, in which case the return value isRange(Double.NaN, Double.NaN)
). If the time series contains no items, this method will returnnull
.- Returns:
- The range of y-values in the time series (possibly
null
).
-
findValueRange
public Range findValueRange(Range xRange, java.util.TimeZone timeZone)
Returns the range of y-values in the time series that fall within the specified range of x-values. This is equivalent tofindValueRange(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.
-
findValueRange
public Range findValueRange(Range xRange, TimePeriodAnchor xAnchor, java.util.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.
-
findValueRange
public Range findValueRange(Range xRange, TimePeriodAnchor xAnchor, java.util.Calendar calendar)
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 calendar).- Parameters:
xRange
- the subset of x-values to use (null
not permitted).xAnchor
- the anchor point for the x-values (null
not permitted).calendar
- the calendar (null
not permitted).- Returns:
- The range of y-values.
-
getMinY
public double getMinY()
Returns the smallest y-value in the series, ignoring anynull
andDouble.NaN
values. This method returnsDouble.NaN
if there is no smallest y-value (for example, when the series is empty).- Returns:
- The smallest y-value.
- See Also:
getMaxY()
-
getMaxY
public double getMaxY()
Returns the largest y-value in the series, ignoring anynull
andDouble.NaN
values. This method returnsDouble.NaN
if there is no largest y-value (for example, when the series is empty).- Returns:
- The largest y-value.
- See Also:
getMinY()
-
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 aYear
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)
-
getRawDataItem
TimeSeriesDataItem getRawDataItem(int index)
Returns a data item for the series. This method returns the object that is used for the underlying storage - you should not modify the contents of the returned value unless you know what you are doing.- Parameters:
index
- the item index (zero-based).- Returns:
- The data item.
- See Also:
getDataItem(int)
-
getRawDataItem
TimeSeriesDataItem getRawDataItem(RegularTimePeriod period)
Returns a data item for the series. This method returns the object that is used for the underlying storage - you should not modify the contents of the returned value unless you know what you are doing.- Parameters:
period
- the item index (zero-based).- Returns:
- The data item.
- See Also:
getDataItem(RegularTimePeriod)
-
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 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 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 java.lang.Number getValue(int index)
Returns the value at the specified index.- Parameters:
index
- index of a value.- Returns:
- The value (possibly
null
).
-
getValue
public java.lang.Number getValue(RegularTimePeriod period)
Returns the value for a time period. If there is no data item with the specified period, this method will returnnull
.- 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 aSeriesChangeEvent
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 aSeriesChangeEvent
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 aSeriesChangeEvent
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 aSeriesChangeEvent
to all registered listeners.- Parameters:
period
- the time period (null
not permitted).value
- the value.notify
- notify listeners?
-
add
public void add(RegularTimePeriod period, java.lang.Number value)
Adds a new data item to the series and sends aSeriesChangeEvent
to all registered listeners.- Parameters:
period
- the time period (null
not permitted).value
- the value (null
permitted).
-
add
public void add(RegularTimePeriod period, java.lang.Number value, boolean notify)
Adds a new data item to the series and sends aSeriesChangeEvent
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 aSeriesException
if the period does not exist.- Parameters:
period
- the period (null
not permitted).value
- the value.
-
update
public void update(RegularTimePeriod period, java.lang.Number value)
Updates (changes) the value for a time period. Throws aSeriesException
if the period does not exist.- Parameters:
period
- the period (null
not permitted).value
- the value (null
permitted).
-
update
public void update(int index, java.lang.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 aSeriesChangeEvent
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, java.lang.Number value)
Adds or updates an item in the times series and sends aSeriesChangeEvent
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 aSeriesChangeEvent
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.
-
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 aSeriesChangeEvent
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 aSeriesChangeEvent
is sent to registered listeners IF any items are removed.
-
clear
public void clear()
Removes all data items from the series and sends aSeriesChangeEvent
to all registered listeners.
-
delete
public void delete(RegularTimePeriod period)
Deletes the data item for the given time period and sends aSeriesChangeEvent
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?
-
clone
public java.lang.Object clone() throws java.lang.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).
-
createCopy
public TimeSeries createCopy(int start, int end) throws java.lang.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:
java.lang.CloneNotSupportedException
- if there is a cloning problem.
-
createCopy
public TimeSeries createCopy(RegularTimePeriod start, RegularTimePeriod end) throws java.lang.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:
java.lang.CloneNotSupportedException
- if there is a cloning problem.
-
equals
public boolean equals(java.lang.Object obj)
Tests the series for equality with an arbitrary object.
-
hashCode
public int hashCode()
Returns a hash code value for the object.
-
updateBoundsForAddedItem
private void updateBoundsForAddedItem(TimeSeriesDataItem item)
Updates the cached values for the minimum and maximum data values.- Parameters:
item
- the item added (null
not permitted).
-
updateBoundsForRemovedItem
private void updateBoundsForRemovedItem(TimeSeriesDataItem item)
Updates the cached values for the minimum and maximum data values on the basis that the specified item has just been removed.- Parameters:
item
- the item added (null
not permitted).
-
updateMinMaxYByIteration
private void updateMinMaxYByIteration()
Finds the bounds of the x and y values for the series, by iterating through all the data items.
-
minIgnoreNaN
private double minIgnoreNaN(double a, double b)
A function to find the minimum of two values, but ignoring any Double.NaN values.- Parameters:
a
- the first value.b
- the second value.- Returns:
- The minimum of the two values.
-
maxIgnoreNaN
private double maxIgnoreNaN(double a, double b)
A function to find the maximum of two values, but ignoring any Double.NaN values.- Parameters:
a
- the first value.b
- the second value.- Returns:
- The maximum of the two values.
-
-