Deprecate old MD-SAL APIs for removal
[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  * <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(forRemoval = true)
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 }

©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.