Bug 1235: Documented Notification services of MD-SAL 20/8320/5
authorTony Tkacik <ttkacik@cisco.com>
Wed, 25 Jun 2014 08:26:15 +0000 (10:26 +0200)
committerTony Tkacik <ttkacik@cisco.com>
Thu, 3 Jul 2014 15:49:12 +0000 (17:49 +0200)
Change-Id: I56c7b41b56eef8c92854e986a5f9f7af21ae1d09
Signed-off-by: Tony Tkacik <ttkacik@cisco.com>
opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationListener.java
opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationProviderService.java
opendaylight/md-sal/sal-binding-api/src/main/java/org/opendaylight/controller/sal/binding/api/NotificationService.java
opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/notify/NotificationPublishService.java

index 9429d3f..be8e0ce 100644 (file)
@@ -12,20 +12,20 @@ import java.util.EventListener;
 import org.opendaylight.yangtools.yang.binding.Notification;
 
 /**
- * Interface implemented by objects interested in some sort of Notification. This
- * class acts as a base interface for specific listeners which usually are a type
+ * Interface for a generic listener that is interested in receiving YANG modeled notifications.
+ * This interface acts as a base interface for specific listeners which usually are a type
  * capture of this interface.
  *
- * @param <T> Notification type
+ * @param <T> the interested notification type
  */
 public interface NotificationListener<T extends Notification> extends EventListener {
     /**
-     * Invoked to deliver the notification. Note that this method may be invoked
-     * from a shared thread pool, so implementations SHOULD NOT perform CPU-intensive
-     * operations and they definitely MUST NOT invoke any potentially blocking
-     * operations.
+     * Invoked to deliver a notification.
+     * <p>
+     * Note that this method may be invoked from a shared thread pool, so implementations SHOULD NOT
+     * perform CPU-intensive operations and MUST NOT invoke any potentially blocking operations.
      *
-     * @param notification Notification being delivered.
+     * @param notification the notification.
      */
     void onNotification(T notification);
 }
index b94695b..00db80c 100644 (file)
@@ -14,29 +14,62 @@ import org.opendaylight.controller.md.sal.common.api.notify.NotificationPublishS
 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.
+ */
 public interface NotificationProviderService extends NotificationService, NotificationPublishService<Notification> {
+
     /**
-     * Publishes a notification.
-     *
-     * @param Notification
-     *            notification to publish.
-     *
+     * {@inheritDoc}
      */
     @Override
-    void publish(Notification notification);
+    public void publish(Notification notification);
 
     /**
-     * Publishes a notification, listener calls are done in provided executor.
-     *
+     * {@inheritDoc}
      */
     @Override
-    void publish(Notification notification, ExecutorService service);
+    void publish(Notification notification, ExecutorService 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.
+     */
     ListenerRegistration<NotificationInterestListener> registerInterestListener(
             NotificationInterestListener interestListener);
 
+    /**
+     * Interface for a listener interested in being notified about notification subscriptions.
+     */
     public 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);
     }
 }
index 46e372a..335f55b 100644 (file)
@@ -10,24 +10,108 @@ package org.opendaylight.controller.sal.binding.api;
 import org.opendaylight.yangtools.concepts.ListenerRegistration;
 import org.opendaylight.yangtools.yang.binding.Notification;
 
+/**
+ * Notification broker which allows clients to subscribe for and publish YANG-modeled notifications.
+ *
+ *<p>
+ * Two styles of listeners are supported:
+ * <ul>
+ * <li>Generic listener</li>
+ * <li>Dispatch listener - listener, which implements <code>{ModelName}Listener</code> interface,
+ * which has dispatch methods for each defined notification. Methods are invoked based on notification type (class).
+ * </li>
+ *
+ * <h3>Generic Listener</h3>
+ * <p>
+ * A generic listener implements the {@link NotificationListener} interface which has one callback method
+ * <code>onNotification</code> that is invoked for any notification type the listener is subscribed to.
+ * <p>
+ * A generic listener is subscribed using the {@link #registerNotificationListener(Class, NotificationListener)}
+ * method by which you specify the type of notification to receive. A generic listener may be registered for
+ * multiple notification types via multiple subscriptions.
+ * <p>
+ * Generic listeners allow for a more flexible approach, allowing you to subscribe for just
+ * one type of notification from a YANG model. You could also have a general subscription
+ * for all notification in the system via
+ * <pre>
+ *   service.registerNotificationListener(Notification.class, listener);
+ * </pre>
+ *
+ * <h3>Dispatch Listener</h3>
+ * <p>
+ * A dispatch listener implements a YANG-generated module interface <code>{ModuleName}Listener</code>
+ * which handles all the notifications defined in the YANG model. Each notification type translates to
+ * a specific method of the form <code>on{NotificationType}</code> on the generated interface.
+ * The generated interface also extends the
+ * {@link org.opendaylight.yangtools.yang.binding.NotificationListener} interface and implementations
+ * are registered using {@link #registerNotificationListener(org.opendaylight.yangtools.yang.binding.NotificationListener)}
+ * method.
+ *
+ * <h5>Dispatch Listener Example</h5>
+ * <p>
+ * Lets assume we have following YANG model:
+ *
+ * <pre>
+ * module example {
+ *      ...
+ *
+ *      notification start {
+ *          ...
+ *      }
+ *
+ *      notification stop {
+ *           ...
+ *      }
+ * }
+ * </pre>
+ *
+ * The generated interface will be:
+ * <pre>
+ *  public interface ExampleListener extends NotificationListener {
+ *      void onStart(Start notification);
+ *      void onStop(Stop notification);
+ *  }
+ * </pre>
+ * The following defines an implementation of the generated interface:
+ * <pre>
+ *  public class MyExampleListener implements ExampleListener {
+ *      public void onStart(Start notification) {
+ *          // do something
+ *      }
+ *
+ *      public void onStop(Stop notification) {
+ *          // do something
+ *      }
+ *  }
+ * </pre>
+ * The implementation is registered as follows:
+ * <pre>
+ *  MyExampleListener listener = new MyExampleListener();
+ *  ListenerRegistration<NotificationListener> reg = service.registerNotificationListener( listener );
+ * </pre>
+ * The <code>onStart</code> method will be invoked when someone publishes a <code>Start</code> notification and
+ * the <code>onStop</code> method will be invoked when someone publishes a <code>Stop</code> notification.
+ */
 public interface NotificationService extends BindingAwareService {
     /**
-     * Register a generic listener for specified notification type only.
+     * Registers a generic listener implementation for a specified notification type.
      *
-     * @param notificationType
-     * @param listener
-     * @return Registration for listener. To unregister listener invoke {@link ListenerRegistration#close()} method.
+     * @param notificationType the YANG-generated interface of the notification type.
+     * @param listener the listener implementation that will receive notifications.
+     * @return a {@link ListenerRegistration} instance that should be used to unregister the listener
+     *         by invoking the {@link ListenerRegistration#close()} method when no longer needed.
      */
     <T extends Notification> ListenerRegistration<NotificationListener<T>> registerNotificationListener(
             Class<T> notificationType, NotificationListener<T> listener);
 
     /**
-     * Register a listener which implements generated notification interfaces derived from
+     * Registers a listener which implements a YANG-generated notification interface derived from
      * {@link org.opendaylight.yangtools.yang.binding.NotificationListener}.
-     * Listener is registered for all notifications present in implemented interfaces.
+     * The listener is registered for all notifications present in the implemented interface.
      *
-     * @param listener
-     * @return Registration for listener. To unregister listener invoke {@link ListenerRegistration#close()} method.
+     * @param listener the listener implementation that will receive notifications.
+     * @return a {@link ListenerRegistration} instance that should be used to unregister the listener
+     *         by invoking the {@link ListenerRegistration#close()} method when no longer needed.
      */
     ListenerRegistration<org.opendaylight.yangtools.yang.binding.NotificationListener> registerNotificationListener(
             org.opendaylight.yangtools.yang.binding.NotificationListener listener);
index f5f03a1..bb866f2 100644 (file)
@@ -9,9 +9,63 @@ package org.opendaylight.controller.md.sal.common.api.notify;
 
 import java.util.concurrent.ExecutorService;
 
+/**
+ * Interface for publishing YANG-modeled notifications.
+ * <p>
+ * Users of this interface can publish any YANG-modeled notification which will
+ * be delivered to all subscribed listeners.
+ * <p>
+ * Prefered way of publishing of notifications is done by invoking {@link #publish(Object)}.
+ *
+ * <p>You may consider using {@link #publish(Object, ExecutorService)} if and only if
+ * your use-case requires customized  execution policy or run-to-completion
+ * inside process.
+ *
+ * <p>
+ * The metadata required to deliver a notification to the correct listeners is
+ * extracted from the published notification.
+ *
+ *
+ * FIXME: Consider clarification of execution/delivery policy, how it will be
+ * affected by Actor model and cluster-wide notifications.
+ *
+ * @param <N>
+ *            the type of notifications
+ */
 public interface NotificationPublishService<N> {
 
+    /**
+     * Publishes a notification and notifies subscribed listeners. All listener
+     * notifications are done via a default executor.
+     * <p>
+     * <b>Note:</b> This call will block when the default executor is saturated
+     * and the notification queue for this executor is full.
+     *
+     * @param notification
+     *            the notification to publish.
+     */
     void publish(N notification);
 
-    void publish(N notification,ExecutorService executor);
+    /**
+     * Publishes a notification and notifies subscribed listeners. All listener
+     * notifications are done via the provided executor.
+     * <p>
+     * <b>Note:</b> Use only if ineccessary. Consider using
+     * {@link #publish(Object)} for most use-cases.
+     *
+     * <p>
+     * By using this method you could customize execution policy of listeners present
+     * inside process (e.g. using  single-threaded executor or even same-thread executor
+     * delivery.
+     *
+     * <p>
+     * This executor is used only for inside-process notification deliveries.
+     *
+     * @param notification
+     *            the notification to publish.
+     * @param executor
+     *            the executor that will be used to deliver notifications to
+     *            subscribed listeners.
+     */
+    void publish(N notification, ExecutorService executor);
 }

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.