X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;ds=sidebyside;f=opendaylight%2Fmd-sal%2Fsal-common-api%2Fsrc%2Fmain%2Fjava%2Forg%2Fopendaylight%2Fcontroller%2Fmd%2Fsal%2Fcommon%2Fapi%2Fnotify%2FNotificationPublishService.java;h=bb866f276e713151ccf18b0e57e589c65633647f;hb=c46e223995956f1f759c551163c212947c1e2fb7;hp=f5f03a106b36119b188ca489924d514f88b12f00;hpb=b1ad47e987f7e73ebcd44f2076f57550715f75d6;p=controller.git diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/notify/NotificationPublishService.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/notify/NotificationPublishService.java index f5f03a106b..bb866f276e 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/notify/NotificationPublishService.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/notify/NotificationPublishService.java @@ -9,9 +9,63 @@ package org.opendaylight.controller.md.sal.common.api.notify; import java.util.concurrent.ExecutorService; +/** + * Interface for publishing YANG-modeled notifications. + *
+ * Users of this interface can publish any YANG-modeled notification which will + * be delivered to all subscribed listeners. + *
+ * Prefered way of publishing of notifications is done by invoking {@link #publish(Object)}. + * + *
You may consider using {@link #publish(Object, ExecutorService)} if and only if + * your use-case requires customized execution policy or run-to-completion + * inside process. + * + *
+ * The metadata required to deliver a notification to the correct listeners is
+ * extracted from the published notification.
+ *
+ *
+ * FIXME: Consider clarification of execution/delivery policy, how it will be
+ * affected by Actor model and cluster-wide notifications.
+ *
+ * @param
+ * Note: This call will block when the default executor is saturated
+ * and the notification queue for this executor is full.
+ *
+ * @param notification
+ * the notification to publish.
+ */
void publish(N notification);
- void publish(N notification,ExecutorService executor);
+ /**
+ * Publishes a notification and notifies subscribed listeners. All listener
+ * notifications are done via the provided executor.
+ *
+ * Note: Use only if ineccessary. Consider using
+ * {@link #publish(Object)} for most use-cases.
+ *
+ *
+ * By using this method you could customize execution policy of listeners present
+ * inside process (e.g. using single-threaded executor or even same-thread executor
+ * delivery.
+ *
+ *
+ * This executor is used only for inside-process notification deliveries.
+ *
+ * @param notification
+ * the notification to publish.
+ * @param executor
+ * the executor that will be used to deliver notifications to
+ * subscribed listeners.
+ */
+ void publish(N notification, ExecutorService executor);
}