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