ForwardingDOMDataReadWriteTransaction (controller 0.7.5-SNAPSHOT API)

java.lang.Object
- com.google.common.collect.ForwardingObject
- - org.opendaylight.controller.md.sal.dom.spi.ForwardingDOMDataReadWriteTransaction

All Implemented Interfaces:

AsyncReadTransaction<org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier,org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?>>, AsyncReadWriteTransaction<org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier,org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?>>, AsyncTransaction<org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier,org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?>>, AsyncWriteTransaction<org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier,org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?>>, DOMDataReadTransaction, DOMDataReadWriteTransaction, DOMDataWriteTransaction, org.opendaylight.yangtools.concepts.Identifiable<Object>
```
public abstract class ForwardingDOMDataReadWriteTransaction
extends com.google.common.collect.ForwardingObject
implements DOMDataReadWriteTransaction
```
Utility DOMDataReadWriteTransaction implementation which forwards all interface method invocation to a delegate instance.

Constructor Summary

Constructors
Constructor and Description

ForwardingDOMDataReadWriteTransaction()

Constructors
Constructor and Description
`ForwardingDOMDataReadWriteTransaction()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`cancel()` Cancels the transaction.
`com.google.common.util.concurrent.ListenableFuture<org.opendaylight.yangtools.yang.common.RpcResult<TransactionStatus>>`	`commit()` Deprecated.
`protected abstract DOMDataReadWriteTransaction`	`delegate()`
`void`	`delete(LogicalDatastoreType store, org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier path)` Removes a piece of data from specified path.
`com.google.common.util.concurrent.CheckedFuture<Boolean,ReadFailedException>`	`exists(LogicalDatastoreType store, org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier path)` Checks if data is available in the logical data store located at provided path.
`Object`	`getIdentifier()`
`void`	`merge(LogicalDatastoreType store, org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier path, org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?> data)` Merges a piece of data with the existing data at a specified path.
`void`	`put(LogicalDatastoreType store, org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier path, org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?> data)` Stores a piece of data at the specified path.
`com.google.common.util.concurrent.CheckedFuture<com.google.common.base.Optional<org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?>>,ReadFailedException>`	`read(LogicalDatastoreType store, org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier path)` Reads data from provided logical data store located at the provided path.
`com.google.common.util.concurrent.CheckedFuture<Void,TransactionCommitFailedException>`	`submit()` Submits this transaction to be asynchronously applied to update the logical data tree.

Methods inherited from class com.google.common.collect.ForwardingObject
toString

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail
- ForwardingDOMDataReadWriteTransaction
```
public ForwardingDOMDataReadWriteTransaction()
```

Method Detail

delegate
```
@Nonnull
protected abstract DOMDataReadWriteTransaction delegate()
```
Specified by:

delegate in class com.google.common.collect.ForwardingObject

read
```
public com.google.common.util.concurrent.CheckedFuture<com.google.common.base.Optional<org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?>>,ReadFailedException> read(LogicalDatastoreType store,
                                                                                                                                                                                      org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier path)
```
Description copied from interface: DOMDataReadTransaction

Reads data from provided logical data store located at the provided path.
If the target is a subtree, then the whole subtree is read (and will be accessible from the returned data object).
Specified by:

read in interface DOMDataReadTransaction

Parameters:

store - Logical data store from which read should occur.

path - Path which uniquely identifies subtree which client want to read

Returns:
a CheckFuture containing the result of the read. The Future blocks until the commit operation is complete. Once complete:
- If the data at the supplied path exists, the Future returns an Optional object containing the data.
- If the data at the supplied path does not exist, the Future returns Optional#absent().
- If the read of the data fails, the Future will fail with a ReadFailedException or an exception derived from ReadFailedException.

exists
```
public com.google.common.util.concurrent.CheckedFuture<Boolean,ReadFailedException> exists(LogicalDatastoreType store,
                                                                                           org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier path)
```
Description copied from interface: DOMDataReadTransaction

Checks if data is available in the logical data store located at provided path.
Note: a successful result from this method makes no guarantee that a subsequent call to DOMDataReadTransaction.read(org.opendaylight.controller.md.sal.common.api.data.LogicalDatastoreType, org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier) will succeed. It is possible that the data resides in a data store on a remote node and, if that node goes down or a network failure occurs, a subsequent read would fail. Another scenario is if the data is deleted in between the calls to exists and read
Specified by:

exists in interface DOMDataReadTransaction

Parameters:

store - Logical data store from which read should occur.

path - Path which uniquely identifies subtree which client want to check existence of

Returns:
a CheckFuture containing the result of the check.
- If the data at the supplied path exists, the Future returns a Boolean whose value is true, false otherwise
- If checking for the data fails, the Future will fail with a ReadFailedException or an exception derived from ReadFailedException.

getIdentifier
```
public Object getIdentifier()
```
Specified by:

getIdentifier in interface AsyncTransaction<org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier,org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?>>

Specified by:

getIdentifier in interface org.opendaylight.yangtools.concepts.Identifiable<Object>

put
```
public void put(LogicalDatastoreType store,
                org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier path,
                org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?> data)
```
Description copied from interface: DOMDataWriteTransaction

Stores a piece of data at the specified path. This acts as an add / replace operation, which is to say that whole subtree will be replaced by the specified data.
For more information on usage and examples, please see the documentation in AsyncWriteTransaction.
If you need to make sure that a parent object exists but you do not want modify its pre-existing state by using put, consider using DOMDataWriteTransaction.merge(org.opendaylight.controller.md.sal.common.api.data.LogicalDatastoreType, org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier, org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?, ?>) instead.

Specified by:

put in interface DOMDataWriteTransaction

Parameters:

store - the logical data store which should be modified

path - the data object path

data - the data object to be written to the specified path

merge
```
public void merge(LogicalDatastoreType store,
                  org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier path,
                  org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?> data)
```
Description copied from interface: DOMDataWriteTransaction

Merges a piece of data with the existing data at a specified path. Any pre-existing data which is not explicitly overwritten will be preserved. This means that if you store a container, its child lists will be merged.
For more information on usage and examples, please see the documentation in AsyncWriteTransaction.
If you require an explicit replace operation, use DOMDataWriteTransaction.put(org.opendaylight.controller.md.sal.common.api.data.LogicalDatastoreType, org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier, org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?, ?>) instead.

Specified by:

merge in interface DOMDataWriteTransaction

Parameters:

store - the logical data store which should be modified

path - the data object path

data - the data object to be merged to the specified path

cancel
```
public boolean cancel()
```
Description copied from interface: AsyncWriteTransaction

Cancels the transaction. Transactions can only be cancelled if it's status is TransactionStatus.NEW or TransactionStatus.SUBMITED Invoking cancel() on TransactionStatus.FAILED or TransactionStatus.CANCELED will have no effect, and transaction is considered cancelled. Invoking cancel() on finished transaction (future returned by AsyncWriteTransaction.submit() already completed with TransactionStatus.COMMITED) will always fail (return false).

Specified by:

cancel in interface AsyncWriteTransaction<org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier,org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?>>

Returns:

false if the task could not be cancelled, typically because it has already completed normally; true otherwise

delete
```
public void delete(LogicalDatastoreType store,
                   org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier path)
```
Description copied from interface: AsyncWriteTransaction

Removes a piece of data from specified path. This operation does not fail if the specified path does not exist.

Specified by:

delete in interface AsyncWriteTransaction<org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier,org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?>>

Specified by:

delete in interface DOMDataWriteTransaction

Parameters:

store - Logical data store which should be modified

path - Data object path

submit

public com.google.common.util.concurrent.CheckedFuture<Void,TransactionCommitFailedException> submit()

Description copied from interface: AsyncWriteTransaction

Submits this transaction to be asynchronously applied to update the logical data tree. The returned CheckedFuture conveys the result of applying the data changes.

Note: It is strongly recommended to process the CheckedFuture result in an asynchronous manner rather than using the blocking get() method. See example usage below.

This call logically seals the transaction, which prevents the client from further changing data tree using this transaction. Any subsequent calls to AsyncWriteTransaction.delete(LogicalDatastoreType, Path) will fail with IllegalStateException. The transaction is marked as TransactionStatus.SUBMITED and enqueued into the data store back-end for processing.

Whether or not the commit is successful is determined by versioning of the data tree and validation of registered commit participants (AsyncConfigurationCommitHandler) if the transaction changes the data tree.

The effects of a successful commit of data depends on data change listeners (AsyncDataChangeListener) and commit participants (AsyncConfigurationCommitHandler) that are registered with the data broker.

Example usage:

  private void doWrite( final int tries ) {
      WriteTransaction writeTx = dataBroker.newWriteOnlyTransaction();

      MyDataObject data = ...;
      InstanceIdentifier<MyDataObject> path = ...;
      writeTx.put( LogicalDatastoreType.OPERATIONAL, path, data );

      Futures.addCallback( writeTx.submit(), new FutureCallback<Void>() {
          public void onSuccess( Void result ) {
              // succeeded
          }

          public void onFailure( Throwable t ) {
              if( t instanceof OptimisticLockFailedException ) {
                  if( ( tries - 1 ) > 0 ) {
                      // do retry
                      doWrite( tries - 1 );
                  } else {
                      // out of retries
                  }
              } else {
                  // failed due to another type of TransactionCommitFailedException.
              }
          } );
 }
 ...
 doWrite( 2 );

Failure scenarios

Transaction may fail because of multiple reasons, such as

Another transaction finished earlier and modified the same node in a non-compatible way (see below). In this case the returned future will fail with an OptimisticLockFailedException. It is the responsibility of the caller to create a new transaction and submit the same modification again in order to update data tree. Warning: In most cases, retrying after an OptimisticLockFailedException will result in a high probability of success. However, there are scenarios, albeit unusual, where any number of retries will not succeed. Therefore it is strongly recommended to limit the number of retries (2 or 3) to avoid an endless loop.
Data change introduced by this transaction did not pass validation by commit handlers or data was incorrectly structured. Returned future will fail with a DataValidationFailedException. User should not retry to create new transaction with same data, since it probably will fail again.

Change compatibility

There are several sets of changes which could be considered incompatible between two transactions which are derived from same initial state. Rules for conflict detection applies recursively for each subtree level.

Change compatibility of leafs, leaf-list items

Following table shows state changes and failures between two concurrent transactions, which are based on same initial state, Tx 1 completes successfully before Tx 2 is submitted.

Initial state	Tx 1	Tx 2	Result
Empty	put(A,1)	put(A,2)	Tx 2 will fail, state is A=1
Empty	put(A,1)	merge(A,2)	A=2
Empty	merge(A,1)	put(A,2)	Tx 2 will fail, state is A=1
Empty	merge(A,1)	merge(A,2)	A=2
A=0	put(A,1)	put(A,2)	Tx 2 will fail, A=1
A=0	put(A,1)	merge(A,2)	A=2
A=0	merge(A,1)	put(A,2)	Tx 2 will fail, A=1
A=0	merge(A,1)	merge(A,2)	A=2
A=0	delete(A)	put(A,2)	Tx 2 will fail, A does not exists
A=0	delete(A)	merge(A,2)	A=2

Change compatibility of subtrees

Following table shows state changes and failures between two concurrent transactions, which are based on same initial state, Tx 1 completes successfully before Tx 2 is submitted.

Initial state	Tx 1	Tx 2	Result
Empty	put(TOP,[])	put(TOP,[])	Tx 2 will fail, state is TOP=[]
Empty	put(TOP,[])	merge(TOP,[])	TOP=[]
Empty	put(TOP,[FOO=1])	put(TOP,[BAR=1])	Tx 2 will fail, state is TOP=[FOO=1]
Empty	put(TOP,[FOO=1])	merge(TOP,[BAR=1])	TOP=[FOO=1,BAR=1]
Empty	merge(TOP,[FOO=1])	put(TOP,[BAR=1])	Tx 2 will fail, state is TOP=[FOO=1]
Empty	merge(TOP,[FOO=1])	merge(TOP,[BAR=1])	TOP=[FOO=1,BAR=1]
TOP=[]	put(TOP,[FOO=1])	put(TOP,[BAR=1])	Tx 2 will fail, state is TOP=[FOO=1]
TOP=[]	put(TOP,[FOO=1])	merge(TOP,[BAR=1])	state is TOP=[FOO=1,BAR=1]
TOP=[]	merge(TOP,[FOO=1])	put(TOP,[BAR=1])	Tx 2 will fail, state is TOP=[FOO=1]
TOP=[]	merge(TOP,[FOO=1])	merge(TOP,[BAR=1])	state is TOP=[FOO=1,BAR=1]
TOP=[]	delete(TOP)	put(TOP,[BAR=1])	Tx 2 will fail, state is empty store
TOP=[]	delete(TOP)	merge(TOP,[BAR=1])	state is TOP=[BAR=1]
TOP=[]	put(TOP/FOO,1)	put(TOP/BAR,1])	state is TOP=[FOO=1,BAR=1]
TOP=[]	put(TOP/FOO,1)	merge(TOP/BAR,1)	state is TOP=[FOO=1,BAR=1]
TOP=[]	merge(TOP/FOO,1)	put(TOP/BAR,1)	state is TOP=[FOO=1,BAR=1]
TOP=[]	merge(TOP/FOO,1)	merge(TOP/BAR,1)	state is TOP=[FOO=1,BAR=1]
TOP=[]	delete(TOP)	put(TOP/BAR,1)	Tx 2 will fail, state is empty store
TOP=[]	delete(TOP)	merge(TOP/BAR,1]	Tx 2 will fail, state is empty store
TOP=[FOO=1]	put(TOP/FOO,2)	put(TOP/BAR,1)	state is TOP=[FOO=2,BAR=1]
TOP=[FOO=1]	put(TOP/FOO,2)	merge(TOP/BAR,1)	state is TOP=[FOO=2,BAR=1]
TOP=[FOO=1]	merge(TOP/FOO,2)	put(TOP/BAR,1)	state is TOP=[FOO=2,BAR=1]
TOP=[FOO=1]	merge(TOP/FOO,2)	merge(TOP/BAR,1)	state is TOP=[FOO=2,BAR=1]
TOP=[FOO=1]	delete(TOP/FOO)	put(TOP/BAR,1)	state is TOP=[BAR=1]
TOP=[FOO=1]	delete(TOP/FOO)	merge(TOP/BAR,1]	state is TOP=[BAR=1]

Examples of failure scenarios

Conflict of two transactions

This example illustrates two concurrent transactions, which derived from same initial state of data tree and proposes conflicting modifications.

 txA = broker.newWriteTransaction(); // allocates new transaction, data tree is empty
 txB = broker.newWriteTransaction(); // allocates new transaction, data tree is empty

 txA.put(CONFIGURATION, PATH, A);    // writes to PATH value A
 txB.put(CONFIGURATION, PATH, B)     // writes to PATH value B

 ListenableFuture futureA = txA.submit(); // transaction A is sealed and submitted
 ListenebleFuture futureB = txB.submit(); // transaction B is sealed and submitted

Commit of transaction A will be processed asynchronously and data tree will be updated to contain value A for PATH. Returned ListenableFuture will successfully complete once state is applied to data tree. Commit of Transaction B will fail, because previous transaction also modified path in a concurrent way. The state introduced by transaction B will not be applied. Returned ListenableFuture object will fail with OptimisticLockFailedException exception, which indicates to client that concurrent transaction prevented the submitted transaction from being applied.

Specified by:: submit in interface AsyncWriteTransaction<org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier,org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?>>
Returns:: a CheckFuture containing the result of the commit. The Future blocks until the commit operation is complete. A successful commit returns nothing. On failure, the Future will fail with a TransactionCommitFailedException or an exception derived from TransactionCommitFailedException.

commit
```
@Deprecated
public com.google.common.util.concurrent.ListenableFuture<org.opendaylight.yangtools.yang.common.RpcResult<TransactionStatus>> commit()
```
Deprecated.

Specified by:

commit in interface AsyncWriteTransaction<org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier,org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode<?,?>>

Class ForwardingDOMDataReadWriteTransaction

Constructor Summary

Method Summary

Methods inherited from class com.google.common.collect.ForwardingObject

Methods inherited from class java.lang.Object

Constructor Detail

ForwardingDOMDataReadWriteTransaction

Method Detail

delegate

read

exists

getIdentifier

put

merge

cancel

delete