Package com.luciad.lucy.addons.previewer

Class TLcyPreviewAddOn

java.lang.Object
com.luciad.lucy.addons.ALcyAddOn
com.luciad.lucy.addons.previewer.TLcyPreviewAddOn
All Implemented Interfaces:
ILcdPropertyChangeSource
public class TLcyPreviewAddOn extends ALcyAddOn implements ILcdPropertyChangeSource

This add-on allows you to work with real-time data: it provides UI for playing back real-time data through time, and updates the data in the view accordingly.

The TLcyPreviewAddOn is basically a wrapper around a TLcdSimulator instance. It provides similar methods, such as methods to set the current time, to control the time factor, to start and stop() the simulator, and so on.

The main difference with the TLcdSimulator is that the TLcyPreviewAddOn has built-in support for controlling multiple real-time models at the same time. The preview add-on also provides a customizable UI to control the time in the Lucy application.

Registering real-time data

There are 2 ways to register your real-time data with this add-on. Once your data is registered, both the API methods of this add-on and the UI controlled by the end user will work on your data.

Using ILcdMultiDimensionalModel instances

This add-on automatically detects all the ILcdMultiDimensionalModel instances with a TLcdDimensionAxis of type Date added to a view in Lucy. Each time the date of the TLcdSimulator changes, the multi-dimensional model will be filtered on its time dimension.

This is the recommended way to add support for your own real-time data format in Lucy. Note that no extra work is required if the ILcdModel instances of your custom real-time data format also implement ILcdMultiDimensionalModel. That mechanism is illustrated in the trajectory sample.

Internally, the preview add-on creates an ILcdSimulatorModel instance for the ILcdMultiDimensionalModel, and registers that with the TLcdSimulator (also known as the adapter design pattern). The ILcdSimulatorModel is exposed in the various API methods of the preview add-on API. For example, if you call getSimulatorModelCount(), the count will include the ILcdSimulatorModel instances representing the ILcdMultiDimensionalModels.

Using ILcdSimulatorModel instances

You can create your own ILcdSimulatorModel instances and register (and de-register) them with the TLcyPreviewAddOn directly. This mechanism allows you to decide when you make the simulator model available to the preview add-on and when you do not.

An example use case is a layer that wants to update itself (or its model) based on the current time while the ILcdModel does not implement ILcdMultiDimensionalModel. To handle that case, add an ILcdSimulatorModel to the preview add-on, and let that simulator model update the layer each time its ILcdSimulatorModel.setDate(Date) method is called.

You can also install a filter that decides which simulator models are taken into account in the UI. An example filter is shown below. 

  static class ModelFilter implements ILcdFilter<ILcdSimulatorModel>, ILcdChangeSource {

    private TLcdChangeSupport fChangeSupport = new TLcdChangeSupport();

    @Override
    public boolean accept(ILcdSimulatorModel aModel) {
      // adjust this method to do per-model filtering
      // notify the previewer of any changes by calling
      // fChangeSupport#fireChangeEvent
      return true;
    }

    @Override
    public void addChangeListener(ILcdChangeListener aListener) {
      fChangeSupport.addChangeListener(aListener);
    }

    @Override
    public void removeChangeListener(ILcdChangeListener aListener) {
      fChangeSupport.removeChangeListener(aListener);
    }
  }

Customizing the UI

You can modify the user interface by extending the TLcyPreviewAddOnCustomizerFactory. That factory is responsible for creating the UI, and exposes the creation process in several small protected methods. Override the method corresponding to the UI element you want to customize, and return a custom component. This mechanism is very similar to the ALcyGUIFactory mechanism.

You must either configure your custom TLcyPreviewAddOnCustomizerFactory extension in the configuration file 


   previewer.previewAddOnCustomizerFactoryName = mypackage.CustomPreviewAddOnCustomizerFactory

or set it on this add-on using the API.

The user can open the UI through a menu item. The location of this menu item is configurable in the configuration file of this add-on. You can also use the setApplicationPaneActive(boolean) method to open and close the UI through the API.

The map-centric version of Lucy uses that mechanism to place the custom time controls on the map (see samples.lucy.frontend.mapcentric.previewer.PreviewerOnMapCustomizerFactory).

Threading rules

All the methods of this class have to be called from the Event Dispatch Thread (EDT, also known as the Swing Thread or AWT thread).

Property changes

The TLcyPreviewAddOn also exposes methods to perform filtering (for example addSimulatorModelFilter(ILcdFilter)) and to listen for property changes. 

  static class ModelFilter implements ILcdFilter<ILcdSimulatorModel>, ILcdChangeSource {

    private TLcdChangeSupport fChangeSupport = new TLcdChangeSupport();

    @Override
    public boolean accept(ILcdSimulatorModel aModel) {
      // adjust this method to do per-model filtering
      // notify the previewer of any changes by calling
      // fChangeSupport#fireChangeEvent
      return true;
    }

    @Override
    public void addChangeListener(ILcdChangeListener aListener) {
      fChangeSupport.addChangeListener(aListener);
    }

    @Override
    public void removeChangeListener(ILcdChangeListener aListener) {
      fChangeSupport.removeChangeListener(aListener);
    }
  }

Integration with legacy ILcySimulatorModelFactory API

Lucy has the concept of an ILcySimulatorModelFactory: a factory that can create ILcdSimulatorModel instances for a static model. The preview add-on will use all the simulator model factory instances available on the Lucy back-end to automatically create and register ILcdSimulatorModels for all ILcdModel instances added to a view.

If an ILcySimulatorModelFactory is available for a model added to a view in Lucy, the preview add-on will not only create a ILcdSimulatorModel for that ILcdModel. It will also create layers for each of the track models, and add those layers to the view. When the original static ILcdModel is removed from the map, the preview add-on will remove the corresponding track layers as well.

Note that, to properly integrate with workspaces, the code that registers the ILcySimulatorModelFactory instance on the back-end and the layer factory for the track models of the simulator model, must also register ALcyWorkspaceObjectCodec instances for the simulator models, the track models and the track layers.

The major drawback of this mechanism is that you need a model and layer representing the static data, from which the real time model (the ILcdSimulatorModel) can be derived. Often such static data is not available. A second drawback is that the static data must be present in the view, even if you do not need it. Removing the static data removes the real-time data as well.
Due to these drawbacks, this mechanism has been deprecated in favor of the ILcdMultiDimensionalModel mechanism.

  • Field Details

    • PREVIEW_GROUP_DESCRIPTOR

      public static final TLcyGroupDescriptor PREVIEW_GROUP_DESCRIPTOR
      Group descriptor which can be used when inserting preview actions in an action bar.

  • Constructor Details

    • TLcyPreviewAddOn

      public TLcyPreviewAddOn()
      Creates a new TLcyPreviewAddOn.

  • Method Details

    • setClassTraceOn

      @Deprecated public static void setClassTraceOn(boolean aClassTraceOn)
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Enables tracing for all instances of this class. If the argument is true then all log messages are recorded, otherwise only the informative, warning and error messages are recorded.
      Parameters:
      aClassTraceOn - if true then all log messages are recorded, otherwise only the informative, warning and error messages are recorded.

    • setTraceOn

      @Deprecated public void setTraceOn(boolean aTraceOn)
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Enables tracing for this class instance. Calling this method with either true or false as argument automatically turns off tracing for all other class instances for which setTraceOn has not been called. If the argument is false then only the informative, warning and error log messages are recorded.
      Parameters:
      aTraceOn - if true then all log messages are recorded for this instance. If false, then only the informative, warning and error log messages are recorded.

    • isTraceOn

      @Deprecated public boolean isTraceOn()
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Returns true if tracing is enabled for this class.
      Returns:
      true if tracing is enabled for this class, false otherwise.

    • plugInto

      public void plugInto(ILcyLucyEnv aLucyEnv)
      Description copied from class: ALcyAddOn
      Plugs this addon into the given lucy environment. It is in the implementation of this method that the addon adds its functionality to the Lucy backend.
      Specified by:
      plugInto in class ALcyAddOn
      Parameters:
      aLucyEnv - The lucy environment to plug into.
      See Also:

    • unplugFrom

      public void unplugFrom(ILcyLucyEnv aLucyEnv)
      Description copied from class: ALcyAddOn
      Unplugs this addon from the given Lucy environment. It removes the functionality previously added to the Lucy backend.
      Specified by:
      unplugFrom in class ALcyAddOn
      Parameters:
      aLucyEnv - The lucy environment to unplug from.
      See Also:

    • isApplicationPaneActive

      public boolean isApplicationPaneActive()
      Returns true if the ILcyApplicationPane is currently active, false otherwise.
      Returns:
      true if the ILcyApplicationPane is currently active, false otherwise.
      See Also:

    • setApplicationPaneActive

      public void setApplicationPaneActive(boolean aActive)
      Sets the active state of the preview ILcyApplicationPane. Active means the ILcyApplicationPane is present in the user interface.

      Note that loading a workspace can change this property.

      Parameters:
      aActive - True to make sure the ILcyApplicationPane is present in the user interface, false to make sure the ILcyApplicationPane is not present.

    • getPreviewAddOnCustomizerFactory

      public ALcyPreviewAddOnCustomizerFactory getPreviewAddOnCustomizerFactory()
      Returns the TLcyPreviewAddOnCustomizerFactory that is responsible to create the gui panel.
      Returns:
      the TLcyPreviewAddOnCustomizerFactory that is responsible to create the gui panel.
      See Also:

    • setPreviewAddOnCustomizerFactory

      public void setPreviewAddOnCustomizerFactory(ALcyPreviewAddOnCustomizerFactory aPreviewAddOnCustomizerFactory)
      Sets the TLcyPreviewAddOnCustomizerFactory that is responsible to create the gui panel.
      Parameters:
      aPreviewAddOnCustomizerFactory - The factory.
      See Also:

    • addPropertyChangeListener

      public void addPropertyChangeListener(PropertyChangeListener aListener)
      Description copied from interface: ILcdPropertyChangeSource

      Registers the given PropertyChangeListener to be notified when this object's properties change.

      In case you need to register a listener which keeps a reference to an object with a shorter life-time than this change source, you can use a ALcdWeakPropertyChangeListener instance as property change listener.

      Specified by:
      addPropertyChangeListener in interface ILcdPropertyChangeSource
      Parameters:
      aListener - The listener to be notified
      See Also:

    • removePropertyChangeListener

      public void removePropertyChangeListener(PropertyChangeListener aListener)
      Description copied from interface: ILcdPropertyChangeSource

      De-registers the given PropertyChangeListener from receiving property change events for this object.

      If the listener was added more than once, it will be notified one less time after being removed. If the listener is null, or was never added, no exception is thrown and no action is taken.

      Specified by:
      removePropertyChangeListener in interface ILcdPropertyChangeSource
      Parameters:
      aListener - the listener that should no longer be notified of changes of this object's properties
      See Also:

    • firePropertyChange

      protected void firePropertyChange(PropertyChangeEvent aEvent)
      Fires the given property change event to the associated listeners.
      Parameters:
      aEvent - The event to fire.
      See Also:

    • addPreviewAddOnListener

      public void addPreviewAddOnListener(ILcyPreviewAddOnListener aListener)
      Adds a preview add-on listener to this add-on.
      Parameters:
      aListener - The listener to add.
      See Also:

    • removePreviewAddOnListener

      public void removePreviewAddOnListener(ILcyPreviewAddOnListener aListener)
      Removes the given preview add-on listener from this add-on.
      Parameters:
      aListener - The listener to remove.
      See Also:

    • firePreviewAddOnEvent

      protected void firePreviewAddOnEvent(TLcyPreviewAddOnEvent aEvent)
      Notifies all registered ILcyPreviewAddOnListeners about the given event.
      Parameters:
      aEvent - The event to fire.

    • getDateFormat

      @Deprecated public DateFormat getDateFormat()
      Deprecated.
      Do not use this method. Lucy has now an application-wide format to control how dates are presented to the user. Use ILcyLucyEnv.getDefaultDateTimeFormat() instead.
      Returns the date format used to present dates to a user.
      Returns:
      the date format used to present dates to a user.
      See Also:

    • setDateFormat

      @Deprecated public void setDateFormat(DateFormat aDateFormat)
      Deprecated.
      Do not use this method. Lucy has now an application-wide format to control how dates are presented to the user. Use ILcyLucyEnv.setDefaultDateTimeFormat(java.text.Format) instead.
      Sets the date format used to present dates to a user.
      Parameters:
      aDateFormat - The date format to set.
      See Also:

    • addSimulatorModel

      @Deprecated public void addSimulatorModel(ILcdSimulatorModel aSimulatorModel)
      Deprecated.
      Use the addSimulatorModelNoLayers(com.luciad.realtime.ILcdSimulatorModel) instead of this method, and manage the creation and addition of the layers manually.
      Adds a ILcdSimulatorModel and notifies all the ILcyPreviewAddOnListener's of the change. Layers will be created for the track models of the simulator model and added to the first GXY view (the GXY view of the map component at index 0 in the map manager)
      Parameters:
      aSimulatorModel - The ILcdSimulatorModel to add.

    • removeSimulatorModel

      @Deprecated public void removeSimulatorModel(ILcdSimulatorModel aSimulatorModel)
      Deprecated.
      Use the removeSimulatorModelNoLayers(com.luciad.realtime.ILcdSimulatorModel) instead of this method, and manage the creation and addition of the layers manually
      Removes a ILcdSimulatorModel and notifies all the ILcyPreviewAddOnListener's of the change.
      Parameters:
      aSimulatorModel - The simulator model to remove.

    • addSimulatorModelNoLayers

      public void addSimulatorModelNoLayers(ILcdSimulatorModel aSimulatorModel)
      Adds a ILcdSimulatorModel and notifies all ILcyPreviewAddOnListener's of the change. Note that the ILcdSimulatorModel can provide track models, but no layers are created for those, nor added to the map. You have full control instead. Refer to the class comment for a more detailed explanation.
      Parameters:
      aSimulatorModel - The ILcdSimulatorModel to add.

    • removeSimulatorModelNoLayers

      public void removeSimulatorModelNoLayers(ILcdSimulatorModel aSimulatorModel)
      Removes a ILcdSimulatorModel and notifies all the ILcyPreviewAddOnListener's of the change.
      Parameters:
      aSimulatorModel - The simulator model to remove.

    • getSimulatorModel

      public ILcdSimulatorModel getSimulatorModel(int aIndex)
      Returns the simulator model at the given index.
      Parameters:
      aIndex - The index to retrieve the simulator model for. 0 <= aIndex < getSimulatorModelCount()
      Returns:
      the simulator model at the given index.
      See Also:

    • getSimulatorModelCount

      public int getSimulatorModelCount()
      Returns the number of simulator models.
      Returns:
      the number of simulator models.

    • addSimulatorModelFilter

      public void addSimulatorModelFilter(ILcdFilter<ILcdSimulatorModel> aFilter)
      Adds a simulator model filter. This filter can be used to prevent some of the simulator models to be used. Only models which pass all the filters will be used.
      Parameters:
      aFilter - The filter to add. If the filter implements ILcdChangeSource, the add-on registers itself to be notified of any changes and updates the models accordingly.
      See Also:

    • removeSimulatorModelFilter

      public void removeSimulatorModelFilter(ILcdFilter<ILcdSimulatorModel> aFilter)
      Removes the given filter.
      Parameters:
      aFilter - The filter to remove.
      See Also:

    • getSimulatorModelFilterCount

      public int getSimulatorModelFilterCount()
      Returns the number of simulator model filters that have been added.
      Returns:
      the number of simulator model filters that have been added.

    • getSimulatorModelFilter

      public ILcdFilter<ILcdSimulatorModel> getSimulatorModelFilter(int aIndex)
      Returns the simulator model filter at the given index.
      Parameters:
      aIndex - The index to retrieve the filter for. 0 <= aIndex < getSimulatorModelFilterCount()
      Returns:
      the simulator model filter at the given index.
      See Also:

    • getDate

      public Date getDate()
      Returns the current date of the previewer.
      Returns:
      the current date of the previewer.
      See Also:

    • setDate

      public void setDate(Date aDate)
      Sets the current date of the previewer.
      Parameters:
      aDate - The data.
      See Also:

    • getMaxCPUUsage

      public int getMaxCPUUsage()
      Returns the maximum cpu usage of the previewer.
      Returns:
      the maximum cpu usage of the previewer.
      See Also:

    • setMaxCPUUsage

      public void setMaxCPUUsage(int aMaxCPUUsage)
      Sets the maximum cpu usage.
      Parameters:
      aMaxCPUUsage - The maximum cpu usage.
      See Also:

    • getStatus

      public int getStatus()
      Returns the status of the previewer. One of TLcdSimulator.ENDED, TLcdSimulator.STOPPED, TLcdSimulator.RUNNING, TLcdSimulator.PAUSING
      Returns:
      The status of the previewer.
      See Also:

    • getStatusAsString

      public String getStatusAsString()
      Returns the status, formatted as a string.
      Returns:
      the status, formatted as a string.
      See Also:

    • getTimeFactor

      public double getTimeFactor()
      Returns the time factor used by the previewer. This is useful to speed up previewing.
      Returns:
      the time factor used by the previewer.
      See Also:

    • setTimeFactor

      public void setTimeFactor(double aTimeFactor)
      Sets the time factor, i.e. the factor by which simulation is accelerated with respect to real time.
      Parameters:
      aTimeFactor - The time factor.
      See Also:

    • getTimeStep

      public long getTimeStep()
      Returns the time step in milliseconds.
      Returns:
      the time step in milliseconds.
      See Also:

    • setTimeStep

      public void setTimeStep(long aTimeStep)
      Sets the time step to use expressed in milliseconds. The default time step is 0.

      Note: when using the properties UseTimeStep and TimeStep, the standard user interface should be adapted because the TimeFactor property will be ignored.

      Parameters:
      aTimeStep - The time step.
      See Also:

    • isUseTimeStep

      public boolean isUseTimeStep()
      Returns true if using time steps, false otherwise.
      Returns:
      true if using time steps, false otherwise.
      See Also:

    • setUseTimeStep

      public void setUseTimeStep(boolean aUseTimeStep)
      Sets whether to use a time-step simulation. If set to true, (and if the method getTimeStep()) returns a value > 0), the simulator will not perform a simulation that has a relation with the real elapsed time. Instead it will give an animation at successive time step as fast as it can. By default, this feature is disabled
      Parameters:
      aUseTimeStep - The value to be set for time-stepping.
      See Also:

    • isPauseOnMousePressed

      public boolean isPauseOnMousePressed()
      Returns whether the simulation is paused while the mouse is pressed. By default, this feature is disabled.
      Returns:
      whether the simulation is paused while the mouse is pressed. By default, this feature is disabled.
      See Also:

    • setPauseOnMousePressed

      public void setPauseOnMousePressed(boolean aPause)
      Set whether to pause the simulation when the mouse is pressed on one of the simulation views.
      Parameters:
      aPause - When true, the simulation will pause while the mouse is being pressed.
      See Also:

    • getUpdatesPerSecond

      public int getUpdatesPerSecond()
      Returns the current update rate in updates per second. Only returns a useful and correct value if getStatus() == TLcdSimulator.RUNNING.
      Returns:
      The current update rate.
      See Also:

    • getDelayBetweenUpdateMs

      public int getDelayBetweenUpdateMs()
      Returns the delay between updates in milliseconds.
      Returns:
      The delay between updates in milliseconds.
      See Also:

    • setDelayBetweenUpdateMs

      public void setDelayBetweenUpdateMs(int aDelayBetweenUpdateMs)
      Set the minimal delay in milliseconds between two simulation updates. This property can be used to limit the maximum frame rate. If this property is for example set to 50 miliseconds, the theoretical maximum frame rate is 1000/50 = 20. In practice it will be somewhat lower because refreshing the view takes some time as well.
      Parameters:
      aDelayBetweenUpdateMs - The delay in milliseconds between two simulation updates.
      See Also:

    • getBeginDate

      public Date getBeginDate()
      Returns the begin date. This is the first date of all added simulator models.
      Returns:
      the begin date.

    • getEndDate

      public Date getEndDate()
      Returns the end date. This is the last date of all added simulator models.
      Returns:
      the end date.

    • getFilterBeginDate

      public Date getFilterBeginDate()
      Returns the begin date of the filter. This is the time range with specific interest.
      Returns:
      the begin date of the filter
      See Also:

    • setFilterBeginDate

      public void setFilterBeginDate(Date aDate)
      Sets the begin date of the filter. This is the time range with specific interest.
      Parameters:
      aDate - The begin date.
      See Also:

    • getFilterEndDate

      public Date getFilterEndDate()
      Returns the end date of the filter. This is the time range with specific interest.
      Returns:
      the end date of the filter.
      See Also:

    • setFilterEndDate

      public void setFilterEndDate(Date aDate)
      Sets the end date of the filter. This is the time range with specific interest.
      Parameters:
      aDate - The end date.
      See Also:

    • run

      public void run()
      Runs the previewer.

    • pause

      public void pause()
      Pauses the previewer.

    • stop

      public void stop()
      Stops the previewer.

    • getSimulatorModelDisplayName

      public String getSimulatorModelDisplayName(ILcdSimulatorModel aSimulatorModel)
      Returns the display name for a simulator model. It attempts to use additional information, for example the layer/model with static data that was used to create the simulator model (using an ILcySimulatorModelFactory). If such attempts fail, the simulator model toString method is used as a fall-back.
      Parameters:
      aSimulatorModel - The simulator model to retrieve the display name for.
      Returns:
      The display name.