org.opendaylight.genius.infra

Interface ManagedNewTransactionRunner

All Known Implementing Classes:

ManagedNewTransactionRunnerImpl, RetryingManagedNewTransactionRunner

@Beta
public interface ManagedNewTransactionRunner

Managed transactions utility to simplify handling of new transactions and ensure they are always closed (see ManagedNewTransactionRunnerImpl). One of the implementations of this API can, optionally, do retries (see RetryingManagedNewTransactionRunnerImpl). When you want both together (which is typical), it is recommended to use the RetryingManagedNewTransactionRunner.

This should typically be used (only) directly in code which really must be creating its own new transactions, such as RPC entry points, or background jobs. Other lower level code "behind" such entry points should just get handed over the transaction provided by this API.

Method Summary

Modifier and Type	Method and Description
<E extends Exception,R> com.google.common.util.concurrent.ListenableFuture<R>	applyWithNewReadWriteTransactionAndSubmit(org.opendaylight.infrautils.utils.function.CheckedFunction<org.opendaylight.controller.md.sal.binding.api.ReadWriteTransaction,R,E> txRunner) Invokes a function with a NEW ReadWriteTransaction, and then submits that transaction and returns the Future from that submission, or cancels it if an exception was thrown and returns a failed future with that exception.
<E extends Exception> com.google.common.util.concurrent.ListenableFuture<Void>	callWithNewReadWriteTransactionAndSubmit(org.opendaylight.infrautils.utils.function.CheckedConsumer<org.opendaylight.controller.md.sal.binding.api.ReadWriteTransaction,E> txRunner) Invokes a consumer with a NEW ReadWriteTransaction, and then submits that transaction and returns the Future from that submission, or cancels it if an exception was thrown and returns a failed future with that exception.
<E extends Exception> com.google.common.util.concurrent.ListenableFuture<Void>	callWithNewWriteOnlyTransactionAndSubmit(org.opendaylight.infrautils.utils.function.CheckedConsumer<org.opendaylight.controller.md.sal.binding.api.WriteTransaction,E> txRunner) Invokes a consumer with a NEW WriteTransaction, and then submits that transaction and returns the Future from that submission, or cancels it if an exception was thrown and returns a failed future with that exception.

Method Detail

callWithNewWriteOnlyTransactionAndSubmit

@CheckReturnValue
<E extends Exception> com.google.common.util.concurrent.ListenableFuture<Void> callWithNewWriteOnlyTransactionAndSubmit(org.opendaylight.infrautils.utils.function.CheckedConsumer<org.opendaylight.controller.md.sal.binding.api.WriteTransaction,E> txRunner)

Invokes a consumer with a NEW WriteTransaction, and then submits that transaction and returns the Future from that submission, or cancels it if an exception was thrown and returns a failed future with that exception. Thus when this method returns, that transaction is guaranteed to have been either submitted or cancelled, and will never "leak" and waste memory.

The consumer should not (cannot) itself use AsyncWriteTransaction.cancel(), AsyncWriteTransaction.commit() or AsyncWriteTransaction.submit() (it will throw an UnsupportedOperationException).

This is an asynchronous API, like DataBroker's own; when returning from this method, the operation of the Transaction may well still be ongoing in the background, or pending; calling code therefore must handle the returned future, e.g. by passing it onwards (return), or by itself adding callback listeners to it using Futures' methods, or by transforming it into a CompletionStage using ListenableFutures.toCompletionStage(ListenableFuture) and chaining on that, or at the very least simply by using ListenableFutures.addErrorLogging(ListenableFuture, org.slf4j.Logger, String) (but better NOT by using the blocking Future.get() on it).

Parameters:

txRunner - the CheckedConsumer that needs a new write only transaction

Returns:

the ListenableFuture returned by AsyncWriteTransaction.submit(), or a failed future with an application specific exception (not from submit())

callWithNewReadWriteTransactionAndSubmit

@CheckReturnValue
<E extends Exception> com.google.common.util.concurrent.ListenableFuture<Void> callWithNewReadWriteTransactionAndSubmit(org.opendaylight.infrautils.utils.function.CheckedConsumer<org.opendaylight.controller.md.sal.binding.api.ReadWriteTransaction,E> txRunner)

Invokes a consumer with a NEW ReadWriteTransaction, and then submits that transaction and returns the Future from that submission, or cancels it if an exception was thrown and returns a failed future with that exception. Thus when this method returns, that transaction is guaranteed to have been either submitted or cancelled, and will never "leak" and waste memory.

The consumer should not (cannot) itself use AsyncWriteTransaction.cancel(), AsyncWriteTransaction.commit() or AsyncWriteTransaction.submit() (it will throw an UnsupportedOperationException).

This is an asynchronous API, like DataBroker's own; when returning from this method, the operation of the Transaction may well still be ongoing in the background, or pending; calling code therefore must handle the returned future, e.g. by passing it onwards (return), or by itself adding callback listeners to it using Futures' methods, or by transforming it into a CompletionStage using ListenableFutures.toCompletionStage(ListenableFuture) and chaining on that, or at the very least simply by using ListenableFutures.addErrorLogging(ListenableFuture, org.slf4j.Logger, String) (but better NOT by using the blocking Future.get() on it).

Parameters:

txRunner - the CheckedConsumer that needs a new read-write transaction

Returns:

the ListenableFuture returned by AsyncWriteTransaction.submit(), or a failed future with an application specific exception (not from submit())

applyWithNewReadWriteTransactionAndSubmit

@CheckReturnValue
<E extends Exception,R> com.google.common.util.concurrent.ListenableFuture<R> applyWithNewReadWriteTransactionAndSubmit(org.opendaylight.infrautils.utils.function.CheckedFunction<org.opendaylight.controller.md.sal.binding.api.ReadWriteTransaction,R,E> txRunner)

Invokes a function with a NEW ReadWriteTransaction, and then submits that transaction and returns the Future from that submission, or cancels it if an exception was thrown and returns a failed future with that exception. Thus when this method returns, that transaction is guaranteed to have been either submitted or cancelled, and will never "leak" and waste memory.

The function must not itself use AsyncWriteTransaction.cancel(), or AsyncWriteTransaction.submit() (it will throw an UnsupportedOperationException).

This is an asynchronous API, like DataBroker's own; when returning from this method, the operation of the Transaction may well still be ongoing in the background, or pending; calling code therefore must handle the returned future, e.g. by passing it onwards (return), or by itself adding callback listeners to it using Futures' methods, or by transforming it into a CompletionStage using ListenableFutures.toCompletionStage(ListenableFuture) and chaining on that, or at the very least simply by using ListenableFutures.addErrorLogging(ListenableFuture, org.slf4j.Logger, String) (but better NOT by using the blocking Future.get() on it).

Parameters:

txRunner - the CheckedFunction that needs a new read-write transaction

Returns:

the ListenableFuture returned by AsyncWriteTransaction.submit(), or a failed future with an application specific exception (not from submit())