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_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 {@link #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 {@link #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 ApplicationModule 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 Object 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 an 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.
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 ViewObjects 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.
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 ApplicationModule.
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 {@link #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 ApplicationModule 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) Internal: Applications should not use this method.
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 ViewObject that this entity is used in and then transforms the parameters from a given JboException from their Entity layer equivalents to the ViewObject 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 #PASSIVATION_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 ApplicationModule state at the time of the undo request -- a deferred undo request does not guarantee that the passivated state equals the ApplicationModule 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 ApplicationModule 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 ApplicationModule 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

RESET_ROLLBACK_FLAG

public static final int RESET_ROLLBACK_FLAG

A reset flag. Indicates that reset should first rollback the ApplicationModule.

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

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

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 ApplicationModule 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 #getApplicatonModuleNames(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 ApplicationModules, or both. Not yet loaded Application Modules would appear only if lazy loading is turned on.

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

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:

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 Object definition. The View Object 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 Object 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 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 View Object 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 an 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 Object definition from the Entity Object and sets the select, from, where, and order-by clauses of the View Definition. Then, it uses that View Object definition to create the View Object.

Parameters:

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

SQLStmtException - if a SQL syntax problem has been discovered while attempting to parse the SQL clauses.

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 Object definition with no Entity Object base and maps database columns to attribute definitions. Then, it uses that View Object definition to create the View Object.

Parameters:

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:

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 Views 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) (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), 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:

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.

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

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.

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

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

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 ViewObject that this entity is used in and then transforms the parameters from a given JboException from their Entity layer equivalents to the ViewObject 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 ViewObject equivalents.

Throws:

NoDefException - if the Entity could not be found.

PersistenceException - if some error was found while loading the Entity Object 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[], flags).

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:

oracle.jbo.server.ApplicationModule#reservePassivationId()

passivateState

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

Deprecated. deprecated since 9.0.5. Use {@link #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 thie ApplicationModule'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 ApplicationModule 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(/tt> 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 {@link #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 {@link #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 #passivateToStack(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)

Internal: Applications should not use this method.

Applications should override/extend ApplicationModuleImpl.reset() to reset custom ApplicationModule state. reset() is invoked by the internal resetState before resetState begins cleaning up internal ApplicationModuel state.

Flag usage:

RESET_RELOAD_FLAG directs resetState to eagerly reload the ApplicationModule compoonents.

RESET_ROLLBACK_FLAG directs resetState to rollback the ApplicationModule.

RESET_INTERNAL_FLAG directs resetState to perform an internal reset only. The ApplicationPool uses this to reset a managed state ApplicationModule 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 ViewObjects 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.

passivateStateForUndo

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

Create an ApplicationModule undo record.

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

ApplicationModule state snapshots that are created using this method will be pushed to an LIFO stack. This stack is defined as part of the ApplicationModule transaction state and as such will be maintained by ApplicationModule 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 ApplicationModule state at the time of the undo request -- a deferred undo request does not guarantee that the passivated state equals the ApplicationModule 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 ApplicationModule undo record.

Activates an ApplicationModule 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)

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 ApplicationModule requests.

getReleaseLevel

public int getReleaseLevel()

Returns the release level that should be employed by clients of this ApplicationModule.

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

Two release levels are currently supported:

RELEASE_LEVEL_MANAGED Default. Indicates that the ApplicationModule 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 ApplicationModule may not be managed by the BC4J state management service. ApplicationModules 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 ApplicationModules 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:

{@link #getReleaseLevel()}