Module org.apache.sis.storage
Package org.apache.sis.storage

# Interface WritableFeatureSet

All Superinterfaces:
  `DataSet`, `FeatureSet`, `Resource`

public interface WritableFeatureSet extends FeatureSet
A `FeatureSet` with writing capabilities. `WritableFeatureSet` inherits the reading capabilities from its parent and adds the capabilities to add, remove or replace feature instances.

Since:
  1.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(Iterator<? extends AbstractFeature> features)`
  Inserts new feature instances in this `FeatureSet`.
  `void`
  `removeIf(Predicate<? super AbstractFeature> filter)`
  Removes all feature instances from this `FeatureSet` which matches the given predicate.
  `void`
  `replaceIf(Predicate<? super AbstractFeature> filter, UnaryOperator<AbstractFeature> updater)`
  Updates all feature instances from this `FeatureSet` which match the given predicate.
  `void`
  `updateType(DefaultFeatureType newType)`
  Declares or redefines the type of all feature instances in this feature set.

  ### Methods inherited from interface DataSet

  `getEnvelope`

  ### Methods inherited from interface FeatureSet

  `features, getType, subset`

  ### Methods inherited from interface Resource

  `addListener, getIdentifier, getMetadata, removeListener`

- ## Method Details

  - ### updateType

    void updateType(DefaultFeatureType newType) throws DataStoreException
    Declares or redefines the type of all feature instances in this feature set. In the case of a newly created feature set, this method can be used for defining the type of features to be stored (this is not a required step however). In the case of a feature set which already contains feature instances, this operation may take an undefined amount of time to execute since all features in the set may need to be transformed.

    Feature sets may restrict the kind of changes that are allowed. An `IllegalFeatureTypeException` will be thrown if the given type contains incompatible property changes.

    Parameters:
      `newType` - new feature type definition (not `null`).
    Throws:
      `IllegalFeatureTypeException` - if the given type is not compatible with the types supported by the store.
      `DataStoreException` - if another error occurred while changing the feature type.

  - ### add

    void add(Iterator<? extends AbstractFeature> features) throws DataStoreException
    Inserts new feature instances in this `FeatureSet`. Any feature already present in this `FeatureSet` will remain unmodified. If a feature property is used as unique identifier, then:
    - If a given feature assigns to that property a value already in use, an exception will be thrown.
    - If given features do not assign value to that property, identifiers should be generated by the data store.
    After successful insertion, the new features may appear after the features already present but not necessarily; ordering is `DataStore` specific.

    #### API note

    This method expects an `Iterator` rather than a `Stream` for easing inter-operability with various API. Implementing a custom `Iterator` requires less effort than implementing a `Stream`. On the other side if the user has a `Stream`, obtaining an `Iterator` can be done by a call to `BaseStream​.iterator()`.
    Parameters:
      `features` - feature instances to insert or copy in this `FeatureSet`.
    Throws:
      `IllegalFeatureTypeException` - if a feature given by the iterator is not of the type expected by this `FeatureSet`.
      `DataStoreException` - if another error occurred while storing new features.

  - ### removeIf

    void removeIf(Predicate<? super AbstractFeature> filter) throws DataStoreException
    Removes all feature instances from this `FeatureSet` which matches the given predicate.
    Parameters:
      `filter` - a predicate which returns `true` for feature instances to be removed.
    Throws:
      `DataStoreException` - if an error occurred while removing features.

  - ### replaceIf

    void replaceIf(Predicate<? super AbstractFeature> filter, UnaryOperator<AbstractFeature> updater) throws DataStoreException
    Updates all feature instances from this `FeatureSet` which match the given predicate. For each `Feature` instance matching the given `Predicate`, the `UnaryOperator​.apply(Feature)` method will be invoked. `UnaryOperator`s are free to modify the given `Feature` in-place or to return a different feature instance. Two behaviors are possible:
    - If the operator returns a non-null `Feature`, then the modified feature is stored in replacement of the previous feature (not necessarily at the same location).
    - If the operator returns `null`, then the feature will be removed from the `FeatureSet`.
    Parameters:
      `filter` - a predicate which returns `true` for feature instances to be updated.
      `updater` - operation called for each matching `Feature` instance.
    Throws:
      `IllegalFeatureTypeException` - if a feature given by the operator is not of the type expected by this `FeatureSet`.
      `DataStoreException` - if another error occurred while replacing features.