*/
package org.opendaylight.mdsal.dom.api;
-import org.eclipse.jdt.annotation.NonNull;
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.opendaylight.yangtools.concepts.Registration;
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.
*/
+@NonNullByDefault
public interface DOMDataBroker extends DOMService<DOMDataBroker, DOMDataBroker.Extension>, DOMTransactionFactory {
/**
* Type capture of a {@link DOMService.Extension} applicable to {@link DOMDataBroker} implementations.
/**
* 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.
*
- * @param listener Transaction chain event listener
* @return A new transaction chain.
*/
- @NonNull DOMTransactionChain createTransactionChain(DOMTransactionChainListener listener);
+ 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(DOMTransactionChainListener)}, 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.
+ * 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.
*/
- @NonNull DOMTransactionChain createMergingTransactionChain(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);
+ }
+
+ /**
+ * An {@link Extension} which allows users to register for changes to a subtree.
+ */
+ interface DataTreeChangeExtension extends Extension {
+ /**
+ * Registers a {@link DOMDataTreeChangeListener} to receive notifications when data changes under a given path
+ * in the conceptual data tree.
+ *
+ * <p>
+ * You are able to register for notifications for any node or subtree which can be represented using
+ * {@link DOMDataTreeIdentifier}.
+ *
+ * <p>
+ * You are able to register for data change notifications for a subtree or leaf even if it does not exist. You
+ * will receive notification once that node is created.
+ *
+ * <p>
+ * If there is any pre-existing data in the data tree for the path for which you are registering, you will
+ * receive an initial data change event, which will contain all pre-existing data, marked as created.
+ *
+ * <p>
+ * This method returns a {@link Registration} object. To "unregister" your listener for changes call
+ * the {@link Registration#close()} method on the returned object.
+ *
+ * <p>
+ * You MUST explicitly unregister your listener when you no longer want to receive notifications. This is
+ * especially true in OSGi environments, where failure to do so during bundle shutdown can lead to stale
+ * listeners being still registered.
+ *
+ * @param treeId Data tree identifier of the subtree which should be watched for changes.
+ * @param listener Listener instance which is being registered
+ * @return A {@link Registration} object, which may be used to unregister your listener using
+ * {@link Registration#close()} to stop delivery of change events.
+ * @throws NullPointerException if any of the arguments is {@code null}
+ */
+ Registration registerDataTreeChangeListener(DOMDataTreeIdentifier treeId, DOMDataTreeChangeListener listener);
+ }
}
Code Review / mdsal.git / blobdiff