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