Package com.luciad.model

Class TLcdModelList

java.lang.Object
com.luciad.model.ALcdModel
com.luciad.model.TLcdModelList
All Implemented Interfaces:
ILcdModel, ILcdModelContainer, ILcdModelProducerListener, ILcdLockDependent, ILcdDisposable, Serializable, AutoCloseable, EventListener
Direct Known Subclasses:
TLcd2DBoundsIndexedModelList
public class TLcdModelList extends ALcdModel implements ILcdModelContainer, ILcdLockDependent
An ILcdModel that is composed of an ordered list of other ILcdModel objects.

This model has as elements the union of all the elements contained in its submodels. The order in which the elements() enumeration iterates over the elements corresponds to the order of the submodels in this model: first all elements of the first submodel are iterated over, then the elements of the second submodel, etcetera.

Using a TLcdModelList has several advantages over copying all elements of the submodels into a new, flat model. A model list does not flatten the data structure which allows, for example, fast reordening of the submodels after the model list has been created. Additionally, each submodel can also keep its own (more detailed) model descriptor, next to the model descriptor of the model list.

Since a model list is also an ILcdModel, all of its submodels should share the same model reference.

This model itself is not editable; adding or removing elements from this model is not allowed. The elements are contained in the submodels and should be added and removed from those models.

Some methods require this model to retrieve the submodel in which an element is contained. This is done by iterating over all submodels and calling the isObjectInModel(Object, ILcdModel) method for each submodel. By default, this method uses a TLcdDefaultObjectInModelFilter to determine whether the specified element is contained in a submodel. Users of this class may use the addModel(ILcdModel, com.luciad.util.ILcdFilter) method to provide a more performant filter. Especially when dealing with lazily-loaded submodels, it is important to use a proper filter, to avoid unnecessary loading of submodels.

Any model descriptor can be set on this model. If an TLcdEditableModelListDescriptor is used, the descriptor will be automatically updated whenever a submodel is added to or removed from this model.

If all submodels implement ILcd2DBoundsIndexedModel, one should consider using TLcd2DBoundsIndexedModelList instead of this model, to preserve the ability the perform spatial queries on this model list. The package documentation provides a detailed overview of all model implementations that are available in this package, and their usage.

An alternative for grouping models is an ILcdModelTreeNode.

See Also:

  • Constructor Details

    • TLcdModelList

      public TLcdModelList()
      Constructs new, empty TLcdModelList list with a TLcdEditableModelListDescriptor.

    • TLcdModelList

      public TLcdModelList(ILcdModelDescriptor aModelDescriptor)
      Constructs new, empty TLcdModelList list with the specified ILcdModelDescriptor.
      Parameters:
      aModelDescriptor - The modeldescriptor for this model list

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

    • addModel

      public boolean addModel(ILcdModel aModel)
      Adds the specified model to this model list, without a filter.
      Specified by:
      addModel in interface ILcdModelContainer
      Parameters:
      aModel - the model to be added.
      Returns:
      true if this collection of models changed as a result of the call
      Throws:
      NullPointerException - if the specified model is null.
      IllegalArgumentException - if the specified model cannot be added to this model list (!canAddModel(aModel).

    • addModel

      public boolean addModel(ILcdModel aModel, ILcdFilter aObjectInModelFilter)
      Adds the specified model to this model list. The specified filter should only accept objects which are in the model.
      Parameters:
      aModel - the model to be added.
      aObjectInModelFilter - a filter that only accepts elements from the specified model.
      Returns:
      true if this collection of models changed as a result of the call
      Throws:
      NullPointerException - if the specified model is null.
      IllegalArgumentException - if the specified model cannot be added to this model list (!canAddModel(aModel).

    • insertModelAt

      public boolean insertModelAt(ILcdModel aModel, ILcdFilter aObjectInModelFilter, int aIndex)
      Inserts the specified model in this model list at the given index. The specified filter should only accept objects which are in the model.
      Parameters:
      aModel - the model to be added.
      aObjectInModelFilter - a filter that only accepts elements from the specified model.
      aIndex - the index the model should have in the list.
      Returns:
      true if this collection of models changed as a result of the call
      Throws:
      NullPointerException - if the specified model is null.
      IllegalArgumentException - if the specified model cannot be added to this model list (!canAddModel(aModel).
      IndexOutOfBoundsException - if aIndex < 0 || aIndex > modelCount()

    • canAddModel

      public boolean canAddModel(ILcdModel aModel)
      Returns true if the specified model can be added to this list, false otherwise. A model can only be added if either:
      Parameters:
      aModel - the model to be added to this model list.
      Returns:
      true if the specified model can be added to this list, false otherwise.

    • getModelCount

      public int getModelCount()
      Returns the number of models in this model list.
      Returns:
      the number of models in this model list.

    • getModel

      public ILcdModel getModel(int aIndex)
      Returns the ILcdModel at the given index.
      Specified by:
      getModel in interface ILcdModelContainer
      Parameters:
      aIndex - a valid index in this ILcdModelContainer.
      Returns:
      the ILcdModel at the given index.
      Throws:
      IndexOutOfBoundsException - if aIndex < 0 || aIndex >= getModelCount()

    • removeModel

      public boolean removeModel(ILcdModel aModel)
      Removes an ILcdModel from this ILcdModelContainer.
      Specified by:
      removeModel in interface ILcdModelContainer
      Parameters:
      aModel - the model to be removed.
      Returns:
      true if a model was removed as a result of this call
      Throws:
      NullPointerException - if the specified model is null.

    • removeAllModels

      public void removeAllModels()
      Removes all models from this model list. An event will fired for every model that has been removed.

    • getModelReference

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

      The model reference is determined in this way:

      1. If a model reference is set by setModelReference(com.luciad.model.ILcdModelReference), this will be returned
      2. If not, the model reference of the first model will be returned
      3. Otherwise, null is returned

      Specified by:
      getModelReference in interface ILcdModel
      Overrides:
      getModelReference in class ALcdModel
      Returns:
      A model reference, null if there are no models and no explicit model reference is set
      See Also:

    • setModelReference

      public void setModelReference(ILcdModelReference aModelReference)
      Sets the model reference. All models in this model list have to use this reference.

      If not set, the the model reference of the first model will be used, or null if there are no models.

      Overrides:
      setModelReference in class ALcdModel
      Parameters:
      aModelReference - A model reference
      See Also:

    • query

      public <T> Stream<T> query(ILcdModel.Query aQuery)
      Description copied from interface: ILcdModel
      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.

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

    • elements

      public Enumeration elements()
      Description copied from interface: ILcdModel
      Returns an enumeration over all elements of this model. The order in which the elements are enumerated is unspecified by default.
      Specified by:
      elements in interface ILcdModel
      Returns:
      an enumeration over all elements of this model.

    • addElement

      public void addElement(Object aElement, int aFireEventMode) throws IllegalArgumentException
      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.

      This implementations always throws an UnsupportedOperationException. Elements cannot be added directly to this model list, but should be added to the sub models instead.

      Specified by:
      addElement in interface ILcdModel
      Overrides:
      addElement in class ALcdModel
      Parameters:
      aElement - the element to be added to this model.
      aFireEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.
      Throws:
      IllegalArgumentException
      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.

      This implementation always returns false. Elements cannot be added directly to this model list, but should be added to the sub models instead.

      Specified by:
      canAddElement in interface ILcdModel
      Overrides:
      canAddElement in class ALcdModel
      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.

      This implementations always throws an UnsupportedOperationException. Elements cannot be added directly to this model list, but should be added to the sub models instead.

      Specified by:
      addElements in interface ILcdModel
      Overrides:
      addElements in class ALcdModel
      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 aObject, int aFireEventMode) throws IllegalArgumentException
      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.

      This implementations always throws an UnsupportedOperationException. Elements cannot be removed directly from this model list, but should be removed from the sub models instead.

      Specified by:
      removeElement in interface ILcdModel
      Overrides:
      removeElement in class ALcdModel
      Parameters:
      aObject - the element to be removed from this model.
      aFireEventMode - the mode for sending out the model change event. This can be FIRE_LATER or NO_EVENT.
      Throws:
      IllegalArgumentException
      See Also:

    • canRemoveElement

      public boolean canRemoveElement(Object aObject)
      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.

      This implementations always returns false. Elements cannot be removed directly from this model list, but should be removed from the sub models instead.

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

    • removeElements

      public void removeElements(Vector aVector, 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.

      This implementations always throws an UnsupportedOperationException. Elements cannot be removed directly from this model list, but should be removed from the sub models instead.

      Specified by:
      removeElements in interface ILcdModel
      Overrides:
      removeElements in class ALcdModel
      Parameters:
      aVector - 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 aFireEventMode)
      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.

      This implementations always throws an UnsupportedOperationException. Elements cannot be removed directly from this model list, but should be removed from the sub models instead.

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

    • isObjectInModel

      protected boolean isObjectInModel(Object aElement, ILcdModel aModel)
      Returns true if the specified element is contained in the specified model, false otherwise. If a filter was provided for the specified model, this filter is used to determine whether the element is in the model or not. Otherwise, the TLcdDefaultObjectInModelFilter filter is used.
      Parameters:
      aElement - the element to be tested.
      aModel - the model to be tested.
      Returns:
      true if the specified element is contained in the specified model, false otherwise.

    • elementChanged

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

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

      This implementation calls isObjectInModel(Object, ILcdModel) for each model in this model list to determine in which model the object is contained. If a model is found, the change is delegated to this model.

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

    • elementsChanged

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

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

      This implementation iterates over all elements in the specified vector, and calls elementChanged(Object, int) for each element , 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:
      elementsChanged in interface ILcdModel
      Overrides:
      elementsChanged in class ALcdModel
      Parameters:
      aObjects - 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.

    • fireCollectedModelChanges

      public void fireCollectedModelChanges()
      Description copied from class: ALcdModel
      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
      Overrides:
      fireCollectedModelChanges in class ALcdModel
      See Also:

    • addModelListener

      public void addModelListener(ILcdModelListener aModelListener)
      Description copied from class: ALcdModel

      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
      Overrides:
      addModelListener in class ALcdModel
      Parameters:
      aModelListener - the ILcdModelListener to register on this model.
      See Also:

    • removeModelListener

      public void removeModelListener(ILcdModelListener aModelListener)
      Description copied from class: ALcdModel
      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
      Overrides:
      removeModelListener in class ALcdModel
      Parameters:
      aModelListener - the ILcdModelListener to remove.
      See Also:

    • dispose

      public void dispose()
      Description copied from class: ALcdModel
      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
      Overrides:
      dispose in class ALcdModel
      See Also:

    • modelCount

      public int modelCount()
      Description copied from interface: ILcdModelContainer
      Returns the number of ILcdModel objects contained in this ILcdModelContainer.
      Specified by:
      modelCount in interface ILcdModelContainer
      Returns:
      the number of ILcdModel objects contained in this ILcdModelContainer.

    • models

      public Enumeration models()
      Description copied from interface: ILcdModelContainer
      Returns an Enumeration of the ILcdModel objects contained in this ILcdModelContainer.
      Specified by:
      models in interface ILcdModelContainer
      Returns:
      an Enumeration of the ILcdModel objects contained in this ILcdModelContainer.

    • getDependentObjects

      public List<Object> getDependentObjects()
      Description copied from interface: ILcdLockDependent
      Returns the objects that must be locked along with this object. TLcdLockUtilfirst locks all objects returned by this method before locking this object.
      Specified by:
      getDependentObjects in interface ILcdLockDependent
      Returns:
      the objects that must be locked along with this object.

    • addModelContainerListener

      public void addModelContainerListener(ILcdModelContainerListener aModelContainerListener)
      Description copied from interface: ILcdModelContainer
      Adds an ILcdModelContainerListener to this ILcdModelContainer.
      Specified by:
      addModelContainerListener in interface ILcdModelContainer
      Parameters:
      aModelContainerListener - the listener to be added.
      See Also:

    • removeModelContainerListener

      public void removeModelContainerListener(ILcdModelContainerListener aModelContainerListener)
      Description copied from interface: ILcdModelContainer
      Removes an ILcdModelContainerListener from this ILcdModelContainer.
      Specified by:
      removeModelContainerListener in interface ILcdModelContainer
      Parameters:
      aModelContainerListener - the listener to be removed.
      See Also:

    • modelProduced

      public void modelProduced(TLcdModelProducerEvent aModelProducerEvent)
      Description copied from interface: ILcdModelProducerListener
      Notifies this ILcdModelProducerListener of a produced model.
      Specified by:
      modelProduced in interface ILcdModelProducerListener
      Parameters:
      aModelProducerEvent - the event describing the changes to a ILcdModelProducer.