Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `FeatureStore`s. 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 `FeatureCollection`s. 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
`static interface` | `Transaction.State` `FeatureStore` implementations can use this interface to externalize the state they require to implement `Transaction` support.

Field Summary
`static Transaction` | `AUTO_COMMIT` Marker constant used to indicate immidiate response.

Method Summary
`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.
`Set<String>` | `getAuthorizations()` Returns the set of authorizations IDs held by this transaction.
`Object` | `getProperty(Object key)` Retrieves a transaction property held by this transaction.
`Transaction.State` | `getState(Object key)` Retrieve a state used to squirel away information (and callbacks) for later.
`void` | `putProperty(Object key, Object value)` Provides a property for this transasction.
`void` | `putState(Object key, Transaction.State state)` Allows `FeatureStore` to squirel away information (and callbacks) for later.
`void` | `removeState(Object key)` Allows `FeatureStore`s to clean up information (and callbacks) they earlier provided.
`void` | `rollback()` Undoes all transactions made since the last commit or rollback.
`void` | `useAuthorization(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(Object key,
                     Object value)
                     throws IOException

  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)

  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

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

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

### getAuthorizations

    Set<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(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(Object key)

  Allows `FeatureStore`s 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)

  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

  Makes all transactions made since the previous commit/rollback permanent. `FeatureStore`s will need to issue any changes notifications using a `FeatureEvent` to all `FeatureStore`s with the same type name and a different transaction. `FeatureStore`s 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:
    `IOException` - if there are problems with the feature store.

### rollback

    void rollback()
                  throws UnsupportedOperationException,
                         IOException

  Undoes all transactions made since the last commit or rollback. `FeatureStore`s will need to issue any changes notifications using a `FeatureEvent`. This will need to be issued to all `FeatureStore`s 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

  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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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