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

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