Class ContentFeatureSource

Object
ContentFeatureSource
All Implemented Interfaces:
FeatureSource<SimpleFeatureType,SimpleFeature>, SimpleFeatureSource
Direct Known Subclasses:
ContentFeatureStore, CSVFeatureSource, GeoJSONFeatureSource, GraticuleFeatureSource, JDBCFeatureSource, MemoryFeatureSource, MongoFeatureSource, PropertyFeatureSource, STACFeatureSource, VectorMosaicFeatureSource, VPFFeatureSource, WFSStoredQueryFeatureSource

public abstract class ContentFeatureSource extends Object implements SimpleFeatureSource
Abstract implementation of FeatureSource.

This feature source works off of operations provided by FeatureCollection. Individual SimpleFeatureCollection implementations are provided by subclasses:

    #all(ContentState): Access to entire dataset #filtered(ContentState, Filter): Access to filtered dataset

Even though a feature source is read-only, this class is transaction aware. (see setTransaction(Transaction). The transaction is taken into account during operations such as #getCount() and getBounds() since these values may be affected by another operation (like writing to a FeautreStore) working against the same transaction.

Subclasses must also implement the buildFeatureType() method which builds the schema for the feature source.

Author:
Jody Garnett, Refractions Research Inc., Justin Deoliveira, The Open Planning Project
  • Field Details

    • entry

      protected ContentEntry entry
      The entry for the feature source.

      This entry is managed by the DataStore and is shared between all live ContentFeatureSource and ContentFeatureStore instances.

    • transaction

      protected Transaction transaction
      The transaction to work from, use {link ContentEntry.getState(Transaction) to access shared state in common to ContentFeatureSource and ContentFeatureStore working on this Transaction. The use of Transaction.AUTO_COMMIT is used access the origional/live content.
    • lock

      protected FeatureLock lock
      Current feature lock
    • hints

      protected Set<Hints.Key> hints
      Hints
    • query

      protected Query query
      The query defining the feature source
    • schema

      protected SimpleFeatureType schema
      Cached feature type (only set if this instance is a view)
    • queryCapabilities

      protected QueryCapabilities queryCapabilities
      The query capabilities returned by this feature source
  • Constructor Details

    • ContentFeatureSource

      public ContentFeatureSource(ContentEntry entry, Query query)
      Creates the new feature source from a query.

      The query is taken into account for any operations done against the feature source. For example, when getReader(Query) is called the query specified is "joined" to the query specified in the constructor. The query parameter may be null to specify that the feature source represents the entire set of features.

  • Method Details

    • getEntry

      public ContentEntry getEntry()
      The entry for the feature source.
    • getTransaction

      public Transaction getTransaction()
      The current transaction the feature source is working against.

      This transaction is used to derive the state for the feature source. A null value for a transaction represents the auto commit transaction: Transaction.AUTO_COMMIT.

    • setTransaction

      public void setTransaction(Transaction transaction)
      Sets the current transaction the feature source is working against.

      transaction may be null. This signifies that the auto-commit transaction is used: Transaction.AUTO_COMMIT.

      Parameters:
      transaction - The new transaction, or null.
    • getState

      public ContentState getState()
      The current state for the feature source.

      This value is derived from current transaction of the feature source.

    • getDataStore

      public ContentDataStore getDataStore()
      The datastore that this feature source originated from.

      Subclasses may wish to extend this method in order to type narrow its return type.

      Specified by:
      getDataStore in interface FeatureSource<SimpleFeatureType,SimpleFeature>
      Returns:
      the data source providing this FeatureSource
    • isView

      public final boolean isView()
      Indicates if this feature source is actually a view.
    • getInfo

      public ResourceInfo getInfo()
      A default ResourceInfo with a generic description.

      Subclasses should override to provide an explicit ResourceInfo object for their content.

      Specified by:
      getInfo in interface FeatureSource<SimpleFeatureType,SimpleFeature>
      Returns:
      description of features contents
    • getName

      public Name getName()
      Returns the same name than the feature type (ie, getSchema().getName() to honor the simple feature land common practice of calling the same both the Features produces and their types
      Specified by:
      getName in interface FeatureSource<SimpleFeatureType,SimpleFeature>
      Returns:
      the name of the features accessible through this FeatureSource
      Since:
      2.5
      See Also:
    • getSchema

      public final SimpleFeatureType getSchema()
      Returns the feature type or the schema of the feature source.

      This method delegates to buildFeatureType(), which must be implemented by subclasses. The result is cached in ContentState.getFeatureType().

      Specified by:
      getSchema in interface FeatureSource<SimpleFeatureType,SimpleFeature>
      Returns:
      the schema that will apply to features retrieved from this FeatureSource
    • getAbsoluteSchema

      protected final SimpleFeatureType getAbsoluteSchema()
      Helper method for returning the underlying schema of the feature source. This is a non-view this is the same as calling getSchema(), but in the view case the underlying "true" schema is returned.
    • getBounds

      public final ReferencedEnvelope getBounds() throws IOException
      Returns the bounds of the entire feature source.

      This method delegates to getBounds(Query):

         return getBounds(Query.ALL).
       
      Specified by:
      getBounds in interface FeatureSource<SimpleFeatureType,SimpleFeature>
      Returns:
      The bounding envelope of the feature data; or null if the bounds are unknown or too costly to calculate.
      Throws:
      IOException - on any errors calculating the bounds
    • getBounds

      public final ReferencedEnvelope getBounds(Query query) throws IOException
      Returns the bounds of the results of the specified query against the feature source.

      This method calls through to getBoundsInternal(Query) which subclasses must implement. It also contains optimizations which check state for cached values.

      Specified by:
      getBounds in interface FeatureSource<SimpleFeatureType,SimpleFeature>
      Parameters:
      query - the query to select features
      Returns:
      The bounding envelope of the feature data; or null if the bounds are unknown or too costly to calculate.
      Throws:
      IOException - on any errors calculating the bounds
    • getBoundsInternal

      protected abstract ReferencedEnvelope getBoundsInternal(Query query) throws IOException
      Calculates the bounds of a specified query. Subclasses must implement this method. If the computation is not fast, subclasses can return null.
      Throws:
      IOException
    • getCount

      public final int getCount(Query query) throws IOException
      Returns the count of the number of features of the feature source.

      This method calls through to getCountInternal(Query) which subclasses must implement. It also contains optimizations which check state for cached values.

      Specified by:
      getCount in interface FeatureSource<SimpleFeatureType,SimpleFeature>
      Parameters:
      query - the query to select features
      Returns:
      the numer of features that would be returned by the Query; or -1 if this cannot be calculated.
      Throws:
      IOException - if there are errors getting the count
    • getCountInternal

      protected abstract int getCountInternal(Query query) throws IOException
      Calculates the number of features of a specified query. Subclasses must implement this method. If the computation is not fast, it's possible to return -1.
      Throws:
      IOException
    • getFeatures

      public final ContentFeatureCollection getFeatures() throws IOException
      Returns the feature collection of all the features of the feature source.
      Specified by:
      getFeatures in interface FeatureSource<SimpleFeatureType,SimpleFeature>
      Specified by:
      getFeatures in interface SimpleFeatureSource
      Returns:
      features retrieved by the Query
      Throws:
      IOException - if the underlying data source cannot be accessed.
    • getReader

      public final FeatureReader<SimpleFeatureType,SimpleFeature> getReader() throws IOException
      Returns a feature reader for all features.

      This method calls through to getReader(Query).

      Throws:
      IOException
    • getFeatures

      public final ContentFeatureCollection getFeatures(Query query) throws IOException
      Returns the feature collection if the features of the feature source which meet the specified query criteria.
      Specified by:
      getFeatures in interface FeatureSource<SimpleFeatureType,SimpleFeature>
      Specified by:
      getFeatures in interface SimpleFeatureSource
      Parameters:
      query - DataAccess query for requested information, such as typeName, maxFeatures and filter.
      Returns:
      features retrieved by the Query
      Throws:
      IOException - if the underlying data source cannot be accessed.
      See Also:
    • getReader

      public final FeatureReader<SimpleFeatureType,SimpleFeature> getReader(Query query) throws IOException
      Returns a reader for the features specified by a query.
      Throws:
      IOException
    • accepts

      public void accepts(Query query, FeatureVisitor visitor, ProgressListener progress) throws IOException
      Visit the features matching the provided query.

      The default information will use getReader( query ) and pass each feature to the provided visitor. Subclasses should override this method to optimise common visitors:

      Often in the case of Filter.INCLUDES the information can be determined from a file header or metadata table.

      Parameters:
      visitor - Visitor called for each feature
      progress - Used to report progress; and errors on a feature by feature basis
      Throws:
      IOException
    • handleVisitor

      protected boolean handleVisitor(Query query, FeatureVisitor visitor) throws IOException
      Subclass method which allows subclasses to natively handle a visitor.

      Subclasses would override this method and return true in cases where the specific visitor could be handled without iterating over the entire result set of query. An example would be handling visitors that calculate aggregate values.

      Parameters:
      query - The query being made.
      visitor - The visitor to
      Returns:
      true if the visitor can be handled natively, otherwise false.
      Throws:
      IOException
    • getReaderInternal

      protected abstract FeatureReader<SimpleFeatureType,SimpleFeature> getReaderInternal(Query query) throws IOException
      Subclass method for returning a native reader from the datastore.

      It is important to note that if the native reader intends to handle any of the following natively:

      • reprojection
      • filtering
      • max feature limiting
      • sorting
      • locking
      • transactions
      Then it *must* set the corresponding flags to true:
      Throws:
      IOException
    • canReproject

      protected boolean canReproject()
      Determines if the datastore can natively perform reprojection.

      If the subclass can handle reprojection natively then it should override this method to return true . In this case it must do the reprojection or throw an exception.

      Not overriding this method or returning false will case the feature reader created by the subclass to be wrapped in a reprojecting decorator when the query specifies a coordinate system reproject (using crs and crsReproject)

      To handle reprojection an implementation should:

      See Also:
    • canLimit

      @Deprecated protected boolean canLimit()
      Deprecated.
      use canLimit(Query) instead.
    • canLimit

      protected boolean canLimit(Query query)
      Determines if the datastore can natively limit the number of features returned in a query.

      If the subclass can handle a map feature cap natively then it should override this method to return true . In this case it must do the cap or throw an exception.

      Not overriding this method or returning false will case the feature reader created by the subclass to be wrapped in a max feature capping decorator when the query specifies a max feature cap.

      See Also:
    • canOffset

      @Deprecated protected boolean canOffset()
      Deprecated.
      use canOffset(Query) instead.
    • canOffset

      protected boolean canOffset(Query query)
      Determines if the datastore can natively skip the first offset number of features returned in a query.

      If the subclass can handle a map feature cap natively then it should override this method to return true . In this case it must do the cap or throw an exception.

      Not overriding this method or returning false will case the feature reader created by the subclass to be accessed offset times before being returned to the caller.

    • canFilter

      @Deprecated protected boolean canFilter()
      Deprecated.
      use canFilter(Query) instead.
    • canFilter

      protected boolean canFilter(Query query)
      Determines if the datastore can natively perform a filtering.

      If the subclass can handle filtering natively it should override this method to return true. In this case it must do the filtering or throw an exception. This includes the case of partial native filtering where the datastore can only handle part of the filter natively. In these cases it is up to the subclass to apply a decorator to the reader it returns which will handle any part of the filter can was not applied natively. See FilteringFeatureReader.

      Not overriding this method or returning false will cause the feature reader created by the subclass to be wrapped in a filtering feature reader when the query specifies a filter. See FilteringFeatureReader.

    • canRetype

      @Deprecated protected boolean canRetype()
      Deprecated.
      use canRetype(Query) instead.
    • canRetype

      protected boolean canRetype(Query query)
      Determines if the datastore can natively perform "retyping" which includes limiting the number of attributes returned and reordering of those attributes

      If the subclass can handle retyping natively it should override this method to return true. In this case it must do the retyping or throw an exception.

      Not overriding this method or returning false will cause the feature reader created by the subclass to be wrapped in a retyping feature reader when the query specifies a retype.

      See Also:
    • canSort

      @Deprecated protected boolean canSort()
      Deprecated.
      use canSort(Query) instead.
    • canSort

      protected boolean canSort(Query query)
      Determines if the datastore can natively perform sorting.

      If the subclass can handle retyping natively it should override this method to return true. In this case it must do the retyping or throw an exception.

      Not overriding this method or returning false will cause an exception to be thrown when the query specifies sorting.

      See Also:
    • canTransact

      protected boolean canTransact()
      Determines if the store can natively manage transactions.

      If a subclass can handle transactions natively it should override this method to return true and deal with transactions on its own, including firing feature modifications events.

      Returns:
      true if transaction independence has custom implementation
    • canEvent

      protected boolean canEvent()
      Determines if the store takes responsibility for issuing events.

      If a subclass issue events (as part of its low level writer implementation) then it should override this method to return true.

      Returns:
      true if event notification has custom implementation
    • getView

      public final ContentFeatureSource getView(Query query) throws IOException
      Creates a new feature source for the specified query.

      If the current feature source already has a defining query it is joined to the specified query.

      Throws:
      IOException
    • getFeatures

      public final ContentFeatureCollection getFeatures(Filter filter) throws IOException
      Returns the feature collection for the features which match the specified filter.

      This method calls through to getFeatures(Query).

      Specified by:
      getFeatures in interface FeatureSource<SimpleFeatureType,SimpleFeature>
      Specified by:
      getFeatures in interface SimpleFeatureSource
      Parameters:
      filter - the filter to select features; must not be null (use Filter.INCLUDE instead)
      Returns:
      features retrieved by the Filter
      Throws:
      IOException - if the underlying data source cannot be accessed.
      See Also:
    • getReader

      public final FeatureReader<SimpleFeatureType,SimpleFeature> getReader(Filter filter) throws IOException
      Returns a reader for features specified by a particular filter.

      This method calls through to getReader(Query).

      Throws:
      IOException
    • getView

      public final ContentFeatureSource getView(Filter filter) throws IOException
      Throws:
      IOException
    • addFeatureListener

      public final void addFeatureListener(FeatureListener listener)
      Adds an listener or observer to the feature source.

      Listeners are stored on a per-transaction basis.

      Specified by:
      addFeatureListener in interface FeatureSource<SimpleFeatureType,SimpleFeature>
      Parameters:
      listener - the new listener
    • removeFeatureListener

      public final void removeFeatureListener(FeatureListener listener)
      Removes a listener from the feature source.
      Specified by:
      removeFeatureListener in interface FeatureSource<SimpleFeatureType,SimpleFeature>
      Parameters:
      listener - the listener to remove
    • getSupportedHints

      public final Set<RenderingHints.Key> getSupportedHints()
      The hints provided by the feature store.

      Subclasses should implement addHints(Set) to provide additional hints.

      Specified by:
      getSupportedHints in interface FeatureSource<SimpleFeatureType,SimpleFeature>
      Returns:
      a set of RenderingHints#Key objects; may be empty but never null
      See Also:
    • addHints

      protected void addHints(Set<Hints.Key> hints)
      Subclass hook too add additional hints.

      By default, the followings are already present:

      Parameters:
      hints - The set of hints supported by the feature source.
    • joinQuery

      protected Query joinQuery(Query query)
      Convenience method for joining a query with the definining query of the feature source.
    • resolvePropertyNames

      protected Query resolvePropertyNames(Query query)
      This method changes the query object so that all propertyName references are resolved to simple attribute names against the schema of the feature source.

      For example, this method ensures that propertyName's such as "gml:name" are rewritten as simply "name".

    • resolvePropertyNames

      protected Filter resolvePropertyNames(Filter filter)
      Transform provided filter; resolving property names
    • buildFeatureType

      protected abstract SimpleFeatureType buildFeatureType() throws IOException
      Creates the feature type or schema for the feature source.

      Implementations should use SimpleFeatureTypeBuilder to build the feature type. Also, the builder should be injected with the feature factory which has been set on the DataStore (see ContentDataStore.getFeatureFactory(). Example:

         SimpleFeatureTypeBuilder b = new SimpleFeatureTypeBuilder();
         b.setFeatureTypeFactory( getDataStore().getFeatureTypeFactory() );
      
         //build the feature type
         ...
       
      Throws:
      IOException
    • buildQueryCapabilities

      protected QueryCapabilities buildQueryCapabilities()
      Builds the query capabilities for this feature source. The default implementation returns a newly built QueryCapabilities, subclasses are advised to build their own.
    • getQueryCapabilities

      public QueryCapabilities getQueryCapabilities()
      SimpleFeatureCollection optimized for read-only access.

      Available via getView( filter ):

      • getFeatures().sort( sort )
      • getFeatures( filter ).sort( sort )

      In particular this method of data access is intended for rendering and other high speed operations; care should be taken to optimize the use of FeatureVisitor.

      Specified by:
      getQueryCapabilities in interface FeatureSource<SimpleFeatureType,SimpleFeature>
      Returns:
      readonly access
    • setFeatureLock

      public final void setFeatureLock(FeatureLock lock)
      Sets the feature lock of the feature store.
    • lockFeatures

      public final int lockFeatures() throws IOException
      Locks all features.

      This method calls through to lockFeatures(Filter).

      Throws:
      IOException
    • lockFeatures

      public final int lockFeatures(Query query) throws IOException
      Locks features specified by a query.

      This method calls through to lockFeatures(Filter).

      Throws:
      IOException
    • lockFeatures

      public final int lockFeatures(Filter filter) throws IOException
      Locks features specified by a filter.
      Throws:
      IOException
    • unLockFeatures

      public final void unLockFeatures() throws IOException
      Unlocks all features.

      This method calls through to unLockFeatures(Filter).

      Throws:
      IOException
    • unLockFeatures

      public final void unLockFeatures(Query query) throws IOException
      Unlocks features specified by a query.

      This method calls through to unLockFeatures(Filter).

      Throws:
      IOException
    • unLockFeatures

      public final void unLockFeatures(Filter filter) throws IOException
      Unlocks features specified by a filter.
      Throws:
      IOException
    • canLock

      protected boolean canLock()
      Determines if the datastore can perform feature locking natively.

      If #getWriterInternal(Query, int) returns a feature writer that supports feature locking natively, it should override this method to return true .

      Not overriding this method or returning false will cause ContentFeatureStore to use the InProcessLockingManager to return a FeatureWriter that honors locks.

    • processLock

      protected FeatureLock processLock(FeatureLock lock)
      If the subclass implements native locking, this method is invoked before the feature lock is (re)assigned to this store.
      Parameters:
      lock - - a FeatureLock instance
      Returns:
      a processed FeatureLock instance
    • doLockInternal

      protected void doLockInternal(String typeName, SimpleFeature feature) throws IOException
      This method must be implemented overridden when native locking is indicated by canLock().
      Parameters:
      typeName - SimpleFeature type name
      feature - SimpleFeature instance
      Throws:
      IOException
    • doUnlockInternal

      protected void doUnlockInternal(String typeName, SimpleFeature feature) throws IOException
      This method must be implemented overridden when native locking is indicated by canLock().
      Parameters:
      typeName - Feature type name
      feature - Feature instance
      Throws:
      IOException