2 * Copyright (c) 2013 Cisco Systems, Inc. and others. All rights reserved.
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
8 package org.opendaylight.controller.md.sal.common.api.data;
10 import org.opendaylight.controller.sal.common.DataStoreIdentifier;
11 // FIXME: After 0.6 Release of YANGTools refactor to use Path marker interface for arguments.
12 // import org.opendaylight.yangtools.concepts.Path;
13 import org.opendaylight.yangtools.yang.common.RpcResult;
15 * Two phase commit handler (cohort) of the two-phase commit protocol of data.
18 * The provider should expose the implementation of DataCommitHandler if it's
19 * functionality depends on any subset of data stored in data repositories, in
20 * order to participate in {@link DataBrokerService#commit(DataStoreIdentifier)
24 * Operations of two-phase commit handlers should not change data in data store,
25 * this is responsibility of the coordinator (broker or some component of the
28 * The commit handlers are responsible for changing the internal state of the
29 * provider to reflect the commited changes in data.
31 * <h3>Two-phase commit</h3>
33 * <h4>Commit Request Phase</h4>
36 * <li> <code>Consumer</code> edits data by invocation of
37 * <code>DataBrokerService.editCandidateData(DataStoreIdentifier, DataRoot)</code>
38 * <li> <code>Consumer</code> starts a commit by invoking
39 * <code>DataBrokerService.commit(DataStoreIdentifier)</code>
40 * <li> <code>Broker</code> retrieves a list of all registered
41 * <code>DataCommitHandlers</code>
42 * <li>For each <code>DataCommitHandler</code>
44 * <li><code>Broker</code> invokes a
45 * <code>DataCommitHandler.requestCommit(DataStoreIdentifier)</code> operation.
46 * <li><code>DataCommitHandler</code> returns a <code>RpcResult</code> with
47 * <code>CommitTransaction</code>
48 * <li>If the result was successful, broker adds <code>CommitTransaction</code>
49 * to the list of opened transactions. If not, brokers stops a commit request
50 * phase and starts a rollback phase.
52 * <li><code>Broker</code> starts a commit finish phase
55 * <h4>Commit Finish Phase</h4>
58 * <li>For each <code>CommitTransaction</code> from Commit Request phase
60 * <li><code>Broker</code> broker invokes a
61 * <code>CommitTransaction.finish()</code>
62 * <li>The provider finishes a commit (applies the change) and returns an
63 * <code>RpcResult</code>.
67 * <li>If all returned results means successful, the brokers end two-phase
68 * commit by returning a success commit result to the Consumer.
69 * <li>If error occured, the broker starts a commit rollback phase.
73 * <h4>Commit Rollback Phase</h4>
74 * <li>For each <code>DataCommitTransaction</code> from Commit Request phase
76 * <li><code>Broker</code>
77 * broker invokes a {@link DataCommitTransaction#finish()}
78 * <li>The provider rollbacks a commit and returns an {@link RpcResult} of
80 * <li>Broker returns a error result to the consumer.
82 * @param <P> Class representing a path
83 * @param <D> Superclass from which all data objects are derived from.
85 public interface DataCommitHandler<P/* extends Path<P> */,D> {
88 DataCommitTransaction<P, D> requestCommit(DataModification<P,D> modification);
90 public interface DataCommitTransaction<P/* extends Path<P> */,D> {
92 DataModification<P,D> getModification();
98 * This callback is invoked by commit coordinator to finish commit action.
100 * The implementation is required to finish transaction or return unsuccessful
101 * rpc result if something went wrong.
103 * The provider (commit handler) should apply all changes to its state
104 * which are a result of data change-
108 RpcResult<Void> finish() throws IllegalStateException;
111 * Rollbacks a commit.
113 * This callback is invoked by commit coordinator to finish commit action.
115 * The provider (commit handler) should rollback all changes to its state
116 * which were a result of previous request commit.
119 * @throws IllegalStateException
120 * If the method is invoked after {@link #finish()}
122 RpcResult<Void> rollback() throws IllegalStateException;