*/
package org.opendaylight.mdsal.binding.api;
-import com.google.common.util.concurrent.Futures;
import com.google.common.util.concurrent.ListenableFuture;
import java.util.concurrent.TimeUnit;
+import org.eclipse.jdt.annotation.NonNull;
+import org.opendaylight.yangtools.util.concurrent.FluentFutures;
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.
+ * A {@link BindingService} which allows its users to submit YANG-modeled top-level (YANG 1) {@link Notification}s for
+ * delivery. There are three methods of submission, following the patters from
+ * {@link java.util.concurrent.BlockingQueue}:
+ * <ul>
+ * <li>{@link #putNotification(Notification)}, which may block indefinitely if the implementation cannot allocate
+ * resources to accept the notification,</li>
+ * <li>{@link #offerNotification(Notification)}, which does not block if face of resource starvation,</li>
+ * <li>{@link #offerNotification(Notification, int, TimeUnit)}, which may block for specified time if resources are
+ * thin.</li>
+ * </ul>
*
- *<p>
- * 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.
+ * <p>
+ * 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 {
-
/**
- * Well-known value indicating that the binding-aware implementation is currently not
- * able to accept a notification.
+ * Well-known value indicating that the binding-aware implementation is currently not able to accept a notification.
*/
- ListenableFuture<Object> REJECTED = Futures.immediateFailedFuture(
+ @NonNull ListenableFuture<Object> REJECTED = FluentFutures.immediateFailedFluentFuture(
new NotificationRejectedException("Rejected due to resource constraints."));
/**
- * 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.
+ * 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.
+ * @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;
+ void putNotification(@NonNull 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.
+ * 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.
*
* <p>
* Still guaranteed not to block. Returns Listenable Future which will complete once.
*
* @param notification the notification to publish.
- * @return A listenable future which will report completion when the service has finished
- * propagating the notification to its immediate registrants, or {@link #REJECTED} if
- * resource constraints prevent
+ * @return A listenable future which will report completion when the service has finished propagating the
+ * notification to its immediate registrants, or {@link #REJECTED} if resource constraints prevent
* @throws NullPointerException if the notification is null
*/
- ListenableFuture<? extends Object> offerNotification(Notification notification);
+ @NonNull ListenableFuture<? extends Object> offerNotification(@NonNull 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.
+ * 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 A listenable future which will report completion when the service has finished
- * propagating the notification to its immediate registrants, or {@link #REJECTED} if
- * resource constraints prevent
+ * @return A listenable future which will report completion when the service has finished propagating the
+ * notification to its immediate registrants, or {@link #REJECTED} if resource constraints prevent
* @throws InterruptedException if interrupted while waiting
* @throws NullPointerException if the notification or unit is null
* @throws IllegalArgumentException if timeout is negative.
*/
- ListenableFuture<? extends Object> offerNotification(Notification notification, int timeout, TimeUnit unit)
- throws InterruptedException;
-
+ @NonNull ListenableFuture<? extends Object> offerNotification(@NonNull Notification<?> notification,
+ int timeout, @NonNull TimeUnit unit) throws InterruptedException;
}
Code Review / mdsal.git / blobdiff