Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle Application Development Framework Model and Business Components Java API Reference 10g Release 3 (10.1.3) B16005-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## oracle.jbo.server
Interface DBTransaction

All Superinterfaces:
  Transaction, oracle.jbo.server.TransactionManager, ValidationManager

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
`DML_OPERATION_TIMEOUT_WAIT_FOREVER, LOCK_NONE, LOCK_OPTIMISTIC, LOCK_OPTUPDATE, 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)` Deprecated.
`void` | `connectToDataSource(javax.sql.DataSource ds, boolean isJTABased)`
`void` | `connectToDataSource(javax.sql.DataSource ds, java.lang.String user, java.lang.String passwd, boolean isJTABased)`
`ApplicationModule` | `createApplicationModule(java.lang.String defName)` Creates an Application Module.
`ApplicationModule` | `createApplicationModule(java.lang.String amName, java.lang.String defName)` Creates an instance of an nested Application Module within this Transaction For example,
`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.
`ApplicationModule` | `findApplicationModule(java.lang.String amName)` Returns the named 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` | `getBatchPostExceptionThreshold()` In case of batch mode post operation, try to post the batched set of entities for each entity type and post operation (Insert/Update/Delete) for this many number of exceptions.
`int` | `getPostThreshold()` Gets the threshold value for the commit-cycle's post phase.
`ApplicationModule` | `getRootApplicationModule()`
`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.
`boolean` | `isConnected(boolean pingDatabase)`
`boolean` | `isLockOptimistic()` Indicates whether the current locking mode is optimistic or not.
`boolean` | `isTrackNewAndModifiedRowsOnly()` Advanced: Most applications should not use this method
`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` | `setBatchPostExceptionThreshold(int count)` Set this value to 0 to let all the modified entities be posted for each entity type and entity-DML operation to collect possible exceptions for all such entities.
`void` | `setPostThreshold(int count)` Sets the threshold value for the commit-cycle's post phase.
`void` | `setTrackNewAndModifiedRowsOnly(boolean flag)` Advanced: Most applications should not use this method
`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
`addTransactionStateListener, addViewClearCacheListener, applyChangeSet, cancelDMLOperations, clearEntityCache, commit, commitAndSaveChangeSet, connect, connect, connect, connectToDataSource, connectToDataSource, connectToDataSource, connectToDataSource, createRef, disconnect, dumpQueryResult, executeCommand, getConnectionMetadata, getDMLOperationTimeOut, getLockingMode, isBundledExceptionMode, isClearCacheOnCommit, isClearCacheOnRollback, isConnected, isDirty, postChanges, reconnect, removeChangeSet, removeTransactionStateListener, removeViewClearCacheListener, rollback, setBundledExceptionMode, setClearCacheOnCommit, setClearCacheOnRollback, setDMLOperationTimeOut, setLockingMode, validate`

Methods inherited from interface oracle.jbo.server.ValidationManager
`addToValidationListeners, validate`

Field Detail

### DEFAULT

    public static final int DEFAULT

  interface constant to inicate that row prefetch should be left as driver default
  See Also:
    Constant Field Values

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)

  Deprecated.
  Internal: Applications should not use this method.
  Since:
    5.0

### connectToDataSource

    public void connectToDataSource(javax.sql.DataSource ds,
                                    boolean isJTABased)

### connectToDataSource

    public void connectToDataSource(javax.sql.DataSource ds,
                                    java.lang.String user,
                                    java.lang.String passwd,
                                    boolean isJTABased)

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

### createApplicationModule

    public ApplicationModule createApplicationModule(java.lang.String amName,
                                                     java.lang.String defName)

  Creates an instance of an nested Application Module within this Transaction For example,

       oracle.jbo.ApplicationModule nestedAM =
       dbtxn.createApplicationModule("subAppMod", "PackageName.AppModuleName");

  This application module can control the namespace of objects that are contained within it.

  Parameters:
    `amName` - the name to be given to the Application Module. If `amName` is empty, a name is generated.
    `defName` - the name of the Application Module definition to be used. If `null` a default definition is used.
  Returns:
    a new Application Module.

### findApplicationModule

    public ApplicationModule findApplicationModule(java.lang.String amName)

  Returns the named Application Module. This method assumes that the Application Module has already been created in this Transaction. The following example returns the Application Module `KpiAM`:

       oracle.jbo.ApplicationModule am = dbTxn.findApplicationModule("KpiAM");

  Parameters:
    `amName` - the name of the Application Module.
  Returns:
    the Application Module.
  Throws:
    `InvalidObjNameException` - if the name cannot be 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.
  Returns:
    the session.
  Throws:
    `java.lang.IllegalStateException` - if the session information cannot be found.

### getSQLBuilder

    public SQLBuilder getSQLBuilder()

### setTrackNewAndModifiedRowsOnly

    public void setTrackNewAndModifiedRowsOnly(boolean flag)

  Advanced: Most applications should not use this method

  Sets this transaction into a mode where this transaction will post/commit only those new entities that have been modified by a setAttribute call. Entities that were created/inserted into collections but never updated by a setAttribute will not be placed in the transaction's list and hence will not get validated, posted or committed.

  This is useful in UIs where the application may create five new rows for display and only update say one or two of them. So only one or two of those rows are added to the transaction. The rest of the entites are in STATUS_INITIALIZED state and are not added to the Entity-cache or Transaction.

### isTrackNewAndModifiedRowsOnly

    public boolean isTrackNewAndModifiedRowsOnly()

  Advanced: Most applications should not use this method

  Returns true if this transaction allows entities to be in STATUS_INITIALIZED state.

### getBatchPostExceptionThreshold

    public int getBatchPostExceptionThreshold()

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

### setBatchPostExceptionThreshold

    public void setBatchPostExceptionThreshold(int count)

  Set this value to 0 to let all the modified entities be posted for each entity type and entity-DML operation to collect possible exceptions for all such entities. Set this number to a postive integer to set a limit on number of exceptions to collect for each entity type and DML operation before aborting the post operation.

### isConnected

    public boolean isConnected(boolean pingDatabase)

### getRootApplicationModule

    public ApplicationModule getRootApplicationModule()

### isLockOptimistic

    public boolean isLockOptimistic()

  Indicates whether the current locking mode is optimistic or not.
  Returns:
    `true` if the locking mode is `LOCK_OPTIMISTIC` or `LOCK_OPTUPDATE`.

Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle Application Development Framework Model and Business Components Java API Reference 10g Release 3 (10.1.3) B16005-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 1997, 2005, Oracle. All rights reserved.