Rename DOMDataTreeCommitCohortRegistry to CommitCohortExtension

[mdsal.git] / dom / mdsal-dom-api / src / main / java / org / opendaylight / mdsal / dom / api / DOMDataBroker.java

diff --git a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataBroker.java b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataBroker.java
index 34b4c517bd3ce8fe287f185e4f0d64b442a6d230..6654fbdab5bd3fd46df5784281325e4c191b4759 100644 (file)
--- a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataBroker.java
+++ b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMDataBroker.java
@@ -7,8 +7,8 @@
  */
 package org.opendaylight.mdsal.dom.api;
 
-import org.opendaylight.mdsal.common.api.AsyncDataBroker;
-import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.opendaylight.yangtools.concepts.Registration;
 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
 
 /**
@@ -42,15 +42,55 @@ import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
  * <b>Implementation Note:</b> This interface is not intended to be implemented by users of MD-SAL,
  * but only to be consumed by them.
  */
-public interface DOMDataBroker extends
-        AsyncDataBroker<YangInstanceIdentifier, NormalizedNode<?, ?>>, DOMTransactionFactory,
-        DOMExtensibleService<DOMDataBroker, DOMDataBrokerExtension> {
+@NonNullByDefault
+public interface DOMDataBroker extends DOMService<DOMDataBroker, DOMDataBroker.Extension>, DOMTransactionFactory {
+    /**
+     * Type capture of a {@link DOMService.Extension} applicable to {@link DOMDataBroker} implementations.
+     */
+    interface Extension extends DOMService.Extension<DOMDataBroker, Extension> {
+        // Marker interface
+    }
+
+    /**
+     * Create a new transaction chain. The chain will be initialized to read from its backing datastore, with
+     * no outstanding transaction.
+     *
+     * @return A new transaction chain.
+     */
+    DOMTransactionChain createTransactionChain();
+
     /**
      * Create a new transaction chain. The chain will be initialized to read from its backing datastore, with
-     * no outstanding transaction. Listener will be registered to handle chain-level events.
+     * no outstanding transaction.
+     *
+     * <p>
+     * Unlike {@link #createTransactionChain()}, the transaction chain returned by this method is allowed to merge
+     * individual transactions into larger chunks. When transactions are merged, the results must be indistinguishable
+     * from the result of all operations having been performed on a single transaction.
+     *
+     * <p>
+     * When transactions are merged, {@link DOMTransactionChain#newReadOnlyTransaction()} may actually be backed by
+     * a read-write transaction, hence an additional restriction on API use is that multiple read-only transactions
+     * may not be open at the same time.
      *
-     * @param listener Transaction chain event listener
      * @return A new transaction chain.
      */
-    DOMTransactionChain createTransactionChain(DOMTransactionChainListener listener);
+    DOMTransactionChain createMergingTransactionChain();
+
+    /**
+     * Optional support for allowing a {@link DOMDataTreeCommitCohort} to participate in the process of committing
+     * {@link DOMDataTreeWriteTransaction}s.
+     */
+    interface CommitCohortExtension extends Extension {
+        /**
+         * Register commit cohort which will participate in three-phase commit protocols of
+         * {@link DOMDataTreeWriteTransaction} in data broker associated with this instance of extension.
+         *
+         * @param path Subtree path on which commit cohort operates.
+         * @param cohort A {@link DOMDataTreeCommitCohort}
+         * @return A {@link Registration}
+         * @throws NullPointerException if any argument is {@code null}
+         */
+        Registration registerCommitCohort(DOMDataTreeIdentifier path, DOMDataTreeCommitCohort cohort);
+    }
 }