org.opendaylight.mdsal.dom.api

Interface DOMNotificationPublishService

All Superinterfaces:

DOMService

All Known Implementing Classes:

DOMNotificationRouter, ForwardingDOMNotificationPublishService

public interface DOMNotificationPublishService
extends DOMService

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 and Description
static com.google.common.util.concurrent.ListenableFuture<Object>	REJECTED Well-known value indicating that the implementation is currently not able to accept a notification.

Method Summary

Modifier and Type	Method and Description
@NonNull com.google.common.util.concurrent.ListenableFuture<? extends Object>	offerNotification(@NonNull DOMNotification notification) Attempt to publish a notification.
@NonNull com.google.common.util.concurrent.ListenableFuture<? extends Object>	offerNotification(@NonNull DOMNotification notification, long timeout, @NonNull TimeUnit unit) Attempt to publish a notification.
@NonNull com.google.common.util.concurrent.ListenableFuture<? extends Object>	putNotification(@NonNull DOMNotification notification) Publish a notification.

Field Detail

REJECTED

static final com.google.common.util.concurrent.ListenableFuture<Object> REJECTED

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<? extends Object> putNotification(@NonNull DOMNotification notification)
                                                                                       throws InterruptedException

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<? extends Object> offerNotification(@NonNull DOMNotification notification)

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<? extends Object> offerNotification(@NonNull DOMNotification notification,
                                                                                                @Nonnegative
                                                                                                long timeout,
                                                                                                @NonNull TimeUnit unit)
                                                                                         throws InterruptedException

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

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.