Java Doc for DataStore.java in  » GIS » GeoTools-2.4.1 » org » geotools » data » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The source of data for FeatureTypes. Shapefiles, databases tables, etc. are referenced through this interface.

Summary of our requirements:

• Provides lookup of available Feature Types
• Provides access to low-level Readers/Writers API for a feature type
• Provides access to high-level FeatureSource/Store/Locking API a feature type
• Handles the conversion of filters into data source specific queries
• Handles creation of new Feature Types
• Provides access of Feature Type Schema information

• GeoAPI - has reduced this to api to the FeatureStore construct Jody - since we are no longer using the FeatureReader/ReaderWriter in client code this would not be a bad idea.

A DataStore cannot be used after dispose has been called, neither can any data access object it helped create, such as FeatureReader , FeatureSource or FeatureCollection .

This operation can be called more than once without side effects.

There is no thread safety assurance associated with this method.

Filter is used as a low-level indication of constraints. (Implementations may resort to using a FilteredFeatureReader, or provide their own optimizations)

FeatureType provides a template for the returned FeatureReader

• featureType.getTypeName(): used by JDBC as the table reference to query against.

To limit FeatureWriter to the FeatureTypes defined by this DataStore, typeName is used to indicate FeatureType.

It is common to return an instanceof InProcessLockingManager for DataStores that do not provide native locking.

AbstractFeatureLocking makes use of this service to provide locking support.

The provided Query does not need to completely cover the existing schema for Query.getTypeName().

The provided featureType we be accessable by the typeName provided by featureType.getTypeName().

A DataStore cannot be used after dispose has been called, neither can any data access object it helped create, such as FeatureReader , FeatureSource or FeatureCollection .

This operation can be called more than once without side effects.

There is no thread safety assurance associated with this method. For example, client code will have to make sure this method is not called while retrieving/saving data from/to the storage, or be prepared for the consequences.

Filter is used as a low-level indication of constraints. (Implementations may resort to using a FilteredFeatureReader, or provide their own optimizations)

FeatureType provides a template for the returned FeatureReader

• featureType.getTypeName(): used by JDBC as the table reference to query against. Shapefile reader may need to store a lookup to the required filename.
• featureType.getAttributeTypes(): describes the requested content. This may be a subset of the complete FeatureType defined by the DataStore.
• getType.getNamespace(): describes the requested namespace for the results (may be different then the one used internally)

Transaction to externalize DataStore state on a per Transaction basis. The most common example is a JDBC datastore saving a Connection for use across several FeatureReader requests. Similarly a Shapefile reader may wish to redirect FeatureReader requests to a alternate filename over the course of a Transaction.

Notes For Implementing DataStore

Subclasses may need to retrieve additional attributes, beyond those requested by featureType.getAttributeTypes(), in order to correctly apply the filter.
These Additional attribtues should be not be returned by FeatureReader. Subclasses may use ReTypeFeatureReader to aid in acomplishing this.

Helper classes for implementing a FeatureReader (in order):

• DefaultFeatureReader - basic support for creating a FeatureReader for an AttributeReader
• FilteringFeatureReader - filtering support
• DiffFeatureReader - In-Process Transaction Support (see TransactionStateDiff)
• ReTypeFeatureReader - Feature Type schema manipulation of namesspace and attribute type subsets
• EmptyFeatureReader - provides no content for Filter.EXCLUDE optimizations

Sample use (not optimized):

 if (filter == Filter.EXCLUDE) {
 return new EmptyFeatureReader(featureType);
 }
 String typeName = featureType.getTypeName();
 FeatureType schema = getSchema( typeName );
 FeatureReader reader = new DefaultFeatureReader( getAttributeReaders(), schema );
 if (filter != Filter.INCLUDE) {
 reader = new FilteringFeatureReader(reader, filter);
 }
 if (transaction != Transaction.AUTO_COMMIT) {
 Map diff = state(transaction).diff(typeName);
 reader = new DiffFeatureReader(reader, diff);
 }
 if (!featureType.equals(reader.getFeatureType())) {
 reader = new ReTypeFeatureReader(reader, featureType);
 }
 return reader
 

Locking support does not need to be provided for FeatureReaders.

The resulting FeatureSource may implment more functionality:

 FeatureSource fsource = dataStore.getFeatureSource( "roads" );
 FeatureStore fstore = null;
 if( fsource instanceof FeatureLocking ){
 fstore = (FeatureStore) fs;
 }
 else {
 System.out.println("We do not have write access to roads");
 }
 
 

To limit FeatureWriter to the FeatureTypes defined by this DataStore, typeName is used to indicate FeatureType. The resulting feature writer will allow modifications against the same FeatureType provided by getSchema( typeName )

The FeatureWriter will provide access to the existing contents of the FeatureType referenced by typeName. The provided filter will be used to skip over Features as required.

The returned FeatureWriter does not support the addition of new Features to FeatureType (it would need to police your modifications to agree with filer). As such it will return false for getNext() when it reaches the end of the Query and NoSuchElementException when next() is called.

Helper classes for implementing a FeatureWriter (in order):

FeatureWriters will need to be limited to the FeatureTypes defined by the DataStore, the easiest way to express this limitation is to the FeatureType by a provided typeName.

The returned FeatureWriter will return false for getNext() when it reaches the end of the Query.

This FeatureWriter will return false for hasNext(), however next() may be used to aquire new Features that may be writen out to add new content.

It is common to return an instanceof InProcessLockingManager for DataStores that do not provide native locking.

AbstractFeatureLocking makes use of this service to provide locking support. You are not limitied by this implementation and may simply return null for this value.

Retrieves the Schema information as a FeatureType object.

This is simply a list of the FeatureType names as aquiring the actual FeatureType schemas may be expensive.

Warning: this list may not be unique - the types may be in separate namespaces.

If you need to worry about such things please consider the use of the Catalog and CatalogEntry interface - many DataStores support this. getTypeNames is really a convience method for a Catalog.iterator() where the name of each entry is returned.

The provided Query does not need to completely cover the existing schema for Query.getTypeName(). The result will mostly likely only be a FeatureSource and probably wont' allow write access by the FeatureStore method.

By using Query we allow support for reprojection, in addition to overriding the CoordinateSystem used by the native FeatureType.

We may wish to limit this method to only support Queries using Filter.EXCLUDE.

Update - GeoServer has an elegatent implementation of this functionality that we could steal. GeoServerFeatureSource, GeoServerFeatureStore and GeoServerFeatureLocking serve as a working prototype.

The provided featureType should completely cover the existing schema. All attributes should be accounted for and the typeName should match.

Suggestions:

• Sean - don't do this
• Jody - Just allow changes to metadata: CS, namespace, and others
• James - Allow change/addition of attribtues