org.geotools.data
Interface Transaction

All Known Implementing Classes:

DefaultTransaction

public interface Transaction

The controller for Transaction with FeatureStore.

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

All opperations 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();
 try {
     FeatureStore road = (FeatureStore) store.getFeatureSource("road");
     FeatureStore river = (FeatureStore) store.getFeatureSource("river");
 
     road.setTransaction( t );
     river.setTransaction( t );
 
     t.addAuthorization( lockID );  // proivde authoriztion
     road.removeFeatures( filter ); // opperate against transaction
     river.removeFeature( filter ); // opperate against transaction
 
     t.commit(); // commit opperations
 }
 catch (IOException io){
     t.rollback(); // cancel opperations
 }
 finally {
     t.close(); // free resources
 }
 

Version:

$Id: Transaction.java,v 1.3 2003/11/16 00:56:16 jive Exp $

Author:

Jody Garnett, Chris Holmes, TOPP

Nested Class Summary

static interface

Transaction.State DataStore implementations can use this interface to externalize the state they require to implement Transaction Support.

Field Summary

static Transaction

AUTO_COMMIT Represents AUTO_COMMIT Mode

Method Summary

void	addAuthorization(java.lang.String authID) Provides an Authorization ID for this Transaction.
void	close() Provides an oppertunity for a Transaction to free an State it maintains.
void	commit() Makes all transactions made since the previous commit/rollback permanent.
java.util.Set	getAuthorizations() List of Authorizations IDs held by this transaction.
Transaction.State	getState(java.lang.Object key) Allows DataStores to squirel away information( and callbacks ) for later.
void	putState(java.lang.Object key, Transaction.State state) Allows FeatureSource to squirel away information( and callbacks ) for later.
void	removeState(java.lang.Object key) Allows FeatureSources to clean up information ( and callbacks ) they earlier provided.
void	rollback() Undoes all transactions made since the last commit or rollback.

Field Detail

AUTO_COMMIT

public static final Transaction AUTO_COMMIT

Represents AUTO_COMMIT Mode

Method Detail

getAuthorizations

public java.util.Set getAuthorizations()

List of Authorizations IDs held by this transaction.

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

Authorization IDs are used to provide FeatureLock support.

Returns:

List of Authorization IDs

putState

public void putState(java.lang.Object key,
                     Transaction.State state)

Allows FeatureSource to squirel away information( and callbacks ) for later.

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

 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.

Parameters:

key - Key used to externalize State

state - Externalized State

removeState

public void removeState(java.lang.Object key)

Allows FeatureSources to clean up information ( and callbacks ) they earlier provided.

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.

Parameters:

key - Key that was used to externalize State

getState

public Transaction.State getState(java.lang.Object key)

Allows DataStores to squirel away information( and callbacks ) for later.

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

Returns:

Current State externalized by key, or null if not found

commit

public void commit()
            throws java.io.IOException

Makes all transactions made since the previous commit/rollback permanent.

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.

Throws:

DataSourceException - if there are any datasource errors.

java.io.IOException

See Also:

#setAutoCommit(boolean)

rollback

public void rollback()
              throws java.io.IOException

Undoes all transactions made since the last commit or rollback.

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.

Throws:

DataSourceException - if there are problems with the datasource.

java.lang.UnsupportedOperationException - if the rollback method is not supported by this datasource.

java.io.IOException

See Also:

#setAutoCommit(boolean)

addAuthorization

public void addAuthorization(java.lang.String authID)
                      throws java.io.IOException

Provides an Authorization ID for this Transaction.

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.

Parameters:

authID -

Throws:

java.io.IOException

close

public void close()
           throws java.io.IOException

Provides an oppertunity for a Transaction to free an State it maintains.

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 oppertunity to revert to Transction.AUTO_COMMIT.

Throws:

java.io.IOException