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