Business Components

oracle.jbo.server
Interface DBTransaction

All Known Implementing Classes:
DBTransactionImpl, NullDBTransactionImpl

public interface DBTransaction
extends Transaction, ValidationManager, oracle.jbo.server.TransactionManager

Interface representing the server side of database connections and transactions.

This interface encapsulates the JDBC connection that is used by the framework to perform database operations.

Since:
JDeveloper 3.0

Field Summary
static int DEFAULT
          interface constant to inicate that row prefetch should be left as driver default
 
Fields inherited from interface oracle.jbo.Transaction
LOCK_NONE, LOCK_OPTIMISTIC, LOCK_PESSIMISTIC
 
Method Summary
 void addTransactionListener(TransactionListener listener)
          Adds a listener to the transaction's list of event subscribers.
 void addTransactionListenerNoCheck(TransactionListener listener)
          Adds a listener to the transaction's event subscribers list, without checking whether the listener is already on the list.
 void addTransactionPostListener(TransactionPostListener listener)
          Adds a listener to the transaction's list of post-phase event subscribers.
 void addTransactionPostListenerNoCheck(TransactionPostListener listener)
          Adds a listener to the transaction's list of post-phase event subscribers, without checking whether the listener is already on the list.
 void addWarning(JboWarning warn)
          Adds a warning to the root Application Module's current list of warnings.
 void closeTransaction()
          Closes this transaction's JDBC connection.
 void connect(java.sql.Connection conn)
          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 instance based on the given defintion.
 EntityImpl createEntityInstance(java.lang.String entityDefName, AttributeList al)
          Creates an EntityImpl instance based on the named defintion.
 java.sql.PreparedStatement createPreparedStatement(java.lang.String str, int noRowsPrefetch)
          Creates a JDBC PreparedStatement instance.
 java.sql.Statement createStatement(int noRowsPrefetch)
          Creates a JDBC Statement instance.
 ViewLink createViewLink(java.lang.String viewLinkDefName, ViewObject master, ViewObject detail)
          Creates a View Link.
 ViewLink createViewLinkBetweenViewObjects(java.lang.String accessorName, ViewObject master, AttributeDef[] srcAttrs, ViewObject detail, AttributeDef[] destAttrs, java.lang.String assocClause)
          Creates a View Link.
 ViewLink createViewLinkFromEntityAssocName(java.lang.String entityAssocName, ViewObject master, ViewObject detail)
          Creates a View Link.
 ViewObject createViewObject(java.lang.String voDefName)
          Creates a ViewObject instance based on the named defintion.
 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 View Object.
 ViewObject createViewObjectFromQueryStmt(java.lang.String sqlStatement)
          Creates a View Object from a SQL statement.
 void disconnect(boolean retainState)
          Closes the JDBC connection object and removes this transaction from the root application module.
 EntityImpl findByPrimaryKey(EntityDefImpl entityDef, Key key)
          Finds an Entity Object in this transaction given a Primary Key.
 EntityImpl findByPrimaryKey(java.lang.String entityDefName, Key key)
          Finds an Entity Object in this transaction given a Primary Key.
 int getPostThreshold()
          Gets the threshold value for the commit-cycle's post phase.
 Session getSession()
          Gets the session information.
 SQLBuilder getSQLBuilder()
           
 TransactionHandler getTransactionHandler()
          Internal: Applications should not use this method.
 int getValidationThreshold()
          Gets the threshold value for the commit-cycle's validation phase.
 void reconnect()
          Reconnect the application module to the database, if necessary, using previously supplied database credentials.
 void removeTransactionListener(TransactionListener listener)
          Removes the listener from the transactions list of event subscribers.
 void removeTransactionPostListener(TransactionPostListener listener)
          Removes a listener from the transaction's list of post-phase event subscribers.
 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.
 
Methods inherited from interface oracle.jbo.Transaction
applyChangeSet, clearEntityCache, commit, commitAndSaveChangeSet, connect, connect, connect, createRef, disconnect, dumpQueryResult, executeCommand, getLockingMode, isClearCacheOnCommit, isClearCacheOnRollback, isConnected, isDirty, postChanges, reconnect, removeChangeSet, rollback, setClearCacheOnCommit, setClearCacheOnRollback, setLockingMode, validate
 
Methods inherited from interface oracle.jbo.server.ValidationManager
addToValidationListeners
 

Field Detail

DEFAULT

public static final int DEFAULT
interface constant to inicate that row prefetch should be left as driver default
Method Detail

closeTransaction

public void closeTransaction()
Closes this transaction's JDBC connection.

Rollback is performed on the current transaction to reset all the data in the cache to their initial state, and then the JDBC connection is dropped.

This method is invoked by ApplicationModule.disconnect(), which should be called so that JDBC resources will be properly released.


setPostThreshold

public void setPostThreshold(int count)
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.

Parameters:
count - the new threshold value.

getPostThreshold

public int getPostThreshold()
Gets the threshold value for the commit-cycle's post phase.

setValidationThreshold

public void setValidationThreshold(int count)
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.

Parameters:
count - the new threshold value.

getValidationThreshold

public int getValidationThreshold()
Gets the threshold value for the commit-cycle's validation phase.

addTransactionListener

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

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

Parameters:
listener - the subscriber to be added.

addTransactionListenerNoCheck

public void addTransactionListenerNoCheck(TransactionListener listener)
Adds a listener to the transaction's event subscribers list, without checking whether the listener is already on the list.

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

Parameters:
listener - the subscriber to be added.

removeTransactionListener

public void removeTransactionListener(TransactionListener listener)
Removes the listener from the transactions list of event subscribers.
Parameters:
listener - the subscriber to be removed.

addTransactionPostListener

public void addTransactionPostListener(TransactionPostListener listener)
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 oracle.jbo.server.TransactionManager
Parameters:
listener - the subscriber to be added.

addTransactionPostListenerNoCheck

public void addTransactionPostListenerNoCheck(TransactionPostListener listener)
Adds a listener to the transaction's list of post-phase event subscribers, without checking whether the listener is already on the list.

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

Specified by:
addTransactionPostListenerNoCheck in interface oracle.jbo.server.TransactionManager
Parameters:
listener - the subscriber to be added.

removeTransactionPostListener

public void removeTransactionPostListener(TransactionPostListener listener)
Removes a listener from the transaction's list of post-phase event subscribers.
Specified by:
removeTransactionPostListener in interface oracle.jbo.server.TransactionManager

createStatement

public java.sql.Statement createStatement(int noRowsPrefetch)
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.

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

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

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.

getTransactionHandler

public TransactionHandler getTransactionHandler()
Internal: Applications should not use this method.

setTransactionHandler

public void setTransactionHandler(TransactionHandler txnHandler)
Internal: Applications should not use this method.

connect

public void connect(java.sql.Connection conn)
Internal: Applications should not use this method.

reconnect

public void reconnect()
Reconnect the application module to the database, if necessary, using previously supplied database credentials.
Specified by:
reconnect in interface Transaction

disconnect

public void disconnect(boolean retainState)
Closes the JDBC connection object and removes this transaction from the root application module. Retains the ApplicationModule state wrt cache as is.

All ViewObjects should have fetched all their data or be in forwardonly mode before this method is invoked with retainState = true

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

Specified by:
disconnect in interface Transaction

createEntityInstance

public EntityImpl createEntityInstance(EntityDefImpl entityDef,
                                       AttributeList al)
Creates an EntityImpl instance based on the given defintion.

Parameters:
entityDef - the defintion to to be used to create the instance.
al - an attribute list to be passed to the new instance's create() method.
Returns:
the new EntityImpl instance.

createEntityInstance

public EntityImpl createEntityInstance(java.lang.String entityDefName,
                                       AttributeList al)
Creates an EntityImpl instance based on the named defintion.

Parameters:
entityDefName - the name of the defintion to to be used to create the instance.
al - an attribute list to be passed to the new instance's create() method.
Returns:
the new EntityImpl instance.

findByPrimaryKey

public EntityImpl findByPrimaryKey(EntityDefImpl entityDef,
                                   Key key)
Finds an Entity Object in this transaction given a Primary Key.
Parameters:
entityDef - 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.

findByPrimaryKey

public EntityImpl findByPrimaryKey(java.lang.String entityDefName,
                                   Key key)
Finds an Entity Object in this transaction given a Primary Key.
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 a ViewObject instance based on the named defintion.

The caller should invoke remove() to dispose of the instance.

Parameters:
voDefName - the name of the defintion to to be used to create the instance.
Returns:
the new ViewObject instance.

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 View Object.

The View Object is constructed from an Entity Object and parts of a SQL statement.

The caller should invoke remove() to dispose of the instance.

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 a View Object from a SQL statement.

The caller should invoke remove() to dispose of the instance.

Parameters:
sqlStatement - a SQL statement.

createApplicationModule

public ApplicationModule createApplicationModule(java.lang.String defName)
Creates an Application Module.

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 a View Link.
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.
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 a View Link.
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)
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.

Parameters:
warn - a warning message.

getSession

public Session getSession()
Gets the session information.

getSQLBuilder

public SQLBuilder getSQLBuilder()

Business Components