Package com.luciad.models.features

Class Feature.Builder

java.lang.Object
com.luciad.models.features.Feature.Builder
All Implemented Interfaces:
AutoCloseable
Enclosing class:
Feature
public static final class Feature.Builder extends Object implements AutoCloseable
Allows the incremental creation of a Feature object.

Make sure to

Otherwise a java.lang.IllegalStateException will be thrown.

  • Constructor Details

    • Builder

      public Builder(@NotNull Feature.Builder other)
      Copy constructor.
      Parameters:
      other - the builder to copy.

  • Method Details

    • finalize

      protected void finalize()
      Overrides:
      finalize in class Object

    • close

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

    • build

      @NotNull public Feature build() throws IllegalStateException
      Build the feature using the settings configured.

      After this method is invoked once, this builder can no longer be used.

      Returns:
      the feature
      Throws:
      IllegalStateException - if the ID or dataType are not configured

    • id

      @NotNull public Feature.Builder id(long id)
      Configures the id of the feature being built.

      A feature id should be unique across a model.

      This method is not mandatory, though Features in a model must have an id. It is allowed to temporarily have features without id, for example during Feature creation. As soon as such a temporary Feature is added to a model, it must be assigned an id though.

      When no id is set, Feature#getId will throw an exception.

      Parameters:
      id - the id
      Returns:
      this builder

    • resetId

      @NotNull public Feature.Builder resetId()
      Resets the id.

      Calling this method will cause the built Feature to have no id, thus throwing an exception when calling Feature#getId.

      Features in a model must have an id. It is allowed to temporarily have features without id, for example during Feature creation. As soon as such a temporary Feature is added to a model, it must be assigned an id though.

      Note that for a newly created Feature.Builder using the Feature#newBuilder() method, the id will be empty by default. This method is less useful in that case. It is mainly useful when using the Feature#asBuilder() method.

      Returns:
      this builder
      Since:
      2023.1

    • dataType

      @NotNull public Feature.Builder dataType(@NotNull DataType dataType)
      Configures the dataType of the feature being built.

      The DataType needs to be set before value() is called.

      Parameters:
      dataType - the data type
      Returns:
      this builder

    • resetValue

      @NotNull public Feature.Builder resetValue(@NotNull String propertyName) throws IllegalArgumentException
      Convenience overload of resetValue that resolves the property by name on the configured data type and resets the value.

      The value type does not need to be named: it is derived from the property.

      The dataType() must be configured before this is called.

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

      Parameters:
      propertyName - the name of a property in the configured data type.
      Returns:
      this builder.
      Throws:
      IllegalArgumentException - when the dataType is not configured or no property with that name exists.
      Since:
      2026.1

    • value

      @NotNull public <T> Feature.Builder value(@NotNull DataPropertyPath propertyPath, @NotNull T value) throws IllegalArgumentException
      Sets the value associated with the given property.

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

      • Scalar property: T is the element type.
      • Composite property (value type is a non-primitive DataType): T is DataObject, with a DataType that must equal the property's value type.
      • List property: T is the list type. One bulk set sizes and populates the list. Individual elements may be unset.
      • List element (path with a terminal index step): T is the element type (DataObject for a composite element), and the single element is overwritten. The list must already be populated by a bulk set: setting an element of an unset list, or at an out-of-bounds index, throws an exception.

      Example

          featureBuilder.value(booleanPropertyPath, booleanValue);
    featureBuilder.value(intPropertyPath, intValue);
    featureBuilder.value(longPropertyPath, longValue);
    featureBuilder.value(floatPropertyPath, floatValue);
    featureBuilder.value(doublePropertyPath, doubleValue);
    featureBuilder.value(stringPropertyPath, stringValue);
    featureBuilder.value(geometryPropertyPath, geometry);

      Setting a list-typed property (bulk set, then overwrite a single element): 

          // Bulk-set the list (a null element marks an unknown value), then overwrite one element through its indexed path.
    Feature feature = Feature.newBuilder().id(1L).dataType(trackType)
        .value(timePath, Arrays.asList(100L, null, 300L))
        .value(firstTimePath, 150L)
        .build();
      Type Parameters:
      T - the value type, chosen by property shape (see above).
      Parameters:
      propertyPath - the property for which to set the value.
      value - the value.
      Returns:
      this builder.
      Throws:
      IllegalArgumentException - when the dataType has not been configured, the property does not exist in the DataType, T does not match the path's leaf type, or the list is unset or the index is out-of-bounds for an indexed path.

    • value

      @NotNull public Feature.Builder value(@NotNull DataPropertyPath propertyPath, @NotNull List<?> values) throws IllegalArgumentException
      Throws:
      IllegalArgumentException

    • resetValue

      @NotNull public Feature.Builder resetValue(@NotNull DataPropertyPath propertyPath) throws IllegalArgumentException
      Resets the value associated with the given property, such that the built Feature returns an empty optional for it.

      For a newly created Feature.Builder (Feature#newBuilder()) all values are empty by default, so this is mainly useful with Feature#asBuilder().

      The effect on a list-typed property depends on the path:

      • List path: the list is cleared (becomes unset).
      • List element: that single element is set to empty. The list must already be populated: resetting an element of an unset list, or at an out-of-bounds index, throws an exception.
      Parameters:
      propertyPath - the property for which to reset the value.
      Returns:
      this builder.
      Throws:
      IllegalArgumentException - when the dataType has not been configured, the property does not exist in the DataType, or the list is unset, or the index is out-of-bounds for an indexed path.

    • value

      @NotNull public <T> Feature.Builder value(@NotNull String propertyName, @NotNull T value) throws IllegalArgumentException
      Convenience overload of value that resolves the property by name on the configured data type and sets the value.

      The dataType() must be configured before this is called.

      Performance note: this overload resolves the name on every call. To set the same property on 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 the configured data type.
      value - the value.
      Returns:
      this builder.
      Throws:
      IllegalArgumentException - when the dataType is not configured, no property with that name exists, or T does not match its type.
      Since:
      2026.1

    • value

      @NotNull public Feature.Builder value(@NotNull String propertyName, @NotNull List<?> values) throws IllegalArgumentException
      Throws:
      IllegalArgumentException