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 javax.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  * Returned instances are not thread-safe and expected to be used by a single thread at a time.
  20  * Furthermore, producers may not be accessed from consumer callbacks unless they were specified
  21  * when the listener is registered.
  22  *
  23  * The service maintains a loop-free topology of producers and consumers. What this means is that a
  24  * consumer is not allowed to access a producer, which affects any of the subtrees it is subscribed
  25  * to. This restriction is in place to ensure the system does not go into a feedback loop, where it
  26  * is impossible to block either a producer or a consumer without accumulating excess work in the
  27  * backlog stemming from its previous activity.
  28  */
  29 public interface DataTreeService extends DataTreeProducerFactory, BindingService {
  30     /**
  31      * Register a {@link DataTreeListener} instance. Once registered, the listener will start
  32      * receiving changes on the selected subtrees. If the listener cannot keep up with the rate of
  33      * changes, and allowRxMerges is set to true, this service is free to merge the changes, so that
  34      * a smaller number of them will be reported, possibly hiding some data transitions (like
  35      * flaps).
  36      *
  37      * If the listener wants to write into any producer, that producer has to be mentioned in the
  38      * call to this method. Those producers will be bound exclusively to the registration, so that
  39      * accessing them outside of this listener's callback will trigger an error. Any producers
  40      * mentioned must be idle, e.g. they may not have an open transaction at the time this method is
  41      * invoked.
  42      *
  43      * Each listener instance can be registered at most once. Implementations of this interface have
  44      * to guarantee that the listener's methods will not be invoked concurrently from multiple
  45      * threads.
  46      *
  47      * @param listener {@link DataTreeListener} that is being registered
  48      * @param subtrees Conceptual subtree identifier of subtrees which should be monitored for
  49      *        changes. May not be null or empty.
  50      * @param allowRxMerges True if the backend may perform ingress state compression.
  51      * @param producers {@link DataTreeProducer} instances to bind to the listener.
  52      * @return A listener registration. Once closed, the listener will no longer be invoked and the
  53      *         producers will be unbound.
  54      * @throws IllegalArgumentException if subtrees is empty or the listener is already bound
  55      * @throws DataTreeLoopException if the registration of the listener to the specified subtrees
  56      *         with specified producers would form a feedback loop
  57      */
  58     @Nonnull
  59     <T extends DataTreeListener> ListenerRegistration<T> registerListener(@Nonnull T listener,
  60             @Nonnull Collection<DataTreeIdentifier<?>> subtrees, boolean allowRxMerges,
  61             @Nonnull Collection<DataTreeProducer> producers) throws DataTreeLoopException;
  62 }