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 datastoreType 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(
  51         Class<D> datastoreType, InterruptibleCheckedFunction<TypedReadTransaction<D>, R, E> txFunction)
  52         throws E, InterruptedException;
  53
  54     /**
  55      * Invokes a function with a <b>NEW</b> {@link TypedReadTransaction}, and ensures that that transaction is closed.
  56      * Thus when this method returns, that transaction is guaranteed to have been closed, and will never "leak" and
  57      * waste memory.
  58      *
  59      * <p>The function must not itself attempt to close the transaction. (It can't directly, since
  60      * {@link TypedReadTransaction} doesn't expose a {@code close()} method.)
  61      *
  62      * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
  63      * other.
  64      *
  65      * @param <D> datastore type
  66      * @param <E> thrown exception type
  67      * @param <R> result type
  68      * @param datastoreType the {@link Datastore} type that will be accessed
  69      * @param txFunction the {@link InterruptibleCheckedFunction} that needs a new read transaction
  70      * @return the result of the function.
  71      * @throws E if an error occurs.
  72      */
  73     <D extends Datastore, E extends Exception, R> R applyWithNewReadOnlyTransactionAndClose(Class<D> datastoreType,
  74         CheckedFunction<TypedReadTransaction<D>, R, E> txFunction) throws E;
  75
  76     /**
  77      * Invokes a function with a <b>NEW</b> {@link ReadWriteTransaction}, and then submits that transaction and
  78      * returns the Future from that submission, or cancels it if an exception was thrown and returns a failed
  79      * future with that exception. Thus when this method returns, that transaction is guaranteed to have
  80      * been either submitted or cancelled, and will never "leak" and waste memory.
  81      *
  82      * <p>The function must not itself use
  83      * {@link ReadWriteTransaction#cancel()}, or
  84      * {@link ReadWriteTransaction#commit()} (it will throw an {@link UnsupportedOperationException}).
  85      *
  86      * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
  87      * other.
  88      *
  89      * <p>This is an asynchronous API, like {@link DataBroker}'s own;
  90      * when returning from this method, the operation of the Transaction may well still be ongoing in the background,
  91      * or pending;
  92      * calling code therefore <b>must</b> handle the returned future, e.g. by passing it onwards (return),
  93      * or by itself adding callback listeners to it using {@link Futures}' methods, or by transforming it into a
  94      * {@link CompletionStage}
  95      * (but better NOT by using the blocking {@link Future#get()} on it).
  96      *
  97      * @param <D> datastore type
  98      * @param <E> thrown exception type
  99      * @param <R> result type
 100      * @param datastoreType the {@link Datastore} type that will be accessed
 101      * @param txFunction the {@link InterruptibleCheckedFunction} that needs a new read-write transaction
 102      * @return the {@link FluentFuture} returned by {@link ReadWriteTransaction#commit()}, or a failed future with an
 103      *         application specific exception (not from submit())
 104      */
 105     @CheckReturnValue
 106     <D extends Datastore, E extends Exception, R>
 107         FluentFuture<R> applyWithNewReadWriteTransactionAndSubmit(Class<D> datastoreType,
 108             InterruptibleCheckedFunction<TypedReadWriteTransaction<D>, R, E> txFunction);
 109
 110     /**
 111      * Invokes a function with a <b>NEW</b> {@link ReadTransaction}, and ensures that that transaction is closed.
 112      * Thus when this method returns, that transaction is guaranteed to have been closed, and will never "leak" and
 113      * waste memory.
 114      *
 115      * <p>The function must not itself attempt to close the transaction. (It can't directly, since
 116      * {@link ReadTransaction} doesn't expose a {@code close()} method.)
 117      *
 118      * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
 119      * other.
 120      *
 121      * @param <D> datastore type
 122      * @param <E> thrown exception type
 123      * @param datastoreType the {@link Datastore} type that will be accessed
 124      * @param txConsumer the {@link InterruptibleCheckedFunction} that needs a new read transaction
 125      * @throws E if an error occurs.
 126      * @throws InterruptedException if the function is interrupted (this is passed through from the provided function).
 127      */
 128     <D extends Datastore, E extends Exception> void callInterruptiblyWithNewReadOnlyTransactionAndClose(
 129         Class<D> datastoreType, InterruptibleCheckedConsumer<TypedReadTransaction<D>, E> txConsumer)
 130         throws E, InterruptedException;
 131
 132     /**
 133      * Invokes a function with a <b>NEW</b> {@link ReadTransaction}, and ensures that that transaction is closed.
 134      * Thus when this method returns, that transaction is guaranteed to have been closed, and will never "leak" and
 135      * waste memory.
 136      *
 137      * <p>The function must not itself attempt to close the transaction. (It can't directly, since
 138      * {@link ReadTransaction} doesn't expose a {@code close()} method.)
 139      *
 140      * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
 141      * other.
 142      *
 143      * @param <D> datastore type
 144      * @param <E> thrown exception type
 145      * @param datastoreType the {@link Datastore} type that will be accessed
 146      * @param txConsumer the {@link InterruptibleCheckedFunction} that needs a new read transaction
 147      * @throws E if an error occurs.
 148      */
 149     <D extends Datastore, E extends Exception> void callWithNewReadOnlyTransactionAndClose(Class<D> datastoreType,
 150         CheckedConsumer<TypedReadTransaction<D>, E> txConsumer) throws E;
 151
 152     /**
 153      * Invokes a consumer with a <b>NEW</b> {@link ReadWriteTransaction}, and then submits that transaction and
 154      * returns the Future from that submission, or cancels it if an exception was thrown and returns a failed
 155      * future with that exception. Thus when this method returns, that transaction is guaranteed to have
 156      * been either submitted or cancelled, and will never "leak" and waste memory.
 157      *
 158      * <p>The consumer should not (cannot) itself use
 159      * {@link ReadWriteTransaction#cancel()}, or
 160      * {@link ReadWriteTransaction#commit()} (it will throw an {@link UnsupportedOperationException}).
 161      *
 162      * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
 163      * other.
 164      *
 165      * <p>This is an asynchronous API, like {@link DataBroker}'s own;
 166      * when returning from this method, the operation of the Transaction may well still be ongoing in the background,
 167      * or pending;
 168      * calling code therefore <b>must</b> handle the returned future, e.g. by passing it onwards (return),
 169      * or by itself adding callback listeners to it using {@link Futures}' methods, or by transforming it into a
 170      * {@link CompletionStage}
 171      * (but better NOT by using the blocking {@link Future#get()} on it).
 172      *
 173      * @param <D> datastore type
 174      * @param <E> thrown exception type
 175      * @param datastoreType the {@link Datastore} type that will be accessed
 176      * @param txConsumer the {@link InterruptibleCheckedConsumer} that needs a new read-write transaction
 177      * @return the {@link FluentFuture} returned by {@link ReadWriteTransaction#commit()}, or a failed future with an
 178      *         application specific exception (not from submit())
 179      */
 180     @CheckReturnValue
 181     <D extends Datastore, E extends Exception>
 182         FluentFuture<? extends Object> callWithNewReadWriteTransactionAndSubmit(Class<D> datastoreType,
 183             InterruptibleCheckedConsumer<TypedReadWriteTransaction<D>, E> txConsumer);
 184
 185     /**
 186      * Invokes a consumer with a <b>NEW</b> {@link WriteTransaction}, and then submits that transaction and
 187      * returns the Future from that submission, or cancels it if an exception was thrown and returns a failed
 188      * future with that exception. Thus when this method returns, that transaction is guaranteed to have
 189      * been either submitted or cancelled, and will never "leak" and waste memory.
 190      *
 191      * <p>The consumer should not (cannot) itself use
 192      * {@link WriteTransaction#cancel()}, or
 193      * {@link WriteTransaction#commit()} (it will throw an {@link UnsupportedOperationException}).
 194      *
 195      * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
 196      * other.
 197      *
 198      * <p>This is an asynchronous API, like {@link DataBroker}'s own;
 199      * when returning from this method, the operation of the Transaction may well still be ongoing in the background,
 200      * or pending;
 201      * calling code therefore <b>must</b> handle the returned future, e.g. by passing it onwards (return),
 202      * or by itself adding callback listeners to it using {@link Futures}' methods, or by transforming it into a
 203      * {@link CompletionStage}
 204      * (but better NOT by using the blocking {@link Future#get()} on it).
 205      *
 206      * @param <D> datastore type
 207      * @param <E> thrown exception type
 208      * @param datastoreType the {@link Datastore} type that will be accessed
 209      * @param txConsumer the {@link InterruptibleCheckedConsumer} that needs a new write only transaction
 210      * @return the {@link FluentFuture} returned by {@link WriteTransaction#commit()}, or a failed future with an
 211      *         application specific exception (not from submit())
 212      */
 213     @CheckReturnValue
 214     <D extends Datastore, E extends Exception>
 215         FluentFuture<? extends Object> callWithNewWriteOnlyTransactionAndSubmit(Class<D> datastoreType,
 216             InterruptibleCheckedConsumer<TypedWriteTransaction<D>, E> txConsumer);
 217 }