/* * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved. * * This program and the accompanying materials are made available under the * terms of the Eclipse Public License v1.0 which accompanies this distribution, * and is available at http://www.eclipse.org/legal/epl-v10.html */ package org.opendaylight.mdsal.common.api; import com.google.common.util.concurrent.CheckedFuture; import com.google.common.util.concurrent.FluentFuture; import com.google.common.util.concurrent.ListenableFuture; import com.google.common.util.concurrent.MoreExecutors; import javax.annotation.CheckReturnValue; import org.eclipse.jdt.annotation.NonNull; import org.opendaylight.yangtools.concepts.Path; import org.opendaylight.yangtools.util.concurrent.ExceptionMapper; /** * Write transaction provides mutation capabilities for a data tree. * *
* Initial state of write transaction is a stable snapshot of the current data tree. * The state is captured when the transaction is created and its state and underlying * data tree are not affected by other concurrently running transactions. * *
* Write transactions are isolated from other concurrent write transactions. All * writes are local to the transaction and represent only a proposal of state * change for the data tree and it is not visible to any other concurrently running * transaction. * *
* Applications make changes to the local data tree in the transaction by via the * put, merge, and delete operations. * *
* Performing the following put operations: * *
* 1) container { list [ a ] } * 2) container { list [ b ] } ** will result in the following data being present: * *
* container { list [ b ] } **
* Performing the following merge operations: * *
* 1) container { list [ a ] } * 2) container { list [ b ] } ** will result in the following data being present: * *
* container { list [ a, b ] } ** This also means that storing the container will preserve any * augmentations which have been attached to it. * *
* After applying changes to the local data tree, applications publish the changes proposed in the * transaction by calling {@link #submit} on the transaction. This seals the transaction * (preventing any further writes using this transaction) and submits it to be * processed and applied to global conceptual data tree. * *
* The transaction commit may fail due to a concurrent transaction modifying and committing data in * an incompatible way. See {@link #submit} for more concrete commit failure examples. * *
* Implementation Note: This interface is not intended to be implemented * by users of MD-SAL, but only to be consumed by them. * * @param
* Type of path (subtree identifier), which represents location in
* tree
* @param , D> extends AsyncTransaction {
/**
* Cancels the transaction.
* Transactions can only be cancelled if it was not yet submited.
* Invoking cancel() on failed or already canceled will have no effect, and transaction is
* considered cancelled.
* Invoking cancel() on finished transaction (future returned by {@link #submit()} already
* successfully completed) will always fail (return false).
*
* @return false if the task could not be cancelled, typically because it has already
* completed normally; true otherwise
*
*/
boolean cancel();
/**
* Removes a piece of data from specified path. This operation does not fail if the specified
* path does not exist.
*
* @param store Logical data store which should be modified
* @param path Data object path
* @throws IllegalStateException if the transaction was submitted or canceled.
*/
void delete(LogicalDatastoreType store, P path);
/**
* Submits this transaction to be asynchronously applied to update the logical data tree. The
* returned CheckedFuture conveys the result of applying the data changes.
*
* @return a CheckFuture containing the result of the commit. The Future blocks until the commit
* operation is complete. A successful commit returns nothing. On failure, the Future
* will fail with a {@link TransactionCommitFailedException} or an exception derived
* from TransactionCommitFailedException.
* @throws IllegalStateException if the transaction is already submitted or was canceled.
* @deprecated Use {@link #commit()} instead.
*/
@Deprecated
@CheckReturnValue
default CheckedFuture
* This call logically seals the transaction, which prevents the client from further changing the data tree using
* this transaction. Any subsequent calls to
* Whether or not the commit is successful is determined by versioning of the data tree and validation of registered
* commit participants if the transaction changes the data tree.
*
*
* The effects of a successful commit of data depends on listeners and commit participants that are registered with
* the data broker.
*
*
*
* Transaction may fail because of multiple reasons, such as
*
* A successful commit produces implementation-specific {@link CommitInfo} structure, which is used to communicate
* post-condition information to the caller. Such information can contain commit-id, timing information or any
* other information the implementation wishes to share.
*
* @return a FluentFuture containing the result of the commit information. The Future blocks until the commit
* operation is complete. A successful commit returns nothing. On failure, the Future will fail with a
* {@link TransactionCommitFailedException} or an exception derived from TransactionCommitFailedException.
* @throws IllegalStateException if the transaction is already submitted or was canceled.
*/
@CheckReturnValue
@NonNull FluentFuture extends @NonNull CommitInfo> commit();
/**
* This only exists for reuse by the deprecated {@link #submit} method and is not intended for general use.
*/
@Deprecated
ExceptionMapperput(LogicalDatastoreType, Path, Object)
,
* merge(LogicalDatastoreType, Path, Object)
, delete(LogicalDatastoreType, Path)
will fail
* with {@link IllegalStateException}. The transaction is marked as submitted and enqueued into the data store
* back-end for processing.
*
* Example usage:
*
* private void doWrite(final int tries) {
* WriteTransaction writeTx = dataBroker.newWriteOnlyTransaction();
* MyDataObject data = ...;
* InstanceIdentifier<MyDataObject> path = ...;
* writeTx.put(LogicalDatastoreType.OPERATIONAL, path, data);
* Futures.addCallback(writeTx.submit(), new FutureCallback<Void>() {
* public void onSuccess(Void result) {
* // succeeded
* }
* public void onFailure(Throwable t) {
* if(t instanceof OptimisticLockFailedException) {
* if(( tries - 1) > 0 ) {
* // do retry
* doWrite(tries - 1);
* } else {
* // out of retries
* }
* } else {
* // failed due to another type of TransactionCommitFailedException.
* }
* });
* }
* ...
* doWrite(2);
*
*
* Failure scenarios
*
*
*
*
* Change compatibility
* There are several sets of changes which could be considered incompatible between two transactions which are
* derived from same initial state. Rules for conflict detection applies recursively for each subtree level.
*
* Change compatibility of leafs, leaf-list items
* Following table shows state changes and failures between two concurrent transactions, which are based on same
* initial state, Tx 1 completes successfully before Tx 2 is submitted.
*
*
*
*
*
*
* Initial state
* Tx 1
* Tx 2
* Result
*
*
* Empty
* put(A,1)
* put(A,2)
* Tx 2 will fail, state is A=1
*
*
*
* Empty
* put(A,1)
* merge(A,2)
* A=2
*
*
* Empty
* merge(A,1)
* put(A,2)
* Tx 2 will fail, state is A=1
*
*
*
*
* Empty
* merge(A,1)
* merge(A,2)
* A=2
*
*
* A=0
* put(A,1)
* put(A,2)
* Tx 2 will fail, A=1
*
*
* A=0
* put(A,1)
* merge(A,2)
* A=2
*
*
* A=0
* merge(A,1)
* put(A,2)
* Tx 2 will fail, A=1
*
*
*
* A=0
* merge(A,1)
* merge(A,2)
* A=2
*
*
* A=0
* delete(A)
* put(A,2)
* Tx 2 will fail, A does not exists
*
*
* A=0
* delete(A)
* merge(A,2)
* A=2
* Change compatibility of subtrees
* Following table shows state changes and failures between two concurrent transactions, which are based on same
* initial state, Tx 1 completes successfully before Tx 2 is submitted.
*
*
*
*
*
*
*
*
* Initial state
* Tx 1
* Tx 2
* Result
*
*
* Empty
* put(TOP,[])
* put(TOP,[])
* Tx 2 will fail, state is TOP=[]
*
*
*
* Empty
* put(TOP,[])
* merge(TOP,[])
* TOP=[]
*
*
* Empty
* put(TOP,[FOO=1])
* put(TOP,[BAR=1])
* Tx 2 will fail, state is TOP=[FOO=1]
*
*
*
* Empty
* put(TOP,[FOO=1])
* merge(TOP,[BAR=1])
* TOP=[FOO=1,BAR=1]
*
*
* Empty
* merge(TOP,[FOO=1])
* put(TOP,[BAR=1])
* Tx 2 will fail, state is TOP=[FOO=1]
*
*
*
* Empty
* merge(TOP,[FOO=1])
* merge(TOP,[BAR=1])
* TOP=[FOO=1,BAR=1]
*
*
* TOP=[]
* put(TOP,[FOO=1])
* put(TOP,[BAR=1])
* Tx 2 will fail, state is TOP=[FOO=1]
*
*
* TOP=[]
* put(TOP,[FOO=1])
* merge(TOP,[BAR=1])
* state is TOP=[FOO=1,BAR=1]
*
*
* TOP=[]
* merge(TOP,[FOO=1])
* put(TOP,[BAR=1])
* Tx 2 will fail, state is TOP=[FOO=1]
*
*
* TOP=[]
* merge(TOP,[FOO=1])
* merge(TOP,[BAR=1])
* state is TOP=[FOO=1,BAR=1]
*
*
* TOP=[]
* delete(TOP)
* put(TOP,[BAR=1])
* Tx 2 will fail, state is empty store
*
*
*
* TOP=[]
* delete(TOP)
* merge(TOP,[BAR=1])
* state is TOP=[BAR=1]
*
*
* TOP=[]
* put(TOP/FOO,1)
* put(TOP/BAR,1])
* state is TOP=[FOO=1,BAR=1]
*
*
* TOP=[]
* put(TOP/FOO,1)
* merge(TOP/BAR,1)
* state is TOP=[FOO=1,BAR=1]
*
*
* TOP=[]
* merge(TOP/FOO,1)
* put(TOP/BAR,1)
* state is TOP=[FOO=1,BAR=1]
*
*
* TOP=[]
* merge(TOP/FOO,1)
* merge(TOP/BAR,1)
* state is TOP=[FOO=1,BAR=1]
*
*
* TOP=[]
* delete(TOP)
* put(TOP/BAR,1)
* Tx 2 will fail, state is empty store
*
*
*
* TOP=[]
* delete(TOP)
* merge(TOP/BAR,1]
* Tx 2 will fail, state is empty store
*
*
* TOP=[FOO=1]
* put(TOP/FOO,2)
* put(TOP/BAR,1)
* state is TOP=[FOO=2,BAR=1]
*
*
* TOP=[FOO=1]
* put(TOP/FOO,2)
* merge(TOP/BAR,1)
* state is TOP=[FOO=2,BAR=1]
*
*
* TOP=[FOO=1]
* merge(TOP/FOO,2)
* put(TOP/BAR,1)
* state is TOP=[FOO=2,BAR=1]
*
*
* TOP=[FOO=1]
* merge(TOP/FOO,2)
* merge(TOP/BAR,1)
* state is TOP=[FOO=2,BAR=1]
*
*
* TOP=[FOO=1]
* delete(TOP/FOO)
* put(TOP/BAR,1)
* state is TOP=[BAR=1]
*
*
* TOP=[FOO=1]
* delete(TOP/FOO)
* merge(TOP/BAR,1]
* state is TOP=[BAR=1]
* Examples of failure scenarios
*
* Conflict of two transactions
* This example illustrates two concurrent transactions, which derived from same initial state
* of data tree and proposes conflicting modifications.
*
*
* txA = broker.newWriteTransaction(); // allocates new transaction, data tree is empty
* txB = broker.newWriteTransaction(); // allocates new transaction, data tree is empty
* txA.put(CONFIGURATION, PATH, A); // writes to PATH value A
* txB.put(CONFIGURATION, PATH, B) // writes to PATH value B
* ListenableFuture futureA = txA.submit(); // transaction A is sealed and submitted
* ListenebleFuture futureB = txB.submit(); // transaction B is sealed and submitted
*
* Commit of transaction A will be processed asynchronously and data tree will be updated to
* contain value A
for PATH
. Returned {@link ListenableFuture} will
* successfully complete once state is applied to data tree.
* Commit of Transaction B will fail, because previous transaction also modified path in a
* concurrent way. The state introduced by transaction B will not be applied. Returned
* {@link ListenableFuture} object will fail with {@link OptimisticLockFailedException}
* exception, which indicates to client that concurrent transaction prevented the submitted
* transaction from being applied.
*
*