Module io.ebean.annotation
Package io.ebean.annotation

Annotation Type Transactional

@Target({METHOD,TYPE}) @Retention(RUNTIME) public @interface Transactional
Specify transaction scoping for a method.

This is only supported if "Enhancement" is used via javaagent, ANT task or IDE enhancement plugin etc.

Note: Currently there are 3 known annotations that perform this role.

  • EJB's javax.ejb.TransactionAttribute
  • Spring's org.springframework.transaction.annotation.Transactional
  • and this one, Ebean's own Transactional

Spring created their one because the EJB annotation does not support features such as isolation level and specifying rollbackOn, noRollbackOn exceptions. This one exists for Ebean because I agree that the standard one is insufficient and don't want to include a dependency on Spring.

The default behaviour of EJB (and hence Spring) is to NOT ROLLBACK on checked exceptions. I find this very counter-intuitive. Ebean will provide a property to set the default behaviour to rollback on any exception and optionally change the setting to be consistent with EJB/Spring if people wish to do so.

Example:



    @Transactional
    public void runInTrans() {

      // tasks performed within the transaction
      ...
      // find some objects
      Customer cust = ebeanServer.find(Customer.class, 42);

      Order order = ...;
      ...
      // save some objects
      customer.save();
      order.save();
    }

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    TxOption
    autoPersistUpdates
    Experimental option to automatically persist mutated entity beans.
    PersistBatch
    batch
    Persist batch mode for the transaction.
    PersistBatch
    batchOnCascade
    Persist batch mode for the request if not set on the transaction.
    int
    batchSize
    The batch size to use when using JDBC batch mode.
    boolean
    flushOnQuery
    Set this to false if the JDBC batch should not be automatically flushed when a query is executed.
    boolean
    getGeneratedKeys
    Set to false when we want to skip getting generatedKeys.
    TxIsolation
    isolation
    The transaction isolation level this transaction should have.
    String
    label
    Set a label to identify the transaction in performance metrics and logging.
    Class<? extends Throwable>[]
    noRollbackFor
    The Throwables that will explicitly NOT cause a rollback to occur.
    int
    profileId
    A key used to identify a specific transaction for profiling purposes.
    boolean
    readOnly
    Set this to true if the transaction should be only contain queries.
    Class<? extends Throwable>[]
    rollbackFor
    The Throwables that will explicitly cause a rollback to occur.
    boolean
    skipCache
    Set this to true such that the L2 cache is not used by queries that otherwise would.
    TxType
    type
    The type of transaction scoping.

  • Element Details

    • type

      TxType type
      The type of transaction scoping. Defaults to REQUIRED.
      Default:
      REQUIRED

    • autoPersistUpdates

      TxOption autoPersistUpdates
      Experimental option to automatically persist mutated entity beans.

      That is, beans that are fetched and mutated are automatically persisted without requiring explicit call to update().

      Default:
      DEFAULT

    • batch

      PersistBatch batch
      Persist batch mode for the transaction.
      Default:
      INHERIT

    • batchOnCascade

      PersistBatch batchOnCascade
      Persist batch mode for the request if not set on the transaction.

      If batch is set to NONE then batchOnCascade can be set to INSERT or ALL and then each save(), delete(), insert(), update() request that cascades to child beans can use JDBC batch.

      Default:
      INHERIT

    • batchSize

      int batchSize
      The batch size to use when using JDBC batch mode.

      If unset this defaults to the value set in ServerConfig.

      Default:
      0

    • getGeneratedKeys

      boolean getGeneratedKeys
      Set to false when we want to skip getting generatedKeys.

      This is typically used in the case of large batch inserts where we get a performance benefit from not calling getGeneratedKeys (as we are going to insert a lot of rows and have no need for the Id values after the insert).

      Default:
      true

    • isolation

      TxIsolation isolation
      The transaction isolation level this transaction should have.

      This will only be used if this scope creates the transaction. If the transaction has already started then this will currently be ignored (you could argue that it should throw an exception).

      Default:
      DEFAULT

    • flushOnQuery

      boolean flushOnQuery
      Set this to false if the JDBC batch should not be automatically flushed when a query is executed.
      Default:
      true

    • readOnly

      boolean readOnly
      Set this to true if the transaction should be only contain queries.
      Default:
      false

    • skipCache

      boolean skipCache
      Set this to true such that the L2 cache is not used by queries that otherwise would.
      Default:
      false

    • label

      String label
      Set a label to identify the transaction in performance metrics and logging.
      Default:
      ""

    • rollbackFor

      Class<? extends Throwable>[] rollbackFor
      The Throwables that will explicitly cause a rollback to occur.
      Default:
      {}

    • noRollbackFor

      Class<? extends Throwable>[] noRollbackFor
      The Throwables that will explicitly NOT cause a rollback to occur.
      Default:
      {}

    • profileId

      int profileId
      A key used to identify a specific transaction for profiling purposes.

      If set to -1 this means there should be no profiling on this transaction.

      If not set (left at 0) this means the profilingId can be automatically set during transactional enhancement.

      Default:
      0