org.opendaylight.mdsal.dom.api

Interface DOMTransactionFactory

All Known Subinterfaces:

DOMDataBroker, DOMTransactionChain, TracingDOMDataBroker

All Known Implementing Classes:

AbstractDOMDataBroker, ForwardingDOMDataBroker, ForwardingDOMTransactionChain, PingPongDataBroker, PingPongTransactionChain, SerializedDOMDataBroker, ShardedDOMDataBrokerAdapter, ShardedDOMTransactionChainAdapter, TracingBroker

public interface DOMTransactionFactory

A factory which allocates new transactions to operate on the data tree.

Note: This interface is not intended to be used directly, but rather via subinterfaces which introduces additional semantics to allocated transactions.

• DOMDataBroker
• DOMTransactionChain

All operations on the data tree are performed via one of the transactions:

• Read-Only - allocated using newReadOnlyTransaction()
• Write-Only - allocated using newWriteOnlyTransaction()

These transactions provides a stable isolated view of the data tree, which is guaranteed to be not affected by other concurrent transactions, until transaction is committed.

For a detailed explanation of how transaction are isolated and how transaction-local changes are committed to global data tree, see DOMDataTreeReadTransaction, DOMDataTreeWriteTransaction and DOMDataTreeWriteTransaction.commit().

It is strongly recommended to use the type of transaction, which provides only the minimal capabilities you need. This allows for optimizations at the data broker / data store level. For example, implementations may optimize the transaction for reading if they know ahead of time that you only need to read data - such as not keeping additional meta-data, which may be required for write transactions.

Implementation Note: This interface is not intended to be implemented by users of MD-SAL, but only to be consumed by them.

See Also:

DOMDataBroker, DOMTransactionChain

Method Summary

Modifier and Type	Method and Description
DOMDataTreeReadTransaction	newReadOnlyTransaction() Allocates a new read-only transaction which provides an immutable snapshot of the data tree.
DOMDataTreeReadWriteTransaction	newReadWriteTransaction() Allocates new read-write transaction which provides a mutable view of the data tree.
DOMDataTreeWriteTransaction	newWriteOnlyTransaction() Allocates new write-only transaction based on latest state of data tree.

Method Detail

newReadOnlyTransaction

DOMDataTreeReadTransaction newReadOnlyTransaction()

Allocates a new read-only transaction which provides an immutable snapshot of the data tree. The view of data tree is an immutable snapshot of current data tree state when transaction was allocated.

Returns:

A new read-only transaction

newWriteOnlyTransaction

DOMDataTreeWriteTransaction newWriteOnlyTransaction()

Allocates new write-only transaction based on latest state of data tree.

Preconditions for mutation of data tree are captured from the snapshot of data tree state, when the transaction is allocated. If data was changed during transaction in an incompatible way then the commit of this transaction will fail. See DOMDataTreeWriteTransaction.commit() for more details about conflicting and non-conflicting changes and failure scenarios.

Since this transaction does not provide a view of the data it SHOULD BE used only by callers which are exclusive writers (exporters of data) to the subtree they modify. This prevents optimistic lock failures as described in DOMDataTreeWriteTransaction.commit().

Exclusivity of writers to particular subtree SHOULD BE enforced by external locking mechanism.

Returns:

new write-only transaction

newReadWriteTransaction

DOMDataTreeReadWriteTransaction newReadWriteTransaction()

Allocates new read-write transaction which provides a mutable view of the data tree.

Preconditions for mutation of data tree are captured from the snapshot of data tree state, when the transaction is allocated. If data was changed during transaction in an incompatible way then the commit of this transaction will fail. See DOMDataTreeWriteTransaction.commit() for more details about conflicting and non-conflicting changes and failure scenarios.

Returns:

new read-write transaction