org.opendaylight.mdsal.binding.javav2.api

Interface DataTreeProducer

All Superinterfaces:

AutoCloseable, DataTreeProducerFactory

All Known Implementing Classes:

BindingDOMDataTreeProducerAdapter

@Beta
public interface DataTreeProducer
extends DataTreeProducerFactory, AutoCloseable

A data producer context. It allows transactions to be submitted to the subtrees specified at instantiation time. At any given time there may be a single transaction open. It needs to be either submitted or cancelled before another one can be open. Once a transaction is submitted, it will proceed to be committed asynchronously.

Each instance has an upper bound on the number of transactions which can be in-flight, once that capacity is exceeded, an attempt to create a new transaction will block until some transactions complete.

Each DataTreeProducer can be in two logical states, bound and unbound, which define the lifecycle rules for when is it legal to create and submit transactions in relationship with DataTreeListener callbacks.

When a producer is first created, it is unbound. In this state the producer can be accessed by any application thread to allocate or submit transactions, as long as the 'single open transaction' rule is maintained. The producer and any transaction object MUST NOT be accessed, directly or indirectly, from a DataTreeListener callback.

When a producer is referenced in a call to DataTreeService.registerListener(DataTreeListener, java.util.Collection, boolean, java.util.Collection) , an attempt will be made to bind the producer to the specified DataTreeListener. Such an attempt will fail the producer is already bound, or it has an open transaction. Once bound, the producer can only be accessed from within the DataTreeListener callback on that particular instance. Any transaction which is not submitted by the time the callback returns will be implicitly cancelled. A producer becomes unbound when the listener it is bound to becomes unregistered.

Method Summary

Modifier and Type	Method and Description
void	close() .
DataTreeProducer	createProducer(Collection<DataTreeIdentifier<?>> subtrees) Create a producer, which is able to access to a set of trees.
CursorAwareWriteTransaction	createTransaction(boolean isolated) Allocate a new open transaction on this producer.

Method Detail

createTransaction

@Nonnull
CursorAwareWriteTransaction createTransaction(boolean isolated)

Allocate a new open transaction on this producer. Any and all transactions previously allocated must have been either submitted or cancelled by the time this method is invoked.

Parameters:

isolated - Indicates whether this transaction should be a barrier. A barrier transaction is processed separately from any preceding transactions. Non-barrier transactions may be merged and processed in a batch, such that any observers see the modifications contained in them as if the modifications were made in a single transaction.

Returns:

A new CursorAwareWriteTransaction

Throws:

IllegalStateException - if a previous transaction was not closed.

IllegalThreadStateException - if the calling thread context does not match the lifecycle rules enforced by the producer state (e.g. bound or unbound). This exception is thrown on a best effort basis and programs should not rely on it for correct operation.

createProducer

@Nonnull
DataTreeProducer createProducer(@Nonnull
                                         Collection<DataTreeIdentifier<?>> subtrees)

Create a producer, which is able to access to a set of trees..

When invoked on a DataTreeProducer, this method has additional restrictions. There may not be an open transaction from this producer. The method needs to be invoked in appropriate context, e.g. bound or unbound.

Specified subtrees must be accessible by this producer. Accessible means they are a subset of the subtrees specified when the producer is instantiated. The set is further reduced as child producers are instantiated -- if you create a producer for /a and then a child for /a/b, /a/b is not accessible from the first producer.

Once this method returns successfully, this (parent) producer loses the ability to access the specified paths until the resulting (child) producer is shut down.

Specified by:

createProducer in interface DataTreeProducerFactory

Parameters:

subtrees - The collection of subtrees the resulting producer should have access to.

Returns:

A DataTreeProducer instance.

Throws:

IllegalStateException - if there is an open transaction

IllegalArgumentException - if subtrees contains a subtree which is not accessible by this producer

IllegalThreadStateException - if the calling thread context does not match the lifecycle rules enforced by the producer state (e.g. bound or unbound). This exception is thrown on a best effort basis and programs should not rely on it for correct operation.

close

void close()
    throws DataTreeProducerException

.

Specified by:

close in interface AutoCloseable

Throws:

DataTreeProducerBusyException - when there is an open transaction.

DataTreeProducerException