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.ListenableFuture;
  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  * <p>
  24  * Write transactions are isolated from other concurrent write transactions. All
  25  * writes are local to the transaction and represent only a proposal of state
  26  * change for the data tree and it is not visible to any other concurrently running
  27  * transaction.
  28  * <p>
  29  * Applications publish the changes proposed in the transaction by calling {@link #commit}
  30  * on the transaction. This seals the transaction
  31  * (preventing any further writes using this transaction) and submits it to be
  32  * processed and applied to global conceptual data tree.
  33  * <p>
  34  * The transaction commit may fail due to a concurrent transaction modifying and committing data in
  35  * an incompatible way. See {@link #commit()} for more concrete commit failure examples.
  36  *
  37  *
  38  * <p>
  39  * <b>Implementation Note:</b> This interface is not intended to be implemented
  40  * by users of MD-SAL, but only to be consumed by them.
  41  *
  42  * @param <P>
  43  *            Type of path (subtree identifier), which represents location in
  44  *            tree
  45  * @param <D>
  46  *            Type of data (payload), which represents data payload
  47  */
  48 public interface AsyncWriteTransaction<P extends Path<P>, D> extends AsyncTransaction<P, D> {
  49     /**
  50      * Cancels the transaction.
  51      *
  52      * Transactions can only be cancelled if it's status is
  53      * {@link TransactionStatus#NEW} or {@link TransactionStatus#SUBMITED}
  54      *
  55      * Invoking cancel() on {@link TransactionStatus#FAILED} or
  56      * {@link TransactionStatus#CANCELED} will have no effect, and transaction
  57      * is considered cancelled.
  58      *
  59      * Invoking cancel() on finished transaction  (future returned by {@link #commit()}
  60      * already completed with {@link TransactionStatus#COMMITED}) will always
  61      * fail (return false).
  62      *
  63      * @return <tt>false</tt> if the task could not be cancelled,
  64      * typically because it has already completed normally;
  65      * <tt>true</tt> otherwise
  66      *
  67      */
  68     public boolean cancel();
  69
  70     /**
  71      * Store a piece of data at specified path. This acts as an add / replace
  72      * operation, which is to say that whole subtree will be replaced by
  73      * specified path. Performing the following put operations:
  74      *
  75      * <pre>
  76      * 1) container { list [ a ] }
  77      * 2) container { list [ b ] }
  78      * </pre>
  79      *
  80      * will result in the following data being present:
  81      *
  82      * <pre>
  83      * container { list [ b ] }
  84      * </pre>
  85      *
  86      *
  87      * If you need to make sure that a parent object exists, but you do not want modify
  88      * its preexisting state by using put, consider using
  89      * {@link #merge(LogicalDatastoreType, Path, Object)}
  90      *
  91      * @param store
  92      *            Logical data store which should be modified
  93      * @param path
  94      *            Data object path
  95      * @param data
  96      *            Data object to be written to specified path
  97      * @throws IllegalStateException
  98      *             if the transaction is no longer {@link TransactionStatus#NEW}
  99      */
 100     public void put(LogicalDatastoreType store, P path, D data);
 101
 102     /**
 103      * Store a piece of data at the specified path. This acts as a merge operation,
 104      * which is to say that any pre-existing data which is not explicitly
 105      * overwritten will be preserved. This means that if you store a container,
 106      * its child lists will be merged. Performing the following merge
 107      * operations:
 108      *
 109      * <pre>
 110      * 1) container { list [ a ] }
 111      * 2) container { list [ b ] }
 112      * </pre>
 113      *
 114      * will result in the following data being present:
 115      *
 116      * <pre>
 117      * container { list [ a, b ] }
 118      * </pre>
 119      *
 120      * This also means that storing the container will preserve any
 121      * augmentations which have been attached to it.
 122      *<p>
 123      * If you require an explicit replace operation, use
 124      * {@link #put(LogicalDatastoreType, Path, Object)} instead.
 125      *
 126      * @param store
 127      *            Logical data store which should be modified
 128      * @param path
 129      *            Data object path
 130      * @param data
 131      *            Data object to be written to specified path
 132      * @throws IllegalStateException
 133      *             if the transaction is no longer {@link TransactionStatus#NEW}
 134      */
 135     public void merge(LogicalDatastoreType store, P path, D data);
 136
 137     /**
 138      * Remove a piece of data from specified path. This operation does not fail
 139      * if the specified path does not exist.
 140      *
 141      * @param store
 142      *            Logical data store which should be modified
 143      * @param path
 144      *            Data object path
 145      * @throws IllegalStateException
 146      *             if the transaction is no longer {@link TransactionStatus#NEW}
 147      */
 148     public void delete(LogicalDatastoreType store, P path);
 149
 150     /**
 151      * Submits transaction to be applied to update logical data tree.
 152      * <p>
 153      * This call logically seals the transaction, which prevents the client from
 154      * further changing data tree using this transaction. Any subsequent calls to
 155      * {@link #put(LogicalDatastoreType, Path, Object)},
 156      * {@link #merge(LogicalDatastoreType, Path, Object)} or
 157      * {@link #delete(LogicalDatastoreType, Path)} will fail with
 158      * {@link IllegalStateException}.
 159      *
 160      * The transaction is marked as {@link TransactionStatus#SUBMITED} and
 161      * enqueued into the data store backed for processing.
 162      *
 163      * <p>
 164      * Whether or not the commit is successful is determined by versioning
 165      * of data tree and validation of registered commit participants
 166      * {@link AsyncConfigurationCommitHandler}
 167      * if transaction changes {@link LogicalDatastoreType#CONFIGURATION} data tree.
 168      *<p>
 169      * The effects of successful commit of data depends on
 170      * other data change listeners {@link AsyncDataChangeListener} and
 171      * {@link AsyncConfigurationCommitHandler}, which was registered to the
 172      * same {@link AsyncDataBroker}, to which this transaction belongs.
 173      *
 174      * <h2>Failure scenarios</h2>
 175      * <p>
 176      * Transaction may fail because of multiple reasons, such as
 177      * <ul>
 178      * <li>Another transaction finished earlier and modified the same node in
 179      * non-compatible way (see below). In this case the returned future will fail with
 180      * {@link OptimisticLockFailedException}. It is the responsibility of the
 181      * caller to create a new transaction and submit the same modification again in
 182      * order to update data tree.</li>
 183      * <li>Data change introduced by this transaction did not pass validation by
 184      * commit handlers or data was incorrectly structured. Returned future will
 185      * fail with {@link DataValidationFailedException}. User should not retry to
 186      * create new transaction with same data, since it probably will fail again.
 187      * </li>
 188      * </ul>
 189      *
 190      * <h3>Change compatibility</h3>
 191      *
 192      * There are several sets of changes which could be considered incompatible
 193      * between two transactions which are derived from same initial state.
 194      * Rules for conflict detection applies recursively for each subtree
 195      * level.
 196      *
 197      * <h4>Change compatibility of leafs, leaf-list items</h4>
 198      *
 199      * Following table shows  state changes and failures between two concurrent transactions,
 200      * which are based on same initial state, Tx 1 completes successfully
 201      * before Tx 2 is submitted.
 202      *
 203      * <table>
 204      * <tr><th>Initial state</th><th>Tx 1</th><th>Tx 2</th><th>Result</th></tr>
 205      * <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>
 206      * <tr><td>Empty</td><td>put(A,1)</td><td>merge(A,2)</td><td>A=2</td></tr>
 207      *
 208      * <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>
 209      * <tr><td>Empty</td><td>merge(A,1)</td><td>merge(A,2)</td><td>A=2</td></tr>
 210      *
 211      *
 212      * <tr><td>A=0</td><td>put(A,1)</td><td>put(A,2)</td><td>Tx 2 will fail, A=1</td></tr>
 213      * <tr><td>A=0</td><td>put(A,1)</td><td>merge(A,2)</td><td>A=2</td></tr>
 214      * <tr><td>A=0</td><td>merge(A,1)</td><td>put(A,2)</td><td>Tx 2 will fail, A=1</td></tr>
 215      * <tr><td>A=0</td><td>merge(A,1)</td><td>merge(A,2)</td><td>A=2</td></tr>
 216      *
 217      * <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>
 218      * <tr><td>A=0</td><td>delete(A)</td><td>merge(A,2)</td><td>A=2</td></tr>
 219      * </table>
 220      *
 221      * <h4>Change compatibility of subtrees</h4>
 222      *
 223      * Following table shows  state changes and failures between two concurrent transactions,
 224      * which are based on same initial state, Tx 1 completes successfully
 225      * before Tx 2 is submitted.
 226      *
 227      * <table>
 228      * <tr><th>Initial state</th><th>Tx 1</th><th>Tx 2</th><th>Result</th></tr>
 229      *
 230      * <tr><td>Empty</td><td>put(TOP,[])</td><td>put(TOP,[])</td><td>Tx 2 will fail, state is TOP=[]</td></tr>
 231      * <tr><td>Empty</td><td>put(TOP,[])</td><td>merge(TOP,[])</td><td>TOP=[]</td></tr>
 232      *
 233      * <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>
 234      * <tr><td>Empty</td><td>put(TOP,[FOO=1])</td><td>merge(TOP,[BAR=1])</td><td>TOP=[FOO=1,BAR=1]</td></tr>
 235      *
 236      * <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>
 237      * <tr><td>Empty</td><td>merge(TOP,[FOO=1])</td><td>merge(TOP,[BAR=1])</td><td>TOP=[FOO=1,BAR=1]</td></tr>
 238      *
 239      * <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>
 240      * <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>
 241      * <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>
 242      * <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>
 243      * <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>
 244      * <tr><td>TOP=[]</td><td>delete(TOP)</td><td>merge(TOP,[BAR=1])</td><td>state is TOP=[BAR=1]</td></tr>
 245      *
 246      * <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>
 247      * <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>
 248      * <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>
 249      * <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>
 250      * <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>
 251      * <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>
 252      *
 253      * <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>
 254      * <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>
 255      * <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>
 256      * <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>
 257      * <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>
 258      * <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>
 259      * </table>
 260      *
 261      *
 262      * <h3>Examples of failure scenarios</h3>
 263      *
 264      * <h4>Conflict of two transactions</h4>
 265      *
 266      * This example illustrates two concurrent transactions, which derived from
 267      * same initial state of data tree and proposes conflicting modifications.
 268      *
 269      * <pre>
 270      * txA = broker.newWriteTransaction(); // allocates new transaction, data tree is empty
 271      * txB = broker.newWriteTransaction(); // allocates new transaction, data tree is empty
 272      *
 273      * txA.put(CONFIGURATION, PATH, A);    // writes to PATH value A
 274      * txB.put(CONFIGURATION, PATH, B)     // writes to PATH value B
 275      *
 276      * ListenableFuture futureA = txA.commit(); // transaction A is sealed and committed
 277      * ListenebleFuture futureB = txB.commit(); // transaction B is sealed and committed
 278      * </pre>
 279      *
 280      * Commit of transaction A will be processed asynchronously and data tree
 281      * will be updated to contain value <code>A</code> for <code>PATH</code>.
 282      * Returned {@link ListenableFuture} will successfully complete once
 283      * state is applied to data tree.
 284      *
 285      * Commit of Transaction B will fail, because previous transaction also
 286      * modified path in a concurrent way. The state introduced by transaction B
 287      * will not be applied. Returned {@link ListenableFuture} object will fail
 288      * with {@link OptimisticLockFailedException} exception, which indicates to
 289      * client that concurrent transaction prevented the submitted transaction from being
 290      * applied.
 291      *
 292      * @return Result of the Commit, containing success information or list of
 293      *         encountered errors, if commit was not successful. The Future
 294      *         blocks until {@link TransactionStatus#COMMITED} is reached.
 295      *         Future will fail with {@link TransactionCommitFailedException} if
 296      *         Commit of this transaction failed. TODO: Usability: Consider
 297      *         change from ListenableFuture to
 298      *         {@link com.google.common.util.concurrent.CheckedFuture} which
 299      *         will throw {@link TransactionCommitFailedException}.
 300      *
 301      * @throws IllegalStateException
 302      *             if the transaction is not {@link TransactionStatus#NEW}
 303      */
 304     public ListenableFuture<RpcResult<TransactionStatus>> commit();
 305
 306 }