binding/mdsal-binding-util/src/main/java/org/opendaylight/mdsal/binding/util/ManagedTransactionFactory.java

   1 /*
   2  * Copyright © 2018 Red Hat, Inc. and others.
   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.binding.util;
   9
  10 import com.google.common.annotations.Beta;
  11 import com.google.common.util.concurrent.FluentFuture;
  12 import com.google.common.util.concurrent.Futures;
  13 import edu.umd.cs.findbugs.annotations.CheckReturnValue;
  14 import java.util.concurrent.CompletionStage;
  15 import java.util.concurrent.Future;
  16 import org.opendaylight.mdsal.binding.api.DataBroker;
  17 import org.opendaylight.mdsal.binding.api.ReadTransaction;
  18 import org.opendaylight.mdsal.binding.api.ReadWriteTransaction;
  19 import org.opendaylight.mdsal.binding.api.WriteTransaction;
  20
  21 /**
  22  * Managed transaction factories provide managed transactions, <em>i.e.</em> transactions which are automatically
  23  * submitted or cancelled (write) or closed (read).
  24  *
  25  * <p>
  26  * This is a common interface for broker- and chain-based transaction managers, and should not be used directly.
  27  */
  28 @Beta
  29 public interface ManagedTransactionFactory {
  30     /**
  31      * Invokes a function with a <b>NEW</b> {@link TypedReadTransaction}, and ensures that that transaction is closed.
  32      * Thus when this method returns, that transaction is guaranteed to have been closed, and will never "leak" and
  33      * waste memory.
  34      *
  35      * <p>The function must not itself attempt to close the transaction. (It can't directly, since
  36      * {@link TypedReadTransaction} doesn't expose a {@code close()} method.)
  37      *
  38      * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
  39      * other.
  40      *
  41      * @param <D> datastore type
  42      * @param <E> thrown exception type
  43      * @param <R> result type
  44      * @param datastore the {@link Datastore} type that will be accessed
  45      * @param txFunction the {@link InterruptibleCheckedFunction} that needs a new read transaction
  46      * @return the result of the function.
  47      * @throws E if an error occurs.
  48      * @throws InterruptedException if the function is interrupted (this is passed through from the provided function).
  49      */
  50     <D extends Datastore, E extends Exception, R> R applyInterruptiblyWithNewReadOnlyTransactionAndClose(D datastore,
  51         InterruptibleCheckedFunction<TypedReadTransaction<D>, R, E> txFunction) throws E, InterruptedException;
  52
  53     /**
  54      * Invokes a function with a <b>NEW</b> {@link TypedReadTransaction}, and ensures that that transaction is closed.
  55      * Thus when this method returns, that transaction is guaranteed to have been closed, and will never "leak" and
  56      * waste memory.
  57      *
  58      * <p>The function must not itself attempt to close the transaction. (It can't directly, since
  59      * {@link TypedReadTransaction} doesn't expose a {@code close()} method.)
  60      *
  61      * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
  62      * other.
  63      *
  64      * @param <D> datastore type
  65      * @param <E> thrown exception type
  66      * @param <R> result type
  67      * @param datastore the {@link Datastore} type that will be accessed
  68      * @param txFunction the {@link InterruptibleCheckedFunction} that needs a new read transaction
  69      * @return the result of the function.
  70      * @throws E if an error occurs.
  71      */
  72     <D extends Datastore, E extends Exception, R> R applyWithNewReadOnlyTransactionAndClose(D datastore,
  73         CheckedFunction<TypedReadTransaction<D>, R, E> txFunction) throws E;
  74
  75     /**
  76      * Invokes a function with a <b>NEW</b> {@link ReadWriteTransaction}, and then submits that transaction and
  77      * returns the Future from that submission, or cancels it if an exception was thrown and returns a failed
  78      * future with that exception. Thus when this method returns, that transaction is guaranteed to have
  79      * been either submitted or cancelled, and will never "leak" and waste memory.
  80      *
  81      * <p>The function must not itself use
  82      * {@link ReadWriteTransaction#cancel()}, or
  83      * {@link ReadWriteTransaction#commit()} (it will throw an {@link UnsupportedOperationException}).
  84      *
  85      * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
  86      * other.
  87      *
  88      * <p>This is an asynchronous API, like {@link DataBroker}'s own;
  89      * when returning from this method, the operation of the Transaction may well still be ongoing in the background,
  90      * or pending;
  91      * calling code therefore <b>must</b> handle the returned future, e.g. by passing it onwards (return),
  92      * or by itself adding callback listeners to it using {@link Futures}' methods, or by transforming it into a
  93      * {@link CompletionStage}
  94      * (but better NOT by using the blocking {@link Future#get()} on it).
  95      *
  96      * @param <D> datastore type
  97      * @param <E> thrown exception type
  98      * @param <R> result type
  99      * @param datastore the {@link Datastore} type that will be accessed
 100      * @param txFunction the {@link InterruptibleCheckedFunction} that needs a new read-write transaction
 101      * @return the {@link FluentFuture} returned by {@link ReadWriteTransaction#commit()}, or a failed future with an
 102      *         application specific exception (not from submit())
 103      */
 104     @CheckReturnValue
 105     <D extends Datastore, E extends Exception, R> FluentFuture<R> applyWithNewReadWriteTransactionAndSubmit(D datastore,
 106         InterruptibleCheckedFunction<TypedReadWriteTransaction<D>, R, E> txFunction);
 107
 108     /**
 109      * Invokes a function with a <b>NEW</b> {@link ReadTransaction}, and ensures that that transaction is closed.
 110      * Thus when this method returns, that transaction is guaranteed to have been closed, and will never "leak" and
 111      * waste memory.
 112      *
 113      * <p>The function must not itself attempt to close the transaction. (It can't directly, since
 114      * {@link ReadTransaction} doesn't expose a {@code close()} method.)
 115      *
 116      * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
 117      * other.
 118      *
 119      * @param <D> datastore type
 120      * @param <E> thrown exception type
 121      * @param datastore the {@link Datastore} type that will be accessed
 122      * @param txConsumer the {@link InterruptibleCheckedFunction} that needs a new read transaction
 123      * @throws E if an error occurs.
 124      * @throws InterruptedException if the function is interrupted (this is passed through from the provided function).
 125      */
 126     <D extends Datastore, E extends Exception> void callInterruptiblyWithNewReadOnlyTransactionAndClose(D datastore,
 127         InterruptibleCheckedConsumer<TypedReadTransaction<D>, E> txConsumer) throws E, InterruptedException;
 128
 129     /**
 130      * Invokes a function with a <b>NEW</b> {@link ReadTransaction}, and ensures that that transaction is closed.
 131      * Thus when this method returns, that transaction is guaranteed to have been closed, and will never "leak" and
 132      * waste memory.
 133      *
 134      * <p>The function must not itself attempt to close the transaction. (It can't directly, since
 135      * {@link ReadTransaction} doesn't expose a {@code close()} method.)
 136      *
 137      * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
 138      * other.
 139      *
 140      * @param <D> datastore type
 141      * @param <E> thrown exception type
 142      * @param datastore the {@link Datastore} type that will be accessed
 143      * @param txConsumer the {@link InterruptibleCheckedFunction} that needs a new read transaction
 144      * @throws E if an error occurs.
 145      */
 146     <D extends Datastore, E extends Exception> void callWithNewReadOnlyTransactionAndClose(D datastore,
 147         CheckedConsumer<TypedReadTransaction<D>, E> txConsumer) throws E;
 148
 149     /**
 150      * Invokes a consumer with a <b>NEW</b> {@link ReadWriteTransaction}, and then submits that transaction and
 151      * returns the Future from that submission, or cancels it if an exception was thrown and returns a failed
 152      * future with that exception. Thus when this method returns, that transaction is guaranteed to have
 153      * been either submitted or cancelled, and will never "leak" and waste memory.
 154      *
 155      * <p>The consumer should not (cannot) itself use
 156      * {@link ReadWriteTransaction#cancel()}, or
 157      * {@link ReadWriteTransaction#commit()} (it will throw an {@link UnsupportedOperationException}).
 158      *
 159      * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
 160      * other.
 161      *
 162      * <p>This is an asynchronous API, like {@link DataBroker}'s own;
 163      * when returning from this method, the operation of the Transaction may well still be ongoing in the background,
 164      * or pending;
 165      * calling code therefore <b>must</b> handle the returned future, e.g. by passing it onwards (return),
 166      * or by itself adding callback listeners to it using {@link Futures}' methods, or by transforming it into a
 167      * {@link CompletionStage}
 168      * (but better NOT by using the blocking {@link Future#get()} on it).
 169      *
 170      * @param <D> datastore type
 171      * @param <E> thrown exception type
 172      * @param datastore the {@link Datastore} type that will be accessed
 173      * @param txConsumer the {@link InterruptibleCheckedConsumer} that needs a new read-write transaction
 174      * @return the {@link FluentFuture} returned by {@link ReadWriteTransaction#commit()}, or a failed future with an
 175      *         application specific exception (not from submit())
 176      */
 177     @CheckReturnValue
 178     <D extends Datastore, E extends Exception> FluentFuture<? extends Object> callWithNewReadWriteTransactionAndSubmit(
 179         D datastore, InterruptibleCheckedConsumer<TypedReadWriteTransaction<D>, E> txConsumer);
 180
 181     /**
 182      * Invokes a consumer with a <b>NEW</b> {@link WriteTransaction}, and then submits that transaction and
 183      * returns the Future from that submission, or cancels it if an exception was thrown and returns a failed
 184      * future with that exception. Thus when this method returns, that transaction is guaranteed to have
 185      * been either submitted or cancelled, and will never "leak" and waste memory.
 186      *
 187      * <p>The consumer should not (cannot) itself use
 188      * {@link WriteTransaction#cancel()}, or
 189      * {@link WriteTransaction#commit()} (it will throw an {@link UnsupportedOperationException}).
 190      *
 191      * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any other.
 192      *
 193      * <p>This is an asynchronous API, like {@link DataBroker}'s own;
 194      * when returning from this method, the operation of the Transaction may well still be ongoing in the background,
 195      * or pending;
 196      * calling code therefore <b>must</b> handle the returned future, e.g. by passing it onwards (return),
 197      * or by itself adding callback listeners to it using {@link Futures}' methods, or by transforming it into a
 198      * {@link CompletionStage}
 199      * (but better NOT by using the blocking {@link Future#get()} on it).
 200      *
 201      * @param <D> datastore type
 202      * @param <E> thrown exception type
 203      * @param datastore the {@link Datastore} type that will be accessed
 204      * @param txConsumer the {@link InterruptibleCheckedConsumer} that needs a new write only transaction
 205      * @return the {@link FluentFuture} returned by {@link WriteTransaction#commit()}, or a failed future with an
 206      *         application specific exception (not from submit())
 207      */
 208     @CheckReturnValue
 209     <D extends Datastore, E extends Exception> FluentFuture<? extends Object> callWithNewWriteOnlyTransactionAndSubmit(
 210         D datastore, InterruptibleCheckedConsumer<TypedWriteTransaction<D>, E> txConsumer);
 211 }