org.geotools.data
Class AbstractDataStore

java.lang.Object
  extended byorg.geotools.data.AbstractDataStore
All Implemented Interfaces:
DataStore
Direct Known Subclasses:
AbstractFileDataStore, CollectionDataStore, GMLDataStore, MemoryDataStore, MIFDataStore, PickleDataStore, PropertyDataStore, TigerDataStore, VPFFileStore, VPFLibrary, WFSDataStore

public abstract class AbstractDataStore
extends java.lang.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:

and optionally this protected methods to allow custom query optimizations:

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

Field Summary
protected  boolean isWriteable
          Flags AbstractDataStore to allow Modification.
 FeatureListenerManager listenerManager
          Manages listener lists for FeatureSource implementation
protected static java.util.logging.Logger LOGGER
          The logger for the filter module.
 
Constructor Summary
AbstractDataStore()
          Default (Writeable) DataStore
AbstractDataStore(boolean isWriteable)
          AbstractDataStore creation.
 
Method Summary
protected  FeatureWriter createFeatureWriter(java.lang.String typeName, Transaction transaction)
          Subclass should implement this to provide writing support.
protected  InProcessLockingManager createLockingManager()
          Currently returns an InProcessLockingManager.
protected  java.util.Map createMetadata(java.lang.String typeName)
          Subclass override to provide access to metadata.
 void createSchema(FeatureType featureType)
          Subclass should implement to provide writing support.
protected  com.vividsolutions.jts.geom.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(java.lang.String typeName)
          Subclass must implement.
protected  FeatureReader getFeatureReader(java.lang.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(java.lang.String typeName)
          Default implementation based on getFeatureReader and getFeatureWriter.
protected  FeatureWriter getFeatureWriter(java.lang.String typeName)
          Deprecated.  
 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()
          Locking manager used for this DataStore.
abstract  FeatureType getSchema(java.lang.String typeName)
          Retrive schema information for typeName
abstract  java.lang.String[] getTypeNames()
          Convience method for retriving all the names from the Catalog Entires
protected  Filter getUnsupportedFilter(java.lang.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(java.lang.String typeName, FeatureType featureType)
          Used to force namespace and CS info into a persistent change.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LOGGER

protected static final java.util.logging.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 java.util.Map createMetadata(java.lang.String typeName)
Subclass override to provide access to metadata.

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


getTypeNames

public abstract java.lang.String[] getTypeNames()
                                         throws java.io.IOException
Convience method for retriving all the names from the Catalog Entires

Specified by:
getTypeNames in interface DataStore
Returns:
typeNames for available FeatureTypes.
Throws:
java.io.IOException

getSchema

public abstract FeatureType getSchema(java.lang.String typeName)
                               throws java.io.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:
java.io.IOException - If typeName cannot be found

getFeatureReader

protected abstract FeatureReader getFeatureReader(java.lang.String typeName)
                                           throws java.io.IOException
Subclass must implement.

Parameters:
typeName -
Returns:
FeatureReader over contents of typeName
Throws:
java.io.IOException

getFeatureWriter

protected FeatureWriter getFeatureWriter(java.lang.String typeName)
                                  throws java.io.IOException
Deprecated.  

Subclass can implement this to provide writing support.

Parameters:
typeName -
Returns:
FeatureWriter over contents of typeName
Throws:
java.io.IOException
java.io.IOException - Subclass may throw IOException
java.lang.UnsupportedOperationException - Subclass may implement

createFeatureWriter

protected FeatureWriter createFeatureWriter(java.lang.String typeName,
                                            Transaction transaction)
                                     throws java.io.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:
java.io.IOException
java.io.IOException - Subclass may throw IOException
java.lang.UnsupportedOperationException - Subclass may implement

createSchema

public void createSchema(FeatureType featureType)
                  throws java.io.IOException
Subclass should implement to provide writing support.

Specified by:
createSchema in interface DataStore
Parameters:
featureType - Requested FeatureType
Throws:
java.io.IOException
java.io.IOException - Subclass may throw IOException
java.lang.UnsupportedOperationException - Subclass may implement

updateSchema

public void updateSchema(java.lang.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:

Specified by:
updateSchema in interface DataStore
Parameters:
typeName -

getView

public FeatureSource getView(Query query)
                      throws java.io.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.ALL.

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
Returns:
FeatureSource providing opperations for featureType
Throws:
SchemaException - If fetureType is not covered by existing schema
java.io.IOException - If FeatureSource is not available

getFeatureSource

public FeatureSource getFeatureSource(java.lang.String typeName)
                               throws java.io.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
Parameters:
typeName -
Returns:
FeatureSource (or subclass) providing opperations for typeName
Throws:
java.io.IOException
See Also:
DataStore.getFeatureSource(java.lang.String)

getFeatureReader

public FeatureReader getFeatureReader(Query query,
                                      Transaction transaction)
                               throws java.io.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

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

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.

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 opperates against
Returns:
FeatureReader Allows Sequential Processing of featureType
Throws:
java.io.IOException

getFeatureReader

protected FeatureReader getFeatureReader(java.lang.String typeName,
                                         Query query)
                                  throws java.io.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:
java.io.IOException

getUnsupportedFilter

protected Filter getUnsupportedFilter(java.lang.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.NONE


getFeatureWriter

public FeatureWriter getFeatureWriter(java.lang.String typeName,
                                      Filter filter,
                                      Transaction transaction)
                               throws java.io.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.ALL 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 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
    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 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
    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 opperates against
    Returns:
    FeatureWriter that may only be used to append new content
    Throws:
    java.io.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:
    See Also:
    DataStore.getLockingManager()

    getBounds

    protected com.vividsolutions.jts.geom.Envelope getBounds(Query query)
                                                      throws java.io.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
    java.io.IOException

    getCount

    protected int getCount(Query query)
                    throws java.io.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:
    java.io.IOException
    java.io.IOException - if there are errors getting the count


    Copyright © GeoTools. All Rights Reserved.