|
Business Components | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Provides the base methods for defining database transactions.
Field Summary |
Type | Field |
---|---|
static int |
LOCK_NONE
Indicates that the row locking mode is Manual. |
static int |
LOCK_OPTIMISTIC
Indicates that the row locking mode is Automatic and Optimistic. |
static int |
LOCK_PESSIMISTIC
Indicates that the row locking mode is Automatic and Pessimistic. |
Method Summary |
Type | Method |
---|---|
void |
addTransactionStateListener(TransactionStateListener target)
|
void |
applyChangeSet(int id)
Applies the changes committed by another transaction in order to synchronize caches between root Application Module instances. |
void |
clearEntityCache(java.lang.String entityName)
Clears the cache of the specified Entity Object. |
void |
commit()
Commits all changes in this transaction to the database, making them visible to other users and transactions. |
int |
commitAndSaveChangeSet()
Commits the transaction and writes updated EntityImpls to the persistent store. |
void |
connect(java.lang.String url)
Attempts to establish a connection to a database identified by a URL. |
void |
connect(java.lang.String url,
java.util.Properties info)
Attempts to establish a connection to a database identified by a URL. |
void |
connect(java.lang.String url,
java.lang.String user,
java.lang.String password)
Attempts to establish a connection to a database identified by a URL. |
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. |
java.lang.Object |
createRef(java.lang.String structName,
byte[] data)
Internal: Applications should not use this method. |
void |
disconnect()
Closes the JDBC connection object and removes this transaction from the root application module. |
void |
disconnect(boolean retainState)
Closes the JDBC connection object. |
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. |
ConnectionMetadata |
getConnectionMetadata()
Returns a metdata structure that describes the transaction's JDBC connection. |
int |
getLockingMode()
Returns the preferred locking mode for this Transaction. |
boolean |
isBundledExceptionMode()
|
boolean |
isClearCacheOnCommit()
Indicates whether all Entity Object caches will be cleared after the transaction is committed. |
boolean |
isClearCacheOnRollback()
Indicates whether all Entity Object caches will be cleared after the transaction is rolled back. |
boolean |
isConnected()
Checks if the transaction is connected to the database. |
boolean |
isDirty()
Checks if any data within this Application Module has been modified but not yet committed. |
void |
postChanges()
Synchronizes the changes in the middle-tier transaction-cache with the database. |
void |
reconnect()
Re-establish the transaction JDBC connection using previously supplied database credentials. |
void |
reconnect(boolean force)
Deprecated. Deprecated since 3.2. Instead, use reconnect(). |
void |
removeChangeSet(int id)
Removes the change set that defines the changes to EntityImpls within a transaction. |
void |
removeTransactionStateListener(TransactionStateListener target)
|
void |
rollback()
Discards all modifications made in this transaction. |
void |
setBundledExceptionMode(boolean flag)
Set this transaction into bundled exception mode. |
void |
setClearCacheOnCommit(boolean val)
Indicates whether all Entity Object caches will be cleared after the transaction is committed. |
void |
setClearCacheOnRollback(boolean val)
Indicates whether all Entity Object caches will be cleared after the transaction is rolled back. |
void |
setLockingMode(int mode)
Sets the preferred locking mode for this Transaction. |
void |
validate()
Starts the validation cycle and validates all subscribers in the ValidationListener list. |
Field Detail |
public static final int LOCK_NONE
public static final int LOCK_PESSIMISTIC
public static final int LOCK_OPTIMISTIC
Method Detail |
public void connect(java.lang.String 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.
url
- a database url of the form jdbc:subprotocol:subname.public void connect(java.lang.String url, java.util.Properties info)
The DriverManager
attempts to select an appropriate driver from
the set of registered JDBC drivers.
Call isConnected
to see if the connection was successful.
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.public void connect(java.lang.String url, java.lang.String user, java.lang.String password)
The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers.
Call isConnected
to see if the connection was successful.
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.public void connectToDataSource(java.lang.String nsUrl, java.lang.String nsUser, java.lang.String nsPasswd, java.lang.String dataSourceName)
nsUrl
- Url to the jndi namespace where the datasource is boundnsUser
- User name that is used to access the namespace.nsPasswd
- nsUsers' passwddatasourceName
- 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.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)
nsUrl
- Url to the jndi namespace where the datasource is boundnsUser
- User name that is used to access the namespace.nsPasswd
- nsUsers' passwddatasourceName
- 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 datasourcepassword
- User's password.public void connectToDataSource(java.util.Hashtable initialContextEnv, java.lang.String dataSourceName, java.lang.String user, java.lang.String password, boolean isXABased)
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 datasourcepassword
- User's password.isXABased
- True if datasource is XADataSource implementation.
If true, the tranasction is assumed to be controlled
by an external transaction manager.public void connectToDataSource(java.util.Hashtable initialContextEnv, java.lang.String dataSourceName, boolean isXABased)
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.public void reconnect()
If the application module was previously disconnected using disconnect(true) (retain application module state) then this method should only re-establish the transaction JDBC connection.
If the application module was previously disconnected using disconnect(false) (do not retain application module state) then this method should re-establish the transaction JDBC connection and reset the application module non-transactional state which may include child view usage and application module usage instances.
public void reconnect(boolean force)
force
- force a reconnect, should usually be false.public void disconnect()
In the middle-tier, you can also use the disconnect
method on the DBTransactionImpl
interface.
public void disconnect(boolean retainState)
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.
public boolean isConnected()
public void setLockingMode(int mode)
Changing the locking mode affects only subsequent locks. Current locks are not affected.
mode
- one of LOCK_PESSIMISTIC, LOCK_OPTIMISTIC
or LOCK_NONE.public int getLockingMode()
am.getTransaction().getLockingMode();The possible return values are:
If not set by setLockingMode
,
the locking mode defaults to LOCK_PESSIMISTIC
.
public void setClearCacheOnCommit(boolean val)
isClearCacheOnCommit
.val
- true indicates that the Entity Object caches will be cleared
on commit, and will be refreshed with new data from the database.#isClearCacheOnCommit(boolean val)
public boolean isClearCacheOnCommit()
RowSet.executeQuery
might miss some of the changes.
The value of the Application Module's
isClearCacheOnCommit() flag will be used if the client has not
set this flag in the Transaction.
At the end of transaction, the transaction checks the value of its
isClearCacheOnCommit()
flag and either clears the Entity Object caches or not.
However, if the client never called
setClearCacheOnCommit
on this transaction, the framework will use the value for the root
Application Module's definition object.
In contrast, if the client called setClearCacheOnCommit on the Transaction, then the value of the root Application Module Def's isClearCacheOnCommit is not used.
Note that clearing the Entity Object caches has performance ramifications: repopulating the caches is expensive in terms of time and processing effort.
For middle-tier applications, you can use
isClearCacheOnCommit
and
setClearCacheOnCommit
in the DBTransactionImpl
class.
RowSet.executeQuery()
,
setClearCacheOnCommit(boolean val)
,
DBTransactionImpl.isClearCacheOnCommit()
,
DBTransactionImpl.setClearCacheOnCommit(boolean val)
public void setClearCacheOnRollback(boolean val)
isClearCacheOnRollback
val
- true indicates that the Entity Object caches will be cleared
on rollback, and will be refreshed with new data from the database.isClearCacheOnRollback()
public boolean isClearCacheOnRollback()
RowSet.executeQuery
might miss some of the changes.
The value of the Application Module's
isClearCacheOnRollback() flag will be used if the client has not
set this flag in the Transaction.
At the end of transaction, the transaction checks the value of its
isClearCacheOnRollback
flag and either clears the Entity Object caches or not.
However, if the client never called
setClearCacheOnRollback
on this transaction, the framework will use the value for the root
Application Module's definition object.
In contrast, if the client called oracle.jbo.Transaction.setClearCacheOnRollback on the Transaction, then the value of the root Application Module Def's isClearCacheOnRollback is not used.
For middle-tier applications, you can use
isClearCacheOnCommit
and
setClearCacheOnCommit
in the DBTransactionImpl
class.
Note that clearing the Entity Object caches has performance ramifications: repopulating the caches is expensive in terms of time and processing effort.
RowSet.executeQuery()
,
setClearCacheOnRollback(boolean val)
,
DBTransactionImpl.setClearCacheOnRollback(boolean val)
,
DBTransactionImpl.isClearCacheOnRollback()
public void validate()
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.
public void postChanges()
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.
commit()
public boolean isDirty()
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.
true
if the local data and the database differ.public void commit()
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.
TransactionListener.beforeCommit(TransactionEvent)
,
TransactionListener.afterCommit(TransactionEvent)
,
DBTransaction
,
postChanges()
public int commitAndSaveChangeSet()
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 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);
EntityImpl
change set in persistent store.applyChangeSet(int)
,
removeChangeSet(int)
public void applyChangeSet(int id)
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
.
id
- an integer representing the change set to apply to the
transaction.commitAndSaveChangeSet()
,
removeChangeSet(int)
public void removeChangeSet(int id)
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
.
id
- an integer representing the change set to remove from the
persistent store.commitAndSaveChangeSet()
,
applyChangeSet(int)
public void rollback()
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.
DBTransaction
,
TransactionListener.afterRollback(TransactionEvent)
,
TransactionListener.beforeRollback(TransactionEvent)
public void clearEntityCache(java.lang.String entityName)
entityName
- the name of the entity whose cache is to
be cleared. If null
, caches
for all entities are cleared.public int executeCommand(java.lang.String command)
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.
command
- a valid SQL statement.InvalidParamException
- if command
is empty.SQLStmtException
- if command fails.public java.lang.String dumpQueryResult(java.lang.String query, java.lang.String dumpClassName, java.lang.String[] data)
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); }
query
- the SQL query statement.dumpClassName
- the class that dumps the result to a string.data
- an array of data items.public java.lang.Object createRef(java.lang.String structName, byte[] data)
public ConnectionMetadata getConnectionMetadata()
public void setBundledExceptionMode(boolean flag)
public boolean isBundledExceptionMode()
public void addTransactionStateListener(TransactionStateListener target)
public void removeTransactionStateListener(TransactionStateListener target)
|
Business Components | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |