opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMDataTreeProducer.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.controller.md.sal.dom.api;
   9
  10 import java.util.Collection;
  11 import javax.annotation.Nonnull;
  12
  13 /**
  14  * A data producer context. It allows transactions to be submitted to the subtrees
  15  * specified at instantiation time. At any given time there may be a single transaction
  16  * open. It needs to be either submitted or cancelled before another one can be open.
  17  * Once a transaction is submitted, it will proceed to be committed asynchronously.
  18  *
  19  * <p>
  20  * Each instance has  an upper bound on the number of transactions which can be in-flight,
  21  * once that capacity is exceeded, an attempt to create a new transaction will block
  22  * until some transactions complete.
  23  *
  24  * <p>
  25  * Each {@link DOMDataTreeProducer} can be in two logical states, bound and unbound,
  26  * which define the lifecycle rules for when is it legal to create and submit transactions
  27  * in relationship with {@link DOMDataTreeListener} callbacks.
  28  *
  29  * <p>
  30  * When a producer is first created, it is unbound. In this state the producer can be
  31  * accessed by any application thread to allocate or submit transactions, as long as
  32  * the 'single open transaction' rule is maintained. The producer and any transaction
  33  * object MUST NOT be accessed, directly or indirectly, from a {@link DOMDataTreeListener}
  34  * callback.
  35  *
  36  * <p>
  37  * When a producer is referenced in a call to {@link DOMDataTreeService#registerListener(DOMDataTreeListener,
  38  * java.util.Collection, boolean, java.util.Collection)},
  39  * an attempt will be made to bind the producer to the specified {@link DOMDataTreeListener}.
  40  * Such an attempt will fail the producer is already bound, or it has an open transaction.
  41  * Once bound, the producer can only be accessed from within the {@link DOMDataTreeListener}
  42  * callback on that particular instance. Any transaction which is not submitted by the
  43  * time the callback returns will be implicitly cancelled. A producer becomes unbound
  44  * when the listener it is bound to becomes unregistered.
  45  *
  46  * @deprecated Use {@link org.opendaylight.mdsal.dom.api.DOMDataTreeProducer} instead.
  47  */
  48 @Deprecated
  49 public interface DOMDataTreeProducer extends DOMDataTreeProducerFactory, AutoCloseable {
  50     /**
  51      * Allocate a new open transaction on this producer. Any and all transactions
  52      * previously allocated must have been either submitted or cancelled by the
  53      * time this method is invoked.
  54      *
  55      * @param isolated Indicates whether this transaction should be a barrier. A barrier
  56      *                transaction is processed separately from any preceding transactions.
  57      *                Non-barrier transactions may be merged and processed in a batch,
  58      *                such that any observers see the modifications contained in them as
  59      *                if the modifications were made in a single transaction.
  60      * @return A new {@link DOMDataWriteTransaction}
  61      * @throws IllegalStateException if a previous transaction was not closed.
  62      * @throws IllegalThreadStateException if the calling thread context does not
  63      *         match the lifecycle rules enforced by the producer state (e.g. bound or unbound).
  64      *         This exception is thrown on a best effort basis and programs should not rely
  65      *         on it for correct operation.
  66      */
  67     @Nonnull DOMDataWriteTransaction createTransaction(boolean isolated);
  68
  69     /**
  70      * {@inheritDoc}
  71      *
  72      * <p>
  73      * When invoked on a {@link DOMDataTreeProducer}, this method has additional restrictions.
  74      * There may not be an open transaction from this producer. The method needs to be
  75      * invoked in appropriate context, e.g. bound or unbound.
  76      *
  77      * <p>
  78      * Specified subtrees must be accessible by this producer. Accessible means they are a subset
  79      * of the subtrees specified when the producer is instantiated. The set is further reduced as
  80      * child producers are instantiated -- if you create a producer for /a and then a child for
  81      * /a/b, /a/b is not accessible from the first producer.
  82      *
  83      * <p>
  84      * Once this method returns successfully, this (parent) producer loses the ability to
  85      * access the specified paths until the resulting (child) producer is shut down.
  86      *
  87      * @throws IllegalStateException if there is an open transaction
  88      * @throws IllegalArgumentException if subtrees contains a subtree which is not
  89      *         accessible by this producer
  90      * @throws IllegalThreadStateException if the calling thread context does not
  91      *         match the lifecycle rules enforced by the producer state (e.g. bound or unbound).
  92      *         This exception is thrown on a best effort basis and programs should not rely
  93      *         on it for correct operation.
  94      */
  95     @Override
  96     @Nonnull DOMDataTreeProducer createProducer(@Nonnull Collection<DOMDataTreeIdentifier> subtrees);
  97
  98     /**
  99      * {@inheritDoc}
 100      *
 101      * @throws DOMDataTreeProducerBusyException when there is an open transaction.
 102      */
 103     @Override
 104     void close() throws DOMDataTreeProducerException;
 105 }