Bug 1081 - Deprecate non-asynchronous Data Broker API
[controller.git] / opendaylight / md-sal / sal-common-api / src / main / java / org / opendaylight / controller / md / sal / common / api / data / DataCommitHandler.java
1 /*
2  * Copyright (c) 2013 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 import org.opendaylight.yangtools.yang.common.RpcResult;
12 /**
13  * Two phase commit handler (cohort) of the two-phase commit protocol of data.
14  *
15  * <p>
16  * The provider should expose the implementation of DataCommitHandler if it's
17  * functionality depends on any subset of data stored in data repositories, in
18  * order to participate in {@link DataBrokerService#commit(DataStoreIdentifier)
19  * operation.
20  *
21  * <p>
22  * Operations of two-phase commit handlers should not change data in data store,
23  * this is responsibility of the coordinator (broker or some component of the
24  * broker).
25  *
26  * Commit handlers are responsible for changing the internal state of the
27  * provider to reflect the committed changes in data.
28  *
29  * <h3>Two-phase commit</h3>
30  *
31  * <h4>Commit Request Phase</h4>
32  *
33  * <ol>
34  * <li> <code>Consumer</code> edits data by invocation of
35  * <code>DataBrokerService.editCandidateData(DataStoreIdentifier, DataRoot)</code>
36  * <li> <code>Consumer</code> starts a commit by invoking
37  * <code>DataBrokerService.commit(DataStoreIdentifier)</code>
38  * <li> <code>Broker</code> retrieves a list of all registered
39  * <code>DataCommitHandlers</code>
40  * <li>For each <code>DataCommitHandler</code>
41  * <ol>
42  * <li><code>Broker</code> invokes a
43  * <code>DataCommitHandler.requestCommit(DataStoreIdentifier)</code> operation.
44  * <li><code>DataCommitHandler</code> returns a <code>RpcResult</code> with
45  * <code>CommitTransaction</code>
46  * <li>If the result was successful, broker adds <code>CommitTransaction</code>
47  * to the list of opened transactions. If not, brokers stops a commit request
48  * phase and starts a rollback phase.
49  * </ol>
50  * <li><code>Broker</code> starts a commit finish phase
51  * </ol>
52  *
53  * <h4>Commit Finish Phase</h4>
54  *
55  * <ol>
56  * <li>For each <code>CommitTransaction</code> from Commit Request phase
57  * <ol>
58  * <li><code>Broker</code> broker invokes a
59  * <code>CommitTransaction.finish()</code>
60  * <li>The provider finishes a commit (applies the change) and returns an
61  * <code>RpcResult</code>.
62  * </ol>
63  * <li>
64  * <ul>
65  * <li>If all returned results means successful, the brokers end two-phase
66  * commit by returning a success commit result to the Consumer.
67  * <li>If error occured, the broker starts a commit rollback phase.
68  * </ul>
69  * </ol>
70  *
71  * <h4>Commit Rollback Phase</h4>
72  * <li>For each <code>DataCommitTransaction</code> from Commit Request phase
73  * <ol>
74  * <li><code>Broker</code>
75  * broker invokes a {@link DataCommitTransaction#finish()}
76  * <li>The provider rollbacks a commit and returns an {@link RpcResult} of
77  * rollback. </ol>
78  * <li>Broker returns a error result to the consumer.
79  *
80  * @param <P> Class representing a path
81  * @param <D> Superclass from which all data objects are derived from.
82  * @deprecated Replaced by {@link AsyncConfigurationCommitHandler}
83  */
84 @Deprecated
85 public interface DataCommitHandler<P extends Path<P>, D> {
86
87
88     DataCommitTransaction<P, D> requestCommit(DataModification<P,D> modification);
89
90     public interface DataCommitTransaction<P extends Path<P>, D> {
91
92         DataModification<P,D> getModification();
93
94         /**
95          *
96          * Finishes a commit.
97          *
98          * This callback is invoked by commit coordinator to finish commit action.
99          *
100          * The implementation is required to finish transaction or return unsuccessful
101          * rpc result if something went wrong.
102          *
103          * The provider (commit handler) should apply all changes to its state
104          * which are a result of data change-
105          *
106          * @return
107          */
108         RpcResult<Void> finish() throws IllegalStateException;
109
110         /**
111          * Rollbacks a commit.
112          *
113          * This callback is invoked by commit coordinator to finish commit action.
114          *
115          * The provider (commit handler) should rollback all changes to its state
116          * which were a result of previous request commit.
117          *
118          * @return
119          * @throws IllegalStateException
120          *             If the method is invoked after {@link #finish()}
121          */
122         RpcResult<Void> rollback() throws IllegalStateException;
123     }
124
125 }

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