public interface Transaction extends AutoCloseable
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.
|
Modifier and Type | Method and Description |
---|---|
void |
addModification(String tableName,
boolean inserts,
boolean updates,
boolean deletes)
Add table modification information to the TransactionEvent.
|
void |
close()
Synonym for end() to support AutoClosable.
|
void |
commit()
Commit the transaction.
|
void |
commitAndContinue()
Commits the transaction at this point with the expectation that another
commit (or rollback or end) will occur later to complete the transaction.
|
static Transaction |
current()
Return the current transaction (of the default database) or null if there is
no current transaction in scope.
|
void |
end()
If the transaction is active then perform rollback.
|
void |
flush()
The batch will be flushing automatically but you can use this to explicitly
flush the batch if you like.
|
void |
flushBatch()
This is a synonym for flush() and will be deprecated.
|
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 |
isBatchMode()
Return the batch mode at the transaction level.
|
boolean |
isBatchOnCascade()
Return the batch mode at the request level.
|
boolean |
isReadOnly()
Return true if this transaction is read only.
|
boolean |
isRollbackOnly()
Return true if the transaction is marked as rollback only.
|
boolean |
isSkipCache()
Return true if the L2 cache should be skipped.
|
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 |
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 use of JDBC statement batching.
|
void |
setBatchOnCascade(boolean batchMode)
Set the JDBC batch mode to use for a save() or delete() when cascading to children.
|
void |
setBatchSize(int batchSize)
Specify the number of statements before a batch is flushed automatically.
|
void |
setDocStoreBatchSize(int batchSize)
Set the batch size to use for sending messages to the document store.
|
void |
setDocStoreMode(io.ebean.annotation.DocStoreMode mode)
Set the behavior for document store updates on this transaction.
|
void |
setLabel(String label)
Set a label on the transaction.
|
void |
setNestedUseSavepoint()
Set when we want nested transactions to use Savepoint's.
|
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 |
setRollbackOnly()
Mark the transaction for rollback only.
|
void |
setSkipCache(boolean skipCache)
Set if the L2 cache should be skipped for "find by id" and "find by natural key" queries.
|
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).
|
static final int READ_COMMITTED
static final int READ_UNCOMMITTED
static final int REPEATABLE_READ
static final int SERIALIZABLE
static Transaction current()
This is the same as DB.currentTransaction()
This returns the current transaction for the 'default server'. If you are using
multiple EbeanServer's then use DB.currentTransaction()
.
void register(TransactionCallback callback)
void setLabel(String label)
This label is used to group transaction execution times for performance metrics reporting.
boolean isReadOnly()
void setReadOnly(boolean readOnly)
void commitAndContinue()
This is similar to commit() but leaves the transaction "Active".
void commit()
This performs commit and completes the transaction closing underlying resources and marking the transaction as "In active".
void rollback() throws javax.persistence.PersistenceException
This performs rollback, closes underlying resources and marks the transaction as "In active".
javax.persistence.PersistenceException
void rollback(Throwable e) throws javax.persistence.PersistenceException
If you are using transaction logging this will log the throwable in the transaction logs.
javax.persistence.PersistenceException
void setNestedUseSavepoint()
This means that for a nested transaction:
void setRollbackOnly()
boolean isRollbackOnly()
void end()
void close()
close
in interface AutoCloseable
boolean isActive()
void setDocStoreMode(io.ebean.annotation.DocStoreMode mode)
For example, set the mode to DocStoreEvent.IGNORE for this transaction and then any changes via this transaction are not sent to the doc store. This would be used when doing large bulk inserts into the database and we want to control how that is sent to the document store.
void setDocStoreBatchSize(int batchSize)
You might set this if you know the changes in this transaction result in especially large or especially small payloads and want to adjust the batch size to match.
Setting this overrides the default of DocStoreConfig.getBulkBatchSize()
void setPersistCascade(boolean persistCascade)
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.
void setUpdateAllLoadedProperties(boolean updateAllLoadedProperties)
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.
void setSkipCache(boolean skipCache)
By default ServerConfig.isSkipCacheAfterWrite()
is true and that means that for
"find by id" and "find by natural key" queries which normally hit L2 bean cache automatically
- will not do so after a persist/write on the transaction.
This method provides explicit control over whether "find by id" and "find by natural key" will skip the L2 bean cache or not (regardless of whether the transaction is considered "read only").
Refer to ServerConfig.setSkipCacheAfterWrite(boolean)
for configuring the default behavior
for using the L2 bean cache in transactions spanning multiple query/persist requests.
// assume Customer has L2 bean caching enabled ...
try (Transaction transaction = DB.beginTransaction()) {
// this uses L2 bean cache as the transaction
// ... is considered "query only" at this point
Customer.find.byId(42);
// transaction no longer "query only" once
// ... a bean has been saved etc
someBean.save();
// will NOT use L2 bean cache as the transaction
// ... is no longer considered "query only"
Customer.find.byId(55);
// explicit control - please use L2 bean cache
transaction.setSkipCache(false);
Customer.find.byId(77); // hit the l2 bean cache
// explicit control - please don't use L2 bean cache
transaction.setSkipCache(true);
Customer.find.byId(99); // skips l2 bean cache
transaction.commit();
}
ServerConfig.isSkipCacheAfterWrite()
boolean isSkipCache()
void setBatchMode(boolean useBatch)
Calls to save(), delete(), insert() and execute() all support batch processing. This includes normal beans, CallableSql and UpdateSql.
try (Transaction transaction = server.beginTransaction()) {
// turn on JDBC batch
transaction.setBatchMode(true);
// tune the batch size
transaction.setBatchSize(50);
...
transaction.commit();
}
Often with large batch inserts we want to turn off getGeneratedKeys. We do
this via setBatchGetGeneratedKeys(boolean)
.
Also note that some JDBC drivers do not support getGeneratedKeys in JDBC batch mode.
try (Transaction transaction = server.beginTransaction()) {
transaction.setBatchMode(true);
transaction.setBatchSize(100);
// insert but don't bother getting back the generated keys
transaction.setBatchGetGeneratedKeys(false);
// perform lots of inserts ...
...
transaction.commit();
}
The batch is automatically flushed when it hits the batch size and also when we execute queries or when we mix UpdateSql and CallableSql with save and delete of beans.
We use flush()
to explicitly flush the batch and we can use
setBatchFlushOnQuery(boolean)
and setBatchFlushOnMixed(boolean)
to control the automatic flushing behaviour.
Example: batch processing of CallableSql executing every 10 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);
try (Transaction txn = DB.beginTransaction()) {
txn.setBatchMode(true);
txn.setBatchSize(10);
for (int i = 0; i < da.length;) {
cs.setParameter(1, da[i]);
DB.execute(cs);
}
// Note: commit implicitly flushes
txn.commit();
}
boolean isBatchMode()
void setBatchOnCascade(boolean batchMode)
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.
This is effectively already turned on for all platforms apart from older Sql Server.
batchMode
- the batch mode to use per save(), insert(), update() or delete()ServerConfig.setPersistBatchOnCascade(PersistBatch)
boolean isBatchOnCascade()
void setBatchSize(int batchSize)
int getBatchSize()
void setBatchGetGeneratedKeys(boolean 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.
void setBatchFlushOnMixed(boolean batchFlushOnMixed)
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).
void setBatchFlushOnQuery(boolean batchFlushOnQuery)
Calling this method with batchFlushOnQuery = false means that you can execute a query and the batch will not be automatically flushed.
boolean isBatchFlushOnQuery()
The default is for this to be true.
void flush() throws javax.persistence.PersistenceException
Flushing occurs automatically when:
javax.persistence.PersistenceException
void flushBatch() throws javax.persistence.PersistenceException
flush() is preferred as it matches the JPA flush() method.
javax.persistence.PersistenceException
Connection getConnection()
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.
void addModification(String tableName, boolean inserts, boolean updates, boolean deletes)
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.
void putUserObject(String name, Object value)
Object getUserObject(String name)
putUserObject(String, Object)
.Copyright © 2019. All rights reserved.