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.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;
  14 /**
  15  * Two phase commit handler (cohort) of the two-phase commit protocol of data.
  16  *
  17  * <p>
  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)
  21  * operation.
  22  *
  23  * <p>
  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
  26  * broker).
  27  *
  28  * The commit handlers are responsible for changing the internal state of the
  29  * provider to reflect the commited changes in data.
  30  *
  31  * <h3>Two-phase commit</h3>
  32  *
  33  * <h4>Commit Request Phase</h4>
  34  *
  35  * <ol>
  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>
  43  * <ol>
  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.
  51  * </ol>
  52  * <li><code>Broker</code> starts a commit finish phase
  53  * </ol>
  54  *
  55  * <h4>Commit Finish Phase</h4>
  56  *
  57  * <ol>
  58  * <li>For each <code>CommitTransaction</code> from Commit Request phase
  59  * <ol>
  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>.
  64  * </ol>
  65  * <li>
  66  * <ul>
  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.
  70  * </ul>
  71  * </ol>
  72  *
  73  * <h4>Commit Rollback Phase</h4>
  74  * <li>For each <code>DataCommitTransaction</code> from Commit Request phase
  75  * <ol>
  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
  79  * rollback. </ol>
  80  * <li>Broker returns a error result to the consumer.
  81  *
  82  * @param <P> Class representing a path
  83  * @param <D> Superclass from which all data objects are derived from.
  84  */
  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 }