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 java.util.concurrent.TimeUnit;
11 import org.opendaylight.yangtools.yang.binding.Notification;
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.
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.
28 public interface NotificationPublishService extends BindingService {
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.
35 * <b>Note:</b> This call will block when the notification queue is full.
38 * the notification to publish.
39 * @throws InterruptedException if interrupted while waiting
40 * @throws NullPointerException if the notification is null
42 void putNotification(Notification notification) throws InterruptedException;
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.
50 * This method is guaranteed not to block.
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
57 boolean offerNotification(Notification notification);
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.
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
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.
76 boolean offerNotification(Notification notification, int timeout, TimeUnit unit)
77 throws InterruptedException;