binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/NotificationPublishService.java

   1 /*
   2  * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.mdsal.binding.api;
   9
  10 import com.google.common.util.concurrent.ListenableFuture;
  11 import java.util.concurrent.TimeUnit;
  12 import org.eclipse.jdt.annotation.NonNull;
  13 import org.opendaylight.yangtools.util.concurrent.FluentFutures;
  14 import org.opendaylight.yangtools.yang.binding.Notification;
  15
  16 /**
  17  * A {@link NotificationService} which also allows its users to
  18  * submit YANG-modeled notifications for delivery. There are three
  19  * methods of submission, following the patters from {@link java.util.concurrent.BlockingQueue}:
  20  * - {@link #putNotification(Notification)}, which may block indefinitely
  21  *   if the implementation cannot allocate resources to accept the notification,
  22  * - {@link #offerNotification(Notification)}, which does not block if face
  23  *   of resource starvation,
  24  * - {@link #offerNotification(Notification, int, TimeUnit)}, which may block
  25  *   for specified time if resources are thin.
  26  *
  27  * <p>
  28  * The actual delivery to listeners is asynchronous and implementation-specific.
  29  * Users of this interface should not make any assumptions as to whether the
  30  * notification has or has not been seen.
  31  */
  32 public interface NotificationPublishService extends BindingService {
  33
  34     /**
  35      * Well-known value indicating that the binding-aware implementation is currently not
  36      * able to accept a notification.
  37      */
  38     ListenableFuture<Object> REJECTED = FluentFutures.immediateFailedFluentFuture(
  39             new NotificationRejectedException("Rejected due to resource constraints."));
  40
  41     /**
  42      * Publishes a notification to subscribed listeners. This initiates
  43      * the process of sending the notification, but delivery to the
  44      * listeners can happen asynchronously, potentially after a call to
  45      * this method returns.
  46      *
  47      * <b>Note:</b> This call will block when the notification queue is full.
  48      *
  49      * @param notification
  50      *            the notification to publish.
  51      * @throws InterruptedException if interrupted while waiting
  52      * @throws NullPointerException if the notification is null
  53      */
  54     void putNotification(@NonNull Notification notification) throws InterruptedException;
  55
  56     /**
  57      * Publishes a notification to subscribed listeners. This initiates the process of sending the
  58      * notification, but delivery to the listeners can happen asynchronously, potentially after a
  59      * call to this method returns.
  60      *
  61      * <p>
  62      * Still guaranteed not to block. Returns Listenable Future which will complete once.
  63      *
  64      * @param notification the notification to publish.
  65      * @return A listenable future which will report completion when the service has finished
  66      *         propagating the notification to its immediate registrants, or {@link #REJECTED} if
  67      *         resource constraints prevent
  68      * @throws NullPointerException if the notification is null
  69      */
  70     @NonNull ListenableFuture<? extends Object> offerNotification(@NonNull Notification notification);
  71
  72     /**
  73      * Publishes a notification to subscribed listeners. This initiates the process of sending the
  74      * notification, but delivery to the listeners can happen asynchronously, potentially after a
  75      * call to this method returns. This method is guaranteed not to block more than the specified
  76      * timeout.
  77      *
  78      * @param notification the notification to publish.
  79      * @param timeout how long to wait before giving up, in units of unit
  80      * @param unit a TimeUnit determining how to interpret the timeout parameter
  81      * @return A listenable future which will report completion when the service has finished
  82      *         propagating the notification to its immediate registrants, or {@link #REJECTED} if
  83      *         resource constraints prevent
  84      * @throws InterruptedException if interrupted while waiting
  85      * @throws NullPointerException if the notification or unit is null
  86      * @throws IllegalArgumentException if timeout is negative.
  87      */
  88     @NonNull ListenableFuture<? extends Object> offerNotification(@NonNull Notification notification,
  89             int timeout, @NonNull TimeUnit unit) throws InterruptedException;
  90 }