mdsalutil/mdsalutil-api/src/main/java/org/opendaylight/genius/infra/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.genius.infra;
   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 import org.opendaylight.mdsal.common.api.ReadFailedException;
  18
  19 /**
  20  * Implementation of {@link ManagedNewTransactionRunner} with automatic transparent retries on transaction failure
  21  * ({@link OptimisticLockFailedException} on write transactions and {@link ReadFailedException} on read transactions
  22  * will cause the operation constructing the transaction to be re-run).
  23  *
  24  * <h3>Details about the threading model used by this class</h3>
  25  *
  26  * <p>This class runs the first attempt to call the delegated {@link ManagedNewTransactionRunner},
  27  * which typically is a {@link ManagedNewTransactionRunnerImpl} which safely invokes
  28  * {@link WriteTransaction#commit()} ,
  29  * in the using application's thread (like a {@link MoreExecutors#directExecutor()} would, if this were an
  30  * {@link Executor}, which it's not).
  31  *
  32  * <p>Any retry attempts required, if that <code>submit()</code> (eventually) fails with an
  33  * {@link OptimisticLockFailedException}, are run in the calling thread of that eventual future completion by a
  34  * {@link MoreExecutors#directExecutor()} implicit in the constructor which does not require you to specify an
  35  * explicit Executor argument.  Normally that will be an internal thread from the respective DataBroker implementation,
  36  * not your application's thread anymore, because that meanwhile could well be off doing something else!  Normally,
  37  * that is not a problem, because retries "should" be relatively uncommon, and (re)issuing some DataBroker
  38  * <code>put()</code> or <code>delete()</code> and <code>re-submit()</code> <i>should</i> be fast.
  39  *
  40  * <p>If this default is not suitable (e.g. for particularly slow try/retry code), then you can specify
  41  * another {@link Executor} to be used for the retries by using the alternative constructor.
  42  *
  43  * @author Michael Vorburger.ch &amp; Stephen Kitt
  44  * @deprecated Use {@link org.opendaylight.mdsal.binding.util.RetryingManagedNewTransactionRunner} instead.
  45  */
  46 @Beta
  47 @Deprecated
  48 // 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
  49 public class RetryingManagedNewTransactionRunner extends RetryingManagedNewTransactionRunnerImpl {
  50
  51     /**
  52      * Constructor.
  53      * Please see the class level documentation above for more details about the threading model used.
  54      * This uses the default of 3 retries, which is typically suitable.
  55      *
  56      * @param dataBroker the {@link DataBroker} from which transactions are obtained
  57      */
  58     @Inject
  59     public RetryingManagedNewTransactionRunner(DataBroker dataBroker) {
  60         super(new ManagedNewTransactionRunnerImpl(dataBroker));
  61     }
  62
  63     /**
  64      * Constructor.
  65      * Please see the class level documentation above for more details about the threading model used.
  66      *
  67      * @param dataBroker the {@link DataBroker} from which transactions are obtained
  68      * @param maxRetries the maximum number of retry attempts
  69      */
  70     public RetryingManagedNewTransactionRunner(DataBroker dataBroker, int maxRetries) {
  71         super(new ManagedNewTransactionRunnerImpl(dataBroker), maxRetries);
  72     }
  73
  74     /**
  75      * Constructor.
  76      * Please see the class level documentation above for more details about the threading model used.
  77      *
  78      * @param dataBroker the {@link DataBroker} from which transactions are obtained
  79      * @param executor the {@link Executor} to asynchronously run any retry attempts in
  80      * @param maxRetries the maximum number of retry attempts
  81      */
  82     public RetryingManagedNewTransactionRunner(DataBroker dataBroker, Executor executor, int maxRetries) {
  83         super(new ManagedNewTransactionRunnerImpl(dataBroker), executor, maxRetries);
  84     }
  85 }