effeabefae89a69158d73028cc9467fb47f9a896
[controller.git] / opendaylight / md-sal / sal-common-api / src / main / java / org / opendaylight / controller / md / sal / common / api / data / AsyncWriteTransaction.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.controller.md.sal.common.api.TransactionStatus;
11 import org.opendaylight.yangtools.concepts.Path;
12 import org.opendaylight.yangtools.yang.common.RpcResult;
13
14 import com.google.common.util.concurrent.CheckedFuture;
15 import com.google.common.util.concurrent.ListenableFuture;
16
17 /**
18  * Write transaction provides mutation capabilities for a data tree.
19  *
20  * <p>
21  * Initial state of write transaction is a stable snapshot of the current data tree.
22  * The state is captured when the transaction is created and its state and underlying
23  * data tree are not affected by other concurrently running transactions.
24  * <p>
25  * Write transactions are isolated from other concurrent write transactions. All
26  * writes are local to the transaction and represent only a proposal of state
27  * change for the data tree and it is not visible to any other concurrently running
28  * transaction.
29  * <p>
30  * Applications make changes to the local data tree in the transaction by via the
31  * <b>put</b>, <b>merge</b>, and <b>delete</b> operations.
32  *
33  * <h2>Put operation</h2>
34  * Stores a piece of data at a specified path. This acts as an add / replace
35  * operation, which is to say that whole subtree will be replaced by the
36  * specified data.
37  * <p>
38  * Performing the following put operations:
39  *
40  * <pre>
41  * 1) container { list [ a ] }
42  * 2) container { list [ b ] }
43  * </pre>
44  *
45  * will result in the following data being present:
46  *
47  * <pre>
48  * container { list [ b ] }
49  * </pre>
50  * <h2>Merge operation</h2>
51  * Merges a piece of data with the existing data at a specified path. Any pre-existing data
52  * which is not explicitly overwritten will be preserved. This means that if you store a container,
53  * its child lists will be merged.
54  * <p>
55  * Performing the following merge operations:
56  *
57  * <pre>
58  * 1) container { list [ a ] }
59  * 2) container { list [ b ] }
60  * </pre>
61  *
62  * will result in the following data being present:
63  *
64  * <pre>
65  * container { list [ a, b ] }
66  * </pre>
67  *
68  * This also means that storing the container will preserve any
69  * augmentations which have been attached to it.
70  *
71  * <h2>Delete operation</h2>
72  * Removes a piece of data from a specified path.
73  * <p>
74  * After applying changes to the local data tree, applications publish the changes proposed in the
75  * transaction by calling {@link #submit} on the transaction. This seals the transaction
76  * (preventing any further writes using this transaction) and submits it to be
77  * processed and applied to global conceptual data tree.
78  * <p>
79  * The transaction commit may fail due to a concurrent transaction modifying and committing data in
80  * an incompatible way. See {@link #submit} for more concrete commit failure examples.
81  * <p>
82  * <b>Implementation Note:</b> This interface is not intended to be implemented
83  * by users of MD-SAL, but only to be consumed by them.
84  *
85  * @param <P>
86  *            Type of path (subtree identifier), which represents location in
87  *            tree
88  * @param <D>
89  *            Type of data (payload), which represents data payload
90  */
91 public interface AsyncWriteTransaction<P extends Path<P>, D> extends AsyncTransaction<P, D> {
92     /**
93      * Cancels the transaction.
94      *
95      * Transactions can only be cancelled if it's status is
96      * {@link TransactionStatus#NEW} or {@link TransactionStatus#SUBMITED}
97      *
98      * Invoking cancel() on {@link TransactionStatus#FAILED} or
99      * {@link TransactionStatus#CANCELED} will have no effect, and transaction
100      * is considered cancelled.
101      *
102      * Invoking cancel() on finished transaction  (future returned by {@link #submit()}
103      * already completed with {@link TransactionStatus#COMMITED}) will always
104      * fail (return false).
105      *
106      * @return <tt>false</tt> if the task could not be cancelled,
107      * typically because it has already completed normally;
108      * <tt>true</tt> otherwise
109      *
110      */
111     boolean cancel();
112
113     /**
114      * Removes a piece of data from specified path. This operation does not fail
115      * if the specified path does not exist.
116      *
117      * @param store
118      *            Logical data store which should be modified
119      * @param path
120      *            Data object path
121      * @throws IllegalStateException
122      *             if the transaction is no longer {@link TransactionStatus#NEW}
123      */
124     void delete(LogicalDatastoreType store, P path);
125
126     /**
127      * Submits this transaction to be asynchronously applied to update the logical data tree.
128      * The returned CheckedFuture conveys the result of applying the data changes.
129      * <p>
130      * <b>Note:</b> It is strongly recommended to process the CheckedFuture result in an asynchronous
131      * manner rather than using the blocking get() method. See example usage below.
132      * <p>
133      * This call logically seals the transaction, which prevents the client from
134      * further changing data tree using this transaction. Any subsequent calls to
135      * {@link #delete(LogicalDatastoreType, Path)} will fail with
136      * {@link IllegalStateException}.
137      *
138      * The transaction is marked as {@link TransactionStatus#SUBMITED} and
139      * enqueued into the data store back-end for processing.
140      *
141      * <p>
142      * Whether or not the commit is successful is determined by versioning
143      * of the data tree and validation of registered commit participants
144      * ({@link AsyncConfigurationCommitHandler})
145      * if the transaction changes the data tree.
146      * <p>
147      * The effects of a successful commit of data depends on data change listeners
148      * ({@link AsyncDataChangeListener}) and commit participants
149      * ({@link AsyncConfigurationCommitHandler}) that are registered with the data broker.
150      *
151      * <h3>Example usage:</h3>
152      * <pre>
153      *  private void doWrite( final int tries ) {
154      *      WriteTransaction writeTx = dataBroker.newWriteOnlyTransaction();
155      *
156      *      MyDataObject data = ...;
157      *      InstanceIdentifier&lt;MyDataObject&gt; path = ...;
158      *      writeTx.put( LogicalDatastoreType.OPERATIONAL, path, data );
159      *
160      *      Futures.addCallback( writeTx.submit(), new FutureCallback&lt;Void&gt;() {
161      *          public void onSuccess( Void result ) {
162      *              // succeeded
163      *          }
164      *
165      *          public void onFailure( Throwable t ) {
166      *              if( t instanceof OptimisticLockFailedException ) {
167      *                  if( ( tries - 1 ) &gt; 0 ) {
168      *                      // do retry
169      *                      doWrite( tries - 1 );
170      *                  } else {
171      *                      // out of retries
172      *                  }
173      *              } else {
174      *                  // failed due to another type of TransactionCommitFailedException.
175      *              }
176      *          } );
177      * }
178      * ...
179      * doWrite( 2 );
180      * </pre>
181      * <h2>Failure scenarios</h2>
182      * <p>
183      * Transaction may fail because of multiple reasons, such as
184      * <ul>
185      * <li>Another transaction finished earlier and modified the same node in a
186      * non-compatible way (see below). In this case the returned future will fail with an
187      * {@link OptimisticLockFailedException}. It is the responsibility of the
188      * caller to create a new transaction and submit the same modification again in
189      * order to update data tree. <i><b>Warning</b>: In most cases, retrying after an
190      * OptimisticLockFailedException will result in a high probability of success.
191      * However, there are scenarios, albeit unusual, where any number of retries will
192      * not succeed. Therefore it is strongly recommended to limit the number of retries (2 or 3)
193      * to avoid an endless loop.</i>
194      * </li>
195      * <li>Data change introduced by this transaction did not pass validation by
196      * commit handlers or data was incorrectly structured. Returned future will
197      * fail with a {@link DataValidationFailedException}. User should not retry to
198      * create new transaction with same data, since it probably will fail again.
199      * </li>
200      * </ul>
201      *
202      * <h3>Change compatibility</h3>
203      *
204      * There are several sets of changes which could be considered incompatible
205      * between two transactions which are derived from same initial state.
206      * Rules for conflict detection applies recursively for each subtree
207      * level.
208      *
209      * <h4>Change compatibility of leafs, leaf-list items</h4>
210      *
211      * Following table shows  state changes and failures between two concurrent transactions,
212      * which are based on same initial state, Tx 1 completes successfully
213      * before Tx 2 is submitted.
214      *
215      * <table summary="">
216      * <tr><th>Initial state</th><th>Tx 1</th><th>Tx 2</th><th>Result</th></tr>
217      * <tr><td>Empty</td><td>put(A,1)</td><td>put(A,2)</td><td>Tx 2 will fail, state is A=1</td></tr>
218      * <tr><td>Empty</td><td>put(A,1)</td><td>merge(A,2)</td><td>A=2</td></tr>
219      *
220      * <tr><td>Empty</td><td>merge(A,1)</td><td>put(A,2)</td><td>Tx 2 will fail, state is A=1</td></tr>
221      * <tr><td>Empty</td><td>merge(A,1)</td><td>merge(A,2)</td><td>A=2</td></tr>
222      *
223      *
224      * <tr><td>A=0</td><td>put(A,1)</td><td>put(A,2)</td><td>Tx 2 will fail, A=1</td></tr>
225      * <tr><td>A=0</td><td>put(A,1)</td><td>merge(A,2)</td><td>A=2</td></tr>
226      * <tr><td>A=0</td><td>merge(A,1)</td><td>put(A,2)</td><td>Tx 2 will fail, A=1</td></tr>
227      * <tr><td>A=0</td><td>merge(A,1)</td><td>merge(A,2)</td><td>A=2</td></tr>
228      *
229      * <tr><td>A=0</td><td>delete(A)</td><td>put(A,2)</td><td>Tx 2 will fail, A does not exists</td></tr>
230      * <tr><td>A=0</td><td>delete(A)</td><td>merge(A,2)</td><td>A=2</td></tr>
231      * </table>
232      *
233      * <h4>Change compatibility of subtrees</h4>
234      *
235      * Following table shows  state changes and failures between two concurrent transactions,
236      * which are based on same initial state, Tx 1 completes successfully
237      * before Tx 2 is submitted.
238      *
239      * <table summary="">
240      * <tr><th>Initial state</th><th>Tx 1</th><th>Tx 2</th><th>Result</th></tr>
241      *
242      * <tr><td>Empty</td><td>put(TOP,[])</td><td>put(TOP,[])</td><td>Tx 2 will fail, state is TOP=[]</td></tr>
243      * <tr><td>Empty</td><td>put(TOP,[])</td><td>merge(TOP,[])</td><td>TOP=[]</td></tr>
244      *
245      * <tr><td>Empty</td><td>put(TOP,[FOO=1])</td><td>put(TOP,[BAR=1])</td><td>Tx 2 will fail, state is TOP=[FOO=1]</td></tr>
246      * <tr><td>Empty</td><td>put(TOP,[FOO=1])</td><td>merge(TOP,[BAR=1])</td><td>TOP=[FOO=1,BAR=1]</td></tr>
247      *
248      * <tr><td>Empty</td><td>merge(TOP,[FOO=1])</td><td>put(TOP,[BAR=1])</td><td>Tx 2 will fail, state is TOP=[FOO=1]</td></tr>
249      * <tr><td>Empty</td><td>merge(TOP,[FOO=1])</td><td>merge(TOP,[BAR=1])</td><td>TOP=[FOO=1,BAR=1]</td></tr>
250      *
251      * <tr><td>TOP=[]</td><td>put(TOP,[FOO=1])</td><td>put(TOP,[BAR=1])</td><td>Tx 2 will fail, state is TOP=[FOO=1]</td></tr>
252      * <tr><td>TOP=[]</td><td>put(TOP,[FOO=1])</td><td>merge(TOP,[BAR=1])</td><td>state is TOP=[FOO=1,BAR=1]</td></tr>
253      * <tr><td>TOP=[]</td><td>merge(TOP,[FOO=1])</td><td>put(TOP,[BAR=1])</td><td>Tx 2 will fail, state is TOP=[FOO=1]</td></tr>
254      * <tr><td>TOP=[]</td><td>merge(TOP,[FOO=1])</td><td>merge(TOP,[BAR=1])</td><td>state is TOP=[FOO=1,BAR=1]</td></tr>
255      * <tr><td>TOP=[]</td><td>delete(TOP)</td><td>put(TOP,[BAR=1])</td><td>Tx 2 will fail, state is empty store</td></tr>
256      * <tr><td>TOP=[]</td><td>delete(TOP)</td><td>merge(TOP,[BAR=1])</td><td>state is TOP=[BAR=1]</td></tr>
257      *
258      * <tr><td>TOP=[]</td><td>put(TOP/FOO,1)</td><td>put(TOP/BAR,1])</td><td>state is TOP=[FOO=1,BAR=1]</td></tr>
259      * <tr><td>TOP=[]</td><td>put(TOP/FOO,1)</td><td>merge(TOP/BAR,1)</td><td>state is TOP=[FOO=1,BAR=1]</td></tr>
260      * <tr><td>TOP=[]</td><td>merge(TOP/FOO,1)</td><td>put(TOP/BAR,1)</td><td>state is TOP=[FOO=1,BAR=1]</td></tr>
261      * <tr><td>TOP=[]</td><td>merge(TOP/FOO,1)</td><td>merge(TOP/BAR,1)</td><td>state is TOP=[FOO=1,BAR=1]</td></tr>
262      * <tr><td>TOP=[]</td><td>delete(TOP)</td><td>put(TOP/BAR,1)</td><td>Tx 2 will fail, state is empty store</td></tr>
263      * <tr><td>TOP=[]</td><td>delete(TOP)</td><td>merge(TOP/BAR,1]</td><td>Tx 2 will fail, state is empty store</td></tr>
264      *
265      * <tr><td>TOP=[FOO=1]</td><td>put(TOP/FOO,2)</td><td>put(TOP/BAR,1)</td><td>state is TOP=[FOO=2,BAR=1]</td></tr>
266      * <tr><td>TOP=[FOO=1]</td><td>put(TOP/FOO,2)</td><td>merge(TOP/BAR,1)</td><td>state is TOP=[FOO=2,BAR=1]</td></tr>
267      * <tr><td>TOP=[FOO=1]</td><td>merge(TOP/FOO,2)</td><td>put(TOP/BAR,1)</td><td>state is TOP=[FOO=2,BAR=1]</td></tr>
268      * <tr><td>TOP=[FOO=1]</td><td>merge(TOP/FOO,2)</td><td>merge(TOP/BAR,1)</td><td>state is TOP=[FOO=2,BAR=1]</td></tr>
269      * <tr><td>TOP=[FOO=1]</td><td>delete(TOP/FOO)</td><td>put(TOP/BAR,1)</td><td>state is TOP=[BAR=1]</td></tr>
270      * <tr><td>TOP=[FOO=1]</td><td>delete(TOP/FOO)</td><td>merge(TOP/BAR,1]</td><td>state is TOP=[BAR=1]</td></tr>
271      * </table>
272      *
273      *
274      * <h3>Examples of failure scenarios</h3>
275      *
276      * <h4>Conflict of two transactions</h4>
277      *
278      * This example illustrates two concurrent transactions, which derived from
279      * same initial state of data tree and proposes conflicting modifications.
280      *
281      * <pre>
282      * txA = broker.newWriteTransaction(); // allocates new transaction, data tree is empty
283      * txB = broker.newWriteTransaction(); // allocates new transaction, data tree is empty
284      *
285      * txA.put(CONFIGURATION, PATH, A);    // writes to PATH value A
286      * txB.put(CONFIGURATION, PATH, B)     // writes to PATH value B
287      *
288      * ListenableFuture futureA = txA.submit(); // transaction A is sealed and submitted
289      * ListenebleFuture futureB = txB.submit(); // transaction B is sealed and submitted
290      * </pre>
291      *
292      * Commit of transaction A will be processed asynchronously and data tree
293      * will be updated to contain value <code>A</code> for <code>PATH</code>.
294      * Returned {@link ListenableFuture} will successfully complete once
295      * state is applied to data tree.
296      *
297      * Commit of Transaction B will fail, because previous transaction also
298      * modified path in a concurrent way. The state introduced by transaction B
299      * will not be applied. Returned {@link ListenableFuture} object will fail
300      * with {@link OptimisticLockFailedException} exception, which indicates to
301      * client that concurrent transaction prevented the submitted transaction from being
302      * applied.
303      * <br>
304      * @return a CheckFuture containing the result of the commit. The Future blocks until the
305      *         commit operation is complete. A successful commit returns nothing. On failure,
306      *         the Future will fail with a {@link TransactionCommitFailedException} or an exception
307      *         derived from TransactionCommitFailedException.
308      *
309      * @throws IllegalStateException
310      *             if the transaction is not {@link TransactionStatus#NEW}
311      */
312     CheckedFuture<Void,TransactionCommitFailedException> submit();
313
314     /**
315      * @deprecated Use {@link #submit()} instead.
316      */
317     @Deprecated
318     ListenableFuture<RpcResult<TransactionStatus>> commit();
319
320 }

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