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.LoggingFutures;
  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} and chaining on that, or at the very least simply by using
  56      * {@link LoggingFutures#addErrorLogging(ListenableFuture, org.slf4j.Logger, String)}
  57      * (but better NOT by using the blocking {@link Future#get()} on it).
  58      *
  59      * @param txConsumer the {@link CheckedConsumer} that needs a new write only transaction
  60      * @return the {@link ListenableFuture} returned by ,
  61      *     or a failed future with an application specific exception (not from submit())
  62      * @param <E> Exception subclass
  63      */
  64     @CheckReturnValue
  65     @Deprecated
  66     <E extends Exception>
  67         ListenableFuture<Void> callWithNewWriteOnlyTransactionAndSubmit(
  68             InterruptibleCheckedConsumer<WriteTransaction, E> txConsumer);
  69
  70     /**
  71      * Invokes a consumer with a <b>NEW</b> {@link ReadWriteTransaction}, and then submits that transaction and
  72      * returns the Future from that submission, or cancels it if an exception was thrown and returns a failed
  73      * future with that exception. Thus when this method returns, that transaction is guaranteed to have
  74      * been either submitted or cancelled, and will never "leak" and waste memory.
  75      *
  76      * <p>The consumer should not (cannot) itself use
  77      * {@link ReadWriteTransaction#cancel()}, or
  78      *  (it will throw an {@link UnsupportedOperationException}).
  79      *
  80      * <p>This is an asynchronous API, like {@link DataBroker}'s own;
  81      * when returning from this method, the operation of the Transaction may well still be ongoing in the background,
  82      * or pending;
  83      * calling code therefore <b>must</b> handle the returned future, e.g. by passing it onwards (return),
  84      * or by itself adding callback listeners to it using {@link Futures}' methods, or by transforming it into a
  85      * {@link CompletionStage} and chaining on that, or at the very least simply by using
  86      * {@link LoggingFutures#addErrorLogging(ListenableFuture, org.slf4j.Logger, String)}
  87      * (but better NOT by using the blocking {@link Future#get()} on it).
  88      *
  89      * @param txConsumer the {@link CheckedConsumer} that needs a new read-write transaction
  90      * @return the {@link ListenableFuture} returned by ,
  91      *     or a failed future with an application specific exception (not from submit())
  92      * @param <E> Exception subclass
  93      */
  94     @CheckReturnValue
  95     @Deprecated
  96     <E extends Exception> ListenableFuture<Void>
  97         callWithNewReadWriteTransactionAndSubmit(InterruptibleCheckedConsumer<ReadWriteTransaction, E> txConsumer);
  98
  99     /**
 100      * Invokes a function with a new {@link ManagedTransactionChain}, which is a wrapper around standard transaction
 101      * chains providing managed semantics. The transaction chain will be closed when the function returns.
 102      *
 103      * <p>This is an asynchronous API, like {@link DataBroker}'s own; when this method returns, the transactions in
 104      * the chain may well still be ongoing in the background, or pending. <strong>It is up to the consumer and
 105      * caller</strong> to agree on how failure will be handled; for example, the return type can include the futures
 106      * corresponding to the transactions in the chain. The implementation uses a default transaction chain listener
 107      * which logs an error if any of the transactions fail.
 108      *
 109      * <p>The MD-SAL transaction chain semantics are preserved: each transaction in the chain will see the results of
 110      * the previous transactions in the chain, even if they haven't been fully committed yet; and any error will result
 111      * in subsequent transactions in the chain <strong>not</strong> being submitted.
 112      *
 113      * @param chainConsumer The {@link InterruptibleCheckedFunction} that will build transactions in the transaction
 114      *                      chain.
 115      * @param <R> The type of result returned by the function.
 116      * @return The result of the function call.
 117      */
 118     <R> R applyWithNewTransactionChainAndClose(Function<ManagedTransactionChain, R> chainConsumer);
 119 }