org.opendaylight.mdsal.dom.api

Interface DOMDataTreeProducer

All Superinterfaces:

AutoCloseable, DOMDataTreeProducerFactory

public interface DOMDataTreeProducer
extends DOMDataTreeProducerFactory, 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 DOMDataTreeProducer 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 DOMDataTreeListener 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 DOMDataTreeListener callback.

When a producer is referenced in a call to DOMDataTreeService.registerListener(DOMDataTreeListener, Collection, boolean, Collection), an attempt will be made to bind the producer to the specified DOMDataTreeListener. 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 DOMDataTreeListener 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() .
DOMDataTreeProducer	createProducer(Collection<DOMDataTreeIdentifier> subtrees) Create a producer, which is able to access to a set of trees.
DOMDataTreeCursorAwareTransaction	createTransaction(boolean isolated) Allocate a new open transaction on this producer.

Method Detail

createTransaction

@Nonnull
DOMDataTreeCursorAwareTransaction 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 DOMDataTreeCursorAwareTransaction

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
DOMDataTreeProducer createProducer(@Nonnull
                                            Collection<DOMDataTreeIdentifier> subtrees)

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

When invoked on a DOMDataTreeProducer, 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 DOMDataTreeProducerFactory

Parameters:

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

Returns:

A DOMDataTreeProducer 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 DOMDataTreeProducerException

.

Specified by:

close in interface AutoCloseable

Throws:

DOMDataTreeProducerBusyException - when there is an open transaction.

DOMDataTreeProducerException