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
Class ApplicationModuleImpl

`java.lang.Object
oracle.jbo.common.NamedObjectImpl
oracle.jbo.server.NamedObjectImpl
oracle.jbo.server.ComponentObjectImpl
oracle.jbo.server.ContainerObjectImpl
oracle.jbo.server.ApplicationModuleImpl`

All Implemented Interfaces:
  ApplicationModule, ComponentObject, ContainerObject, java.util.EventListener, Properties, SvcMsgReceiver, SvcMsgSender, TransactionListener, TransPostControl, VariableManagerOwner, WSApplicationModuleMarshaller

public class ApplicationModuleImpl
extends ContainerObjectImpl
implements ApplicationModule, TransPostControl, SvcMsgReceiver, SvcMsgSender, WSApplicationModuleMarshaller, TransactionListener

The base class of Application Modules. An Application Module is a logical container for coordinated objects related to a particular task, with optional programming logic. Application Modules provide a simple runtime data connection model (one connection per Application Module) and a context for defining and executing transactions. The framework provides an `ApplicationPool` interface that clients can use to manage and share a pool of Application Modules. An Application Module provides the following functionality:

- Defines a database session and a transaction boundary.
- Controls concurrent access to data.
- Groups related View Objects into a data model that clients can access in a single network roundtrip.
- Stores application-specific Java code in an object on the middle tier.
- Creates read-only View Objects from SQL statements and clauses.
- Accesses utility methods for testing and debugging.

## Uses of Application Module Instances

Application Module instances are used during the lifetime of an application to obtain a reference to the application's transaction context `getTransaction`, to obtain references to application View Objects `getViewObjects`, and to invoke custom application methods. For more information about custom application methods please see Extending the Application Module Implementation which describes extending the default Application Module implementation.

## Root Application Modules

Root Application Modules are instantiated by the Business Components for Java framework when an application invokes `create()` on the Application Module's home, `ApplicationModuleHome`. Nested Application Modules may be instantiated by the Business Components for Java framework when its parent application module is instantiated (static nesting) or when an application invokes `createApplicationModule` on an existing Application Module instance (dynamic nesting). Please see Nesting Application Modules for more information about nested Application Modules.

## Extending the Application Module Implementation

Application developers can extend this class to meet their own requirements. Extending the default Application Module implementation might be necessary to define custom application logic that must execute in the application's middle tier. For example, a human resources application might require that the salary total for employees is recalculated every time an employee is created. In this case, the default implementation can be extended with a method, `createEmployee`, that creates a new row in the contained Employees View Object and then re-computes the salary of the existing employees. In addition to encapsulating application logic, this design will often offer substantial performance benefits in the form of reduced network roundtrips.

Customers can use the Application Module wizard to declare custom Application Module implemenations to the BC4J framework.

## Nesting Application Modules

Application Modules can be nested. That is, an Application Module can (logically) contain one or more other Application Modules as well as View Objects. The outermost containing Application Module is referred to as the "root" Application Module. A nested Application Module cannot see the instances of any other Application Modules that might be nested beneath the same root.

### Nested Application Modules and Transactions

Nested Application Modules share the same transaction, `DBTransactionImpl`. The root Application Module provides the transaction context for its contained Application Modules. A nested Application Module design is useful for applications that define several functional sub-applications that share the same transaction context and transaction caches. With a nested Application Module design, it is easy to re-deploy nested Application Modules as standalone Application Modules in different client applications without having to modify the metadata for the other existing Application Modules.

Since:
  JDevloper 3.0
See Also:
  `ApplicationPool`

Field Summary
`static java.lang.String` | `DEFAULT_DEF_NAME` Default Def name for Application Module.

Fields inherited from class oracle.jbo.server.ContainerObjectImpl
`mComponentList, mComponents`

Fields inherited from class oracle.jbo.common.NamedObjectImpl
`mFullName, mObjName, mParent, mProperties`

Fields inherited from interface oracle.jbo.ApplicationModule
`ACTIVATE_CLIENT_FLAG, ACTIVATE_REMOVE_FLAG, ACTIVATE_SKIP_RESTORE_VO_FROM_DEF, ACTIVATE_TRANSIENT_FLAG, ACTIVATE_UNDO_FLAG, DEFAULT_DEF_FULL_NAME, DEFAULT_ROOT_APP_MOD_NAME, PASSIVATE_DEFER_FLAG, PASSIVATE_HINT_FLAG, PASSIVATE_TO_DATABASE, PASSIVATE_TO_FILE, PASSIVATE_TO_MEMORY, PASSIVATE_TO_STACK_FLAG, PASSIVATE_TRANSIENT_FLAG, PASSIVATE_UNDO_FLAG, RELEASE_LEVEL_MANAGED, RELEASE_LEVEL_RESERVED, REMOVE_SNAPSHOT, RESET_CLIENT_ONLY_FLAG, RESET_INTERNAL_FLAG, RESET_MANAGE_SNAPSHOTS, RESET_RELOAD_FLAG, RESET_ROLLBACK_FLAG, SYNC_BATCH, SYNC_IMMEDIATE, SYNC_LAZY`

Fields inherited from interface oracle.jbo.common.TransPostControl
`TRANS_POST_GET_ATTR_BY_INDEX, TRANS_POST_GET_ATTR_BY_NAME, TRANS_POST_GET_ATTR_COUNT, TRANS_POST_GET_ATTR_INDEX_OF, TRANS_POST_GET_STRUCTURE_DEF, TRANS_POST_PUSHBACK, TRANS_POST_REFRESH_UNDO_CHANGES, TRANS_POST_REFRESH_WITH_DB_FORGET_CHANGES, TRANS_POST_REFRESH_WITH_DB_ONLY_IF_UNCHANGED, TRANS_POST_REMOVE, TRANS_POST_SET_ATTR_BY_INDEX, TRANS_POST_SET_ATTR_BY_NAME`

Fields inherited from interface oracle.jbo.common.ws.WSApplicationModuleMarshaller
`ACTIVATION_AFTER_LOSS_OF_AFFINITY, ACTIVATION_AFTER_RESTART, ACTIVATION_NONE, SYNC_INT_BATCH, SYNC_INT_BATCH_DO_WORK`

Constructor Summary
`protected` | `ApplicationModuleImpl()` constructs a new Application Module.

Method Summary
`protected void` | `activate(Session session)` Called by the framework when a root Application Module is created.
`protected void` | `activateConnectionState(Element parent)` Allow subclasses to retrieve custom data associated with connection state.
`void` | `activateOpenVOs(XMLDocument out)` Internal: Applications should not call this method.
`protected void` | `activateState(Element parent)` Allows subclasses to retrieve custom data from an XML-node under the given parent element.
`byte[]` | `activateState(int id, boolean remove)`
`byte[]` | `activateState(int id, boolean remove, SessionData info)`
`byte[]` | `activateState(int id, SessionData info, int flags)` Internal: Applications should not use this method.
`byte[]` | `activateStateForUndo(java.lang.String id, int flags)` Restore an application module undo record.
`protected void` | `addChild(ComponentObjectImpl object)` Internal: Applications should not use this method.
`void` | `addResponse(java.io.Serializable resp)`
`void` | `addWarning(JboWarning warn)` Specifies the name of the handler that will perform special processing of warnings on the client.
`void` | `afterActivation(int activationMode)`
`void` | `afterCommit(TransactionEvent e)` Called to report that a Commit operation has occurred.
`protected void` | `afterConnect()` Invoked after the application module database connection has been established.
`void` | `afterRemove(TransactionEvent e)` A cleanup routine to be invoked by transaction manager when this transaction listener is removed from the manager's list.
`void` | `afterRollback(TransactionEvent e)` Called to report that a Rollback operation has occurred.
`void` | `beforeCommit(TransactionEvent e)` Called to report that a Commit operation is imminent.
`protected void` | `beforeDisconnect()` Invoked before the application module database connection has been released.
`void` | `beforeRollback(TransactionEvent e)` Called to report that a Rollback operation is imminent.
`void` | `bindToWorkingSet(WSApplicationModuleImpl wsam)`
`void` | `clearVOCaches(java.lang.String entityName, boolean recurse)` Clears the caches of all View Objects that use the specified entity.
`ApplicationModule` | `createApplicationModule(java.lang.String amName, java.lang.String defName)` Creates an instance of an Application Module within this Application Module; that is, a nested Application Module.
`ComponentObject` | `createComponentObject(java.lang.String coName, java.lang.String comDefName)` Creates a Component object in the context of this Application Module.
`static ApplicationModuleImpl` | `createRootApplicationModule(java.lang.String applicationModuleDefName, Session sess)` Internal: Applications should not call this method.
`static void` | `createSharedDataHandle()` Internal: Applications should not call this method.
`ViewLink` | `createViewLink(java.lang.String viewLinkName, java.lang.String viewLinkDefName, ViewObject master, ViewObject detail)` Creates a View Link, given the View Link name, the Def name, and the names of the master and detail View Objects.
`ViewLink` | `createViewLinkBetweenViewObjects(java.lang.String viewLinkName, java.lang.String accessorName, ViewObject master, AttributeDef[] srcAttrs, ViewObject detail, AttributeDef[] destAttrs, java.lang.String assocClause)` Creates a View Link given either a View Link Definition or an Entity Association.
`ViewLink` | `createViewLinkFromEntityAssocName(java.lang.String viewLinkName, java.lang.String entityAssocName, ViewObject master, ViewObject detail)` Creates a View Link, given the View Objects and an Entity Association.
`ViewObject` | `createViewObject(java.lang.String voName, java.lang.String vDefName)` Creates an updateable View Object.
`protected ViewObject` | `createViewObject(java.lang.String voName, ViewDefImpl viewDef)`
`ViewObject` | `createViewObjectFromQueryClauses(java.lang.String voName, java.lang.String eoName, java.lang.String selectClause, java.lang.String fromClause, java.lang.String whereClause, java.lang.String orderByClause)` Creates an updateable View Object.
`ViewObject` | `createViewObjectFromQueryStmt(java.lang.String voName, java.lang.String query)` Creates a read-only View Object, given a query statement and a name for the View Object.
`ViewObject` | `createViewObjectOnEntity(java.lang.String voName, java.lang.String eoName)`
`ViewObject` | `createViewObjectOnRowSet(java.lang.String voName, RowSet rs)`
`ApplicationModule` | `createWorkerApplicationModule(java.lang.Object sessionCookie)`
`static void` | `createXMLSharedDataHandle()` Deprecated. This method was to be used in conjunction with Java-in-the-database configuration which is no longer supported.
`void` | `detach()` Internal: Applications should not use this method.
`ServiceMessage` | `doMessage(ServiceMessage msg)` Processes a service message sent by `SvcMsgSender`.
`ApplicationPoolSvcMsgContext` | `doPoolMessage(ApplicationPoolSvcMsgContext ctx)` Internal use only.
`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)` Specifies a valid SQL statement to be executed by the server.
`void` | `fetchAttributeProperties(java.lang.String[] voNames, java.lang.String[][] attrs, LocaleContext locale)` Fetches all custom properties for the given list of attributes for the named view objects in this application module over to the remote client objects in one network roundtrip.
`ApplicationModule` | `findApplicationModule(java.lang.String amName)` Finds the named Application Module.
`ComponentObject` | `findComponentObject(java.lang.String compName)` Finds the component object from the Application Module.
`java.lang.Object` | `findObject(java.lang.String name)`
`java.lang.Object` | `findObject(java.lang.String name, java.lang.Class type)`
`RowSetIterator` | `findRSIForEntity(RowSetIterator[] rsis, int eRowHandle)` Finds the RowSetIterator associated with the specified row handle.
`ViewLink` | `findViewLink(java.lang.String vlName)` Finds the named View Link.
`ViewObject` | `findViewObject(java.lang.String voName)` Finds the named View Object.
`ViewObject` | `findViewObjectUsingEntity(ViewObject[] vos, java.lang.String eoName, java.lang.String[] attrNames)` Given an array of view objects (the `vos` parameter), finds the first matching view object.
`ViewObject` | `findViewObjectWithParameters(java.lang.String voName, VariableManager params, boolean executeIfNeeded)` Given a ViewObject name, use findViewObject(String name) to find the ViewObject and set it's named bind parameters with the values passed in the 'params' argument.
`void` | `findVOsWithEntityUsage(java.lang.String entityName, boolean recurse, com.sun.java.util.collections.ArrayList vos)` Finds the View Objects that use the specified entity.
`void` | `findVOsWithEntityUsage(java.lang.String entityName, boolean recurse, java.util.Vector vos)`
`void` | `finishLoadingComponents(boolean recurse)`
`void` | `finishSyncWorkingSet(WSApplicationModuleImpl wsAM, boolean isEndOfSvcMsg)`
`ApplicationModuleDefImpl` | `getApplicationModuleDef()` Returns the Def (definition) associated with this Application Module.
`ApplicationModuleImpl[]` | `getApplicationModuleImpls()` Internal: Applications should not use this method.
`java.lang.String[]` | `getApplicationModuleNames()` Returns an array of names of the nested Application Modules that are currently loaded within this Application Module.
`java.lang.String[]` | `getApplicationModuleNames(boolean inclLoadedOnes, boolean inclNotLoadedOnes)` Returns an array of names of the nested Application Modules in this Application Module.
`AppModuleRequestHandler` | `getAppModuleRequestHandler()`
`static AttributeDefValue[]` | `getAttributeDefs(StructureDef def)`
`static AttributeDefValue[]` | `getAttributeDefsForVO(ViewObject vo)`
`java.lang.String` | `getClientProxyClassName()` Internal: Applications should not use this method.
`java.lang.String` | `getClientProxyClassName(java.lang.String serverType)` Deprecated. Platform specific proxies not required. Use getClientProxyClassName() instead.
`java.lang.String` | `getClientProxyInterfaceName()`
`WSApplicationModuleImpl` | `getCurrentWorkingSet()`
`DBTransaction` | `getDBTransaction()` Gets this Application Module's database transaction.
`java.lang.String` | `getDefFullName()` Returns the fully-qualified (that is, package-qualified) name of this Application Module's Def (definition) object.
`java.lang.String` | `getDefName()` Returns the name of this Application Module's Def (definition) object.
`byte[]` | `getEntityAttributesPermission(java.lang.String entityName)` Returns the current authenticated user permission for entity attributes.
`Row` | `getEntityRowFromHandle(int eRowHandle)` Internal: Applications should not use this method.
`JboExceptionHandler` | `getExceptionHandler()`
`int` | `getMostRecentStackId()` Internal: Applications should not use this method.
`ObjectMarshaller` | `getObjectMarshaller()`
`int` | `getReleaseLevel()` Returns the release level that should be employed by clients of this application module.
`int` | `getRemoteObjectId(java.lang.Object obj)`
`java.lang.String` | `getResponseName()`
`Session` | `getSession()` Returns the session information.
`ClientDocument` | `getStyles(java.lang.String name)` Gets the Application Module's style definitions from the middle tier.
`java.lang.Object` | `getSyncLock()` Gets the locking object for this application module.
`int` | `getSyncMode()` Returns the sync mode for this Application Module.
`Transaction` | `getTransaction()` Returns the transaction information.
`java.lang.String` | `getUserPrincipalName()` Returns the session user principal name.
`byte[]` | `getViewAttributesPermission(ViewObject vo)` Returns the current authenticated user permission for view attributes.
`java.lang.String[]` | `getViewLinkNames()` Returns an array of the names of the View Links that are currently loaded within this Application Module.
`java.lang.String[]` | `getViewLinkNames(boolean inclLoadedOnes, boolean inclNotLoadedOnes)` Returns an array of names of the View Links in this Application Module.
`ViewLinkImpl[]` | `getViewLinks()` Returns an array of the View Links contained in this Application Module.
`java.lang.String[]` | `getViewObjectNames()` Returns an array of names of the View Objects that are currently loaded within this Application Module.
`java.lang.String[]` | `getViewObjectNames(boolean inclLoadedOnes, boolean inclNotLoadedOnes)` Returns an array of names of the View Objects in this Application Module.
`ViewObject[]` | `getViewObjects()` Constructs an array of this Application Module's View Objects.
`WSApplicationModuleMarshaller` | `getWorkingSetMarshaller()` Internal: Applications should not use this method.
`protected void` | `handleDefinitionChangedOnActivate(java.lang.Object activatedTS)` Allows subclasses to abort activation, when the metadata for the component objects has changed and an attempt is made to activate an Application Module which was saved with an older version of the metadata.
`boolean` | `hasPendingDataPosts()`
`java.lang.Object` | `invokeMethod(java.lang.Object target, java.lang.String methodName, java.lang.String[] argTypeNames, java.lang.Object[] args)`
`boolean` | `isLoadComponentsLazily()`
`boolean` | `isNameGenerated()` Tests if the Application Module's name was generated by the system.
`boolean` | `isRoot()` Determines if this is the root Application Module.
`boolean` | `isTransientTransactionListener()` Tests whether this transaction listener is transient or permanent.
`boolean` | `isValidIdForUndo(java.lang.String id)` Determines if an id created using `passivateStateForUndo(String, byte[], int)` is still valid.
`static void` | `launchTester(java.lang.String packageName, java.lang.String configName)`
`java.lang.Object` | `marshal(java.lang.Object obj)`
`java.lang.Object` | `marshalForActivate(java.lang.Object obj)`
`protected void` | `passivateConnectionState(Document doc, Element parent)` Allows subclasses to store custom data associated with connection state.
`XMLDocument` | `passivateOpenVOs(boolean close)` Internal: Applications should not call this method.
`int` | `passivateState(byte[] clientData)`
`int` | `passivateState(byte[] clientData, int flags)` Internal: Applications should not use this method.
`protected void` | `passivateState(Document doc, Element parent)` Allows subclasses to store custom data as XML-nodes under the given parent element, in the given document.
`int` | `passivateState(int id, byte[] clientData)` Internal: Applications should not user this method.
`int` | `passivateState(int id, byte[] clientData, int flags)` Internal: Applications should not use this method.
`java.lang.String` | `passivateStateForUndo(java.lang.String id, byte[] clientData, int flags)` Create an application module undo record.
`protected void` | `prepareForActivation(Element amNode)` Override this method to activate custom data in the ApplicationModule from this AM's xml node.
`protected void` | `prepareForPassivation(Document out, Element parent)` Override this method to passivate custom data in the ApplicationModule.
`protected void` | `prepareSession(Session session)` Prepares the ApplicationModule session.
`void` | `prepareSession(SessionData info)` Internal: Applications should not use this method.
`void` | `remove()` Deletes this Application Module.
`protected void` | `removeChild(ComponentObjectImpl object)` Internal: Applications should not use this method.
`void` | `removeState(int id)` Internal: Applications should not use this method.
`int` | `reservePassivationId()` Internal: Applications should not user this method.
`int` | `reserveSnapshotId(int flags)` Internal: Applications should not use this method.
`protected void` | `reset()` BC4J invokes this method when a ApplicationModule is being reset for potential reuse by another client session.
`void` | `resetState(boolean reload)`
`void` | `resetState(int flags)` Advanced use only
`ServiceMessage` | `sendServiceMessage(ServiceMessage svcMsgIn)` Sends a service message to `SvcMsgReceiver`.
`ServiceMessage` | `sendWorkingSetRequests(java.lang.String reqName, WSApplicationModuleImpl wsAM, ServiceMessage msg)`
`void` | `setBoundToWorkingSet(boolean b)`
`void` | `setDataModelRefresh(boolean b)`
`void` | `setExceptionHandler(JboExceptionHandler hndlr)` Specifies the name of the handler which will perform special processing of the exceptions on the client.
`void` | `setLoadComponentsLazily(boolean isLoadComponentsLazily)`
`void` | `setReleaseLevel(int releaseLevel)`
`void` | `setRemoteAdapter(ApplicationModuleRemoteAdapter adapter)`
`void` | `setStoreForPassiveState(byte storageType)` Internal: Applications should not use this method.
`void` | `setStyles(java.lang.String name, ClientDocument clientDocument)` Saves the Application Module's style definitions to the middle tier.
`void` | `setSyncMode(int mode)` Sets the data synchronization mode between the client and the middle tier.
`void` | `setWorkingSetMarshaller(WSApplicationModuleMarshaller marshaller)` Internal: Applications should not use this method.
`void` | `sync()` Synchronizes all the result sets defined in this Application Module in the client with the application tier.
`void` | `syncMarshaller(ServiceMessage msg)`
`void` | `syncWorkingSet(WSApplicationModuleImpl wsAM)` Internal: Applications should not use this method.
`java.lang.Object[]` | `transformExceptionParams(ViewObject[] inVOs, java.lang.String entityDefName, java.lang.String className, java.lang.Object[] params)` Internal: Applications should not use this method. This method uses findViewObjectUsingEntity() to get the first view object that this entity is used in and then transforms the parameters from a given JboException from their entity layer equivalents to the view object equivalents.
`protected java.lang.Object[]` | `transformExceptionParams(ViewObject vo, java.lang.String entityDefName, java.lang.String className, java.lang.Object[] params)` Internal: Applications should not call this method.
`java.lang.Object` | `transPostGetAttr(int op, int hdl, int index, java.lang.String name)` Internal: Applications should not use this method.
`void` | `transPostPushback(int hdl)` Internal: Applications should not use this method.
`void` | `transPostRefresh(int refreshMode, int hdl)`
`void` | `transPostRemove(int hdl)` Internal: Applications should not use this method.
`void` | `transPostRevert(int hdl)` Internal: Applications should not use this method.
`void` | `transPostRowOp(int op, int hdl)` Internal: Applications should not use this method.
`void` | `transPostSetAttr(int op, int hdl, int index, java.lang.String name, java.lang.Object value)` Internal: Applications should not use this method.

Methods inherited from class oracle.jbo.server.ContainerObjectImpl
`addContainerListener, removeContainerListener`

Methods inherited from class oracle.jbo.server.ComponentObjectImpl
`addListener, create, createRef, ensureVariableManager, getApplicationModule, getCompListeners, getCompListenersList, getMessageBundleClass, getProxyClassName, getProxyClassName, getRootApplicationModule, getVariableManager, hasVariables, isDead, isRegWithPiggyMan, setName, setParent, setProxyClassName`

Methods inherited from class oracle.jbo.server.NamedObjectImpl
`setParent, setPropertiesMap`

Methods inherited from class oracle.jbo.common.NamedObjectImpl
`getFullName, getName, getParent, getProperties, getPropertiesAsStrings, getPropertiesMap, getProperty, refreshProperty, setFullName, setProperty`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface oracle.jbo.ComponentObject
`getFullName, getName`

Methods inherited from interface oracle.jbo.Properties
`getProperties, getProperty, refreshProperty`

Methods inherited from interface oracle.jbo.VariableManagerOwner
`getName`

Field Detail

### DEFAULT_DEF_NAME

    public static final java.lang.String DEFAULT_DEF_NAME

  Default Def name for Application Module.

Constructor Detail

### ApplicationModuleImpl

    protected ApplicationModuleImpl()

  constructs a new Application Module.

Method Detail

### getSyncLock

    public final java.lang.Object getSyncLock()

  Description copied from interface: `ApplicationModule`
  Gets the locking object for this application module. Note that if this method is invoked on a nested application module, the root application module's locking object is returned. This is because the locking object is shared by all application modules contained by the root application module.

  This locking object should be used to synchronize multiple calls into BC4J. The client application code rarely needs to worry about synchronization. It is the middle tier (the server) code that needs to synchronize calls into the middle tier to serialize updates to shared middle tier objects.

  Here is an example of how to synchronize access using this method:

          synchronized(am.getSyncLock())
          {
             // Code that needs to execute serially.
          }

  Specified by:
    `getSyncLock` in interface `ApplicationModule`
  Returns:
    the locking object.

### createRootApplicationModule

    public static ApplicationModuleImpl createRootApplicationModule(java.lang.String applicationModuleDefName,
                                                                    Session sess)

  Internal: Applications should not call this method.

  A factory method for creating a root Application Module.

  Parameters:
    `applicationModuleDefName` - the name of an Application Module definition.
    `sess` - the session.

### createSharedDataHandle

    public static void createSharedDataHandle()

  Internal: Applications should not call this method.

  Call this function to register a shared data handle with the `MetaObjectManager` and use it later.

### createXMLSharedDataHandle

    public static void createXMLSharedDataHandle()

  Deprecated. This method was to be used in conjunction with Java-in-the-database configuration which is no longer supported.
  Call this function to register a shared data handle with `MetaObjectManager` and use it later.

### activate

    protected void activate(Session session)
                     throws java.lang.IllegalStateException

  Called by the framework when a root Application Module is created. Unlike the `create` method which is called even when nested Application Modules are created, this method is called only for the root Application Module.

  Subclasses can override this method to perform customizations. For example, it can be overriden to initialize connection pools. Another example is to override `activate` to automatically create a connection in the middle tier when the root Application Module is created.

  If this method is overriden, then subclasses must call the super class first in the custom implementation.

  Please take special note that this method will only be called once when the root ApplicationModule is created. Subclasses should extend `prepareSession(Session)` to initialize true session state.

  Parameters:
    `session` - the session in which the root Application Module is created.
  Throws:
    `java.lang.IllegalStateException`
  See Also:
    `prepareSession(oracle.jbo.Session)`

### isLoadComponentsLazily

    public boolean isLoadComponentsLazily()

### setLoadComponentsLazily

    public void setLoadComponentsLazily(boolean isLoadComponentsLazily)

### finishLoadingComponents

    public void finishLoadingComponents(boolean recurse)

### getApplicationModuleDef

    public ApplicationModuleDefImpl getApplicationModuleDef()

  Returns the Def (definition) associated with this Application Module. The Def contains all of the metadata belonging to the Application Module. The Def name is the name of the Def object for the Application Module. Typically, this will have the format Packagename.AppModuleName in the XML file.

  This method should not be overridden.

  Returns:
    the Def associated with this Application Module.

### isRoot

    public boolean isRoot()

  Determines if this is the root Application Module. For example, if your code is traversing through the Application Module instances use this method to test for the root Application Module instance.
  Specified by:
    `isRoot` in interface `ApplicationModule`
  Returns:
    `true` if this is the root; `false` otherwise.

### addChild

    protected void addChild(ComponentObjectImpl object)

  Internal: Applications should not use this method.

  Adds names to this Application Module's own list of child components. The child components can be View Objects, View Links, or other Application Modules. This method overrides an internal `addChild` method in `NamedObjectImpl`.

  Parameters:
    `object` - an object to add to the component list.
  See Also:
    `NamedObjectImpl`

### removeChild

    protected void removeChild(ComponentObjectImpl object)

  Internal: Applications should not use this method.

  Removes names from this Application Module's own list of child components. The child components can be View Objects, View Links, or other Application Modules. This method overrides an internal `removeChild` method in `NamedObjectImpl`.

  Parameters:
    `object` - an object to remove from the component list.
  See Also:
    `NamedObjectImpl`

### getDefName

    public java.lang.String getDefName()

  Returns the name of this Application Module's Def (definition) object. Typically, this will have the format AppModuleName in the XML file. For example, use this method to find the Def name of the Application Module, then use it to create an instance of this Application Module in another location.
  Specified by:
    `getDefName` in interface `ComponentObject`
  Overrides:
    `getDefName` in class `ComponentObjectImpl`
  Returns:
    the name of this Application Module's Def object.

### getDefFullName

    public java.lang.String getDefFullName()

  Returns the fully-qualified (that is, package-qualified) name of this Application Module's Def (definition) object. Typically, this will have the format Packagename.AppModuleName in the XML file.
  Specified by:
    `getDefFullName` in interface `ComponentObject`
  Overrides:
    `getDefFullName` in class `ComponentObjectImpl`
  Returns:
    a fully-qualified name. The name typically has the format packageName.appModuleName

### createApplicationModule

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

  Creates an instance of an Application Module within this Application Module; that is, a nested Application Module. For example,

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

  You can override this method to also create View Objects within the "scope" of the Application Module, and make it available to other code. In this case, the code in the Application Module can make assumptions about what View Objects are available and contain code for customizing the View Objects. It can control the namespace of objects that are contained within it.

  Specified by:
    `createApplicationModule` in interface `ApplicationModule`
  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.

### findObject

    public java.lang.Object findObject(java.lang.String name)

### findObject

    public java.lang.Object findObject(java.lang.String name,
                                       java.lang.Class type)

### findApplicationModule

    public ApplicationModule findApplicationModule(java.lang.String amName)

  Finds the named Application Module. The Application Module name passed in (`amName`) may be a single part name or a multi-part name. If it is multi-part (separated by dots), each part from left represents the containing (parent) Application Module.

  Based on the name, `findApplicationModule` first tries to find the nested Application Module starting with this Application Module. If it finds a match, it returns it. In this case, the name is said to be relative.

  If it does not find a match, it starts searching for the Application Module from the root Application Module. If it finds a match, it returns it. In this case, the name is said to be absolute.

  For example, suppose we have the following containership of nested Application Modules:

          Root (root Application Module)
             ChildAM1
                GrandChildAM1_1
                GrandChildAM1_2
                   GreatGrandChildAM1_2_1
             ChildAM2
                GrandChildAM2_1

  If one calls `findApplicationModule("GrandChildAM1_2")` on `ChildAM1`, it will find it from `ChildAM1` and return it.

  If one calls `findApplicationModule("GrandChildAM1_2.GreatGrandChildAM1_2_1")` on `ChildAM1`, it will find it from `ChildAM1` and return it.

  Both these are relative name cases.

  If one calls `findApplicationModule("Root.ChildAM2.GrandChildAM2_1")` on `ChildAM1`, it will first try to find it from `ChildAM1`. This will fail because `ChildAM1` does not have a nested Application Module named `Root`. After that, the search begins from the root Application Module. This will succeed because `Root` has a nested Application Module named `ChildAM2` and `ChildAM2` in turn has a nested nested Application Module named `GrandChildAM2_1`. This is an absolute name case.

  For Application Module searching, `findApplicationModule()` makes no distinction between nested Application Modules included in other Application Modules during design time and those created programmatically during runtime.

  Example code:

          ApplicationModule nestedAM = parentAM.findApplicationModule("MyNestedAM");

  Specified by:
    `findApplicationModule` in interface `ApplicationModule`
  Parameters:
    `amName` - the name of the nested Application Module. It may be a relative name or an absolute name. If `null`, the root Application Module is returned.
  Returns:
    the nested Application Module. `null` if the Application Module is not found.
  Throws:
    `InvalidObjNameException` - if `amName` is an invalid name. `amName` must be a vaild Java name.

### getApplicationModuleNames

    public java.lang.String[] getApplicationModuleNames()

  Returns an array of names of the nested Application Modules that are currently loaded within this Application Module.

  Example code:

          String[] nestedAMNames = parentAM.getApplicationModuleNames();

          // If you want to retrieve all currently loaded nested Application Modules
          ApplicationModule[] nestedAMs = new ApplicationModule[nestedAMNames.length];

          for (int i = 0; i < nestedAMNames.length; i++)
          {
             nestedAM[i] = parentAM.findApplicationModule(nestedAMNames[i]);
          }

  If you need names of Application Modules that are not yet loaded, use ``getApplicationModuleNames(boolean, boolean)``.

  Specified by:
    `getApplicationModuleNames` in interface `ApplicationModule`
  Returns:
    an array of nested Application Module names. If this Application Module contains no nested Application Module, it returns an empty array, i.e., `new String[0]`.
  See Also:
    `findApplicationModule(String)`

### getApplicationModuleNames

    public java.lang.String[] getApplicationModuleNames(boolean inclLoadedOnes,
                                                        boolean inclNotLoadedOnes)

  Returns an array of names of the nested Application Modules in this Application Module.

  This method allows the user to control whether the returning names are those of loaded (instantiated) nested Application Modules, or those of not yet loaded (uninstantiated) nested ApplicationModules, or both. Not yet loaded Application Modules would appear only if lazy loading is turned on.

  Note that ``getApplicationModuleNames()`` is equivalent to `getApplicationModuleNames(true, false)`.

  Specified by:
    `getApplicationModuleNames` in interface `ApplicationModule`
  Parameters:
    `inclLoadedOnes` - if `true`, only loaded ones are returned.
    `inclNotLoadedOnes` - if `true`, only those that are not yet loaded are returned.
  Returns:
    an array of nested Application Module names. If this Application Module contains no nested Application Module, it returns an empty array, i.e., `new String[0]`.

### transPostPushback

    public void transPostPushback(int hdl)

  Internal: Applications should not use this method.
  Specified by:
    `transPostPushback` in interface `TransPostControl`

### transPostRemove

    public void transPostRemove(int hdl)

  Internal: Applications should not use this method.
  Specified by:
    `transPostRemove` in interface `TransPostControl`

### transPostRevert

    public void transPostRevert(int hdl)

  Internal: Applications should not use this method.
  Specified by:
    `transPostRevert` in interface `TransPostControl`

### transPostRefresh

    public void transPostRefresh(int refreshMode,
                                 int hdl)

  Specified by:
    `transPostRefresh` in interface `TransPostControl`

### transPostRowOp

    public void transPostRowOp(int op,
                               int hdl)

  Internal: Applications should not use this method.

### transPostGetAttr

    public java.lang.Object transPostGetAttr(int op,
                                             int hdl,
                                             int index,
                                             java.lang.String name)

  Internal: Applications should not use this method.

### transPostSetAttr

    public void transPostSetAttr(int op,
                                 int hdl,
                                 int index,
                                 java.lang.String name,
                                 java.lang.Object value)

  Internal: Applications should not use this method.

### getEntityRowFromHandle

    public Row getEntityRowFromHandle(int eRowHandle)

  Internal: Applications should not use this method.

### sync

    public void sync()

  Synchronizes all the result sets defined in this Application Module in the client with the application tier. As a side result of calling this method, validations on the data will be performed.
  Specified by:
    `sync` in interface `ApplicationModule`

### setBoundToWorkingSet

    public void setBoundToWorkingSet(boolean b)

  Specified by:
    `setBoundToWorkingSet` in interface `WSApplicationModuleMarshaller`

### setSyncMode

    public void setSyncMode(int mode)

  Sets the data synchronization mode between the client and the middle tier. There are two sync modes: `ApplicationModule.SYNC_LAZY` and `ApplicationModule.SYNC_IMMEDIATE`.

  `SYNC_LAZY` is typically more efficient in that it causes fewer round trips to the middle tier.

  Note that the sync mode is an attribute of the root Application Module. If one calls `getSyncMode` or `setSyncMode` on a nested Application Module, it is routed to the root Application Module. Also, note that pending changes are managed at the root Application Module. When the changes are flushed from the client to the middle tier, all changes pending under the root Application Module are flushed.

  Specified by:
    `setSyncMode` in interface `ApplicationModule`
  Parameters:
    `mode` - the new synchronization mode: `SYNC_LAZY` or `SYNC_IMMEDIATE`.
  See Also:
    `getSyncMode()`, `ApplicationModule.SYNC_LAZY`, `ApplicationModule.SYNC_IMMEDIATE`

### setWorkingSetMarshaller

    public void setWorkingSetMarshaller(WSApplicationModuleMarshaller marshaller)

  Internal: Applications should not use this method.
  Parameters:
    `marshaller` - Working Set AM marshaller

### getWorkingSetMarshaller

    public WSApplicationModuleMarshaller getWorkingSetMarshaller()

  Internal: Applications should not use this method.

### detach

    public void detach()

  Internal: Applications should not use this method.
  Specified by:
    `detach` in interface `WSApplicationModuleMarshaller`

### afterActivation

    public void afterActivation(int activationMode)

  Specified by:
    `afterActivation` in interface `WSApplicationModuleMarshaller`

### bindToWorkingSet

    public void bindToWorkingSet(WSApplicationModuleImpl wsam)

  Specified by:
    `bindToWorkingSet` in interface `WSApplicationModuleMarshaller`

### getCurrentWorkingSet

    public WSApplicationModuleImpl getCurrentWorkingSet()

  Specified by:
    `getCurrentWorkingSet` in interface `WSApplicationModuleMarshaller`

### hasPendingDataPosts

    public boolean hasPendingDataPosts()

  Specified by:
    `hasPendingDataPosts` in interface `WSApplicationModuleMarshaller`

### createWorkerApplicationModule

    public ApplicationModule createWorkerApplicationModule(java.lang.Object sessionCookie)

  Specified by:
    `createWorkerApplicationModule` in interface `WSApplicationModuleMarshaller`

### getAppModuleRequestHandler

    public AppModuleRequestHandler getAppModuleRequestHandler()

  Specified by:
    `getAppModuleRequestHandler` in interface `WSApplicationModuleMarshaller`

### syncWorkingSet

    public void syncWorkingSet(WSApplicationModuleImpl wsAM)

  Internal: Applications should not use this method.
  Specified by:
    `syncWorkingSet` in interface `WSApplicationModuleMarshaller`
  Parameters:
    `wsAM` - Working Set AM

### finishSyncWorkingSet

    public void finishSyncWorkingSet(WSApplicationModuleImpl wsAM,
                                     boolean isEndOfSvcMsg)

  Specified by:
    `finishSyncWorkingSet` in interface `WSApplicationModuleMarshaller`

### sendWorkingSetRequests

    public ServiceMessage sendWorkingSetRequests(java.lang.String reqName,
                                                 WSApplicationModuleImpl wsAM,
                                                 ServiceMessage msg)

  Specified by:
    `sendWorkingSetRequests` in interface `WSApplicationModuleMarshaller`

### getResponseName

    public java.lang.String getResponseName()

  Specified by:
    `getResponseName` in interface `WSApplicationModuleMarshaller`

### getRemoteObjectId

    public int getRemoteObjectId(java.lang.Object obj)

  Specified by:
    `getRemoteObjectId` in interface `WSApplicationModuleMarshaller`

### marshal

    public java.lang.Object marshal(java.lang.Object obj)

  Specified by:
    `marshal` in interface `WSApplicationModuleMarshaller`

### marshalForActivate

    public java.lang.Object marshalForActivate(java.lang.Object obj)

  Specified by:
    `marshalForActivate` in interface `WSApplicationModuleMarshaller`

### addResponse

    public void addResponse(java.io.Serializable resp)

  Specified by:
    `addResponse` in interface `WSApplicationModuleMarshaller`

### setDataModelRefresh

    public void setDataModelRefresh(boolean b)

  Specified by:
    `setDataModelRefresh` in interface `WSApplicationModuleMarshaller`

### getObjectMarshaller

    public ObjectMarshaller getObjectMarshaller()

  Specified by:
    `getObjectMarshaller` in interface `WSApplicationModuleMarshaller`

### getSyncMode

    public int getSyncMode()

  Returns the sync mode for this Application Module.
  Specified by:
    `getSyncMode` in interface `ApplicationModule`
  Returns:
    integer representation of the sync mode: 0=`SYNC_LAZY`, 1=`SYNC_IMMEDIATE`.
  See Also:
    `ApplicationModule.setSyncMode(int mode)`, `ApplicationModule.SYNC_LAZY`, `ApplicationModule.SYNC_IMMEDIATE`

### getViewObjectNames

    public java.lang.String[] getViewObjectNames()

  Returns an array of names of the View Objects that are currently loaded within this Application Module.

  Example code:

          String[] voNames = am.getViewObjectNames();

          // If you want to retrieve all currently loaded View Objects
          ViewObject[] vos = new ViewObject[voNames.length];

          for (int i = 0; i < voNames.length; i++)
          {
             vos[i] = am.findViewObject(voNames[i]);
          }

  If you need names of View Objects that are not yet loaded, use ``getViewObjectNames(boolean, boolean)``.

  Specified by:
    `getViewObjectNames` in interface `ApplicationModule`
  Returns:
    an array of View Object names. If this Application Module contains no View Object, it returns an empty array, i.e., `new String[0]`.
  See Also:
    `findViewObject(String)`

### getViewObjectNames

    public java.lang.String[] getViewObjectNames(boolean inclLoadedOnes,
                                                 boolean inclNotLoadedOnes)

  Returns an array of names of the View Objects in this Application Module.

  This method allows the user to control whether the returning names are those of loaded (instantiated) View Objects, or those of not yet loaded (uninstantiated) View Objects, or both. Not yet loaded View Objects would appear only if lazy loading is turned on.

  Note that ``getViewObjectNames()`` is equivalent to `getViewObjectNames(true, false)`.

  Specified by:
    `getViewObjectNames` in interface `ApplicationModule`
  Parameters:
    `inclLoadedOnes` - if `true`, only loaded ones are returned.
    `inclNotLoadedOnes` - if `true`, only those that are not yet loaded are returned.
  Returns:
    an array of View Object names. If this Application Module contains no View Object , it returns an empty array, i.e., `new String[0]`.

### getViewLinkNames

    public java.lang.String[] getViewLinkNames()

  Returns an array of the names of the View Links that are currently loaded within this Application Module.

  Example code:

          String[] vlNames = am.getViewLinkNames();

          // If you want to retrieve all currently loaded View Links
          ViewLink[] vls = new ViewLink[vlNames.length];

          for (int i = 0; i < vlNames.length; i++)
          {
             vls[i] = am.findViewLink(vlNames[i]);
          }

  If you need names of View Links that are not yet loaded, use ``getViewLinkNames(boolean, boolean)``.

  Specified by:
    `getViewLinkNames` in interface `ApplicationModule`
  Returns:
    an array of View Link names. If this Application Module contains no View Link, it returns an empty array, i.e., `new String[0]`.
  See Also:
    `findViewLink(String)`

### getViewLinkNames

    public java.lang.String[] getViewLinkNames(boolean inclLoadedOnes,
                                               boolean inclNotLoadedOnes)

  Returns an array of names of the View Links in this Application Module.

  This method allows the user to control whether the returning names are those of loaded (instantiated) View Links, or those of not yet loaded (uninstantiated) View Links, or both. Not yet loaded View Links would appear only if lazy loading is turned on.

  Note that ``getViewLinkNames()`` is equivalent to `getViewLinkNames(true, false)`.

  Specified by:
    `getViewLinkNames` in interface `ApplicationModule`
  Parameters:
    `inclLoadedOnes` - if `true`, only loaded ones are returned.
    `inclNotLoadedOnes` - if `true`, only those that are not yet loaded are returned.
  Returns:
    an array of View Link names. If this Application Module contains no View Link, it returns an empty array, i.e., `new String[0]`.

### getViewLinks

    public ViewLinkImpl[] getViewLinks()

  Returns an array of the View Links contained in this Application Module. Called from the root Application Module, this method can be invoked to browse and access any View Link in the system.

  The following example uses this method to remove the View Links contained in the Application Module:

       ViewLink[] vls = yourAM.getViewLinks();
          for (j = 0; j < vls.length; j++)
            {
              vls[j].remove();
            }

  Returns:
    the array of View Links.

### createViewLink

    public ViewLink createViewLink(java.lang.String viewLinkName,
                                   java.lang.String viewLinkDefName,
                                   ViewObject master,
                                   ViewObject detail)

  Creates a View Link, given the View Link name, the Def name, and the names of the master and detail View Objects. You can use this method to dynamically create View Links.

  For example, assume that during design time, you used the Design-Time View Object Wizard to create two View Objects, `DeptVO` and `EmpVO` inside of a package named `package1`. Then, assume that you invoked the View Link Wizard from the package node to create a View Link Definition named `MyViewLinkDef`, that links `DeptVO` and `EmpVO` in a master-detail relationship.

  Given that you have the names of the View Link Definition and the master and detail View Objects, you can provide code such as the following that executes during runtime and creates a View Link named `MyLink1`:

       ViewObject voDept = myAM.createViewObject("MyDept", "package1.DeptVO");
       ViewObject voEmp = myAM.createViewObject("MyEmp", "package1.EmpVO");
       ViewLink vl = myAM.createViewLink("MyLink1", "package1.MyViewLinkDef",
                      voDept, voEmp);

  This will set up a master-detail relationship between the `voDept` and the `voEmp`.

  Specified by:
    `createViewLink` in interface `ApplicationModule`
  Parameters:
    `viewLinkName` - the name to be given to the View Link. If empty, a name is generated.
    `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 View Object.
    `detail` - the link's destination View Object.
  Returns:
    a new view link.
  Throws:
    `InvalidParamException` - if `master` or `detail` are invalid.
    `InvalidObjNameException` - if `viewLinkName` is invalid.
    `NameClashException` - if `viewLinkName` already exists.
  See Also:
    `ApplicationModule.createViewObject(String, String)`

### createViewLinkFromEntityAssocName

    public ViewLink createViewLinkFromEntityAssocName(java.lang.String viewLinkName,
                                                      java.lang.String entityAssocName,
                                                      ViewObject master,
                                                      ViewObject detail)

  Creates a View Link, given the View Objects and an Entity Association.

  Use this method to create a View Link when your code can access the View Objects and an Entity Association. This method can create a View Link because a View Link Definition can be built from the Entity Association between the underlying Entity Objects.

  For example, during Design Time you can define View Objects such as `DeptVO` for the `DeptEO` Entity Object, and `EmpVO` for the `EmpEO` Entity Object. Then you can define an Association named `MyAssoc` that associates `DeptEO` to `EmpEO`. With this information, you can build a View Link Definition, say `MyViewLinkBasedOnAssoc`, which relates `DeptVO` to `EmpVO`, based on this Entity Association.

  During runtime, you can create a View Link with code like this:

       ViewObject voDept = myAM.createViewObject("MyDept", "package1.DeptVO");
       ViewObject voEmp = myAM.createViewObject("MyEmp", "package1.EmpVO");
       ViewLink vl = myAM.createViewLinkFromEntityAssocName("MyLink2",
                   "package1.MyAssoc",  voDept, voEmp);

  The primary difference between `createViewLink` and `createViewLinkFromEntityAssocName` is that the former requires the View Link Definition name, and the latter requires the Entity Association name.

  Specified by:
    `createViewLinkFromEntityAssocName` in interface `ApplicationModule`
  Parameters:
    `viewLinkName` - the name to be given to the View Link. If empty a name is generated.
    `entityAssocName` - the entity association that the View Link will represent.
    `master` - the link's source View Object.
    `detail` - the link's destination View Object.
  Returns:
    a new view link.
  Throws:
    `InvalidParamException` - if `master`, `detail`, or `entityAssocName` are invalid.
    `InvalidObjNameException` - if `viewLinkName` is invalid.
    `NameClashException` - if `viewLinkName` already exists.
  See Also:
    `ApplicationModule.createViewObject(String, String)`

### createViewLinkBetweenViewObjects

    public ViewLink createViewLinkBetweenViewObjects(java.lang.String viewLinkName,
                                                     java.lang.String accessorName,
                                                     ViewObject master,
                                                     AttributeDef[] srcAttrs,
                                                     ViewObject detail,
                                                     AttributeDef[] destAttrs,
                                                     java.lang.String assocClause)

  Creates a View Link given either a View Link Definition or an Entity Association. This method creates the View Link by identifying which View Object attributes to relate to each other. This method also gives you the option of creating a View Link accessor and specifying a custom association clause.

  During design time, you could define View Objects such as DeptVO for the `DeptEO` Entity Object, and `EmpVO` for the `EmpEO` Entity Object, but not define an Entity Association or a View Link Definition.

  During runtime, you can use `createViewLinkBetweenViewObjects` to create a View Link by associating attributes from `DeptVO` and `EmpVO`. For example, if both `DeptVO` and `EmpVO` have a `DeptNum` attribute, you can associate the attributes and create the View Link with the following block of code:

       ViewObject voDept = myAM.createViewObject("MyDept", "package1.DeptVO");
       ViewObject voEmp = myAM.createViewObject("MyEmp", "package1.EmpVO");

       // Build an attribute array, consisting of DeptVO.DeptNum.
       AttributeDef[] deptAttrs = new AttributeDef[1];
       deptAttrs[0] = voDept.findAttributeDef("DeptNum");

       // Build an attribute array, consisting of EmpVO.DeptNum.
       AttributeDef[] empAttrs = new Attributedef[1];
       empAttrs[0] = voEmp.findAttributeDef("DeptNum");
       ViewLink vl = myAM.createViewLinkBetweenViewObjects("MyLink3",
                    "Employees",  // accessor name--more on this below
                     voDept,      // master
                     deptAttrs,   // department attributes
                     voEmp,       // detail
                     empAttrs,    // employee attributes
                     null);       // assoc clause

  The `createViewLinkBetweenViewObjects` call builds a View Link that makes `voEmp` a detail of `voDept`. The `voEmp` View Object will display employees for the current department in `voDept`.

  Using the Accessor Name
  The `createViewLinkBetweenViewObjects` method lets you specify an accessor name. The accessor lets you retrieve details by calling `getAttribute` with that name. In the above code example, the accessor was specified as `Employees`. Calling `getAttribute` on `Employees` will return an iterator through which you can enumerate employees in the current department.

  For example, you can write code like this that will return an iterator that can enumerate employees in the first department.

       Row row = voDept.first(); // get the first dept
       RowIterator iter = (RowIterator) row.getAttribute("Employees");

  If your code does not need an accessor, the `accessorName` parameter can be set to `null`.

  Using the Association Clause
  The `createViewLinkBetweenViewObjects` method lets you specify a custom association clause, replacing the one generated by the Business Components runtime. Passing in `null` means that the method will use the association clause generated by runtime which relates the source attributes to the destination attributes. For example, since `assocClause` is `null` in the above code snippet, runtime will use the equivalent of the PL/SQL association clause `WHERE voDept.DeptNum=voEmp.DeptNum`.

  Specified by:
    `createViewLinkBetweenViewObjects` in interface `ApplicationModule`
  Parameters:
    `viewLinkName` - the name to be given to the View Link. If empty, a name is generated.
    `accessorName` - the name to be given to the View Link's accessor.
    `master` - the link's source View Object.
    `srcAttrs` - link attributes taken from the master View Object.
    `detail` - the link's destination View Object.
    `destAttrs` - link attributes taken from the detail View Object.
    `assocClause` - the association clause. Can be `null`.
  Returns:
    a new view link.
  Throws:
    `InvalidParamException` - if `master` or `detail` are invalid.
    `InvalidObjNameException` - if `viewLinkName` or `accessorName` are invalid.
    `NameClashException` - if `viewLinkName` or `accessorName` already exist.
  See Also:
    `ApplicationModule.createViewObject(String, String)`, `StructureDef.findAttributeDef(String)`, `RowIterator.next()`, `AttributeList.getAttribute(String)`

### findViewObjectWithParameters

    public ViewObject findViewObjectWithParameters(java.lang.String voName,
                                                   VariableManager params,
                                                   boolean executeIfNeeded)

  Given a ViewObject name, use findViewObject(String name) to find the ViewObject and set it's named bind parameters with the values passed in the 'params' argument. If the execute flag is true, execute this ViewObject before returning it to the caller.
  Specified by:
    `findViewObjectWithParameters` in interface `ApplicationModule`

### findViewObject

    public ViewObject findViewObject(java.lang.String voName)

  Finds the named View Object. The View Object name passed in (`voName`) may or may not be qualified with the name of the containing Application Module. If it is, the View Object name is said to be an AM-qualified View Object name. If not, the name is said to be an unqualified View Object name.

  An AM-qualified name is a multi-part name (separated by dots). The last part of the name is the View Object name (View Object part of the name). All preceding parts consistitute the name of the Application Module that contains the View Object. For an AM-qualified name, `findViewObject()` first locates the containing Application Module using the Application Module name. In fact, it uses `findApplicationModule(String)` to find the Application Module. Thus, the Application Module name in an AM-qualified View Object name may be relative or absolute Application Module name. See `findApplicationModule()` discussions on absolute and relative Application Module names. Once the Application Module is found, the View Object part is used to find the View Object in that Application Module.

  If the View Object name is unqualified, the search for the View Object is made on this Application Module.

  For example, suppose we have the following containership of nested Application Modules and View Objects:

          Root (root Application Module)
             ChildAM1
                ViewObjectA
                GrandChildAM1_1
                   ViewObjectB
                GrandChildAM1_2
                   GreatGrandChildAM1_2_1
                      ViewObjectC
             ChildAM2
                GrandChildAM2_1
                   ViewObjectD

  `ChildAM1.findViewObject("GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewObjectC")` will succeed (using relative Application Module name).

  `ChildAM2.findViewObject("Root.ChildAM1.GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewObjectC")` will succeed (using absolute Application Module name) and return the same View Object as `ChildAM1.findViewObject("GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewObjectC")`.

  Both these are AM-qualified name cases.

  `GrandChildAM2_1.findViewObject("ViewObjectD")` will succeed. This is is an unqualified name case.

  For View Object searching, `findViewObject()` makes no distinction between View Objects included the Application Module during design time and those created programmatically during runtime.

  Example code:

          ViewObject vo = am.findViewObject("MyVO");

  Specified by:
    `findViewObject` in interface `ApplicationModule`
  Parameters:
    `voName` - the name of the View Object.
  Returns:
    the View Object. `null` if the View Object is not found.
  Throws:
    `NoObjException` - if an AM-qualified name was specified and the containing Application Module could not be found.
    `InvalidObjNameException` - if `voName` is an invalid name. `voName` must be a vaild Java name.
  See Also:
    `findApplicationModule(String)`, `findViewLink(String)`

### findComponentObject

    public ComponentObject findComponentObject(java.lang.String compName)

  Finds the component object from the Application Module. An Application Module typically contains View Objects, View Links, or another Application Module. This method will instead, return a generic component that has been included in the Application Module. A generic component is any object that implements the `ComponentObject` interface. This method allows for integration of other applications.
  Specified by:
    `findComponentObject` in interface `ApplicationModule`
  Overrides:
    `findComponentObject` in class `ContainerObjectImpl`
  Parameters:
    `compName` - name of the component object.

### findViewLink

    public ViewLink findViewLink(java.lang.String vlName)

  Finds the named View Link. The View Link name passed in (`vlName`) may or may not be qualified with the name of the containing Application Module. If it is, the View Link name is said to be an AM-qualified View Link name. If not, the name is said to be an unqualified View Link name.

  An AM-qualified name is a multi-part name (separated by dots). The last part of the name is the View Link name (View Link part of the name). All preceding parts consistitute the name of the Application Module that contains the View Link. For an AM-qualified name, `findViewLink()` first locates the containing Application Module using the Application Module name. In fact, it uses `findApplicationModule(String)` to find the Application Module. Thus, the Application Module name in an AM-qualified View Link name may be relative or absolute Application Module name. See `findApplicationModule()` discussions on absolute and relative Application Module names. Once the Application Module is found, the View Link part is used to find the View Link in that Application Module.

  If the View Link name is unqualified, the search for the View Link is made on this Application Module.

  For example, suppose we have the following containership of nested Application Modules and View Links:

          Root (root Application Module)
             ChildAM1
                ViewLinkA
                GrandChildAM1_1
                   ViewLinkB
                GrandChildAM1_2
                   GreatGrandChildAM1_2_1
                      ViewLinkC
             ChildAM2
                GrandChildAM2_1
                   ViewLinkD

  `ChildAM1.findViewLink("GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewLinkC")` will succeed (using relative Application Module name).

  `ChildAM2.findViewLink("Root.ChildAM1.GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewLinkC")` will succeed (using absolute Application Module name) and return the same View Link as `ChildAM1.findViewLink("GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewLinkC")`.

  Both these are AM-qualified name cases.

  `GrandChildAM2_1.findViewLink("ViewLinkD")` will succeed. This is is an unqualified name case.

  For View Link searching, `findViewLink()` makes no distinction between View Links included the Application Module during design time and those created programmatically during runtime.

  Example code:

          ViewLink vl = am.findViewLink("MyVL");

  Specified by:
    `findViewLink` in interface `ApplicationModule`
  Parameters:
    `vlName` - the name of the View Link.
  Returns:
    the View Link. `null` if the View Link is not found.
  Throws:
    `NoObjException` - if an AM-qualified name was specified and the containing Application Module could not be found.
    `InvalidObjNameException` - if `vlName` is an invalid name. `vlName` must be a vaild Java name.
  See Also:
    `findApplicationModule(String)`, `findViewObject(String)`

### getDBTransaction

    public DBTransaction getDBTransaction()

  Gets this Application Module's database transaction. Note that if this method is invoked on a nested Application Module, the root Application Module's transaction is returned. This is because the transaction is shared by all Application Modules contained by the root Application Module.

  If the user creates two root Application Modules, they normally do not share the transaction. To share a transaction acroos root Application Modules, the user would need to define a global transaction through JTA and have both Application Modules participate in it.

  Returns:
    the transaction.
  Throws:
    `java.lang.IllegalStateException` - if no root Application Module is found. This could happen if the user calls this method on an Application Module that has

### getViewObjects

    public ViewObject[] getViewObjects()

  Constructs an array of this Application Module's View Objects. The following example uses this method to remove the View Objects contained in the Application Module:

       ViewObject[] vos = yourAM.getViewObjects();
              for (j = 0; j < vos.length; j++)
                {
                  vos[j].remove();
                }

  Returns:
    the array of View Objects contained by this Application Module.

### createViewObjectFromQueryStmt

    public ViewObject createViewObjectFromQueryStmt(java.lang.String voName,
                                                    java.lang.String query)

  Creates a read-only View Object, given a query statement and a name for the View Object. View Objects created using this method are read-only because there are no underlying Entity Objects.

  The following example of a simple fetch uses a static SQL statement with all information hard-coded. After printing the results, the View Object is removed.

       public static void demoSimpleFetch(ApplicationModule appMod) {
            // Define basic query string.
            String sqlStr = "SELECT Emp.ename, Emp.mgr FROM EMP Emp ";
            ViewObject vo =
                   appMod.createViewObjectFromQueryStmt("QueryDemo", sqlStr);
            printViewObject(vo);
            vo.remove();}

  Specified by:
    `createViewObjectFromQueryStmt` in interface `ApplicationModule`
  Parameters:
    `voName` - the name to be given to the View Object. If empty a name is generated.
    `query` - the SQL query that defines the View Object.
  Returns:
    a new View Object.
  Throws:
    `InvalidObjNameException` - if `qName` is invalid.
    `NoObjException` - if `qName` does not exist.

### createViewObjectFromQueryClauses

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

  Creates an updateable View Object.

  Use this method to build a View Object from SQL clauses. The View Object can be based on an Entity Object. For example, the following statement creates a View Object from attributes of the `EMP` Entity Object. Attributes related to `EMP` (such as `E.ENAME`) are updateable.

         ViewObject v = appMod.createViewObjectFromQueryClauses("xyz",
               "demo.hr.EMP",       // The one updateable Entity Object Name
               "E.ENAME, E.EMPNO",  // select clause
               "EMP E",             // from clause
               "E.DEPTNO = 10",     // where clause
                null);              // order by clause

  Specified by:
    `createViewObjectFromQueryClauses` in interface `ApplicationModule`
  Parameters:
    `voName` - the name to be given to the View Object. If empty, a name is generated.
    `eoName` - the name of the Entity Object from which the View Object is to be derived.
    `selectClause` - a SQL statement SELECT clause.
    `fromClause` - a SQL statement FROM clause.
    `whereClause` - a SQL statement WHERE clause.
    `orderByClause` - a SQL statement ORDERBY clause.
  Returns:
    a new View Object.
  Throws:
    `InvalidParamException` - if `voName` is invalid.
    `NameClashException` - if `voName` already exists.

### createViewObjectOnEntity

    public ViewObject createViewObjectOnEntity(java.lang.String voName,
                                               java.lang.String eoName)

  Specified by:
    `createViewObjectOnEntity` in interface `ApplicationModule`

### createViewObjectOnRowSet

    public ViewObject createViewObjectOnRowSet(java.lang.String voName,
                                               RowSet rs)

  Specified by:
    `createViewObjectOnRowSet` in interface `ApplicationModule`

### executeCommand

    public int executeCommand(java.lang.String command)

  Specifies a valid SQL statement to be executed by the server. The return integer value describes how many rows were affected by the SQL statement. This is a utility method for testing and debugging queries and applications.

  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.

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

### createViewObject

    protected ViewObject createViewObject(java.lang.String voName,
                                          ViewDefImpl viewDef)

### createViewObject

    public ViewObject createViewObject(java.lang.String voName,
                                       java.lang.String vDefName)

  Creates an updateable View Object.

  This method is useful for instantiating View Objects within a generic Application Module, but you can use it with any Application Module. The code calls `createViewObject`, passing in the name of the View Object metadata (that is, the name you provided for the View Object at design time) that defines the View Object and a View instance name to identify this instance. You can use this View instance name to find the View Object later, if needed.

        // Specify the Java file that defines the View Object.
        // Format: package.filename
            String voDefFile = "d2e.DeptView";

        // Identify the View Object. Must be a valid Java identifier.
            String voname="demoDeptVO";

       // Create the View Object within the context defined by the
       // Application Module.
          ViewObject vo = appMod.createViewObject(voName, voDefFile);

  Specified by:
    `createViewObject` in interface `ApplicationModule`
  Parameters:
    `voName` - the name to be given to the View Object. If empty, a name is generated.
    `vDefName` - a view definition.
  Returns:
    a new View Object.
  Throws:
    `InvalidObjNameException` - if `voName` is invalid.
    `NoObjException` - if `voName` does not exist.

### createComponentObject

    public ComponentObject createComponentObject(java.lang.String coName,
                                                 java.lang.String comDefName)

  Creates a Component object in the context of this Application Module.

  An Application Module typically contains View Objects, View Links, or other Application Modules. This method will create a generic component in the context of the Application Module. A generic component is any object that implements the `ComponentObject` interface. This method allows for integration of other applications.

  Specified by:
    `createComponentObject` in interface `ApplicationModule`
  Overrides:
    `createComponentObject` in class `ContainerObjectImpl`
  Parameters:
    `coName` - name of the component object. If empty, a name will be generated.
    `comDefName` - name of the component Def (definition) object.
  Throws:
    `InvalidObjNameException` - if an invalid component name is used.

### getApplicationModuleImpls

    public ApplicationModuleImpl[] getApplicationModuleImpls()

  Internal: Applications should not use this method.

  Creates an array of Application Modules.

  Returns:
    the array of Application Modules.

### isNameGenerated

    public final boolean isNameGenerated()

  Tests if the Application Module's name was generated by the system.
  Returns:
    `true` if the name was generated by the system. `false` if the name was given by the user and not generated by the system.

### getAttributeDefs

    public static AttributeDefValue[] getAttributeDefs(StructureDef def)

### getAttributeDefsForVO

    public static AttributeDefValue[] getAttributeDefsForVO(ViewObject vo)

### remove

    public void remove()

  Deletes this Application Module. Call this method when the application is finished using the Application Module. In three tier mode, calling this method cleans up server-side memory and resources.

  This method should not be overridden.

  Specified by:
    `remove` in interface `ComponentObject`
  Overrides:
    `remove` in class `ComponentObjectImpl`

### reset

    protected void reset()

  BC4J invokes this method when a ApplicationModule is being reset for potential reuse by another client session. Custom applications may extend this method to clean up custom ApplicationModule state that was specific to the last session to use this ApplicationModule.

  Examples of session ApplicationModule state include custom instance variables.

  See Also:
    `resetState(boolean)`

### resetState

    public void resetState(boolean reload)

  Specified by:
    `resetState` in interface `ApplicationModule`

### resetState

    public void resetState(int flags)

  Description copied from interface: `ApplicationModule`
  Advanced use only

  Applications should override/extend `reset()` to reset custom application module state. reset() is invoked by the internal `resetState` before resetState begins cleaning up internal application module state.

  Flag usage:

  `RESET_RELOAD_FLAG` directs resetState to eagerly reload the application module compoonents.

  `RESET_ROLLBACK_FLAG` directs resetState to rollback the application module.

  `RESET_INTERNAL_FLAG` directs resetState to perform an internal reset only. The ApplicationPool uses this to reset a managed state application module while also managing the previous session's state. For example, when RESET_INTERNAL has been specified the reset will not remove the persistent snapshot records on the snapshot stack.

  Resets the non-transaction state of an application module. For example:

       appModule.resetState(false);

  Specified by:
    `resetState` in interface `ApplicationModule`

### findVOsWithEntityUsage

    public void findVOsWithEntityUsage(java.lang.String entityName,
                                       boolean recurse,
                                       com.sun.java.util.collections.ArrayList vos)

  Finds the View Objects that use the specified entity. This method is used by `clearVOCaches`.

  If `entityName` is `null`, then this method finds all View Objects in the Application Module. If `recurse` is `true`, it recurses into nested (child) Application Modules.

  Parameters:
    `entityName` - name of the Entity Object that the View Objects use. Can be `null`.
    `recurse` - `true` recurses to (child) Application Modules; `false` applies this method only to the top-level Application Module.
    `vos` - a vector of View Objects.
  See Also:
    `clearVOCaches(String, boolean)`

### findVOsWithEntityUsage

    public void findVOsWithEntityUsage(java.lang.String entityName,
                                       boolean recurse,
                                       java.util.Vector vos)

### clearVOCaches

    public void clearVOCaches(java.lang.String entityName,
                              boolean recurse)

  Clears the caches of all View Objects that use the specified entity. This method finds all View Objects that use the entity, then calls `clearCache()` on each View Object.

  If `entityName` is `null`, then the caches of all View Objects in the Application Module are cleared. If `recurse` is `true`, it recurses into nested (child) Application Modules.

  Specified by:
    `clearVOCaches` in interface `ApplicationModule`
  Parameters:
    `entityName` - name of the Entity Object that the View Objects use. Can be `null`.
    `recurse` - `true` recurses to (child) Application Modules; `false` applies this method only to the top-level Application Module.
  See Also:
    `ViewObject.clearCache()`

### getClientProxyClassName

    public java.lang.String getClientProxyClassName()

  Internal: Applications should not use this method.

  Returns the client proxy's class name for this Application Module.

### getClientProxyClassName

    public java.lang.String getClientProxyClassName(java.lang.String serverType)

  Deprecated. Platform specific proxies not required. Use getClientProxyClassName() instead.
  Internal: Applications should not use this method.

  Returns the client proxy's class name for this Application Module. for the given server platform type

### getClientProxyInterfaceName

    public java.lang.String getClientProxyInterfaceName()

  Specified by:
    `getClientProxyInterfaceName` in interface `WSApplicationModuleMarshaller`

### getExceptionHandler

    public JboExceptionHandler getExceptionHandler()

  Specified by:
    `getExceptionHandler` in interface `ApplicationModule`

### setExceptionHandler

    public void setExceptionHandler(JboExceptionHandler hndlr)

  Specifies the name of the handler which will perform special processing of the exceptions on the client.

  In typical use in three tier mode, a user enters values at the client. A user response, such as pressing the Return key or a Submit button, pushes the values to the server. The values are applied to the Entities and validated. Any exceptions that are thrown, are collected and shipped back to the client. Typically, exceptions are given, one-by-one, to the client. Instead, a handler can be specified to perform special processing of the exceptions.

  Specified by:
    `setExceptionHandler` in interface `ApplicationModule`
  Parameters:
    `hndlr` - an exception handler.

### addWarning

    public void addWarning(JboWarning warn)

  Specifies the name of the handler that will perform special processing of warnings on the client.
  Specified by:
    `addWarning` in interface `ApplicationModule`
  Parameters:
    `warn` - a warning.

### setStyles

    public void setStyles(java.lang.String name,
                          ClientDocument clientDocument)

  Saves the Application Module's style definitions to the middle tier.
  Specified by:
    `setStyles` in interface `ApplicationModule`
  Parameters:
    `name` - a name under which the style definitions are to be stored.
    `clientDocument` - the `ClientDocument` to be saved.
  See Also:
    `ClientDocument`

### getStyles

    public ClientDocument getStyles(java.lang.String name)

  Gets the Application Module's style definitions from the middle tier.
  Specified by:
    `getStyles` in interface `ApplicationModule`
  Parameters:
    `name` - a name under which the style definitions are stored.
  Returns:
    a `ClientDocument`.
  See Also:
    `ClientDocument`

### getSession

    public Session getSession()

  Returns the session information. Whenever a client connects to a middle tier server, a session is created. Note, this is the same session that is passed in the `activate` call.
  Specified by:
    `getSession` in interface `ApplicationModule`
  Returns:
    the session.
  Throws:
    `java.lang.IllegalStateException` - if the session information cannot be found.
  See Also:
    `activate(Session)`

### getTransaction

    public Transaction getTransaction()

  Returns the transaction information. This method can be called from the client.
  Specified by:
    `getTransaction` in interface `ApplicationModule`
  Returns:
    the transaction.
  Throws:
    `java.lang.IllegalStateException` - if the transaction information cannot be found.

### beforeCommit

    public void beforeCommit(TransactionEvent e)

  Description copied from interface: `TransactionListener`
  Called to report that a Commit operation is imminent.
  Specified by:
    `beforeCommit` in interface `TransactionListener`
  Parameters:
    `e` - a transaction event.

### beforeRollback

    public void beforeRollback(TransactionEvent e)

  Description copied from interface: `TransactionListener`
  Called to report that a Rollback operation is imminent.
  Specified by:
    `beforeRollback` in interface `TransactionListener`
  Parameters:
    `e` - a transaction event.

### afterCommit

    public void afterCommit(TransactionEvent e)

  Description copied from interface: `TransactionListener`
  Called to report that a Commit operation has occurred.
  Specified by:
    `afterCommit` in interface `TransactionListener`
  Parameters:
    `e` - a transaction event.

### afterRollback

    public void afterRollback(TransactionEvent e)

  Description copied from interface: `TransactionListener`
  Called to report that a Rollback operation has occurred.
  Specified by:
    `afterRollback` in interface `TransactionListener`
  Parameters:
    `e` - a transaction event.

### afterRemove

    public void afterRemove(TransactionEvent e)

  Description copied from interface: `TransactionListener`
  A cleanup routine to be invoked by transaction manager when this transaction listener is removed from the manager's list.
  Specified by:
    `afterRemove` in interface `TransactionListener`
  Parameters:
    `e` - a transaction event.

### isTransientTransactionListener

    public boolean isTransientTransactionListener()

  Description copied from interface: `TransactionListener`
  Tests whether this transaction listener is transient or permanent.

  Transient listeners are automatically removed at the end of a transaction commit or rollback cycle; permanent listeners remain across these cycles.

  Specified by:
    `isTransientTransactionListener` in interface `TransactionListener`
  Returns:
    `true` if the listener is transient.

### findRSIForEntity

    public RowSetIterator findRSIForEntity(RowSetIterator[] rsis,
                                           int eRowHandle)

  Finds the RowSetIterator associated with the specified row handle. This method is provided to handle errors that occur during entity post cycle.

  If an error occurs while an entity is being posted to database, the framework throws a `DMLException`. Inside the `DMLException` instance is an opaque handle (in reality an integer) identifying the Entity (an instance of `EntityImpl`) that caused the error.

  For example, the `DMLException` could have been thrown because the row violated a database constraint. The client might want to give the user a chance to correct the problem by displaying the the ViewRow that uses this Entity.

  To do this, the client would "gather" all RowSetIterators that can be used to report and fix the problem. It would then call `findRSIForEntity`, passing in the array of RowSetIterators and the Entity row handle returned by `DMLException`.

  Among the RowSetIterator elements in the array, `findRSIForEntity` will pick the "best" one and return it to the client. The client then can use the RowSetIterator to report the problem and give the user a chance to fix the problem.

  Specified by:
    `findRSIForEntity` in interface `ApplicationModule`
  Parameters:
    `rsis` - an array of RowSetIterators
    `eRowHandle` - an Entity row handle returned by `DMLException`.
  Returns:
    the `RowSetIterator`.
  See Also:
    `DMLException`

### setStoreForPassiveState

    public void setStoreForPassiveState(byte storageType)

  Description copied from interface: `ApplicationModule`
  Internal: Applications should not use this method.

  Determines where the application module will store serialized versions of its session-state, plus any cached changes. This information can be stored to the database, to a file, or to memory, based on the value of the `storageType` parameter. The `storageType` can be set to:

  - `ApplicationModule.PASSIVATE_TO_DATABASE` (default target)
  - `ApplicationModule.PASSIVATE_TO_FILE`
  - `ApplicationModule.PASSIVATE_TO_MEMORY`

  This method should be called before calling `ApplicationModule.passivateState(byte[])`. Note that once an application module has serialized its state, it cannot be asked to change its store. This method will throw an `JboException` if this application module has already stored its state earlier.

  For example, the following code will set the storage to database, file, or memory, based on the value of the `str` parameter. Database is the default target:

       String str =
          oracle.jbo.common.JboEnvUtil.getProperty("jbo.test.passivateStateTo");
       if (str != null)
       {
          if (str.equals("file"))
          {
            appModule.setStoreForPassiveState(ApplicationModule.PASSIVATE_TO_FILE);
          }
          else
          if (str.equals("memory"))
          {
            appModule.setStoreForPassiveState(ApplicationModule.PASSIVATE_TO_MEMORY);
          }

  Specified by:
    `setStoreForPassiveState` in interface `ApplicationModule`
  Parameters:
    `storageType` - where the application module state is stored. Can be one of `ApplicationModule.PASSIVATE_TO_DATABASE` (default target), `ApplicationModule.PASSIVATE_TO_FILE`, or `ApplicationModule.PASSIVATE_TO_MEMORY`.
  See Also:
    `ApplicationModule.passivateState(byte[])`

### reservePassivationId

    public int reservePassivationId()

  Description copied from interface: `ApplicationModule`
  Internal: Applications should not user this method.
  Specified by:
    `reservePassivationId` in interface `ApplicationModule`

### reserveSnapshotId

    public int reserveSnapshotId(int flags)

  Description copied from interface: `ApplicationModule`
  Internal: Applications should not use this method.

  Reserves a unique indentifier which may later be specified when passivating AM state as the identifier to be used for re-establishing AM state.

  If the `PASSIVATE_TRANSIENT_FLAG` has not been set then this method will return a passivation id from one of the persistent Serializers (File and Database). This method will then reserve a stack snapshot id for that persistent snapshot. The reserved stack id may be acquired by invoking `ApplicationModule.getMostRecentStackId()`.

  If the `PASSIVATE_TRANSIENT_FLAG` has been set then this method will return a stack id. The stack id is unique for a session transaction only. This may need to be extended to provide a UUID so that applications do not inadvertantly try to undo state across transaction boundaries.

  This method may be invoked to obtain a unique snapshot identifier before a snapshot is actually acquired. An example use case is an HTTP servlet that must encode all URLs with the snapshot id before the snapshot is acquired.

  Specified by:
    `reserveSnapshotId` in interface `ApplicationModule`
  Parameters:
    `flags` - a bit map defining passivation flags.
  Returns:
    a unique integer identifier that may later be used to passivate and activate application module state
  See Also:
    `ApplicationModule.passivateState(int, byte[], int).`

### passivateState

    public int passivateState(byte[] clientData)

  Specified by:
    `passivateState` in interface `ApplicationModule`

### passivateState

    public int passivateState(byte[] clientData,
                              int flags)

  Description copied from interface: `ApplicationModule`
  Internal: Applications should not use this method.

  Creates a snapshot of the current state of this application module's session. If the `PASSIVATE_TRANSIENT_FLAG` is not set then the snapshot bytes will be serialized to a persistent store (database or file). If the `PASSIVATE_TRANSIENT_FLAG` bit is set then the snapshot bytes will be pushed to the application module snapshot stack. The method will then return a unique identifier which may be used to activate the state. Please note that the same snapshot type bit should be used to activate the state as was used to passivate the state. Failing to do so could result in the snapshot record not being located.

  This method always works from the top-level application module. If you have nested application modules and you call this method on a inner application module, it will still work from the top-level module.

  In contrast to `ApplicationModule.activateState(int, SessionData, int)`, which deserializes a session-state from the persistent store, calling `passivateState`, does not affect the transaction state.

  The cached changes, or `clientData`, can be any information that a client might want to store. For example, a JSP client could store the additional client-state information in this byte array so that when the JSP client becomes active and connects to an application module later, it could get its passivated state from the application module. This would reduce the amount of state information stored at the client side to a bare minimum (typically just an application module persistence ID).

  A value of `null` for `clientData` indicates that the state will be stored, but there is no client data to be preserved.

  This method preserves currency. When `ApplicationModule.activateState(int, SessionData, int)` is called, the active row is returned.

  For example, the following code snippet inserts a new row in a view object, then calls `passivateState` to save the application module state. The transaction is rolled back and `activateState` is called. The value of `getCurrentRow` called before the `passivateState` should match the the value of `getCurrentRow` called after `activateState`.

       // create a view object "depts"
       ViewObject depts = appModule.createViewObject("myDeptView", "myDeptViewDef");

       // insert a new row into depts
       Row r = depts.createRow();
       r.setAttribute("DeptNum","56");
       depts.insertRow(r);

       Row afterInsert = depts.getCurrentRow();

       // Passivate the application module state
       int id = appModule.passivateState(null);

       // rollback the transaction
       appModule.getTransaction.rollback();

       // move the cursor to the last row -- just to make it interesting
       depts.last();

       // now activate the application module state
       // currency should be on the new row inserted.
       appModule.activateState(id, SessionData, int);

       Row afterActivate = depts.getCurrentRow();

  The values `afterInsert` and `afterActivate` should be the same.

  Specified by:
    `passivateState` in interface `ApplicationModule`
  Parameters:
    `clientData` - cached changes, or any information that a client might want to store.
    `flags` - a bit map defining passivation flags.
  Returns:
    a unique integer identifier associated with an instance of the application module.

### passivateState

    public int passivateState(int id,
                              byte[] clientData)

  Description copied from interface: `ApplicationModule`
  Internal: Applications should not user this method.
  Specified by:
    `passivateState` in interface `ApplicationModule`

### passivateState

    public int passivateState(int id,
                              byte[] clientData,
                              int flags)

  Description copied from interface: `ApplicationModule`
  Internal: Applications should not use this method.

  Serializes the current state of this application module's session, along with all changes cached, to a byte array and returns a unique identifier with which to re-establish the state.

  This method accepts an id which represents the unique identifier that should be used to re-establish the application module state. The id must have been generated by invoking `ApplicationModule.reserveSnapshotId(int)`.

  The same snapshot type bit which was specified when the snapshot id was reserved should be specified when this method is invoked. For example, if `reserveSnapshotId` was invoked with the PASSIVATE_TRANSIENT_FLAG set then this method should be invoked with the PASSIVATE_TRANSIENT_FLAG set. Failing to do so may result in invalid snapshot id exceptions.

  For more information regarding passivation please see `ApplicationModule.passivateState(byte[], int)`.

  Specified by:
    `passivateState` in interface `ApplicationModule`
  Parameters:
    `id` - a reserved passivation id
    `clientData` - cached changes, or any information that a client might want to store.
    `flags` - a bit map defining passivation flags.
  Returns:
    a unique integer identifier associated with an instance of the application module.
  See Also:
    `ApplicationModule.reservePassivationId()`

### activateState

    public byte[] activateState(int id,
                                boolean remove)

  Specified by:
    `activateState` in interface `ApplicationModule`

### activateState

    public byte[] activateState(int id,
                                boolean remove,
                                SessionData info)

  Specified by:
    `activateState` in interface `ApplicationModule`

### activateState

    public byte[] activateState(int id,
                                SessionData info,
                                int flags)

  Description copied from interface: `ApplicationModule`
  Internal: Applications should not use this method.

  Deserializes a session-state from the persistent store based on the given `id`. This method always works from the top-level application module. If you have nested application modules and you call this method on a inner application module, it will still work from the top-level module.

  When the `PERSISTENT_SNAPSHOT` bit is set then this method will attempt to locate the snapshot bytes in a persistent store (database or file). If the `PERSISTENT_SNAPSHOT` bit is not set then this method will locate the snapshot bytes on the stack.

  When this method is called, the rows that are updated are locked; new rows are inserted into the transaction cache and posted. This is in contrast to `ApplicationModule.passivateState(byte[], int)`, which does not affect the transaction state.

  The `activateState` method preserves currency. When it is called, it will return the row that was active when `ApplicationModule.passivateState(byte[], int)` was called. For an example usage of `activateState`, see `ApplicationModule.passivateState(byte[], int)`.

  If the `REMOVE_SNAPSHOT` bit is set in the flags then the activation framework will remove the snapshot from the persistent store after activation.

  It is up to the developer to devise a clean-up strategy for the redundant store.

  Specified by:
    `activateState` in interface `ApplicationModule`
  Parameters:
    `id` - a unique integer identifier associated with an instance of the application module.
  Returns:
    a byte array containing any client information that was originally stored with the `ApplicationModule.passivateState(byte[], int)` method.

### getMostRecentStackId

    public int getMostRecentStackId()

  Description copied from interface: `ApplicationModule`
  Internal: Applications should not use this method.

  Acquire the snapshot id of the most recent stack snapshot. This method may be used by clients to acquire the stack snapshot id of a persistent snapshot.

  Please see `ApplicationModule.passivateState(byte[])` for more information regarding stack passivation.

  Specified by:
    `getMostRecentStackId` in interface `ApplicationModule`

### prepareSession

    public void prepareSession(SessionData info)

  Description copied from interface: `ApplicationModule`
  Internal: Applications should not use this method.
  Specified by:
    `prepareSession` in interface `ApplicationModule`

### prepareSession

    protected void prepareSession(Session session)

  Prepares the ApplicationModule session. This method is invoked whenever the ApplicationModule has been targeted for use by a client session which is different than the previously referencing session. The method will also be invoked when the ApplicationModule is first created.

  The application module may be assumed to be in a valid, connected state when this method is invoked. Application developers may extend this method to prepare custom session state. For example, an application developer could extend this method to prepare PL/SQL session state which is related to a virtual private database.

  The default implementation of this method will store the current ApplicationModuleHandle on the ApplicationModule session.

  See Also:
    `getSession()`

### removeState

    public void removeState(int id)

  Description copied from interface: `ApplicationModule`
  Internal: Applications should not use this method.

  Removes the application module's session-state, and any cached change information, from the persistent store based on the given `id`. For example:

       appModule.removeState(id);

  Specified by:
    `removeState` in interface `ApplicationModule`
  Parameters:
    `id` - an unique integer identifier associated with an instance of the application module.

### launchTester

    public static void launchTester(java.lang.String packageName,
                                    java.lang.String configName)

### passivateState

    protected void passivateState(Document doc,
                                  Element parent)

  Allows subclasses to store custom data as XML-nodes under the given parent element, in the given document. Specifies the current row for which the key has been passivated.

  This method lets customized Application Modules determine how they want to store private data. The only requirement is that this data should be stored under a child node under the parent element. Note that the data cannot be stored under the first child, because that is where default passivation routines always store the key.

  By default, the Application Module does not store anything in this method. On activation, the ApplicationModule calls `activateState(Element)` with the `parent` element for the reverse operation.

  Parameters:
    `doc` - the name of the XML document where the custom data will be stored.
    `parent` - the name of the parent element under which the custom data will be stored.

### activateState

    protected void activateState(Element parent)

  Allows subclasses to retrieve custom data from an XML-node under the given parent element. Specifies the current row for which the key has been passivated.
  Parameters:
    `parent` - the name of the parent element under which the custom data resides.

### passivateConnectionState

    protected void passivateConnectionState(Document doc,
                                            Element parent)

  Allows subclasses to store custom data associated with connection state. Custom data may be saved either as XML-nodes under the given parent element, or via a custom approach.

  In addition to being invoked prior to full passivation (which allows subclasses to encapsulate their connection state data storage), this method is also invoked as part of disconnect(true). In this latter case, the aim is to allow subclasses to store their connection specific data in memory prior to recycling of the JDBC connection. This data (such as open cursors or PL-SQL global variables) can then be restored when the connection is restored.

  For reference, the call order during full passivation is:

  Passivate Custom Connection State --------------------------------- 1. For each nested AM in root AM, cycle from step 1: 1.1. For each nested AM in the nested AM, cycle from step 1 (recursion). 1.2. passivateConnectionState() on nested AM. 2. passivateConnectionState() on root AM.

  Passivate Overall State ----------------------- 3. prepareForPassivation() on root AM. 4. passivateState() on VOs in root AM. 5. For each nested AM in root AM, cycle from step 1: 5.1. prepareForPassivation() on nested AM. 5.2. passivateState() on VOs in nested AM. 5.3. For each nested AM in the nested AM, cycle from step 1 (recursion). 5.4. passivateState() on nested AM. 6. passivateState() on root AM.

  In all cases, clients may expect the application module connection to be valid during these callback methods.

  Parameters:
    `doc` - the XML document in which custom data may be stored.
    `parent` - the parent element under which custom data may be stored.

### activateConnectionState

    protected void activateConnectionState(Element parent)

  Allow subclasses to retrieve custom data associated with connection state. Because we realize that clients may store data using a custom approach which does not result in any data residing on our XML nodes, BC4J will invoke this method on all child application modules, regardless of whether we have state to restore for that application module. If no child nodes were added during passivateConnectionState(), then the parent node passed into this method will be null.

  In addition to being invoked at the conclusion of full passivation (which allows subclasses to encapsulate their connection state data retrieval), this method is also invoked during reconnect() whenever disconnect(true) has been previously called.

  For reference, the call order during full activation is:

  Activate Overall State ----------------------- 1. prepareForActivation() on root AM. 2. For each nested AM in root AM, cycle from step 1: 2.1. prepareForActivation() on nested AM. 2.2. For each nested AM in the nested AM, cycle from step 1 (recursion). 2.3. activateState() on VOs in the nested AM. 2.4. activateState() on nested AM. 3. activateState() on VOs in root AM. 4. activateState() on root AM.

  Activate Custom Connection State --------------------------------- 5. activateConnectionState() on root AM. 6. For each nested AM in root AM, cycle from step 1: 6.1. activateConnectionState() on nested AM. 6.2. For each nested AM in the nested AM, cycle from step 1 (recursion).

  In all cases, clients may expect the application module connection to be valid during these callback methods.

  Parameters:
    `parent` - the parent element under which the custom data resides.

### handleDefinitionChangedOnActivate

    protected void handleDefinitionChangedOnActivate(java.lang.Object activatedTS)

  Allows subclasses to abort activation, when the metadata for the component objects has changed and an attempt is made to activate an Application Module which was saved with an older version of the metadata.
  Parameters:
    `activatedTS` - The meta-data definition version that the ApplicationModule being activated was passivated with. Currently this version object is a Long value. However Applications should not rely on the fact that this object will be of type Long in future.

### findViewObjectUsingEntity

    public ViewObject findViewObjectUsingEntity(ViewObject[] vos,
                                                java.lang.String eoName,
                                                java.lang.String[] attrNames)

  Description copied from interface: `ApplicationModule`
  Given an array of view objects (the `vos` parameter), finds the first matching view object. It uses the following rules to determine if the view object matches the description.
  - Does the view object use the specified entity (`entityName`) as one of its entity bases?
  - If `attrName` is not empty, is one of the view object's attributes mapped to the entity's attribute whose name is `attrName[0]`? If `attrName` is empty, i.e., it is either `null` or has no element, then this rule is skipped.
  - If the view object passes the above two rules, then a check is made to see if the entity base in this view object is updateable or not. If it is, this view object is returned. If it is not, we continue until we find one that with an updateable entity base or until we exhaust the `vos` array. If none of the view objects that pass the first two rules has an updateable entity base, the first view object that passed the first two rules is returned.
  The method is used to find a view object that can be used to edit an entity object's attribute. If a matching view object is identified, and if `attrName` coming in was not empty, the view object's attribute name is copied into the `attrName`.
  Specified by:
    `findViewObjectUsingEntity` in interface `ApplicationModule`
  Parameters:
    `vos` - an array of possible view objects.
    `eoName` - fully qualified name of the entity object. Should not be `null`.
    `attrNames` - if empty, i.e., `null` or an array of length 0, then the attribute matching rule will be skipped (see the above discussion). If not empty, it should have only one element and that element should be the name of an attribute of the entity. The attribute matching rule will apply. If a matching view object is found, `attrName[0]` upon return should have the name of a view object mapped to the entity attribute.

### transformExceptionParams

    public java.lang.Object[] transformExceptionParams(ViewObject[] inVOs,
                                                       java.lang.String entityDefName,
                                                       java.lang.String className,
                                                       java.lang.Object[] params)

  Description copied from interface: `ApplicationModule`
  Internal: Applications should not use this method. This method uses findViewObjectUsingEntity() to get the first view object that this entity is used in and then transforms the parameters from a given JboException from their entity layer equivalents to the view object equivalents. This method is primarily used by JboException subclasses to map their parameters when doEntityToVOMapping() is called on those Exceptions.
  Specified by:
    `transformExceptionParams` in interface `ApplicationModule`
  Parameters:
    `inVOs` - an array of possible view objects.
    `entityDefName` - fully qualified name of the entity object. Should not be `null`.
    `className` - Qualified classname for the Exception which is being mapped
    `params` - Parameters from the Exception that is to be transformed into view object equivalents.

### transformExceptionParams

    protected java.lang.Object[] transformExceptionParams(ViewObject vo,
                                                          java.lang.String entityDefName,
                                                          java.lang.String className,
                                                          java.lang.Object[] params)

  Internal: Applications should not call this method.

### afterConnect

    protected void afterConnect()

  Invoked after the application module database connection has been established. This method may be overriden by applications to perform application module initialization which requires database access.

### beforeDisconnect

    protected void beforeDisconnect()

  Invoked before the application module database connection has been released. This method may be overriden by applications to cleanup any database state which may have been created by afterConnect.

### passivateOpenVOs

    public XMLDocument passivateOpenVOs(boolean close)

  Internal: Applications should not call this method.

### activateOpenVOs

    public void activateOpenVOs(XMLDocument out)

  Internal: Applications should not call this method.

### fetchAttributeProperties

    public void fetchAttributeProperties(java.lang.String[] voNames,
                                         java.lang.String[][] attrs,
                                         LocaleContext locale)

  Description copied from interface: `ApplicationModule`
  Fetches all custom properties for the given list of attributes for the named view objects in this application module over to the remote client objects in one network roundtrip. This method is a no-op in when this application module is deployed in local-mode.

  For clients like JClient applications, this method helps in downloading all the attribute properties over to the client side in one roundtrip so that startup of these applications are more performant. Calls to properties methods like getFormat(), getLabel(), etc. on the Attribute definition then, does not go over the network boundary for the attributes that are included in the parameter list.

  Specified by:
    `fetchAttributeProperties` in interface `ApplicationModule`
  Parameters:
    `voNames` - An array of view object names in this application module
    `attrs` - For each view object name, a list of attribute names for which the custom properties need to be brought over to the client side.

### sendServiceMessage

    public ServiceMessage sendServiceMessage(ServiceMessage svcMsgIn)

  Description copied from interface: `SvcMsgSender`
  Sends a service message to `SvcMsgReceiver`.
  Specified by:
    `sendServiceMessage` in interface `SvcMsgSender`
  Parameters:
    `svcMsgIn` - service message to be sent.
  Returns:
    response to the message.

### prepareForPassivation

    protected void prepareForPassivation(Document out,
                                         Element parent)

  Override this method to passivate custom data in the ApplicationModule.
  Parameters:
    `out` - Document in which to create xml nodes.
    `parent` - Element node under which this AM's data is being passivated.

### prepareForActivation

    protected void prepareForActivation(Element amNode)

  Override this method to activate custom data in the ApplicationModule from this AM's xml node. This data would most likely be passivated in the overridden prepareForPassivation()
  Parameters:
    `amNode` - Element node under which this AM's data is being passivated.

### getUserPrincipalName

    public java.lang.String getUserPrincipalName()

  Returns the session user principal name.
  Returns:
    the user principal name.

### getEntityAttributesPermission

    public byte[] getEntityAttributesPermission(java.lang.String entityName)

  Returns the current authenticated user permission for entity attributes.
  Parameters:
    `entityName` - the full name of the entity definition.
  Returns:
    permission values.

### getViewAttributesPermission

    public byte[] getViewAttributesPermission(ViewObject vo)

  Returns the current authenticated user permission for view attributes.
  Parameters:
    `vo` - view object.
  Returns:
    permission values.

### setRemoteAdapter

    public void setRemoteAdapter(ApplicationModuleRemoteAdapter adapter)

### doMessage

    public ServiceMessage doMessage(ServiceMessage msg)

  Description copied from interface: `SvcMsgReceiver`
  Processes a service message sent by `SvcMsgSender`.
  Specified by:
    `doMessage` in interface `SvcMsgReceiver`
  Parameters:
    `msg` - service message coming from `SvcMsgSender`.
  Returns:
    response to the message.

### passivateStateForUndo

    public java.lang.String passivateStateForUndo(java.lang.String id,
                                                  byte[] clientData,
                                                  int flags)

  Description copied from interface: `ApplicationModule`
  Create an application module undo record.

  application module state that is passivated using this method will have transaction scope only -- the passivated state will be removed when a transaction commit/rollback occurs.

  application module state snapshots that are created using this method will be pushed to an LIFO stack. This stack is defined as part of the application module transaction state and as such will be maintained by application module passivation/activation.

  The application developer may specify their own snapshot id by passing an id in for the request. If no id has been specified then an id will be generated by the system and returned. If a snapshot already exists for this transaction with the specified id then the old snapshot will be removed from the snapshot stack.

  The application developer may control whether a persistent snapshot (on-disk) or a transient snapshot (in-memory) is taken with the BC4J session property, `PropertyConstants.ENV_SNAPSHOT_STORE_UNDO`.

  A value of `PropertyConstants.SNAPSHOT_STORE_PERSISTENT` (default) directs the algorithm to create a persistent snapshot (on-disk) for this undo request. The location of the persistent snapshot may further be controlled by the BC4J propery `PropertyConstants.ENV_PASSIVATION_STORE` which accepts values of {file,database}.

  A value of `PropertyConstants.SNAPSHOT_STORE_TRANSIENT` directs the algorithm to create a transient snapshot (in-memory). Transient snapshots are not guaranteed to be maintained in the event of system failure.

  Setting the flags parameter value to `ApplicationModule.PASSIVATE_DEFER_FLAG` allows the snapshot creation to be deferred until the application module is checked in. For typical web-based applications, this means that the snapshot would be created at the end of the request when the application module checkin is invoked.

  Most applications using the application module pool are highly encouraged to use this flag value for performance and memory usage optimization. Deferring the snapshot creation allows one snapshot to be used for both transaction undo and failover support.

  Deferred passivation should not be requested if it is necessary to capture the application module state at the time of the undo request -- a deferred undo request does not guarantee that the passivated state equals the application module state at the time of the undo request.

  Specified by:
    `passivateStateForUndo` in interface `ApplicationModule`
  Parameters:
    `id` - the id which is to be used to identify this undo record. The id should be unique within a transaction. If an id is not specified then an id will be generated by the system and returned.
    `clientData` - a byte array representing any clientData which the invoker wishes to associate with the undo record.
    `flags` - an int representing passivateStateForUndo flags. Valid flags are:

    `ApplicationModule.PASSIVATE_DEFER_FLAG` see the discussion above for more information regarding the use of this flag.

    In order to specify default behaviour the application developer may pass 0 for the flags parameter. Default behaviour is defined as immediate passivation.

### activateStateForUndo

    public byte[] activateStateForUndo(java.lang.String id,
                                       int flags)

  Description copied from interface: `ApplicationModule`
  Restore an application module undo record.

  Activates an application module state which was created using `ApplicationModule.passivateStateForUndo(String, byte[], int)`.

  If the id is not on the undo stack then an exception will be thrown indicating that it is an invalid undo id.

  Invoking this method will remove all those undo records that are above (more recent) than the specified undo record.

  Specified by:
    `activateStateForUndo` in interface `ApplicationModule`
  Parameters:
    `id` - the id of an undo record that was created using `ApplicationModule.passivateStateForUndo(String, byte[], int)`
    `flags` - Valid flags are:

    N/A -- The flags are currently unused. Please pass 0.

### isValidIdForUndo

    public boolean isValidIdForUndo(java.lang.String id)

  Description copied from interface: `ApplicationModule`
  Determines if an id created using `ApplicationModule.passivateStateForUndo(String, byte[], int)` is still valid.

  An id may become invalid if a transaction boundary (commit/rollback) has occured since the id was created.

  Specified by:
    `isValidIdForUndo` in interface `ApplicationModule`
  Parameters:
    `id` - the id of an undo record that was created using `ApplicationModule.passivateStateForUndo(String id, byte[] clientData, int flags)`

### invokeMethod

    public java.lang.Object invokeMethod(java.lang.Object target,
                                         java.lang.String methodName,
                                         java.lang.String[] argTypeNames,
                                         java.lang.Object[] args)

  Specified by:
    `invokeMethod` in interface `WSApplicationModuleMarshaller`

### doPoolMessage

    public ApplicationPoolSvcMsgContext doPoolMessage(ApplicationPoolSvcMsgContext ctx)

  Description copied from interface: `ApplicationModule`
  Internal use only. Applications should not use. Used by the ApplicationPool to send batch application module requests.
  Specified by:
    `doPoolMessage` in interface `ApplicationModule`

### getReleaseLevel

    public int getReleaseLevel()

  Description copied from interface: `ApplicationModule`
  Returns the release level that should be employed by clients of this application module.

  For example, the ADF/BC DataControl will invoke getReleaseLevel() to determine if this application module may be released to the ApplicationPool in SHARED_MANAGED_RELEASE_MODE or if the application module may be released in RESERVED_UNMANAGED_RELEASE_MODE.

  Two release levels are currently supported:

  `RELEASE_LEVEL_MANAGED` Default. Indicates that the application module is in a state that may be managed by BC4J state management service.

  For more information about the BC4J state management service please see the passivation documentation.

  `RELEASE_LEVEL_RESERVED` Indicates that the application module may not be managed by the BC4J state management service. Application modules may specify this release level if they reference session/txn state that may not be recreated by passivation/activation.

  Common examples of state that is not currently managed by the state management service are posted database changes and database locks. Other custom examples may exist.

  Care should be taken that the default RELEASE_LEVEL_MANAGED level is used for most releases. Using a RELEASE_LEVEL_RESERVED level throughout an application could result in scalability issues as application modules accumulate with the accumulation of new sessions.

  If both flags have been specified then RELEASE_LEVEL_RESERVED will take precedence.

  Specified by:
    `getReleaseLevel` in interface `ApplicationModule`
  Returns:
    ApplicationModule.RELEASE_LEVEL_MANAGED or ApplicationModule.RELEASE_LEVEL_RESERVED

### setReleaseLevel

    public void setReleaseLevel(int releaseLevel)

  Specified by:
    `setReleaseLevel` in interface `ApplicationModule`
  See Also:
    `ApplicationModule.getReleaseLevel()`

### syncMarshaller

    public void syncMarshaller(ServiceMessage msg)

  Specified by:
    `syncMarshaller` in interface `WSApplicationModuleMarshaller`

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.