Interface FeatureSet

  • All Superinterfaces:
    Data­Set, Resource
    All Known Subinterfaces:
    Writable­Feature­Set

    public interface FeatureSet
    extends DataSet
    A dataset providing access to a stream of features. All features share a common set of properties described by get­Type(). The common set of properties does not need to enumerate all possible properties since additional properties can be defined in subtypes. In many cases at least one property is a geometry, but features without geometry are also allowed.
    Since:
    0.8

    Defined in the sis-storage module

    • Method Detail

      • getType

        DefaultFeatureType getType()
                            throws DataStoreException
        Returns a description of properties that are common to all features in this dataset. The feature type contains the definition of all properties, including but not only:
        • Name to use for accessing the property
        • Human-readable description
        • Type of values
        • Multiplicity (minimum and maximum number of occurrences)
        • Coordinate Reference System.
        All features returned by features(boolean) will be either of that type, or a sub-type of it.
        Relationship with metadata: if subtypes exist, their list may be obtained from the metadata like below (if the Feature­Set implementation provides that information):
        for (ContentInformation content : metadata.getContentInfo()) {
            if (content instanceof FeatureCatalogueDescription) {
                for (FeatureTypeInfo info : ((FeatureCatalogueDescription) content).getFeatureTypeInfo()) {
                    GenericName name = info.getFeatureTypeName();
                    // ... add the name to some list ...
                }
            }
        }
        Returns:
        description of common properties (never null).
        Throws:
        Data­Store­Exception - if an error occurred while reading definitions from the underlying data store.
      • subset

        default FeatureSet subset​(Query query)
                           throws UnsupportedQueryException,
                                  DataStoreException
        Requests a subset of features and/or feature properties from this resource. The filtering can be applied in two domains:
        • The returned Feature­Set may contain a smaller number of Feature instances.
        • In each Feature instance of the returned set, the number of properties may be smaller.
        While it is technically possible to return a transformed feature set (i.e. containing feature properties not found in this original Feature­Set, for example as a result of some computation), such usages should be rare. Transformations should be the topic of a separated processing package. This subset(Query) method is rather for allowing Data­Store implementations to optimize the overall filtering by using the tools available with their format (for example an R-tree). Bounding­Box filters are the most common case of optimization implemented by Data­Store.

        The returned subset may be a view of this set, i.e. changes in this Feature­Set may be reflected immediately on the returned subset (and conversely), but not necessarily. However the returned subset may not have the same capabilities as this Feature­Set. In particular, write operations may become unsupported after complex queries.

        The default implementation tries to execute the query by filtering the stream of features, which may be inefficient — subclasses are encouraged to override. An Unsupported­Query­Exception is thrown if the given query is unrecognized.

        Parameters:
        query - definition of feature and feature properties filtering applied at reading time.
        Returns:
        resulting subset of features (never null).
        Throws:
        Unsupported­Query­Exception - if this Feature­Set can not execute the given query. This includes query validation errors.
        Data­Store­Exception - if another error occurred while processing the query.
      • features

        Stream<AbstractFeature> features​(boolean parallel)
                                  throws DataStoreException
        Returns a stream of all features contained in this dataset. For all features, the following condition shall be true:
        get­Type().is­Assignable­From(feature.get­Type())
        Most implementations will create Feature instances on-the-fly when the stream terminal operation is executed. A tryfinally block should be used for releasing Data­Store resources used by the operation. If a checked exception happens during stream execution, that exception will be wrapped in an unchecked Backing­Store­Exception. The following code shows how this stream can be used:
        void myReadOperation() throws DataStoreException {
            try (Stream<Feature> features = myDataStore.features(false)) {
                // Use the stream here.
            } catch (BackingStoreException e) {
                throw e.unwrapOrRethrow(DataStoreException.class);
            }
        }
        The parallel argument specifies whether a parallelized stream is desired. If false, the stream is guaranteed to be sequential. If true, the stream may or may not be parallel; implementations are free to ignore this argument if they do not support parallelism.
        Parameters:
        parallel - true for a parallel stream (if supported), or false for a sequential stream.
        Returns:
        all features contained in this dataset.
        Throws:
        Data­Store­Exception - if an error occurred while creating the stream.