org.geotools.data.store
Class ContentFeatureSource

Object
  extended by ContentFeatureSource
All Implemented Interfaces:
FeatureSource<SimpleFeatureType,SimpleFeature>, SimpleFeatureSource
Direct Known Subclasses:
ContentFeatureStore, JDBCFeatureSource

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:

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 Summary
protected  ContentEntry entry
          The entry for the feature source.
protected  Set<Hints.Key> hints
          hints
protected  FeatureLock lock
          current feature lock
protected  Query query
          The query defining the feature source
protected  QueryCapabilities queryCapabilities
          The query capabilities returned by this feature source
protected  SimpleFeatureType schema
          cached feature type (only set if this instance is a view)
protected  Transaction transaction
          The transaction to work from
 
Constructor Summary
ContentFeatureSource(ContentEntry entry, Query query)
          Creates the new feature source from a query.
 
Method Summary
 void accepts(Query query, FeatureVisitor visitor, ProgressListener progress)
          Visit the features matching the provided query.
 void addFeatureListener(FeatureListener listener)
          Adds an listener or observer to the feature source.
protected  void addHints(Set<Hints.Key> hints)
          Subclass hook too add additional hints.
protected abstract  SimpleFeatureType buildFeatureType()
          Creates the feature type or schema for the feature source.
protected  QueryCapabilities buildQueryCapabilities()
          Builds the query capabilities for this feature source.
protected  boolean canEvent()
          Determines if the store takes responsibility for issuing events.
protected  boolean canFilter()
          Determines if the datastore can natively perform a filtering.
protected  boolean canLimit()
          Determines if the datastore can natively limit the number of features returned in a query.
protected  boolean canLock()
          Determines if the datastore can perform feature locking natively.
protected  boolean canOffset()
          Determines if the datastore can natively skip the first offset number of features returned in a query.
protected  boolean canReproject()
          Determines if the datastore can natively perform reprojection..
protected  boolean canRetype()
          Determines if the datasatore 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.
protected  boolean canSort()
          Determines if the datastore can natively perform sorting.
protected  boolean canTransact()
          Determines if the store can natively manage transactions.
protected  void doLockInternal(String typeName, SimpleFeature feature)
          This method must be implemented overridden when native locking is indicated by canLock().
protected  void doUnlockInternal(String typeName, SimpleFeature feature)
          This method must be implemented overridden when native locking is indicated by canLock().
protected  SimpleFeatureType getAbsoluteSchema()
          Helper method for returning the underlying schema of the feature source.
 ReferencedEnvelope getBounds()
          Returns the bounds of the entire feature source.
 ReferencedEnvelope getBounds(Query query)
          Returns the bounds of the results of the specified query against the feature source.
protected abstract  ReferencedEnvelope getBoundsInternal(Query query)
          Calculates the bounds of a specified query.
 int getCount(Query query)
          Returns the count of the number of features of the feature source.
protected abstract  int getCountInternal(Query query)
          Calculates the number of features of a specified query.
 ContentDataStore getDataStore()
          The datastore that this feature source originated from.
 ContentEntry getEntry()
          The entry for the feature source.
 ContentFeatureCollection getFeatures()
          Returns the feature collection of all the features of the feature source.
 ContentFeatureCollection getFeatures(Filter filter)
          Returns the feature collection for the features which match the specified filter.
 ContentFeatureCollection getFeatures(Query query)
          Returns the feature collection if the features of the feature source which meet the specified query criteria.
 ResourceInfo getInfo()
          A default ResourceInfo with a generic description.
 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
 QueryCapabilities getQueryCapabilities()
          SimpleFeatureCollection optimized for read-only access.
 FeatureReader<SimpleFeatureType,SimpleFeature> getReader()
          Returns a feature reader for all features.
 FeatureReader<SimpleFeatureType,SimpleFeature> getReader(Filter filter)
          Returns a reader for features specified by a particular filter.
 FeatureReader<SimpleFeatureType,SimpleFeature> getReader(Query query)
          Returns a reader for the features specified by a query.
protected abstract  FeatureReader<SimpleFeatureType,SimpleFeature> getReaderInternal(Query query)
          Subclass method for returning a native reader from the datastore.
 SimpleFeatureType getSchema()
          Returns the feature type or the schema of the feature source.
 ContentState getState()
          The current state for the feature source.
 Set getSupportedHints()
          The hints provided by the feature store.
 Transaction getTransaction()
          The current transaction the feature source is working against.
 ContentFeatureSource getView(Filter filter)
           
 ContentFeatureSource getView(Query query)
          Creates a new feature source for the specified query.
protected  boolean handleVisitor(Query query, FeatureVisitor visitor)
          Subclass method which allows subclasses to natively handle a visitor.
 boolean isView()
          Indicates if this feature source is actually a view.
protected  Query joinQuery(Query query)
          Convenience method for joining a query with the definining query of the feature source.
 int lockFeatures()
          Locks all features.
 int lockFeatures(Filter filter)
          Locks features specified by a filter.
 int lockFeatures(Query query)
          Locks features specified by a query.
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.
 void removeFeatureListener(FeatureListener listener)
          Removes a listener from the feature source.
protected  Filter resolvePropertyNames(Filter filter)
          Transform provided filter; resolving property names
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.
 void setFeatureLock(FeatureLock lock)
          Sets the feature lock of the feature store.
 void setTransaction(Transaction transaction)
          Sets the current transaction the feature source is working against.
 void unLockFeatures()
          Unlocks all features.
 void unLockFeatures(Filter filter)
          Unlocks features specified by a filter.
 void unLockFeatures(Query query)
          Unlocks features specified by a query.
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

entry

protected ContentEntry entry
The entry for the feature source.


transaction

protected Transaction transaction
The transaction to work from


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 Detail

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 Detail

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.

See Also:
#getState()}.

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.

See Also:
#setTransaction(Transaction)}.

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:
FeatureSource.getName()

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.

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 getCount(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.

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:
Query

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:

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.

See Also:
ReprojectFeatureReader

canLimit

protected boolean canLimit()
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:
MaxFeatureReader

canOffset

protected boolean canOffset()
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 be accesset offset times before being returned to the caller.


canFilter

protected boolean canFilter()
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

protected boolean canRetype()
Determines if the datasatore 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:
ReTypeFeatureReader

canSort

protected boolean canSort()
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:
SortedFeatureReader

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.

Parameters:
query -
Returns:
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:
Filter

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 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:
FeatureSource.getSupportedHints()

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.

Returns:
Throws:
IOException

getQueryCapabilities

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

Available via getView( filter ):

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>
Parameters:
transactionState -
filter -
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


Copyright © 1996-2014 Geotools. All Rights Reserved.