Business Components

oracle.jbo.server
Class DBTransactionImpl

java.lang.Object
  |
  +--oracle.jbo.server.DBTransactionImpl

public class DBTransactionImpl
extends java.lang.Object
implements DBTransaction

The superclass of classes representing connections of middle-tier objects to databases.

Instances encapsulate the JDBC connection, provide commit() and rollback() operations, and maintain various internal framework states, events and caches of entity data.

Advanced applications can provide custom subclass implementations using DatabaseTransactionFactory.

Using Anonymous View Objects

The DBTransactionImpl class has these methods for creating View Objects:

In contrast to the "create View Object" methods on the ApplicationModuleImpl class, the methods on DBTransaction do not take a String voNname parameter. These methods create anonymous View Objects on the database transaction. Anonymous View Objects do not require an Application Module. An anonymous View Object is a View Object to which you do not give a name and that is usually used locally. For example, you could use an anonymous View Object when you want to perform a query (for example, a look-up) through a View Object, then remove it.

Anonymous View Objects should not be passed around between Application Modules. As soon as the anonymous View Object has performed its task, it should be discarded with the View Object remove() method.

Using anonymous View Objects also lets you avoid name clashes between View Objects. For example, if one Entity Object developer builds some code that is expecting to create a View Object in its own Application Module with a name like "temp" and another unrelated Entity Object developer builds some code that is expecting to work with a View Object in its own Application Module named "temp" (but which is for a totally different View Object), then if an application required both of these Application Modules to works as peers, name clashes could result.

The method getDBTransaction().createViewObject() creates a View Object from a definition created at design time which can be based on Entity Objects just like the ones you might have been creating with the createViewObject from the ApplicationModule class.

The DBTransactionImpl class also has createViewObjectFromQueryStmt and createViewObjectFromQueryClauses just like the Application Module class does; all of the same functionality is available to the Entity Object business logic writer.

The only difference is that the DBTransactionImpl class approach forces the Entity Object business logic writer to not pre-select an "instance" name for the View Object being used (the equivalent of calling the Application Module-level methods with a null instance name argument) so that the system ensures the "instance" names are unique and no unintended clashes occur.

To illustrate the differences between using the create View Object methods on the Application Module class versus the DBTransaction class, consider the following code snippets. Assume you have a method called doSomething() on an Entity Object to implement some operation. Two possible implementations are:

  // Implementation 1
 public void doSomething() {
     DBTransaction txn = this.getDBTransaction();
     ViewObject vo1 =
 txn.createViewObject("myPackage.MyFirstViewObject");
     ViewObject vo2 =
 txn.createViewObject("myPackage.MySecondViewObject");

     // Do something here...

     vo1.remove();
     vo2.remove();
 }

 // Implementation 2
 public void doSomething() {
     DBTransaction txn = this.getDBTransaction();
     MyApplicationModule am =
 txn.createApplicationModule("myPackage.MyAppModule");
     ViewObject vo1 = am.getMyFirstViewObject();
     ViewObject vo2 = am.getMySecondViewObject();

     // Do the same something here...

     am.remove();
 }
 
The following lists compare the advantages and disadvangages of each implementation.

Implementation 1:

Implementation 2:

Generally, the motivation for separating code out into an Application Module would be the same as the general motivation for separating code out into a different a class.

In that sense, you may choose to take your example one step further and move the "Do Something Here" code into the Application Module class:

 // Implementation 3
 public void doSomething() {
     DBTransaction txn = this.getDBTransaction();
     MyApplicationModule am = (MyApplicationModule)
 txn.createApplicationModule("myPackage.MyAppModule");
     am.doSomethingThere(...);
     am.remove();
 }
  
Implementations 1 and 2 are both correct approaches. Creating a nested Application Module is good for multi-View Object data models, and DbTransaction is good for simple one-off queries. If your application is using one-off queries most of the time, you might find that the extra overhead of creating an Application Module "container" might not add sufficient value.

Since:
JDevloper 3.0

Field Summary
static int MAX_CURSORS_UNINITIALIZED
           
protected  ConnectionCredentials mConnectionCredentials
           
protected  ConnectionCredentials mInternalCredentials
           
protected  SQLBuilder mSQLBuilder
          The SQLBuilder instance used to interact with JDBC in this transaction.
 
Fields inherited from interface oracle.jbo.server.DBTransaction
DEFAULT
 
Fields inherited from interface oracle.jbo.Transaction
LOCK_NONE, LOCK_OPTIMISTIC, LOCK_PESSIMISTIC
 
Constructor Summary
DBTransactionImpl(java.sql.Connection connection)
          Creates an instance from an existing JDBC connection.
DBTransactionImpl(java.lang.String url)
          Attempts to establish a connection to a database through the given URL.
DBTransactionImpl(java.lang.String url, java.util.Properties info)
          Attempts to establish a connection to a database through the given URL.
DBTransactionImpl(java.lang.String url, java.lang.String user, java.lang.String password)
          Attempts to establish a connection to a database through the given URL.
DBTransactionImpl(java.lang.String url, java.lang.String user, java.lang.String password, java.util.Properties info)
          Internal: Applications should not use this constructor.
 
Method Summary
 void addToValidationListeners(ValidationListener entity)
          Adds an entity validation listener.
 void addTransactionListener(TransactionListener listener)
          Adds a listener to the transaction's list.
 void addTransactionListenerNoCheck(TransactionListener listener)
          Internal: Applications should not call this method.
 void addTransactionPostListener(TransactionPostListener listener)
          Adds a subscriber to the transaction's post-events list.
 void addTransactionPostListenerNoCheck(TransactionPostListener listener)
          Internal: Applications should not use this method.
 void addWarning(JboWarning warn)
          Adds a warning to the root Application Module's current list of warnings.
 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 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(java.sql.Connection sqlConnection)
          Internal: Applications should not use this method.
 void connect(java.lang.String url)
          Internal: Applications should not use this method.
 void connect(java.lang.String url, java.util.Properties info)
          Internal: Applications should not use this method.
 void connect(java.lang.String url, java.lang.String user, java.lang.String password)
          Internal: Applications should not use this method.
 ApplicationModule createApplicationModule(java.lang.String defName)
          Creates an Application Module.
 java.sql.CallableStatement createCallableStatement(java.lang.String str, int noRowsPrefetch)
          Creates a JDBC CallableStatement instance.
 EntityImpl createEntityInstance(EntityDefImpl entityDef, AttributeList al)
          Creates an EntityImpl object based on the given defintion, in the context of the root Application Module.
 EntityImpl createEntityInstance(java.lang.String entityDefName, AttributeList al)
          Creates an EntityImpl object based on the given defintion, in the context of the root Application Module.
 java.sql.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.
 java.sql.Statement createStatement(int noRowsPrefetch)
          Creates a JDBC Statement instance.
 ViewLink createViewLink(java.lang.String viewLinkDefName, ViewObject master, ViewObject detail)
          Creates an anonymous View Link.
 ViewLink createViewLinkBetweenViewObjects(java.lang.String accessorName, ViewObject master, AttributeDef[] srcAttrs, ViewObject detail, AttributeDef[] destAttrs, java.lang.String assocClause)
          Creates an anonymous View Link.
 ViewLink createViewLinkFromEntityAssocName(java.lang.String entityAssocName, ViewObject master, ViewObject detail)
          Creates a View Link.
 ViewObject createViewObject(java.lang.String voDefName)
          Creates an anonymous query definition from the name of a ViewObject class.
 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.
 ViewObject createViewObjectFromQueryStmt(java.lang.String sqlStatement)
          Creates an anonymous query definition from an SQL statement.
 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.
 void dumpEntityCaches(java.io.Writer out)
          Internal: Applications should not use this method.
 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.
 EntityImpl findByPrimaryKey(EntityDefImpl entityDef, Key key)
          Finds an Entity Object in this transaction given an EntityDef object and a Primary Key.
 EntityImpl findByPrimaryKey(java.lang.String entityDefName, Key key)
          Finds an Entity Object in this transaction given the String name of the EntityDef and a Primary Key.
protected  java.sql.Connection getJdbcConnection()
          Returns the JDBC connection for this transaction.
 int getLockingMode()
          Returns the preferred locking mode for this Transaction.
 int getPostThreshold()
          Gets the threshold value for the commit-cycle's post phase.
 Session getSession()
          Gets the session information.
 SQLBuilder getSQLBuilder()
          Internal: Applications should not use this method.
 TransactionHandler getTransactionHandler()
          Internal: Applications should not use this method.
 int getValidationThreshold()
          Gets the threshold value for the commit-cycle's validation phase.
 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()
          This method is typically called before an attempt is made to post the data.
 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 reconnect()
          Reconnect the Application Module 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 removeTransactionListener(TransactionListener listener)
          Removes a subscriber from the transaction's events list.
 void removeTransactionPostListener(TransactionPostListener listener)
          Removes a subscriber from the transaction's post-events list.
 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 setPostThreshold(int count)
          Sets the threshold value for the commit-cycle's post phase.
 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 showCursorUsage(java.io.Writer out)
          Internal: Applications should not use this method.
 void validate()
          Starts the validation cycle and validates all subscribers in the ValidationListener list.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

mSQLBuilder

protected SQLBuilder mSQLBuilder
The SQLBuilder instance used to interact with JDBC in this transaction.

MAX_CURSORS_UNINITIALIZED

public static final int MAX_CURSORS_UNINITIALIZED

mConnectionCredentials

protected ConnectionCredentials mConnectionCredentials

mInternalCredentials

protected ConnectionCredentials mInternalCredentials
Constructor Detail

DBTransactionImpl

public DBTransactionImpl(java.sql.Connection connection)
Creates an instance from an existing JDBC connection. This constructor is used when applications supply their own JDBC connection to an Application Module's transaction.
Parameters:
connection - an existing connection.

DBTransactionImpl

public DBTransactionImpl(java.lang.String url)
Attempts to establish a connection to a database through the given URL. The driver manager attempts to select an appropriate driver from the set of registered JDBC drivers.
Parameters:
url - a database URL of the form JDBC:subprotocol:subname.

DBTransactionImpl

public DBTransactionImpl(java.lang.String url,
                         java.util.Properties info)
Attempts to establish a connection to a database through the given URL. The driver manager attempts to select an appropriate driver from the set of registered JDBC drivers.
Parameters:
url - a database URL of the form JDBC:subprotocol:subname.
info - a list of arbitrary string tag/value pairs as connection arguments; normally at least "user" and "password" tags should be included.

DBTransactionImpl

public DBTransactionImpl(java.lang.String url,
                         java.lang.String user,
                         java.lang.String password)
Attempts to establish a connection to a database through the given URL. The driver manager attempts to select an appropriate driver from the set of registered JDBC drivers.
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.

DBTransactionImpl

public DBTransactionImpl(java.lang.String url,
                         java.lang.String user,
                         java.lang.String password,
                         java.util.Properties info)
Internal: Applications should not use this constructor.

Attempts to establish a connection to the given database URL. The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers.

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
info - a list of arbitrary string tag/value pairs as connection arguments; normally at least a "user" and "password" property should be included
Method Detail

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.

Specified by:
closeTransaction in interface DBTransaction

getSQLBuilder

public SQLBuilder getSQLBuilder()
Internal: Applications should not use this method.

Identifies the SQLBuilder that is used by this driver. In the runtime, the SQLBuilder that is used depends on whether the JDBC driver is Oracle-specific or non-Oracle-specific.

Specified by:
getSQLBuilder in interface DBTransaction
Returns:
the SQLBuilder used by the current JDBC driver.

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 oracle.jbo.Transaction.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.

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(), Transaction.isClearCacheOnCommit(), Transaction.setClearCacheOnCommit(boolean val)

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

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.

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(), Transaction.setClearCacheOnRollback(boolean val), Transaction.isClearCacheOnRollback()

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

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

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

Tags copied from interface: Transaction
Returns:
an integer representing an EntityImpl change set in persistent store.
See Also:
Transaction.applyChangeSet(int), Transaction.removeChangeSet(int)

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.

Tags copied from interface: Transaction
Parameters:
id - an integer representing the change set to apply to the transaction.
See Also:
Transaction.commitAndSaveChangeSet(), Transaction.removeChangeSet(int)

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.

Tags copied from interface: Transaction
Parameters:
id - an integer representing the change set to remove from the persistent store.
See Also:
Transaction.commitAndSaveChangeSet(), Transaction.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)

addTransactionListener

public void addTransactionListener(TransactionListener listener)
Adds a listener to the transaction's list.

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.

This method is available only on the middle tier; it is not available on the client.

This method should not be overridden.

Specified by:
addTransactionListener in interface DBTransaction
Parameters:
listener - the subscriber to be added.
See Also:
commit(), rollback()

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.

removeTransactionListener

public void removeTransactionListener(TransactionListener listener)
Removes a subscriber from the transaction's events list.
Specified by:
removeTransactionListener in interface DBTransaction
Parameters:
listener - the subscriber to be removed.

addTransactionPostListener

public void addTransactionPostListener(TransactionPostListener listener)
Adds a subscriber to the transaction's post-events list.

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

Specified by:
addTransactionPostListener in interface DBTransaction
Parameters:
listener - the subscriber to be added.
See Also:
postChanges()

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.

Specified by:
addTransactionPostListenerNoCheck in interface DBTransaction
Parameters:
listener - the subscriber to be added.
See Also:
postChanges()

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.

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

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.


createStatement

public java.sql.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
Tags copied from interface: DBTransaction
Parameters:
noRowsPrefetch - the number of rows to prefetch when executing this statement's query.
Returns:
a JDBC Statement instance.

createCallableStatement

public java.sql.CallableStatement createCallableStatement(java.lang.String str,
                                                          int noRowsPrefetch)
Description copied from interface: DBTransaction
Creates a JDBC CallableStatement 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:
createCallableStatement in interface DBTransaction
Tags copied from interface: DBTransaction
Parameters:
str - the CallableStatement 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 CallableStatement instance.

createPreparedStatement

public java.sql.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
Tags copied from 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.

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.

getLockingMode

public int getLockingMode()
Returns the preferred locking mode for this Transaction. For example:

 am.getTransaction().getLockingMode();
 
The possible return values are:

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.

setLockingMode

public void setLockingMode(int mode)
Sets the preferred locking mode for this Transaction. The possible values are:

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

Parameters:
mode - one of LOCK_PESSIMISTIC, LOCK_OPTIMISTIC or LOCK_NONE.

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.
Tags copied from interface: Transaction
Parameters:
entityName - the name of the entity whose cache is to be cleared. If null, caches for all entities are cleared.

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.

Parameters:
entity - an entity validation listener.

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.

Tags copied from interface: ValidationManager
Throws:
JboException - if validation fails.

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
Tags copied from 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

setPostThreshold

public void setPostThreshold(int count)
Description copied from interface: DBTransaction
Sets the threshold value for the commit-cycle's post phase.

When commit() is invoked the framework attempts to post the transaction's modifications, making count attempts before failing with an exception. This mechanism allows applications to update data in the cache within the post phase, and commit all changes.

Specified by:
setPostThreshold in interface DBTransaction
Tags copied from interface: DBTransaction
Parameters:
count - the new threshold value.

getPostThreshold

public int getPostThreshold()
Description copied from interface: DBTransaction
Gets the threshold value for the commit-cycle's post phase.
Specified by:
getPostThreshold in interface DBTransaction

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.
Returns:
trueif any data within this Application Module has been modified but not yet committed; false otherwise.

dumpEntityCaches

public void dumpEntityCaches(java.io.Writer out)
Internal: Applications should not use this method.

showCursorUsage

public void showCursorUsage(java.io.Writer out)
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.

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.

connect

public void connect(java.sql.Connection sqlConnection)
Internal: Applications should not use this method.
Specified by:
connect in interface DBTransaction

connect

public void connect(java.lang.String url)
Internal: Applications should not use this method.

Use the connect method on the Transaction interface instead.

Tags copied from interface: Transaction
Parameters:
url - a database url of the form jdbc:subprotocol:subname.

connect

public void connect(java.lang.String url,
                    java.util.Properties info)
Internal: Applications should not use this method.

Use the connect method on the Transaction interface instead.

Tags copied from 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)
Internal: Applications should not use this method.

Use the connect method on the Transaction interface instead.

Tags copied from 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.

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.

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 DBTransaction

reconnect

public void reconnect()
Reconnect the Application Module to the database, using previously supplied database credentials.
Specified by:
reconnect in interface DBTransaction
Parameters:
force - force a reconnect, should usually be false.

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.

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


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.
Specified by:
setTransactionHandler in interface DBTransaction

createEntityInstance

public EntityImpl createEntityInstance(EntityDefImpl entityDef,
                                       AttributeList al)
Creates an EntityImpl object based on the given defintion, in the context of the root Application Module. Passes the attribute list, al, to the create method on the EntityImpl.
Specified by:
createEntityInstance in interface DBTransaction
Parameters:
entityDef - the EntityDef defintion to use to create the EntityImpl.
al - attribute list to pass to the create() method on the EntityImpl.

createEntityInstance

public EntityImpl createEntityInstance(java.lang.String entityDefName,
                                       AttributeList al)
Creates an EntityImpl object based on the given defintion, in the context of the root Application Module. Passes the attribute list, al, to the create method on the EntityImpl.
Specified by:
createEntityInstance in interface DBTransaction
Parameters:
entityDefName - the String name of entity defintion to use to create the EntityImpl.
al - attribute list to pass to the create method on the EntityImpl.

findByPrimaryKey

public EntityImpl findByPrimaryKey(EntityDefImpl entityDef,
                                   Key key)
Finds an Entity Object in this transaction given an EntityDef object and a Primary Key.

Given the EntityDef object and the table's primary key, this method returns the associated Entity Object. If the Entity has not already been brought into the cache by any of the View Objects, this method will cause the Entity to be fetched from the database. This method returns null if the Entity Object is not found.

For example, use this method to create a set of Entity Objects based on a relational schema without the need to create any Application Modules or View Objects. To do this, use findByPrimaryKey to locate a specific object and then traverse association accessors to get to all the other objects.

Specified by:
findByPrimaryKey in interface DBTransaction
Parameters:
entityDef - the Entity Def object to to be used to find the instance.
key - the Primary Key.
Returns:
the Entity Object matching Key, or null if not found.

findByPrimaryKey

public EntityImpl findByPrimaryKey(java.lang.String entityDefName,
                                   Key key)
Finds an Entity Object in this transaction given the String name of the EntityDef and a Primary Key.

Given the String name of the EntityDef and the table's primary key, this method returns the associated Entity Object. If the Entity has not already been brought into the cache by any of the View Objects, this method will cause the Entity to be fetched from the database.

This method returns null if the Entity Object is not found.

For example, use this method to create a set of Entity Objects based on a relational schema without the need to create any Application Modules or View Objects. To do this, use findByPrimaryKey to locate a specific object and then traverse association accessors to get to all the other objects.

Specified by:
findByPrimaryKey in interface DBTransaction
Parameters:
entityDefName - the name of the defintion to to be used to find the instance.
key - the Primary Key.
Returns:
the Entity Object matching Key, or null if not found.

createViewObject

public ViewObject createViewObject(java.lang.String voDefName)
Creates an anonymous query definition from the name of a ViewObject class. 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:
createViewObject in interface DBTransaction
Parameters:
voName - the name of the ViewObject class.

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.

createViewObjectFromQueryStmt

public ViewObject createViewObjectFromQueryStmt(java.lang.String sqlStatement)
Creates an anonymous query definition from an 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.

The following example creates a View Object that queries for the system date:

  ViewObject vo = tx.createViewObjectFromQueryStmt("select sysdate
   from dual");
         Row row = vo.first();
         Date now = (Date) row.getAttribute(0);
         System.out.println("The date/time is now: "+now);
         oracle.sql.DATE nextMonth = now.addMonths(1);
         System.out.println("The date/time is now: "+nextMonth);
 
Specified by:
createViewObjectFromQueryStmt in interface DBTransaction
Parameters:
sqlStatement - a SQL statement.

createApplicationModule

public ApplicationModule createApplicationModule(java.lang.String defName)
Description copied from interface: DBTransaction
Creates an Application Module.

Specified by:
createApplicationModule in interface DBTransaction
Tags copied from interface: DBTransaction
Parameters:
defName - the name of the Application Module definition to be used. If null a default definition is used.
Returns:
a new Application Module.

createViewLink

public ViewLink createViewLink(java.lang.String viewLinkDefName,
                               ViewObject master,
                               ViewObject detail)
Creates an anonymous View Link.
Specified by:
createViewLink in interface DBTransaction
Parameters:
viewLinkDefName - the name of the definition to be used to create the link. If empty a default definition will be used.
master - the link's source.
detail - the link's destination.
Throws:
InvalidParamException - if master or detail are invalid.
InvalidObjNameException - if viewLinkName is invalid.
NameClashException - if viewLinkName already exists.

createViewLinkFromEntityAssocName

public ViewLink createViewLinkFromEntityAssocName(java.lang.String entityAssocName,
                                                  ViewObject master,
                                                  ViewObject detail)
Creates a View Link.
Specified by:
createViewLinkFromEntityAssocName in interface DBTransaction
Parameters:
entityAssocName - the entity association that the View Link will represent.
master - the link's source.
detail - the link's destination.
Throws:
InvalidParamException - if master, detail, or entityAssocName are invalid.
InvalidObjNameException - if viewLinkName is invalid.
NameClashException - if viewLinkName already exists.

createViewLinkBetweenViewObjects

public ViewLink createViewLinkBetweenViewObjects(java.lang.String accessorName,
                                                 ViewObject master,
                                                 AttributeDef[] srcAttrs,
                                                 ViewObject detail,
                                                 AttributeDef[] destAttrs,
                                                 java.lang.String assocClause)
Creates an anonymous View Link.
Specified by:
createViewLinkBetweenViewObjects in interface DBTransaction
Parameters:
accessorName - the name to be given to the View Link's accessor.
master - the link's source.
srcAttrs - link attributes taken from the master View Object.
detail - the link's destination.
destAttrs - link attributes taken from the detail View Object.
assocClause -  
Throws:
InvalidParamException - if master or detail are invalid.
InvalidObjNameException - if viewLinkName or accessorName are invalid.
NameClashException - if viewLinkName or accessorName already exist.

addWarning

public void addWarning(JboWarning warn)
Description copied from interface: DBTransaction
Adds a warning to the root Application Module's current list of warnings.

These warnings may be used for diagnostic purposes and may contain application-specific messages.

Specified by:
addWarning in interface DBTransaction
Tags copied from interface: DBTransaction
Parameters:
warn - a warning message.

getSession

public Session getSession()
Gets the session information.
Specified by:
getSession in interface DBTransaction

getJdbcConnection

protected java.sql.Connection getJdbcConnection()
Returns the JDBC connection for this transaction.

createRef

public java.lang.Object createRef(java.lang.String structName,
                                  byte[] data)
Internal: Applications should not use this method.

Business Components