org.geotools.data
Class AbstractDataStore

Object
  AbstractDataStore

All Implemented Interfaces:

DataStore

Direct Known Subclasses:

AbstractFileDataStore, ArcSDEDataStore, CollectionDataStore, FileGMLDataStore, GMLDataStore, MemoryDataStore, VPFFileStore, VPFLibrary, WFSDataStore

public abstract class AbstractDataStore
extends Object
implements DataStore

Represents a stating point for implementing your own DataStore.

The goal is to have this class provide everything else if you can only provide:

• String[] getFeatureTypes()
• FeatureType getSchema(String typeName)
• FeatureReader getFeatureReader( typeName )
• FeatureWriter getFeatureWriter( typeName )

and optionally this protected methods to allow custom query optimizations:

• Filter getUnsupportedFilter(String typeName, Filter filter)
• FeatureReader getFeatureReader(String typeName, Query query)

All remaining functionality is implemented against these methods, including Transaction and Locking Support. These implementations will not be optimal but they will work.

Pleae note that there may be a better place for you to start out from, (like JDBCDataStore).

Author:

jgarnett

Module:

modules/library/main (gt2-main.jar) (Maven report) (SVN head)

Field Summary

protected boolean	isWriteable Flags AbstractDataStore to allow Modification.
FeatureListenerManager	listenerManager Manages listener lists for FeatureSource implementation
protected static Logger	LOGGER The logger for the filter module.

Constructor Summary

AbstractDataStore()
Default (Writeable) DataStore

AbstractDataStore(boolean isWriteable)
AbstractDataStore creation.

Method Summary

protected FeatureWriter	createFeatureWriter(String typeName, Transaction transaction) Subclass should implement this to provide writing support.
protected InProcessLockingManager	createLockingManager() Currently returns an InProcessLockingManager.
protected Map	createMetadata(String typeName) Subclass override to provide access to metadata.
void	createSchema(FeatureType featureType) Subclass should implement to provide writing support.
void	dispose() Dummy implementation, it's a no-op.
protected Envelope	getBounds(Query query) Computes the bounds of the features for the specified feature type that satisfy the query provided that there is a fast way to get that result.
protected int	getCount(Query query) Gets the number of the features that would be returned by this query for the specified feature type.
FeatureReader	getFeatureReader(Query query, Transaction transaction) Access a FeatureReader providing access to Feature information.
protected abstract FeatureReader	getFeatureReader(String typeName) Subclass must implement.
protected FeatureReader	getFeatureReader(String typeName, Query query) GR: this method is called from inside getFeatureReader(Query ,Transaction ) to allow subclasses return an optimized FeatureReader wich supports the filter and attributes truncation specified in query A subclass that supports the creation of such an optimized FeatureReader shold override this method.
FeatureSource	getFeatureSource(String typeName) Default implementation based on getFeatureReader and getFeatureWriter.
protected FeatureWriter	getFeatureWriter(String typeName) Deprecated.
FeatureWriter	getFeatureWriter(String typeName, Filter filter, Transaction transaction) Access FeatureWriter for modification of existing DataStore contents.
FeatureWriter	getFeatureWriter(String typeName, Transaction transaction) Access FeatureWriter for modification of the DataStore typeName.
FeatureWriter	getFeatureWriterAppend(String typeName, Transaction transaction) Aquire a FeatureWriter for adding new content to a FeatureType.
LockingManager	getLockingManager() Locking manager used for this DataStore.
abstract FeatureType	getSchema(String typeName) Retrive schema information for typeName
protected Set	getSupportedHints() If you are using the automated FeatureSource/Store/Locking creation, this method allows for the specification of the supported hints.
abstract String[]	getTypeNames() Convience method for retriving all the names from the Catalog Entires
protected Filter	getUnsupportedFilter(String typeName, Filter filter) GR: if a subclass supports filtering, it should override this method to return the unsupported part of the passed filter, so a FilteringFeatureReader will be constructed upon it.
FeatureSource	getView(Query query) Access a FeatureSource for Query providing a high-level API.
void	updateSchema(String typeName, FeatureType featureType) Used to force namespace and CS info into a persistent change.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOGGER

protected static final Logger LOGGER

The logger for the filter module.

listenerManager

public FeatureListenerManager listenerManager

Manages listener lists for FeatureSource implementation

isWriteable

protected final boolean isWriteable

Flags AbstractDataStore to allow Modification.

GetFeatureSource will return a FeatureStore is this is true.

Constructor Detail

AbstractDataStore

public AbstractDataStore()

Default (Writeable) DataStore

AbstractDataStore

public AbstractDataStore(boolean isWriteable)

AbstractDataStore creation.

Parameters:

isWriteable - true for writeable DataStore.

Method Detail

createLockingManager

protected InProcessLockingManager createLockingManager()

Currently returns an InProcessLockingManager.

Subclasses that implement real locking may override this method to return null.

Returns:

InProcessLockingManager or null.

createMetadata

protected Map createMetadata(String typeName)

Subclass override to provide access to metadata.

CreateTypeEntry uses this method to aquire metadata information, if available.

getTypeNames

public abstract String[] getTypeNames()
                               throws IOException

Convience method for retriving all the names from the Catalog Entires

Specified by:

getTypeNames in interface DataStore

Returns:

typeNames for available FeatureTypes.

Throws:

IOException

getSchema

public abstract FeatureType getSchema(String typeName)
                               throws IOException

Retrive schema information for typeName

Specified by:

getSchema in interface DataStore

Parameters:

typeName - typeName of requested FeatureType

Returns:

FeatureType for the provided typeName

Throws:

IOException - If typeName cannot be found

getFeatureReader

protected abstract FeatureReader getFeatureReader(String typeName)
                                           throws IOException

Subclass must implement.

Parameters:

typeName -

Returns:

FeatureReader over contents of typeName

Throws:

IOException

getFeatureWriter

protected FeatureWriter getFeatureWriter(String typeName)
                                  throws IOException

Deprecated.

Subclass can implement this to provide writing support.

Parameters:

typeName -

Returns:

FeatureWriter over contents of typeName

Throws:

IOException

IOException - Subclass may throw IOException

UnsupportedOperationException - Subclass may implement

createFeatureWriter

protected FeatureWriter createFeatureWriter(String typeName,
                                            Transaction transaction)
                                     throws IOException

Subclass should implement this to provide writing support.

A feature writer writes to the resource so it should considered to always be committing. The transaction is passed in so that it can be known what FeatureListeners should be notified of the changes. If the Transaction is AUTOCOMMIT then all listeners should be notified. If not all listeners that are NOT registered with that transaction should be notified.

Parameters:

typeName -

transaction - a feature writer

Returns:

FeatureWriter over contents of typeName

Throws:

IOException

IOException - Subclass may throw IOException

UnsupportedOperationException - Subclass may implement

createSchema

public void createSchema(FeatureType featureType)
                  throws IOException

Subclass should implement to provide writing support.

Specified by:

createSchema in interface DataStore

Parameters:

featureType - Requested FeatureType

Throws:

IOException

IOException - Subclass may throw IOException

UnsupportedOperationException - Subclass may implement

updateSchema

public void updateSchema(String typeName,
                         FeatureType featureType)

Description copied from interface: DataStore

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

Specified by:

updateSchema in interface DataStore

getView

public FeatureSource getView(Query query)
                      throws IOException,
                             SchemaException

Description copied from interface: DataStore

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

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

Specified by:

getView in interface DataStore

Parameters:

query - Query.getTypeName() locates FeatureType being viewed

Returns:

FeatureSource providing operations for featureType

Throws:

IOException - If FeatureSource is not available

SchemaException - If fetureType is not covered by existing schema

getFeatureSource

public FeatureSource getFeatureSource(String typeName)
                               throws IOException

Default implementation based on getFeatureReader and getFeatureWriter.

We should be able to optimize this to only get the RowSet once

Specified by:

getFeatureSource in interface DataStore

Returns:

FeatureSource (or subclass) providing operations for typeName

Throws:

IOException

See Also:

DataStore.getFeatureSource(java.lang.String)

getFeatureReader

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

Description copied from interface: DataStore

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

Specified by:

getFeatureReader in interface DataStore

Parameters:

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

transaction - Transaction this query operates against

Returns:

FeatureReader Allows Sequential Processing of featureType

Throws:

IOException

getFeatureReader

protected FeatureReader getFeatureReader(String typeName,
                                         Query query)
                                  throws IOException

GR: this method is called from inside getFeatureReader(Query ,Transaction ) to allow subclasses return an optimized FeatureReader wich supports the filter and attributes truncation specified in query

A subclass that supports the creation of such an optimized FeatureReader shold override this method. Otherwise, it just returns getFeatureReader(typeName)

Throws:

IOException

getUnsupportedFilter

protected Filter getUnsupportedFilter(String typeName,
                                      Filter filter)

GR: if a subclass supports filtering, it should override this method to return the unsupported part of the passed filter, so a FilteringFeatureReader will be constructed upon it. Otherwise it will just return the same filter.

If the complete filter is supported, the subclass must return Filter.INCLUDE

getFeatureWriter

public FeatureWriter getFeatureWriter(String typeName,
                                      Filter filter,
                                      Transaction transaction)
                               throws IOException

Description copied from interface: DataStore

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

Specified by:

getFeatureWriter in interface DataStore

Parameters:

typeName - Indicates featureType to be modified

filter - constraints used to limit the modification

transaction - Transaction this query operates against

Returns:

FeatureWriter Allows Sequential Modification of featureType

Throws:

IOException

getFeatureWriter

public FeatureWriter getFeatureWriter(String typeName,
                                      Transaction transaction)
                               throws IOException

Description copied from interface: DataStore

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.

Specified by:

getFeatureWriter in interface DataStore

Parameters:

typeName - Indicates featureType to be modified

transaction - Transaction to operates against

Returns:

FeatureReader Allows Sequential Processing of featureType

Throws:

IOException

getFeatureWriterAppend

public FeatureWriter getFeatureWriterAppend(String typeName,
                                            Transaction transaction)
                                     throws IOException

Description copied from interface: DataStore

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.

Specified by:

getFeatureWriterAppend in interface DataStore

Parameters:

typeName - Indicates featureType to be modified

transaction - Transaction to operates against

Returns:

FeatureWriter that may only be used to append new content

Throws:

IOException

getLockingManager

public LockingManager getLockingManager()

Locking manager used for this DataStore.

By default AbstractDataStore makes use of InProcessLockingManager.

Specified by:

getLockingManager in interface DataStore

Returns:

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

See Also:

DataStore.getLockingManager()

getBounds

protected Envelope getBounds(Query query)
                      throws IOException

Computes the bounds of the features for the specified feature type that satisfy the query provided that there is a fast way to get that result.

Will return null if there is not fast way to compute the bounds. Since it's based on some kind of header/cached information, it's not guaranteed to be real bound of the features

Parameters:

query -

Returns:

the bounds, or null if too expensive

Throws:

SchemaNotFoundException

IOException

getCount

protected int getCount(Query query)
                throws IOException

Gets the number of the features that would be returned by this query for the specified feature type.

If getBounds(Query) returns -1 due to expense consider using getFeatures(Query).getCount() as a an alternative.

Parameters:

query - Contains the Filter and MaxFeatures to find the bounds 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

IOException - if there are errors getting the count

getSupportedHints

protected Set getSupportedHints()

If you are using the automated FeatureSource/Store/Locking creation, this method allows for the specification of the supported hints.

Returns:

dispose

public void dispose()

Dummy implementation, it's a no-op. Subclasses holding to system resources must override this method and release them.

Specified by:

dispose in interface DataStore