2 * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved.
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
8 package org.opendaylight.mdsal.binding.api;
10 import java.util.Collection;
11 import javax.annotation.Nonnull;
12 import org.opendaylight.yangtools.concepts.ListenerRegistration;
15 * A {@link BindingService} providing access to the conceptual data tree. Interactions with the data
16 * tree are split into data producers and consumers (listeners). Each of them operate on a set of
17 * subtrees, which need to be declared at instantiation time.
20 * Returned instances are not thread-safe and expected to be used by a single thread at a time.
21 * Furthermore, producers may not be accessed from consumer callbacks unless they were specified
22 * when the listener is registered.
25 * The service maintains a loop-free topology of producers and consumers. What this means is that a
26 * consumer is not allowed to access a producer, which affects any of the subtrees it is subscribed
27 * to. This restriction is in place to ensure the system does not go into a feedback loop, where it
28 * is impossible to block either a producer or a consumer without accumulating excess work in the
29 * backlog stemming from its previous activity.
31 public interface DataTreeService extends DataTreeProducerFactory, BindingService {
33 * Register a {@link DataTreeListener} instance. Once registered, the listener will start
34 * receiving changes on the selected subtrees. If the listener cannot keep up with the rate of
35 * changes, and allowRxMerges is set to true, this service is free to merge the changes, so that
36 * a smaller number of them will be reported, possibly hiding some data transitions (like
40 * If the listener wants to write into any producer, that producer has to be mentioned in the
41 * call to this method. Those producers will be bound exclusively to the registration, so that
42 * accessing them outside of this listener's callback will trigger an error. Any producers
43 * mentioned must be idle, e.g. they may not have an open transaction at the time this method is
47 * Each listener instance can be registered at most once. Implementations of this interface have
48 * to guarantee that the listener's methods will not be invoked concurrently from multiple
51 * @param listener {@link DataTreeListener} that is being registered
52 * @param subtrees Conceptual subtree identifier of subtrees which should be monitored for
53 * changes. May not be null or empty.
54 * @param allowRxMerges True if the backend may perform ingress state compression.
55 * @param producers {@link DataTreeProducer} instances to bind to the listener.
56 * @return A listener registration. Once closed, the listener will no longer be invoked and the
57 * producers will be unbound.
58 * @throws IllegalArgumentException if subtrees is empty or the listener is already bound
59 * @throws DataTreeLoopException if the registration of the listener to the specified subtrees
60 * with specified producers would form a feedback loop
63 <T extends DataTreeListener> ListenerRegistration<T> registerListener(@Nonnull T listener,
64 @Nonnull Collection<DataTreeIdentifier<?>> subtrees, boolean allowRxMerges,
65 @Nonnull Collection<DataTreeProducer> producers) throws DataTreeLoopException;