2 * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
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
8 package org.opendaylight.mdsal.common.api;
10 import org.opendaylight.yangtools.concepts.Path;
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:
24 * AsyncWriteTransaction t1 = broker.newWriteOnlyTransaction();
28 * AsyncReadTransaction t2 = broker.newReadOnlyTransaction();
29 * Optional<?> maybeData = t2.read(id).get();
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
40 public interface TransactionChain<P extends Path<P>, D> extends AutoCloseable,
41 AsyncDataTransactionFactory<P, D> {
44 * Create a new read only transaction which will continue the chain.
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).
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.
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.
65 AsyncReadTransaction<P, D> newReadOnlyTransaction();
68 * Create a new write-only transaction which will continue the chain.
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)
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
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.
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.
94 AsyncWriteTransaction<P, D> newWriteOnlyTransaction();
97 * Create a new read-write transaction which will continue the chain.
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).
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.
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.
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.
123 AsyncReadWriteTransaction<P, D> newReadWriteTransaction();