org.apache.sis.storage

## Interface Aggregate

- All Superinterfaces:
    Resource
  All Known Implementing Classes:
    NetcdfStore

      public interface Aggregate
      extends Resource

  A collection of resources. An aggregate can have two or more components. Each component can be another aggregate, thus forming a tree of resources. Different kinds of aggregate may exist for various reasons, for example (adapted from ISO 19115):
  - Series: a generic collection of resources that share similar characteristics (theme, date, resolution, etc.). The exact definition is determined by the data provider. See `ScopeCode​.SERIES` for more examples.
  - Sensor series: a collection of resources observed by the same sensor.
  - Platform series: a collection of resources observed by sensors installed on the same platform. The components of a platform series are sensor series. Those components usually share the same geospatial geometry.
  - Production series: a collection of resources produced using the same process. Members of a production series share lineage and processing history.
  - Initiative: a collection of resources related by their participation in a common initiative.
  - Transfer aggregate: a set of resources collected for the purpose of transfer. The components may be the results of an ad hoc query, for example on a Web Service.
  The same resource may be part of more than one aggregate. For example the same resource could be part of a production series and a transfer aggregate. In Apache SIS implementation, those two kinds of aggregate will usually be implemented by different `DataStore` instances.
  Metadata
  Aggregates should have `metadata` / `metadataScope` / `resourceScope` sets to `ScopeCode​.SERIES` or `ScopeCode​.INITIATIVE` if applicable. If not too expensive to compute, the names of all components should be listed as associated resources with an `AssociationType​.IS_COMPOSED_OF` relation.
  Since:
    0.8

  Defined in the `sis-storage` module

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `Resource` | `add(Resource resource)` Adds a new `Resource` in this `Aggregate`.
    `Collection<Resource>` | `components()` Returns the children resources of this aggregate.
    `void` | `remove(Resource resource)` Removes a `Resource` from this `Aggregate`.

    - ### Methods inherited from interface Resource

      `getMetadata`

- - ### Method Detail

    - #### components

          Collection<Resource> components()
                                   throws DataStoreException

      Returns the children resources of this aggregate. The returned collection contains the resources listed by their name in the following metadata elements. The returned collection may contain more resources if the metadata are incomplete, and the resources do not need to be in the same order:

      > `this.metadata` / `identificationInfo` / `associatedResource` with `AssociationType​.IS_COMPOSED_OF`

      The name of each child resource in the returned collection is given by the following metadata element:

      > `child.metadata` / `identificationInfo` / `citation` / `title`

      Lazy resource instantiation
      If the collection instantiates components only when first needed, and if a checked exception occurs during invocation of a `Collection` or `Iterator` method, then the collection or the iterator should wrap the exception in a `BackingStoreException`.
      Returns:
        all children resources that are components of this aggregate. Never `null`.
      Throws:
        `DataStoreException` - if an error occurred while fetching the components.

    - #### add

          Resource add(Resource resource)
                throws ReadOnlyStorageException,
                       DataStoreException

      Adds a new `Resource` in this `Aggregate`. The given `Resource` will be copied, and the effectively added resource returned. The effectively added resource may differ from the given resource in many aspects. The possible changes may include the followings but not only:
      - types and properties names
      - `CoordinateReferenceSystem`
      - `Metadata`
      Warning: copying informations between stores may produce differences in many aspects. The range of changes depends both on the original `Resource` structure and the target `Resource` structure. If the differences are too large, then this `Aggregate` may throw an exception.
      Parameters:
        `resource` - the resource to copy in this `Aggregate`.
      Returns:
        the effectively added resource. May be `resource` itself if it has been added verbatim.
      Throws:
        `ReadOnlyStorageException` - if this instance does not support write operations.
        `DataStoreException` - if the given resource can not be stored in this `Aggregate` for another reason.

    - #### remove

          void remove(Resource resource)
               throws ReadOnlyStorageException,
                      DataStoreException

      Removes a `Resource` from this `Aggregate`. This operation is destructive: the `Resource` and it's related data will be removed.

      The default implementation throws `ReadOnlyStorageException`.

      Parameters:
        `resource` - child resource to remove, should not be null.
      Throws:
        `ReadOnlyStorageException` - if this instance does not support write operations.
        `DataStoreException` - if the given resource could not be removed for another reason.

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.