X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;ds=sidebyside;f=dom%2Fmdsal-dom-api%2Fsrc%2Fmain%2Fjava%2Forg%2Fopendaylight%2Fmdsal%2Fdom%2Fapi%2FDOMTransactionChain.java;h=f811a6078bf1d3ecbd45f3d533d53f70083cf889;hb=c71394328f488ea5f3bccf5ac8d42c8802cb637e;hp=c8d2264755945731280e57f6a05734773ce0619d;hpb=0f351bbc28ddf2cddfe30c8d018646d81953fa17;p=mdsal.git

diff --git a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMTransactionChain.java b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMTransactionChain.java
index c8d2264755..f811a6078b 100644
--- a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMTransactionChain.java
+++ b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMTransactionChain.java
@@ -7,27 +7,100 @@
  */
 package org.opendaylight.mdsal.dom.api;
 
-import org.opendaylight.mdsal.common.api.TransactionChain;
-import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
-import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
+import org.opendaylight.yangtools.concepts.Registration;
 
 /**
- * A chain of DOM Data transactions.
- * Transactions in a chain need to be committed in sequence and each
- * transaction should see the effects of previous transactions as if they happened. A chain
- * makes no guarantees of atomicity, in fact transactions are committed as soon as possible.
+ * 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:
  *
- * <p>
- * This interface is type capture of {@link TransactionChain} for DOM Data Contracts.
+ * <code>
+ * DOMWriteTransaction t1 = broker.newWriteOnlyTransaction();
+ * t1.put(id, data);
+ * t1.commit();
+ *
+ * DOMReadTransaction t2 = broker.newReadOnlyTransaction();
+ * Optional&lt;?&gt; maybeData = t2.read(id).get();
+ * </code>
+ * 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.
  */
-public interface DOMTransactionChain extends TransactionChain<YangInstanceIdentifier, NormalizedNode<?, ?>> {
-
+public interface DOMTransactionChain extends Registration, DOMTransactionFactory {
+    /**
+     * Create a new read only transaction which will continue the chain.
+     *
+     * <p>
+     * The previous write transaction has to be either SUBMITTED ({@link DOMDataTreeWriteTransaction#commit commit} was
+     * invoked) or CANCELLED ({@link #close close} was invoked).
+     *
+     * <p>
+     * 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.
+     *
+     * @return New transaction in the chain.
+     * @throws IllegalStateException if the previous transaction was not SUBMITTED or CANCELLED.
+     * @throws DOMTransactionChainClosedException if the chain has been closed.
+     */
     @Override
     DOMDataTreeReadTransaction newReadOnlyTransaction();
 
+    /**
+     * Create a new write-only transaction which will continue the chain.
+     *
+     * <p>
+     * The previous write transaction has to be either SUBMITTED ({@link DOMDataTreeWriteTransaction#commit commit} was
+     * invoked) or CANCELLED ({@link #close close} was invoked)
+     *
+     * <p>
+     * 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
+     *
+     * <p>
+     * Committing this write-only transaction using {@link DOMDataTreeWriteTransaction#commit 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.
+     *
+     * @return New transaction in the chain.
+     * @throws IllegalStateException if the previous transaction was not SUBMITTED or CANCELLED.
+     * @throws DOMTransactionChainClosedException if the chain has been closed.
+     */
     @Override
     DOMDataTreeWriteTransaction newWriteOnlyTransaction();
 
+    /**
+     * Create a new read-write transaction which will continue the chain.
+     *
+     * <p>
+     * The previous write transaction has to be either SUBMITTED ({@link DOMDataTreeWriteTransaction#commit commit} was
+     * invoked) or CANCELLED ({@link #close close} was invoked).
+     *
+     * <p>
+     * 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.
+     *
+     * <p>
+     * Committing this read-write transaction using {@link DOMDataTreeReadWriteTransaction#commit 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.
+     *
+     * @return New transaction in the chain.
+     * @throws IllegalStateException if the previous transaction was not SUBMITTED or CANCELLED.
+     * @throws DOMTransactionChainClosedException if the chain has been closed.
+     */
     @Override
     DOMDataTreeReadWriteTransaction newReadWriteTransaction();
 }