io.ebean.annotation

Annotation Type Transactional

@Target(value={METHOD,TYPE})
 @Retention(value=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.

 // a normal class
 public class MySimpleUserService {

   // this method is transactional automatically handling
   // transaction begin, commit and rollback etc
   @Transactional
   public void runInTrans() throws IOException {

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

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

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
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 Throwable's 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 Throwable's 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 Detail

type

public abstract TxType type

The type of transaction scoping. Defaults to REQUIRED.

Default:

io.ebean.annotation.TxType.REQUIRED

batch

public abstract PersistBatch batch

Persist batch mode for the transaction.

Default:

io.ebean.annotation.PersistBatch.INHERIT

batchOnCascade

public abstract 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:

io.ebean.annotation.PersistBatch.INHERIT

batchSize

public abstract 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

public abstract 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

public abstract 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:

io.ebean.annotation.TxIsolation.DEFAULT

flushOnQuery

public abstract boolean flushOnQuery

Set this to false if the JDBC batch should not be automatically flushed when a query is executed.

Default:

true

readOnly

public abstract boolean readOnly

Set this to true if the transaction should be only contain queries.

Default:

false

skipCache

public abstract boolean skipCache

Set this to true such that the L2 cache is not used by queries that otherwise would.

Default:

false

label

public abstract String label

Set a label to identify the transaction in performance metrics and logging.

Default:

""

rollbackFor

public abstract Class<? extends Throwable>[] rollbackFor

The Throwable's that will explicitly cause a rollback to occur.

Default:

{}

noRollbackFor

public abstract Class<? extends Throwable>[] noRollbackFor

The Throwable's that will explicitly NOT cause a rollback to occur.

Default:

{}

profileId

public abstract 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