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
Interface ApplicationModule

All Superinterfaces:
  ComponentObject, Properties

All Known Implementing Classes:
  ApplicationModuleImpl, ApplicationModuleImpl, WSApplicationModuleImpl

public interface ApplicationModule
extends ComponentObject

The interface for application modules. An application module is a logical container for coordinated objects related to a particular task with optional programming logic.

Root Application Module and Nested Application Module

An application module may be a root application module or a nested application module. A root application module is not contained in another applicatin module. It provides transaction context for all objects contained in it. It may optionally contain nested application modules. A root application module is created through JDNI calls. See below for details.

A nested application module is contained in another application module. The containing application module is referred to as the parent application module. If one traverses this containership ancestry, one will eventually find the root application module (which does not have a parent application module). A nested application module uses the transaction context provided by the root application module. Thus, data modifications performed in application modules parented by one root application module will commit or rollback together.

Transaction

Associated with the root application module is the `Transaction` object, which provides this transaction context. From any (root or nested) application module, the user can retrieve the transaction object through a call to `getTransaction()`. In reality, `getTransaction()` first locates the root application module and then returns the transaction object from it.

The transaction object manages connection to database and entity caches. Thus, changes made through one view object are visible to other view objects as long as these view objects all parented by the one root application module. In contrast, if two view objects are parented by two separate root application modules, then changes made through the view object will not be seen by the second view object until the changes are committed to database through the first root application module and the second VO executes query (to retrieve the most up-to-date data from database).

Creating Application Module

A root application module is created by:

- Finding the application module home through JNDI.
- Calling `create()` on the application module home.

Here is a sample code to create a root application module:

>         java.util.Hashtable env = new java.util.Hashtable();

>         // Add environment entries into env...

>         javax.naming.Context ic = new InitialContext(env);

>         // 'defName' is the JNDI name for the application module
>         // definition from which the root application module is to
>         // be created
>         String defName = ...;

>         oracle.jbo.ApplicationModuleHome home = ic.lookup(defName);
>         oracle.jbo.ApplicationModule am = home.create();

One creates a nested application module by calling `createApplicationModule` on the parent Application module.

Component Object

As metioned earlier, an application module may contain other nested application modules. In addition, it may contain view objects and view links. View objects enable the user to set up queries to database and retrieve data through them. View links enable the user to related two view objects, such that events occuring on one of them (referred to as master) will cause the other view object (referred to as detail) to refresh its result set based on master's data values. These objects that an application module may contain are referred to as component objects.

A component object may be included in an application module during design time or be created in it during runtime. Component objects included during design time are referred to as static component objects. Those that are created during runtime as dynamic component objects. Dynamic component objects are created through a call to a `create...` method.

Each component object (whether static or dynamic) is given a name within the application module. This name can be used to locate a component object. * `find...` methods are provided for that purpose.

When using a `find...` method, the user may pass in a relative or absolute component object name. A relative name causes the application module to look for the component object starting from this application module. An absolute name causes the search to start from the root application module.

Application Module Custom Methods

The user may attach custom methods to an application module. BC4J Design Time tools allows one to declare a method at the application module interface level. The `ApplicationModule` interface is extended to include declaration fo such a method. Then, the user implements the method in the middle iter implementation class (which extends `oracle.jbo.server.ApplicationModuleImpl`). For the client tier, BC4J Design Time tools generate a client tier proxy for that method (based on the user's choice of cli-tier-to-middle-tier interaction platform). This enables the user to invoke the custom method in the client tier (3 tier mode) or directly in the middle iter (2 tier mode).

For the middle tier, `ApplicationModuleImpl`. is the base implementation of this interface.

The framework provides an `ApplicationPool` interface that clients can use to manage and share a pool of application modules.

Application Module Definition

Behind every instance of application module is a definition (or metaobject) that describes the application module. One can look at the application module definition as the factory for application module instance. Another way of looking at this is that the definition objects is akin to the Java class (in that the class describes instances and in that one uses the class to create instances).

An application module definition is identified by its full name. The definition's full name is qualified by the package in which the definition resides (just like a Java class).

In the middle tier, application module definitions are managed by `oracle.jbo.server.MetaObjectManager`. One can find a specific definition object by issuing:

>         String defName = ...;
>         oracle.jbo.server.ApplicationModuleDefImpl def;

>         def = oracle.jbo.server.ApplicationModuleDefImpl.findDefObject(defName);

where `defName` is a fully (package) qualified application module definition name.

The user has the option of using the default application module definition or a custom application module definition. The default application module definition produces application module instances that do not have any custom methods or static component objects.

If the user wishes to include custom methods or static component objects, he should define a custom application module definition in BC4J design time. The default application module definition has a special definition name (see `DEFAULT_DEF_FULL_NAME` below).

Since:
  JDevloper 3.0
See Also:
  `ApplicationModuleHome`, `ViewObject`, `ViewLink`, `Transaction`, `ApplicationPool`, `ApplicationModuleImpl`, `ApplicationModuleDefImpl`, `MetaObjectManager`

Field Summary
`static int` | `ACTIVATE_CLIENT_FLAG`
`static int` | `ACTIVATE_REMOVE_FLAG` An activation flag.
`static int` | `ACTIVATE_SKIP_RESTORE_VO_FROM_DEF` An activation flag.
`static int` | `ACTIVATE_TRANSIENT_FLAG`
`static int` | `ACTIVATE_UNDO_FLAG`
`static java.lang.String` | `DEFAULT_DEF_FULL_NAME` The name of the default application module definition (one that represents `oracle.jbo.server.ApplicationModuleDefImpl`).
`static java.lang.String` | `DEFAULT_ROOT_APP_MOD_NAME` The default name of root application module.
`static int` | `PASSIVATE_DEFER_FLAG` A passivate flag.
`static int` | `PASSIVATE_HINT_FLAG` An internal passivation flag.
`static byte` | `PASSIVATE_TO_DATABASE` Used by `setStoreForPassivate` to serialize the state of the application module's session and any cached changes to the database.
`static byte` | `PASSIVATE_TO_FILE` Used by `setStoreForPassivate` to serialize the state of the application module's session and any cached changes to a file.
`static byte` | `PASSIVATE_TO_MEMORY` Used by `setStoreForPassivate` to serialize the state of the application module's session and any cached changes to memory.
`static int` | `PASSIVATE_TO_STACK_FLAG` An internal passivation flag.
`static int` | `PASSIVATE_TRANSIENT_FLAG` A passivation/activation flag.
`static int` | `PASSIVATE_UNDO_FLAG` An internal passivate flag.
`static int` | `RELEASE_LEVEL_MANAGED`
`static int` | `RELEASE_LEVEL_RESERVED`
`static int` | `REMOVE_SNAPSHOT` Deprecated. use `ACTIVATE_REMOVE_FLAG` instead
`static int` | `RESET_CLIENT_ONLY_FLAG` May be used to indicate that reset should be performed on the client tier only.
`static int` | `RESET_INTERNAL_FLAG` A reset flag.
`static int` | `RESET_MANAGE_SNAPSHOTS` A reset flag.
`static int` | `RESET_RELOAD_FLAG` A reset flag.
`static int` | `RESET_ROLLBACK_FLAG` A reset flag.
`static int` | `SYNC_BATCH` Deprecated. deprecated since 9.0.5. This mode should not be used by client. Batch mode operations should be performed through working set objects instead.
`static int` | `SYNC_IMMEDIATE` `SYNC_...` constants are used to control how often data changes in the client tier are flushed to the middle tier cache.
`static int` | `SYNC_LAZY` `SYNC_...` constants are used to control how often data changes in the client tier are flushed to the middle tier cache.

Method Summary
`byte[]` | `activateState(int id, boolean remove)` Deprecated. deprecated since 9.0.5. Use `activateState(int, SessionData, int)` with the PERSISTNENT_SNAPSHOT bit set and a null SessionData instead.
`byte[]` | `activateState(int id, boolean remove, SessionData info)` Deprecated. deprecated since 9.0.5. Use `activateState(int, SessionData, int)` with the PERSISTNENT_SNAPSHOT bit set instead.
`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.
`void` | `addWarning(JboWarning warn)` Adds a warning message.
`void` | `clearVOCaches(java.lang.String entityName, boolean recurse)` Clears the view object cache for all view objects that use an entity object identified by `entityName`.
`ApplicationModule` | `createApplicationModule(java.lang.String amName, java.lang.String defName)` Creates a nested application module in this application module from the application module definition.
`ComponentObject` | `createComponentObject(java.lang.String coName, java.lang.String coDefName)` Creates a component object in this application module from the component object definition.
`ViewLink` | `createViewLink(java.lang.String vlName, java.lang.String defName, ViewObject master, ViewObject detail)` Creates a view link in this application module from the view link definition.
`ViewLink` | `createViewLinkBetweenViewObjects(java.lang.String vlName, java.lang.String accessorName, ViewObject master, AttributeDef[] srcAttrs, ViewObject detail, AttributeDef[] destAttrs, java.lang.String assocClause)` Creates a view link in this application module.
`ViewLink` | `createViewLinkFromEntityAssocName(java.lang.String vlName, java.lang.String entityAssocName, ViewObject master, ViewObject detail)` Creates a view link in this application module from an entity association.
`ViewObject` | `createViewObject(java.lang.String voName, java.lang.String defName)` Creates a view object in this application module from the view definition.
`ViewObject` | `createViewObjectFromQueryClauses(java.lang.String vuName, java.lang.String eoName, java.lang.String selectClause, java.lang.String fromClause, java.lang.String whereClause, java.lang.String orderByClause)` Creates a view object in this application module from an entity Object and additional SQL clauses.
`ViewObject` | `createViewObjectFromQueryStmt(java.lang.String vuName, java.lang.String sqlStatement)` Creates a view object in this application module based on a SQL statement.
`ViewObject` | `createViewObjectOnEntity(java.lang.String voName, java.lang.String eoName)`
`ViewObject` | `createViewObjectOnRowSet(java.lang.String voName, RowSet rs)`
`ApplicationPoolSvcMsgContext` | `doPoolMessage(ApplicationPoolSvcMsgContext ctx)` Internal use only.
`void` | `fetchAttributeProperties(java.lang.String[] voNames, java.lang.String[][] voAttrNames, 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 coName)` Finds the named component object.
`RowSetIterator` | `findRSIForEntity(RowSetIterator[] rsis, int eRowHandle)` Finds the `RowSetIterator` associated with the specified entity 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 entityName, java.lang.String[] attrName)` 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)` Internal: Applications should not use this method. Given a view object name, use findViewObject(String name) to find the view object and set it's named bind parameters with the values passed in the 'params' argument.
`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 fromDef)` Returns an array of names of the nested application modules in this application module.
`JboExceptionHandler` | `getExceptionHandler()`
`int` | `getMostRecentStackId()` Internal: Applications should not use this method.
`int` | `getReleaseLevel()` Returns the release level that should be employed by clients of this application module.
`Session` | `getSession()` Gets the application module's session.
`ClientDocument` | `getStyles(java.lang.String name)` Gets the style definition from an XML file in 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()` Gets this application module's database transaction.
`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 fromDef)` Returns an array of names of the view links 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 fromDef)` Returns an array of names of the view objects in this application module.
`boolean` | `isRoot()` Returns `true` if this application module is a root application module.
`boolean` | `isValidIdForUndo(java.lang.String id)` Determines if an id created using `passivateStateForUndo(String, byte[], int)` is still valid.
`int` | `passivateState(byte[] clientData)` Deprecated. deprecated since 9.0.5. Use `passivateState(byte[])` with the PERSISTNENT_SNAPSHOT bit set instead.
`int` | `passivateState(byte[] clientData, int flags)` Internal: Applications should not use this method.
`int` | `passivateState(int id, byte[] clientData)` Deprecated. deprecated since 9.0.5. Use `passivateState(int, byte[], int)` with the PASSIVATE_TRANSIENT_FLAG not set instead.
`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.
`void` | `prepareSession(SessionData info)` Internal: Applications should not use this method.
`void` | `removeState(int id)` Internal: Applications should not use this method.
`int` | `reservePassivationId()` Deprecated. deprecated since 9.0.5. Use `reserveSnapshotId(int)` with the PERSISTNENT_SNAPSHOT bit set instead.
`int` | `reserveSnapshotId(int flags)` Internal: Applications should not use this method.
`void` | `resetState(boolean reload)` Deprecated. since 9.0.5. Use `resetState(int)` with the `RESET_RELOAD_FLAG` enabled instead.
`void` | `resetState(int flags)` Advanced use only
`void` | `setExceptionHandler(JboExceptionHandler hndlr)` Sets the exception handler for this application module.
`void` | `setReleaseLevel(int releaseLevel)`
`void` | `setStoreForPassiveState(byte storageType)` Internal: Applications should not use this method.
`void` | `setStyles(java.lang.String name, ClientDocument clientDocument)` Saves a style definition XML file in the middle tier.
`void` | `setSyncMode(int mode)` Sets the data synchronization mode between the client and the middle tier.
`void` | `sync()` In 3 tier mode, this method enumerates through all row sets contained in this application module and flushes any changes pending in these row sets to the middle tier.
`java.lang.Object[]` | `transformExceptionParams(ViewObject[] vos, java.lang.String entityName, java.lang.String exceptionClassName, 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.

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

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

Field Detail

### DEFAULT_ROOT_APP_MOD_NAME

    public static final java.lang.String DEFAULT_ROOT_APP_MOD_NAME

  The default name of root application module.
  See Also:
    Constant Field Values

### DEFAULT_DEF_FULL_NAME

    public static final java.lang.String DEFAULT_DEF_FULL_NAME

  The name of the default application module definition (one that represents `oracle.jbo.server.ApplicationModuleDefImpl`). This definition object produces instances of `oracle.jbo.server.ApplicationModuleImpl`, which do not have any custom methods or static component objects.
  See Also:
    Constant Field Values

### REMOVE_SNAPSHOT

    public static final int REMOVE_SNAPSHOT

  Deprecated. use `ACTIVATE_REMOVE_FLAG` instead
  An activation flag. Setting this bit when performing activation will direct the activation framework to remove the snapshot record after activation.
  See Also:
    Constant Field Values

### PASSIVATE_TRANSIENT_FLAG

    public static final int PASSIVATE_TRANSIENT_FLAG

  A passivation/activation flag. Setting this bit when performing passivation/activation related activities will direct the passivation framework to store snapshots in memory only. Please see `passivateState(byte[], int)` and `activateState(int, SessionData, int)` for more information.
  See Also:
    Constant Field Values

### PASSIVATE_DEFER_FLAG

    public static final int PASSIVATE_DEFER_FLAG

  A passivate flag. Setting this bit when performing passivation for undo will indicate that passivation should be deferred until the next passivation request.

  Setting the flags parameter value to `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.

  See Also:
    Constant Field Values

### PASSIVATE_UNDO_FLAG

    public static final int PASSIVATE_UNDO_FLAG

  An internal passivate flag. Indicates that passivateState has been invoked by the undo framework. If this flag is not set then it is assumed that passivateState has been invoked directly by an application module client. This flag may be used by subclassing ApplicationModuleImpl classes to determine the source of a passivateState invocation.
  See Also:
    Constant Field Values

### PASSIVATE_HINT_FLAG

    public static final int PASSIVATE_HINT_FLAG

  An internal passivation flag. Indicates to passivation that it should passivate if a deferred passivation request is pending. Otherwise do nothing.
  See Also:
    Constant Field Values

### PASSIVATE_TO_STACK_FLAG

    public static final int PASSIVATE_TO_STACK_FLAG

  An internal passivation flag. Indicates to passivation that the passivation record should be pushed to the application module passivation stack. This flag is automatically enabled when using passivateForUndo. This flag is not typically enabled when passivating for failover.
  See Also:
    Constant Field Values

### ACTIVATE_TRANSIENT_FLAG

    public static final int ACTIVATE_TRANSIENT_FLAG

  See Also:
    Constant Field Values

### ACTIVATE_REMOVE_FLAG

    public static final int ACTIVATE_REMOVE_FLAG

  An activation flag. Setting this bit when performing activation will direct the activation framework to remove the snapshot record after activation.
  See Also:
    Constant Field Values

### ACTIVATE_CLIENT_FLAG

    public static final int ACTIVATE_CLIENT_FLAG

  See Also:
    Constant Field Values

### ACTIVATE_UNDO_FLAG

    public static final int ACTIVATE_UNDO_FLAG

  See Also:
    Constant Field Values

### ACTIVATE_SKIP_RESTORE_VO_FROM_DEF

    public static final int ACTIVATE_SKIP_RESTORE_VO_FROM_DEF

  An activation flag. Setting this bit when performing activation will prevent activation from restoring view objects from their def objects before activation. This is only necessary when not resetting before activation.
  See Also:
    Constant Field Values

### RESET_ROLLBACK_FLAG

    public static final int RESET_ROLLBACK_FLAG

  A reset flag. Indicates that reset should first rollback the application module.
  See Also:
    Constant Field Values

### RESET_RELOAD_FLAG

    public static final int RESET_RELOAD_FLAG

  A reset flag. Indicates that reset should eagerly reload the application module.
  See Also:
    Constant Field Values

### RESET_MANAGE_SNAPSHOTS

    public static final int RESET_MANAGE_SNAPSHOTS

  A reset flag. Indicates that reset should not destroy the persistent snapshots that are managed by the snapshot stack. Used internally by the applicaiton pool.
  See Also:
    Constant Field Values

### RESET_CLIENT_ONLY_FLAG

    public static final int RESET_CLIENT_ONLY_FLAG

  May be used to indicate that reset should be performed on the client tier only.
  See Also:
    Constant Field Values

### RESET_INTERNAL_FLAG

    public static final int RESET_INTERNAL_FLAG

  A reset flag. Indicates that the reset was invoked for internal use. DBTransactionImpl invokes reset in a number of different places to ensure that the txn application module is initialized properly.

  Applications may use this flag to determine if the resetState call was made internally or as the result of a lifecycle event. An example of a lifecycle event may be an unmanaged ApplicationPool release or an ApplicationPool recycle event.

  See Also:
    Constant Field Values

### RELEASE_LEVEL_MANAGED

    public static final int RELEASE_LEVEL_MANAGED

  See Also:
    Constant Field Values

### RELEASE_LEVEL_RESERVED

    public static final int RELEASE_LEVEL_RESERVED

  See Also:
    Constant Field Values

### SYNC_LAZY

    public static final int SYNC_LAZY

  `SYNC_...` constants are used to control how often data changes in the client tier are flushed to the middle tier cache. As such, these constants only affect 3 tier mode and not 2 tier. In 2 tier mode, changes are applied to cache immediately regardless of the sync mode, i.e., the system effectively runs in the `SYNC_IMMEDIATE` mode.

  `SYNC_LAZY` means that attribute changes are kept in the client tier until an operation forces changes to be flushed. Examples of such operations are: transaction commit, the currency movement (`next()`, `previous()`, ...), etc.

  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.

  See Also:
    `getSyncMode()`, `setSyncMode(int)`, Constant Field Values

### SYNC_IMMEDIATE

    public static final int SYNC_IMMEDIATE

  `SYNC_...` constants are used to control how often data changes in the client tier are flushed to the middle tier cache. As such, these constants only affect 3 tier mode and not 2 tier. In 2 tier mode, changes are applied to cache immediately regardless of the sync mode, i.e., the system effectively runs in the `SYNC_IMMEDIATE` mode.

  `SYNC_IMMEDIATE` means that attribute changes from the client tier are applied (flushed) immediately to the middle tier. to be flushed is issued. Examples of such operations are: if the transaction is committed, if the currency moves (`next()`, `previous()`, ...), if etc.

  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.

  See Also:
    `getSyncMode()`, `setSyncMode(int)`, Constant Field Values

### SYNC_BATCH

    public static final int SYNC_BATCH

  Deprecated. deprecated since 9.0.5. This mode should not be used by client. Batch mode operations should be performed through working set objects instead.
  See Also:
    Constant Field Values

### PASSIVATE_TO_DATABASE

    public static final byte PASSIVATE_TO_DATABASE

  Used by `setStoreForPassivate` to serialize the state of the application module's session and any cached changes to the database. Database is the default target for `setStoreForPassivate`.
  See Also:
    `setStoreForPassiveState(byte)`, Constant Field Values

### PASSIVATE_TO_FILE

    public static final byte PASSIVATE_TO_FILE

  Used by `setStoreForPassivate` to serialize the state of the application module's session and any cached changes to a file.
  See Also:
    `setStoreForPassiveState(byte)`, Constant Field Values

### PASSIVATE_TO_MEMORY

    public static final byte PASSIVATE_TO_MEMORY

  Used by `setStoreForPassivate` to serialize the state of the application module's session and any cached changes to memory.
  See Also:
    `setStoreForPassiveState(byte)`, Constant Field Values

Method Detail

### createApplicationModule

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

  Creates a nested application module in this application module from the application module definition. The application module definition is identified by the `defName` parameter.

  Example code:

          ApplicationModule nestedAM = parentAM.createApplicationModule("MyAM", "package1.Package1Module");

  Parameters:
    `amName` - the name to be assigned to the application module. If `null`, a system generated name is assigned.
    `defName` - the name of the application module definition from which the new nested application module is to be created. It must be a fully qualified definition name (including the package name). If `DEFAULT_DEF_FULL_NAME` or `null` is passed, a generic application module (one without custom code or static component objects) is created.
  Returns:
    a new nested application module.
  Throws:
    `InvalidObjNameException` - if `amName` is an invalid name. `amName` must be a vaild Java name.
    `NameClashException` - if a nested application module of `amName` already exists in this application module. The application module name must be unique.
    `NoDefException` - if application module definition (named by the `defName` parameter) was not found. Make sure `defName` is fully qualified with the package name.
    `PersistenceException` - if some error was found while loading the application module definition.

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

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

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

  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 application modules, 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)`.

  If this method is called with `loadedOnes = true` and `fromDef = true`, both loaded and not-yet-loaded application module names are returned. No duplicate name is returned. Note that loaded application modules include dynamically created ones.

  Parameters:
    `inclLoadedOnes` - if `true`, loaded ones are returned.
    `fromDef` - if `true`, names of the child application modules from the application module definition are returned. Some of these child AMs could have already been loaded and some may have not yet been loaded.
  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]`.

### sync

    public void sync()

  In 3 tier mode, this method enumerates through all row sets contained in this application module and flushes any changes pending in these row sets to the middle tier. Note that if this application module's sync mode is `SYNC_IMMEDIATE`, no pending changes would be found, and `sync()` will effectively be a no-op.

  In 2 tier mode, this method is a no-op, as all changes are applied immediately.

### setSyncMode

    public void setSyncMode(int mode)

  Sets the data synchronization mode between the client and the middle tier. There are two sync modes: `SYNC_LAZY` and `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.

  Parameters:
    `mode` - the new synchronization mode: `SYNC_LAZY` or `SYNC_IMMEDIATE`.
  See Also:
    `getSyncMode()`, `SYNC_LAZY`, `SYNC_IMMEDIATE`

### getSyncMode

    public int getSyncMode()

  Returns the sync mode for this application module.

  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.

  Returns:
    the sync mode: `SYNC_LAZY` or `SYNC_IMMEDIATE`.
  See Also:
    `setSyncMode(int mode)`, `SYNC_LAZY`, `SYNC_IMMEDIATE`

### createViewObject

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

  Creates a view object in this application module from the view definition. The view definition is identified by the `defName` parameter.

  Example code:

          ViewObject vo = am.createViewObject("MyVO", "package1.DeptView");

  Parameters:
    `voName` - the name to be assigned to the view object. If `null`, a system generated name is assigned.
    `defName` - the name of the view definition from which the new view object is to be created. It must be a fully qualified name (including the package name).
  Returns:
    a new view object.
  Throws:
    `InvalidObjNameException` - if `voName` is an invalid name. `voName` must be a vaild Java name.
    `NameClashException` - if a view object of `voName` already exists in this application module. The view object name must be unique.
    `NoDefException` - if view definition (named by the `defName` parameter) was not found. Make sure `defName` is fully qualified with the package name.
    `PersistenceException` - if some error was found while loading the view definition.

### createViewObjectFromQueryClauses

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

  Creates a view object in this application module from an entity Object and additional SQL clauses. The returning view object will have that entity object as its sole entity object base. This method cannot create a view object that joins two entity objects. The view object's attributes will be those that are mapped to the entity object's attributes.

  For example, suppose we have an entity object named `Emp` in a package named `package1`. The following code block creates a view object using this method:

          ViewObject vo = am.createViewObjectFromQueryClauses("MyVO",
               "package1.Emp",      // Fully qualified EO name
               "E.ENAME as EmpName, E.EMPNO as EmpNo",  // select clause
               "EMP E",             // from clause
               "E.DEPTNO = 10",     // where clause
                null);              // order by clause

  Internally, this methods create a temporary view definition from the entity object and sets the select, from, where, and order-by clauses of the view definition. Then, it uses that view definition to create the view object.

  Parameters:
    `vuName` - the name to be assigned the view object. If `null`, a system generated name is assigned.
    `eoName` - the name of the entity object from which the new view object is to be derived.
    `selectClause` - a SQL statement SELECT clause. The name or alias of each column must match the name of the corresponding entity object's attribute. In the above example code, "ENAME" and "EMPNO" are database column names, and "EmpName" and "EmpNo" are entity object's attribute names.
    `fromClause` - a SQL statement FROM clause.
    `whereClause` - a SQL statement WHERE clause. If `null` no where clause is established, i.e., all rows from the database table/view are retrieved.
    `orderByClause` - a SQL statement ORDER-BY clause. If `null` no order-by clause is established.
  Returns:
    a new view object.
  Throws:
    `InvalidObjNameException` - if `voName` is an invalid name. `voName` must be a vaild Java name.
    `NameClashException` - if a view object of `voName` already exists in this application module. The view object name must be unique.
    `NoDefException` - if entity object (named by the `eoName` parameter) was not found. Make sure `eoName` is fully qualified with the package name.
    `PersistenceException` - if some error was found while loading the entity definition.
    `SQLStmtException` - if a SQL syntax problem has been discovered while attempting to parse the SQL clauses.

### createViewObjectOnEntity

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

### createViewObjectOnRowSet

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

### createViewObjectFromQueryStmt

    public ViewObject createViewObjectFromQueryStmt(java.lang.String vuName,
                                                    java.lang.String sqlStatement)

  Creates a view object in this application module based on a SQL statement. The returning view object does not have any entity object base and all its attributes are `ATTR_SQL_DERIVED` kind attributes. Thus, all attributes are read-only.

  Example code:

          ViewObject vo = am.createViewObjectFromQueryStmt("MyVO",
               "SELECT EMP.ENAME as EmpName, EMP.MGR as EmpMgr FROM EMP");

  In this example, the resulting view object will have two attributes, named `EmpName` and `EmpMgr`.

  Internally, this method create a temporary view definition with no entity object base and maps database columns to attribute definitions. Then, it uses that view definition to create the view object.

  Parameters:
    `vuName` - the name to be assigned the view object. If `null`, a system generated name is assigned.
    `sqlStatement` - the SQL query statement for the view object.
  Returns:
    a new view object.
  Throws:
    `InvalidObjNameException` - if `voName` is an invalid name. `voName` must be a vaild Java name.
    `NameClashException` - if a view object of `voName` already exists in this application module. The view object name must be unique.
    `SQLStmtException` - if a SQL syntax problem has been discovered while attempting to parse the SQL statement.

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

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

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

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

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

  If this method is called with `loadedOnes = true` and `fromDef = true`, both loaded and not-yet-loaded view object names are returned. No duplicate name is returned. Note that loaded view objects include dynamically created ones.

  Parameters:
    `inclLoadedOnes` - if `true`, loaded ones are returned.
    `fromDef` - if `true`, names of the view objects from the application module definition are returned. Some of these VOs could have already been loaded and some may have not yet been loaded.
  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]`.

### createViewLink

    public ViewLink createViewLink(java.lang.String vlName,
                                   java.lang.String defName,
                                   ViewObject master,
                                   ViewObject detail)

  Creates a view link in this application module from the view link definition. The view link definition is identified by the `defName` parameter.

  `master` and `detail` identifies two view objects that will linked by this new view link.

  For example, assume that during design time, the user used the design time view object Wizard to create two view objects, `DeptView` and `EmpView` inside of a package named `package1`. Then, assume that the user invoked the view link wizard to create a view link definition (in the same package) named `DeptEmpViewLink`, that correlates the `DeptNo` attribute of `DeptView` to the `DeptNo` attribute of `EmpView`.

  Given these, the user can use the code block like the following to create in this application module (represented by `am`) two view objects and a view link programmatically (during runtime):

          ViewObject voDept = am.createViewObject("MyDeptVO", "package1.DeptView");
          ViewObject voEmp = am.createViewObject("MyEmpVO", "package1.EmpView");

          ViewLink vl = am.createViewLink("MyDeptEmpLink", "package1.DeptEmpViewLink",
                                          voDept, voEmp);

  This will set up a master-detail relationship between `voDept` and `voEmp`. Whenever `voDept`'s currency moves, `voEmp`'s result set will be refreshed to show employees that work in the department.

  This method verifies that the view objects passed in match the view link definition. Specifically, in the above example, `createViewLink()` checks to ensure that the master (`voDept`) is an instance of `package1.DeptView` and that the detail (`voEmp`) is an instance of `package1.EmpView`. If match fails, an error (`InvalidParamException`) is reported, as the user tried to set up a view link between two view objects where the View Link definition does not match the view link definitions of master and detail.

  One exception to this match rule is that `createViewLink()` allows the user to reverse the view link direction. Thus, in the above example, the following would have succeeded:

          ViewLink vl = am.createViewLink("MyEmpDeptLink", "package1.DeptEmpViewLink",
                                          voEmp, voDept);

  Note that in the above code block, `voEmp` is the master and `voDept` is the detail. The view link definition is used in the reverse direction.

  Parameters:
    `vlName` - the name to be assigned to the view link. If `null`, a system generated name is assigned.
    `defName` - the name of the link definition from which the new view link is to be created. It must be a fully qualified name (including the package name).
    `master` - the view object that is to play the role of master.
    `detail` - the view object that is to play the role of detail.
  Returns:
    a new view link.
  Throws:
    `InvalidObjNameException` - if `vlName` is an invalid name. `vlName` must be a vaild Java name.
    `NameClashException` - if a view link of `vlName` already exists in this application module. The view link name must be unique.
    `NoDefException` - if view link definition (named by the `defName` parameter) was not found. Make sure `defName` is fully qualified with the package name.
    `PersistenceException` - if some error was found while loading the view link definition.
    `InvalidParamException` - (1) if `master` or `detail` is `null` (2) if `master` and `detail` represent the same view object (circular view link is disallowed) (3) if `master` and `detail`'s definitions do not match the view link definition. See the above discussion for more info.
    `InvalidOperException` - if a recursive view link chain is found. Suppose we have three view objects, VO_A, VO_B, VO_C. Suppose we have view links that link VO_A to VO_B, VO_B to VO_C, and VO_C back to VO_A. Then, we have a recursive view link chain. This is disallowed and reported as an error.
  See Also:
    `createViewObject(String, String)`

### createViewLinkFromEntityAssocName

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

  Creates a view link in this application module from an entity association. The returning view link will use the entity association's definition to build a link between the two Viwe Objects.

  For example, suppose we have two entity objects in package `package1`: `Dept` and `Emp`. An entity association `DeptEmpAssoc` is created between the two entity objects relating the `Deptno` attribute. Two view objects are defined on these entity objects, `DeptView` and `EmpView`.

  The following code creates two view objects in this application module and link them, using `DeptEmpAssoc`:

          ViewObject voDept = am.createViewObject("MyDeptVO", "package1.DeptView");
          ViewObject voEmp = am.createViewObject("MyEmpVO", "package1.EmpView");

          ViewLink vl = am.createViewLinkFromEntityAssocName("MyDeptEmpLink",
                              "package1.DeptEmpAssoc",
                              voDept, voEmp);

  This will set up a master-detail relationship between `voDept` and `voEmp`. Whenever `voDept`'s currency moves, `voEmp`'s result set will be refreshed to show employees that work in the department.

  Internally, this method creates a temporary view link definition from the entity association and uses it to create the view link.

  This method verifies that the view objects passed in match the entity association definition. Specifically, in the above example, `createViewLinkFromEntityAssocName()` checks to ensure that the master (`voDept`) uses the `Dept` entity object as one of its entity bases and the detail (`voEmp`) uses the `Emp` entity object as one of its entity bases. If match fails, an error (`InvalidParamException`) is reported, as the user tried to set up a view link between two view objects where the entity association is unable to relate the two view objects.

  The primary difference between `createViewLink(String, String, ViewObject, ViewObject)` and `createViewLinkFromEntityAssocName` is that the former requires the view link definition name, and the latter requires the entity association name.

  Parameters:
    `vlName` - the name to be assigned to the view link. If `null`, a system generated name is assigned.
    `entityAssocName` - the name of the entity association from which the new view link is to be derived. It must be a fully qualified name (including the package name).
    `master` - the view object that is to play the role of master.
    `detail` - the view object that is to play the role of detail.
  Returns:
    a new view link.
  Throws:
    `InvalidObjNameException` - if `vlName` is an invalid name. `vlName` must be a vaild Java name.
    `NameClashException` - if a view link of `vlName` already exists in this application module. The view link name must be unique.
    `NoDefException` - if entity association (named by the `entityAssocName` parameter) was not found. Make sure `entityAssocName` is fully qualified with the package name.
    `PersistenceException` - if some error was found while loading the entity association.
    `InvalidParamException` - (1) if `master` or `detail` is `null` (2) if `master` and `detail` represent the same view object (circular view link is disallowed) (3) if `master` and `detail`'s definitions do not match the entity association's definition. See the above discussion for more info.
    `InvalidOperException` - if a recursive view link chain is found. Suppose we have three view objects, VO_A, VO_B, VO_C. Suppose we have view links that link VO_A to VO_B, VO_B to VO_C, and VO_C back to VO_A. Then, we have a recursive view link chain. This is disallowed and reported as an error.
  See Also:
    `createViewObject(String, String)`

### createViewLinkBetweenViewObjects

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

  Creates a view link in this application module. This view link is not created from either a view link definition or an entity association. Rather, all required information are passed as parameters, and the view link is created based on the info. The user must supply the following info:
  - Master view object - the view object that is to play the role of master.
  - Detail view object - the view object that is to play the role of detail.
  - Source attributes - One or more attributes from the master view object to be related to the destination attributes.
  - Destination attributes - One or more attribute from the detail view object to be related to the source attributes. Note that the source/destination attribute arrays must have the same number of elements.
  - View link accessor name - Optionally, the user can supply a name by which the related detail row set can be retrieved as an attribute. More on this below...
  - Association clause - The user can override the default association clause to be generated by BC4J by supply his custom clause.

  For example, suppose we have two view objects in package `package1`: `DeptView` and `EmpView`. Each of them has an attribute named `Deptno`.

  The following code creates two view objects in this application module and link them by the `Deptno` attribute:

          ViewObject voDept = am.createViewObject("MyDeptVO", "package1.DeptView");
          ViewObject voEmp = am.createViewObject("MyEmpVO", "package1.EmpView");

          AttributeDef[] deptLinkAttrs = new AttributeDef[] { voDept.findAttributeDef("Deptno") };
          AttributeDef[] empLinkAttrs = new AttributeDef[] { voEmp.findAttributeDef("Deptno") };

          ViewLink vl = am.createViewLinkFromEntityAssocName("MyDeptEmpLink",
                              "Employees",
                              voDept, deptLinkAttrs,
                              voEmp, empLinkAttrs,
                              null);

  This will set up a master-detail relationship between `voDept` and `voEmp`. Whenever `voDept`'s currency moves, `voEmp`'s result set will be refreshed to show employees that work in the department.

  Using the Association Clause
  This view link will generate a SQL clause like `EMP.DEPTNO=?` on `voEmp`. The `Deptno` value of the current row in `voDept` (master) is bound into the bind variable ('?'). This results in limiting query on `voEmp` to employees whose `Deptno` equals the current Dept's `Deptno`.

  By supplying a `non-null` association clause (the last parameter), the user can override the default SQL clause and replace it with his. For example, if he wishes to include only employees whose JOB is ANALYST, he can supply the following `assocClause`: `EMP.DEPTNO=? AND EMP.JOB='ANALYST'`.

  Using the Accessor Name
  If the user supplies a `non-null` `accessorName` (the second parameter), a dynamic attribute is added to `master` view object which allows the user retrieve related rows from a master row.

  In the above code example, a dynamic attribute "Employees" is added to `voDept`, such that if the user retrieve that attribute on a row the came from `voDept`, it will return a row set of Emp's that are related to that row.

  The code example below retrieves all rows from `voDept` and for each Dept row, retrieves its employees by using the "Employees" attribute and prints their names.

          Row deptRow;

          while ((deptRow = voDept.next()) != null)
          {
             System.out.println("Dept: " + deptRow.getAttribute("Dname"));

             RowSet emps = (RowSet) deptRow.getAttribute("Employees");
             Row empRow;

             while ((empRow = emps.next()) != null)
             {
                System.out.println("  Emp: " + empRow.getAttribute("Ename"));
             }
          }

  Parameters:
    `vlName` - the name to be assigned to the view link. If `null`, a system generated name is assigned.
    `accessorName` - the name to be given to the dynamic attribute to be added to master view object. Given a row from the master view object, the user can retrieve the attribute of this name to get a row set of related rows from the detail view object. See the above discussions for more info. If `null`, no dynamic attribute is added.
    `master` - the view object that is to play the role of master.
    `srcAttrs` - an array of attributes from master view object to be related to detail.
    `detail` - the view object that is to play the role of detail.
    `destAttrs` - an array of attributes from detail view object to be related to master.
    `assocClause` - a custom association clause. See the above discussions for more info. If `null`, system generated SQL clause will be used.
  Returns:
    a new view link.
  Throws:
    `InvalidObjNameException` - (1) if `vlName` is an invalid name. `vlName` must be a vaild Java name. (2) if `accessorName` is an invalid name. `accessorName` must be valid Java name.
    `NameClashException` - (1) if a view link of `vlName` already exists in this application module. The view link name must be unique. (2) if an attribute of `accessorName` already exists in the master view object. The accessor (attribute) name must be unique.
    `InvalidParamException` - (1) if `master` or `detail` is `null` (2) if `master` and `detail` represent the same view object (circular view link is disallowed)
    `InvalidOperException` - if a recursive view link chain is found. Suppose we have three view objects, VO_A, VO_B, VO_C. Suppose we have view links that link VO_A to VO_B, VO_B to VO_C, and VO_C back to VO_A. Then, we have a recursive view link chain. This is disallowed and reported as an error.
  See Also:
    `createViewObject(String, String)`, `StructureDef.findAttributeDef(String)`, `RowIterator.next()`, `AttributeList.getAttribute(String)`

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

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

### 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 objects that are not yet loaded, use ``getViewLinkNames(boolean, boolean)``.

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

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

  If this method is called with `loadedOnes = true` and `fromDef = true`, both loaded and not-yet-loaded view link names are returned. No duplicate name is returned. Note that loaded view links include dynamically created ones.

  Parameters:
    `inclLoadedOnes` - if `true`, loaded ones are returned.
    `fromDef` - if `true`, names of the view links from the application module definition are returned. Some of these VLs could have already been loaded and some may have not yet been loaded.
  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]`.

### createComponentObject

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

  Creates a component object in this application module from the component object definition. The component object definition is identified by the `defName` parameter.

  Example code:

          ComponentObject vo = am.createComponentObject("MyCO", "package1.MyComponentDef");

  A component object is a generic object that an application module can contain. A Comonent object is any object that implements the `ComponentObject` interface. In particular, `ViewObject` and `ViewLink` implement the `ComponentObject` interface.

  Thus, this method enables the user to build a custom `ComponentObject` and have it be managed by application module. Specificially, he must first implement a Java class that implements `ComponentObject`.

  Then, as is the case with view objects and view links, he must build a component object definition (an XML file) reachable from the class path. (Note that for view objects and view links, BC4J design time provides tools to produce these definition files. For custom component object, the user must provide a custom tool to produce definition files or provide finished definition files himself.)

  Parameters:
    `coName` - the name to be assigned to the component object. If `null`, a system generated name is assigned.
    `coDefName` - the name of the component object definition from which the new component object is to be created. It must be a fully qualified name (including the package name).
  Returns:
    a new component object.
  Throws:
    `InvalidObjNameException` - if `coName` is an invalid name. `coName` must be a vaild Java name.
    `NameClashException` - if a component object of `coName` already exists in this application module. The component object name must be unique.
    `NoDefException` - if component object definition (named by the `defName` parameter) was not found. Make sure `defName` is fully qualified with the package name.
    `PersistenceException` - if some error was found while loading the component object definition.

### findComponentObject

    public ComponentObject findComponentObject(java.lang.String coName)

  Finds the named component object. See `createComponentObject(String, String)` for explanation of BC4J's support for custom component objects.

  See `findViewObject(String)` for explanation on AM-qualified names and unqualified names.

  Parameters:
    `coName` - the name of the component object.
  Returns:
    the component object. `null` if the component object is not found.
  Throws:
    `NoObjException` - if an AM-qualified name was specified and the containing application module could not be found.
    `InvalidObjNameException` - if `coName` is an invalid name. `coName` must be a vaild Java name.
  See Also:
    `findApplicationModule(String)`

### isRoot

    public boolean isRoot()

  Returns `true` if this application module is a root application module.
  Returns:
    `true` if this application module is a root application module. `false` if this application module is a nested application module.

### getTransaction

    public Transaction getTransaction()

  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 been removed or has not fully been initialized.

### getSession

    public Session getSession()

  Gets the application module's session. Note that if this method is invoked on a nested application module, the root application module's session is returned. This is because the session is shared by all application modules contained by the root application module.

  If the user creates two root application modules, each has its own session.

  Note that this is the same session that is passed to the `ApplicationModuleImpl.activate(Session)` call.

  Returns:
    the session.
  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 been removed or has not fully been initialized.
  See Also:
    `ApplicationModuleImpl.activate(Session)`

### getSyncLock

    public java.lang.Object getSyncLock()

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

  Returns:
    the locking object.

### clearVOCaches

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

  Clears the view object cache for all view objects that use an entity object identified by `entityName`. This method finds all view objects that use the entity, then calls `ViewObject.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 application modules.

  Parameters:
    `entityName` - fully qualified name of the entity object. If `null` all view object caches are cleared.
    `recurse` - a flag indicating whether to recurse into nested application modules.

### findRSIForEntity

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

  Finds the `RowSetIterator` associated with the specified entity 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 system throws a `DMLException`. Inside the `DMLException` instance is an opaque handle (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 view row that uses this entity.

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

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

  Parameters:
    `rsis` - an array of `RowSetIterator`'s to look through.
    `eRowHandle` - the entity row handle.
  Returns:
    the `RowSetIterator`.
  See Also:
    `DMLException`, `RowSetIterator`, `DMLException`

### findViewObjectUsingEntity

    public ViewObject findViewObjectUsingEntity(ViewObject[] vos,
                                                java.lang.String entityName,
                                                java.lang.String[] attrName)

  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`.
  Parameters:
    `vos` - an array of possible view objects.
    `entityName` - fully qualified name of the entity object. Should not be `null`.
    `attrName` - 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.
  Throws:
    `NoDefException` - if the entity could not be found.
    `PersistenceException` - if some error was found while loading the entity definition.

### findViewObjectWithParameters

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

  Internal: Applications should not use this method. Given a view object name, use findViewObject(String name) to find the view object and set it's named bind parameters with the values passed in the 'params' argument. If the execute flag is true, execute this view object before returning it to the caller if it's not already executed or if it's bind parameter values have changed.

### transformExceptionParams

    public java.lang.Object[] transformExceptionParams(ViewObject[] vos,
                                                       java.lang.String entityName,
                                                       java.lang.String exceptionClassName,
                                                       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. This method is primarily used by JboException subclasses to map their parameters when doEntityToVOMapping() is called on those Exceptions.
  Parameters:
    `vos` - an array of possible view objects.
    `entityName` - fully qualified name of the entity object. Should not be `null`.
    `exceptionClassName` - Qualified classname for the Exception which is being mapped
    `params` - Parameters from the Exception that is to be transformed into view object equivalents.
  Throws:
    `NoDefException` - if the entity could not be found.
    `PersistenceException` - if some error was found while loading the entity definition.

### getExceptionHandler

    public JboExceptionHandler getExceptionHandler()

### setExceptionHandler

    public void setExceptionHandler(JboExceptionHandler hndlr)

  Sets the exception handler for this application module. An exception handler must implement the `JboExceptionHandler` interface.

  `JboExceptionHandler` handle exceptions (`java.lang.Exception`) and warnings (`JboWarning`). In 2 tier mode, the handler will only see warnings but no exception. In 2 tier mode, Exceptions are thrown through the normal Java `throw` mechanism. They should be handled through `catch` blocks. For warnings, no `throw/catch` mechanism is available. The handler must process them.

  In 3 tier mode, the handler may have to process exceptions in addition to warnings. When a method call is marshalled from the client tier into the middle tier, the middle tier processing of the method may result in more than one exceptions. All these exceptions are caught by the marshalling code and brought back to the client tier. As Java's `throw` mechanism allows throwing of only one exception, these multiple exceptions cannot be processed through Java `throw`. Thus, for each of these exceptions, a call is made to handler's handleException(), so that the handler can process it.

  Parameters:
    `hndlr` - an exception handler.

### addWarning

    public void addWarning(JboWarning warn)

  Adds a warning message. In 2 tier mode, the warning is passed to this method is sent to the exception handler immediately if an exception handler is present (exception handler is specified through a call to `setExceptionHandler(JboExceptionHandler)`). This is done through a call to `JboExceptionHandler.handleWarning(JboWarning)`.

  In 3 tier mode, the warnings that came to this application module through calls to `addWarning()` in the middle tier are "chained" until the middle tier processing completes. They are brought to the client at the end of middle tier processing, and, for each warning, a call is made to `JboExceptionHandler.handleWarning(JboWarning)` if an exception handler is present.

  Parameters:
    `warn` - warning message.

### getStyles

    public ClientDocument getStyles(java.lang.String name)

  Gets the style definition from an XML file in the middle tier. While this method, along with `setStyles()`, was originally provided for DAC (Data Aware Control), it can be used for general purpose.

  This method retrieves the content of an XML document specified by `name` and returns it as a `ClientDocument`. It locates the XML file through the following logic:

  - It retrieves the server property named `DACStylesDirectory`, which specifies the base directory in which the XML file is to be located.
  - The property value may have '.' separators. These separators are converted to directory separators ('\' in Windows and '/' in Unix).
  - `name` is appended to this base directory. `name` may contain additional '.' separators. They are converted to directory separators as well.
  - The '.xml' extension is added. This is used as the XML file name.
  For example, if `DACStylesDirectory` is `package1.mypackage` and `name` is `styles.myStyle`, the resulting XML file name on Unix would be `package1/mypackage/styles/myStyle.xml`.

  `ClientDocument` enables the user to manipulate an arbitrary tree of an XML style document. Thus, the user can retrieve a `ClientDocument` using this method and modify parts of the tree and write it back out using `setStyles(String, ClientDocument)`.

  Parameters:
    `name` - the XML file name.
  Returns:
    the content of the XML file as a `ClientDocument`.
  See Also:
    `ClientDocument`

### setStyles

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

  Saves a style definition XML file in the middle tier. While this method, along with `getStyles()`, was originally provided for DAC (Data Aware Control), it can be used for general purpose.

  This method saves the content of the document (the `clientDocument` parameter) in an XML file specified by `name`. It locates the XML file through the following logic:

  - It retrieves the server property named `DACStylesDirectory`, which specifies the base directory in which the XML file is to be located.
  - The property value may have '.' separators. These separators are converted to directory separators ('\' in Windows and '/' in Unix).
  - `name` is appended to this base directory. `name` may contain additional '.' separators. They are converted to directory separators as well.
  - The '.xml' extension is added. This is used as the XML file name.
  For example, if `DACStylesDirectory` is `package1.mypackage` and `name` is `styles.myStyle`, the resulting XML file name on Unix would be `package1/mypackage/styles/myStyle.xml`.

  `ClientDocument` enables the user to build an arbitrary tree of an XML style document. Thus, this method can be used to programmatically build and save an XML file.

  Parameters:
    `name` - the XML file name.
    `clientDocument` - the `ClientDocument` to be saved.
  See Also:
    `ClientDocument`

### reserveSnapshotId

    public int reserveSnapshotId(int flags)

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

  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:
    `passivateState(int, byte[], int).`

### reservePassivationId

    public int reservePassivationId()

  Deprecated. deprecated since 9.0.5. Use `reserveSnapshotId(int)` with the PERSISTNENT_SNAPSHOT bit set instead.
  Internal: Applications should not user this method.

### passivateState

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

  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 `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 `passivateState(byte[], int)`.

  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:
    `reservePassivationId()`

### passivateState

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

  Deprecated. deprecated since 9.0.5. Use `passivateState(int, byte[], int)` with the PASSIVATE_TRANSIENT_FLAG not set instead.
  Internal: Applications should not user this method.

### passivateState

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

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

  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(byte[] clientData)

  Deprecated. deprecated since 9.0.5. Use `passivateState(byte[])` with the PERSISTNENT_SNAPSHOT bit set instead.

### activateState

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

  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 `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 `passivateState(byte[], int)` was called. For an example usage of `activateState`, see `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.

  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 `passivateState(byte[], int)` method.

### activateState

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

  Deprecated. deprecated since 9.0.5. Use `activateState(int, SessionData, int)` with the PERSISTNENT_SNAPSHOT bit set and a null SessionData instead.

### activateState

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

  Deprecated. deprecated since 9.0.5. Use `activateState(int, SessionData, int)` with the PERSISTNENT_SNAPSHOT bit set instead.

### getMostRecentStackId

    public int getMostRecentStackId()

  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 `passivateState(byte[])` for more information regarding stack passivation.

### prepareSession

    public void prepareSession(SessionData info)

  Internal: Applications should not use this method.

### resetState

    public void resetState(int flags)

  Advanced use only

  Applications should override/extend `ApplicationModuleImpl.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);

### resetState

    public void resetState(boolean reload)

  Deprecated. since 9.0.5. Use `resetState(int)` with the `RESET_RELOAD_FLAG` enabled instead.

### removeState

    public void removeState(int id)

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

  Parameters:
    `id` - an unique integer identifier associated with an instance of the application module.

### setStoreForPassiveState

    public void setStoreForPassiveState(byte storageType)

  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:

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

  This method should be called before calling `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);
          }

  Parameters:
    `storageType` - where the application module state is stored. Can be one of `PASSIVATE_TO_DATABASE` (default target), `PASSIVATE_TO_FILE`, or `PASSIVATE_TO_MEMORY`.
  Throws:
    `JboException` - if this application module has already stored its state earlier.
  See Also:
    `passivateState(byte[])`

### fetchAttributeProperties

    public void fetchAttributeProperties(java.lang.String[] voNames,
                                         java.lang.String[][] voAttrNames,
                                         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. 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.

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

### passivateStateForUndo

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

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

  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)

  Restore an application module undo record.

  Activates an application module state which was created using `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.

  Parameters:
    `id` - the id of an undo record that was created using `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)

  Determines if an id created using `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.

  Parameters:
    `id` - the id of an undo record that was created using `passivateStateForUndo(String id, byte[] clientData, int flags)`

### doPoolMessage

    public ApplicationPoolSvcMsgContext doPoolMessage(ApplicationPoolSvcMsgContext ctx)

  Internal use only. Applications should not use. Used by the ApplicationPool to send batch application module requests.

### getReleaseLevel

    public int getReleaseLevel()

  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.

  Returns:
    ApplicationModule.RELEASE_LEVEL_MANAGED or ApplicationModule.RELEASE_LEVEL_RESERVED

### setReleaseLevel

    public void setReleaseLevel(int releaseLevel)

  See Also:
    `getReleaseLevel()`

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.