b966589afde579f48efc6d87efa14ed89ab1052c
[controller.git] / opendaylight / md-sal / sal-common-api / src / main / java / org / opendaylight / controller / md / sal / common / api / data / AsyncConfigurationCommitHandler.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.yangtools.concepts.Path;
11
12 import com.google.common.util.concurrent.CheckedFuture;
13
14 /**
15  * User-supplied participant in three-phase commit of transaction for configuration data tree
16  *
17  * Client-supplied implementation of commit handler for subtree, which
18  * is responsible for processing CAN-COMMIT phase of three-phase commit protocol
19  * and return CommitCohort, which provides access to additional transitions
20  * such as PRE-COMMIT, COMMIT and ABORT.
21  *
22  * @param <P>
23  *            Type of path (subtree identifier), which represents location in
24  *            tree
25  * @param <D>
26  *            Type of data (payload), which represents data payload
27  */
28 public interface AsyncConfigurationCommitHandler<P extends Path<P>, D> {
29
30     /**
31      *
32      * Requests a can commit phase
33      *
34      * Implementations SHOULD NOT do any blocking operation during
35      * processing this callback.
36      *
37      * <b>Implementation Notes</b>
38      * <ul>
39      * <li>Implementation are REQUIRED to use <code>request</code> object for any data related access</li>
40      * <li>Implementations SHOULD NOT use any other state stored outside configuration subtree for validation</li>
41      * <li>Validation should happen asynchronously, outside callback call by updating returned {@link CheckedFuture}
42      *     object.</li>
43      * <li>If validation (CAN_COMMIT) phase:
44      * <ul>
45      * <li><b>is successful</b> - invocation of {@link CheckedFuture#checkedGet()} on returned future MUST
46      *     return {@link AsyncConfigurationCommitCohort} associated with request.</li>
47      * <li><b>is unsuccessful</b> - invocation of {@link CheckedFuture#checkedGet()} must throw instance of {@link DataValidationFailedException}
48      * with human readable explanaition of error condition.
49      * </li>
50      * </ul>
51      * </li>
52      * </ul>
53      * @param request
54      *            Commit Request submitted by client, which contains
55      *            information about modifications and read-only view as
56      *            if transaction happened.
57      * @return CheckedFuture which contains client-supplied implementation of {@link AsyncConfigurationCommitCohort}
58      *         associated with submitted request, if can commit phase is
59      *         successful, if can commit was unsuccessful, future must fail with
60      *         {@link TransactionCommitFailedException} exception.
61      */
62     CheckedFuture<AsyncConfigurationCommitCohort<P, D>, DataValidationFailedException> canCommit(
63             ConfigurationCommitRequest<P, D> request);
64
65     /**
66      *
67      * Commit Request as was submitted by client code
68      *
69      * Commit Request contains list view of created / updated / removed
70      * path and read-only view of proposed client transaction,
71      * which may be used to retrieve modified or referenced data.
72      *
73      *
74      * @param <P>
75      *            Type of path (subtree identifier), which represents location
76      *            in tree
77      * @param <D>
78      *            Type of data (payload), which represents data payload
79      */
80     interface ConfigurationCommitRequest<P extends Path<P>, D> {
81
82         /**
83          *
84          * Read-only transaction which provides access only to configuration
85          * data tree as if submitted transaction successfully happened and
86          * no other concurrent modifications happened between allocation
87          * of client transactions and write of client transactions.
88          *
89          * Implementations of Commit Handlers are REQUIRED to use this
90          * read-only view to access any data from configuration data tree,
91          * in order to capture them as preconditions for this transaction.
92          *
93          * @return Read-only transaction which provides access only to configuration
94          * data tree as if submitted transaction successfully happened
95          */
96         AsyncReadTransaction<P, D> getReadOnlyView();
97
98         /**
99          *
100          * Returns iteration of paths, to data which was introduced by this transaction.
101          *
102          * @return Iteration of paths, which was introduced by this transaction.
103          */
104         Iterable<P> getCreatedPaths();
105         /**
106          *
107          * Returns iteration of paths, to data which was updated by this transaction.
108          *
109          * @return Iteration of paths, which was updated by this transaction.
110          */
111         Iterable<P> getUpdatedPaths();
112
113         /**
114          *
115          * Returns iteration of paths, to data which was removed by this transaction.
116          *
117          * @return Iteration of paths, which was removed by this transaction.
118          */
119         Iterable<P> getRemovedPaths();
120     }
121
122 }

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