org.opendaylight.mdsal.dom.broker

Class DOMNotificationRouter

java.lang.Object

org.opendaylight.mdsal.dom.broker.DOMNotificationRouter

All Implemented Interfaces:

AutoCloseable, DOMNotificationPublishService, DOMNotificationService, DOMService, DOMNotificationSubscriptionListenerRegistry

public final class DOMNotificationRouter
extends Object
implements AutoCloseable, DOMNotificationPublishService, DOMNotificationService, DOMNotificationSubscriptionListenerRegistry

Joint implementation of DOMNotificationPublishService and DOMNotificationService. Provides routing of notifications from publishers to subscribers.

Internal implementation works by allocating a two-handler Disruptor. The first handler delivers notifications to subscribed listeners and the second one notifies whoever may be listening on the returned future. Registration state tracking is performed by a simple immutable multimap -- when a registration or unregistration occurs we re-generate the entire map from scratch and set it atomically. While registrations/unregistrations synchronize on this instance, notifications do not take any locks here.

The fully-blocking publish(long, DOMNotification, Collection) and non-blocking offerNotification(DOMNotification) are realized using the Disruptor's native operations. The bounded-blocking offerNotification(DOMNotification, long, TimeUnit) is realized by arming a background wakeup interrupt.

Field Summary

Fields inherited from interface org.opendaylight.mdsal.dom.api.DOMNotificationPublishService

REJECTED

Method Summary

Modifier and Type	Method and Description
void	close()
static DOMNotificationRouter	create(int queueDepth)
static DOMNotificationRouter	create(int queueDepth, long spinTime, long parkTime, TimeUnit unit)
com.google.common.util.concurrent.ListenableFuture<? extends Object>	offerNotification(DOMNotification notification) Attempt to publish a notification.
com.google.common.util.concurrent.ListenableFuture<? extends Object>	offerNotification(DOMNotification notification, long timeout, TimeUnit unit) Attempt to publish a notification.
com.google.common.util.concurrent.ListenableFuture<? extends Object>	putNotification(DOMNotification notification) Publish a notification.
<T extends DOMNotificationListener> org.opendaylight.yangtools.concepts.ListenerRegistration<T>	registerNotificationListener(T listener, Collection<org.opendaylight.yangtools.yang.model.api.SchemaPath> types) Register a DOMNotificationListener to receive a set of notifications.
<T extends DOMNotificationListener> org.opendaylight.yangtools.concepts.ListenerRegistration<T>	registerNotificationListener(T listener, org.opendaylight.yangtools.yang.model.api.SchemaPath... types) Register a DOMNotificationListener to receive a set of notifications.
<L extends DOMNotificationSubscriptionListener> org.opendaylight.yangtools.concepts.ListenerRegistration<L>	registerSubscriptionListener(L listener)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static DOMNotificationRouter create(int queueDepth)

create

public static DOMNotificationRouter create(int queueDepth,
                                           long spinTime,
                                           long parkTime,
                                           TimeUnit unit)

registerNotificationListener

public <T extends DOMNotificationListener> org.opendaylight.yangtools.concepts.ListenerRegistration<T> registerNotificationListener(T listener,
                                                                                                                                    Collection<org.opendaylight.yangtools.yang.model.api.SchemaPath> types)

Description copied from interface: DOMNotificationService

Register a DOMNotificationListener to receive a set of notifications. As with other ListenerRegistration-based interfaces, registering an instance multiple times results in notifications being delivered for each registration.

Specified by:

registerNotificationListener in interface DOMNotificationService

Parameters:

listener - Notification instance to register

types - Notification types which should be delivered to the listener. Duplicate entries are processed only once, null entries are ignored.

Returns:

Registration handle. Invoking ListenerRegistration.close() will stop the delivery of notifications to the listener

registerNotificationListener

public <T extends DOMNotificationListener> org.opendaylight.yangtools.concepts.ListenerRegistration<T> registerNotificationListener(T listener,
                                                                                                                                    org.opendaylight.yangtools.yang.model.api.SchemaPath... types)

Description copied from interface: DOMNotificationService

Register a DOMNotificationListener to receive a set of notifications. As with other ListenerRegistration-based interfaces, registering an instance multiple times results in notifications being delivered for each registration.

Specified by:

registerNotificationListener in interface DOMNotificationService

Parameters:

listener - Notification instance to register

types - Notification types which should be delivered to the listener. Duplicate entries are processed only once, null entries are ignored.

Returns:

Registration handle. Invoking ListenerRegistration.close() will stop the delivery of notifications to the listener

registerSubscriptionListener

public <L extends DOMNotificationSubscriptionListener> org.opendaylight.yangtools.concepts.ListenerRegistration<L> registerSubscriptionListener(L listener)

Specified by:

registerSubscriptionListener in interface DOMNotificationSubscriptionListenerRegistry

putNotification

public com.google.common.util.concurrent.ListenableFuture<? extends Object> putNotification(DOMNotification notification)
                                                                                     throws InterruptedException

Description copied from interface: DOMNotificationPublishService

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.

Specified by:

putNotification in interface DOMNotificationPublishService

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

offerNotification

public com.google.common.util.concurrent.ListenableFuture<? extends Object> offerNotification(DOMNotification notification)

Description copied from interface: DOMNotificationPublishService

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 DOMNotificationPublishService.putNotification(DOMNotification), this method is guaranteed not to block if the underlying implementation encounters contention.

Specified by:

offerNotification in interface DOMNotificationPublishService

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 DOMNotificationPublishService.REJECTED if resource constraints prevent the implementation from accepting the notification for delivery.

offerNotification

public com.google.common.util.concurrent.ListenableFuture<? extends Object> offerNotification(DOMNotification notification,
                                                                                              long timeout,
                                                                                              TimeUnit unit)
                                                                                       throws InterruptedException

Description copied from interface: DOMNotificationPublishService

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 DOMNotificationPublishService.putNotification(DOMNotification), this method is guaranteed to block more than the specified timeout.

Specified by:

offerNotification in interface DOMNotificationPublishService

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 DOMNotificationPublishService.REJECTED if resource constraints prevent the implementation from accepting the notification for delivery.

Throws:

InterruptedException - if interrupted while waiting

close

public void close()

Specified by:

close in interface AutoCloseable