Bug 500: Updated data APIs with new concepts.
[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 java.util.concurrent.Future;
11
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 public interface AsyncWriteTransaction<P extends Path<P>, D>  extends AsyncTransaction<P, D> {
17     /**
18      * Cancels transaction.
19      *
20      * Transaction could be only cancelled if it's status
21      * is {@link TransactionStatus#NEW} or {@link TransactionStatus#SUBMITED}
22      *
23      * Invoking cancel() on {@link TransactionStatus#FAILED} or {@link TransactionStatus#CANCELED}
24      * will have no effect.
25      *
26      * @throws IllegalStateException If transaction status is {@link TransactionStatus#COMMITED}
27      *
28      */
29     public void cancel();
30
31     /**
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.
34      *
35      * If you need add or merge of current object with specified use {@link #merge(LogicalDatastoreType, Path, Object)}
36      *
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}
41      */
42     public void put(LogicalDatastoreType store, P path, D data);
43
44     /**
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:
49      *
50      * 1) container { list [ a ] }
51      * 2) container { list [ b ] }
52      *
53      * will result in the following data being present:
54      *
55      * container { list [ a, b ] }
56      *
57      * This also means that storing the container will preserve any augmentations
58      * which have been attached to it.
59      *
60      * If you require an explicit replace operation, use {@link #put(LogicalDatastoreType, Path, Object)} instead.
61      *
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}
66      */
67     public void merge(LogicalDatastoreType store, P path, D data);
68
69     /**
70      * Remove a piece of data from specified path. This operation does not fail
71      * if the specified path does not exist.
72      *
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}
76      */
77     public void delete(LogicalDatastoreType store, P path);
78
79     /**
80      *
81      * Closes transaction and resources allocated to the transaction.
82      *
83      * This call does not change Transaction status. Client SHOULD
84      * explicitly {@link #commit()} or {@link #cancel()} transaction.
85      *
86      * @throws IllegalStateException if the transaction has not been
87      *         updated by invoking {@link #commit()} or {@link #cancel()}.
88      */
89     @Override
90     public void close();
91
92     /**
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.
97      *
98      * <p>
99      * The successful commit changes the state of the system and may affect
100      * several components.
101      *
102      * <p>
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
106      * changes.
107      *
108      * @see DataCommitHandler for further information how two-phase commit is
109      *      processed.
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}
116      */
117     public Future<RpcResult<TransactionStatus>> commit();
118
119 }

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