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