dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMTransactionChain.java

   1 /*
   2  * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.mdsal.dom.api;
   9
  10 import org.opendaylight.yangtools.concepts.Registration;
  11
  12 /**
  13  * A chain of transactions. Transactions in a chain need to be committed in sequence and each transaction should see
  14  * the effects of previous committed transactions as they occurred. A chain makes no guarantees of atomicity across
  15  * the chained transactions - the transactions are committed as soon as possible in the order that they were committed.
  16  * This behaviour is different from the default AsyncDataBroker, where a transaction is always created from the current
  17  * global state, not taking into account any transactions previously committed by the calling thread. Due to
  18  * the asynchronous nature of transaction submission this can lead to surprising results. If a thread executes
  19  * the following sequence sufficiently quickly:
  20  *
  21  * <code>
  22  * DOMWriteTransaction t1 = broker.newWriteOnlyTransaction();
  23  * t1.put(id, data);
  24  * t1.commit();
  25  *
  26  * DOMReadTransaction t2 = broker.newReadOnlyTransaction();
  27  * Optional&lt;?&gt; maybeData = t2.read(id).get();
  28  * </code>
  29  * it may happen, that it sees maybeData.isPresent() == false, simply because t1 has not completed the processes
  30  * of being applied and t2 is actually allocated from the previous state. This is obviously bad for users who create
  31  * incremental state in the datastore and actually read what they write in subsequent transactions.
  32  * Using a TransactionChain instead of a broker solves this particular problem, and leads to expected behavior: t2 will
  33  * always see the data written in t1
  34  * present.
  35  */
  36 public interface DOMTransactionChain extends Registration, DOMTransactionFactory {
  37     /**
  38      * Create a new read only transaction which will continue the chain.
  39      *
  40      * <p>
  41      * The previous write transaction has to be either SUBMITTED ({@link DOMDataTreeWriteTransaction#commit commit} was
  42      * invoked) or CANCELLED ({@link #close close} was invoked).
  43      *
  44      * <p>
  45      * The returned read-only transaction presents an isolated view of the data if the previous write transaction was
  46      * successful - in other words, this read-only transaction will see the state changes made by the previous write
  47      * transaction in the chain. However, state which was introduced by other transactions outside this transaction
  48      * chain after creation of the previous transaction is not visible.
  49      *
  50      * @return New transaction in the chain.
  51      * @throws IllegalStateException if the previous transaction was not SUBMITTED or CANCELLED.
  52      * @throws DOMTransactionChainClosedException if the chain has been closed.
  53      */
  54     @Override
  55     DOMDataTreeReadTransaction newReadOnlyTransaction();
  56
  57     /**
  58      * Create a new write-only transaction which will continue the chain.
  59      *
  60      * <p>
  61      * The previous write transaction has to be either SUBMITTED ({@link DOMDataTreeWriteTransaction#commit commit} was
  62      * invoked) or CANCELLED ({@link #close close} was invoked)
  63      *
  64      * <p>
  65      * The returned write-only transaction presents an isolated view of the data if the previous write transaction was
  66      * successful - in other words, this write-only transaction will see the state changes made by the previous write
  67      * transaction in the chain. However, state which was introduced by other transactions outside this transaction
  68      * chain after creation of the previous transaction is not visible
  69      *
  70      * <p>
  71      * Committing this write-only transaction using {@link DOMDataTreeWriteTransaction#commit commit} will commit
  72      * the state changes in this transaction to be visible to any subsequent transaction in this chain and also to any
  73      * transaction outside this chain.
  74      *
  75      * @return New transaction in the chain.
  76      * @throws IllegalStateException if the previous transaction was not SUBMITTED or CANCELLED.
  77      * @throws DOMTransactionChainClosedException if the chain has been closed.
  78      */
  79     @Override
  80     DOMDataTreeWriteTransaction newWriteOnlyTransaction();
  81
  82     /**
  83      * Create a new read-write transaction which will continue the chain.
  84      *
  85      * <p>
  86      * The previous write transaction has to be either SUBMITTED ({@link DOMDataTreeWriteTransaction#commit commit} was
  87      * invoked) or CANCELLED ({@link #close close} was invoked).
  88      *
  89      * <p>
  90      * The returned read-write transaction presents an isolated view of the data if the previous write transaction was
  91      * successful - in other words, this read-write transaction will see the state changes made by the previous write
  92      * transaction in the chain. However, state which was introduced by other transactions outside this transaction
  93      * chain after creation of the previous transaction is not visible.
  94      *
  95      * <p>
  96      * Committing this read-write transaction using {@link DOMDataTreeReadWriteTransaction#commit commit} will commit
  97      * the state changes in this transaction to be visible to any subsequent transaction in this chain and also to any
  98      * transaction outside this chain.
  99      *
 100      * @return New transaction in the chain.
 101      * @throws IllegalStateException if the previous transaction was not SUBMITTED or CANCELLED.
 102      * @throws DOMTransactionChainClosedException if the chain has been closed.
 103      */
 104     @Override
 105     DOMDataTreeReadWriteTransaction newReadWriteTransaction();
 106 }