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