2 * Copyright (c) 2013 Cisco Systems, Inc. and others. All rights reserved.
\r
4 * This program and the accompanying materials are made available under the
\r
5 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
\r
6 * and is available at http://www.eclipse.org/legal/epl-v10.html
\r
8 package org.opendaylight.controller.sal.binding.api;
\r
10 import java.util.Set;
\r
12 import org.opendaylight.controller.sal.binding.api.BindingAwareProvider.ProviderFunctionality;
\r
13 import org.opendaylight.controller.sal.common.DataStoreIdentifier;
\r
14 import org.opendaylight.controller.yang.common.RpcResult;
\r
18 * Two phase commit handler (cohort) of the two-phase commit protocol of data.
\r
21 * The provider should expose the implementation of DataCommitHandler if it's
\r
22 * functionality depends on any subset of data stored in data repositories, in
\r
23 * order to participate in {@link DataBrokerService#commit(DataStoreIdentifier)
\r
27 * Operations of two-phase commit handlers should not change data in data store,
\r
28 * this is responsibility of the coordinator (broker or some component of the
\r
31 * The commit handlers are responsible for changing the internal state of the
\r
32 * provider to reflect the commited changes in data.
\r
34 * <h3>Two-phase commit</h3>
\r
36 * <h4>Commit Request Phase</h4>
\r
39 * <li> <code>Consumer</code> edits data by invocation of
\r
40 * <code>DataBrokerService.editCandidateData(DataStoreIdentifier, DataRoot)</code>
\r
41 * <li> <code>Consumer</code> starts a commit by invoking
\r
42 * <code>DataBrokerService.commit(DataStoreIdentifier)</code>
\r
43 * <li> <code>Broker</code> retrieves a list of all registered
\r
44 * <code>DataCommitHandlers</code>
\r
45 * <li>For each <code>DataCommitHandler</code>
\r
47 * <li><code>Broker</code> invokes a
\r
48 * <code>DataCommitHandler.requestCommit(DataStoreIdentifier)</code> operation.
\r
49 * <li><code>DataCommitHandler</code> returns a <code>RpcResult</code> with
\r
50 * <code>CommitTransaction</code>
\r
51 * <li>If the result was successful, broker adds <code>CommitTransaction</code>
\r
52 * to the list of opened transactions. If not, brokers stops a commit request
\r
53 * phase and starts a rollback phase.
\r
55 * <li><code>Broker</code> starts a commit finish phase
\r
58 * <h4>Commit Finish Phase</h4>
\r
61 * <li>For each <code>CommitTransaction</code> from Commit Request phase
\r
63 * <li><code>Broker</code> broker invokes a
\r
64 * <code>CommitTransaction.finish()</code>
\r
65 * <li>The provider finishes a commit (applies the change) and returns an
\r
66 * <code>RpcResult</code>.
\r
70 * <li>If all returned results means successful, the brokers end two-phase
\r
71 * commit by returning a success commit result to the Consumer.
\r
72 * <li>If error occured, the broker starts a commit rollback phase.
\r
76 * <h4>Commit Rollback Phase</h4>
\r
77 * <li>For each <code>CommitTransaction</code> from Commit Request phase
\r
79 * <li><code>Broker</code>
\r
125 * broker invokes a {@link CommitTransaction#finish()}
\r
126 * <li>The provider rollbacks a commit and returns an {@link RpcResult} of
\r
128 * <li>Broker returns a error result to the consumer.
\r
131 * <h3>Registration of functionality</h3>
\r
132 * The registration could be done by :
\r
134 * <li>returning an instance of implementation in the return value of
\r
135 * {@link Provider#getProviderFunctionality()}
\r
136 * <li>passing an instance of implementation and {@link DataStoreIdentifier} of
\r
137 * rpc as arguments to the
\r
138 * {@link DataProviderService#addCommitHandler(DataStoreIdentifier, DataCommitHandler)}
\r
144 public interface DataCommitHandler extends ProviderFunctionality {
\r
146 * A set of Data Stores supported by implementation.
\r
148 * The set of {@link DataStoreIdentifier}s which identifies target data
\r
149 * stores which are supported by this commit handler. This set is used, when
\r
150 * {@link Provider} is registered to the SAL, to register and expose the
\r
151 * commit handler functionality to affected data stores.
\r
153 * @return Set of Data Store identifiers
\r
155 Set<DataStoreIdentifier> getSupportedDataStores();
\r
158 * The provider (commit handler) starts a commit transaction.
\r
161 * The commit handler (provider) prepares an commit scenario, rollback
\r
162 * scenario and validates data.
\r
165 * If the provider is aware that at this point the commit would not be
\r
166 * successful, the transaction is not created, but list of errors which
\r
167 * prevented the start of transaction are returned.
\r
170 * @return Transaction object representing this commit, errors otherwise.
\r
172 RpcResult<CommitTransaction> requestCommit(DataStoreIdentifier store);
\r
174 public interface CommitTransaction {
\r
177 * @return Data store affected by the transaction
\r
179 DataStoreIdentifier getDataStore();
\r
182 * Returns the handler associated with this transaction.
\r
186 DataCommitHandler getHandler();
\r
190 * Finishes a commit.
\r
192 * The provider (commit handler) should apply all changes to its state
\r
193 * which are a result of data change-
\r
197 RpcResult<Void> finish() throws IllegalStateException;
\r
200 * Rollbacks a commit.
\r
203 * @throws IllegalStateException
\r
204 * If the method is invoked after {@link #finish()}
\r
206 RpcResult<Void> rollback() throws IllegalStateException;
\r