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

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.