2 * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
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
8 package org.opendaylight.controller.md.sal.binding.api;
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;
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.
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.
30 public interface NotificationPublishService extends BindingService {
33 * Well-known value indicating that the binding-aware implementation is currently not
34 * able to accept a notification.
36 ListenableFuture<Object> REJECTED = Futures.immediateFailedFuture(new NotificationRejectedException("Rejected due to resource constraints."));
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.
44 * <b>Note:</b> This call will block when the notification queue is full.
47 * the notification to publish.
48 * @throws InterruptedException if interrupted while waiting
49 * @throws NullPointerException if the notification is null
51 void putNotification(Notification notification) throws InterruptedException;
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.
59 * Still guaranteed not to block. Returns Listenable Future which will complete once.
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 {@link #REJECTED} if resource
66 * @throws NullPointerException if the notification is null
68 ListenableFuture<?> offerNotification(Notification notification);
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.
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
82 * @return A listenable future which will report completion when the service has finished
83 * propagating the notification to its immediate registrants, or {@link #REJECTED} if resource
85 * @throws InterruptedException if interrupted while waiting
86 * @throws NullPointerException if the notification or unit is null
87 * @throws IllegalArgumentException if timeout is negative.
89 ListenableFuture<?> offerNotification(Notification notification, int timeout, TimeUnit unit)
90 throws InterruptedException;