2 * Copyright © 2018 Red Hat, Inc. and others.
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
8 package org.opendaylight.mdsal.binding.util;
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;
22 * Managed transaction factories provide managed transactions, <em>i.e.</em> transactions which are automatically
23 * submitted or cancelled (write) or closed (read).
26 * This is a common interface for broker- and chain-based transaction managers, and should not be used directly.
29 public interface ManagedTransactionFactory {
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
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.)
38 * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
41 * @param <D> datastore type
42 * @param <E> thrown exception type
43 * @param <R> result type
44 * @param datastoreType the {@link Datastore} type that will be accessed
45 * @param txFunction the {@link InterruptibleCheckedFunction} that needs a new read transaction
46 * @return the result of the function.
47 * @throws E if an error occurs.
48 * @throws InterruptedException if the function is interrupted (this is passed through from the provided function).
50 <D extends Datastore, E extends Exception, R> R applyInterruptiblyWithNewReadOnlyTransactionAndClose(
51 Class<D> datastoreType, InterruptibleCheckedFunction<TypedReadTransaction<D>, R, E> txFunction)
52 throws E, InterruptedException;
55 * Invokes a function with a <b>NEW</b> {@link TypedReadTransaction}, and ensures that that transaction is closed.
56 * Thus when this method returns, that transaction is guaranteed to have been closed, and will never "leak" and
59 * <p>The function must not itself attempt to close the transaction. (It can't directly, since
60 * {@link TypedReadTransaction} doesn't expose a {@code close()} method.)
62 * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
65 * @param <D> datastore type
66 * @param <E> thrown exception type
67 * @param <R> result type
68 * @param datastoreType the {@link Datastore} type that will be accessed
69 * @param txFunction the {@link InterruptibleCheckedFunction} that needs a new read transaction
70 * @return the result of the function.
71 * @throws E if an error occurs.
73 <D extends Datastore, E extends Exception, R> R applyWithNewReadOnlyTransactionAndClose(Class<D> datastoreType,
74 CheckedFunction<TypedReadTransaction<D>, R, E> txFunction) throws E;
77 * Invokes a function with a <b>NEW</b> {@link ReadWriteTransaction}, and then submits that transaction and
78 * returns the Future from that submission, or cancels it if an exception was thrown and returns a failed
79 * future with that exception. Thus when this method returns, that transaction is guaranteed to have
80 * been either submitted or cancelled, and will never "leak" and waste memory.
82 * <p>The function must not itself use
83 * {@link ReadWriteTransaction#cancel()}, or
84 * {@link ReadWriteTransaction#commit()} (it will throw an {@link UnsupportedOperationException}).
86 * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
89 * <p>This is an asynchronous API, like {@link DataBroker}'s own;
90 * when returning from this method, the operation of the Transaction may well still be ongoing in the background,
92 * calling code therefore <b>must</b> handle the returned future, e.g. by passing it onwards (return),
93 * or by itself adding callback listeners to it using {@link Futures}' methods, or by transforming it into a
94 * {@link CompletionStage}
95 * (but better NOT by using the blocking {@link Future#get()} on it).
97 * @param <D> datastore type
98 * @param <E> thrown exception type
99 * @param <R> result type
100 * @param datastoreType the {@link Datastore} type that will be accessed
101 * @param txFunction the {@link InterruptibleCheckedFunction} that needs a new read-write transaction
102 * @return the {@link FluentFuture} returned by {@link ReadWriteTransaction#commit()}, or a failed future with an
103 * application specific exception (not from submit())
106 <D extends Datastore, E extends Exception, R>
107 FluentFuture<R> applyWithNewReadWriteTransactionAndSubmit(Class<D> datastoreType,
108 InterruptibleCheckedFunction<TypedReadWriteTransaction<D>, R, E> txFunction);
111 * Invokes a function with a <b>NEW</b> {@link ReadTransaction}, and ensures that that transaction is closed.
112 * Thus when this method returns, that transaction is guaranteed to have been closed, and will never "leak" and
115 * <p>The function must not itself attempt to close the transaction. (It can't directly, since
116 * {@link ReadTransaction} doesn't expose a {@code close()} method.)
118 * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
121 * @param <D> datastore type
122 * @param <E> thrown exception type
123 * @param datastoreType the {@link Datastore} type that will be accessed
124 * @param txConsumer the {@link InterruptibleCheckedFunction} that needs a new read transaction
125 * @throws E if an error occurs.
126 * @throws InterruptedException if the function is interrupted (this is passed through from the provided function).
128 <D extends Datastore, E extends Exception> void callInterruptiblyWithNewReadOnlyTransactionAndClose(
129 Class<D> datastoreType, InterruptibleCheckedConsumer<TypedReadTransaction<D>, E> txConsumer)
130 throws E, InterruptedException;
133 * Invokes a function with a <b>NEW</b> {@link ReadTransaction}, and ensures that that transaction is closed.
134 * Thus when this method returns, that transaction is guaranteed to have been closed, and will never "leak" and
137 * <p>The function must not itself attempt to close the transaction. (It can't directly, since
138 * {@link ReadTransaction} doesn't expose a {@code close()} method.)
140 * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
143 * @param <D> datastore type
144 * @param <E> thrown exception type
145 * @param datastoreType the {@link Datastore} type that will be accessed
146 * @param txConsumer the {@link InterruptibleCheckedFunction} that needs a new read transaction
147 * @throws E if an error occurs.
149 <D extends Datastore, E extends Exception> void callWithNewReadOnlyTransactionAndClose(Class<D> datastoreType,
150 CheckedConsumer<TypedReadTransaction<D>, E> txConsumer) throws E;
153 * Invokes a consumer with a <b>NEW</b> {@link ReadWriteTransaction}, and then submits that transaction and
154 * returns the Future from that submission, or cancels it if an exception was thrown and returns a failed
155 * future with that exception. Thus when this method returns, that transaction is guaranteed to have
156 * been either submitted or cancelled, and will never "leak" and waste memory.
158 * <p>The consumer should not (cannot) itself use
159 * {@link ReadWriteTransaction#cancel()}, or
160 * {@link ReadWriteTransaction#commit()} (it will throw an {@link UnsupportedOperationException}).
162 * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
165 * <p>This is an asynchronous API, like {@link DataBroker}'s own;
166 * when returning from this method, the operation of the Transaction may well still be ongoing in the background,
168 * calling code therefore <b>must</b> handle the returned future, e.g. by passing it onwards (return),
169 * or by itself adding callback listeners to it using {@link Futures}' methods, or by transforming it into a
170 * {@link CompletionStage}
171 * (but better NOT by using the blocking {@link Future#get()} on it).
173 * @param <D> datastore type
174 * @param <E> thrown exception type
175 * @param datastoreType the {@link Datastore} type that will be accessed
176 * @param txConsumer the {@link InterruptibleCheckedConsumer} that needs a new read-write transaction
177 * @return the {@link FluentFuture} returned by {@link ReadWriteTransaction#commit()}, or a failed future with an
178 * application specific exception (not from submit())
181 <D extends Datastore, E extends Exception>
182 FluentFuture<? extends Object> callWithNewReadWriteTransactionAndSubmit(Class<D> datastoreType,
183 InterruptibleCheckedConsumer<TypedReadWriteTransaction<D>, E> txConsumer);
186 * Invokes a consumer with a <b>NEW</b> {@link WriteTransaction}, and then submits that transaction and
187 * returns the Future from that submission, or cancels it if an exception was thrown and returns a failed
188 * future with that exception. Thus when this method returns, that transaction is guaranteed to have
189 * been either submitted or cancelled, and will never "leak" and waste memory.
191 * <p>The consumer should not (cannot) itself use
192 * {@link WriteTransaction#cancel()}, or
193 * {@link WriteTransaction#commit()} (it will throw an {@link UnsupportedOperationException}).
195 * <p>The provided transaction is specific to the given logical datastore type and cannot be used for any
198 * <p>This is an asynchronous API, like {@link DataBroker}'s own;
199 * when returning from this method, the operation of the Transaction may well still be ongoing in the background,
201 * calling code therefore <b>must</b> handle the returned future, e.g. by passing it onwards (return),
202 * or by itself adding callback listeners to it using {@link Futures}' methods, or by transforming it into a
203 * {@link CompletionStage}
204 * (but better NOT by using the blocking {@link Future#get()} on it).
206 * @param <D> datastore type
207 * @param <E> thrown exception type
208 * @param datastoreType the {@link Datastore} type that will be accessed
209 * @param txConsumer the {@link InterruptibleCheckedConsumer} that needs a new write only transaction
210 * @return the {@link FluentFuture} returned by {@link WriteTransaction#commit()}, or a failed future with an
211 * application specific exception (not from submit())
214 <D extends Datastore, E extends Exception>
215 FluentFuture<? extends Object> callWithNewWriteOnlyTransactionAndSubmit(Class<D> datastoreType,
216 InterruptibleCheckedConsumer<TypedWriteTransaction<D>, E> txConsumer);