oracle.jbo
Interface Transaction

All Known Subinterfaces:

DBTransaction

public interface Transaction

Provides the base methods for defining database transactions.

Since:

JDeveloper 3.0

Field Summary

static int	LOCK_NONE Indicates that the row locking mode is Manual.
static int	LOCK_OPTIMISTIC Indicates that the row locking mode is Automatic and Optimistic.
static int	LOCK_PESSIMISTIC Indicates that the row locking mode is Automatic and Pessimistic.

Method Summary

void	applyChangeSet(int id) Applies the changes committed by another transaction in order to synchronize caches between root Application Module instances.
void	clearEntityCache(java.lang.String entityName) Clears the cache of the specified Entity Object.
void	commit() Commits all changes in this transaction to the database, making them visible to other users and transactions.
int	commitAndSnap() Commits the transaction and writes updated EntityImpls to the persistent store.
void	connect(java.lang.String url) Attempts to establish a connection to a database identified by a URL.
void	connect(java.lang.String url, java.util.Properties info) Attempts to establish a connection to a database identified by a URL.
void	connect(java.lang.String url, java.lang.String user, java.lang.String password) Attempts to establish a connection to a database identified by a URL.
java.lang.Object	createRef(java.lang.String structName, byte[] data) Internal: Applications should not use this method.
void	disconnect() Closes the JDBC connection object and removes this transaction from the root application module.
java.lang.String	dumpQueryResult(java.lang.String query, java.lang.String dumpClassName, java.lang.String[] data) Writes the result of the query to a (potentially very long) string.
int	executeCommand(java.lang.String command) Executes a SQL command using a JDBC Statement under the current transaction.
int	getLockingMode() Returns the preferred locking mode for this Transaction.
boolean	isClearCacheOnCommit() Indicates whether all Entity Object caches will be cleared after the transaction is committed.
boolean	isClearCacheOnRollback() Indicates whether all Entity Object caches will be cleared after the transaction is rolled back.
boolean	isConnected() Checks if the transaction is connected to the database.
boolean	isDirty() Checks if any data within this Application Module has been modified but not yet committed.
void	postChanges() Synchronizes the changes in the middle-tier transaction-cache with the database.
void	reconnect(boolean force) Reconnect the application module to the database, if necessary, using previously supplied database credentials.
void	removeChangeSet(int id) Removes the change set that defines the changes to EntityImpls within a transaction.
void	rollback() Discards all modifications made in this transaction.
void	setClearCacheOnCommit(boolean val) Indicates whether all Entity Object caches will be cleared after the transaction is committed.
void	setClearCacheOnRollback(boolean val) Indicates whether all Entity Object caches will be cleared after the transaction is rolled back.
void	setLockingMode(int mode) Sets the preferred locking mode for this Transaction.
void	validate() Starts the validation cycle and validates all subscribers in the ValidationListener list.

Field Detail

LOCK_NONE

public static final int LOCK_NONE

Indicates that the row locking mode is Manual.

LOCK_PESSIMISTIC

public static final int LOCK_PESSIMISTIC

Indicates that the row locking mode is Automatic and Pessimistic.

LOCK_OPTIMISTIC

public static final int LOCK_OPTIMISTIC

Indicates that the row locking mode is Automatic and Optimistic.

Method Detail

connect

public void connect(java.lang.String url)

Attempts to establish a connection to a database identified by a URL.

The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers.

Call isConnected to see if the connection was successful.

Parameters:

url - a database url of the form jdbc:subprotocol:subname.

connect

public void connect(java.lang.String url,
                    java.util.Properties info)

Attempts to establish a connection to a database identified by a URL.

The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers.

Call isConnected to see if the connection was successful.

Parameters:

url - a database url of the form jdbc:subprotocol:subname.

info - a list of arbitrary string tag/value pairs to be used as connection arguments. Normally, at least "user" and "password" properties should be included.

connect

public void connect(java.lang.String url,
                    java.lang.String user,
                    java.lang.String password)

Attempts to establish a connection to a database identified by a URL.

The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers.

Call isConnected to see if the connection was successful.

Parameters:

url - a database url of the form jdbc:subprotocol:subname.

user - the database user on whose behalf the connection is being made.

password - the user's password.

reconnect

public void reconnect(boolean force)

Reconnect the application module to the database, if necessary, using previously supplied database credentials. If the parameter is true, then a database disconnect and reconnect is performed, whatever the current connection state. If false, the connect is only performed if the connection has disappeared.

Parameters:

force - force a reconnect, should usually be false.

disconnect

public void disconnect()

Closes the JDBC connection object and removes this transaction from the root application module.

In the middle-tier, you can also use the disconnect method on the DBTransactionImpl interface.

isConnected

public boolean isConnected()

Checks if the transaction is connected to the database. In a three-tier scenario, clients can call this method to check if the middle tier is connected to the database.

Returns:

true if connected; false if disconnected.

setLockingMode

public void setLockingMode(int mode)

Sets the preferred locking mode for this Transaction. The possible values are:

• LOCK_NONE - Row locking mode is Manual.
• LOCK_PESSIMISTIC (default) - Row locking mode is Automatic and Pessimistic.
• LOCK_OPTIMISTIC - Row locking mode is Automatic and Optimistic.

Changing the locking mode affects only subsequent locks. Current locks are not affected.

Parameters:

mode - one of LOCK_PESSIMISTIC, LOCK_OPTIMISTIC or LOCK_NONE.

getLockingMode

public int getLockingMode()

Returns the preferred locking mode for this Transaction. For example:

 am.getTransaction().getLockingMode();
 

The possible return values are:

• LOCK_NONE Row locking mode is Manual.
• LOCK_PESSIMISTIC (default) - Row locking mode is Automatic and Pessimistic.
• LOCK_OPTIMISTIC - Row locking mode is Automatic and Optimistic.

If not set by setLockingMode, the locking mode defaults to LOCK_PESSIMISTIC.

Returns:

an integer representing the preferred locking mode. The values can be LOCK_NONE, LOCK_PESSIMISTIC (default), or LOCK_OPTIMISTIC.

setClearCacheOnCommit

public void setClearCacheOnCommit(boolean val)

Indicates whether all Entity Object caches will be cleared after the transaction is committed. For more information on this topic, see isClearCacheOnCommit.

Parameters:

val - true indicates that the Entity Object caches will be cleared on commit, and will be refreshed with new data from the database.

See Also:

#isClearCacheOnCommit(boolean val)

isClearCacheOnCommit

public boolean isClearCacheOnCommit()

Indicates whether all Entity Object caches will be cleared after the transaction is committed. If the Entity caches are cleared, they will be refreshed with new data from the database. Clearing the Entity cache will ensure that all changes from the database will be captured; relying on the fault-in mechanism or RowSet.executeQuery might miss some of the changes.

The value of the Application Module's isClearCacheOnCommit() flag will be used if the client has not set this flag in the Transaction. At the end of transaction, the transaction checks the value of its isClearCacheOnCommit() flag and either clears the Entity Object caches or not. However, if the client never called setClearCacheOnCommit on this transaction, the framework will use the value for the root Application Module's definition object.

In contrast, if the client called setClearCacheOnCommit on the Transaction, then the value of the root Application Module Def's isClearCacheOnCommit is not used.

Note that clearing the Entity Object caches has performance ramifications: repopulating the caches is expensive in terms of time and processing effort.

For middle-tier applications, you can use isClearCacheOnCommit and setClearCacheOnCommit in the DBTransactionImpl class.

Returns:

true indicates that the Entity Object caches will be cleared on commit, and will be refreshed with new data from the database.

See Also:

RowSet.executeQuery(), setClearCacheOnCommit(boolean val), DBTransactionImpl.isClearCacheOnCommit(), DBTransactionImpl.setClearCacheOnCommit(boolean val)

setClearCacheOnRollback

public void setClearCacheOnRollback(boolean val)

Indicates whether all Entity Object caches will be cleared after the transaction is rolled back. For more information on this topic, see isClearCacheOnRollback

Parameters:

val - true indicates that the Entity Object caches will be cleared on rollback, and will be refreshed with new data from the database.

See Also:

isClearCacheOnRollback()

isClearCacheOnRollback

public boolean isClearCacheOnRollback()

Indicates whether all Entity Object caches will be cleared after the transaction is rolled back. If the Entity caches are cleared, they will be refreshed with new data from the database. Clearing the Entity caches will ensure that all changes from the database will be captured; relying on the fault-in mechanism or RowSet.executeQuery might miss some of the changes.

The value of the Application Module's isClearCacheOnRollback() flag will be used if the client has not set this flag in the Transaction. At the end of transaction, the transaction checks the value of its isClearCacheOnRollback flag and either clears the Entity Object caches or not. However, if the client never called setClearCacheOnRollback on this transaction, the framework will use the value for the root Application Module's definition object.

In contrast, if the client called oracle.jbo.Transaction.setClearCacheOnRollback on the Transaction, then the value of the root Application Module Def's isClearCacheOnRollback is not used.

For middle-tier applications, you can use isClearCacheOnCommit and setClearCacheOnCommit in the DBTransactionImpl class.

Note that clearing the Entity Object caches has performance ramifications: repopulating the caches is expensive in terms of time and processing effort.

Returns:

true indicates that the Entity Object caches will be cleared on rollback, and will be refreshed with new data from the database.

See Also:

RowSet.executeQuery(), setClearCacheOnRollback(boolean val), DBTransactionImpl.setClearCacheOnRollback(boolean val), DBTransactionImpl.isClearCacheOnRollback()

validate

public void validate()

Starts the validation cycle and validates all subscribers in the ValidationListener list. Typically all top-level entities which were invalidated through the framework will be in this list. Listeners are removed as they are validated.

The advantage of calling validate() is that the data stays in the middle tier. Data is not posted to the database, thus avoiding the possible firing of database triggers or constraints.

postChanges

public void postChanges()

Synchronizes the changes in the middle-tier transaction-cache with the database.

This method bypasses the validation cycle and can allow invalid data to be posted to the database. As a side effect of this method, database triggers or other constraints might be fired as a result of posting data. However, invalid changes cannot be committed, as the commit() method validates all changes before committing them.

Typically, applications should call this method if they must execute SQL operations or queries with the current cached-state of data, before validating the changes.

See Also:

commit()

isDirty

public boolean isDirty()

Checks if any data within this Application Module has been modified but not yet committed. This method is typically called before an attempt is made to post the data.

For example, this method can be called when the user at the client attempts to close an application. If there is unsaved data, this method can return true. In response, the client can prompt the user to save before closing the application.

Returns:

true if the local data and the database differ.

commit

public void commit()

Commits all changes in this transaction to the database, making them visible to other users and transactions. This method is called on the Application Module's transaction. For example:

     appMod.getTransaction().commit();
 

When the commit process begins multiple attempts are made to validate all objects in the list of validation listeners, depending on the setting of the validation threshold. After each attempt, top-level entities that are still invalid will remain in the list. If any remain after the last attempt, a failure exception is thrown.

Each listed TransactionPostListener is notified to post any changes to the database using the postChanges method. Non-transient listeners are notified first, followed by transient listeners. The post phase is repeated, the number of repetitions depending on the setting of the validation threshold. If any invalid objects remain after the last repetition, a failure exception is thrown.

Following validation, no further changes to data should be made until the commit operation is completed.

Finally, beforeCommit events are posted to the listeners, the data is committed, afterCommit events are posted, and transient listeners are deleted from the transaction. For both beforeCommit and afterCommit events, non-transient listeners preceed transient listeners.

Note, if your Application Module is an EJB session bean, a new transaction is started for you automatically after calling commit. You do not have to explicitly start a new transaction.

See Also:

TransactionListener.beforeCommit(TransactionEvent), TransactionListener.afterCommit(TransactionEvent), DBTransaction, postChanges()

commitAndSnap

public int commitAndSnap()

Commits the transaction and writes updated EntityImpls to the persistent store.

This method (along with applyChangeSet and removeChangeSet is used to synchronize the cache between root Application Module instances in an Application Module pool.

commitAndSnap commits the transaction, but during the commit process, writes out "changed" EntityImpls to the persistent store. These changes are stored as a "change set". The change set can then be applied to other transactions (that is, to the Entity caches of other root Application Modules).

The integer value returned by this method identifies the change set that is stored in persistent store.

To apply the changes to another transaction (or Application Module cache), call applyChangeSet(int) where int is the integer value returned by commitAndSnap that represents the change set.

Returns:

an integer representing an EntityImpl change set in persistent store.

See Also:

applyChangeSet(int), removeChangeSet(int)

applyChangeSet

public void applyChangeSet(int id)

Applies the changes committed by another transaction in order to synchronize caches between root Application Module instances.

This method (along with commitAndSnap and removeChangeSet is used to synchronize the cache between root Application Module instances in an Application Module pool.

Call applyChangeSet to apply changes commited by another transaction. The integer id parameter (returned by commitAndSnap) identifies the change set to be found in the persistent store.

After this call, this transaction's cache is synchronized with the changes from the change set.

Parameters:

id - an integer representing the change set to apply to the transaction.

See Also:

commitAndSnap(), removeChangeSet(int)

removeChangeSet

public void removeChangeSet(int id)

Removes the change set that defines the changes to EntityImpls within a transaction.

This method (along with commitAndSnap and applyChangeSet is used to synchronize the cache between root Application Module instances in an Application Module pool.

Parameters:

id - an integer representing the change set to remove from the persistent store.

See Also:

commitAndSnap(), applyChangeSet(int)

rollback

public void rollback()

Discards all modifications made in this transaction. This method is called on the Application Module's transaction. For example:

     appMod.getTransaction().rollback();
 

When this method is invoked, beforeRollback events are posted to the listeners, the changes are discarded, afterRollback events are posted, and transient listeners are deleted from the transaction. For both events, non-transient listeners preceed transient listeners.

In the following example, a method named updateAttr has been implemented to update a row of a View Object vo with the value newAttrVal. If updateAttr succeeds (returns true), the code commits the transaction; otherwise, it rolls the transaction back:

 // Assume that appMod has been declared and initialized elsewhere.
   try {  if (updateAttr(vo, newAttrVal)) {
       // Commit changes to the database, making
       // updated data available to other Application Modules.
       appMod.getTransaction().commit();
       System.out.println("\n Transaction committed. \n");
     }
   else {
       appMod.getTransaction().rollback();
       System.out.println("\n Transaction rolled back. \n");
    }
 } catch (Exception e) {
       e.printStackTrace();
 }
 

Note, if your Application Module is an EJB session bean, a new transaction is started for you automatically after calling rollback. You do not have to explicitly start a new transaction.

See Also:

DBTransaction, TransactionListener.afterRollback(TransactionEvent), TransactionListener.beforeRollback(TransactionEvent)

clearEntityCache

public void clearEntityCache(java.lang.String entityName)

Clears the cache of the specified Entity Object. A value of null clears the caches of all Entities. If a View Object uses the Entity Object, the View Object's cache will be cleared as well.

Parameters:

entityName - the name of the entity whose cache is to be cleared. If null, caches for all entities are cleared.

executeCommand

public int executeCommand(java.lang.String command)

Executes a SQL command using a JDBC Statement under the current transaction. Applications should use this method to execute application-specific JDBC statements.

This method provides a way of bypassing the framework to query the database directly. Internally, the method passes the specified SQL command to a statement on the JDBC connection and executes it.

The following code example uses executeCommand. The SQL string is designed to update the EMP table. This example passes the string to executeCommand, then prints a message to report how many rows were actually updated.

 public static void demoUpdateColumn(ApplicationModule appMod) {
     String sqlStr = "UPDATE EMP " +
                     "SET MGR=7007 " +
                     "WHERE MGR=7698 ";

     int n = appMod.getTransaction().executeCommand(sqlStr);
     System.out.println("Updated " + n + " rows.");
   }
 

Be careful when using executeCommand, because it will execute any valid SQL statement. For example, you could perform an operation like the following DDL command:

 appMod.getTransaction().executeCommand("DROP TABLE MYTEMPTABLE");
 

A pending database transaction could be committed inadvertently due to the implicit commit performed by DDL operations, as well as having any row locks released.

Parameters:

command - a valid SQL statement.

Returns:

the number of rows affected.

Throws:

InvalidParamException - if command is empty.

SQLStmtException - if command fails.

dumpQueryResult

public java.lang.String dumpQueryResult(java.lang.String query,
                                        java.lang.String dumpClassName,
                                        java.lang.String[] data)

Writes the result of the query to a (potentially very long) string. It takes three parameters: the first is the SQL query statement. The second is the class that dumps the result to a string. This class must implement the oracle.jbo.server.QueryDump interface. The implementation of this class decides what to do with the third, data parameter (which can be null). This is a utility method for testing and debugging queries and applications.

The following code example uses dumpQueryResult.

 public static void demoSimpleFetch(ApplicationModule appMod) {
       // Define and execute a simple SQL statement.
       String sqlStr = "SELECT Emp.ename FROM EMP Emp ";
       // dumpQueryResult is a utility method for testing queries.
       String result = appMod.getTransaction().dumpQueryResult(sqlStr,
                                    "oracle.jbo.server.QueryDumpTab",
                                      null);

 System.out.println(sqlStr);
 System.out.println(result);  }
 

Parameters:

query - the SQL query statement.

dumpClassName - the class that dumps the result to a string.

data - an array of data items.

createRef

public java.lang.Object createRef(java.lang.String structName,
                                  byte[] data)

Internal: Applications should not use this method.