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