Package com.luciad.model

Interface ILcdModel

All Superinterfaces:
AutoCloseable, ILcdDisposable, Serializable
All Known Subinterfaces:
ILcd2DBoundsIndexedModel, ILcdDataObjectIndexedModel, ILcdFeatureIndexedAnd2DBoundsIndexedModel, ILcdFeatureIndexedModel, ILcdIntegerIndexedModel, ILcdMagneticNorthModel, ILcdModelTreeNode, ILcdMultiDimensionalModel
All Known Implementing Classes:
ALcdModel, ALcdTransformingModel, ALfnTileStoreModel, TLcd2DBoundsIndexedModel, TLcd2DBoundsIndexedModelList, TLcd2DBoundsIndexedModelTreeNode, TLcd2DRegularTiledBoundsIndexedModel, TLcdAIXM51AbstractAIXMMessage, TLcdASTERIXFilteredModel, TLcdDatabaseModel, TLcdDatabaseReadOnlyModel, TLcdDataObjectIndexedAnd2DBoundsIndexedModel, TLcdDataObjectIndexedVectorModel, TLcdFeatureIndexedAnd2DBoundsIndexedModel, TLcdFeatureIndexedVectorModel, TLcdGML2AbstractFeatureCollection, TLcdGML31AbstractFeatureCollection, TLcdGML31DynamicFeatureCollection, TLcdGML31FeatureCollection, TLcdGML31Model, TLcdGML32AbstractFeatureCollection, TLcdGML32FeatureCollection, TLcdGML32Model, TLcdKML22AbstractContainer, TLcdKML22Document, TLcdKML22DynamicModel, TLcdKML22Folder, TLcdKML22Kml, TLcdKML22NetworkLink, TLcdKML22RenderableModel, TLcdMagneticNorthModel, TLcdModelList, TLcdModelTreeNode, TLcdMultilevel2DBoundsIndexedModel, TLcdMultilevelGridCoordinateModel, TLcdNetCDFFilteredModel, TLcdNVG15Model, TLcdNVG20FilteredModel, TLcdNVG20Model, TLcdRegularTiled2DBoundsIndexedModel, TLcdS57DepthAreaEdgeModel, TLcdSoft2DBoundsIndexedModel, TLcdTiled2DBoundsIndexedModel, TLcdTrackModel, TLcdVectorModel, TLcdWCSProxyModel, TLcdWFSProxyModel
public interface ILcdModel extends Serializable, ILcdDisposable
A container for domain objects. Typically these are spatial elements that model a part of the real world.

Models can be created and populated by hand, or they can be created by an ILcdModelDecoder from a data source.

ILcdModel provides basic methods for retrieving, adding and removing elements. The basic method for retrieving is sequential. The identities of the elements are determined by the equals() method.

Model reference

A model has an ILcdModelReference associated with it. This model reference defines the common coordinate system in which the geometry of its elements is expressed. All elements of a model should thus share the same coordinate system.

Model descriptor

A model also has an ILcdModelDescriptor associated with it. This model descriptor provides meta information about the model and information common to all elements contained in this model. The actual contents of this information may vary from model to model.

Accessing data

You can typically access data in a model on any thread, but you must take a read lock: 
    try (TLcdLockUtil.Lock lock = TLcdLockUtil.readLock(model);
         Stream<Object> elements = model.query(all())) {
      elements.forEach(consumer);
    }
This applies to operations such as query, elements or applyOnInteract2DBounds.

This also applies to accessing element internals, such as looping over points of a polyline.

Consult the javadoc of your specific model implementation for additional considerations.

Changing data

There are various methods to add and remove elements. External changes to the elements of the model (for example, the bounds of an element) have to be reported to the model through elementChanged, so it can update its internal structures and send out events to its listeners.

When you do changes to the model or one of its elements, you must take a write lock: 

    try (TLcdLockUtil.Lock lock = TLcdLockUtil.writeLock(model)) {
      model.addElement(element, FIRE_LATER);
    } finally {
      model.fireCollectedModelChanges();
    }
By default, you have to do this on the view's painting thread, but if this is a performance problem you can use another thread. Refer to the Advanced threading and locking guide for more details.

One or more ILcdModelListener objects can be registered to a model, to be notified of changes in the model. The model will notify its listeners whenever one or more elements are added, removed and/or changed. These events can be sent individually, grouped or silently suppressed,depending on the event mode that was specified with the change. Two modes for firing events are supported:

  • FIRE_LATER: applies the change but delays the model change event. You have to flush the events through fireCollectedModelChanges() outside the write lock. This is the recommended mode.
  • NO_EVENT: applies the change but doesn't send or delay the model change event. This can be used if the model being constructed and is not yet in a layer.

The use of ILcdFireEventMode constants for specifying event modes in the methods of this interface has been deprecated in favor of the constants that are defined within this interface.

See ALcdModel for info on debugging missing or wrong model locks.

Extensions

Several extensions of this interface provide additional methods targeted to specific operations (spatial access, indexed access, ...). In addition, a number of implementations of ILcdModel and its extensions are also provided in this package, each optimized for different types of usages. Choosing the right interface or implementation of ILcdModel is important for achieving proper performance. See the package documentation for an overview of all available extension interfaces and implementations.

Additional restrictions

Null values are not accepted as elements in a model. Implementations of this interface may impose additional constraints on what elements they may contain. For example, implementations that are based on a spatial indexing structure will often require that elements implement ILcdBounded. Implementations should clearly specify in their documentation any restrictions on the elements they may contain. The methods canAddElement(Object) and canRemoveElement(Object) reflect these constraints programmatically.
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final class 
    ILcdModel.Query
    A query to be used with query(Query).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    FIRE_LATER
    Store the event for later.
    static final int
    FIRE_NOW
    Deprecated.
    Don't use this event mode always use FIRE_LATER or NO_EVENT.
    static final int
    NO_EVENT
    Don't signal the event at all.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addElement(Object aElement, int aEventMode)
    Adds the specified element to this model.
    void
    addElements(Vector aElements, int aEventMode)
    Adds all of the elements in the specified vector to this model.
    void
    addModelListener(ILcdModelListener aModelListener)
    Registers the specified model listener to receive notifications of model changes on this model.
    static ILcdModel.Query
    all()
    Create a query indicating that all elements should be retrieved.
    boolean
    canAddElement(Object aElement)
    Returns true if the specified element can be added to this model, false otherwise.
    boolean
    canRemoveElement(Object aElement)
    Returns true if the specified element can be removed from this model, false otherwise.
    void
    dispose()
    Disposes of this model and allows it to release any system resources that it is holding.
    void
    elementChanged(Object aElement, int aEventMode)
    Notifies this model that the specified element has changed.
    Enumeration
    elements()
    Returns an enumeration over all elements of this model.
    void
    elementsChanged(Vector aElements, int aEventMode)
    Notifies this model that the elements in the specified vector have changed.
    static ILcdModel.Query
    filter(ILcdOGCCondition aCondition)
    Create a query with the given condition to filter on.
    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.
    ILcdModelDescriptor
    getModelDescriptor()
    Returns the ILcdModelDescriptor providing meta information about this model and its elements.
    ILcdModelEncoder
    getModelEncoder()
    Returns, if available, a model encoder that is capable of encoding this model, (encoder.canEncode(this)), null otherwise.
    default TLcdModelMetadata
    getModelMetadata()
    Collects and returns metadata about the model.
    ILcdModelReference
    getModelReference()
    Returns the ILcdModelReference describing how the geometry of the elements contained in this model should be interpreted.
    default <T> Stream<T>
    query(ILcdModel.Query aQuery)
    Provides a Stream of all elements in this model that match the given query.
    void
    removeAllElements(int aEventMode)
    Removes all elements from this model.
    void
    removeElement(Object aElement, int aEventMode)
    Removes the specified element from this model.
    void
    removeElements(Vector aElements, int aEventMode)
    Removes all of the elements in the specified vector from this model.
    void
    removeModelListener(ILcdModelListener aModelListener)
    Unregisters the specified model listener so that it no longer receives notifications of model changes on this model.

    Methods inherited from interface com.luciad.util.ILcdDisposable

    close

  • Field Details

  • Method Details

    • getModelReference

      ILcdModelReference getModelReference()
      Returns the ILcdModelReference describing how the geometry of the elements contained in this model should be interpreted.
      Returns:
      the ILcdModelReference of this ILcdModel.

    • getModelDescriptor

      ILcdModelDescriptor getModelDescriptor()
      Returns the ILcdModelDescriptor providing meta information about this model and its elements.
      Returns:
      the ILcdModelDescriptor of this ILcdModel. Should not be null.

    • getModelMetadata

      default TLcdModelMetadata getModelMetadata()
      Collects and returns metadata about the model. Note that this method does not necessarily return the same TLcdModelMetadata instance every time it is called. The default implementation uses TLcdModelMetadata.Builder.fromModel(com.luciad.model.ILcdModel).

      Implementations can recreate or extend the metadata. The following example adds a data category and source file mime type: 

      
   public TLcdModelMetadata getModelMetadata() {
     String source = this.getModelDescriptor().getSourceName();
     return this.getModelMetadata().asBuilder()
                                   .entryPoint(new TLcdModelMetadata.Source(source, MIME_XML))
                                   .addDataCategory(TLcdModelMetadata.DataCategory.VECTOR)
                                   .build();
   }
      Returns:
      Metadata about the model.
      Since:
      2018.0

    • getModelEncoder

      ILcdModelEncoder getModelEncoder()
      Returns, if available, a model encoder that is capable of encoding this model, (encoder.canEncode(this)), null otherwise.
      Returns:
      a model encoder that is capable of encoding this model if available, null otherwise.

    • elements

      Enumeration elements()
      Returns an enumeration over all elements of this model. The order in which the elements are enumerated is unspecified by default.
      Returns:
      an enumeration over all elements of this model.

    • addElement

      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.

      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:
      Preconditions:
      The specified element should be expressed in the model reference of this model., It should be possible to add the specified element (canAddElement(aElement)).

    • canAddElement

      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.

      Parameters:
      aElement - the element to be verified.
      Returns:
      true if the specified element can be added to this model, false otherwise.

    • addElements

      void addElements(Vector aElements, int aEventMode)
      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.

      Parameters:
      aElements - the vector of elements to be added to this model.
      aEventMode - the mode for sending the model change events This can be FIRE_LATER or NO_EVENT.
      See Also:
      Preconditions:
      The elements in the specified vector should all be expressed in the model reference of this model., It should be possible to add each of the elements in the specified vector (for each element: canAddElement(aElement)).

    • removeElement

      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.

      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:
      Preconditions:
      It should be possible to remove the specified element (canRemoveElement(aElement)).

    • canRemoveElement

      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.
      Parameters:
      aElement - the element to be verified.
      Returns:
      true if the specified element can be removed from this model, false otherwise.

    • removeElements

      void removeElements(Vector aElements, int aEventMode)
      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.

      Parameters:
      aElements - the vector of elements 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:
      Preconditions:
      It should be possible to remove each of the elements in the specified vector (for each element: canRemoveElement(aElement)).

    • removeAllElements

      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.

      Parameters:
      aEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.

    • elementChanged

      void elementChanged(Object aElement, int aEventMode)
      Notifies this model that the specified element has changed.
      Parameters:
      aElement - the element that has changed.
      aEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.

    • elementsChanged

      void elementsChanged(Vector aElements, int aEventMode)
      Notifies this model that the elements in the specified vector have changed.
      Parameters:
      aElements - the vector of elements that have changed.
      aEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.
      Throws:
      NullPointerException - if the specified vector is null.

    • fireCollectedModelChanges

      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.
      See Also:

    • addModelListener

      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.

      Parameters:
      aModelListener - the ILcdModelListener to register on this model.
      Throws:
      NullPointerException - if the specified listener is null.
      See Also:

    • removeModelListener

      void removeModelListener(ILcdModelListener aModelListener)
      Unregisters the specified model listener so that it no longer receives notifications of model changes on this model.
      Parameters:
      aModelListener - the ILcdModelListener to remove.
      Throws:
      NullPointerException - if the specified listener is null.
      See Also:

    • dispose

      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.
      Specified by:
      dispose in interface ILcdDisposable

    • query

      default <T> Stream<T> query(ILcdModel.Query aQuery)
      Provides a Stream of all elements in this model that match the given query.

      The query aspects are applied in this specific order, regardless of the order used to create the query:

      1. The query filter is applied first (if any).
      2. The query sorting is applied second (if any).
      3. The query limit is applied last (if any).
      The condition and sort-by must never change after creation.

      Examples:

      A stream is closeable, and it depends on the implementation whether the stream has to be closed or not.
      You should use this template to ensure proper model locking and stream closing: 

      
   try (TLcdLockUtil.Lock autoUnlock = TLcdLockUtil.readLock(model);
        Stream elements = model.query(all())) {
     elements.forEach(System.err::println);
   }

      Model implementations:

      By default, this method will invoke elements(), loop over all elements and apply the filter, sorting and limit.

      For ILcd2DBoundsIndexedModel, this method will invoke applyOnInteract2DBounds() if the condition contains a spatial component (either a bounding-box operator, or a spatial operator), and apply the rest of the filter on those elements.

      Overriding:

      Model implementers can override this method to apply the query more efficiently on their back-end format.

      For example, if your back-end is a service or database that accepts certain queries, you can override this method and transform the condition into a query on that service.
      You can inspect the condition using instanceof on the various condition classes.

      Parameters:
      aQuery - The query, cannot be null. Pass all() if you want all elements.
      Returns:
      a stream of the retained model elements
      Since:
      2017.0
      See Also:

    • all

      static ILcdModel.Query all()
      Create a query indicating that all elements should be retrieved.

      You can further refine the query using the instance methods filter, sorted or limit.

      Returns:
      The query (not null)
      Since:
      2017.0

    • filter

      static ILcdModel.Query filter(ILcdOGCCondition aCondition)
      Create a query with the given condition to filter on.

      You can further refine the query using the instance methods sorted or limit.

      Parameters:
      aCondition - The condition, or null if no filtering should be done.
      Returns:
      The query (not null)
      Since:
      2017.0
      See Also: