org.opendaylight.mdsal.common.api

Interface TransactionChain<P extends org.opendaylight.yangtools.concepts.Path<P>,D>

All Superinterfaces:

AsyncDataTransactionFactory<P,D>, AutoCloseable

All Known Subinterfaces:

BindingTransactionChain, BindingTransactionChain, DOMTransactionChain

All Known Implementing Classes:

BindingDOMTransactionChainAdapter, ForwardingDOMTransactionChain, PingPongTransactionChain, ShardedDOMTransactionChainAdapter

public interface TransactionChain<P extends org.opendaylight.yangtools.concepts.Path<P>,D>
extends AutoCloseable, AsyncDataTransactionFactory<P,D>

A chain of transactions. Transactions in a chain need to be committed in sequence and each transaction should see the effects of previous committed transactions as they occurred. A chain makes no guarantees of atomicity across the chained transactions - the transactions are committed as soon as possible in the order that they were committed. This behaviour is different from the default AsyncDataBroker, where a transaction is always created from the current global state, not taking into account any transactions previously committed by the calling thread. Due to the asynchronous nature of transaction submission this can lead to surprising results. If a thread executes the following sequence sufficiently quickly:

 AsyncWriteTransaction t1 = broker.newWriteOnlyTransaction();
 t1.put(id, data);
 t1.commit();

 AsyncReadTransaction t2 = broker.newReadOnlyTransaction();
 Optional<?> maybeData = t2.read(id).get();
 

it may happen, that it sees maybeData.isPresent() == false, simply because t1 has not completed the processes of being applied and t2 is actually allocated from the previous state. This is obviously bad for users who create incremental state in the datastore and actually read what they write in subsequent transactions. Using a TransactionChain instead of a broker solves this particular problem, and leads to expected behavior: t2 will always see the data written in t1 present.

Method Summary

Modifier and Type	Method and Description
void	close()
AsyncReadTransaction<P,D>	newReadOnlyTransaction() Create a new read only transaction which will continue the chain.
AsyncReadWriteTransaction<P,D>	newReadWriteTransaction() Create a new read-write transaction which will continue the chain.
AsyncWriteTransaction<P,D>	newWriteOnlyTransaction() Create a new write-only transaction which will continue the chain.

Method Detail

newReadOnlyTransaction

AsyncReadTransaction<P,D> newReadOnlyTransaction()

Create a new read only transaction which will continue the chain.

The previous write transaction has to be either SUBMITTED (commit was invoked) or CANCELLED (close was invoked).

The returned read-only transaction presents an isolated view of the data if the previous write transaction was successful - in other words, this read-only transaction will see the state changes made by the previous write transaction in the chain. However, state which was introduced by other transactions outside this transaction chain after creation of the previous transaction is not visible.

Specified by:

newReadOnlyTransaction in interface AsyncDataTransactionFactory<P extends org.opendaylight.yangtools.concepts.Path<P>,D>

Returns:

New transaction in the chain.

Throws:

IllegalStateException - if the previous transaction was not SUBMITTED or CANCELLED.

TransactionChainClosedException - if the chain has been closed.

newWriteOnlyTransaction

AsyncWriteTransaction<P,D> newWriteOnlyTransaction()

Create a new write-only transaction which will continue the chain.

The previous write transaction has to be either SUBMITTED (commit was invoked) or CANCELLED (close was invoked)

The returned write-only transaction presents an isolated view of the data if the previous write transaction was successful - in other words, this write-only transaction will see the state changes made by the previous write transaction in the chain. However, state which was introduced by other transactions outside this transaction chain after creation of the previous transaction is not visible

Committing this write-only transaction using commit will commit the state changes in this transaction to be visible to any subsequent transaction in this chain and also to any transaction outside this chain.

Specified by:

newWriteOnlyTransaction in interface AsyncDataTransactionFactory<P extends org.opendaylight.yangtools.concepts.Path<P>,D>

Returns:

New transaction in the chain.

Throws:

IllegalStateException - if the previous transaction was not SUBMITTED or CANCELLED.

TransactionChainClosedException - if the chain has been closed.

newReadWriteTransaction

AsyncReadWriteTransaction<P,D> newReadWriteTransaction()

Create a new read-write transaction which will continue the chain.

The previous write transaction has to be either SUBMITTED (commit was invoked) or CANCELLED (close was invoked).

The returned read-write transaction presents an isolated view of the data if the previous write transaction was successful - in other words, this read-write transaction will see the state changes made by the previous write transaction in the chain. However, state which was introduced by other transactions outside this transaction chain after creation of the previous transaction is not visible.

Committing this read-write transaction using commit will commit the state changes in this transaction to be visible to any subsequent transaction in this chain and also to any transaction outside this chain.

Specified by:

newReadWriteTransaction in interface AsyncDataTransactionFactory<P extends org.opendaylight.yangtools.concepts.Path<P>,D>

Returns:

New transaction in the chain.

Throws:

IllegalStateException - if the previous transaction was not SUBMITTED or CANCELLED.

TransactionChainClosedException - if the chain has been closed.

close

void close()

Specified by:

close in interface AutoCloseable