com.avaje.ebean

Interface Transaction

All Superinterfaces:

AutoCloseable, Closeable

public interface Transaction
extends Closeable

The Transaction object. Typically representing a JDBC or JTA transaction.

Field Summary

Fields

Modifier and Type	Field and Description
static int	READ_COMMITTED Read Committed transaction isolation.
static int	READ_UNCOMMITTED Read Uncommitted transaction isolation.
static int	REPEATABLE_READ Repeatable read transaction isolation.
static int	SERIALIZABLE Serializable transaction isolation.

Method Summary

Modifier and Type	Method and Description
void	addModification(String tableName, boolean inserts, boolean updates, boolean deletes) Add table modification information to the TransactionEvent.
void	commit() Commit the transaction.
void	end() If the transaction is active then perform rollback.
void	flushBatch() The batch will be flushing automatically but you can use this to explicitly flush the batch if you like.
PersistBatch	getBatch() Return the batch mode at the transaction level.
PersistBatch	getBatchOnCascade() Return the batch mode at the request level (for each save(), insert(), update() or delete()).
int	getBatchSize() Return the current batch size.
Connection	getConnection() Return the underlying Connection object.
Object	getUserObject(String name) Get an object added with putUserObject(String, Object).
boolean	isActive() Return true if the transaction is active.
boolean	isBatchFlushOnQuery() Return true if the batch (of persisted beans or executed UpdateSql etc) should be flushed prior to executing a query.
boolean	isReadOnly() Return true if this transaction is read only.
void	putUserObject(String name, Object value) Add an arbitrary user object to the transaction.
void	register(TransactionCallback callback) Register a TransactionCallback with this transaction.
void	rollback() Rollback the transaction.
void	rollback(Throwable e) Rollback the transaction specifying a throwable that caused the rollback to occur.
void	setBatch(PersistBatch persistBatchMode) The JDBC batch mode to use for this transaction.
void	setBatchFlushOnMixed(boolean batchFlushOnMixed) By default when mixing UpdateSql (or CallableSql) with Beans the batch is automatically flushed when you change (between persisting beans and executing UpdateSql or CallableSql).
void	setBatchFlushOnQuery(boolean batchFlushOnQuery) By default executing a query will automatically flush any batched statements (persisted beans, executed UpdateSql etc).
void	setBatchGetGeneratedKeys(boolean getGeneratedKeys) Specify if you want batched inserts to use getGeneratedKeys.
void	setBatchMode(boolean useBatch) Turn on or off statement batching.
void	setBatchOnCascade(PersistBatch batchOnCascadeMode) Set the JDBC batch mode to use for a save() or delete() request.
void	setBatchSize(int batchSize) Specify the number of statements before a batch is flushed automatically.
void	setPersistCascade(boolean persistCascade) Explicitly turn off or on the cascading nature of save() and delete().
void	setReadOnly(boolean readOnly) Set whether this transaction should be readOnly.
void	setUpdateAllLoadedProperties(boolean updateAllLoadedProperties) Set to true when you want all loaded properties to be included in the update (rather than just the changed properties).

Methods inherited from interface java.io.Closeable

close

Field Detail

READ_COMMITTED

static final int READ_COMMITTED

Read Committed transaction isolation. Same as java.sql.Connection.TRANSACTION_READ_COMMITTED.

See Also:

Constant Field Values

READ_UNCOMMITTED

static final int READ_UNCOMMITTED

Read Uncommitted transaction isolation. Same as java.sql.Connection.TRANSACTION_READ_UNCOMMITTED.

See Also:

Constant Field Values

REPEATABLE_READ

static final int REPEATABLE_READ

Repeatable read transaction isolation. Same as java.sql.Connection.TRANSACTION_REPEATABLE_READ.

See Also:

Constant Field Values

SERIALIZABLE

static final int SERIALIZABLE

Serializable transaction isolation. Same as java.sql.Connection.TRANSACTION_SERIALIZABLE.

See Also:

Constant Field Values

Method Detail

register

void register(TransactionCallback callback)

Register a TransactionCallback with this transaction.

isReadOnly

boolean isReadOnly()

Return true if this transaction is read only.

setReadOnly

void setReadOnly(boolean readOnly)

Set whether this transaction should be readOnly.

commit

void commit()
     throws javax.persistence.RollbackException

Commit the transaction.

Throws:

javax.persistence.RollbackException

rollback

void rollback()
       throws javax.persistence.PersistenceException

Rollback the transaction.

Throws:

javax.persistence.PersistenceException

rollback

void rollback(Throwable e)
       throws javax.persistence.PersistenceException

Rollback the transaction specifying a throwable that caused the rollback to occur.

If you are using transaction logging this will log the throwable in the transaction logs.

Throws:

javax.persistence.PersistenceException

end

void end()
  throws javax.persistence.PersistenceException

If the transaction is active then perform rollback. Otherwise do nothing.

Throws:

javax.persistence.PersistenceException

isActive

boolean isActive()

Return true if the transaction is active.

setPersistCascade

void setPersistCascade(boolean persistCascade)

Explicitly turn off or on the cascading nature of save() and delete(). This gives the developer exact control over what beans are saved and deleted rather than Ebean cascading detecting 'dirty/modified' beans etc.

This is useful if you can getting back entity beans from a layer of code (potentially remote) and you prefer to have exact control.

This may also be useful if you are using jdbc batching with jdbc drivers that do not support getGeneratedKeys.

setUpdateAllLoadedProperties

void setUpdateAllLoadedProperties(boolean updateAllLoadedProperties)

Set to true when you want all loaded properties to be included in the update (rather than just the changed properties).

You might set this when using JDBC batch in order to get multiple updates with slightly different sets of changed properties into the same statement and hence better JDBC batch performance.

setBatchMode

void setBatchMode(boolean useBatch)

Turn on or off statement batching. Statement batching can be transparent for drivers and databases that support getGeneratedKeys. Otherwise you may wish to specifically control when batching is used via this method.

Refer to java.sql.PreparedStatement.addBatch();

Note that you may also wish to use the setPersistCascade method to stop save and delete cascade behaviour. You may do this to have full control over the order of execution rather than the normal cascading fashion.

Note that the execution order in batch mode may be different from non batch mode execution order. Also note that insert behaviour may be different depending on the JDBC driver and its support for getGeneratedKeys. That is, for JDBC drivers that do not support getGeneratedKeys you may not get back the generated IDs (used for inserting associated detail beans etc).

Calls to save(), delete(), insert() and execute() all support batch processing. This includes normal beans, MapBean, CallableSql and UpdateSql.

The flushing of the batched statements is automatic but you can call batchFlush when you like. Note that flushing occurs when a query is executed or when you mix UpdateSql and CallableSql with save and delete of beans.

Example: batch processing executing every 3 rows

String data = "This is a simple test of the batch processing"
            + " mode and the transaction execute batch method";

String[] da = data.split(" ");

String sql = "{call sp_t3(?,?)}";

CallableSql cs = new CallableSql(sql);
cs.registerOut(2, Types.INTEGER);

// (optional) inform eBean this stored procedure
// inserts into a table called sp_test
cs.addModification("sp_test", true, false, false);

Transaction txn = ebeanServer.beginTransaction();
txn.setBatchMode(true);
txn.setBatchSize(3);
try {
  for (int i = 0; i < da.length;) {
    cs.setParameter(1, da[i]);
    ebeanServer.execute(cs);
  }

  // NB: commit implicitly flushes
  txn.commit();

} finally {
  txn.end();
}

setBatch

void setBatch(PersistBatch persistBatchMode)

The JDBC batch mode to use for this transaction.

If this is NONE then JDBC batch can still be used for each request - save(), insert(), update() or delete() and this would be useful if the request cascades to detail beans.

Parameters:

persistBatchMode - the batch mode to use for this transaction

See Also:

ServerConfig.setPersistBatch(com.avaje.ebean.config.PersistBatch)

getBatch

PersistBatch getBatch()

Return the batch mode at the transaction level.

setBatchOnCascade

void setBatchOnCascade(PersistBatch batchOnCascadeMode)

Set the JDBC batch mode to use for a save() or delete() request.

This only takes effect when batch mode on the transaction has not already meant that JDBC batch mode is being used.

This is useful when the single save() or delete() cascades. For example, inserting a 'master' cascades and inserts a collection of 'detail' beans. The detail beans can be inserted using JDBC batch.

Parameters:

batchOnCascadeMode - the batch mode to use per save(), insert(), update() or delete()

See Also:

ServerConfig.setPersistBatchOnCascade(com.avaje.ebean.config.PersistBatch)

getBatchOnCascade

PersistBatch getBatchOnCascade()

Return the batch mode at the request level (for each save(), insert(), update() or delete()).

setBatchSize

void setBatchSize(int batchSize)

Specify the number of statements before a batch is flushed automatically.

getBatchSize

int getBatchSize()

Return the current batch size.

setBatchGetGeneratedKeys

void setBatchGetGeneratedKeys(boolean getGeneratedKeys)

Specify if you want batched inserts to use getGeneratedKeys.

By default batched inserts will try to use getGeneratedKeys if it is supported by the underlying jdbc driver and database.

You may want to turn getGeneratedKeys off when you are inserting a large number of objects and you don't care about getting back the ids.

setBatchFlushOnMixed

void setBatchFlushOnMixed(boolean batchFlushOnMixed)

By default when mixing UpdateSql (or CallableSql) with Beans the batch is automatically flushed when you change (between persisting beans and executing UpdateSql or CallableSql).

If you want to execute both WITHOUT having the batch automatically flush you need to call this with batchFlushOnMixed = false.

Note that UpdateSql and CallableSql are ALWAYS executed first (before the beans are executed). This is because the UpdateSql and CallableSql have already been bound to their PreparedStatements. The beans on the other hand have a 2 step process (delayed binding).

setBatchFlushOnQuery

void setBatchFlushOnQuery(boolean batchFlushOnQuery)

By default executing a query will automatically flush any batched statements (persisted beans, executed UpdateSql etc).

Calling this method with batchFlushOnQuery = false means that you can execute a query and the batch will not be automatically flushed.

isBatchFlushOnQuery

boolean isBatchFlushOnQuery()

Return true if the batch (of persisted beans or executed UpdateSql etc) should be flushed prior to executing a query.

The default is for this to be true.

flushBatch

void flushBatch()
         throws javax.persistence.PersistenceException

The batch will be flushing automatically but you can use this to explicitly flush the batch if you like.

Flushing occurs automatically when:

• the batch size is reached
• A query is executed on the same transaction
• UpdateSql or CallableSql are mixed with bean save and delete
• Transaction commit occurs

Throws:

javax.persistence.PersistenceException

getConnection

Connection getConnection()

Return the underlying Connection object.

Useful where a Developer wishes to use the JDBC API directly. Note that the commit() rollback() and end() methods on the Transaction should still be used. Calling these methods on the Connection would be a big no no unless you know what you are doing.

Examples of when a developer may wish to use the connection directly are: Savepoints, advanced CLOB BLOB use and advanced stored procedure calls.

addModification

void addModification(String tableName,
                     boolean inserts,
                     boolean updates,
                     boolean deletes)

Add table modification information to the TransactionEvent.

Use this in conjunction with getConnection() and raw JDBC.

This effectively informs Ebean of the data that has been changed by the transaction and this information is normally automatically handled by Ebean when you save entity beans or use UpdateSql etc.

If you use raw JDBC then you can use this method to inform Ebean for the tables that have been modified. Ebean uses this information to keep its caches in synch and maintain text indexes.

putUserObject

void putUserObject(String name,
                   Object value)

Add an arbitrary user object to the transaction. The objects added have no impact on any internals of ebena and are solely meant as a convenient method push user information to e.g. the TransactionEventListener.

getUserObject

Object getUserObject(String name)

Get an object added with putUserObject(String, Object).