org.opengis.feature

Interface Transaction

@XmlElement(value="Transaction")
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 operations are considered to be working against a transaction. The AUTO_COMMIT constant is used to represent an immediate mode where requests are immediately commited. Example use:

Transaction t = ... t.putProperty("someHint", someValue); try { FeatureCollection road = store.getFeatures("road"); FeatureCollection river = store.getFeatures("river"); road .setTransaction(t); river.setTransaction(t); // Provides authorization and operates against transaction t.useAuthorization(authorizationID); road .removeAll(road .subCollection(filter)); river.removeAll(river.subCollection(filter)); t.commit(); // Commit operations } catch (IOException exception){ t.rollback(); // Cancel operations throw exception; // Propagate the exception } finally { t.close(); // free resources }

Example code walkthrough from the perspective of transaction:

• A new transaction is created
• A hint is provided using putProperty(key, value)
• Transaction is provided to two FeatureStores. This may result in several Transaction.State instances being registered. These instances of transaction state may make use of any hint provided as properties (in previous step) when they are connected with State.setTransaction(t).
• t.useAuthorization(authorizationID) is called. Each Transaction.State has its addAuthorization callback invoked with the value of authorizationID.
• removeAll methods are called on the two FeatureCollections. Any of these opperations may make use of the hints provided as properties.
• The transaction is commited. All of the transaction state instances have there commit commit methods called.
• The transaction is closed. All of the transaction state instances have there close close methods called.

Since:

GeoAPI 2.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Transaction.State FeatureStore implementations can use this interface to externalize the state they require to implement Transaction support.

Field Summary

Fields

Modifier and Type	Field and Description
static Transaction	AUTO_COMMIT Marker constant used to indicate immidiate response.

Method Summary

Modifier and Type	Method and Description
void	close() Provides an opportunity for a transaction to free any State it maintains.
LockResponse	commit() Makes all transactions made since the previous commit/rollback permanent.
java.util.Set<java.lang.String>	getAuthorizations() Returns the set of authorizations IDs held by this transaction.
java.lang.Object	getProperty(java.lang.Object key) Retrieves a transaction property held by this transaction.
Transaction.State	getState(java.lang.Object key) Retrieve a state used to squirel away information (and callbacks) for later.
void	putProperty(java.lang.Object key, java.lang.Object value) Provides a property for this transasction.
void	putState(java.lang.Object key, Transaction.State state) Allows FeatureStore to squirel away information (and callbacks) for later.
void	removeState(java.lang.Object key) Allows FeatureStores to clean up information (and callbacks) they earlier provided.
void	rollback() Undoes all transactions made since the last commit or rollback.
void	useAuthorization(java.lang.String authorizationID) Uses an Authorization token with this transaction.

Field Detail

AUTO_COMMIT

static final Transaction AUTO_COMMIT

Marker constant used to indicate immidiate response. The constant is a pure Marker (similar in spirit to a Null Object pattern). All methods do nothing, this constant can be detected by interested parties as a request to perform actions immidiately.

Method Detail

putProperty

void putProperty(java.lang.Object key,
                 java.lang.Object value)
          throws java.io.IOException

Provides a property for this transasction. All proceeding FeatureStore operations may make use of the provided property.

Throws:

java.io.IOException - if there are problems with the feature store.

See Also:

getProperty(java.lang.Object)

getProperty

java.lang.Object getProperty(java.lang.Object key)

Retrieves a transaction property held by this transaction. This may be used to provide hints to FeatureStore implementations. It operates as a blackboard for client, FeatureStore communication.

See Also:

putProperty(java.lang.Object, java.lang.Object)

useAuthorization

void useAuthorization(java.lang.String authorizationID)
               throws java.io.IOException

Uses an Authorization token with this transaction. Any locks held against this token will be released on commit.

All FeatureCollections operations can make use of the provided authorization for the duration of this transaction. Authorization is only maintained until this transaction is commited or rolled back. That is operations that modify or delete a feature will only succeed if affected features either:

• not locked
• locked with a provided authorizationID

You may call this method several times to provide authorization token to multiple feature collections.

Parameters:

authorizationID - Authorization ID. Should of been obtained from a LockResponse.

Throws:

java.io.IOException - if there are problems with the feature store.

See Also:

getAuthorizations()

getAuthorizations

java.util.Set<java.lang.String> getAuthorizations()

Returns the set of authorizations IDs held by this transaction. This collection is reset by the next call to commit() or rollback().

See Also:

useAuthorization(java.lang.String)

putState

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

Allows FeatureStore to squirel away information (and callbacks) for later. The most common example is a JDBC FeatureStore saving the required connection for later opperations.

This method will call State.setTransaction(this) to allow State a chance to configure itself.

Parameters:

key - Key used to externalize State

state - Externalized State

See Also:

removeState(java.lang.Object), getState(java.lang.Object)

removeState

void removeState(java.lang.Object key)

Allows FeatureStores to clean up information (and callbacks) they earlier provided. Care should be taken when using shared State to not remove State required by another feature sources.

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

Parameters:

key - Key that was used to externalize State

getState

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

Retrieve a state used to squirel away information (and callbacks) for later. The most common example is a JDBC FeatureStore saving the required connection for later opperations.

Parameters:

key - Key that was used to externalize State

Returns:

Current State externalized by key, or null if not found

commit

LockResponse commit()
             throws java.io.IOException

Makes all transactions made since the previous commit/rollback permanent. FeatureStores will need to issue any changes notifications using a FeatureEvent to all FeatureStores with the same type name and a different transaction. FeatureStores with the same transaction will been notified of changes as the feature writer made them.

Workflows:

• LockRequest + Transaction returns a LockResponse as the result of any and all lock requests made during the transaction.
• Transaction returns LockResponse.NONE when no lock requests are made.

For a discussion of these workflows please read the package javadocs.

Returns:

The lock response, or LockResponse.NONE if no lock requests were made.

Throws:

java.io.IOException - if there are problems with the feature store.

rollback

void rollback()
       throws java.lang.UnsupportedOperationException,
              java.io.IOException

Undoes all transactions made since the last commit or rollback. FeatureStores will need to issue any changes notifications using a FeatureEvent. This will need to be issued to all FeatureStores with the same type name and transaction.

Throws:

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

java.io.IOException - if there are problems with the feature store.

close

void close()
    throws java.io.IOException

Provides an opportunity for a transaction to free any 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 opportunity to revert to AUTO_COMMIT.

Throws:

java.io.IOException - if there are problems with the feature store.