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

This class provides a default implementation of a JDBC data store. Support for vendor specific JDBC data stores can be easily added to Geotools by subclassing this class and overriding the hooks provided.

At a minimum subclasses should implement the following methods:

• JDBC1DataStore.buildAttributeType(ResultSet) buildAttributeType(ResultSet) - This should be overriden to construct an attribute type that represents any column types not supported by the default implementation, such as geometry columns.
• JDBC1DataStore.getGeometryAttributeIO(AttributeType,QueryData)getGeometryAttributeIO(AttributeType, QueryData) - Should be overriden to provide a way to read/write geometries into the format of the database

Additionally subclasses can optionally override the following:

• Use a specific FIDMapperFactory by overriding the JDBC1DataStore.buildFIDMapperFactory(JDBCDataStoreConfig)buildFIDMapperFactory(JDBCDataStoreConfig) method, and eventually disallow user overrides by throwing an java.lang.UnsupportedOperationExceptionUnsupportedOperationException in the JDBC1DataStore.setFIDMapperFactory(FIDMapperFactory) setFidMapperFactory() method.
• JDBC1DataStore.allowTable(String) allowTable - Used to determine whether a table name should be exposed as a feature type.
• JDBC1DataStore.determineSRID(String,String) determineSRID - Used to determine the SpatialReference ID of a geometry column in a table.
• JDBC1DataStore.buildSQLQuery(String,AttributeType[],Filter,boolean)buildSQLQuery() - Sub classes can override this to build a custom SQL query.
• JDBC1DataStore.getResultSetType(boolean) getResultSetType if the standard result set type is not satisfactory/does not work with a normal FORWARD_ONLY resultset type
• JDBC1DataStore.getConcurrency(boolean) getConcurrency to set the level of concurrency for the result set used to read/write the database

Additionally subclasses may want to set the value of:

• sqlNameEscape - character (String) to surround names of SQL objects to support mixed-case and non-English names.

This works by retrieving the column information for the table from the DatabaseMetaData object.

The provided schema describes the attributes in the queryData ResultSet.

The default implementation of determining the FID column name is to use the primary key as the FID column.

This allows SRIDs to be determined in a Vendor specific way and to be cached by the default implementation.

This is private in the expectation that subclasses should not need to change this behaviour.

Jody with a question here - I have stopped this method from closing connection shared by a Transaction.

Chris- I've gone with the Query object aswell.

Subclass may wish to implement an optimized featureWriter for this operation.

Subclasses requiring a ClientTransactionAccessor should override and instantiate an SQLBuilder with one in the constructor.

Specifically this is intended to address updating the metadata Coordinate System information.

If we can figure out the Catalog API for metadata we will not have to use such a heavy handed approach.

Subclasses are free to implement various levels of support:

• None - table modification is not supported
• CS change - ensure that the attribtue types match and only update metadata but not table structure.

These mappings were taken from http://java.sun.com/j2se/1.3/docs/guide/jdbc/getstart/mapping.html#997737

The default implementation constructs an AttributeType using the default JDBC type mappings defined in JDBCDataStore. These type mappings only handle native Java classes and SQL standard column types, so to handle Geometry columns, sub classes should override this to check if a column is a geometry column, if it is a geometry column the appropriate determination of the geometry type can be performed. Otherwise, overriding methods should call super.buildAttributeType.

Note: Overriding methods must never move the current row pointer in the result set.

This works by retrieving the column information for the table from the DatabaseMetaData object. It then iterates over the information for each column, calling buildAttributeType(ResultSet) to construct an AttributeType for each column. The list of attribute types is then turned into a FeatureType that defines the schema.

It is not intended that this method is overriden. It should provide the required functionality for most sub-classes. To add AttributeType construction for vendor specific SQL types, such as geometries, override the buildAttributeType(ResultSet) method.

This may become final later. In fact Ill make it private because I don't think It will need to be overriden.

The provided schema describes the attributes in the queryData ResultSet. This schema should cover the requirements of filter.

Retyping to the users requested Schema will not happen in this method.

Not currently supported - subclass may implement.

The default implementation of determining the FID column name is to use the primary key as the FID column. If no primary key is present, null will be returned. Sub classes can override this behaviour to define primary keys for vendor specific cases.

There is an unresolved issue as to what to do when there are multiple primary keys. Maybe a restriction that table much have a single column primary key is appropriate.

This should not be called by subclasses to retreive the FID column name. Instead, subclasses should call getFeatureTypeInfo(String) to get the FeatureTypeInfo for a feature type and get the fidColumn name from the fidColumn name memeber.

This allows SRIDs to be determined in a Vendor specific way and to be cached by the default implementation. To retreive these srids, get the FeatureTypeInfo object for the table and call getSRID(geometryColumnName). This will allow storage of SRIDs for multiple geometry columns in each table.

If no SRID can be found, subclasses should return -1. The default implementation always returns -1.

This is private in the expectation that subclasses should not need to change this behaviour.

Jody with a question here - I have stopped this method from closing connection shared by a Transaction. It sill seems like we are leaving connections open by using this method. I have also stopped QueryData from doing the same thing.

Answer from Sean: Resources for successful queries are closed when close is called on the AttributeReaders constructed with the QueryData. We can't close them here since they need to be open to read from the ResultSet.

Jody AttributeReader question: I looked at the code and Attribute Readers do not close with respect to Transactions (they need to as we can issue a Reader against a Transaction. I have changed the JDBCDataStore.close method to force us to keep track of these things.

SG: I've marked this as final since I don't think it shoudl be overriden, but Im not sure

This result is suitable for a quick map display, illustrating the data. This value is often stored as metadata in databases such as oraclespatial.

We have given some though to changing this api to be based on query.

Currently the is is the only way to retype your features to different name spaces.

Chris- I've gone with the Query object aswell. It just seems to make more sense. This is pretty well split up across methods. The hooks for DB specific AttributeReaders are createResultSetReader and createGeometryReader.

JG- I have implemented getFeatureReader( FeatureType, Filter, Transasction) ontop of this method, it will Retype as required

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

Quick notes: This FeatureWriter is often used to add new content, or perform summary calculations over the entire dataset.

Subclass may wish to implement an optimized featureWriter for these operations.

It should provide Feature for next() even when hasNext() is false.

Subclasses are responsible for checking with the lockingManger unless they are providing their own locking support.

Quick notes: This FeatureWriter is often used to remove contents specified by the provided filter, or perform summary calculations.

Subclasses are responsible for checking with the lockingManager unless they are providing their own locking support.

Subclass may wish to implement an optimized featureWriter for this operation. One based on prepaired statemnts is a possibility, as we do not require a ResultSet.

To allow new content the FeatureWriter should provide Feature for next() even when hasNext() is false.

Subclasses are responsible for checking with the lockingManger unless they are providing their own locking support.

By default AbstractDataStore makes use of InProcessLockingManager.

Subclasses requiring a ClientTransactionAccessor should override and instantiate an SQLBuilder with one in the constructor.
Parameters:
  typeName - The typename for the sql builder. A new sql builder.
throws:
  IOException - if anything goes wrong.

The value of this string is prefixed and appended to table schema names, table names and column names in an SQL statement to support mixed-case and non-English names.

Method will figure out names from the schema for query.getTypeName(), if query getPropertyNames() is null, or query.retrieveAllProperties is true.

Warning: the ovveride may not be supported by all data stores, in this case an exception will be thrown

The value of this string is prefixed and appended to table schema names, table names and column names in an SQL statement to support mixed-case and non-English names.

This value is typically only set once when the DataStore implementation class is constructed.

Specifically this is intended to address updating the metadata Coordinate System information.

If we can figure out the Catalog API for metadata we will not have to use such a heavy handed approach.

Subclasses are free to implement various levels of support:

• None - table modification is not supported
• CS change - ensure that the attribtue types match and only update metadata but not table structure.
• Allow table change opperations