X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?p=controller.git;a=blobdiff_plain;f=opendaylight%2Fmd-sal%2Fsal-binding-api%2Fsrc%2Fmain%2Fjava%2Forg%2Fopendaylight%2Fcontroller%2Fsal%2Fbinding%2Fapi%2FNotificationProviderService.java;h=ac2bb6477696cd25083edecf7ff2a74de0b381ab;hp=08029dc52fa2c35fe1ea0f4b7994ef6eecf3fbe2;hb=aaea3e9a92ae9d6fac04c4a065db4b35cbca9ed0;hpb=2e7347fdc0eb7734ff59a4f902227a93ab6afece

diff --git a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationProviderService.java b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationProviderService.java
index 08029dc52f..ac2bb64776 100644
--- a/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationProviderService.java
+++ b/opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationProviderService.java
@@ -9,52 +9,65 @@ package org.opendaylight.controller.sal.binding.api;
 
 import java.util.EventListener;
 import java.util.concurrent.ExecutorService;
-
 import org.opendaylight.controller.md.sal.common.api.notify.NotificationPublishService;
 import org.opendaylight.yangtools.concepts.ListenerRegistration;
 import org.opendaylight.yangtools.yang.binding.Notification;
 
+/**
+ * Interface for a notification service that provides publish/subscribe capabilities for YANG
+ * modeled notifications. This interface is a combination of the {@link NotificationService} and
+ * {@link NotificationPublishService} interfaces.
+ *
+ * @deprecated Please use {@link org.opendaylight.mdsal.binding.api.NotificationPublishService}.
+ */
+@Deprecated(forRemoval = true)
 public interface NotificationProviderService extends NotificationService, NotificationPublishService<Notification> {
 
-
-    /**
-     * Deprecated. Use {@link #publish(Notification)}.
-     *
-     * @param notification
-     */
-    @Deprecated
-    void notify(Notification notification);
-
-    /**
-     * Deprecated. Use {@link #publish(Notification,ExecutorService)}.
-     *
-     * @param notification
-     */
-    @Deprecated
-    void notify(Notification notification, ExecutorService service);
-
-    /**
-     * Publishes a notification.
-     *
-     * @param Notification
-     *            notification to publish.
-     *
-     */
     @Override
     void publish(Notification notification);
 
+    @Override
+    void publish(Notification notification, ExecutorService executor);
+
     /**
-     * Publishes a notification, listener calls are done in provided executor.
+     * Registers a listener to be notified about notification subscriptions. This
+     * enables a component to know when there is a notification listener subscribed
+     * for a particular notification type.
      *
+     * <p>
+     * On registration of this listener, the
+     * {@link NotificationInterestListener#onNotificationSubscribtion(Class)} method
+     * will be invoked for every notification type that currently has a notification listener
+     * subscribed.
+     *
+     * @param interestListener the listener that will be notified when subscriptions
+     *                         for new notification types occur.
+     * @return a {@link ListenerRegistration} instance that should be used to unregister the listener
+     *         by invoking the {@link ListenerRegistration#close()} method when no longer needed.
      */
-    @Override
-    void publish(Notification notification, ExecutorService service);
-
     ListenerRegistration<NotificationInterestListener> registerInterestListener(
             NotificationInterestListener interestListener);
 
-    public interface NotificationInterestListener extends EventListener {
+    /**
+     * Interface for a listener interested in being notified about notification subscriptions.
+     */
+    interface NotificationInterestListener extends EventListener {
 
+        /**
+         * Callback that is invoked when a notification listener subscribes for a particular notification type.
+         *
+         * <p>
+         * This method is only called for the first subscription that occurs for a
+         * particular notification type. Subsequent subscriptions for the same
+         * notification type do not trigger invocation of this method.
+         *
+         * <p>
+         * <b>Note:</b>This callback is delivered from thread not owned by this listener,
+         * all processing should be as fast as possible and implementations should
+         * not do any blocking calls or block this thread.
+         *
+         * @param notificationType the notification type for the subscription that occurred.
+         */
         void onNotificationSubscribtion(Class<? extends Notification> notificationType);
     }
 }