--- /dev/null
+/*
+ * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.opendaylight.controller.md.sal.binding.api;
+
+import java.util.concurrent.TimeUnit;
+import org.opendaylight.yangtools.yang.binding.Notification;
+
+/**
+ * A {@link NotificationService} which also allows its users to
+ * submit YANG-modeled notifications for delivery. There are three
+ * methods of submission, following the patters from {@link java.util.concurrent.BlockingQueue}:
+ * - {@link #putNotification(Notification)}, which may block indefinitely
+ * if the implementation cannot allocate resources to accept the notification,
+ * - {@link #offerNotification(Notification)}, which does not block if face
+ * of resource starvation,
+ * - {@link #offerNotification(Notification, int, TimeUnit)}, which may block
+ * for specified time if resources are thin.
+ *
+ * The actual delivery to listeners is asynchronous and implementation-specific.
+ * Users of this interface should not make any assumptions as to whether the
+ * notification has or has not been seen.
+ */
+public interface NotificationPublishService extends BindingService {
+ /**
+ * Publishes a notification to subscribed listeners. This initiates
+ * the process of sending the notification, but delivery to the
+ * listeners can happen asynchronously, potentially after a call to
+ * this method returns.
+ *
+ * <b>Note:</b> This call will block when the notification queue is full.
+ *
+ * @param notification
+ * the notification to publish.
+ * @throws InterruptedException if interrupted while waiting
+ * @throws NullPointerException if the notification is null
+ */
+ void putNotification(Notification notification) throws InterruptedException;
+
+ /**
+ * Publishes a notification to subscribed listeners. This initiates
+ * the process of sending the notification, but delivery to the
+ * listeners can happen asynchronously, potentially after a call to
+ * this method returns.
+ *
+ * This method is guaranteed not to block.
+ *
+ * @param notification
+ * the notification to publish.
+ * @return true if the notification was accepted for processing, false otherwise
+ * @throws NullPointerException if the notification is null
+ */
+ boolean offerNotification(Notification notification);
+
+ /**
+ * Publishes a notification to subscribed listeners. This initiates
+ * the process of sending the notification, but delivery to the
+ * listeners can happen asynchronously, potentially after a call to
+ * this method returns. This method is guaranteed not to block more
+ * than the specified timeout.
+ *
+ * @param notification
+ * the notification to publish.
+ * @param timeout how long to wait before giving up, in units of unit
+ * @param unit a TimeUnit determining how to interpret the
+ * timeout parameter
+ * @return true if the notification was accepted for processing, false otherwise
+ * @throws InterruptedException if interrupted while waiting
+ * @throws NullPointerException if the notification or unit is null
+ * @throws IllegalArgumentException if timeout is negative.
+ */
+ boolean offerNotification(Notification notification, int timeout, TimeUnit unit)
+ throws InterruptedException;
+}
--- /dev/null
+/*
+ * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.opendaylight.controller.md.sal.binding.api;
+
+import org.opendaylight.yangtools.concepts.ListenerRegistration;
+import org.opendaylight.yangtools.yang.binding.NotificationListener;
+
+/**
+ * Notification broker which allows clients to subscribe for and publish YANG-modeled notifications.
+ *
+ * Each YANG module which defines notifications results in a generated 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 BindingService {
+ /**
+ * Registers a listener which implements a YANG-generated notification interface derived from
+ * {@link NotificationListener}. The listener is registered for all notifications present in
+ * the implemented interface.
+ *
+ * @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 NotificationListener> ListenerRegistration<T> registerNotificationListener(T listener);
+}
Code Review / controller.git / commitdiff