--- /dev/null
+/*\r
+ * Copyright (c) 2013 Cisco Systems, Inc. and others. All rights reserved.\r
+ *\r
+ * This program and the accompanying materials are made available under the\r
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,\r
+ * and is available at http://www.eclipse.org/legal/epl-v10.html\r
+ */\r
+package org.opendaylight.controller.sal.core.api.data;\r
+\r
+import java.util.Set;\r
+\r
+import org.opendaylight.controller.sal.common.DataStoreIdentifier;\r
+import org.opendaylight.controller.sal.core.api.Provider;\r
+import org.opendaylight.controller.yang.common.RpcResult;\r
+\r
+\r
+/**\r
+ * Two phase commit handler (cohort) of the two-phase commit protocol of data.\r
+ * \r
+ * <p>\r
+ * The provider should expose the implementation of DataCommitHandler if it's\r
+ * functionality depends on any subset of data stored in data repositories, in\r
+ * order to participate in {@link DataBrokerService#commit(DataStoreIdentifier)\r
+ * operation.\r
+ * \r
+ * <p>\r
+ * Operations of two-phase commit handlers should not change data in data store,\r
+ * this is responsibility of the coordinator (broker or some component of the\r
+ * broker).\r
+ * \r
+ * The commit handlers are responsible for changing the internal state of the\r
+ * provider to reflect the commited changes in data.\r
+ * \r
+ * <h3>Two-phase commit</h3>\r
+ * \r
+ * <h4>Commit Request Phase</h4>\r
+ * \r
+ * <ol>\r
+ * <li> <code>Consumer</code> edits data by invocation of\r
+ * <code>DataBrokerService.editCandidateData(DataStoreIdentifier, CompositeNodeModification)</code>\r
+ * <li> <code>Consumer</code> starts a commit by invoking\r
+ * <code>DataBrokerService.commit(DataStoreIdentifier)</code>\r
+ * <li> <code>Broker</code> retrieves a list of all registered\r
+ * <code>DataCommitHandlers</code>\r
+ * <li>For each <code>DataCommitHandler</code>\r
+ * <ol>\r
+ * <li><code>Broker</code> invokes a\r
+ * <code>DataCommitHandler.requestCommit(DataStoreIdentifier)</code> operation.\r
+ * <li><code>DataCommitHandler</code> returns a <code>RpcResult</code> with\r
+ * <code>CommitTransaction</code>\r
+ * <li>If the result was successful, broker adds <code>CommitTransaction</code>\r
+ * to the list of opened transactions. If not, brokers stops a commit request\r
+ * phase and starts a rollback phase.\r
+ * </ol>\r
+ * <li><code>Broker</code> starts a commit finish phase\r
+ * </ol>\r
+ * \r
+ * <h4>Commit Finish Phase</h4>\r
+ * \r
+ * <ol>\r
+ * <li>For each <code>CommitTransaction</code> from Commit Request phase\r
+ * <ol>\r
+ * <li><code>Broker</code> broker invokes a\r
+ * <code>CommitTransaction.finish()</code>\r
+ * <li>The provider finishes a commit (applies the change) and returns an\r
+ * <code>RpcResult</code>.\r
+ * </ol>\r
+ * <li>\r
+ * <ul>\r
+ * <li>If all returned results means successful, the brokers end two-phase\r
+ * commit by returning a success commit result to the Consumer.\r
+ * <li>If error occured, the broker starts a commit rollback phase.\r
+ * </ul>\r
+ * </ol>\r
+ * \r
+ * <h4>Commit Rollback Phase</h4>\r
+ * <li>For each <code>CommitTransaction</code> from Commit Request phase\r
+ * <ol>\r
+ * <li><code>Broker</code>\r
+ * \r
+ * broker invokes a {@link CommitTransaction#finish()}\r
+ * <li>The provider rollbacks a commit and returns an {@link RpcResult} of\r
+ * rollback. </ol>\r
+ * <li>Broker returns a error result to the consumer.\r
+ * \r
+ * \r
+ * <h3>Registration of functionality</h3>\r
+ * The registration could be done by :\r
+ * <ul>\r
+ * <li>returning an instance of implementation in the return value of\r
+ * {@link Provider#getProviderFunctionality()}\r
+ * <li>passing an instance of implementation and {@link DataStoreIdentifier} of\r
+ * rpc as arguments to the\r
+ * {@link DataProviderService#addCommitHandler(DataStoreIdentifier, DataCommitHandler)}\r
+ * </ul>\r
+ * \r
+ * \r
+ */\r
+public interface DataCommitHandler extends Provider.ProviderFunctionality {\r
+\r
+ /**\r
+ * A set of Data Stores supported by implementation.\r
+ * \r
+ * The set of {@link DataStoreIdentifier}s which identifies target data\r
+ * stores which are supported by this commit handler. This set is used, when\r
+ * {@link Provider} is registered to the SAL, to register and expose the\r
+ * commit handler functionality to affected data stores.\r
+ * \r
+ * @return Set of Data Store identifiers\r
+ */\r
+ Set<DataStoreIdentifier> getSupportedDataStores();\r
+\r
+ /**\r
+ * The provider (commit handler) starts a commit transaction.\r
+ * \r
+ * <p>\r
+ * The commit handler (provider) prepares an commit scenario, rollback\r
+ * scenario and validates data.\r
+ * \r
+ * <p>\r
+ * If the provider is aware that at this point the commit would not be\r
+ * successful, the transaction is not created, but list of errors which\r
+ * prevented the start of transaction are returned.\r
+ * \r
+ * @param store\r
+ * @return Transaction object representing this commit, errors otherwise.\r
+ */\r
+ RpcResult<CommitTransaction> requestCommit(DataStoreIdentifier store);\r
+\r
+ public interface CommitTransaction {\r
+ /**\r
+ * \r
+ * @return Data store affected by the transaction\r
+ */\r
+ DataStoreIdentifier getDataStore();\r
+\r
+ /**\r
+ * Returns the handler associated with this transaction.\r
+ * \r
+ * @return Handler\r
+ */\r
+ DataCommitHandler getHandler();\r
+\r
+ /**\r
+ * \r
+ * Finishes a commit.\r
+ * \r
+ * The provider (commit handler) should apply all changes to its state\r
+ * which are a result of data change-\r
+ * \r
+ * @return\r
+ */\r
+ RpcResult<Void> finish() throws IllegalStateException;\r
+\r
+ /**\r
+ * Rollbacks a commit.\r
+ * \r
+ * @return\r
+ * @throws IllegalStateException\r
+ * If the method is invoked after {@link #finish()}\r
+ */\r
+ RpcResult<Void> rollback() throws IllegalStateException;\r
+ }\r
+}\r
Code Review / controller.git / blobdiff