opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/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.sal.binding.api.data;
   9
  10 import java.util.Set;
  11
  12 import org.opendaylight.controller.sal.binding.api.BindingAwareProvider;
  13 import org.opendaylight.controller.sal.binding.api.BindingAwareProvider.ProviderFunctionality;
  14 import org.opendaylight.controller.sal.common.DataStoreIdentifier;
  15 import org.opendaylight.yangtools.yang.common.RpcResult;
  16
  17 /**
  18  * Two phase commit handler (cohort) of the two-phase commit protocol of data.
  19  *
  20  * <p>
  21  * The provider should expose the implementation of DataCommitHandler if it's
  22  * functionality depends on any subset of data stored in data repositories, in
  23  * order to participate in {@link DataBrokerService#commit(DataStoreIdentifier)
  24  * operation.
  25  *
  26  * <p>
  27  * Operations of two-phase commit handlers should not change data in data store,
  28  * this is responsibility of the coordinator (broker or some component of the
  29  * broker).
  30  *
  31  * The commit handlers are responsible for changing the internal state of the
  32  * provider to reflect the commited changes in data.
  33  *
  34  * <h3>Two-phase commit</h3>
  35  *
  36  * <h4>Commit Request Phase</h4>
  37  *
  38  * <ol>
  39  * <li> <code>Consumer</code> edits data by invocation of
  40  * <code>DataBrokerService.editCandidateData(DataStoreIdentifier, DataRoot)</code>
  41  * <li> <code>Consumer</code> starts a commit by invoking
  42  * <code>DataBrokerService.commit(DataStoreIdentifier)</code>
  43  * <li> <code>Broker</code> retrieves a list of all registered
  44  * <code>DataCommitHandlers</code>
  45  * <li>For each <code>DataCommitHandler</code>
  46  * <ol>
  47  * <li><code>Broker</code> invokes a
  48  * <code>DataCommitHandler.requestCommit(DataStoreIdentifier)</code> operation.
  49  * <li><code>DataCommitHandler</code> returns a <code>RpcResult</code> with
  50  * <code>CommitTransaction</code>
  51  * <li>If the result was successful, broker adds <code>CommitTransaction</code>
  52  * to the list of opened transactions. If not, brokers stops a commit request
  53  * phase and starts a rollback phase.
  54  * </ol>
  55  * <li><code>Broker</code> starts a commit finish phase
  56  * </ol>
  57  *
  58  * <h4>Commit Finish Phase</h4>
  59  *
  60  * <ol>
  61  * <li>For each <code>CommitTransaction</code> from Commit Request phase
  62  * <ol>
  63  * <li><code>Broker</code> broker invokes a
  64  * <code>CommitTransaction.finish()</code>
  65  * <li>The provider finishes a commit (applies the change) and returns an
  66  * <code>RpcResult</code>.
  67  * </ol>
  68  * <li>
  69  * <ul>
  70  * <li>If all returned results means successful, the brokers end two-phase
  71  * commit by returning a success commit result to the Consumer.
  72  * <li>If error occured, the broker starts a commit rollback phase.
  73  * </ul>
  74  * </ol>
  75  *
  76  * <h4>Commit Rollback Phase</h4>
  77  * <li>For each <code>CommitTransaction</code> from Commit Request phase
  78  * <ol>
  79  * <li><code>Broker</code>
  80  * broker invokes a {@link CommitTransaction#finish()}
  81  * <li>The provider rollbacks a commit and returns an {@link RpcResult} of
  82  * rollback. </ol>
  83  * <li>Broker returns a error result to the consumer.
  84  *
  85  *
  86  * <h3>Registration of functionality</h3>
  87  * The registration could be done by :
  88  * <ul>
  89  * <li>returning an instance of implementation in the return value of
  90  * {@link Provider#getProviderFunctionality()}
  91  * <li>passing an instance of implementation and {@link DataStoreIdentifier} of
  92  * rpc as arguments to the
  93  * {@link DataProviderService#addCommitHandler(DataStoreIdentifier, DataCommitHandler)}
  94  * </ul>
  95  *
  96  *
  97  *
  98  */
  99 public interface DataCommitHandler extends ProviderFunctionality {
 100     /**
 101      * A set of Data Stores supported by implementation.
 102      *
 103      * The set of {@link DataStoreIdentifier}s which identifies target data
 104      * stores which are supported by this commit handler. This set is used, when
 105      * {@link Provider} is registered to the SAL, to register and expose the
 106      * commit handler functionality to affected data stores.
 107      *
 108      * @return Set of Data Store identifiers
 109      */
 110     @Deprecated
 111     Set<DataStoreIdentifier> getSupportedDataStores();
 112
 113     /**
 114      * The provider (commit handler) starts a commit transaction.
 115      *
 116      * <p>
 117      * The commit handler (provider) prepares an commit scenario, rollback
 118      * scenario and validates data.
 119      *
 120      * <p>
 121      * If the provider is aware that at this point the commit would not be
 122      * successful, the transaction is not created, but list of errors which
 123      * prevented the start of transaction are returned.
 124      *
 125      * @param store
 126      * @return Transaction object representing this commit, errors otherwise.
 127      */
 128     @Deprecated
 129     RpcResult<CommitTransaction> requestCommit(DataStoreIdentifier store);
 130
 131
 132     RpcResult<CommitTransaction> requestCommit(DataModification modification);
 133
 134     public interface CommitTransaction {
 135         /**
 136          *
 137          * @return Data store affected by the transaction
 138          */
 139         @Deprecated
 140         DataStoreIdentifier getDataStore();
 141
 142         /**
 143          * Returns a modification transaction which is the source of this
 144          * commit transaction.
 145          *
 146          */
 147         DataModification getModification();
 148
 149         /**
 150          * Returns the handler associated with this transaction.
 151          *
 152          * @return Handler
 153          */
 154         DataCommitHandler getHandler();
 155
 156         /**
 157          *
 158          * Finishes a commit.
 159          *
 160          * The provider (commit handler) should apply all changes to its state
 161          * which are a result of data change-
 162          *
 163          * @return
 164          */
 165         RpcResult<Void> finish() throws IllegalStateException;
 166
 167         /**
 168          * Rollbacks a commit.
 169          *
 170          * @return
 171          * @throws IllegalStateException
 172          *             If the method is invoked after {@link #finish()}
 173          */
 174         RpcResult<Void> rollback() throws IllegalStateException;
 175     }
 176
 177 }