2 * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
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
8 package org.opendaylight.controller.md.sal.common.api.data;
10 import java.util.concurrent.Future;
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;
16 public interface AsyncWriteTransaction<P extends Path<P>, D> extends AsyncTransaction<P, D> {
18 * Cancels transaction.
20 * Transaction could be only cancelled if it's status
21 * is {@link TransactionStatus#NEW} or {@link TransactionStatus#SUBMITED}
23 * Invoking cancel() on {@link TransactionStatus#FAILED} or {@link TransactionStatus#CANCELED}
24 * will have no effect.
26 * @throws IllegalStateException If transaction status is {@link TransactionStatus#COMMITED}
32 * Store a piece of data at specified path. This acts as a add / replace operation,
33 * which is to say that whole subtree will be replaced by specified path.
35 * If you need add or merge of current object with specified use {@link #merge(LogicalDatastoreType, Path, Object)}
37 * @param store Logical data store which should be modified
38 * @param path Data object path
39 * @param data Data object to be written to specified path
40 * @throws IllegalStateException if the transaction is no longer {@link TransactionStatus#NEW}
42 public void put(LogicalDatastoreType store, P path, D data);
45 * Store a piece of data at specified path. This acts as a merge operation,
46 * which is to say that any pre-existing data which is not explicitly
47 * overwritten will be preserved. This means that if you store a container,
48 * its child lists will be merged. Performing the following put operations:
50 * 1) container { list [ a ] }
51 * 2) container { list [ b ] }
53 * will result in the following data being present:
55 * container { list [ a, b ] }
57 * This also means that storing the container will preserve any augmentations
58 * which have been attached to it.
60 * If you require an explicit replace operation, use {@link #put(LogicalDatastoreType, Path, Object)} instead.
62 * @param store Logical data store which should be modified
63 * @param path Data object path
64 * @param data Data object to be written to specified path
65 * @throws IllegalStateException if the transaction is no longer {@link TransactionStatus#NEW}
67 public void merge(LogicalDatastoreType store, P path, D data);
70 * Remove a piece of data from specified path. This operation does not fail
71 * if the specified path does not exist.
73 * @param store Logical data store which should be modified
74 * @param path Data object path
75 * @throws IllegalStateException if the transaction is no longer {@link TransactionStatus#NEW}
77 public void delete(LogicalDatastoreType store, P path);
81 * Closes transaction and resources allocated to the transaction.
83 * This call does not change Transaction status. Client SHOULD
84 * explicitly {@link #commit()} or {@link #cancel()} transaction.
86 * @throws IllegalStateException if the transaction has not been
87 * updated by invoking {@link #commit()} or {@link #cancel()}.
93 * Initiates a commit of modification. This call logically seals the
94 * transaction, preventing any the client from interacting with the
95 * data stores. The transaction is marked as {@link TransactionStatus#SUBMITED}
96 * and enqueued into the data store backed for processing.
99 * The successful commit changes the state of the system and may affect
100 * several components.
103 * The effects of successful commit of data are described in the
104 * specifications and YANG models describing the Provider components of
105 * controller. It is assumed that Consumer has an understanding of this
108 * @see DataCommitHandler for further information how two-phase commit is
110 * @param store Identifier of the store, where commit should occur.
111 * @return Result of the Commit, containing success information or list of
112 * encountered errors, if commit was not successful. The Future
113 * blocks until {@link TransactionStatus#COMMITED} or
114 * {@link TransactionStatus#FAILED} is reached.
115 * @throws IllegalStateException if the transaction is not {@link TransactionStatus#NEW}
117 public Future<RpcResult<TransactionStatus>> commit();