opendaylight/sal/yang-prototype/sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/DataCommitHandler.java

   1 /*\r
   2  * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.\r
   3  *\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
   7  */\r
   8 package org.opendaylight.controller.sal.binding.api;\r
   9 \r
  10 import java.util.Set;\r
  11 \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
  15 \r
  16 \r
  17 /**\r
  18  * Two phase commit handler (cohort) of the two-phase commit protocol of data.\r
  19  * \r
  20  * <p>\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
  24  * operation.\r
  25  * \r
  26  * <p>\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
  29  * broker).\r
  30  * \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
  33  * \r
  34  * <h3>Two-phase commit</h3>\r
  35  * \r
  36  * <h4>Commit Request Phase</h4>\r
  37  * \r
  38  * <ol>\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
  46  * <ol>\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
  54  * </ol>\r
  55  * <li><code>Broker</code> starts a commit finish phase\r
  56  * </ol>\r
  57  * \r
  58  * <h4>Commit Finish Phase</h4>\r
  59  * \r
  60  * <ol>\r
  61  * <li>For each <code>CommitTransaction</code> from Commit Request phase\r
  62  * <ol>\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
  67  * </ol>\r
  68  * <li>\r
  69  * <ul>\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
  73  * </ul>\r
  74  * </ol>\r
  75  * \r
  76  * <h4>Commit Rollback Phase</h4>\r
  77  * <li>For each <code>CommitTransaction</code> from Commit Request phase\r
  78  * <ol>\r
  79  * <li><code>Broker</code>\r
  80  * \r
  81  * \r
  82  * \r
  83  * \r
  84  * \r
  85  * \r
  86  * \r
  87  * \r
  88  * \r
  89  * \r
  90  * \r
  91  * \r
  92  * \r
  93  * \r
  94  * \r
  95  * \r
  96  * \r
  97  * \r
  98  * \r
  99  * \r
 100  * \r
 101  * \r
 102  * \r
 103  * \r
 104  * \r
 105  * \r
 106  * \r
 107  * \r
 108  * \r
 109  * \r
 110  * \r
 111  * \r
 112  * \r
 113  * \r
 114  * \r
 115  * \r
 116  * \r
 117  * \r
 118  * \r
 119  * \r
 120  * \r
 121  * \r
 122  * \r
 123  * \r
 124  * \r
 125  * broker invokes a {@link CommitTransaction#finish()}\r
 126  * <li>The provider rollbacks a commit and returns an {@link RpcResult} of\r
 127  * rollback. </ol>\r
 128  * <li>Broker returns a error result to the consumer.\r
 129  * \r
 130  * \r
 131  * <h3>Registration of functionality</h3>\r
 132  * The registration could be done by :\r
 133  * <ul>\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
 139  * </ul>\r
 140  * \r
 141 \r
 142  * \r
 143  */\r
 144 public interface DataCommitHandler extends ProviderFunctionality {\r
 145     /**\r
 146      * A set of Data Stores supported by implementation.\r
 147      * \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
 152      * \r
 153      * @return Set of Data Store identifiers\r
 154      */\r
 155     Set<DataStoreIdentifier> getSupportedDataStores();\r
 156 \r
 157     /**\r
 158      * The provider (commit handler) starts a commit transaction.\r
 159      * \r
 160      * <p>\r
 161      * The commit handler (provider) prepares an commit scenario, rollback\r
 162      * scenario and validates data.\r
 163      * \r
 164      * <p>\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
 168      * \r
 169      * @param store\r
 170      * @return Transaction object representing this commit, errors otherwise.\r
 171      */\r
 172     RpcResult<CommitTransaction> requestCommit(DataStoreIdentifier store);\r
 173 \r
 174     public interface CommitTransaction {\r
 175         /**\r
 176          * \r
 177          * @return Data store affected by the transaction\r
 178          */\r
 179         DataStoreIdentifier getDataStore();\r
 180 \r
 181         /**\r
 182          * Returns the handler associated with this transaction.\r
 183          * \r
 184          * @return Handler\r
 185          */\r
 186         DataCommitHandler getHandler();\r
 187 \r
 188         /**\r
 189          * \r
 190          * Finishes a commit.\r
 191          * \r
 192          * The provider (commit handler) should apply all changes to its state\r
 193          * which are a result of data change-\r
 194          * \r
 195          * @return\r
 196          */\r
 197         RpcResult<Void> finish() throws IllegalStateException;\r
 198 \r
 199         /**\r
 200          * Rollbacks a commit.\r
 201          * \r
 202          * @return\r
 203          * @throws IllegalStateException\r
 204          *             If the method is invoked after {@link #finish()}\r
 205          */\r
 206         RpcResult<Void> rollback() throws IllegalStateException;\r
 207     }\r
 208 \r
 209 }\r