oracle.jbo.server
Class DBTransactionImpl

java.lang.Object
  oracle.jbo.server.DBTransactionImpl

All Implemented Interfaces:

PCollManagerHelper, JboTransAttrValidationManager, JboTransValidationManager, DBTransaction, ValidationManager, Transaction

Direct Known Subclasses:

DBTransactionImpl2

public class DBTransactionImpl
extends java.lang.Object
implements DBTransaction, PCollManagerHelper, JboTransValidationManager, JboTransAttrValidationManager

Field Summary

static java.lang.Class	CLASS_INSTANCE
static int	MAX_CURSORS_UNINITIALIZED
protected ConnectionDetails	mConnectionMetaData
protected int	mDMLOperationTimeOut
protected List	mLongRunningDMLOperationHandles
static int	POST_ABORT_ON_FIRST_EXCEPTION
static int	POST_ALL_NO_RESET_ON_EXCEPTION
static int	POST_ALL_RESET_ON_EXCEPTION

Fields inherited from interface oracle.jbo.server.DBTransaction

DEFAULT

Fields inherited from interface oracle.jbo.Transaction

DML_OPERATION_TIMEOUT_WAIT_FOREVER, LOCK_NONE, LOCK_OPTIMISTIC, LOCK_OPTUPDATE, LOCK_PESSIMISTIC

Constructor Summary

DBTransactionImpl()

Method Summary

void	addLongRunningDMLOperationHandle(LongRunningStatementHandle handle)
void	addToValidationListeners(ValidationListener entity) Adds an entity validation listener.
void	addTransactionListener(TransactionListener listener) Add a TransactionListener.
void	addTransactionListenerNoCheck(TransactionListener listener) Internal: Applications should not call this method.
void	addTransactionPostListener(TransactionPostListener listener) Adds a listener to the transaction's list of post-phase event subscribers.
void	addTransactionPostListenerNoCheck(TransactionPostListener listener) Internal: Applications should not use this method.
void	addTransactionStateListener(TransactionStateListener target) Add this TransactionListener to the list and notify all such listeners whenever commit and rollback occurs in this transaction.
void	addViewClearCacheListener(ViewClearCacheListener target)
void	applyChangeSet(int id) Applies the changes committed by another transaction in order to synchronize caches between root Application Module instances.
boolean	cancelDMLOperations() Cancels the currently running Entity Object DML operations.
protected void	checkConnected()
void	clearEntityCache(java.lang.String entityName) Clears the cache of the specified Entity Object.
void	closeTransaction() Internal: Applications should not use this method.
void	commit() Commits all changes in this transaction to the database, making them visible to other users and transactions.
int	commitAndSaveChangeSet() Commits the transaction and writes updated EntityImpls to the persistent store.
void	connect(ConnectionDetails metaData) Connect to the datasource identified by the connection metadata
void	connect(java.lang.String url) Attempts to establish a connection to a database identified by a URL.
void	connect(java.lang.String url, 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.
void	connectToDataSource(java.util.Hashtable initialContextEnv, java.lang.String dataSourceName, boolean isXABased) Looks up a datasource from a jndi tree and acquires the jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection(String user, String passwd) method.
void	connectToDataSource(java.util.Hashtable initialContextEnv, java.lang.String dataSourceName, java.lang.String user, java.lang.String password, boolean isXABased) Looks up a datasource from a jndi tree and acquires the jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection(String user, String passwd) method.
void	connectToDataSource(java.lang.String nsUrl, java.lang.String nsUser, java.lang.String nsPasswd, java.lang.String dataSourceName) Looks up a datasource from Oracle 8i namespace using the jdbc_access protocol and acquires the default jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection() method.
void	connectToDataSource(java.lang.String nsUrl, java.lang.String nsUser, java.lang.String nsPasswd, java.lang.String dataSourceName, java.lang.String user, java.lang.String password) Looks up a datasource from Oracle 8i namespace using the jdbc_access protocol and acquires the jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection(String user, String password) method.
CallableStatement	createCallableStatement(java.lang.String str, int noRowsPrefetch)
PreparedStatement	createPreparedStatement(java.lang.String sql) Create a PreparedStatement on the underlying database connection
PreparedStatement	createPreparedStatement(java.lang.String str, int noRowsPrefetch) Creates a JDBC PreparedStatement instance.
java.lang.Object	createRef(java.lang.String structName, byte[] data) Internal: Applications should not use this method.
Statement	createStatement() Create a new, empty Statement that can be used to issue SQL queries
Statement	createStatement(int noRowsPrefetch) Creates a JDBC Statement instance.
ViewObject	createViewObjectFromQueryClauses(java.lang.String eoName, java.lang.String selectClause, java.lang.String fromClause, java.lang.String whereClause, java.lang.String orderByClause) Creates an updatable query definition.
void	disconnect() Closes the JDBC connection object and removes this transaction from the root application module.
void	disconnect(boolean retainState) Closes the JDBC connection object.
protected void	doCommit() Called by the commit method to issue the commit call.
protected void	doRollback() Called by the rollback method to issue the rollback call.
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.
EntityCache	findEntityCache(EntityDefImpl source) Finds a Cache table for the entity.
int	getBatchPostExceptionThreshold() In case of batch mode post operation, try to post the batched set of entities for each entity type and post operation (Insert/Update/Delete) for this many number of exceptions.
ConnectionDetails	getConnectionMetadata() Returns a metdata structure that describes the transaction's JDBC connection.
int	getDMLOperationTimeOut() Returns the current Entity Object DML operation time out value.
EntityCache	getEntityCache(EntityDefImpl source)
protected EntityCache	getEntityCache(java.lang.String fullName)
protected Connection	getJdbcConnection() Returns the JDBC connection for this transaction.
int	getLockingMode() Returns the preferred locking mode for this Transaction.
Connection	getPersistManagerConnection()
int	getPostChangesFlag() Internal: Applications should not use this method.
int	getPostThreshold()
ApplicationModule	getRootApplicationModule() Returns the root appmodule that owns this transaction.
Session	getSession() Gets the session information.
SQLBuilder	getSQLBuilder() Get the SQLBuilder class which is used to create SQL statements compatible with the underlying database connection
java.lang.Object	getSyncLock()
TransactionHandler	getTransactionHandler() Internal: Applications should not use this method.
protected int	getTransactionState()
ArrayList	getTransAttrValidationList()
JboTransAttrValidationManager	getTransAttrValidationManager()
java.util.Hashtable	getTransAttrValidations()
ArrayList	getTransValidationList()
JboTransValidationManager	getTransValidationManager()
java.util.Hashtable	getTransValidations()
protected ApplicationModuleImpl	getTxnApplicationModuleImpl() Gets the root Application Module to which this transaction belongs.
int	getValidationThreshold() Gets the threshold value for the commit-cycle's validation phase.
protected boolean	hasRollbackSavePoint()
boolean	isBundledExceptionMode()
boolean	isClearCacheOnCommit() Returns the flag indicating whether all Entity Object caches will be cleared after the transaction is committed.
boolean	isClearCacheOnRollback() Returns the flag indicating whether all Entity Object caches will be cleared after the transaction is rolled back.
boolean	isConnected() Is this transaction object connected to the underlying database?
boolean	isConnected(boolean pingDatabase)
boolean	isDirty() This method is typically called before an attempt is made to post the data.
boolean	isForceDeferValidation()
boolean	isTrackNewAndModifiedRowsOnly() Deprecated. since 9.0.5.1
EntityCache	lookupEntityCache(EntityDefImpl source)
void	postChanges() Synchronizes the changes in the middle-tier transaction-cache with the database.
protected void	postChanges(TransactionEvent te) Internal: Applications should not use this method.
void	putTransAttrValEntry(JboTransValidatorInterface validator, JboValidatorContext valCtx)
void	putTransValEntry(JboTransValidatorInterface validator, JboValidatorContext valCtx)
void	reconnect() Reconnect the ApplicationModule to the database, using previously supplied database credentials.
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	removeLongRunningDMLOperationHandle(LongRunningStatementHandle handle)
void	removeTransactionListener(TransactionListener listener) Remove a TransactionListener so it is no longer notified of transaction events
void	removeTransactionPostListener(TransactionPostListener listener) Removes a subscriber from the transaction's post-events list.
void	removeTransactionStateListener(TransactionStateListener target)
void	removeViewClearCacheListener(ViewClearCacheListener target)
void	rollback() Discards all modifications made in this transaction.
void	setBatchModeForEntity(EntityDefImpl def, boolean mode) Sets the updatebatching (Batch post operations) mode on or off for a given entity type in this transaction.
void	setBundledExceptionMode(boolean flag) Set this transaction into bundled exception mode.
void	setClearCacheOnCommit(boolean val) Sets the value of the flag indicating whether all Entity Object caches will be cleared after the transaction is committed.
void	setClearCacheOnRollback(boolean val) Sets the value of the flag indicating whether all Entity Object caches will be cleared after the transaction is rolled back.
void	setDMLOperationTimeOut(int timeOutMills) Sets the query time out value for the Entity Object's DML operations.
void	setForceDeferValidation(boolean bForceDefer)
void	setLockingMode(int mode) Sets the preferred locking mode for this Transaction.
void	setTransactionHandler(TransactionHandler txnHandler) Internal: Applications should not use this method.
void	setValidationThreshold(int count) Sets the threshold value for the commit-cycle's validation phase.
void	validate() Starts the validation cycle and validates all subscribers in the ValidationListener list.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CLASS_INSTANCE

public static final java.lang.Class CLASS_INSTANCE

mLongRunningDMLOperationHandles

protected List mLongRunningDMLOperationHandles

mDMLOperationTimeOut

protected int mDMLOperationTimeOut

mConnectionMetaData

protected ConnectionDetails mConnectionMetaData

MAX_CURSORS_UNINITIALIZED

public static final int MAX_CURSORS_UNINITIALIZED

See Also:

Constant Field Values

POST_ALL_NO_RESET_ON_EXCEPTION

public static int POST_ALL_NO_RESET_ON_EXCEPTION

POST_ALL_RESET_ON_EXCEPTION

public static int POST_ALL_RESET_ON_EXCEPTION

POST_ABORT_ON_FIRST_EXCEPTION

public static int POST_ABORT_ON_FIRST_EXCEPTION

Constructor Detail

DBTransactionImpl

public DBTransactionImpl()

Method Detail

getSQLBuilder

public SQLBuilder getSQLBuilder()

Get the SQLBuilder class which is used to create SQL statements compatible with the underlying database connection

Specified by:

getSQLBuilder in interface DBTransaction

Returns:

SQLBuilder implementation

addTransactionListener

public void addTransactionListener(TransactionListener listener)

Add a TransactionListener. TransactionListener's are notified of events generated by this object.

Specified by:

addTransactionListener in interface DBTransaction

Parameters:

listener - New TransactionListener to add

connect

public void connect(ConnectionDetails metaData)

Connect to the datasource identified by the connection metadata

Specified by:

connect in interface DBTransaction

Parameters:

metaData - Identifies datasource (user, name, password, etc.)

createPreparedStatement

public PreparedStatement createPreparedStatement(java.lang.String sql)

Create a PreparedStatement on the underlying database connection

Specified by:

createPreparedStatement in interface DBTransaction

Parameters:

sql - SQL query to use as the basis for the parameterized statement

Returns:

A new PreparedStatement object

createStatement

public Statement createStatement()

Create a new, empty Statement that can be used to issue SQL queries

Specified by:

createStatement in interface DBTransaction

Returns:

A new Statement object

isConnected

public boolean isConnected()

Is this transaction object connected to the underlying database?

Specified by:

isConnected in interface DBTransaction

Specified by:

isConnected in interface Transaction

Returns:

true if connected, false if not

removeTransactionListener

public void removeTransactionListener(TransactionListener listener)

Remove a TransactionListener so it is no longer notified of transaction events

Specified by:

removeTransactionListener in interface DBTransaction

Parameters:

listener - TransactionListener object to remove

findEntityCache

public EntityCache findEntityCache(EntityDefImpl source)

Finds a Cache table for the entity. This method will find the internal EntityCache object which is allocated to cache the Entity information. If one is not already present for the type of Entity, then it will be created and returned.

Returns:

the EntityCache for the Entity in this Transaction.

getEntityCache

public EntityCache getEntityCache(EntityDefImpl source)

getEntityCache

protected EntityCache getEntityCache(java.lang.String fullName)

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.

Specified by:

commit in interface DBTransaction

Specified by:

commit in interface Transaction

See Also:

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

getRootApplicationModule

public ApplicationModule getRootApplicationModule()

Returns the root appmodule that owns this transaction.

Specified by:

getRootApplicationModule in interface DBTransaction

createPreparedStatement

public PreparedStatement createPreparedStatement(java.lang.String str,
                                                 int noRowsPrefetch)

Description copied from interface: DBTransaction

Creates a JDBC PreparedStatement instance.

Applications may use this method to create a JDBC callable statement object to execute application specific SQL statements directly, so that the modifications are committed to the database in a single transaction through this object.

Specified by:

createPreparedStatement in interface DBTransaction

Parameters:

str - the PreparedStatement instance's SQL statement.

noRowsPrefetch - the number of rows to prefetch when executing this statement's query. If this parameter is set to DBTransaction.DEFAULT, then the default value from the jdbc driver is used.

Returns:

a JDBC PreparedStatement instance.

addTransactionStateListener

public void addTransactionStateListener(TransactionStateListener target)

Add this TransactionListener to the list and notify all such listeners whenever commit and rollback occurs in this transaction.

Specified by:

addTransactionStateListener in interface Transaction

addViewClearCacheListener

public void addViewClearCacheListener(ViewClearCacheListener target)

Specified by:

addViewClearCacheListener in interface Transaction

applyChangeSet

public void applyChangeSet(int id)

Description copied from interface: Transaction

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

This method (along with commitAndSaveChangeSet 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 commitAndSaveChangeSet) 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.

For an example of how to use applyChangeSet, see commitAndSaveChangeSet.

Specified by:

applyChangeSet in interface Transaction

Parameters:

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

See Also:

Transaction.commitAndSaveChangeSet(), Transaction.removeChangeSet(int)

cancelDMLOperations

public boolean cancelDMLOperations()

Description copied from interface: Transaction

Cancels the currently running Entity Object DML operations.

Specified by:

cancelDMLOperations in interface Transaction

Returns:

A false is returned if a DML cancel fails.

clearEntityCache

public void clearEntityCache(java.lang.String entityName)

Description copied from interface: Transaction

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.

Specified by:

clearEntityCache in interface Transaction

Parameters:

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

commitAndSaveChangeSet

public int commitAndSaveChangeSet()

Description copied from interface: Transaction

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.

commitAndSaveChangeSet 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 Transaction.applyChangeSet(int) where int is the integer value returned by commitAndSaveChangeSet that represents the change set.

For example, assume you have two root Application Modules, named am1 and am2, in an Application Module pool.

  // The line below commits the transaction in am1 and writes the change
  // set to persistent store (database table).  The returning snapId
  // identifies the (persistent) change set.

  int snapId = am1.getTransaction().commitAndSaveChangeSet();

  // Use that change set and apply the changes to the other Application
  // Module, am2.  That is, apply changes from am1 to am2.

  am2.getTransaction().applyChangeSet(snapId);

  // When you are done with the change set, remove (free) it.

  am1.getTransaction().removeChangeSet(snapId);
 

Specified by:

commitAndSaveChangeSet in interface Transaction

Returns:

an integer representing an EntityImpl change set in persistent store.

See Also:

Transaction.applyChangeSet(int), Transaction.removeChangeSet(int)

connect

public void connect(java.lang.String url)

Description copied from interface: Transaction

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.

Specified by:

connect in interface Transaction

Parameters:

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

connect

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

Description copied from interface: Transaction

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.

Specified by:

connect in interface Transaction

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)

Description copied from interface: Transaction

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.

Specified by:

connect in interface Transaction

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.

connectToDataSource

public void connectToDataSource(java.lang.String nsUrl,
                                java.lang.String nsUser,
                                java.lang.String nsPasswd,
                                java.lang.String dataSourceName)

Description copied from interface: Transaction

Looks up a datasource from Oracle 8i namespace using the jdbc_access protocol and acquires the default jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection() method.

Specified by:

connectToDataSource in interface Transaction

Parameters:

nsUrl - Url to the jndi namespace where the datasource is bound

nsUser - User name that is used to access the namespace.

nsPasswd - nsUsers' passwd

dataSourceName - Datasource name as bound in the namespace. Name can be the fully qaultified url such as jdbc_access://test/ds/db1 otherwise the the url prefix jdbc_acess:// is prepended to the datasource name for lookup.

connectToDataSource

public void connectToDataSource(java.lang.String nsUrl,
                                java.lang.String nsUser,
                                java.lang.String nsPasswd,
                                java.lang.String dataSourceName,
                                java.lang.String user,
                                java.lang.String password)

Description copied from interface: Transaction

Looks up a datasource from Oracle 8i namespace using the jdbc_access protocol and acquires the jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection(String user, String password) method.

Specified by:

connectToDataSource in interface Transaction

Parameters:

nsUrl - Url to the jndi namespace where the datasource is bound

nsUser - User name that is used to access the namespace.

nsPasswd - nsUsers' passwd

dataSourceName - Datasource name as bound in the namespace. Name can be the fully qaultified url such as jdbc_access://test/ds/db1 otherwise the the url prefix jdbc_acess:// is prepended to the datasource name for lookup.

user - Username for which the connection is acquired from the datasource

password - User's password.

connectToDataSource

public void connectToDataSource(java.util.Hashtable initialContextEnv,
                                java.lang.String dataSourceName,
                                java.lang.String user,
                                java.lang.String password,
                                boolean isXABased)

Description copied from interface: Transaction

Looks up a datasource from a jndi tree and acquires the jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection(String user, String passwd) method.

Specified by:

connectToDataSource in interface Transaction

Parameters:

initialContextEnv - Envirionment used the create initial context. May be null.

dataSourceName - Datasource name as bound in the namespace.

user - Username for which the connection is acquired from the datasource

password - User's password.

isXABased - True if datasource is XADataSource implementation. If true, the tranasction is assumed to be controlled by an external transaction manager.

connectToDataSource

public void connectToDataSource(java.util.Hashtable initialContextEnv,
                                java.lang.String dataSourceName,
                                boolean isXABased)

Description copied from interface: Transaction

Looks up a datasource from a jndi tree and acquires the jdbc connection from the looked up datasource using the javax.sql.Datasource.getConnection(String user, String passwd) method.

Specified by:

connectToDataSource in interface Transaction

Parameters:

initialContextEnv - Envirionment used the create initial context. May be null.

dataSourceName - Datasource name as bound in the namespace.

isXABased - True if datasource is XADataSource implementation. If true, the tranasction is assumed to be controlled by an external transaction manager.

createRef

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

Description copied from interface: Transaction

Internal: Applications should not use this method.

Specified by:

createRef in interface Transaction

dumpQueryResult

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

Description copied from interface: Transaction

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);  }
 

Specified by:

dumpQueryResult in interface Transaction

Parameters:

query - the SQL query statement.

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

data - an array of data items.

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.

Specified by:

executeCommand in interface Transaction

Parameters:

command - a valid SQL statement.

Returns:

the number of rows affected.

Throws:

InvalidParamException - if command is empty.

SQLStmtException - if command fails.

getConnectionMetadata

public ConnectionDetails getConnectionMetadata()

Description copied from interface: Transaction

Returns a metdata structure that describes the transaction's JDBC connection.

Specified by:

getConnectionMetadata in interface Transaction

getDMLOperationTimeOut

public int getDMLOperationTimeOut()

Description copied from interface: Transaction

Returns the current Entity Object DML operation time out value. The default is DML_OPERATION_TIMEOUT_WAIT_FOREVER.

Specified by:

getDMLOperationTimeOut in interface Transaction

Returns:

the current Entity Object DML operation time out value.

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.

Specified by:

getLockingMode in interface Transaction

Returns:

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

setBundledExceptionMode

public void setBundledExceptionMode(boolean flag)

Description copied from interface: Transaction

Set this transaction into bundled exception mode. In this mode, all exceptions thrown during updates to rows will be cached by the entity-cache. However when the rows are validated either by explicit validation call or when the transaction is committed, these exceptions will be thrown bundled in a RowValException. When in bundledException mode, validation code in setXXX methods on the Entity will be executed and if a ValidationException is thrown from these methods, they're cached by the Entity and thrown later as a detail of RowValException when the Entity is eventually validated.

Specified by:

setBundledExceptionMode in interface Transaction

isBundledExceptionMode

public final boolean isBundledExceptionMode()

Specified by:

isBundledExceptionMode in interface Transaction

isClearCacheOnCommit

public boolean isClearCacheOnCommit()

Returns the flag indicating whether all Entity Object caches will be cleared after the transaction is committed.

After the transaction is committed, the value of this flag is used to determine whether the Entity Object caches are cleared or not. If this flag value is false, the cache contents are kept. In this case, the cache may contain data that is stale in that it does not match the newest data (changes made by another user and committed).

If this flag is true, the caches are cleared after the transaction is committed. When the user brings in data by traversing row collection, the latest data from the database will be brought into Entity caches.

Specified by:

isClearCacheOnCommit in interface Transaction

Returns:

the current value of clear-cache-on-commit flag.

See Also:

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

isClearCacheOnRollback

public boolean isClearCacheOnRollback()

Returns the flag indicating whether all Entity Object caches will be cleared after the transaction is rolled back.

After the transaction is rolled back, the value of this flag is used to determine whether the Entity Object caches are cleared or not. If this flag value is false, the cache contents are kept. In this case, the cache may contain data that is not in sync with database in that uncommitted changes made this by user (before the transaction was rolled back) will be kept.

If this flag is true, the caches are cleared after the transaction is rolled back. When the user brings in data by traversing row collection, the latest data from the database will be brought into Entity caches.

Specified by:

isClearCacheOnRollback in interface Transaction

Returns:

the current value of clear-cache-on-roll-back flag.

See Also:

RowSet.executeQuery(), setClearCacheOnRollback(boolean val), Transaction.isClearCacheOnCommit(), Transaction.setClearCacheOnCommit(boolean val)

isDirty

public boolean isDirty()

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.

Specified by:

isDirty in interface Transaction

Returns:

trueif any data within this Application Module has been modified but not yet committed; false otherwise.

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.

Specified by:

postChanges in interface Transaction

See Also:

commit()

postChanges

protected void postChanges(TransactionEvent te)

Internal: Applications should not use this method.

Synchronizes all the changes in this transaction-cache with the database. These changes are still not visible to other users/transaction.

Executes a savepoint before starting to post any changes. Then, all non-transient and transient TransactionPostListeners are notified to post their changes, in that order. In case of any exception, rollsback the transaction to the savepoint. and throws DMLException.

For Entity types that are marked to use batch update in case of oracle jdbc, first a maximal-attribute-changed-set is collected for each entity-type so that batch statements could be created for all changes. Then postChanges() is called on all the entities in the transaction just like in the normal case, but entity does not execute the dml, instead simply adds the DML to a batched statement which is executed after all entities are done adding their changes to the batch. Then for each entity type that has batched statements executes the batches (deletes first, followed by inserts and then updates). On any eror during the batch operations, the entire transaction is rolled back to the savepoint as described earlier.

reconnect

public void reconnect(boolean force)

Description copied from interface: Transaction

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.

Specified by:

reconnect in interface Transaction

Parameters:

force - force a reconnect, should usually be false.

removeChangeSet

public void removeChangeSet(int id)

Description copied from interface: Transaction

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

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

For an example of how to use removeChangeSet, see commitAndSaveChangeSet.

Specified by:

removeChangeSet in interface Transaction

Parameters:

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

See Also:

Transaction.commitAndSaveChangeSet(), Transaction.applyChangeSet(int)

removeTransactionStateListener

public void removeTransactionStateListener(TransactionStateListener target)

Specified by:

removeTransactionStateListener in interface Transaction

removeViewClearCacheListener

public void removeViewClearCacheListener(ViewClearCacheListener target)

Specified by:

removeViewClearCacheListener in interface Transaction

doRollback

protected void doRollback()

Called by the rollback method to issue the rollback call. This method is called just before the transaction is rolled back on the JDBC connection. Override this method to provide your own handler for the rollback operation.

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.

Specified by:

rollback in interface Transaction

See Also:

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

setClearCacheOnCommit

public void setClearCacheOnCommit(boolean val)

Description copied from interface: Transaction

Sets the value of the flag indicating whether all Entity Object caches will be cleared after the transaction is committed.

The initial value of this flag is retrieved from the Application Module definition of the root Application Module (an XML attribute value named "ClearCacheOnCommit" in the Application Module definition's XML file). If the Application Module definition does not contain the initial value, the default value is false, i.e., the caches are kept after commit.

The user can override the value of this flag for this Transaction by calling this method. Calling this method does not affect the initial value in the Application Module definition.

Specified by:

setClearCacheOnCommit in interface Transaction

Parameters:

val - the new value of the clear-cache-on-commit flag. true indicates that the Entity Object caches will be cleared after commit.

See Also:

Transaction.isClearCacheOnCommit()

setClearCacheOnRollback

public void setClearCacheOnRollback(boolean val)

Description copied from interface: Transaction

Sets the value of the flag indicating whether all Entity Object caches will be cleared after the transaction is rolled back.

The initial value of this flag is retrieved from the Application Module definition of the root Application Module (an XML attribute value named "ClearCacheOnRollback" in the Application Module definition's XML file). If the Application Module definition does not contain the initial value, the default value is true, i.e., the caches are cleared after rollback.

The user can override the value of this flag for this Transaction by calling this method. Calling this method does not affect the initial value in the Application Module definition.

Specified by:

setClearCacheOnRollback in interface Transaction

Parameters:

val - the new value of the clear-cache-on-roll-back flag. true indicates that the Entity Object caches will be cleared after rollback, and will be refreshed with new data from the database.

See Also:

Transaction.isClearCacheOnRollback()

setDMLOperationTimeOut

public void setDMLOperationTimeOut(int timeOutMills)

Description copied from interface: Transaction

Sets the query time out value for the Entity Object's DML operations. The default is DML_OPERATION_TIMEOUT_WAIT_FOREVER (-1), which means that the DML operations will not time out. The user will be able to cancel the long running operations by calling cancelDMLOperations() started by this Transaction during postChanges.

If a positive value of timeout is specified the operation is monitored by a global monitor thread. The monitor thread waits the specified amount of time (approximately) in milli-seconds, and cancels the operation by calling JDBC's Statement.cancel().

Specified by:

setDMLOperationTimeOut in interface Transaction

Parameters:

timeOutMills - if non-negative, number of milli-seconds before the DML operation is timed out.

setLockingMode

public void setLockingMode(int mode)

Description copied from interface: Transaction

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.

Specified by:

setLockingMode in interface Transaction

Parameters:

mode - one of LOCK_PESSIMISTIC, LOCK_OPTIMISTIC or LOCK_NONE.

validate

public void validate()

Description copied from interface: Transaction

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.

Specified by:

validate in interface ValidationManager

Specified by:

validate in interface Transaction

addToValidationListeners

public void addToValidationListeners(ValidationListener entity)

Adds an entity validation listener.

The entity listener will be notified to perform its own validation when this validation manager is validated.

This method overrides the ValidationManager.addToValidationListeners(ValidationListener) method.

Specified by:

addToValidationListeners in interface ValidationManager

Parameters:

entity - an entity validation listener.

addTransactionPostListener

public void addTransactionPostListener(TransactionPostListener listener)

Description copied from interface: DBTransaction

Adds a listener to the transaction's list of post-phase event subscribers.

Listeners are notified of events spawned by the postChanges() method. The framework adds modified top-level Entity Objects to this list.

Specified by:

addTransactionPostListener in interface DBTransaction

Parameters:

listener - the subscriber to be added.

removeTransactionPostListener

public void removeTransactionPostListener(TransactionPostListener listener)

Removes a subscriber from the transaction's post-events list.

Specified by:

removeTransactionPostListener in interface DBTransaction

Parameters:

listener - the subscriber to be removed.

getTxnApplicationModuleImpl

protected ApplicationModuleImpl getTxnApplicationModuleImpl()

Gets the root Application Module to which this transaction belongs.

Returns:

the root Application Module.

getSyncLock

public final java.lang.Object getSyncLock()

isTrackNewAndModifiedRowsOnly

public boolean isTrackNewAndModifiedRowsOnly()

Deprecated. since 9.0.5.1

Internal: Applications should not use this method.

Specified by:

isTrackNewAndModifiedRowsOnly in interface DBTransaction

lookupEntityCache

public EntityCache lookupEntityCache(EntityDefImpl source)

addTransactionPostListenerNoCheck

public void addTransactionPostListenerNoCheck(TransactionPostListener listener)

Internal: Applications should not use this method.

Adds a subscriber to the transaction's post-events list, without checking if it is already present.

When postChanges() is invoked, each listed TransactionPostListener is notified to post any changes to the database.

Parameters:

listener - the subscriber to be added.

See Also:

postChanges()

addTransactionListenerNoCheck

public void addTransactionListenerNoCheck(TransactionListener listener)

Internal: Applications should not call this method.

Adds a listener to the transaction's list, without checking whether the listener was present.

Listeners are notified of the commit and rollback events generated by the commit and rollback methods. The framework adds modified top-level Entity Objects to this list.

Specified by:

addTransactionListenerNoCheck in interface DBTransaction

Parameters:

listener - the subscriber to be added.

getTransValidationManager

public JboTransValidationManager getTransValidationManager()

getTransValidations

public java.util.Hashtable getTransValidations()

Specified by:

getTransValidations in interface JboTransValidationManager

getTransValidationList

public ArrayList getTransValidationList()

Specified by:

getTransValidationList in interface JboTransValidationManager

getTransAttrValidationManager

public JboTransAttrValidationManager getTransAttrValidationManager()

getTransAttrValidations

public java.util.Hashtable getTransAttrValidations()

Specified by:

getTransAttrValidations in interface JboTransAttrValidationManager

getTransAttrValidationList

public ArrayList getTransAttrValidationList()

Specified by:

getTransAttrValidationList in interface JboTransAttrValidationManager

putTransValEntry

public void putTransValEntry(JboTransValidatorInterface validator,
                             JboValidatorContext valCtx)

Specified by:

putTransValEntry in interface JboTransValidationManager

putTransAttrValEntry

public void putTransAttrValEntry(JboTransValidatorInterface validator,
                                 JboValidatorContext valCtx)

Specified by:

putTransAttrValEntry in interface JboTransAttrValidationManager

setValidationThreshold

public void setValidationThreshold(int count)

Description copied from interface: DBTransaction

Sets the threshold value for the commit-cycle's validation phase.

When commit() is invoked the framework attempts to validate the transaction's modifications, making count attempts before failing with an exception. This mechanism allows applications to update data in the cache within the validation phase, and validate them before they are posted.

Specified by:

setValidationThreshold in interface DBTransaction

Parameters:

count - the new threshold value.

getValidationThreshold

public int getValidationThreshold()

Description copied from interface: DBTransaction

Gets the threshold value for the commit-cycle's validation phase.

Specified by:

getValidationThreshold in interface DBTransaction

getPersistManagerConnection

public Connection getPersistManagerConnection()

Specified by:

getPersistManagerConnection in interface PCollManagerHelper

setForceDeferValidation

public void setForceDeferValidation(boolean bForceDefer)

isForceDeferValidation

public boolean isForceDeferValidation()

addLongRunningDMLOperationHandle

public void addLongRunningDMLOperationHandle(LongRunningStatementHandle handle)

removeLongRunningDMLOperationHandle

public void removeLongRunningDMLOperationHandle(LongRunningStatementHandle handle)

getPostThreshold

public int getPostThreshold()

getTransactionHandler

public TransactionHandler getTransactionHandler()

Internal: Applications should not use this method.

Specified by:

getTransactionHandler in interface DBTransaction

setTransactionHandler

public void setTransactionHandler(TransactionHandler txnHandler)

Internal: Applications should not use this method.

doCommit

protected void doCommit()

Called by the commit method to issue the commit call. This method is called just before the transaction is committed on the JDBC connection. Override this method to provide your own handler for the commit operation.

setBatchModeForEntity

public void setBatchModeForEntity(EntityDefImpl def,
                                  boolean mode)

Sets the updatebatching (Batch post operations) mode on or off for a given entity type in this transaction.

Parameters:

def - - Def for the desired entity type

mode - - whether to turn batch updates on or off. if false rest of the arguments are ignored. If attribute list is null or has no elements, then Def is consulted for any default setting in the def for AttributeLists for these purposes. If Def does not have an attribute list then ALL attributes participate in the concerned operation.

getBatchPostExceptionThreshold

public int getBatchPostExceptionThreshold()

In case of batch mode post operation, try to post the batched set of entities for each entity type and post operation (Insert/Update/Delete) for this many number of exceptions.

See Also:

#setBatchPostExceptionThreshold

hasRollbackSavePoint

protected boolean hasRollbackSavePoint()

getPostChangesFlag

public final int getPostChangesFlag()

Internal: Applications should not use this method.

createCallableStatement

public CallableStatement createCallableStatement(java.lang.String str,
                                                 int noRowsPrefetch)

createStatement

public Statement createStatement(int noRowsPrefetch)

Description copied from interface: DBTransaction

Creates a JDBC Statement instance.

Applications may use this method to create a JDBC statement object to execute application specific SQL statements directly, so that the modifications are committed to the database in a single transaction through this object.

Specified by:

createStatement in interface DBTransaction

Parameters:

noRowsPrefetch - the number of rows to prefetch when executing this statement's query.

Returns:

a JDBC Statement instance.

getTransactionState

protected int getTransactionState()

createViewObjectFromQueryClauses

public ViewObject createViewObjectFromQueryClauses(java.lang.String eoName,
                                                   java.lang.String selectClause,
                                                   java.lang.String fromClause,
                                                   java.lang.String whereClause,
                                                   java.lang.String orderByClause)

Creates an updatable query definition.

Creates an anonymous query definition from an Entity Object and parts of a SQL statement. For more information on anonymous View Objects, see Using Anonymous View Objects

Calling method should also call remove() for the View Object to be properly garbage-collected.

Specified by:

createViewObjectFromQueryClauses in interface DBTransaction

Parameters:

eoName - the name of a EntityObject beaninfo class.

selectClause - an SQL statement SELECT clause.

fromClause - an SQL statement FROM clause.

whereClause - an SQL statement WHERE clause.

orderByClause - an SQL statement ORDERBY clause.

getSession

public Session getSession()

Gets the session information.

Returns:

the session.

Throws:

java.lang.IllegalStateException - if the session information cannot be found.

disconnect

public void disconnect()

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

As an alternative, you can also use the disconnect method on the Transaction interface.

Specified by:

disconnect in interface DBTransaction

Specified by:

disconnect in interface Transaction

disconnect

public void disconnect(boolean retainState)

Closes the JDBC connection object. If disconnect is invoked with retainState equal to false then the JDBC connection will be closed and this transaction will be removed* from the root application module.

If disconnect is invoked with retainState equal to true then this transaction's JDBC connection will be closed but, the root application module will continue to reference this transaction and its state. The transaction state may include unposted database changes and cached result sets. In the middle tier, reconnect on the DBTransaction interface may be invoked to re-establish a JDBC connection for this transaction. If connection pooling is enabled for this middle tier instance this connection may represent a recycled connection.

The developer should take measures to ensure that the following requirements are met before attempting to disconnect a JDBC connection and retain application module state. All of these validations are not currently performed by the disconnection implementation because of performance considerations:

All non-forward only view objects should have fetched in all data

If pessimistic locking is enabled, all pending changes should be commited/rolled back.

All changes that have been posted to the database should be commited/rolled back>/p>

Specified by:

disconnect in interface Transaction

closeTransaction

public void closeTransaction()

Internal: Applications should not use this method.

Closes this transaction's JDBC connection.

Performs rollback on the current transaction to reset all the data in the cache to their initial states and then drops the JDBC connection. This method is invoked by disconnect to terminate the JDBC connection. Applications should use disconnect() instead of closeTransaction() to properly release JDBC resources.

getJdbcConnection

protected Connection getJdbcConnection()

Returns the JDBC connection for this transaction.

reconnect

public void reconnect()

Reconnect the ApplicationModule to the database, using previously supplied database credentials. This method should only be invoked if the transaction has been previously disconnected using disconnect(boolean) with the retainState parameter equal to true or, if a previous isConnected() request had discovered a stale JDBC connection. If it is invoked otherwise the method will do nothing.

Specified by:

reconnect in interface DBTransaction

Specified by:

reconnect in interface Transaction

See Also:

disconnect(boolean)

isConnected

public boolean isConnected(boolean pingDatabase)

checkConnected

protected void checkConnected()
                       throws NotConnectedException

Throws:

NotConnectedException