org.opengis.feature
Interface Transaction


Deprecated. Removed pending a redesign of feature storage interfaces

@Deprecated
@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:

Since:
GeoAPI 2.0

Nested Class Summary
static interface Transaction.State
          Deprecated. FeatureStore implementations can use this interface to externalize the state they require to implement Transaction support.
 
Field Summary
static Transaction AUTO_COMMIT
          Deprecated. Marker constant used to indicate immidiate response.
 
Method Summary
 void close()
          Deprecated. Provides an opportunity for a transaction to free any State it maintains.
 LockResponse commit()
          Deprecated. Makes all transactions made since the previous commit/rollback permanent.
 Set<String> getAuthorizations()
          Deprecated. Returns the set of authorizations IDs held by this transaction.
 Object getProperty(Object key)
          Deprecated. Retrieves a transaction property held by this transaction.
 Transaction.State getState(Object key)
          Deprecated. Retrieve a state used to squirel away information (and callbacks) for later.
 void putProperty(Object key, Object value)
          Deprecated. Provides a property for this transasction.
 void putState(Object key, Transaction.State state)
          Deprecated. Allows FeatureStore to squirel away information (and callbacks) for later.
 void removeState(Object key)
          Deprecated. Allows FeatureStores to clean up information (and callbacks) they earlier provided.
 void rollback()
          Deprecated. Undoes all transactions made since the last commit or rollback.
 void useAuthorization(String authorizationID)
          Deprecated. Uses an Authorization token with this transaction.
 

Field Detail

AUTO_COMMIT

static final Transaction AUTO_COMMIT
Deprecated. 
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(Object key,
                 Object value)
                 throws IOException
Deprecated. 
Provides a property for this transasction. All proceeding FeatureStore operations may make use of the provided property.

Throws:
IOException - if there are problems with the feature store.
See Also:
getProperty(java.lang.Object)

getProperty

Object getProperty(Object key)
Deprecated. 
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(String authorizationID)
                      throws IOException
Deprecated. 
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:

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:
IOException - if there are problems with the feature store.
See Also:
getAuthorizations()

getAuthorizations

Set<String> getAuthorizations()
Deprecated. 
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(Object key,
              Transaction.State state)
Deprecated. 
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(Object key)
Deprecated. 
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(Object key)
Deprecated. 
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 IOException
Deprecated. 
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:

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:
IOException - if there are problems with the feature store.

rollback

void rollback()
              throws UnsupportedOperationException,
                     IOException
Deprecated. 
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:
UnsupportedOperationException - if the rollback method is not supported by this datasource.
IOException - if there are problems with the feature store.

close

void close()
           throws IOException
Deprecated. 
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:
IOException - if there are problems with the feature store.


Copyright © 1994-2008 Open Geospatial Consortium. All Rights Reserved.