Deprecate ClassToInstance-taking methods

[mdsal.git] / binding / mdsal-binding-api / src / main / java / org / opendaylight / mdsal / binding / api / ReadTransaction.java

diff --git a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/ReadTransaction.java b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/ReadTransaction.java
index 65de216381c2b560ea39a2efc4db7058f990736a..6308be5e5d7954b0f7ee548017f9032548839940 100644 (file)
--- a/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/ReadTransaction.java
+++ b/binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/ReadTransaction.java
@@ -7,46 +7,45 @@
  */
 package org.opendaylight.mdsal.binding.api;
 
-import com.google.common.base.Optional;
-import com.google.common.util.concurrent.FluentFuture;
-import org.opendaylight.mdsal.common.api.AsyncReadTransaction;
-import org.opendaylight.mdsal.common.api.LogicalDatastoreType;
-import org.opendaylight.mdsal.common.api.ReadFailedException;
-import org.opendaylight.yangtools.yang.binding.DataObject;
-import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
-
-
 /**
  * A transaction that provides a stateful read-only view of the data tree.
  *
  * <p>
- * For more information on usage and examples, please see the documentation in
- *  {@link org.opendaylight.mdsal.common.api.AsyncReadTransaction}.
+ * View of the data tree is a stable point-in-time snapshot of the current data tree state when the
+ * transaction was created. It's state and underlying data tree is not affected by other
+ * concurrently running transactions.
+ *
+ * <p>
+ * <b>Implementation Note:</b> This interface is not intended to be implemented by users of MD-SAL,
+ * but only to be consumed by them.
+ *
+ * <h2>Transaction isolation example</h2>
+ * Lets assume initial state of data tree for <code>PATH</code> is <code>A</code>.
+ *
+ * <code>
+ * txRead = broker.newReadOnlyTransaction(); // read Transaction is snapshot of data
+ * txWrite = broker.newReadWriteTransactoin(); // concurrent write transaction
+ * txRead.read(OPERATIONAL, PATH).get(); // will return Optional containing A
+ * txWrite = broker.put(OPERATIONAL, PATH, B); // writes B to PATH
+ * txRead.read(OPERATIONAL, PATH).get(); // still returns Optional containing A
+ * txWrite.submit().get(); // data tree is updated, PATH contains B
+ * txRead.read(OPERATIONAL, PATH).get(); // still returns Optional containing A
+ * txAfterCommit = broker.newReadOnlyTransaction(); // read Transaction is snapshot of new state
+ * txAfterCommit.read(OPERATIONAL, PATH).get(); // returns Optional containing B;
+ * </code>
+ *
+ * <p>
+ * <b>Note:</b> example contains blocking calls on future only to illustrate that action happened after other
+ * asynchronous action. Use of blocking call {@link com.google.common.util.concurrent.FluentFuture#get()} is
+ * discouraged for most uses and you should use
+ * {@link com.google.common.util.concurrent.FluentFuture#addCallback(com.google.common.util.concurrent.FutureCallback,
+ * java.util.concurrent.Executor)} or other functions from {@link com.google.common.util.concurrent.Futures} to register
+ * more specific listeners.
  */
-public interface ReadTransaction extends AsyncReadTransaction<InstanceIdentifier<?>, DataObject> {
-
+public interface ReadTransaction extends Transaction, AutoCloseable, ReadOperations {
     /**
-     * Reads data from the provided logical data store located at the provided path.
-     *
-     *<p>
-     * If the target is a subtree, then the whole subtree is read (and will be
-     * accessible from the returned data object).
-     *
-     * @param store
-     *            Logical data store from which read should occur.
-     * @param path
-     *            Path which uniquely identifies subtree which client want to
-     *            read
-     * @return a FluentFuture containing the result of the read. The Future blocks until the
-     *         commit operation is complete. Once complete:
-     *         <ul>
-     *         <li>If the data at the supplied path exists, the Future returns an Optional object
-     *         containing the data.</li>
-     *         <li>If the data at the supplied path does not exist, the Future returns
-     *         Optional#absent().</li>
-     *         <li>If the read of the data fails, the Future will fail with a
-     *         {@link ReadFailedException} or an exception derived from ReadFailedException.</li>
-     *         </ul>
+     * Closes this transaction and releases all resources associated with it.
      */
-    <T extends DataObject> FluentFuture<Optional<T>> read(LogicalDatastoreType store, InstanceIdentifier<T> path);
+    @Override
+    void close();
 }