org.opendaylight.mdsal.dom.api

Interface DOMDataTreeService

All Superinterfaces:

DOMDataTreeProducerFactory, DOMExtensibleService<DOMDataTreeService,DOMDataTreeServiceExtension>, DOMService

All Known Implementing Classes:

ShardedDOMDataTree

public interface DOMDataTreeService
extends DOMDataTreeProducerFactory, DOMExtensibleService<DOMDataTreeService,DOMDataTreeServiceExtension>

A DOMService providing access to the conceptual data tree. Interactions with the data tree are split into data producers and consumers (listeners). Each of them operate on a set of subtrees, which need to be declared at instantiation time.

Returned instances are not thread-safe and expected to be used by a single thread at a time. Furthermore, producers may not be accessed from consumer callbacks unless they were specified when the listener is registered.

The service maintains a loop-free topology of producers and consumers. What this means is that a consumer is not allowed to access a producer, which affects any of the subtrees it is subscribed to. This restriction is in place to ensure the system does not go into a feedback loop, where it is impossible to block either a producer or a consumer without accumulating excess work in the backlog stemming from its previous activity.

Method Summary

Modifier and Type	Method and Description
<T extends DOMDataTreeListener> @NonNull org.opendaylight.yangtools.concepts.ListenerRegistration<T>	registerListener(T listener, @NonNull Collection<DOMDataTreeIdentifier> subtrees, boolean allowRxMerges, @NonNull Collection<DOMDataTreeProducer> producers) Register a DOMDataTreeListener instance.

Methods inherited from interface org.opendaylight.mdsal.dom.api.DOMDataTreeProducerFactory

createProducer

Methods inherited from interface org.opendaylight.mdsal.dom.api.DOMExtensibleService

getExtensions

Method Detail

registerListener

<T extends DOMDataTreeListener> @NonNull org.opendaylight.yangtools.concepts.ListenerRegistration<T> registerListener(T listener,
                                                                                                                      @NonNull Collection<DOMDataTreeIdentifier> subtrees,
                                                                                                                      boolean allowRxMerges,
                                                                                                                      @NonNull Collection<DOMDataTreeProducer> producers)
                                                                                                               throws DOMDataTreeLoopException

Register a DOMDataTreeListener instance. Once registered, the listener will start receiving changes on the selected subtrees. If the listener cannot keep up with the rate of changes, and allowRxMerges is set to true, this service is free to merge the changes, so that a smaller number of them will be reported, possibly hiding some data transitions (like flaps).

If the listener wants to write into any producer, that producer has to be mentioned in the call to this method. Those producers will be bound exclusively to the registration, so that accessing them outside of this listener's callback will trigger an error. Any producers mentioned must be idle, e.g. they may not have an open transaction at the time this method is invoked.

Each listener instance can be registered at most once. Implementations of this interface have to guarantee that the listener's methods will not be invoked concurrently from multiple threads.

Parameters:

listener - DOMDataTreeListener that is being registered

subtrees - Conceptual subtree identifier of subtrees which should be monitored for changes. May not be null or empty.

allowRxMerges - True if the backend may perform ingress state compression.

producers - DOMDataTreeProducer instances to bind to the listener.

Returns:

A listener registration. Once closed, the listener will no longer be invoked and the producers will be unbound.

Throws:

IllegalArgumentException - if subtrees is empty or the listener is already bound

DOMDataTreeLoopException - if the registration of the listener to the specified subtrees with specified producers would form a feedback loop