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