Package org.jfree.data.time

Class TimeSeries

java.lang.Object
org.jfree.data.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).
See Also:
Serialized Form

  • Constructor Details

    • TimeSeries

      public TimeSeries​(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 series name (null not permitted).

    • TimeSeries

      public TimeSeries​(String name, Class timePeriodClass)
      Creates a new (empty) time series.
      Parameters:
      name - the series name (null not permitted).
      timePeriodClass - the type of time period (null not permitted).

    • TimeSeries

      public TimeSeries​(String 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 Details

    • getDomainDescription

      public String getDomainDescription()
      Returns the domain description.
      Returns:
      The domain description (possibly null).

    • setDomainDescription

      public void setDomainDescription​(String description)
      Sets the domain description.

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

      Parameters:
      description - the description (null permitted).

    • getRangeDescription

      public String getRangeDescription()
      Returns the range description.
      Returns:
      The range description (possibly null).

    • setRangeDescription

      public void setRangeDescription​(String description)
      Sets the range description and fires a property change event for the 'Range' property.
      Parameters:
      description - the description (null permitted).

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

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

    • getDataItem

      public TimeSeriesDataItem getDataItem​(int index)
      Returns a data item for the series.
      Parameters:
      index - the item index (zero-based).
      Returns:
      The data item.

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

    • 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 registerd listeners.
      Parameters:
      item - the (timeperiod, value) pair (null not permitted).

    • add

      public void add​(RegularTimePeriod period, double value)
      Adds a new data item to the series and sends a SeriesChangeEvent to all registerd listeners.
      Parameters:
      period - the time period (null not permitted).
      value - the value.

    • add

      public void add​(RegularTimePeriod period, Number value)
      Adds a new data item to the series and sends a SeriesChangeEvent to all registerd listeners.
      Parameters:
      period - the time period (null not permitted).
      value - the value (null permitted).

    • 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 listenrs.
      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 listenrs.
      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.

    • ageHistoryCountItems

      public void ageHistoryCountItems()
      Age items in the series. Ensure that the timespan from the youngest to the oldest record in the series does not exceed history count. oldest items will be removed if required.

    • ageHistoryCountItems

      public void ageHistoryCountItems​(long latest)
      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.

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

    • 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.
      end - the last time period to copy.
      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 object)
      Tests the series for equality with an arbitrary object.
      Overrides:
      equals in class Series
      Parameters:
      object - 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

    • getDataPair

      public TimeSeriesDataItem getDataPair​(int index)
      Deprecated.
      Use getDataItem(int).
      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)
      Deprecated.
      Use getDataItem(RegularTimePeriod).
      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).