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 }