Fix checkstyle violations in sal-common-api
[controller.git] / 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 }

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.