4c5ae16b0db016a8d970c7eaaf4ebd438cdb50d3
[controller.git] / opendaylight / md-sal / sal-common-api / src / main / java / org / opendaylight / controller / md / sal / common / api / notify / NotificationPublishService.java
1 /*
2  * Copyright (c) 2013 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.common.api.notify;
9
10 import java.util.concurrent.ExecutorService;
11
12 /**
13  * Interface for publishing YANG-modeled notifications.
14  *
15  * <p>
16  * Users of this interface can publish any YANG-modeled notification which will
17  * be delivered to all subscribed listeners.
18  *
19  * <p>
20  * Preferred way of publishing of notifications is done by invoking {@link #publish(Object)}.
21  *
22  * <p>You may consider using {@link #publish(Object, ExecutorService)} if and only if
23  * your use-case requires customized  execution policy or run-to-completion
24  * inside process.
25  *
26  * <p>
27  * The metadata required to deliver a notification to the correct listeners is
28  * extracted from the published notification.
29  *
30  * <p>
31  * FIXME: Consider clarification of execution/delivery policy, how it will be
32  * affected by Actor model and cluster-wide notifications.
33  *
34  * @param <N> the type of notifications
35  */
36 @Deprecated
37 public interface NotificationPublishService<N> {
38
39     /**
40      * Publishes a notification and notifies subscribed listeners. All listener
41      * notifications are done via a default executor.
42      *
43      * <p>
44      * <b>Note:</b> This call will block when the default executor is saturated
45      * and the notification queue for this executor is full.
46      *
47      * @param notification
48      *            the notification to publish.
49      */
50     void publish(N notification);
51
52     /**
53      * Publishes a notification and notifies subscribed listeners. All listener
54      * notifications are done via the provided executor.
55      *
56      * <p>
57      * <b>Note:</b> Use only if necessary. Consider using
58      * {@link #publish(Object)} for most use-cases.
59      *
60      * <p>
61      * By using this method you could customize execution policy of listeners present
62      * inside process (e.g. using  single-threaded executor or even same-thread executor
63      * delivery.
64      *
65      * <p>
66      * This executor is used only for inside-process notification deliveries.
67      *
68      * @param notification
69      *            the notification to publish.
70      * @param executor
71      *            the executor that will be used to deliver notifications to
72      *            subscribed listeners.
73      */
74     void publish(N notification, ExecutorService executor);
75 }

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