* 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. + * + *
+ * You are able to register for notifications for any node or subtree which can be represented using + * {@link DOMDataTreeIdentifier}. + * + *
+ * 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. + * + *
+ * 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. + * + *
+ * This method returns a {@link Registration} object. To "unregister" your listener for changes call + * the {@link Registration#close()} method on the returned object. + * + *
+ * 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); + } }