binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/CursorAwareWriteTransaction.java

   1 /*
   2  * Copyright (c) 2016 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
   9 package org.opendaylight.mdsal.binding.api;
  10
  11 import com.google.common.util.concurrent.FluentFuture;
  12 import javax.annotation.CheckReturnValue;
  13 import org.eclipse.jdt.annotation.NonNull;
  14 import org.opendaylight.mdsal.common.api.CommitInfo;
  15 import org.opendaylight.mdsal.common.api.TransactionCommitFailedException;
  16 import org.opendaylight.yangtools.yang.binding.DataObject;
  17
  18 /**
  19  * Write transaction that provides cursor's with write access to the data tree.
  20  */
  21 public interface CursorAwareWriteTransaction extends DataTreeCursorProvider {
  22     /**
  23      * Create a {@link DataTreeWriteCursor} anchored at the specified path.
  24      * There can only be one cursor open at a time.
  25      *
  26      * <p>
  27      * @param path Path at which the cursor is to be anchored
  28      * @return write cursor at the desired location.
  29      * @throws IllegalStateException when there's an open cursor, or this transaction is closed already.
  30      */
  31     @Override
  32     <T extends DataObject> DataTreeWriteCursor createCursor(DataTreeIdentifier<T> path);
  33
  34     /**
  35      * Cancels the transaction.
  36      *
  37      * <p>
  38      * A transaction can only be cancelled if it has not yet been committed.
  39      *
  40      * <p>
  41      * Invoking cancel() on failed or already canceled will have no effect, and transaction is
  42      * considered cancelled.
  43      *
  44      * <p>
  45      * Invoking cancel() on finished transaction (future returned by {@link #commit()} already
  46      * successfully completed) will always fail (return false).
  47      *
  48      * @return <tt>false</tt> if the task could not be cancelled, typically because it has already
  49      *         completed normally; <tt>true</tt> otherwise
  50      *
  51      */
  52     boolean cancel();
  53
  54     /**
  55      * Commits this transaction to be asynchronously applied to update the logical data tree. The
  56      * returned CheckedFuture conveys the result of applying the data changes.
  57      *
  58      * <p>
  59      * <b>Note:</b> It is strongly recommended to process the FluentFuture result in an
  60      * asynchronous manner rather than using the blocking get() method.
  61      *
  62      * <p>
  63      * This call logically seals the transaction, which prevents the client from further changing
  64      * data tree using this transaction's cursor. Any subsequent calls to
  65      * <code>createCursorCursor(DOMDataTreeIdentifier</code>
  66      * or any of the cursor's methods will fail with {@link IllegalStateException}.
  67      *
  68      * <p>
  69      * The transaction is marked as submitted and enqueued into the shard back-end for
  70      * processing.
  71      *
  72      * @return a FluentFuture containing the result of the commit information. The Future blocks until the commit
  73      *         operation is complete. A successful commit returns nothing. On failure, the Future will fail with a
  74      *         {@link TransactionCommitFailedException} or an exception derived from TransactionCommitFailedException.
  75      */
  76     @CheckReturnValue
  77     @NonNull FluentFuture<? extends @NonNull CommitInfo> commit();
  78 }