Package com.luciad.model

Interface ILcdDataObjectIndexedModel

All Superinterfaces:
AutoCloseable, ILcdDisposable, ILcdModel, Serializable
All Known Implementing Classes:
TLcdAIXM51AbstractAIXMMessage, TLcdDataObjectIndexedAnd2DBoundsIndexedModel, TLcdDataObjectIndexedVectorModel
public interface ILcdDataObjectIndexedModel extends ILcdModel
An ILcdModel whose elements can be retrieved efficiently via expression-based indices.

First an index must be created on the model, by specifying the list of expressions on which the index should be based. The addIndex(java.util.List, boolean) method will return an ILcdDataObjectIndexedModel.IndexId which can be used to identify the index later, when retrieving elements via retrieveAllByIndex(com.luciad.model.ILcdDataObjectIndexedModel.IndexId, java.util.List) or retrieveFirstByIndex(com.luciad.model.ILcdDataObjectIndexedModel.IndexId, java.util.List).

All elements in this model should implement ILcdDataObject. Expressions should be expressed in the data object expression language which is configured on this model using setDataObjectExpressionLanguage(com.luciad.datamodel.expression.ALcdDataObjectExpressionLanguage). The model uses the TLcdDataObjectExpressionLanguage by default.

Two types of indices are supported:

  • unique indices: each combination of expression values in the index is unique.
  • non-unique indices: a combination of expression values can exist more than once in the index.
Unique indices are more performant and should be preferred whenever possible. However, it is not allowed to create a unique index when more than one elements map on the same set of index expression values.

Implementations of this interface should take care when implementing the ILcdModel.elementChanged(Object, int) method: the evaluated expressions for an element may already have changed at the moment the elementChanged method is called, and can thus not be used to retrieve the element in the index.

Since:
11.0.04

  • Method Details

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

      In addition to any constraints imposed by ILcdModel.canAddElement(Object), this method also verifies whether:

      • the element is an instance of ILcdDataObject
      • the element does not violate the uniqueness constraints of the indices defined on this model.
      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.

    • getIndexIds

      Set<ILcdDataObjectIndexedModel.IndexId> getIndexIds()
      Returns the set of all indices which are currently available on this model. If no indices are available, an empty set is returned.

      If a required index is not available, it can be created using addIndex(java.util.List, boolean).

      Returns:
      the set of all indices which are currently available on this model.
      See Also:

    • getIndexId

      ILcdDataObjectIndexedModel.IndexId getIndexId(Set<String> aExpressions)
      Returns the index id which corresponds to the given set of expressions, or null if no such index is available on this model.

      Note that, in case the set would be sorted, the order of expressions in the returned index id may be different from the order in the set. It is the order of expressions in the returned index id which determines the order of expression values to be passed to retrieveAllByIndex(com.luciad.model.ILcdDataObjectIndexedModel.IndexId, java.util.List) and retrieveFirstByIndex(com.luciad.model.ILcdDataObjectIndexedModel.IndexId, java.util.List).

      Parameters:
      aExpressions - the expressions for which an index id should be returned.
      Returns:
      the index matching the given set of expressions and uniqueness, or null if no such index is available.

    • canAddIndex

      boolean canAddIndex(List<String> aExpressions, boolean aIsUniqueIndex)
      Returns true if an index can be created for the given list of expressions and uniqueness flag, false otherwise.

      An index can be created if:

      • There are no duplicate expressions in the expression list.
      • An index with the same expressions but different uniqueness property doesn't exist yet in this model.
      • The specified expressions are valid expressions for the expression language of this model, that is, the expression language is capable of compiling each of the expressions
      • If the index is unique, there should at most be one model element matching each unique combination of expression values.
      Implementations may add additional constraints, which should be clearly specified in their documentation.
      Parameters:
      aExpressions - a set of expressions defining the index.
      aIsUniqueIndex - boolean flag indicating whether the index is unique (has at most one element for each unique combination of expression values) or not.
      Returns:
      true if an index can be created for the given list of expressions and uniqueness flag, false otherwise.
      Throws:
      NullPointerException - if aExpressions == null or one of the expressions in aExpressions is null.

    • addIndex

      ILcdDataObjectIndexedModel.IndexId addIndex(List<String> aExpressions, boolean aIsUniqueIndex)
      Creates a new index for the given list of expressions. The uniqueness flag allows to specify whether the index should be created as a unique index or not. If the index already exists on the model, this method has no effect and the index id of the existing index is returned.

      It is not allowed to create both a unique and a non-unique index with the same list of expressions.

      Parameters:
      aExpressions - a set of expressions defining the index.
      aIsUniqueIndex - boolean flag indicating whether the index is unique (has at most one element for each unique combination of expression values) or not.
      Returns:
      the index id, uniquely identifying the created index.
      Throws:
      NullPointerException - if aExpressions == null or one of the expressions in aExpressions is null.
      IllegalArgumentException - if !canAddIndex(aExpressions, aIsUniqueIndex)

    • removeIndex

      boolean removeIndex(ILcdDataObjectIndexedModel.IndexId aIndexId)
      Removes the specified index from this model. All resources allocated for the index will be released. If the index does not exist on this model, this method has no effect.
      Parameters:
      aIndexId - the index to be removed.
      Returns:
      true if the specified index was successfully removed from this model, false otherwise.
      Throws:
      NullPointerException - if aIndexId == null

    • removeAllIndices

      void removeAllIndices()
      Removes all indices from this model.

    • retrieveAllByIndex

      Collection<ILcdDataObject> retrieveAllByIndex(ILcdDataObjectIndexedModel.IndexId aIndexId, List aExpressionValues)
      Returns all model elements which match the given list of values for the expressions in the given index.

      The list of values in aExpressionValues should contain a value for each expression in aIndexId.getExpressions(), where the value at position i specifies the value to which the expression at position i, evaluated for each model element, should be compared to.

      aExpressionValues may contain null values. A null value will be considered a match if the corresponding expression for the tested model element also evaluates to null.

      If no elements match the specified expression values, an empty collection is returned.

      Parameters:
      aIndexId - the index describing the expressions to test for.
      aExpressionValues - the list of values to be compared with the list of evaluated expressions.
      Returns:
      a collection containing all model elements which match the given list of values for the expressions in the given index.
      Throws:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the specified index does not exist on this model, or if aIndexId.getExpressions().size() != aExpressionValues().size()
      See Also:

    • retrieveFirstByIndex

      ILcdDataObject retrieveFirstByIndex(ILcdDataObjectIndexedModel.IndexId aIndexId, List aExpressionValues)
      Returns a single model element which matches the given list of values for the expressions in the given index, or null if no such element exists in the model.

      The list of values in aExpressionValues should contain a value for each expression in aIndexId.getExpressions(), where the value at position i specifies the value to which the expression at position i, evaluated for each model element, should be compared to.

      aExpressionValues may contain null values. A null value will be considered a match if the corresponding expression for the tested model element also evaluates to null.

      Parameters:
      aIndexId - the index describing the expressions to test for.
      aExpressionValues - the list of values to be compared with the list of evaluated expressions.
      Returns:
      a single model element which matches the given list of values for the expressions in the given index, or null if no such element exists in the model.
      Throws:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the specified index does not exist on this model, or if aIndexId.getExpressions().size() != aExpressionValues().size()
      See Also:

    • getIndexedValues

      Set<List<Object>> getIndexedValues(ILcdDataObjectIndexedModel.IndexId aIndex)
      Returns the set of all unique expression value combinations which are present in the specified index.
      Parameters:
      aIndex - the index for which to return the set of expression value combinations.
      Returns:
      the set of expression value combinations, present in the specified index.
      Throws:
      IllegalArgumentException - if the specified index does not exist on this model.

    • getDataObjectExpressionLanguage

      ALcdDataObjectExpressionLanguage getDataObjectExpressionLanguage()
      Returns the expression language used to evaluate expressions defined in the indices of the model.
      Returns:
      the expression language used to evaluate expressions defined in the indices of the model.

    • setDataObjectExpressionLanguage

      void setDataObjectExpressionLanguage(ALcdDataObjectExpressionLanguage aExpressionLanguage)
      Sets the expression language to be used for evaluating expressions defined in the indices of the model. This operation will trigger a rebuild of all indices which are currently configured on the model.
      Parameters:
      aExpressionLanguage - the expression language used to evaluate expressions defined in the indices of the model.
      Throws:
      IllegalArgumentException - if one or more of the existing indices could not be rebuilt with the specified expression language, either because the expression language cannot parse one or more of the expressions, or the new expression language maps multiple objects on a single entry in a unique index.