Deprecate old MD-SAL APIs for removal
[controller.git] / opendaylight / md-sal / sal-common-api / src / main / java / org / opendaylight / controller / md / sal / common / api / data / AsyncReadWriteTransaction.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  * Transaction enabling a client to have a combined read/write capabilities.
14  *
15  * <p>
16  * The initial state of the write transaction is stable snapshot of current data tree
17  * state captured when transaction was created and it's state and underlying
18  * data tree are not affected by other concurrently running transactions.
19  *
20  * <p>
21  * Write transactions are isolated from other concurrent write transactions. All
22  * writes are local to the transaction and represents only a proposal of state
23  * change for data tree and it is not visible to any other concurrently running
24  * transactions.
25  *
26  * <p>
27  * Applications publish the changes proposed in the transaction by calling {@link #submit}
28  * on the transaction. This seals the transaction
29  * (preventing any further writes using this transaction) and submits it to be
30  * processed and applied to global conceptual data tree.
31  *
32  * <p>
33  * The transaction commit may fail due to a concurrent transaction modifying and committing data in
34  * an incompatible way. See {@link #submit()} for more concrete commit failure examples.
35  *
36  * <b>Implementation Note:</b> This interface is not intended to be implemented
37  * by users of MD-SAL, but only to be consumed by them.
38  *
39  * <h2>Examples</h2>
40  *
41  * <h3>Transaction local state</h3>
42  *
43  * <p>
44  * Let assume initial state of data tree for <code>PATH</code> is <code>A</code>
45  * .
46  *
47  * <pre>
48  * txWrite = broker.newReadWriteTransaction(); // concurrent write transaction
49  *
50  * txWrite.read(OPERATIONAL,PATH).get()        // will return Optional containing A
51  * txWrite.put(OPERATIONAL,PATH,B);            // writes B to PATH
52  * txWrite.read(OPERATIONAL,PATH).get()        // will return Optional Containing B
53  *
54  * txWrite.commit().get();                     // data tree is updated, PATH contains B
55  *
56  * tx1afterCommit = broker.newReadOnlyTransaction(); // read Transaction is snapshot of new state
57  * tx1afterCommit.read(OPERATIONAL,PATH).get(); // returns Optional containing B
58  * </pre>
59  *
60  * <p>
61  * As you could see read-write transaction provides capabilities as
62  * {@link AsyncWriteTransaction} but also allows for reading proposed changes as
63  * if they already happened.
64  *
65  * <h3>Transaction isolation (read transaction, read-write transaction)</h3> Let
66  * assume initial state of data tree for <code>PATH</code> is <code>A</code>.
67  *
68  * <pre>
69  * txRead = broker.newReadOnlyTransaction();   // read Transaction is snapshot of data
70  * txWrite = broker.newReadWriteTransaction(); // concurrent write transaction
71  *
72  * txRead.read(OPERATIONAL,PATH).get();        // will return Optional containing A
73  * txWrite.read(OPERATIONAL,PATH).get()        // will return Optional containing A
74  *
75  * txWrite.put(OPERATIONAL,PATH,B);            // writes B to PATH
76  * txWrite.read(OPERATIONAL,PATH).get()        // will return Optional Containing B
77  *
78  * txRead.read(OPERATIONAL,PATH).get();        // concurrent read transaction still returns
79  *                                             // Optional containing A
80  *
81  * txWrite.commit().get();                     // data tree is updated, PATH contains B
82  * txRead.read(OPERATIONAL,PATH).get();        // still returns Optional containing A
83  *
84  * tx1afterCommit = broker.newReadOnlyTransaction(); // read Transaction is snapshot of new state
85  * tx1afterCommit.read(OPERATIONAL,PATH).get(); // returns Optional containing B
86  * </pre>
87  *
88  * <h3>Transaction isolation (2 concurrent read-write transactions)</h3> Let
89  * assume initial state of data tree for <code>PATH</code> is <code>A</code>.
90  *
91  * <pre>
92  * tx1 = broker.newReadWriteTransaction(); // read Transaction is snapshot of data
93  * tx2 = broker.newReadWriteTransaction(); // concurrent write transaction
94  *
95  * tx1.read(OPERATIONAL,PATH).get();       // will return Optional containing A
96  * tx2.read(OPERATIONAL,PATH).get()        // will return Optional containing A
97  *
98  * tx2.put(OPERATIONAL,PATH,B);            // writes B to PATH
99  * tx2.read(OPERATIONAL,PATH).get()        // will return Optional Containing B
100  *
101  * tx1.read(OPERATIONAL,PATH).get();       // tx1 read-write transaction still sees Optional
102  *                                         // containing A since is isolated from tx2
103  * tx1.put(OPERATIONAL,PATH,C);            // writes C to PATH
104  * tx1.read(OPERATIONAL,PATH).get()        // will return Optional Containing C
105  *
106  * tx2.read(OPERATIONAL,PATH).get()        // tx2 read-write transaction still sees Optional
107  *                                         // containing B since is isolated from tx1
108  *
109  * tx2.commit().get();                     // data tree is updated, PATH contains B
110  * tx1.read(OPERATIONAL,PATH).get();       // still returns Optional containing C since is isolated from tx2
111  *
112  * tx1afterCommit = broker.newReadOnlyTransaction(); // read Transaction is snapshot of new state
113  * tx1afterCommit.read(OPERATIONAL,PATH).get(); // returns Optional containing B
114  *
115  * tx1.commit()                            // Will fail with OptimisticLockFailedException
116  *                                         // which means concurrent transaction changed the same PATH
117  *
118  * </pre>
119  *
120  * <p>
121  * <b>Note:</b> examples contains blocking calls on future only to illustrate
122  * that action happened after other asynchronous action. Use of blocking call
123  * {@link com.google.common.util.concurrent.ListenableFuture#get()} is discouraged for most uses and you should
124  * use {@link com.google.common.util.concurrent.Futures#addCallback(com.google.common.util.concurrent.ListenableFuture,
125  * com.google.common.util.concurrent.FutureCallback, java.util.concurrent.Executor)}
126  * or other functions from {@link com.google.common.util.concurrent.Futures} to
127  * register more specific listeners.
128  *
129  * @see AsyncReadTransaction
130  * @see AsyncWriteTransaction
131  *
132  * @param <P>
133  *            Type of path (subtree identifier), which represents location in
134  *            tree
135  * @param <D>
136  *            Type of data (payload), which represents data payload
137  */
138 @Deprecated(forRemoval = true)
139 public interface AsyncReadWriteTransaction<P extends Path<P>, D> extends AsyncReadTransaction<P, D>,
140         AsyncWriteTransaction<P, D> {
141
142 }

©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.