Package org.opendaylight.mdsal.dom.api

Interface DOMTransactionChain

  • All Superinterfaces:
    AutoCloseable, DOMTransactionFactory, Registration
    All Known Implementing Classes:
    ForwardingDOMTransactionChain, PingPongTransactionChain
    public interface DOMTransactionChain
extends Registration, DOMTransactionFactory
    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: DOMWriteTransaction t1 = broker.newWriteOnlyTransaction(); t1.put(id, data); t1.commit(); DOMReadTransaction 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 Detail

      • newReadOnlyTransaction

        DOMDataTreeReadTransaction 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 DOMTransactionFactory
        Returns:
        New transaction in the chain.
        Throws:
        IllegalStateException - if the previous transaction was not SUBMITTED or CANCELLED.
        DOMTransactionChainClosedException - if the chain has been closed.

      • newWriteOnlyTransaction

        DOMDataTreeWriteTransaction 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 DOMTransactionFactory
        Returns:
        New transaction in the chain.
        Throws:
        IllegalStateException - if the previous transaction was not SUBMITTED or CANCELLED.
        DOMTransactionChainClosedException - if the chain has been closed.

      • newReadWriteTransaction

        DOMDataTreeReadWriteTransaction 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 DOMTransactionFactory
        Returns:
        New transaction in the chain.
        Throws:
        IllegalStateException - if the previous transaction was not SUBMITTED or CANCELLED.
        DOMTransactionChainClosedException - if the chain has been closed.