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 java.util.concurrent.TimeUnit;
  11 import org.opendaylight.yangtools.yang.binding.Notification;
  12
  13 /**
  14  * A {@link NotificationService} which also allows its users to
  15  * submit YANG-modeled notifications for delivery. There are three
  16  * methods of submission, following the patters from {@link java.util.concurrent.BlockingQueue}:
  17  * - {@link #putNotification(Notification)}, which may block indefinitely
  18  *   if the implementation cannot allocate resources to accept the notification,
  19  * - {@link #offerNotification(Notification)}, which does not block if face
  20  *   of resource starvation,
  21  * - {@link #offerNotification(Notification, int, TimeUnit)}, which may block
  22  *   for specified time if resources are thin.
  23  *
  24  * The actual delivery to listeners is asynchronous and implementation-specific.
  25  * Users of this interface should not make any assumptions as to whether the
  26  * notification has or has not been seen.
  27  */
  28 public interface NotificationPublishService extends BindingService {
  29     /**
  30      * Publishes a notification to subscribed listeners. This initiates
  31      * the process of sending the notification, but delivery to the
  32      * listeners can happen asynchronously, potentially after a call to
  33      * this method returns.
  34      *
  35      * <b>Note:</b> This call will block when the notification queue is full.
  36      *
  37      * @param notification
  38      *            the notification to publish.
  39      * @throws InterruptedException if interrupted while waiting
  40      * @throws NullPointerException if the notification is null
  41      */
  42     void putNotification(Notification notification) throws InterruptedException;
  43
  44     /**
  45      * Publishes a notification to subscribed listeners. This initiates
  46      * the process of sending the notification, but delivery to the
  47      * listeners can happen asynchronously, potentially after a call to
  48      * this method returns.
  49      *
  50      * This method is guaranteed not to block.
  51      *
  52      * @param notification
  53      *            the notification to publish.
  54      * @return true if the notification was accepted for processing, false otherwise
  55      * @throws NullPointerException if the notification is null
  56      */
  57     boolean offerNotification(Notification notification);
  58
  59     /**
  60      * Publishes a notification to subscribed listeners. This initiates
  61      * the process of sending the notification, but delivery to the
  62      * listeners can happen asynchronously, potentially after a call to
  63      * this method returns. This method is guaranteed not to block more
  64      * than the specified timeout.
  65      *
  66      * @param notification
  67      *            the notification to publish.
  68      * @param timeout how long to wait before giving up, in units of unit
  69      * @param unit a TimeUnit determining how to interpret the
  70      *             timeout parameter
  71      * @return true if the notification was accepted for processing, false otherwise
  72      * @throws InterruptedException if interrupted while waiting
  73      * @throws NullPointerException if the notification or unit is null
  74      * @throws IllegalArgumentException if timeout is negative.
  75      */
  76     boolean offerNotification(Notification notification, int timeout, TimeUnit unit)
  77         throws InterruptedException;
  78 }