5ec51269b738df3e7625133773a2d72cf1af7705
[controller.git] / 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  * The actual delivery to listeners is asynchronous and implementation-specific.
27  * Users of this interface should not make any assumptions as to whether the
28  * notification has or has not been seen.
29  */
30 public interface NotificationPublishService extends BindingService {
31
32     /**
33      * Well-known value indicating that the binding-aware implementation is currently not
34      * able to accept a notification.
35      */
36     ListenableFuture<Object> REJECTED = Futures.immediateFailedFuture(new NotificationRejectedException("Rejected due to resource constraints."));
37
38     /**
39      * Publishes a notification to subscribed listeners. This initiates
40      * the process of sending the notification, but delivery to the
41      * listeners can happen asynchronously, potentially after a call to
42      * this method returns.
43      *
44      * <b>Note:</b> This call will block when the notification queue is full.
45      *
46      * @param notification
47      *            the notification to publish.
48      * @throws InterruptedException if interrupted while waiting
49      * @throws NullPointerException if the notification is null
50      */
51     void putNotification(Notification notification) throws InterruptedException;
52
53     /**
54      * Publishes a notification to subscribed listeners. This initiates
55      * the process of sending the notification, but delivery to the
56      * listeners can happen asynchronously, potentially after a call to
57      * this method returns.
58      *
59      * Still guaranteed not to block. Returns Listenable Future which will complete once.
60      *
61      * @param notification
62      *            the notification to publish.
63      * @return A listenable future which will report completion when the service has finished
64      * propagating the notification to its immediate registrants, or {@value #REJECTED} if resource
65      * constraints prevent
66      * @throws NullPointerException if the notification is null
67      */
68     ListenableFuture<? extends Object> offerNotification(Notification notification);
69
70     /**
71      * Publishes a notification to subscribed listeners. This initiates
72      * the process of sending the notification, but delivery to the
73      * listeners can happen asynchronously, potentially after a call to
74      * this method returns. This method is guaranteed not to block more
75      * than the specified timeout.
76      *
77      * @param notification
78      *            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
81      *             timeout parameter
82      * @return A listenable future which will report completion when the service has finished
83      * propagating the notification to its immediate registrants, or {@value #REJECTED} if resource
84      * constraints prevent
85      * @throws InterruptedException if interrupted while waiting
86      * @throws NullPointerException if the notification or unit is null
87      * @throws IllegalArgumentException if timeout is negative.
88      */
89     ListenableFuture<? extends Object> offerNotification(Notification notification, int timeout, TimeUnit unit)
90             throws InterruptedException;
91
92 }

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.