Package org.opendaylight.controller.md.sal.dom.api

Interface DOMNotificationPublishService

  • All Superinterfaces:
    DOMService, org.opendaylight.mdsal.dom.api.DOMService
    @Deprecated(forRemoval=true)
public interface DOMNotificationPublishService
extends DOMService
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use DOMNotificationPublishService instead
    A DOMService which allows its user to send DOMNotifications. It provides two styles of initiating the notification delivery, similar to BlockingQueue: - a put-style method which waits until the implementation can accept the notification for delivery, and - an offer-style method, which attempts to enqueue the notification, but allows the caller to specify that it should never wait, or put an upper bound on how long it is going to wait.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static com.google.common.util.concurrent.ListenableFuture<Object> REJECTED
      Deprecated, for removal: This API element is subject to removal in a future version.
      Well-known value indicating that the implementation is currently not able to accept a notification.

    • Method Summary

      All Methods Instance Methods Abstract Methods Deprecated Methods 
      Modifier and Type Method Description
      @NonNull com.google.common.util.concurrent.ListenableFuture<?> offerNotification​(@NonNull DOMNotification notification)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Attempt to publish a notification.
      @NonNull com.google.common.util.concurrent.ListenableFuture<?> offerNotification​(@NonNull DOMNotification notification, long timeout, @NonNull TimeUnit unit)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Attempt to publish a notification.
      @NonNull com.google.common.util.concurrent.ListenableFuture<?> putNotification​(@NonNull DOMNotification notification)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Publish a notification.

    • Field Detail

      • REJECTED

        static final com.google.common.util.concurrent.ListenableFuture<Object> REJECTED
        Deprecated, for removal: This API element is subject to removal in a future version.
        Well-known value indicating that the implementation is currently not able to accept a notification.

    • Method Detail

      • putNotification

        @NonNull com.google.common.util.concurrent.ListenableFuture<?> putNotification​(@NonNull DOMNotification notification)
                                                                        throws InterruptedException
        Deprecated, for removal: This API element is subject to removal in a future version.
        Publish a notification. The result of this method is a ListenableFuture which will complete once the notification has been delivered to all immediate registrants. The type of the object resulting from the future is not defined and implementations may use it to convey additional information related to the publishing process.

        Abstract subclasses can refine the return type as returning a promise of a more specific type, e.g.: public interface DeliveryStatus { int getListenerCount(); } ListenableFuture<? extends DeliveryStatus> putNotification(DOMNotification notification);

        Once the Future succeeds, the resulting object can be queried for traits using instanceof, e.g: // Can block when (for example) the implemention's ThreadPool queue is full Object o = service.putNotification(notif).get(); if (o instanceof DeliveryStatus) { DeliveryStatus ds = (DeliveryStatus)o; LOG.debug("Notification was received by {} listeners", ds.getListenerCount();); }

        In case an implementation is running out of resources, it can block the calling thread until enough resources become available to accept the notification for processing, or it is interrupted.

        Caution: completion here means that the implementation has completed processing of the notification. This does not mean that all existing registrants have seen the notification. Most importantly, the delivery process at other cluster nodes may have not begun yet.

        Parameters:
        notification - Notification to be published.
        Returns:
        A listenable future which will report completion when the service has finished propagating the notification to its immediate registrants.
        Throws:
        InterruptedException - if interrupted while waiting
        NullPointerException - if notification is null.

      • offerNotification

        @NonNull com.google.common.util.concurrent.ListenableFuture<?> offerNotification​(@NonNull DOMNotification notification)
        Deprecated, for removal: This API element is subject to removal in a future version.
        Attempt to publish a notification. The result of this method is a ListenableFuture which will complete once the notification has been delivered to all immediate registrants. The type of the object resulting from the future is not defined and implementations may use it to convey additional information related to the publishing process. Unlike putNotification(DOMNotification), this method is guaranteed not to block if the underlying implementation encounters contention.
        Parameters:
        notification - Notification to be published.
        Returns:
        A listenable future which will report completion when the service has finished propagating the notification to its immediate registrants, or REJECTED if resource constraints prevent the implementation from accepting the notification for delivery.
        Throws:
        NullPointerException - if notification is null.

      • offerNotification

        @NonNull com.google.common.util.concurrent.ListenableFuture<?> offerNotification​(@NonNull DOMNotification notification,
                                                                                 long timeout,
                                                                                 @NonNull TimeUnit unit)
                                                                          throws InterruptedException
        Deprecated, for removal: This API element is subject to removal in a future version.
        Attempt to publish a notification. The result of this method is a ListenableFuture which will complete once the notification has been delivered to all immediate registrants. The type of the object resulting from the future is not defined and implementations may use it to convey additional information related to the publishing process. Unlike putNotification(DOMNotification), this method is guaranteed to block more than the specified timeout.
        Parameters:
        notification - Notification to be published.
        timeout - how long to wait before giving up, in units of unit, must not be negative
        unit - a TimeUnit determining how to interpret the timeout parameter
        Returns:
        A listenable future which will report completion when the service has finished propagating the notification to its immediate registrants, or REJECTED if resource constraints prevent the implementation from accepting the notification for delivery.
        Throws:
        InterruptedException - if interrupted while waiting
        NullPointerException - if notification or unit is null.
        IllegalArgumentException - if timeout is negative.