X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=opendaylight%2Fmd-sal%2Fsal-common-api%2Fsrc%2Fmain%2Fjava%2Forg%2Fopendaylight%2Fcontroller%2Fmd%2Fsal%2Fcommon%2Fapi%2Fdata%2FAsyncDataTransactionFactory.java;h=a558b96b2d56fa26658741d8ee11ac63f3e735a3;hb=49346407810110d0cf9ed7fc9470e0fbb4562499;hp=732fed0f3f482466ee3a4acb682b73f6826ea8ea;hpb=2a4c88aa665a45c5394642cb3604603bebf8c0da;p=controller.git diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataTransactionFactory.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataTransactionFactory.java index 732fed0f3f..a558b96b2d 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataTransactionFactory.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataTransactionFactory.java @@ -9,12 +9,110 @@ package org.opendaylight.controller.md.sal.common.api.data; import org.opendaylight.yangtools.concepts.Path; +/** + * A factory which allocates new transactions to operate on the data + * tree. + * + *
+ * Note: This interface is not intended to be used directly, but rather + * via subinterfaces which introduces additional semantics to allocated + * transactions. + *
+ * All operations on the data tree are performed via one of the transactions: + *
+ * These transactions provides a stable isolated view of the data tree, which is + * guaranteed to be not affected by other concurrent transactions, until + * transaction is committed. + * + *
+ * For a detailed explanation of how transaction are isolated and how transaction-local + * changes are committed to global data tree, see + * {@link AsyncReadTransaction}, {@link AsyncWriteTransaction}, + * {@link AsyncReadWriteTransaction} and {@link AsyncWriteTransaction#commit()}. + * + *
+ * It is strongly recommended to use the type of transaction, which + * provides only the minimal capabilities you need. This allows for + * optimizations at the data broker / data store level. For example, + * implementations may optimize the transaction for reading if they know ahead + * of time that you only need to read data - such as not keeping additional meta-data, + * which may be required for write transactions. + *
+ * Implementation Note: This interface is not intended to be implemented + * by users of MD-SAL, but only to be consumed by them. + * + * @see AsyncDataBroker + * @see TransactionChain + * + * @param
+ * Type of path (subtree identifier), which represents location in
+ * tree
+ * @param , D> {
- AsyncReadTransaction newReadOnlyTransaction();
+ /**
+ * Allocates a new read-only transaction which provides an immutable snapshot of
+ * the data tree.
+ *
+ * The view of data tree is an immutable snapshot of current data tree state when
+ * transaction was allocated.
+ *
+ * @return new read-only transaction
+ */
+ AsyncReadOnlyTransaction newReadOnlyTransaction();
+ /**
+ * Allocates new read-write transaction which provides a mutable view of the data
+ * tree.
+ *
+ *
+ * Preconditions for mutation of data tree are captured from the snapshot of
+ * data tree state, when the transaction is allocated. If data was
+ * changed during transaction in an incompatible way then the commit of this transaction
+ * will fail. See {@link AsyncWriteTransaction#commit()} for more
+ * details about conflicting and not-conflicting changes and
+ * failure scenarios.
+ *
+ * @return new read-write transaction
+ */
AsyncReadWriteTransaction newReadWriteTransaction();
- AsyncWriteTransaction newWriteOnlyTransaction();
+ /**
+ * Allocates new write-only transaction based on latest state of data
+ * tree.
+ *
+ *
+ * Preconditions for mutation of data tree are captured from the snapshot of
+ * data tree state, when the transaction is allocated. If data was
+ * changed during transaction in an incompatible way then the commit of this transaction
+ * will fail. See {@link AsyncWriteTransaction#commit()} for more
+ * details about conflicting and not-conflicting changes and
+ * failure scenarios.
+ *
+ *
+ * Since this transaction does not provide a view of the data it SHOULD BE
+ * used only by callers which are exclusive writers (exporters of data)
+ * to the subtree they modify. This prevents optimistic
+ * lock failures as described in {@link AsyncWriteTransaction#commit()}.
+ *
+ * Exclusivity of writers to particular subtree SHOULD BE enforced by
+ * external locking mechanism.
+ *
+ * @return new write-only transaction
+ */
+ AsyncWriteTransaction newWriteOnlyTransaction();
}