org.geotools.data
Interface DataStore

All Known Implementing Classes:

AbstractDataStore, AbstractDataStore2, DirectoryDataStore, HsqlDataStore, JDBC1DataStore, PostgisDataStore

public interface DataStore

Represents a Physical Store for FeatureTypes.

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

Suggestions:

• Aadrea - Support for a reprojection based FeautreSource. Needs to be added to DataStore (rather than a wrapper based) to allow for DataStores
  Jody - You can see it as part of Query now.
  OGC - apparenty they agree as well - it is part of WFS 1.1.
• 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.

Version:

$Id: DataStore.java 17702 2006-01-23 00:08:55Z desruisseaux $

Author:

Jody Garnett, Refractions Research

Method Summary

void	createSchema(FeatureType featureType) Creates storage for a new featureType.
FeatureReader	getFeatureReader(Query query, Transaction transaction) Access a FeatureReader providing access to Feature information.
FeatureSource	getFeatureSource(java.lang.String typeName) Access a FeatureSource for typeName providing a high-level API.
FeatureWriter	getFeatureWriter(java.lang.String typeName, Filter filter, Transaction transaction) Access FeatureWriter for modification of existing DataStore contents.
FeatureWriter	getFeatureWriter(java.lang.String typeName, Transaction transaction) Access FeatureWriter for modification of the DataStore typeName.
FeatureWriter	getFeatureWriterAppend(java.lang.String typeName, Transaction transaction) Aquire a FeatureWriter for adding new content to a FeatureType.
LockingManager	getLockingManager() Retrieve a per featureID based locking service from this DataStore.
FeatureType	getSchema(java.lang.String typeName) Retrieve FeatureType metadata by typeName.
java.lang.String[]	getTypeNames() Retrieves a list of of the available FeatureTypes.
FeatureSource	getView(Query query) Access a FeatureSource for Query providing a high-level API.
void	updateSchema(java.lang.String typeName, FeatureType featureType) Used to force namespace and CS info into a persistent change.

Method Detail

createSchema

public void createSchema(FeatureType featureType)
                  throws java.io.IOException

Creates storage for a new featureType.

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

Parameters:

featureType - FetureType to add to DataStore

Throws:

java.io.IOException - If featureType cannot be created

updateSchema

public void updateSchema(java.lang.String typeName,
                         FeatureType featureType)
                  throws java.io.IOException

Used to force namespace and CS info into a persistent change.

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

Parameters:

typeName -

Throws:

java.io.IOException

getTypeNames

public java.lang.String[] getTypeNames()
                                throws java.io.IOException

Retrieves a list of of the available FeatureTypes.

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.

Returns:

typeNames for available FeatureTypes.

Throws:

java.io.IOException

getSchema

public FeatureType getSchema(java.lang.String typeName)
                      throws java.io.IOException

Retrieve FeatureType metadata by typeName.

Retrieves the Schema information as a FeatureType object.

Parameters:

typeName - typeName of requested FeatureType

Returns:

FeatureType for the provided typeName

Throws:

java.io.IOException - If typeName cannot be found

getView

public FeatureSource getView(Query query)
                      throws java.io.IOException,
                             SchemaException

Access a FeatureSource for Query providing a high-level API.

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.ALL.

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

Returns:

FeatureSource providing opperations for featureType

Throws:

java.io.IOException - If FeatureSource is not available

SchemaException - If fetureType is not covered by existing schema

getFeatureSource

public FeatureSource getFeatureSource(java.lang.String typeName)
                               throws java.io.IOException

Access a FeatureSource for typeName providing a high-level API.

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");
 }
 
 

Parameters:

typeName -

Returns:

FeatureSource (or subclass) providing opperations for typeName

Throws:

java.io.IOException

getFeatureReader

public FeatureReader getFeatureReader(Query query,
                                      Transaction transaction)
                               throws java.io.IOException

Access a FeatureReader providing access to Feature information.

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.ALL optimizations

Sample use (not optimized):

 if (filter == Filter.ALL) {
      return new EmptyFeatureReader(featureType);
  }

  String typeName = featureType.getTypeName();
  FeatureType schema = getSchema( typeName );
  FeatureReader reader = new DefaultFeatureReader( getAttributeReaders(), schema );

  if (filter != Filter.NONE) {
      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.

Parameters:

query - Requested form of the returned Features and the filter used to constraints the results

transaction - Transaction this query opperates against

Returns:

FeatureReader Allows Sequential Processing of featureType

Throws:

java.io.IOException

getFeatureWriter

public FeatureWriter getFeatureWriter(java.lang.String typeName,
                                      Filter filter,
                                      Transaction transaction)
                               throws java.io.IOException

Access FeatureWriter for modification of existing DataStore contents.

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.

Notes For Implementing DataStore

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

InProcessLockingManager.checkedWriter( writer ) - provides a check against locks before allowing modification

FilteringFeatureWriter - filtering support for FeatureWriter (does not allow new content)

DiffFeatureWriter - In-Process Transaction Support (see TransactionStateDiff)

EmptyFeatureWriter - provides no content for Filter.ALL optimizations

Parameters:

typeName - Indicates featureType to be modified

filter - constraints used to limit the modification

transaction - Transaction this query opperates against

Returns:

FeatureWriter Allows Sequential Modification of featureType

Throws:

java.io.IOException

getFeatureWriter

public FeatureWriter getFeatureWriter(java.lang.String typeName,
                                      Transaction transaction)
                               throws java.io.IOException

Access FeatureWriter for modification of the DataStore typeName.

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.

Parameters:

typeName - Indicates featureType to be modified

transaction - Transaction to opperates against

Returns:

FeatureReader Allows Sequential Processing of featureType

Throws:

java.io.IOException

getFeatureWriterAppend

public FeatureWriter getFeatureWriterAppend(java.lang.String typeName,
                                            Transaction transaction)
                                     throws java.io.IOException

Aquire a FeatureWriter for adding new content to a FeatureType.

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.

Parameters:

typeName - Indicates featureType to be modified

transaction - Transaction to opperates against

Returns:

FeatureWriter that may only be used to append new content

Throws:

java.io.IOException

getLockingManager

public LockingManager getLockingManager()

Retrieve a per featureID based locking service from this DataStore.

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.

Returns:

DataStores may return null, if the handling locking in another fashion.