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 }