common/mdsal-common-api/src/main/java/org/opendaylight/mdsal/common/api/TransactionChain.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.common.api;
   9
  10 import org.opendaylight.yangtools.concepts.Path;
  11
  12 /**
  13  * A chain of transactions. Transactions in a chain need to be committed in
  14  * sequence and each transaction should see the effects of previous committed transactions
  15  * as they occurred. A chain makes no guarantees of atomicity across the chained transactions -
  16  * the transactions are committed as soon as possible in the order that they were submitted.
  17  * This behaviour is different from the default AsyncDataBroker, where a
  18  * transaction is always created from the current global state, not taking into
  19  * account any transactions previously committed by the calling thread. Due to
  20  * the asynchronous nature of transaction submission this can lead to surprising
  21  * results. If a thread executes the following sequence sufficiently quickly:
  22  *
  23  * <pre><code>
  24  * AsyncWriteTransaction t1 = broker.newWriteOnlyTransaction();
  25  * t1.put(id, data);
  26  * t1.submit();
  27  *
  28  * AsyncReadTransaction t2 = broker.newReadOnlyTransaction();
  29  * Optional&lt;?&gt; maybeData = t2.read(id).get();
  30  * </code></pre>
  31  * it may happen, that it sees maybeData.isPresent() == false, simply because
  32  * t1 has not completed the processes of being applied and t2 is actually
  33  * allocated from the previous state. This is obviously bad for users who create
  34  * incremental state in the datastore and actually read what they write in
  35  * subsequent transactions.
  36  * Using a TransactionChain instead of a broker solves this particular problem,
  37  * and leads to expected behavior: t2 will always see the data written in t1
  38  * present.
  39  */
  40 public interface TransactionChain<P extends Path<P>, D> extends AutoCloseable,
  41         AsyncDataTransactionFactory<P, D> {
  42
  43     /**
  44      * Create a new read only transaction which will continue the chain.
  45      *
  46      * <p>
  47      * The previous write transaction has to be either SUBMITTED
  48      * ({@link AsyncWriteTransaction#submit submit} was invoked) or CANCELLED
  49      * ({@link #close close} was invoked).
  50      *
  51      * <p>
  52      * The returned read-only transaction presents an isolated view of the data if the previous
  53      * write transaction was successful - in other words, this read-only transaction will see the
  54      * state changes made by the previous write transaction in the chain. However, state which
  55      * was introduced by other transactions outside this transaction chain after creation of
  56      * the previous transaction is not visible.
  57      *
  58      * @return New transaction in the chain.
  59      * @throws IllegalStateException
  60      *             if the previous transaction was not SUBMITTED or CANCELLED.
  61      * @throws TransactionChainClosedException
  62      *             if the chain has been closed.
  63      */
  64     @Override
  65     AsyncReadTransaction<P, D> newReadOnlyTransaction();
  66
  67     /**
  68      * Create a new write-only transaction which will continue the chain.
  69      *
  70      * <p>
  71      * The previous write transaction has to be either SUBMITTED
  72      * ({@link AsyncWriteTransaction#submit submit} was invoked) or CANCELLED
  73      * ({@link #close close} was invoked)
  74      *
  75      * <p>
  76      * The returned write-only transaction presents an isolated view of the data if the previous
  77      * write transaction was successful - in other words, this write-only transaction will see the
  78      * state changes made by the previous write transaction in the chain. However, state which
  79      * was introduced by other transactions outside this transaction chain after creation of
  80      * the previous transaction is not visible
  81      *
  82      * <p>
  83      * Committing this write-only transaction using {@link AsyncWriteTransaction#submit submit}
  84      * will submit the state changes in this transaction to be visible to any subsequent
  85      * transaction in this chain and also to any transaction outside this chain.
  86      *
  87      * @return New transaction in the chain.
  88      * @throws IllegalStateException
  89      *             if the previous transaction was not SUBMITTED or CANCELLED.
  90      * @throws TransactionChainClosedException
  91      *             if the chain has been closed.
  92      */
  93     @Override
  94     AsyncWriteTransaction<P, D> newWriteOnlyTransaction();
  95
  96     /**
  97      * Create a new read-write transaction which will continue the chain.
  98      *
  99      * <p>
 100      * The previous write transaction has to be either SUBMITTED
 101      * ({@link AsyncWriteTransaction#submit submit} was invoked) or CANCELLED
 102      * ({@link #close close} was invoked).
 103      *
 104      * <p>
 105      * The returned read-write transaction presents an isolated view of the data if the previous
 106      * write transaction was successful - in other words, this read-write transaction will see the
 107      * state changes made by the previous write transaction in the chain. However, state which
 108      * was introduced by other transactions outside this transaction chain after creation of
 109      * the previous transaction is not visible.
 110      *
 111      * <p>
 112      * Committing this read-write transaction using {@link AsyncWriteTransaction#submit submit}
 113      * will submit the state changes in this transaction to be visible to any subsequent
 114      * transaction in this chain and also to any transaction outside this chain.
 115      *
 116      * @return New transaction in the chain.
 117      * @throws IllegalStateException
 118      *             if the previous transaction was not SUBMITTED or CANCELLED.
 119      * @throws TransactionChainClosedException
 120      *             if the chain has been closed.
 121      */
 122     @Override
 123     AsyncReadWriteTransaction<P, D> newReadWriteTransaction();
 124
 125     @Override
 126     void close();
 127 }