binding/mdsal-binding-util/src/main/java/org/opendaylight/mdsal/binding/util/RetryingManagedNewTransactionRunner.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.mdsal.binding.util;
   9
  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;
  17
  18 /**
  19  * Implementation of {@link ManagedNewTransactionRunner} with automatic transparent retries.
  20  *
  21  * <h2>Details about the threading model used by this class</h2>
  22  *
  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).
  27  *
  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.
  35  *
  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.
  38  *
  39  * @author Michael Vorburger.ch &amp; Stephen Kitt
  40  */
  41 @Beta
  42 // Do *NOT* mark this as @Singleton, because users choose Impl; and as long as this in API, because of
  43 // https://wiki-archive.opendaylight.org/view/BestPractices/DI_Guidelines#Nota_Bene
  44 public class RetryingManagedNewTransactionRunner extends RetryingManagedNewTransactionRunnerImpl {
  45     /**
  46      * Constructor.
  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.
  49      *
  50      * @param dataBroker the {@link DataBroker} from which transactions are obtained
  51      * @throws NullPointerException if {@code dataBroker} is {@code null}.
  52      */
  53     @Inject
  54     public RetryingManagedNewTransactionRunner(final DataBroker dataBroker) {
  55         super(new ManagedNewTransactionRunnerImpl(dataBroker));
  56     }
  57
  58     /**
  59      * Constructor.
  60      * Please see the class level documentation above for more details about the threading model used.
  61      *
  62      * @param dataBroker the {@link DataBroker} from which transactions are obtained
  63      * @param maxRetries the maximum number of retry attempts
  64      */
  65     public RetryingManagedNewTransactionRunner(final DataBroker dataBroker, final int maxRetries) {
  66         super(new ManagedNewTransactionRunnerImpl(dataBroker), maxRetries);
  67     }
  68
  69     /**
  70      * Constructor.
  71      * Please see the class level documentation above for more details about the threading model used.
  72      *
  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
  76      */
  77     public RetryingManagedNewTransactionRunner(final DataBroker dataBroker, final Executor executor,
  78             final int maxRetries) {
  79         super(new ManagedNewTransactionRunnerImpl(dataBroker), executor, maxRetries);
  80     }
  81 }