/* * 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.controller.md.sal.common.api.data; import org.opendaylight.controller.md.sal.common.api.TransactionStatus; import org.opendaylight.yangtools.concepts.Path; import org.opendaylight.yangtools.yang.common.RpcResult; import com.google.common.util.concurrent.ListenableFuture; /** * 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 publish the changes proposed in the transaction by calling {@link #commit} * 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 #commit()} 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's status is
* {@link TransactionStatus#NEW} or {@link TransactionStatus#SUBMITED}
*
* Invoking cancel() on {@link TransactionStatus#FAILED} or
* {@link TransactionStatus#CANCELED} will have no effect, and transaction
* is considered cancelled.
*
* Invoking cancel() on finished transaction (future returned by {@link #commit()}
* already completed with {@link TransactionStatus#COMMITED}) will always
* fail (return false).
*
* @return false if the task could not be cancelled,
* typically because it has already completed normally;
* true otherwise
*
*/
public boolean cancel();
/**
* Store a piece of data at specified path. This acts as an add / replace
* operation, which is to say that whole subtree will be replaced by
* specified path. Performing the following put operations:
*
*
* If you require an explicit replace operation, use
* {@link #put(LogicalDatastoreType, Path, Object)} instead.
*
* @param store
* Logical data store which should be modified
* @param path
* Data object path
* @param data
* Data object to be written to specified path
* @throws IllegalStateException
* if the transaction is no longer {@link TransactionStatus#NEW}
*/
public void merge(LogicalDatastoreType store, P path, D data);
/**
* Remove 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 is no longer {@link TransactionStatus#NEW}
*/
public void delete(LogicalDatastoreType store, P path);
/**
* Submits transaction to be applied to update logical data tree.
*
* This call logically seals the transaction, which prevents the client from
* further changing data tree using this transaction. Any subsequent calls to
* {@link #put(LogicalDatastoreType, Path, Object)},
* {@link #merge(LogicalDatastoreType, Path, Object)} or
* {@link #delete(LogicalDatastoreType, Path)} will fail with
* {@link IllegalStateException}.
*
* The transaction is marked as {@link TransactionStatus#SUBMITED} and
* enqueued into the data store backed for processing.
*
*
* Whether or not the commit is successful is determined by versioning
* of data tree and validation of registered commit participants
* {@link AsyncConfigurationCommitHandler}
* if transaction changes {@link LogicalDatastoreType#CONFIGURATION} data tree.
*
* The effects of successful commit of data depends on
* other data change listeners {@link AsyncDataChangeListener} and
* {@link AsyncConfigurationCommitHandler}, which was registered to the
* same {@link AsyncDataBroker}, to which this transaction belongs.
*
*
* Transaction may fail because of multiple reasons, such as
*
* 1) container { list [ a ] }
* 2) container { list [ b ] }
*
*
* will result in the following data being present:
*
*
* container { list [ b ] }
*
*
*
* If you need to make sure that a parent object exists, but you do not want modify
* its preexisting state by using put, consider using
* {@link #merge(LogicalDatastoreType, Path, Object)}
*
* @param store
* Logical data store which should be modified
* @param path
* Data object path
* @param data
* Data object to be written to specified path
* @throws IllegalStateException
* if the transaction is no longer {@link TransactionStatus#NEW}
*/
public void put(LogicalDatastoreType store, P path, D data);
/**
* Store a piece of data at the specified path. This acts as a merge operation,
* which is to say that any pre-existing data which is not explicitly
* overwritten will be preserved. This means that if you store a container,
* its child lists will be merged. 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.
*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.commit(); // transaction A is sealed and committed
* ListenebleFuture futureB = txB.commit(); // transaction B is sealed and committed
*
*
* 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.
*
* @return Result of the Commit, containing success information or list of
* encountered errors, if commit was not successful. The Future
* blocks until {@link TransactionStatus#COMMITED} is reached.
* Future will fail with {@link TransactionCommitFailedException} if
* Commit of this transaction failed. TODO: Usability: Consider
* change from ListenableFuture to
* {@link com.google.common.util.concurrent.CheckedFuture} which
* will throw {@link TransactionCommitFailedException}.
*
* @throws IllegalStateException
* if the transaction is not {@link TransactionStatus#NEW}
*/
public ListenableFuture