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