org.geotools.data.store
Class ContentFeatureSource

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

public abstract class ContentFeatureSource
extends Object
implements FeatureSource<SimpleFeatureType,SimpleFeature>

Abstract implementation of FeatureSource.

This feature source works off of operations provided by FeatureCollection. Individual FeatureCollection 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
Module:
modules/library/data (gt-data.jar)

Field Summary
protected  ContentEntry entry
          The entry for the feature source.
protected  Set<Hints.Key> hints
          hints
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 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 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  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()
          FeatureCollection 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.
 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 setTransaction(Transaction transaction)
          Sets the current transaction the feature source is working against.
 
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


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:
DataStore implementing this FeatureStore

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 AttributeDescriptor for the Features served by 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 of features created by this datasource.

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 box of the datasource or null if unknown and too expensive for the method to calculate.
Throws:
IOException - if there are errors getting the bounding box.

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 - Contains the Filter, and optionally MaxFeatures and StartIndex to find the bounds for.
Returns:
The bounding box of the datasource or null if unknown and too expensive for the method to calculate or any errors occur.
Throws:
IOException - DOCUMENT ME!

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 - Contains the Filter, and optionally MaxFeatures and StartIndex to find the count for.
Returns:
The number of Features provided by the Query or -1 if count is too expensive to calculate or any errors or occur.
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>
Returns:
Collection The collection to put the features into.
Throws:
IOException - For all data source errors.

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>
Parameters:
query - a datasource query object. It encapsulates requested information, such as typeName, maxFeatures and filter.
Returns:
Collection The collection to put the features into.
Throws:
IOException - For all data source errors.
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 corresonding 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.

TODO: link to decorating feature reader


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.

TODO: link to feature decorator


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.


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>
Parameters:
filter - An OpenGIS filter; specifies which features to retrieve. null is not allowed, use Filter.INCLUDE instead.
Returns:
Collection The collection to put the features into.
Throws:
IOException - For all data source errors.

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 - FeatureListener

removeFeatureListener

public final void removeFeatureListener(FeatureListener listener)
Removes a listener from the feature source.

Specified by:
removeFeatureListener in interface FeatureSource<SimpleFeatureType,SimpleFeature>
Parameters:
listener - FeatureListener

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 (eventually empty, 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()
FeatureCollection 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>
Parameters:
state -
filter -
Returns:
readonly access


Copyright © 1996-2010 Geotools. All Rights Reserved.