Class Series

java.lang.Object
com.iizix.prop.GProp<GProp<?>[]>
com.iizix.prop.PropCnr
com.iizix.prop.ui.chart.series.Series
All Implemented Interfaces:
EventListener, IGProp<GProp<?>[]>, IPropCnr, IPropCnrBooleanSettings<SeriesOption>, IPropCnrColorSettings<SeriesColor>, IPropCnrFillSettings<SeriesFill>, IPropCnrFontSettings<SeriesFont>, IPropCnrIntegerSettings<SeriesInteger>, IPropCnrStrokeSettings<SeriesStroke>, IChartContainer, IVSColumnBestValueListener, IVSColumnListener, IVSComponentListener, IVSComponentState, Cloneable
Direct Known Subclasses:
ESeries
public class Series extends PropCnr implements IChartContainer, IPropCnrBooleanSettings<SeriesOption>, IPropCnrIntegerSettings<SeriesInteger>, IPropCnrColorSettings<SeriesColor>, IPropCnrStrokeSettings<SeriesStroke>, IPropCnrFillSettings<SeriesFill>, IPropCnrFontSettings<SeriesFont>, IVSColumnListener
A chart series consists of several series values properties in a defined order. The Designer chart series persists in XML and can be predefined and only modified at runtime with the required settings.

A live series is one a server-side application keeps appending to with appendLive(double...), keeping a window of the last points (setLiveWindow(int,int,boolean)): see the threading contract there.

Author:
Christopher Mindus

  • Field Details

  • Constructor Details

    • Series

      public Series(String name)
      Constructs a new series from a name.
      Parameters:
      name - The name of the series. The name MUST be a valid Atom name.
      Throws:
      NullPointerException - If the name is null.
      IllegalArgumentException - If the name is invalid.

    • Series

      public Series(Atom atom)
      Constructs a new series from an Atom name.

      This constructor is used by the persistence framework and should not be used.

      Parameters:
      atom - The atom name.

    • Series

      public Series()
      Constructs a new series without a name.

      This constructor is used by the persistence framework and should not be used.

  • Method Details

    • usesPropIndex

      public final boolean usesPropIndex()
      Checks if index is relevant for this container, e.g. to keep the values in order.
      Specified by:
      usesPropIndex in interface IPropCnr
      Overrides:
      usesPropIndex in class PropCnr
      Returns:
      true, the series is index-sensitive.

    • getSeriesType

      public SeriesType getSeriesType()
      Gets the series type.
      Returns:
      The series type, or null if undefined.

    • getContainerType

      public final IChartContainer.Type getContainerType()
      Gets the type of container.
      Specified by:
      getContainerType in interface IChartContainer
      Returns:
      Type.SERIES.

    • clone

      public Series clone()
      Clone must be overridden.
      Overrides:
      clone in class PropCnr

    • getValuesList

      public List<GSeriesValue> getValuesList()
      Gets the series values as a list of values.
      Returns:
      A modifiable list with the values. Changing the array will not affect the series.

    • getValues

      public GSeriesValue[] getValues()
      Gets the series values as an array of values.
      Returns:
      An array with the values.

    • getValuesProp

      public SeriesValue getValuesProp(int index)
      Gets the series value property at specified index.
      Parameters:
      index - The index.
      Returns:
      The value property, or null if index is out of bounds.

    • getValue

      public GSeriesValue getValue(int index)
      Gets the series value at specified index.

    • addValue

      public Series addValue(GSeriesValue value)
      Adds a new data series value.
      Parameters:
      value - The new values to add.
      Returns:
      this instance for concatenation use.

    • addValues

      public Series addValues(GSeriesValue... values)
      Adds a new data series values.
      Parameters:
      values - The new values to add.
      Returns:
      this instance for concatenation use.

    • addValue

      public Series addValue(double value)
      Adds a new data series simple value.
      Parameters:
      value - The new simple value to add.
      Returns:
      this instance for concatenation use.

    • addValues

      public Series addValues(double... values)
      Adds a new data series simple values.
      Parameters:
      values - The new simple values to add.
      Returns:
      this instance for concatenation use.

    • addNoValue

      public Series addNoValue()
      Adds a new data point without value, i.e. a null value.
      Returns:
      this instance for concatenation use.

    • removeValue

      public boolean removeValue(int index)
      Remove a value at specified index.
      Parameters:
      index - The index of the value to remove.
      Returns:
      true for success, false for failure (index out of bounds).

    • getValueCount

      public int getValueCount()
      Gets the count of values in the series.
      Returns:
      The count.

    • removeAllValues

      public boolean removeAllValues()
      Removes all the values from the data series.
      Returns:
      true for changed, false for no change (no values present).

    • appendLive

      public boolean appendLive(double... values)
      Appends simple values to a live series, from any thread.

      Threading contract.

      • This method may be called from any thread, typically a sampler thread of the application that is not the application session's worker. It only queues the points and returns.
      • The points are applied on the application session's worker thread, where every property change belongs, in the order of the calls. All the points queued before the worker gets to them are applied in one task, so a burst of calls travels to the client as one transaction.
      • Called on the worker thread itself (an event handler of the application), the points are applied before the call returns.
      • A series not in an application session (not yet added to a chart of a panel, or used on its own as in a unit test) applies the points before the call returns, in the calling thread; concurrent callers are serialised.
      • All other methods of the series (including setLiveWindow(int,int,boolean) and addValue(double)) are ordinary property changes: call them on the worker thread.

      Window. After the points are added, the live window applies (setLiveWindow(int,int,boolean)): the oldest points beyond the window size in points, and the points appended longer ago than the window size in seconds, are removed. The client receives the new points and the removals, and updates the series in the chart it already has.

      Example, a sampler feeding the series once a second:

        series.setLiveWindow(60,0,true);   // On the worker thread, e.g. in OnUICreate.
  ...
  series.appendLive(sample);         // From the sampler thread.

      Parameters:
      values - The values, one point each. A Double.NaN is a point without value.
      Returns:
      true when the points were applied or queued, false when the series is disposed of or its application session is gone: the points are then discarded.

    • appendLive

      public boolean appendLive(GSeriesValue... values)
      Appends values of any type (simple, X/Y, bubble or OHLC) to a live series, from any thread. The threading contract and the window are those of appendLive(double...).

      Example, X/Y points whose X is the sample time in seconds, keeping the last 5 minutes:

        series.setLiveWindow(0,300,true);
  ...
  series.appendLive(new XY(seconds,value));

      Parameters:
      values - The values, one point each; null is a point without value.
      Returns:
      true when the points were applied or queued, false when the series is disposed of or its application session is gone: the points are then discarded.

    • applyLiveWindow

      public boolean applyLiveWindow()
      Applies the live window now: removes the points beyond the window size in points, and those appended longer ago than the window size in seconds. An append does this by itself; this call is for an application timer that lets points expire by age while no new point arrives. The threading contract is that of appendLive(double...).
      Returns:
      true when the window was applied or queued, false when the series is disposed of or its application session is gone.

    • getPendingLiveCount

      public int getPendingLiveCount()
      Gets the count of live points appended and not yet applied: they are waiting for the worker thread. This is a snapshot that may be stale on return.
      Returns:
      The count.

    • setLiveWindow

      public Series setLiveWindow(int maxPoints, int maxSeconds, boolean scroll)
      Sets the live window of the series, applied when live points are appended.

      This is an ordinary property change: call it on the application session's worker thread. The Designer edits the same settings on the series.

      Parameters:
      maxPoints - The window size in points, zero for no limit by count.
      maxSeconds - The window size in seconds, zero for no limit by age.
      scroll - True to apply the window (the oldest points are dropped and the client scrolls), false to keep every point (the chart rescales to show them all).
      Returns:
      this instance for concatenation use.
      Throws:
      IllegalArgumentException - If a size is negative.

    • getLiveMaxPoints

      public int getLiveMaxPoints()
      Gets the live window size in points.
      Returns:
      The size, zero for no limit by count.

    • getLiveMaxSeconds

      public int getLiveMaxSeconds()
      Gets the live window size in seconds.
      Returns:
      The size, zero for no limit by age.

    • isLiveScroll

      public boolean isLiveScroll()
      Returns whether the live window applies (the series scrolls).
      Returns:
      The SeriesOption.LIVE_SCROLL option, default true.

    • setPlot

      public Series setPlot(String name)
      Sets the plot name to associate this series with. If the plot name is not found in the chart, this setting will be ignored.
      Parameters:
      name - The plot name, must be an Atom-valid name. If set to null series will be unassigned from any potential previous plot.
      Returns:
      this instance for concatenation use.
      Throws:
      IllegalArgumentException - If the name is invalid (i.e. must be an Atom-valid name).

    • getPlot

      public String getPlot()
      Gets the plot name to associate this series with.
      Returns:
      The plot name, or null if unassigned.

    • verify

      public boolean verify(PropVerification verification)
      Verifies this property container. The check performed is the extension of classes and that no circular reference is present.
      Specified by:
      verify in interface IGProp<GProp<?>[]>
      Overrides:
      verify in class PropCnr
      Parameters:
      verification - The property verification class.
      Returns:
      true if verification should proceed, false if disposed of and verification should not take place.

    • hasConnection

      public boolean hasConnection(int vs)
      Returns whether this series is with or without VS table connection.
      Parameters:
      vs - The VS connection check: -1 = no matter what type of connection, 0 = no VS connection, 1 = with VS connection.
      Returns:
      true if the data series matches the VS connection check setting, always true when "vs=-1".

    • getVSTable

      public VSTable getVSTable()
      Returns the VS table connection.
      Returns:
      The VS table, or null for none.

    • onResolved

      public void onResolved(VSRelativeReference<?> reference, VSColumnHeader column)
      Called when the property reference has been resolved. UI components use this method to set its state according to the field.
      Specified by:
      onResolved in interface IVSColumnListener
      Parameters:
      reference - The VSRelativeReference instance holding the reference.
      column - The target reference.

    • onBroken

      public void onBroken(VSRelativeReference<?> reference, VSColumnHeader column)
      Called when the property reference has been broken, i.e. unresolved.
      Specified by:
      onBroken in interface IVSColumnListener
      Parameters:
      reference - The VSRelativeReference instance holding the reference.
      column - The target reference.

    • getBestVSColumnHeaderValueType

      public Value.Type getBestVSColumnHeaderValueType(VSRelativeReference<?> reference)
      Requests the value type that would best suit the listener.
      Specified by:
      getBestVSColumnHeaderValueType in interface IVSColumnBestValueListener
      Parameters:
      reference - The VSRelativeReference instance holding the reference.
      Returns:
      null if none is available.

    • onStateChanged

      public void onStateChanged(VSColumnHeader column, IVSComponentState.State state, boolean on)
      Called when the column changes state.
      Specified by:
      onStateChanged in interface IVSColumnListener
      Parameters:
      column - The VS table column.
      state - The state change, possible values ENABLED, READONLY, VISIBLE or SELECTED.
      on - New state.

    • onSingleSelectionChanged

      public void onSingleSelectionChanged(VSColumnHeader column, int rowIndex)
      Called when the row selection in table single-selection mode is changed to forward to column listeners.
      Specified by:
      onSingleSelectionChanged in interface IVSColumnListener
      Parameters:
      column - The column.
      rowIndex - The row index selected, -1 for none.

    • onSelectionChanged

      public void onSelectionChanged(VSColumnHeader column, VSRow row, int rowIndex, boolean isSelected)
      Called when the row selection is changed to forward to column listeners.
      Specified by:
      onSelectionChanged in interface IVSColumnListener
      Parameters:
      column - The column.
      row - The row that was changed.
      rowIndex - The row index.
      isSelected - The selected state.

    • onRowAdded

      public void onRowAdded(VSColumnHeader column, VSRow row, int rowIndex)
      Called when a row has been added to the table.
      Specified by:
      onRowAdded in interface IVSColumnListener
      Parameters:
      column - The column.
      row - The row that was added.
      rowIndex - The row index where it was inserted.

    • onRowRemoved

      public void onRowRemoved(VSColumnHeader column, VSRow row, int rowIndex)
      Called when a row has been removed from the table.
      Specified by:
      onRowRemoved in interface IVSColumnListener
      Parameters:
      column - The column.
      row - The row that was removed.
      rowIndex - The row index before removal.

    • onStateChanged

      public void onStateChanged(VSColumnHeader column, VSField cell, IVSComponentState.State state, boolean on)
      Called when a cell in the column changes state.
      Specified by:
      onStateChanged in interface IVSColumnListener
      Parameters:
      column - The VS column.
      cell - The VS field.
      state - The state change.
      on - New state.

    • onCellValueChanged

      public void onCellValueChanged(VSColumnHeader column, VSField cell, Value value, GProp<?> trigger, IPostEventProcessing postProcessing)
      Called when the cell value is set in the column.
      Specified by:
      onCellValueChanged in interface IVSColumnListener
      Parameters:
      column - The VS column.
      cell - The VS field.
      value - The value, never null, but value.isNull() could be true.
      trigger - The trigger property that may be null.
      postProcessing - Post-processing instance.

    • onParentStateChanged

      public void onParentStateChanged(IVSComponent parent, IVSComponentState.State state, boolean on)
      Called when the parent changes state.
      Specified by:
      onParentStateChanged in interface IVSComponentListener
      Parameters:
      parent - The parent who's state was changed.
      state - The state change, possible values PARENT_ENABLED, PARENT_READONLY, PARENT_VISIBLE.
      on - New state.

    • updateContents

      public void updateContents()
      Called to update the data series with new data from the connected VS table.