Fix checkstyle violations in sal-common-api
[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 com.google.common.util.concurrent.CheckedFuture;
11 import org.opendaylight.yangtools.concepts.Path;
12
13 /**
14  * User-supplied participant in three-phase commit of transaction for configuration data tree.
15  *
16  * <p>
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      * Requests a can commit phase
32      *
33      * <p>
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
48      *     of {@link DataValidationFailedException}
49      * with human readable explanaition of error condition.
50      * </li>
51      * </ul>
52      * </li>
53      * </ul>
54      * @param request
55      *            Commit Request submitted by client, which contains
56      *            information about modifications and read-only view as
57      *            if transaction happened.
58      * @return CheckedFuture which contains client-supplied implementation of {@link AsyncConfigurationCommitCohort}
59      *         associated with submitted request, if can commit phase is
60      *         successful, if can commit was unsuccessful, future must fail with
61      *         {@link TransactionCommitFailedException} exception.
62      */
63     CheckedFuture<AsyncConfigurationCommitCohort<P, D>, DataValidationFailedException> canCommit(
64             ConfigurationCommitRequest<P, D> request);
65
66     /**
67      * Commit Request as was submitted by client code
68      *
69      * <p>
70      * Commit Request contains list view of created / updated / removed
71      * path and read-only view of proposed client transaction,
72      * which may be used to retrieve modified or referenced data.
73      *
74      *
75      * @param <P>
76      *            Type of path (subtree identifier), which represents location
77      *            in tree
78      * @param <D>
79      *            Type of data (payload), which represents data payload
80      */
81     interface ConfigurationCommitRequest<P extends Path<P>, D> {
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          * <p>
90          * Implementations of Commit Handlers are REQUIRED to use this
91          * read-only view to access any data from configuration data tree,
92          * in order to capture them as preconditions for this transaction.
93          *
94          * @return Read-only transaction which provides access only to configuration
95          *     data tree as if submitted transaction successfully happened
96          */
97         AsyncReadTransaction<P, D> getReadOnlyView();
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          * Returns iteration of paths, to data which was removed by this transaction.
115          *
116          * @return Iteration of paths, which was removed by this transaction.
117          */
118         Iterable<P> getRemovedPaths();
119     }
120
121 }

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