Package org.osgi.service.transaction.control

Class TransactionBuilder

  • All Implemented Interfaces:
    TransactionStarter
    @ProviderType
public abstract class TransactionBuilder
extends java.lang.Object
implements TransactionStarter
    A builder for a piece of transactional work

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.util.List<java.lang.Class<? extends java.lang.Throwable>> noRollbackFor
      The list of Throwable types that must not trigger rollback
      protected java.util.List<java.lang.Class<? extends java.lang.Throwable>> rollbackFor
      The list of Throwable types that must trigger rollback

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      TransactionBuilder noRollbackFor​(java.lang.Class<? extends java.lang.Throwable> t, java.lang.Class<? extends java.lang.Throwable>... throwables)
      Declare a list of Exception types (and their subtypes) that must not trigger a rollback.
      abstract TransactionBuilder readOnly()
      Indicate to the Transaction Control service that this transaction will be read-only.
      TransactionBuilder rollbackFor​(java.lang.Class<? extends java.lang.Throwable> t, java.lang.Class<? extends java.lang.Throwable>... throwables)
      Declare a list of Exception types (and their subtypes) that must trigger a rollback.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • rollbackFor

        protected final java.util.List<java.lang.Class<? extends java.lang.Throwable>> rollbackFor
        The list of Throwable types that must trigger rollback

      • noRollbackFor

        protected final java.util.List<java.lang.Class<? extends java.lang.Throwable>> noRollbackFor
        The list of Throwable types that must not trigger rollback

    • Constructor Detail

      • TransactionBuilder

        public TransactionBuilder()

    • Method Detail

      • rollbackFor

        @SafeVarargs
public final TransactionBuilder rollbackFor​(java.lang.Class<? extends java.lang.Throwable> t,
                                            java.lang.Class<? extends java.lang.Throwable>... throwables)
        Declare a list of Exception types (and their subtypes) that must trigger a rollback. By default the transaction will rollback for all Exceptions. If a more specific type is registered using noRollbackFor(Class, Class...) then that type will not trigger rollback. If the same type is registered using both rollbackFor(Class, Class...) and noRollbackFor(Class, Class...) then the transaction will not begin and will instead throw a TransactionException

        Note that the behavior of this method differs from Java EE and Spring in two ways:

        • In Java EE and Spring transaction management checked exceptions are considered "normal returns" and do not trigger rollback. Using an Exception as a normal return value is considered a bad design practice. In addition this means that checked Exceptions such as java.sql.SQLException do not trigger rollback by default. This, in turn, leads to implementation mistakes that break the transactional behavior of applications.
        • In Java EE it is legal to specify the same Exception type in rollbackFor and noRollbackFor. Stating that the same Exception should both trigger and not trigger rollback is a logical impossibility, and clearly indicates an API usage error. This API therefore enforces usage by triggering an exception in this invalid case.
        Parameters:
        t -
        throwables - The Exception types that should trigger rollback
        Returns:
        this builder

      • noRollbackFor

        @SafeVarargs
public final TransactionBuilder noRollbackFor​(java.lang.Class<? extends java.lang.Throwable> t,
                                              java.lang.Class<? extends java.lang.Throwable>... throwables)
        Declare a list of Exception types (and their subtypes) that must not trigger a rollback. By default the transaction will rollback for all Exceptions. If an Exception type is registered using this method then that type and its subtypes will not trigger rollback. If the same type is registered using both rollbackFor(Class, Class...) and noRollbackFor(Class, Class...) then the transaction will not begin and will instead throw a TransactionException

        Note that the behavior of this method differs from Java EE and Spring in two ways:

        • In Java EE and Spring transaction management checked exceptions are considered "normal returns" and do not trigger rollback. Using an Exception as a normal return value is considered a bad design practice. In addition this means that checked Exceptions such as java.sql.SQLException do not trigger rollback by default. This, in turn, leads to implementation mistakes that break the transactional behavior of applications.
        • In Java EE it is legal to specify the same Exception type in rollbackFor and noRollbackFor. Stating that the same Exception should both trigger and not trigger rollback is a logical impossibility, and clearly indicates an API usage error. This API therefore enforces usage by triggering an exception in this invalid case.
        Parameters:
        t - An exception type that should not trigger rollback
        throwables - further exception types that should not trigger rollback
        Returns:
        this builder

      • readOnly

        public abstract TransactionBuilder readOnly()
        Indicate to the Transaction Control service that this transaction will be read-only. This hint may be used by the Transaction Control service and associated resources to optimize the transaction.

        Note that this method is for optimization purposes only. The TransactionControl service is free to ignore the call if it does not offer read-only optimization.

        If a transaction is marked read-only and then the scoped work performs a write operation on a resource then this is a programming error. The resource is free to raise an exception when the write is attempted, or to permit the write operation. As a result the transaction may commit successfully, or may rollback.

        Returns:
        this builder