This automatic retry logic is very handy for solving the problem of transient deadlocks that can occur in complex Java/ORM applications. Due to the ORM layer hiding the details of the underlying data access patterns, it's often difficult to design Java/ORM applications such that transient deadlocks at the database layer can't occur. Since these deadlocks can often be dealt with simply by retrying the transaction, having retry logic automatically applied can eliminate this problem.

Note, beans involved in transactions should either be stateless, or be prepared to rollback any state changes on transaction failure; of course, this is true whether or not transactions are automatically being retried, but adding automatic retry can magnify pre-existing bugs of that nature.

The @RetryTransaction annotation is ignored unless all of the following conditions are satisfied:

• The method (and/or the containing type) must be annotated with both @Transactional and @RetryTransaction
• The @Transactional annotation must have propagation set to either PROPAGATION_REQUIRED or PROPAGATION_REQUIRES_NEW (other propagation values do not involve creating new transactions).
• In the case of PROPAGATION_REQUIRED propagation, there must not be a transaction already open in the calling thread. In other words, the invoked method must be the one responsible for creating the transaction.
• The method's class must be woven (either at build time or runtime) using the AspectJ compiler with the RetryTransactionAspect aspect (included in the dellroad-stuff JAR file).
• The RetryTransactionAspect aspect must be configured with a PersistenceExceptionTranslator appropriate for the ORM layer being used. The simplest way to do this is to include the aspect in your Spring application context, for example:

  
        <bean class="org.dellroad.stuff.spring.RetryTransactionAspect" factory-method="aspectOf"
          p:persistenceExceptionTranslator-ref="myJpaDialect"/>
        

  This also gives you the opportunity to change the default values for maxRetries(), initialDelay(), and maximumDelay(), which are applied when not explicitly overridden in the annotation, for example:

  
        <bean class="org.dellroad.stuff.spring.RetryTransactionAspect" factory-method="aspectOf"
          p:persistenceExceptionTranslator-ref="myJpaDialect" p:maxRetriesDefault="2"
          p:initialDelayDefault="25" p:maximumDelayDefault="5000"/>
        

Logging behavior: Normal activity is logged at trace level, retries are logged at debug level, and errors are logged at error level.

Transactional code can determine the transaction attempt number using the RetryTransactionProvider interface implemented by the aspect. RetryTransactionProvider.getAttemptNumber() method returns the current attempt number (1, 2, 3...), or zero if the current thread is not executing within activated retry logic:

      import org.dellroad.stuff.spring.RetryTransactionProvider;
      ...

      @Autowired
      private RetryTransactionProvider retryTransactionProvider;
      ...

      @RetryTransaction
      @Transactional
      public void doSomething() {
          ...
          final int attempt = this.retryTransactionProvider.getAttempt();
          ...
      }