Cleaned up mdsal-common-api and mdsal-dom-spi

[mdsal.git] / common / mdsal-common-api / src / main / java / org / opendaylight / mdsal / common / api / AsyncWriteTransaction.java

diff --git a/common/mdsal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncWriteTransaction.java b/common/mdsal-common-api/src/main/java/org/opendaylight/mdsal/common/api/AsyncWriteTransaction.java
similarity index 91%
rename from common/mdsal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncWriteTransaction.java
rename to common/mdsal-common-api/src/main/java/org/opendaylight/mdsal/common/api/AsyncWriteTransaction.java
index 533c8eac049a4392721bc25a60f14143298acbbc..21ad979195b71f9edf1ab3110ae22cbd23b622a2 100644 (file)
--- a/common/mdsal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncWriteTransaction.java
+++ b/common/mdsal-common-api/src/main/java/org/opendaylight/mdsal/common/api/AsyncWriteTransaction.java
@@ -5,13 +5,11 @@
  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
  * and is available at http://www.eclipse.org/legal/epl-v10.html
  */
-package org.opendaylight.controller.md.sal.common.api.data;
+package org.opendaylight.mdsal.common.api;
 
 import com.google.common.util.concurrent.CheckedFuture;
 import com.google.common.util.concurrent.ListenableFuture;
-import org.opendaylight.controller.md.sal.common.api.TransactionStatus;
 import org.opendaylight.yangtools.concepts.Path;
-import org.opendaylight.yangtools.yang.common.RpcResult;
 
 /**
  * Write transaction provides mutation capabilities for a data tree.
@@ -91,34 +89,27 @@ public interface AsyncWriteTransaction<P extends Path<P>, D> extends AsyncTransa
     /**
      * Cancels the transaction.
      *
-     * Transactions can only be cancelled if it's status is
-     * {@link TransactionStatus#NEW} or {@link TransactionStatus#SUBMITED}
+     * Transactions can only be cancelled if it was not yet submited.
      *
-     * Invoking cancel() on {@link TransactionStatus#FAILED} or
-     * {@link TransactionStatus#CANCELED} will have no effect, and transaction
-     * is considered cancelled.
+     * Invoking cancel() on failed or already canceled will have no effect, and transaction is
+     * considered cancelled.
      *
-     * Invoking cancel() on finished transaction  (future returned by {@link #submit()}
-     * already completed with {@link TransactionStatus#COMMITED}) will always
-     * fail (return false).
+     * Invoking cancel() on finished transaction (future returned by {@link #submit()} already
+     * successfully completed) will always fail (return false).
      *
-     * @return <tt>false</tt> if the task could not be cancelled,
-     * typically because it has already completed normally;
-     * <tt>true</tt> otherwise
+     * @return <tt>false</tt> if the task could not be cancelled, typically because it has already
+     *         completed normally; <tt>true</tt> otherwise
      *
      */
     boolean cancel();
 
     /**
-     * Removes a piece of data from specified path. This operation does not fail
-     * if the specified path does not exist.
-     *
-     * @param store
-     *            Logical data store which should be modified
-     * @param path
-     *            Data object path
-     * @throws IllegalStateException
-     *             if the transaction is no longer {@link TransactionStatus#NEW}
+     * Removes a piece of data from specified path. This operation does not fail if the specified
+     * path does not exist.
+     *
+     * @param store Logical data store which should be modified
+     * @param path Data object path
+     * @throws IllegalStateException if the transaction was submitted or canceled.
      */
     void delete(LogicalDatastoreType store, P path);
 
@@ -135,8 +126,8 @@ public interface AsyncWriteTransaction<P extends Path<P>, D> extends AsyncTransa
      * <code>merge(LogicalDatastoreType, Path, Object)</code>,
      * <code>delete(LogicalDatastoreType, Path)</code> will fail with {@link IllegalStateException}.
      *
-     * The transaction is marked as {@link TransactionStatus#SUBMITED} and enqueued into the data
-     * store back-end for processing.
+     * The transaction is marked as submitted and enqueued into the data store back-end for
+     * processing.
      *
      * <p>
      * Whether or not the commit is successful is determined by versioning of the data tree and
@@ -151,16 +142,16 @@ public interface AsyncWriteTransaction<P extends Path<P>, D> extends AsyncTransa
      * <pre>
      *  private void doWrite( final int tries ) {
      *      WriteTransaction writeTx = dataBroker.newWriteOnlyTransaction();
-     *
+     * 
      *      MyDataObject data = ...;
      *      InstanceIdentifier&lt;MyDataObject&gt; path = ...;
      *      writeTx.put( LogicalDatastoreType.OPERATIONAL, path, data );
-     *
+     * 
      *      Futures.addCallback( writeTx.submit(), new FutureCallback&lt;Void&gt;() {
      *          public void onSuccess( Void result ) {
      *              // succeeded
      *          }
-     *
+     * 
      *          public void onFailure( Throwable t ) {
      *              if( t instanceof OptimisticLockFailedException ) {
      *                  if( ( tries - 1 ) &gt; 0 ) {
@@ -455,10 +446,10 @@ public interface AsyncWriteTransaction<P extends Path<P>, D> extends AsyncTransa
      * <pre>
      * txA = broker.newWriteTransaction(); // allocates new transaction, data tree is empty
      * txB = broker.newWriteTransaction(); // allocates new transaction, data tree is empty
-     *
+     * 
      * txA.put(CONFIGURATION, PATH, A);    // writes to PATH value A
      * txB.put(CONFIGURATION, PATH, B)     // writes to PATH value B
-     *
+     * 
      * ListenableFuture futureA = txA.submit(); // transaction A is sealed and submitted
      * ListenebleFuture futureB = txB.submit(); // transaction B is sealed and submitted
      * </pre>
@@ -478,14 +469,8 @@ public interface AsyncWriteTransaction<P extends Path<P>, D> extends AsyncTransa
      *         will fail with a {@link TransactionCommitFailedException} or an exception derived
      *         from TransactionCommitFailedException.
      *
-     * @throws IllegalStateException if the transaction is not {@link TransactionStatus#NEW}
+     * @throws IllegalStateException if the transaction is already submitted or was canceled.
      */
     CheckedFuture<Void,TransactionCommitFailedException> submit();
 
-    /**
-     * @deprecated Use {@link #submit()} instead.
-     */
-    @Deprecated
-    ListenableFuture<RpcResult<TransactionStatus>> commit();
-
 }