X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=binding%2Fmdsal-binding-api%2Fsrc%2Fmain%2Fjava%2Forg%2Fopendaylight%2Fmdsal%2Fbinding%2Fapi%2FDataTreeChangeService.java;h=b5b1d0c1ee16d93ea03d439c328149bc19eb42c3;hb=b8a896e6dfc47374f99efee157683dc8a7ef8860;hp=50d20c993f3f842b006ad63b78408dbeb1f355dd;hpb=b270139f1ba3e72db7953c62dd374aca9699fcb0;p=mdsal.git

diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeService.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeService.java
index 50d20c993f..b5b1d0c1ee 100644
--- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeService.java
+++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeChangeService.java
@@ -7,8 +7,8 @@
  */
 package org.opendaylight.mdsal.binding.api;
 
-import javax.annotation.Nonnull;
-import org.opendaylight.yangtools.concepts.ListenerRegistration;
+import org.eclipse.jdt.annotation.NonNull;
+import org.opendaylight.yangtools.concepts.Registration;
 import org.opendaylight.yangtools.yang.binding.DataObject;
 
 /**
@@ -16,39 +16,188 @@ import org.opendaylight.yangtools.yang.binding.DataObject;
  */
 public interface DataTreeChangeService extends BindingService {
     /**
-     * Registers a {@link DataTreeChangeListener} to receive
-     * notifications when data changes under a given path in the conceptual data
-     * tree.
+     * Registers a {@link DataTreeChangeListener} 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 DataTreeIdentifier}.
+     *
+     * <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 <b>MUST</b> 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 Registration object, which may be used to unregister your listener using {@link Registration#close()}
+     *         to stop delivery of change events.
+     */
+    <T extends DataObject> @NonNull Registration registerTreeChangeListener(
+        @NonNull DataTreeIdentifier<T> treeId, @NonNull DataTreeChangeListener<T> listener);
+
+    /**
+     * Registers a {@link DataTreeChangeListener} to receive notifications when data changes under a given path in the
+     * conceptual data tree, with legacy semantics, where no events are delivered if this "cluster node" (further
+     * undefined) is a "leader" (also not explicitly undefined).
+     *
+     * <p>
+     * The sole known implementation, the Akka-based datastore, defines the difference in terms of RAFT, suspending
+     * even delivery when the RAFT leader is not local. Even when there may be valid use cases for this, RAFT there
+     * is a storage backend whose lifecycle is disconnected from this object.
+     *
+     * <p>
+     * Aside from the above difference, this method is equivalent to
+     * {@link #registerTreeChangeListener(DataTreeIdentifier, DataTreeChangeListener)}. If you are unable to migrate,
+     * please contact us on <a href="email:discuss@lists.opendaylight.org">the mailing list</a>
+     *
+     * @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}
+     */
+    @Deprecated(since = "13.0.0", forRemoval = true)
+    <T extends DataObject> @NonNull Registration registerLegacyTreeChangeListener(@NonNull DataTreeIdentifier<T> treeId,
+        @NonNull DataTreeChangeListener<T> listener);
+
+    /**
+     * Registers a {@link DataTreeChangeListener} 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 DataTreeIdentifier}.
+     *
+     * <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 <b>MUST</b> 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 Registration object, which may be used to unregister your listener using {@link Registration#close()}
+     *         to stop delivery of change events.
+     * @deprecated This interface relies on magic of {@link ClusteredDataTreeChangeListener}. See
+     *             {@link #registerLegacyTreeChangeListener(DataTreeIdentifier, DataTreeChangeListener)} for migration
+     *             guidance.
+     */
+    @Deprecated(since = "13.0.0", forRemoval = true)
+    default <T extends DataObject> @NonNull Registration registerDataTreeChangeListener(
+            final @NonNull DataTreeIdentifier<T> treeId, final @NonNull DataTreeChangeListener<T> listener) {
+        return listener instanceof ClusteredDataTreeChangeListener ? registerTreeChangeListener(treeId, listener)
+            : registerLegacyTreeChangeListener(treeId, listener);
+    }
+
+    /**
+     * Registers a {@link ClusteredDataTreeChangeListener} to receive notifications when data changes under a given path
+     * in the conceptual data tree. This is a migration shorthand for
+     * {@code registerDataTreeListener(treeId, listener)}.
+     *
+     * @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}
+     * @deprecated Use {@link #registerTreeChangeListener(DataTreeIdentifier, DataTreeChangeListener)} instead.
+     */
+    @Deprecated(since = "13.0.0", forRemoval = true)
+    default <T extends DataObject> @NonNull Registration registerDataTreeChangeListener(
+            final @NonNull DataTreeIdentifier<T> treeId, final @NonNull ClusteredDataTreeChangeListener<T> listener) {
+        return registerTreeChangeListener(treeId, listener);
+    }
+
+    /**
+     * Registers a {@link DataTreeChangeListener} 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 DataTreeIdentifier}.
+     * You are able to register for notifications  for any node or subtree which can be represented using
+     * {@link DataTreeIdentifier}.
+     *
      * <p>
+     * This method returns a {@link Registration} object. To "unregister" your listener for changes call the
+     * {@link Registration#close()} method on the returned object.
      *
-     * 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.
+     * You <b>MUST</b> 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.
+     *
+     * @implSpec This method provides {@link DataListenerAdapter} as listener during the registration of
+     *           {@link DataTreeChangeListener}. This would allow users to know the last state of data instead of
+     *           getting details about what changed in the entire tree.
+     *
+     * @param treeId Data tree identifier of the subtree which should be watched for changes.
+     * @param listener Listener instance which is being registered
+     * @return Listener registration object, which may be used to unregister your listener using
+     *         {@link Registration#close()} to stop delivery of change events.
+     */
+    default <T extends DataObject> @NonNull Registration registerDataListener(
+            final @NonNull DataTreeIdentifier<T> treeId, final @NonNull DataListener<T> listener) {
+        return registerTreeChangeListener(checkNotWildcard(treeId), new DataListenerAdapter<>(listener));
+    }
+
+    /**
+     * Registers a {@link DataTreeChangeListener} to receive notifications about the last data state when it 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 DataTreeIdentifier}.
      *
      * <p>
-     * This method returns a {@link ListenerRegistration} object. To
-     * "unregister" your listener for changes call the {@link ListenerRegistration#close()}
-     * method on the returned object.
+     * 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.
+     * You <b>MUST</b> 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.
+     *
+     * @implSpec This method provides {@link DataChangeListenerAdapter} as listener during the registration of
+     *           {@link DataTreeChangeListener}, which provides a comparison of before-value and after-value.
      *
-     * @param treeId
-     *            Data tree identifier of the subtree which should be watched for
-     *            changes.
-     * @param listener
-     *            Listener instance which is being registered
-     * @return Listener registration object, which may be used to unregister
-     *         your listener using {@link ListenerRegistration#close()} to stop
-     *         delivery of change events.
+     * @param treeId Data tree identifier of the subtree which should be watched for changes.
+     * @param listener Listener instance which is being registered
+     * @return Listener registration object, which may be used to unregister your listener using
+     *         {@link Registration#close()} to stop  delivery of change events.
      */
-    @Nonnull <T extends DataObject,L extends DataTreeChangeListener<T>> ListenerRegistration<L> registerDataTreeChangeListener(@Nonnull DataTreeIdentifier<T> treeId, @Nonnull L listener);
+    default <T extends DataObject> @NonNull Registration registerDataChangeListener(
+            final @NonNull DataTreeIdentifier<T> treeId, final @NonNull DataChangeListener<T> listener) {
+        return registerTreeChangeListener(checkNotWildcard(treeId), new DataChangeListenerAdapter<>(listener));
+    }
+
+    private static <T extends DataObject> @NonNull DataTreeIdentifier<T> checkNotWildcard(
+            final DataTreeIdentifier<T> treeId) {
+        final var instanceIdentifier = treeId.path();
+        if (instanceIdentifier.isWildcarded()) {
+            throw new IllegalArgumentException("Cannot register listener for wildcard " + instanceIdentifier);
+        }
+        return treeId;
+    }
 }
\ No newline at end of file