mdsalutil/mdsalutil-api/src/main/java/org/opendaylight/genius/infra/ManagedNewTransactionRunner.java

   1 /*
   2  * Copyright (c) 2017 Red Hat, 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.genius.infra;
   9
  10 import com.google.common.annotations.Beta;
  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 java.util.function.Function;
  17 import org.opendaylight.infrautils.utils.concurrent.ListenableFutures;
  18 import org.opendaylight.infrautils.utils.function.CheckedConsumer;
  19 import org.opendaylight.infrautils.utils.function.InterruptibleCheckedConsumer;
  20 import org.opendaylight.infrautils.utils.function.InterruptibleCheckedFunction;
  21 import org.opendaylight.mdsal.binding.api.DataBroker;
  22 import org.opendaylight.mdsal.binding.api.ReadWriteTransaction;
  23 import org.opendaylight.mdsal.binding.api.WriteTransaction;
  24
  25 /**
  26  * Managed transactions utility to simplify handling of new transactions and ensure they are always closed.
  27  * Implementation in {@link ManagedNewTransactionRunnerImpl}, alternative implementation of this API with optional
  28  * retries is {@link RetryingManagedNewTransactionRunner}.
  29  *
  30  * <p>This should typically be used (only) directly in code which really must be creating its own new transactions,
  31  * such as RPC entry points, or background jobs.  Other lower level code "behind" such entry points should
  32  * just get handed over the transaction provided by this API.
  33  *
  34  * @deprecated Use {@link org.opendaylight.mdsal.binding.util.ManagedNewTransactionRunner} instead.
  35  */
  36 @Beta
  37 @Deprecated(forRemoval = true)
  38 public interface ManagedNewTransactionRunner extends ManagedTransactionFactory {
  39
  40     /**
  41      * Invokes a consumer with a <b>NEW</b> {@link WriteTransaction}, and then submits that transaction and
  42      * returns the Future from that submission, or cancels it if an exception was thrown and returns a failed
  43      * future with that exception. Thus when this method returns, that transaction is guaranteed to have
  44      * been either submitted or cancelled, and will never "leak" and waste memory.
  45      *
  46      * <p>The consumer should not (cannot) itself use
  47      * {@link WriteTransaction#cancel()}, or
  48      *  (it will throw an {@link UnsupportedOperationException}).
  49      *
  50      * <p>This is an asynchronous API, like {@link DataBroker}'s own;
  51      * when returning from this method, the operation of the Transaction may well still be ongoing in the background,
  52      * or pending;
  53      * calling code therefore <b>must</b> handle the returned future, e.g. by passing it onwards (return),
  54      * or by itself adding callback listeners to it using {@link Futures}' methods, or by transforming it into a
  55      * {@link CompletionStage} using {@link ListenableFutures#toCompletionStage(ListenableFuture)} and chaining on
  56      * that, or at the very least simply by using
  57      * {@link ListenableFutures#addErrorLogging(ListenableFuture, org.slf4j.Logger, String)}
  58      * (but better NOT by using the blocking {@link Future#get()} on it).
  59      *
  60      * @param txConsumer the {@link CheckedConsumer} that needs a new write only transaction
  61      * @return the {@link ListenableFuture} returned by ,
  62      *     or a failed future with an application specific exception (not from submit())
  63      * @param <E> Exception subclass
  64      */
  65     @CheckReturnValue
  66     @Deprecated
  67     <E extends Exception>
  68         ListenableFuture<Void> callWithNewWriteOnlyTransactionAndSubmit(
  69             InterruptibleCheckedConsumer<WriteTransaction, E> txConsumer);
  70
  71     /**
  72      * Invokes a consumer with a <b>NEW</b> {@link ReadWriteTransaction}, and then submits that transaction and
  73      * returns the Future from that submission, or cancels it if an exception was thrown and returns a failed
  74      * future with that exception. Thus when this method returns, that transaction is guaranteed to have
  75      * been either submitted or cancelled, and will never "leak" and waste memory.
  76      *
  77      * <p>The consumer should not (cannot) itself use
  78      * {@link ReadWriteTransaction#cancel()}, or
  79      *  (it will throw an {@link UnsupportedOperationException}).
  80      *
  81      * <p>This is an asynchronous API, like {@link DataBroker}'s own;
  82      * when returning from this method, the operation of the Transaction may well still be ongoing in the background,
  83      * or pending;
  84      * calling code therefore <b>must</b> handle the returned future, e.g. by passing it onwards (return),
  85      * or by itself adding callback listeners to it using {@link Futures}' methods, or by transforming it into a
  86      * {@link CompletionStage} using {@link ListenableFutures#toCompletionStage(ListenableFuture)} and chaining on
  87      * that, or at the very least simply by using
  88      * {@link ListenableFutures#addErrorLogging(ListenableFuture, org.slf4j.Logger, String)}
  89      * (but better NOT by using the blocking {@link Future#get()} on it).
  90      *
  91      * @param txConsumer the {@link CheckedConsumer} that needs a new read-write transaction
  92      * @return the {@link ListenableFuture} returned by ,
  93      *     or a failed future with an application specific exception (not from submit())
  94      * @param <E> Exception subclass
  95      */
  96     @CheckReturnValue
  97     @Deprecated
  98     <E extends Exception> ListenableFuture<Void>
  99         callWithNewReadWriteTransactionAndSubmit(InterruptibleCheckedConsumer<ReadWriteTransaction, E> txConsumer);
 100
 101     /**
 102      * Invokes a function with a new {@link ManagedTransactionChain}, which is a wrapper around standard transaction
 103      * chains providing managed semantics. The transaction chain will be closed when the function returns.
 104      *
 105      * <p>This is an asynchronous API, like {@link DataBroker}'s own; when this method returns, the transactions in
 106      * the chain may well still be ongoing in the background, or pending. <strong>It is up to the consumer and
 107      * caller</strong> to agree on how failure will be handled; for example, the return type can include the futures
 108      * corresponding to the transactions in the chain. The implementation uses a default transaction chain listener
 109      * which logs an error if any of the transactions fail.
 110      *
 111      * <p>The MD-SAL transaction chain semantics are preserved: each transaction in the chain will see the results of
 112      * the previous transactions in the chain, even if they haven't been fully committed yet; and any error will result
 113      * in subsequent transactions in the chain <strong>not</strong> being submitted.
 114      *
 115      * @param chainConsumer The {@link InterruptibleCheckedFunction} that will build transactions in the transaction
 116      *                      chain.
 117      * @param <R> The type of result returned by the function.
 118      * @return The result of the function call.
 119      */
 120     <R> R applyWithNewTransactionChainAndClose(Function<ManagedTransactionChain, R> chainConsumer);
 121 }