2 * Copyright (c) 2017 Red Hat, Inc. and others. All rights reserved.
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.MoreExecutors;
12 import java.util.concurrent.Executor;
13 import javax.inject.Inject;
14 import org.opendaylight.mdsal.binding.api.DataBroker;
15 import org.opendaylight.mdsal.binding.api.WriteTransaction;
16 import org.opendaylight.mdsal.common.api.OptimisticLockFailedException;
19 * Implementation of {@link ManagedNewTransactionRunner} with automatic transparent retries.
21 * <h3>Details about the threading model used by this class</h3>
23 * <p>This class runs the first attempt to call the delegated {@link ManagedNewTransactionRunner},
24 * which typically is a {@link ManagedNewTransactionRunnerImpl} which safely invokes {@link WriteTransaction#commit()},
25 * in the using application's thread (like a {@link MoreExecutors#directExecutor()} would, if this were an
26 * {@link Executor}, which it's not).
28 * <p>Any retry attempts required, if that <code>submit()</code> (eventually) fails with an
29 * {@link OptimisticLockFailedException}, are run in the calling thread of that eventual future completion by a
30 * {@link MoreExecutors#directExecutor()} implicit in the constructor which does not require you to specify an
31 * explicit Executor argument. Normally that will be an internal thread from the respective DataBroker implementation,
32 * not your application's thread anymore, because that meanwhile could well be off doing something else! Normally,
33 * that is not a problem, because retries "should" be relatively uncommon, and (re)issuing some DataBroker
34 * <code>put()</code> or <code>delete()</code> and <code>re-submit()</code> <i>should</i> be fast.
36 * <p>If this default is not suitable (e.g. for particularly slow try/retry code), then you can specify
37 * another {@link Executor} to be used for the retries by using the alternative constructor.
39 * @author Michael Vorburger.ch & Stephen Kitt
42 // Do *NOT* mark this as @Singleton, because users choose Impl; and as long as this in API, because of https://wiki.opendaylight.org/view/BestPractices/DI_Guidelines#Nota_Bene
43 public class RetryingManagedNewTransactionRunner extends RetryingManagedNewTransactionRunnerImpl {
47 * Please see the class level documentation above for more details about the threading model used.
48 * This uses the default of 3 retries, which is typically suitable.
50 * @param dataBroker the {@link DataBroker} from which transactions are obtained
51 * @throws NullPointerException if {@code dataBroker} is {@code null}.
54 public RetryingManagedNewTransactionRunner(DataBroker dataBroker) {
55 super(new ManagedNewTransactionRunnerImpl(dataBroker));
60 * Please see the class level documentation above for more details about the threading model used.
62 * @param dataBroker the {@link DataBroker} from which transactions are obtained
63 * @param maxRetries the maximum number of retry attempts
65 public RetryingManagedNewTransactionRunner(DataBroker dataBroker, int maxRetries) {
66 super(new ManagedNewTransactionRunnerImpl(dataBroker), maxRetries);
71 * Please see the class level documentation above for more details about the threading model used.
73 * @param dataBroker the {@link DataBroker} from which transactions are obtained
74 * @param executor the {@link Executor} to asynchronously run any retry attempts in
75 * @param maxRetries the maximum number of retry attempts
77 public RetryingManagedNewTransactionRunner(DataBroker dataBroker, Executor executor, int maxRetries) {
78 super(new ManagedNewTransactionRunnerImpl(dataBroker), executor, maxRetries);