binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/DataTreeService.java

   1 /*
   2  * Copyright (c) 2015 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   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
   7  */
   8 package org.opendaylight.mdsal.binding.api;
   9
  10 import java.util.Collection;
  11 import org.eclipse.jdt.annotation.NonNull;
  12 import org.opendaylight.yangtools.concepts.ListenerRegistration;
  13
  14 /**
  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.
  18  *
  19  *<p>
  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.
  23  *
  24  *<p>
  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.
  30  */
  31 public interface DataTreeService extends DataTreeProducerFactory, BindingService {
  32     /**
  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
  37      * flaps).
  38      *
  39      *<p>
  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
  44      * invoked.
  45      *
  46      *<p>
  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
  49      * threads.
  50      *
  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
  61      */
  62     <T extends DataTreeListener> @NonNull ListenerRegistration<T> registerListener(@NonNull T listener,
  63             @NonNull Collection<DataTreeIdentifier<?>> subtrees, boolean allowRxMerges,
  64             @NonNull Collection<DataTreeProducer> producers) throws DataTreeLoopException;
  65 }