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

# Class ConcatenatedFeatureSet

Object
AbstractResource
AbstractFeatureSet
ConcatenatedFeatureSet

All Implemented Interfaces:
  `DataSet`, `FeatureSet`, `Resource`

public class ConcatenatedFeatureSet extends AbstractFeatureSet
Exposes a sequence of `FeatureSet`s as a single one. The concatenation is built from an array or collection of input feature sets, copied verbatim in iteration order and without removal of duplicated elements. All input feature sets must share a common type, or at least a common super-type. The feature type of this concatenated set will be the most specific type found among all input feature sets.

## Identification

There is no identifier since this feature set is a computation result.

## Multi-threading

Concatenated feature set is immutable and thread-safe if all input feature sets are immutable and thread-safe.

Since:
  1.0

- ## Field Summary

  ### Fields inherited from class AbstractResource

  `listeners`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `ConcatenatedFeatureSet(Resource parent, FeatureSet[] sources)`
  Creates a new feature set as a concatenation of the sequence of features given by the `sources`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `clearCache()`
  Clears any cache in this resource, forcing the data to be recomputed when needed again.
  `static FeatureSet`
  `create(Collection<? extends FeatureSet> sources)`
  Creates a new feature set as a concatenation of the sequence of features given by the `sources`.
  `static FeatureSet`
  `create(FeatureSet... sources)`
  Creates a new feature set as a concatenation of the sequence of features given by the `sources`.
  `protected Metadata`
  `createMetadata()`
  Invoked in a synchronized block the first time that `getMetadata()` is invoked.
  `Stream<AbstractFeature>`
  `features(boolean parallel)`
  Returns a stream of all features contained in this concatenated dataset.
  `final Optional<Envelope>`
  `getEnvelope()`
  Returns the union of the envelopes in all aggregated feature sets.
  `OptionalLong`
  `getFeatureCount()`
  Returns an estimation of the number of features in this set, or an empty value if unknown.
  `DefaultFeatureType`
  `getType()`
  Returns the most specific feature type common to all feature sets given to the constructor.
  `FeatureSet`
  `subset(Query query)`
  Requests a subset of features and/or feature properties from this resource.

  ### Methods inherited from class AbstractFeatureSet

  `getIdentifier`

  ### Methods inherited from class AbstractResource

  `addListener, getMetadata, getSynchronizationLock, removeListener`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface Resource

  `addListener, getMetadata, removeListener`

- ## Constructor Details

  - ### ConcatenatedFeatureSet

    protected ConcatenatedFeatureSet(Resource parent, FeatureSet[] sources) throws DataStoreException
    Creates a new feature set as a concatenation of the sequence of features given by the `sources`. This constructor does not verify that the given `sources` array contains at least two elements; this verification must be done by the caller. This constructor retains the given `sources` array by direct reference; clone, if desired, shall be done by the caller.
    Parameters:
      `parent` - the parent resource, or `null` if none.
      `sources` - the sequence of feature sets to expose in a single set. Must neither be null, empty nor contain a single element only.
    Throws:
      `DataStoreException` - if given feature sets does not share any common type.

- ## Method Details

  - ### create

    public static FeatureSet create(FeatureSet... sources) throws DataStoreException
    Creates a new feature set as a concatenation of the sequence of features given by the `sources`. The given array shall be non-empty. If the array contains only 1 element, that element is returned.
    Parameters:
      `sources` - the sequence of feature sets to expose in a single set.
    Returns:
      the concatenation of given feature set.
    Throws:
      `DataStoreException` - if given feature sets does not share any common type.

  - ### create

    public static FeatureSet create(Collection<? extends FeatureSet> sources) throws DataStoreException
    Creates a new feature set as a concatenation of the sequence of features given by the `sources`. The given collection shall be non-empty. If the collection contains only 1 element, that element is returned.
    Parameters:
      `sources` - the sequence of feature sets to expose in a single set.
    Returns:
      the concatenation of given feature set.
    Throws:
      `DataStoreException` - if given feature sets does not share any common type.

  - ### getType

    public DefaultFeatureType getType()
    Returns the most specific feature type common to all feature sets given to the constructor.
    Returns:
      the common type of all features returned by this set.

  - ### getFeatureCount

    public OptionalLong getFeatureCount()
    Returns an estimation of the number of features in this set, or an empty value if unknown. This is the sum of the estimations provided by all source sets, or empty if at least one source could not provide an estimation.
    Overrides:
      `getFeatureCount` in class `AbstractFeatureSet`
    Returns:
      estimation of the number of features.

  - ### features

    public Stream<AbstractFeature> features(boolean parallel)
    Returns a stream of all features contained in this concatenated dataset. If the `parallel` argument is `false`, then datasets are traversed in the order they were specified at construction time. If the `parallel` argument is `true`, then datasets are traversed in no determinist order. If an error occurred while reading the feature instances from a source, then the error is wrapped in a `BackingStoreException`.
    Parameters:
      `parallel` - `true` for a parallel stream, or `false` for a sequential stream.
    Returns:
      all features contained in this dataset.

  - ### subset

    public FeatureSet subset(Query query) throws DataStoreException
    Requests a subset of features and/or feature properties from this resource.
    Parameters:
      `query` - definition of feature and feature properties filtering applied at reading time.
    Returns:
      resulting subset of features (never `null`).
    Throws:
      `DataStoreException` - if an error occurred while processing the query.
    See Also:
      - `GridCoverageResource​.subset(CoverageQuerty)`
      - `FeatureQuery​.execute(FeatureSet)`

  - ### getEnvelope

    public final Optional<Envelope> getEnvelope() throws DataStoreException
    Returns the union of the envelopes in all aggregated feature sets. This method tries to find a CRS common to all feature sets. If no common CRS can be found, then the envelope is absent.
    Specified by:
      `getEnvelope` in interface `DataSet`
    Overrides:
      `getEnvelope` in class `AbstractResource`
    Returns:
      union of envelopes from all dependencies.
    Throws:
      `DataStoreException` - if an error occurred while computing the envelope.

  - ### createMetadata

    protected Metadata createMetadata() throws DataStoreException
    Invoked in a synchronized block the first time that `getMetadata()` is invoked. The default implementation adds the information documented in the parent class, then adds the dependencies as lineages.
    Overrides:
      `createMetadata` in class `AbstractFeatureSet`
    Returns:
      the newly created metadata, or `null` if unknown.
    Throws:
      `DataStoreException` - if an error occurred while reading metadata from the data stores.

  - ### clearCache

    protected void clearCache()
    Clears any cache in this resource, forcing the data to be recomputed when needed again. This method should be invoked if the data in underlying data store changed.
    Overrides:
      `clearCache` in class `AbstractResource`