Package com.luciad.models.features

Class Feature

java.lang.Object
com.luciad.models.features.Feature
All Implemented Interfaces:
AutoCloseable
public final class Feature extends Object implements AutoCloseable
A Feature is a (partial) copy of a domain object.

It allows the rest of the API to easily access the domain object's properties, including any geometry. If you do a query on the model, and retrieve a Feature from it, the caller of the query receives ownership of the Feature. I.e. the caller can decide what to do with it, and when to dispose it.

This means that the Map and Layer APIs are allowed to keep references to a Feature and have unrestricted lock-less access to its properties. The caller of the IFeatureModel#query method is responsible for managing the lifetime of a Feature.

To make Feature instances easy to use in a multi-threaded environment, they are

  • immutable
  • thread safe for reading

See article for more details on this class.

  • Method Details

    • finalize

      protected void finalize()
      Overrides:
      finalize in class Object

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable

    • newBuilder

      @NotNull public static Feature.Builder newBuilder()
      Returns a new Feature Builder.
      Returns:
      a new Feature Builder.

    • asBuilder

      @NotNull public Feature.Builder asBuilder()
      Returns this Feature as a Feature.Builder.

      This makes it possible to copy a Feature, and modify values. Note that when using this builder, it is not possible to change the datatype. Only the values and the id of the Feature. Otherwise a java.lang.IllegalStateException will be thrown.

      Returns:
      this Feature as a Feature.Builder.

    • hasId

      public boolean hasId()
      Returns if this Feature has an id.

      If this method returns false, it is not allowed to call Feature#getId.

      Returns:
      if this Feature has an id.
      See Also:

    • getId

      public long getId() throws IllegalStateException
      Returns the id of this feature.

      A feature id should be unique across a model.

      When no id is set, this method will throw an exception.

      Returns:
      the id of this feature.
      Throws:
      IllegalStateException - when the feature has no id.

    • getDataType

      @NotNull public DataType getDataType()
      Returns the data type describing the feature properties.
      Returns:
      the data type describing the feature properties.

    • findGeometry

      @Nullable public Geometry findGeometry()
      Tries to find a geometry for this feature.

      If this feature's data type is annotated with GeometryDataAnnotation, the value of the corresponding property is returned. Otherwise, the result will be null.

      Returns:
      the annotated geometry, if any, else null.
      See Also:

    • getListSize

      @Nullable public Long getListSize(@NotNull DataPropertyPath propertyPath) throws IllegalArgumentException
      Returns the element count of a list-typed property.

      Example

          Long size = feature.getListSize(timePath);    // 3
    Long first = feature.getValue(firstTimePath); // 150
      Parameters:
      propertyPath - the path to the list-typed property (DataCollectionKind#List).
      Returns:
      no value if the list is unset for this feature, or the element count otherwise (0 for an empty list).
      Throws:
      IllegalArgumentException - if the path's origin type does not match this Feature's data type, or the path does not point to a list, such as for a scalar property or a list element.
      Since:
      2026.1

    • getListSize

      @Nullable public Long getListSize(@NotNull String propertyName) throws IllegalArgumentException
      Convenience overload of getListSize that resolves the property by name on this feature's data type.

      Equivalent to calling getListSize with a DataPropertyPath built from getDataType() and propertyName.

      Performance note: this overload resolves the name on every call. To read the same property from many features in a tight loop, build a DataPropertyPath once and use the DataPropertyPath overload, which prevents the repeated lookup.

      Parameters:
      propertyName - the name of a list-typed property (DataCollectionKind#List) in this feature's data type.
      Returns:
      no value if the list is unset for this feature, or the element count otherwise (0 for an empty list).
      Throws:
      IllegalArgumentException - when no property with that name exists, or it does not point to a list, such as for a scalar property.
      Since:
      2026.1

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(@Nullable Object other)
      Overrides:
      equals in class Object

    • getValue

      @Nullable public <T> T getValue(@NotNull DataPropertyPath propertyPath) throws IllegalArgumentException
      Accesses the value for the given property.

      The type parameter T depends on the type of value this property contains:

      • Scalar property: T is the element type (bool, int32_t, int64_t, float, double, std::string, or a Geometry, or one of its subtypes).
      • Composite property (value type is a non-primitive DataType): T is DataObject, and the nested composite value is returned.
      • List property: T is the list type, and the list is returned, or no value when the list is unset. Individual elements may be unset as well.
      • List element (path with a terminal index step): T is the element type (DataObject for a composite element), and the single element is returned.

      Example

          Boolean optBoolean = feature.<Boolean>getValue(booleanPropertyPath);
    Integer optInteger = feature.<Integer>getValue(intPropertyPath);
    Long optLong = feature.<Long>getValue(longPropertyPath);
    Float optFloat = feature.<Float>getValue(floatPropertyPath);
    Double optDouble = feature.<Double>getValue(doublePropertyPath);
    String optString = feature.<String>getValue(stringPropertyPath);
    Geometry optGeometry = feature.<Geometry>getValue(geometryPropertyPath);
    String unsetValue = feature.<String>getValue(unsetPropertyPath); // Unset property -> null

      Reading a composite value and navigating to one of its leaves: 

          // Read the whole composite, then descend to one of its leaves.
    DataObject retrieved = person.getValue(addressPath);
    String street = retrieved.getValue(streetPath);

      Reading the elements of a list of composite values: 

          // A list of composites: bulk-set the list, then navigate from an element to its inner leaf.
    DataPropertyPath addressesPath = DataPropertyPath.newBuilder().originType(teamType).property(addressesProperty).build();
    DataObject mainSt = DataObject.newBuilder().dataType(addressType).value(streetPath, "Main St").build();
    DataObject highSt = DataObject.newBuilder().dataType(addressType).value(streetPath, "High St").build();
    Feature team = Feature.newBuilder().id(2L).dataType(teamType)
        .value(addressesPath, Arrays.asList(mainSt, highSt))
        .build();
    DataPropertyPath secondPath = DataPropertyPath.newBuilder().originType(teamType).property(addressesProperty).index(1).build();
    DataObject secondElement = team.getValue(secondPath);
    String secondStreet = secondElement.getValue(streetPath);

      Note: a ClassCastException may be thrown if you try to retrieve a geometry property value using a Geometry sub-type parameter that does not correspond with the actual type of the geometry property value.

      Type Parameters:
      T - the value type, chosen by property shape (see above).
      Parameters:
      propertyPath - the property for which to return a value.
      Returns:
      the value, or no value if the property exists in the DataType but is not set for this feature. For an indexed path, no value means the element at that index is explicitly unset.
      Throws:
      IllegalArgumentException - when the property does not exist in the DataType, T does not match the path's leaf type (for example the value is a Point geometry but ArcBand was requested), or the list is unset or the index is out of bounds for an indexed path.

    • getValue

      @Nullable public <T> T getValue(@NotNull String propertyName) throws IllegalArgumentException
      Convenience overload of getValue that resolves the property by name on this feature's data type.

      Equivalent to calling getValue with a DataPropertyPath built from getDataType() and propertyName.

      Performance note: this overload resolves the name on every call. To read the same property from many features in a tight loop, build a DataPropertyPath once and use the DataPropertyPath overload, which avoids the repeated lookup.

      Type Parameters:
      T - the value type, chosen by the property's shape (see the DataPropertyPath overload).
      Parameters:
      propertyName - the name of a property in this feature's data type.
      Returns:
      the value, or no value if the property exists but is not set for this feature.
      Throws:
      IllegalArgumentException - when no property with that name exists, or T does not match its type.
      Since:
      2026.1