org.geotools.data
Interface TransactionalDataSource

All Superinterfaces:

DataSource

All Known Implementing Classes:

PostgisDataSource

public interface TransactionalDataSource

extends DataSource

Extends geotools2 DataSource to account for transaction support.

The goal of this class is to support "strong transactions", that is expose a locking mechanism that can be backed by a Database. The reference use of this DataSource extension is GeoServer. This project can be seen as GeoServer giving back some useful code to geotools2 for general reuse.

The Plan for this refactoring is:

• Construct this TransactionDataSource and AbstractTransactionalDataSource
• Implment PostgisTransactionalDataSource:
  using:
  • SELECT FOR UPDATE: for per transaction locking
  • Use of 'Lock Tables' for long transaction support
• Modify GeoServer Locking code to make use of TransactionDataSource locking abilities
• Port GeoServer Locking Code into a AbstractTransactionDataSource with tests against GeoServer codebase to maintain functionality
• Approach group about moving existing DataSource update operations to TransactionalDataSource and renaming the result DataStore. This would remove a lot of the need for the DataSourceMetaData class.

Example use of per transaction locking:

 HashMap params = new HashMap();
 
 params.put("dbtype", "postgis");
 params.put("host","feathers.leeds.ac.uk");
 params.put("port", "5432");
 params.put("database","postgis_test");
 params.put("user","postgis_ro");
 params.put("passwd","postgis_ro");
 params.put("table","testset");
 
 DataSource ds = DataSourceFinder.getDataSource( params );
 TransactionalDataSource tds = null;
 if ( ds instanceof TransactionalDataSource ){
    tds = (TransactionalDataSource) ds;
    tds.setCurrentLock( null );
 }
 ds.setAutoCommit( false ); // start transaction
 if (tds != null){
   lock = tds.lockFeatures( Filter );
 )
 ds.removeFeatures( fc );
 ds.commit();
 

Aquire Lock for Long Transaction:

 public Lock lockSomething( Filter filter){
   TransactionalDataSource tds =
       (TransactionalDataSource) DataSourceFinder.getDataSource( params );
  
   Lock lock = Lock.create( 30*60 );
   tds.setCurrentLock( lock );
   tds.lockFeatures( Filter );
   tds.commit();
   return Lock;
 }
 

Using previously aquired Lock:

 public Lock deleteSomething( String lockId, Filter filter){
   TransactionalDataSource tds =
      (TransactionalDataSource) DataSourceFinder.getDataSource( params );
   tds.setAuthorization( new String[]{ lockId,} );
   tds.removeFeatures( filter );
   tds.commit();
 }
 

Version:

CVS Version

Author:

Refractions Reasearch Inc., jgarnett

See Also:

org.geotools.data

Method Summary

void	lockFeatures() Lock all Features.
void	lockFeatures(Filter filter) Lock features described by Filter.
void	lockFeatures(Query query) Lock features described by Query.
void	setAuthorization(java.lang.String[] locksIds) Provides a set of Lock ids this Transaction can use for authorization.
void	setCurrentLock(Lock lock) All locking operations will operate against the provided Lock.
void	unLockFeatures() Unlocks all Features.
void	unLockFeatures(Filter filter) Unlock Features denoted by provided filter.
void	unLockFeatures(Query query) Unlock Features denoted by provided query.

Methods inherited from interface org.geotools.data.DataSource

abortLoading, addFeatures, commit, getAutoCommit, getBounds, getFeatures, getFeatures, getFeatures, getFeatures, getFeatures, getMetaData, getSchema, modifyFeatures, modifyFeatures, removeFeatures, rollback, setAutoCommit, setFeatures

Method Detail

setCurrentLock

public void setCurrentLock(Lock lock)

All locking operations will operate against the provided Lock.

This in in keeping with the stateful spirit of DataSource in which operations are against the "current" transaction. If a Lock is not provided lock operations will only be applicable for the current transaction (they will expire on the next commit or rollback).

That is lock() and getFeaturesWithLock() operations will:

• Be recorded against the provided Lock.
• Be recorded against the current transaction if no Lock is provided.

Calling this method with setCurrentLock( null ), will revert to per transaction operation.

This design allows for the following:

• cross DataSource Lock useage
• not having pass in the same Lock object multiple times

lockFeatures

public void lockFeatures(Query query)
                  throws DataSourceException

Lock features described by Query.

This is an All or nothing operartion - to implement parcial Locking retrieve the features with a query operation first before trying to lock them individually.

Parameters:

query - Query describing the features to lock

Throws:

DataSourceException - Thrown if anything goes wrong

lockFeatures

public void lockFeatures(Filter filter)
                  throws DataSourceException

Lock features described by Filter.

This is an All or nothing operartion - to implement parcial Locking retrieve the features with a Filter operation first before trying to lock them individually.

Parameters:

filter - Filter describing the features to lock

Throws:

DataSourceException - Thrown if anything goes wrong

lockFeatures

public void lockFeatures()
                  throws DataSourceException

Lock all Features.

The method does not prevent addFeatures() from being used (we could add a lockDataSource() method if this functionality is required.

Throws:

DataSourceException

setAuthorization

public void setAuthorization(java.lang.String[] locksIds)

Provides a set of Lock ids this Transaction can use for authorization.

All proceeding modifyFeatures and removeFeature operations will make use of the provided authorization.

That is operations will only succeed if affected features are:

• unlocked
• locked with one of the provided lockids

LockIds are provided as a String, rather than Lock objects, to account for across process lock use.

Parameters:

locksIds - LockIds for Long Transaction operations

unLockFeatures

public void unLockFeatures()
                    throws DataSourceException

Unlocks all Features.

Authorization must be provided prior before calling this method.

 void releaseLock( String lockId, TransactionDataSource tds ){
    tds.setAuthorization( new String[]{"LOCK1234","LOCK534"} );
    tds.unLockFeatures(); 
 }
 

Throws:

DataSourceException

unLockFeatures

public void unLockFeatures(Filter filter)
                    throws DataSourceException

Unlock Features denoted by provided filter.

Authorization must be provided prior before calling this method.

Parameters:

filter -

Throws:

DataSourceException

unLockFeatures

public void unLockFeatures(Query query)
                    throws DataSourceException

Unlock Features denoted by provided query.

Authorization must be provided prior before calling this method.

Parameters:

query - Specifies fatures to unlock

Throws:

DataSourceException