Package com.luciad.model

Class ALcdModel

java.lang.Object
com.luciad.model.ALcdModel
All Implemented Interfaces:
ILcdModel, ILcdDisposable, Serializable, AutoCloseable
Direct Known Subclasses:
ALfnTileStoreModel, TLcd2DBoundsIndexedModel, TLcd2DRegularTiledBoundsIndexedModel, TLcdASTERIXFilteredModel, TLcdDatabaseModel, TLcdDatabaseReadOnlyModel, TLcdFeatureIndexedAnd2DBoundsIndexedModel, TLcdKML22DynamicModel, TLcdKML22RenderableModel, TLcdModelList, TLcdMultilevel2DBoundsIndexedModel, TLcdMultilevelGridCoordinateModel, TLcdRegularTiled2DBoundsIndexedModel, TLcdTrackModel, TLcdVectorModel, TLcdWFSProxyModel
public abstract class ALcdModel extends Object implements ILcdModel
A skeleton implementation of ILcdModel to minimize the effort required to implement this interface.

To implement an unmodifiable model, the user needs to extend this class and implement the ILcdModel.elements() method.

To implement a modifiable model, the user must additionally override the following methods:

To achieve better performance, one should also consider:

Threading and locking

Models have a set of threading rules to obey, please refer to ILcdModel or the developer's guide.

By enabling debug-level logging on ALcdModel, write lock violations of the threading rules are reported on the log. Applications or developers should never solely rely on this mechanism, it is intended to be used for debugging purposes. Its behavior may change in future versions.

Logging can be enabled via config files:


   com.luciad.model.ALcdModel.level = FINE

or via code:


   Logger.getLogger(ALcdModel.class.getName()).setLevel(Level.FINE);

The violations themselves are reported at the error level.

Limitations

  • Enabling logging via code requires the standard Java logging to be used.
  • Logging must be enabled before any model is created.
  • If correct threading is guaranteed on the application level rather than through using locks, this gets reported while there is no issue in practice. For example, this sequence of events will not cause issues, but does get flagged: access a model on thread-1 without locks, thread-1 dies, access the same model on thread-2 without locks.
See Also:

  • Field Details

  • Constructor Details

    • ALcdModel

      public ALcdModel()

  • Method Details

    • setClassTraceOn

      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.

    • isClassTraceOn

      public static boolean isClassTraceOn()
      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.

    • setTraceOn

      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

      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.

    • getModelReference

      public ILcdModelReference getModelReference()
      Returns the ILcdModelReference describing how the geometry of the elements contained in this model should be interpreted.
      Specified by:
      getModelReference in interface ILcdModel
      Returns:
      the ILcdModelReference of this ILcdModel.
      See Also:

    • setModelReference

      public void setModelReference(ILcdModelReference aModelReference)
      Sets the model reference describing how the geometry of the elements contained in this model should be interpreted.
      Parameters:
      aModelReference - the model reference for this model.
      See Also:

    • getModelDescriptor

      public ILcdModelDescriptor getModelDescriptor()
      Returns the ILcdModelDescriptor providing meta information about this model and its elements.
      Specified by:
      getModelDescriptor in interface ILcdModel
      Returns:
      the ILcdModelDescriptor of this ILcdModel. Should not be null.
      See Also:

    • setModelDescriptor

      public void setModelDescriptor(ILcdModelDescriptor aModelDescriptor)
      Sets the model descriptor providing meta information about this model and its elements.
      Parameters:
      aModelDescriptor - the model descriptor for this model.
      See Also:

    • getModelEncoder

      public ILcdModelEncoder getModelEncoder()
      Returns, if available, a model encoder that is capable of encoding this model, (encoder.canEncode(this)), null otherwise.
      Specified by:
      getModelEncoder in interface ILcdModel
      Returns:
      a model encoder that is capable of encoding this model if available, null otherwise.
      See Also:

    • setModelEncoder

      public void setModelEncoder(ILcdModelEncoder aModelEncoder)
      Sets a model encoder on this model that can be used to encode this model.
      Parameters:
      aModelEncoder - a model encoder capable of encoding this model.
      Preconditions:
      The specified model encoder should be capable of encoding this model (encoder.canEncode(this)).

    • getModelMetadata

      public TLcdModelMetadata getModelMetadata()
      Collects and returns metadata about the model, using this model's model metadata function. The model metadata function can be changed with setModelMetadataFunction(Function). The default metadata function uses TLcdModelMetadata.Builder.fromModel(com.luciad.model.ILcdModel), but subclasses may set an adjusted default function.
      Specified by:
      getModelMetadata in interface ILcdModel
      Returns:
      Metadata about the model.
      See Also:

    • setModelMetadataFunction

      public final void setModelMetadataFunction(Function<ALcdModel,TLcdModelMetadata> aModelMetadataFunction)
      Sets the function that is used to collect the model metadata returned by getModelMetadata(). This function will be called every time the getModelMetadata() method is called, providing this model instance as parameter: 
      
 public TLcdModelMetadata getModelMetadata() {
   return aModelMetadataFunction.apply(this);
 }
      The default model metadata function uses TLcdModelMetadata.Builder.fromModel(ILcdModel), but subclasses may set an adjusted default function.
      Since:
      2018.1

    • setModelDisposer

      public final void setModelDisposer(Consumer<ILcdModel> aModelDisposer)
      Sets the method to call when disposing the model. This allows a decoder to register specific logic to free resources when the model is disposed.

      The disposable is called within the method dispose().

      Parameters:
      aModelDisposer - the disposable that takes care of freeing resources held by the model.
      Since:
      2018.1

    • addElement

      public void addElement(Object aElement, int aEventMode)
      Adds the specified element to this model.

      Models that support this operation may place limitations on what elements may be added to this model. For example, implementations that are based on a spatial indexing structure will require that elements implement ILcdBounded.

      When adding an element, the user should make sure that canAddElement(aElement) holds, and that the element's geometry is expressed in the same model reference as this model. It is generally undefined what happens if an invalid element is added.

      Implementations of this interface should clearly specify in their documentation any restrictions on what elements may be added. Although it is unspecified what happens if the preconditions are not met, implementations are encouraged to throw meaningful exceptions (for example, NullPointerException, IllegalArgumentException, ClassCastException, UnsupportedOperationException), whenever possible.

      This implementation always throws an UnsupportedOperationException.

      Specified by:
      addElement in interface ILcdModel
      Parameters:
      aElement - the element to be added to this model.
      aEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.
      See Also:

    • canAddElement

      public boolean canAddElement(Object aElement)
      Returns true if the specified element can be added to this model, false otherwise.

      Note that this method generally does not validate whether the specified element is expressed in the same model reference as this model. It is the responsibility of the user of this model to make sure this precondition is fulfilled when an element is added to this model.

      This implementation always returns false.

      Specified by:
      canAddElement in interface ILcdModel
      Parameters:
      aElement - the element to be verified.
      Returns:
      true if the specified element can be added to this model, false otherwise.

    • addElements

      public void addElements(Vector aElements, int aFireEventMode)
      Adds all of the elements in the specified vector to this model. Models that support this operation may place limitations on what elements may be added to this model. For example, implementations that are based on a spatial indexing structure will require that elements implement ILcdBounded. Implementations of this interface should clearly specify in their documentation any restrictions on what elements may be added.

      The behavior of this operation is undefined if the specified vector is modified while the operation is in progress.

      The specified elements will be added to this model in the order they are specified in the vector. If an element cannot be added, this method will return at the first failure. Succeeding elements won't be added.

      Although it is unspecified what happens if the preconditions are not met, implementations are encouraged to throw meaningful exceptions (for example, NullPointerException, IllegalArgumentException, ClassCastException, UnsupportedOperationException), whenever possible.

      This implementation iterates over all elements in the specified vector, and calls addElement(Object, int) for each element to be added, using event mode NO_EVENT if the specified event mode is NO_EVENT, FIRE_LATER otherwise. If the specified event mode is FIRE_NOW, fireCollectedModelChanges() is called afterwards.

      Specified by:
      addElements in interface ILcdModel
      Parameters:
      aElements - the vector of elements to be added to this model.
      aFireEventMode - the mode for sending the model change events This can be FIRE_LATER or NO_EVENT.
      See Also:

    • removeElement

      public void removeElement(Object aElement, int aEventMode)
      Removes the specified element from this model. If the specified element is not contained in this model, this method has no effect.

      Although it is unspecified what happens if the preconditions are not met, implementations are encouraged to throw meaningful exceptions (for example, NullPointerException, IllegalArgumentException, ClassCastException, UnsupportedOperationException), whenever possible.

      This implementation always throws an UnsupportedOperationException.

      Specified by:
      removeElement in interface ILcdModel
      Parameters:
      aElement - the element to be removed from this model.
      aEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.
      See Also:

    • canRemoveElement

      public boolean canRemoveElement(Object aElement)
      Returns true if the specified element can be removed from this model, false otherwise. Note that this method generally does not check whether the specified element is actually contained in this model.

      This implementation always returns false.

      Specified by:
      canRemoveElement in interface ILcdModel
      Parameters:
      aElement - the element to be verified.
      Returns:
      true if the specified element can be removed from this model, false otherwise.

    • removeElements

      public void removeElements(Vector aElements, int aFireEventMode)
      Removes all of the elements in the specified vector from this model. If one of the elements in the specified vector is not contained in this model, this element will be ignored.

      The behavior of this operation is undefined if the specified vector is modified while the operation is in progress.

      The specified elements will be removed from this model in the order they are specified in the vector. If an element cannot be removed, this method will return at the first failure. Succeeding elements won't be removed.

      Although it is unspecified what happens if the preconditions are not met, implementations are encouraged to throw meaningful exceptions (for example, NullPointerException, IllegalArgumentException, ClassCastException, UnsupportedOperationException), whenever possible.

      This implementation iterates over all elements in the specified vector, and calls removeElement(Object, int) for each element to be removed, using event mode NO_EVENT if the specified event mode is NO_EVENT, FIRE_LATER otherwise. If the specified event mode is FIRE_NOW, fireCollectedModelChanges() is called afterwards.

      Specified by:
      removeElements in interface ILcdModel
      Parameters:
      aElements - the vector of elements to be removed from this model.
      aFireEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.
      See Also:

    • removeAllElements

      public void removeAllElements(int aEventMode)
      Removes all elements from this model.

      If an element cannot be removed, this method will return at the first failure. Succeeding elements won't be removed.

      Although it is unspecified what happens if the preconditions are not met, implementations are encouraged to throw meaningful exceptions (for example, NullPointerException, IllegalArgumentException, ClassCastException, UnsupportedOperationException), whenever possible.

      This implementation iterates over all elements in the model, and calls removeElement(Object, int) for each element to be removed, using event mode NO_EVENT if the specified event mode is NO_EVENT, FIRE_LATER otherwise. If the specified event mode is FIRE_NOW, fireCollectedModelChanges() is called afterwards.

      Specified by:
      removeAllElements in interface ILcdModel
      Parameters:
      aEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.

    • fireCollectedModelChanges

      public void fireCollectedModelChanges()
      Notifies all listeners that are registered on this model of all the changes that have been collected between the previous notification and now.

      This implementation calls #TLcdModelChangedEventSupport#fireCollectedModelChanges().

      Specified by:
      fireCollectedModelChanges in interface ILcdModel
      See Also:

    • elementsChanged

      public void elementsChanged(Vector aElements, int aFireEventMode)
      Notifies this model that the elements in the specified vector have changed.

      This implementation calls TLcdModelChangedEventSupport#elementsChanged(java.util.Vector, int).

      Specified by:
      elementsChanged in interface ILcdModel
      Parameters:
      aElements - the vector of elements that have changed.
      aFireEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.

    • allElementsChanged

      public void allElementsChanged(int aFireEventMode)
      Notifies this model that all elements have changed.

      This implementation calls TLcdModelChangedEventSupport#allElementsChanged(int).

      Parameters:
      aFireEventMode - the mode for sending out the model change event. This can be one of FIRE_NOW, FIRE_LATER or NO_EVENT. In case of FIRE_NOW mode, only one event will be fired, containing all changes.

    • elementChanged

      public void elementChanged(Object aElement, int aFireEventMode)
      Notifies this model that the specified element has changed.

      This implementation calls TLcdModelChangedEventSupport#elementChanged(Object, int).

      Specified by:
      elementChanged in interface ILcdModel
      Parameters:
      aElement - the element that has changed.
      aFireEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.

    • elementsAdded

      protected void elementsAdded(Vector aElements, int aFireEventMode)
      Notifies this model that the specified elements have been added.

      This implementation calls com.luciad.model.TLcdModelChangedEventSupport#elementsAdded(java.util.Vector, int).

      Parameters:
      aElements - the Vector of Objects that has been added to the model.
      aFireEventMode - the mode for sending out the model event. This can be FIRE_NOW, LATER or NO_EVENT.

    • elementAdded

      protected void elementAdded(Object aElement, int aFireEventMode)
      Sends a TLcdModelChangedEvent to the listeners.

      This implementation calls com.luciad.model.TLcdModelChangedEventSupport#elementAdded(Object, int).

      Parameters:
      aElement - the Object that has been added to the model.
      aFireEventMode - the mode for sending out the model event. This can be FIRE_NOW, LATER or NO_EVENT.

    • elementsRemoved

      protected void elementsRemoved(Vector aElements, int aFireEventMode)
      Sends a TLcdModelChangedEvent to the listeners.

      This implementation calls com.luciad.model.TLcdModelChangedEventSupport#elementsRemoved(java.util.Vector, int).

      Parameters:
      aElements - the Vector of Objects that has been removed from the model.
      aFireEventMode - the mode for sending out the model event. This can be FIRE_NOW, LATER or NO_EVENT.

    • elementRemoved

      protected void elementRemoved(Object aElement, int aFireEventMode)
      Sends a TLcdModelChangedEvent to the listeners.

      This implementation calls com.luciad.model.TLcdModelChangedEventSupport#elementRemoved(Object, int).

      Parameters:
      aElement - the Object that has been removed from the model.
      aFireEventMode - the mode for sending out the model event. This can be FIRE_NOW, LATER or NO_EVENT.

    • allElementsRemoved

      protected void allElementsRemoved(int aFireEventMode)
      Sends a TLcdModelChangedEvent to the listeners.
      Parameters:
      aFireEventMode - the mode for sending out the model event. This can be FIRE_NOW, LATER or NO_EVENT.

    • addModelListener

      public void addModelListener(ILcdModelListener aModelListener)

      Registers the specified model listener to receive notifications of model changes on this model.

      Model changes are sent out when an element has been added, removed or changed. Model changes can be sent out individually, grouped or silently applied without notifications, depending on the ILcdFireEventMode that was specified with the change.

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

      This implementation calls TLcdModelChangedEventSupport#addModelListener(ILcdModelListener).

      Specified by:
      addModelListener in interface ILcdModel
      Parameters:
      aModelListener - the ILcdModelListener to register on this model.
      See Also:

    • removeModelListener

      public void removeModelListener(ILcdModelListener aModelListener)
      Unregisters the specified model listener so that it no longer receives notifications of model changes on this model.

      This implementation calls TLcdModelChangedEventSupport#removeModelListener(ILcdModelListener).

      Specified by:
      removeModelListener in interface ILcdModel
      Parameters:
      aModelListener - the ILcdModelListener to remove.
      See Also:

    • dispose

      public void dispose()
      Disposes of this model and allows it to release any system resources that it is holding. The result of calling any other method (other than finalize) on this model subsequent to a call to this method is undefined.

      When a model disposer has been provided it is called, otherwise this method does nothing. When overriding this method it is recommended to call super.dispose().

      Specified by:
      dispose in interface ILcdDisposable
      Specified by:
      dispose in interface ILcdModel
      See Also:

    • initializeTransientValues

      protected void initializeTransientValues()
      Initializes transient values. Subclasses that redefine this method MUST call super.initializeTransientValues() before doing any processing to any transient instance variables of the subclass.