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

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