Package io.ebeaninternal.server.transaction

Class JtaTransaction

    • Method Detail

      • setLabel

        public void setLabel​(String label)
        Description copied from interface: Transaction
        Set a label on the transaction.

        This label is used to group transaction execution times for performance metrics reporting.

        Specified by:
        setLabel in interface Transaction

      • getStartNanoTime

        public long getStartNanoTime()
        Description copied from interface: SpiTransaction
        Return the start timestamp for the transaction (JVM side).
        Specified by:
        getStartNanoTime in interface SpiTransaction

      • profileOffset

        public long profileOffset()
        Description copied from interface: SpiTransaction
        Return the offset time from the start of the transaction.
        Specified by:
        profileOffset in interface SpiTransaction

      • isSkipCacheExplicit

        public boolean isSkipCacheExplicit()
        Description copied from interface: SpiTransaction
        Return true if explicitly set to skip cache (ignores skipOnWrite).
        Specified by:
        isSkipCacheExplicit in interface SpiTransaction

      • isSkipCache

        public boolean isSkipCache()
        Description copied from interface: Transaction
        Return true if the L2 cache should be skipped. More accurately if true then find by id and find by natural key queries should NOT automatically use the L2 bean cache.
        Specified by:
        isSkipCache in interface Transaction

      • setSkipCache

        public void setSkipCache​(boolean skipCache)
        Description copied from interface: Transaction
        Set if the L2 cache should be skipped for "find by id" and "find by natural key" queries.

        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();
   }
        Specified by:
        setSkipCache in interface Transaction
        See Also:
        ServerConfig.isSkipCacheAfterWrite()

      • getDocStoreBatchSize

        public int getDocStoreBatchSize()
        Description copied from interface: SpiTransaction
        Return the batch size to us for ElasticSearch Bulk API calls as a result of this transaction.
        Specified by:
        getDocStoreBatchSize in interface SpiTransaction

      • setDocStoreBatchSize

        public void setDocStoreBatchSize​(int docStoreBatchSize)
        Description copied from interface: Transaction
        Set the batch size to use for sending messages to the document store.

        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()

        Specified by:
        setDocStoreBatchSize in interface Transaction

      • getDocStoreMode

        public io.ebean.annotation.DocStoreMode getDocStoreMode()
        Description copied from interface: SpiTransaction
        Return the batchSize specifically set for this transaction or 0.

        Returning 0 implies to use the system wide default batch size.

        Specified by:
        getDocStoreMode in interface SpiTransaction

      • setDocStoreMode

        public void setDocStoreMode​(io.ebean.annotation.DocStoreMode docStoreMode)
        Description copied from interface: Transaction
        Set the behavior for document store updates on this transaction.

        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.

        Specified by:
        setDocStoreMode in interface Transaction

      • registerDeleteBean

        public void registerDeleteBean​(Integer persistingBean)
        Add a bean to the registed list.

        This is to handle bi-directional relationships where both sides Cascade.

        Specified by:
        registerDeleteBean in interface SpiTransaction

      • isRegisteredDeleteBean

        public boolean isRegisteredDeleteBean​(Integer persistingBean)
        Return true if this is a bean that has already been saved/deleted.
        Specified by:
        isRegisteredDeleteBean in interface SpiTransaction

      • unregisterBeans

        public void unregisterBeans()
        Unregister the persisted beans (when persisting at the top level).
        Specified by:
        unregisterBeans in interface SpiTransaction

      • isRegisteredBean

        public boolean isRegisteredBean​(Object bean)
        Return true if this is a bean that has already been saved. This will register the bean if it is not already.
        Specified by:
        isRegisteredBean in interface SpiTransaction

      • isSaveAssocManyIntersection

        public boolean isSaveAssocManyIntersection​(String intersectionTable,
                                           String beanName)
        Return true if the m2m intersection save is allowed from a given bean direction. This is to stop m2m intersection management via both directions of a m2m.
        Specified by:
        isSaveAssocManyIntersection in interface SpiTransaction

      • depth

        public void depth​(int diff)
        Return the depth of the current persist request plus the diff. This has the effect of changing the current depth and returning the new value. Pass diff=0 to return the current depth.

        The depth of 0 is for the initial persist request. It is modified as the cascading of the save or delete traverses to the the associated Ones (-1) and associated Manys (+1).

        The depth is used to help the ordering of batched statements.

        Specified by:
        depth in interface SpiTransaction
        Parameters:
        diff - the amount to add or subtract from the depth.

      • depth

        public int depth()
        Return the current depth.
        Specified by:
        depth in interface SpiTransaction

      • markNotQueryOnly

        public void markNotQueryOnly()
        Description copied from interface: SpiTransaction
        Mark the transaction explicitly as not being query only.
        Specified by:
        markNotQueryOnly in interface SpiTransaction

      • isReadOnly

        public boolean isReadOnly()
        Description copied from interface: Transaction
        Return true if this transaction is read only.
        Specified by:
        isReadOnly in interface Transaction

      • setReadOnly

        public void setReadOnly​(boolean readOnly)
        Description copied from interface: Transaction
        Set whether this transaction should be readOnly.
        Specified by:
        setReadOnly in interface Transaction

      • setUpdateAllLoadedProperties

        public void setUpdateAllLoadedProperties​(boolean updateAllLoadedProperties)
        Description copied from interface: Transaction
        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.

        Specified by:
        setUpdateAllLoadedProperties in interface Transaction

      • isUpdateAllLoadedProperties

        public Boolean isUpdateAllLoadedProperties()
        Description copied from interface: SpiTransaction
        Return true if this transaction has updateAllLoadedProperties set. If null is returned the server default is used (set on ServerConfig).
        Specified by:
        isUpdateAllLoadedProperties in interface SpiTransaction

      • setBatchMode

        public void setBatchMode​(boolean batchMode)
        Description copied from interface: Transaction
        Turn on or off use of JDBC statement batching.

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

        

 try (Transaction transaction = database.beginTransaction()) {

   // turn on JDBC batch
   transaction.setBatchMode(true);

   // tune the batch size
   transaction.setBatchSize(50);

   ...

   transaction.commit();
 }

        getGeneratedKeys

        Often with large batch inserts we want to turn off getGeneratedKeys. We do this via Transaction.setGetGeneratedKeys(boolean). Also note that some JDBC drivers do not support getGeneratedKeys in JDBC batch mode. 

        

 try (Transaction transaction = database.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();
 }

        Flush

        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 Transaction.flush() to explicitly flush the batch and we can use Transaction.setFlushOnQuery(boolean) and Transaction.setFlushOnMixed(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();
 }
        Specified by:
        setBatchMode in interface Transaction

      • isBatchMode

        public boolean isBatchMode()
        Description copied from interface: Transaction
        Return the batch mode at the transaction level.
        Specified by:
        isBatchMode in interface Transaction

      • setBatchOnCascade

        public void setBatchOnCascade​(boolean batchMode)
        Description copied from interface: Transaction
        Set the JDBC batch mode to use for a save() or delete() when cascading to children.

        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.

        Specified by:
        setBatchOnCascade in interface Transaction
        Parameters:
        batchMode - the batch mode to use per save(), insert(), update() or delete()
        See Also:
        ServerConfig.setPersistBatchOnCascade(PersistBatch)

      • isBatchOnCascade

        public boolean isBatchOnCascade()
        Description copied from interface: Transaction
        Return the batch mode at the request level.
        Specified by:
        isBatchOnCascade in interface Transaction

      • setGetGeneratedKeys

        public void setGetGeneratedKeys​(boolean getGeneratedKeys)
        Description copied from interface: Transaction
        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.

        Specified by:
        setGetGeneratedKeys in interface Transaction

      • setFlushOnMixed

        public void setFlushOnMixed​(boolean batchFlushOnMixed)
        Description copied from interface: Transaction
        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).

        Specified by:
        setFlushOnMixed in interface Transaction

      • getBatchSize

        public int getBatchSize()
        Return the batchSize specifically set for this transaction or 0.

        Returning 0 implies to use the system wide default batch size.

        Specified by:
        getBatchSize in interface SpiTransaction
        Specified by:
        getBatchSize in interface Transaction

      • setBatchSize

        public void setBatchSize​(int batchSize)
        Description copied from interface: Transaction
        Specify the number of statements before a batch is flushed automatically.
        Specified by:
        setBatchSize in interface Transaction

      • isFlushOnQuery

        public boolean isFlushOnQuery()
        Description copied from interface: Transaction
        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.

        Specified by:
        isFlushOnQuery in interface Transaction

      • setFlushOnQuery

        public void setFlushOnQuery​(boolean batchFlushOnQuery)
        Description copied from interface: Transaction
        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.

        Specified by:
        setFlushOnQuery in interface Transaction

      • isBatchThisRequest

        public boolean isBatchThisRequest()
        Return true if this request should be batched. Returning false means that this request should be executed immediately.
        Specified by:
        isBatchThisRequest in interface SpiTransaction

      • flushBatchOnCollection

        public void flushBatchOnCollection()
        Description copied from interface: SpiTransaction
        Flush batch if we escalated batch mode on saving or deleting a collection.
        Specified by:
        flushBatchOnCollection in interface SpiTransaction

      • flushBatchOnRollback

        public void flushBatchOnRollback()
        Description copied from interface: SpiTransaction
        If batch was on then effectively clear the batch such that we can handle exceptions and continue.
        Specified by:
        flushBatchOnRollback in interface SpiTransaction

      • setBatchControl

        public void setBatchControl​(BatchControl batchControl)
        Set the BatchControl to the transaction. This is done once per transaction on the first persist request.
        Specified by:
        setBatchControl in interface SpiTransaction

      • flush

        public void flush()
        Flush any queued persist requests.

        This is general will result in a number of batched PreparedStatements executing.

        Specified by:
        flush in interface Transaction

      • flushBatch

        public void flushBatch()
        Description copied from interface: Transaction
        This is a synonym for flush() and will be deprecated.

        flush() is preferred as it matches the JPA flush() method.

        Specified by:
        flushBatch in interface Transaction

      • setPersistenceContext

        public void setPersistenceContext​(PersistenceContext context)
        Set the persistence context to this transaction.

        This could be considered similar to EJB3 Extended PersistanceContext. In that you get the PersistanceContext from a transaction, hold onto it, and then set it back later to a second transaction.

        Specified by:
        setPersistenceContext in interface SpiTransaction

      • isExplicit

        public boolean isExplicit()
        Return true if this was an explicitly created transaction.
        Specified by:
        isExplicit in interface SpiTransaction

      • isLogSql

        public boolean isLogSql()
        Description copied from interface: SpiTransaction
        Return true if generated SQL and Bind values should be logged to the transaction log.
        Specified by:
        isLogSql in interface SpiTransaction

      • isLogSummary

        public boolean isLogSummary()
        Description copied from interface: SpiTransaction
        Return true if summary level events should be logged to the transaction log.
        Specified by:
        isLogSummary in interface SpiTransaction

      • commitAndContinue

        public void commitAndContinue()
        Perform a commit, fire callbacks and notify l2 cache etc.

        This leaves the transaction active and expects another commit to occur later (which closes the underlying connection etc).

        Specified by:
        commitAndContinue in interface Transaction

      • isRollbackOnly

        public boolean isRollbackOnly()
        Return true if the transaction is marked as rollback only.
        Specified by:
        isRollbackOnly in interface Transaction

      • setRollbackOnly

        public void setRollbackOnly()
        Mark the transaction as rollback only.
        Specified by:
        setRollbackOnly in interface Transaction

      • isNestedUseSavepoint

        public boolean isNestedUseSavepoint()
        Description copied from interface: SpiTransaction
        Return true when nested transactions should create Savepoints.
        Specified by:
        isNestedUseSavepoint in interface SpiTransaction

      • setNestedUseSavepoint

        public void setNestedUseSavepoint()
        Description copied from interface: Transaction
        Set when we want nested transactions to use Savepoint's.

        This means that for a nested transaction:

        • begin transaction maps to creating a savepoint
        • commit transaction maps to releasing a savepoint
        • rollback transaction maps to rollback a savepoint
        Specified by:
        setNestedUseSavepoint in interface Transaction

      • end

        public void end()
         throws javax.persistence.PersistenceException
        If the transaction is active then perform rollback.
        Specified by:
        end in interface Transaction
        Throws:
        javax.persistence.PersistenceException

      • isActive

        public boolean isActive()
        Return true if the transaction is active.
        Specified by:
        isActive in interface Transaction

      • setPersistCascade

        public void setPersistCascade​(boolean persistCascade)
        Description copied from interface: Transaction
        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.

        Specified by:
        setPersistCascade in interface Transaction

      • addModification

        public void addModification​(String tableName,
                            boolean inserts,
                            boolean updates,
                            boolean deletes)
        Description copied from interface: Transaction
        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.

        Specified by:
        addModification in interface Transaction

      • putUserObject

        public void putUserObject​(String name,
                          Object value)
        Description copied from interface: Transaction
        Add an arbitrary user object to the transaction. The objects added have no impact on any internals of ebean and are solely meant as a convenient method push user information (although somewhat replaced by TransactionCallback).
        Specified by:
        putUserObject in interface Transaction

      • close

        public void close()
        Alias for end(), which enables this class to be used in try-with-resources.
        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Transaction