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

Shapefiles, databases, etc. are safely modified with the assistance of this interface. Transactions are also to provide authorization when working with locked features.

All operations are considered to be working against a Transaction. Transaction.AUTO_COMMIT is used to represent an immidiate mode where requests are immidately commited.

For more information please see DataStore and FeatureStore.

Example Use:

 Transaction t = new DefaultTransaction("handle");
 t.putProperty( "hint", new Integer(7) );
 try {
 FeatureStore road = (FeatureStore) store.getFeatureSource("road");
 FeatureStore river = (FeatureStore) store.getFeatureSource("river");
 road.setTransaction( t );
 river.setTransaction( t );
 t.addAuthorization( lockID );  // provide authoriztion
 road.removeFeatures( filter ); // operate against transaction
 river.removeFeature( filter ); // operate against transaction
 t.commit(); // commit operations
 }
 catch (IOException io){
 t.rollback(); // cancel operations
 }
 finally {
 t.close(); // free resources
 }
 

Example code walkthrough (from the perspective of Transaction):

1. A new transaction is created (an instanceof DefaultTransaction with a handle)
2. A hint is provided using Transaction.putProperty( key, value )
3. Transaction is provided to two FeatureStores, this may result in Transaction.State instances being registered
• TransactionStateDiff (stored by DataStore): Used for in memory locking is used by many DataStore's (like ShapefileDataStore). Lazy creation by AbstractDataStore.state(transaction).
• JDBCTransactionState (stored by ConnectionPool): Used to manage connection rollback/commit. Lazy creation as part of JDBCDataStore.getConnection(transaction).
• InProcessLockingManager.FeatureLock (stored by LockingManger): Used for per transaction FeatureLocks, used to free locked features on Transaction commit/rollback.
These instances of Transaction state may make use of any hint provided to Transaction.putProperty( key, value ) when they are connected with Transaction.State.setTransaction( transaction ).
4. t.addAuthorization(lockID) is called, each Transaction.State has its addAuthroization(String) callback invoked with the value of lockID
5. FeatureStore.removeFeatures methods are called on the two DataStores.
   • PostgisFeatureStore.removeFeatures(fitler) handles operation without delegation.
   • Most removeFeature(filter) implementations use the implementation provided by AbstractFeatureStore which delegates to FeatureWriter.
   Any of these operations may make use of the Transaction.putProperty( key, value ).
6. The transaction is commited, all of the Transaction.State methods have there Transaction.State.commit() methods called gicing them a chance to applyDiff maps, or commit various connections.
7. The transaction is closed, all of the Transaction.State methods have there Transaction.State.setTransaction( null ) called, giving them a chance to clean up diffMaps, or return connections to the pool.

FeatureSources will need to issue any changes notifications using a FeatureEvent.FEATURES_CHANGED to all FeatureSources with the same typeName and a different Transaction.

FeatureSources will need to issue any changes notifications using a FeatureEvent.FEATURES_CHANGED.

All proceeding modifyFeatures,removeFeature, unLockFeatures, refreshLock and ReleaseLock operations will make use of the provided authorization.

Authorization is only maintained until the this Transaction is commited or rolledback.

That is operations will only succeed if affected features either:

• not locked
• locked with the provided authID

Authorization ID is provided as a String, rather than a FeatureLock, to account for across process lock use.

This method should call State.setTransaction( null ) on all State it maintains.

It is hoped that FeatureStore implementations that have externalized their State with the transaction take the opportunity to revert to Transction.AUTO_COMMIT.

FeatureSources will need to issue any changes notifications using a FeatureEvent.FEATURES_CHANGED to all FeatureSources with the same typeName and a different Transaction. FeatureSources with the same Transaction will of been notified of changes as the FeaureWriter made them.

This list is reset by the next call to commit() or rollback().

Authorization IDs are used to provide FeatureLock support.

This may be used to provide hints to DataStore implementations, it operates as a blackboard for client, FeatureSource communication.

If this proves successful addAuthorization/getAuthorization will be replaced with this mechanism.

The most common example is a JDBC DataStore saving the required connection for later operations.

All proceeding FeatureSource (for FeatureReader/Writer) operations may make use of the provided property.

The most common example is a JDBC DataStore saving the required connection for later operations.

 ConnectionState implements State {
 public Connection conn;
 public addAuthorization() {}
 public commit(){ conn.commit(); }
 public rollback(){ conn.rollback(); }
 }
 

putState will call State.setTransaction( transaction ) to allow State a chance to configure itself.

Care should be taken when using shared State to not remove State required by another FeatureSources.

removeState will call State.setTransaction( null ) to allow State a chance cleanup after itself.

FeatureSources will need to issue any changes notifications using a FeatureEvent.FEATURES_CHANGED. This will need to be issued to all FeatureSources with the same typeName and Transaction.