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

Defines a database session and a transaction boundary.

Controls concurrent access to data.

Groups related View Objects into a data model that clients can access in a single network roundtrip.

Stores application-specific Java code in an object on the middle tier.

Creates read-only View Objects from SQL statements and clauses.

Accesses utility methods for testing and debugging.

Uses of Application Module Instances

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

Root Application Modules

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

Extending the Application Module Implementation

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

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

Nesting Application Modules

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

Nested Application Modules and Transactions

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

createViewObjectFromQueryStmt(java.lang.String voName, java.lang.String query, java.lang.String voImplClassName)
Creates a read-only View Object, given the name of the View Object, the query statement and the name of a class that extends (ViewObjectImpl).

fetchAttributeProperties(java.lang.String[] voNames, java.lang.String[][] attrs, LocaleContext locale)
Fetches all custom properties for the given list of attributes for the named view objects in this application module over to the remote client objects in one network roundtrip.

findViewObjectWithParameters(java.lang.String voName, VariableManager params, boolean executeIfNeeded)
Given a ViewObject name, use findViewObject(String name) to find the ViewObject and set it's named bind parameters with the values passed in the 'params' argument.

handleDefinitionChangedOnActivate(java.lang.Object activatedTS)
Allows subclasses to abort activation, when the metadata for the component objects has changed and an attempt is made to activate an Application Module which was saved with an older version of the metadata.

transformExceptionParams(ViewObject[] inVOs, java.lang.String entityDefName, java.lang.String className, java.lang.Object[] params)Internal:Applications should not use this method. This method uses findViewObjectUsingEntity() to get the first view object that this entity is used in and then transforms the parameters from a given JboException from their entity layer equivalents to the view object equivalents.

ApplicationModuleImpl

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.

activate

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

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

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

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

Parameters:

session - the session in which the root Application Module is created.

finishLoadingComponents

getApplicationModuleDef

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

This method should not be overridden.

Returns:

the Def associated with this Application Module.

isRoot

public boolean isRoot()

Determines if this is the root Application Module. For example, if your code is traversing through the Application Module instances use this method to test for the root Application Module instance.

addChild

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

removeChild

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

getDefName

public java.lang.String getDefName()

Returns the name of this Application Module's Def (definition) object. Typically, this will have the format AppModuleName in the XML file. For example, use this method to find the Def name of the Application Module, then use it to create an instance of this Application Module in another location.

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

findObject

findApplicationModule

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:

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.

getApplicationModuleNames

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.

setSyncMode

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.

getViewObjectNames

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.

getViewLinkNames

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.

createViewLink

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

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

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

createViewLink

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

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

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

createViewLinkFromEntityAssocName

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

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

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

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

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

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

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

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

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

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

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

findViewObjectWithParameters

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

findViewObject

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:

findComponentObject

Finds the component object from the Application Module. An Application Module typically contains View Objects, View Links, or another Application Module. This method will instead, return a generic component that has been included in the Application Module. A generic component is any object that implements the ComponentObject interface. This method allows for integration of other applications.

findViewLink

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:

getDBTransaction

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

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

Returns:

the transaction.

Throws:

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

createViewObjectFromQueryStmt

Creates a read-only View Object, given the name of the View Object, the query statement and the name of a class that extends (ViewObjectImpl). The returned ViewObject is an instance of the Class name provided in the argument. If a null value is passed in for the ViewObjectImpl class name this method is equivalent to createViewObjectFromQueryStmt(String, String).

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

createViewObjectOnRowSet

executeCommand

public int executeCommand(java.lang.String command)

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

The following code example uses executeCommand. The SQL string is designed to update the EMP table. This example passes the string to executeCommand, then prints a message to report how many rows were actually updated.

dumpQueryResult

Writes the result of the query to a (potentially very long) string. It takes three parameters: the first is the SQL query statement. The second is the class that dumps the result to a string. This class must implement the oracle.jbo.server.QueryDump interface. The implementation of this class decides what to do with the third, data parameter (which can be null). This is a utility method for testing and debugging queries and applications.

createViewObject

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

createComponentObject

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

reset

protected void reset()

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

Examples of session ApplicationModule state include custom instance variables.

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

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

getImageLoc

setExceptionHandler

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

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

findRSIForEntity

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

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

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

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

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

setStoreForPassiveState

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:

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

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

reserveSnapshotId

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

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

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

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

passivateState

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

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

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.

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.

passivateState

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

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

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

activateState

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

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

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

prepareApplicationModuleSession

Prepare the ApplicationModule session. Application developers may extend this method to initialize ApplicationModule session state. In constrast to prepareSession(Session), a developer may extend this method to initialize the ApplicationModule session only -- a developer may not use this method to initialize database state for the session.

A developer should extend this method instead of prepareSession(Session) if they implement code to initialize the ApplicationModule session that should not be re-executed when the ApplicationModule is reconnected.

prepareSession

Prepare the ApplicationModule and/or the JDBC session. Application developers may extend this method to initialize JDBC or ApplicationModule session state. For example, a developer could extend this method to prepare PL/SQL session state which is related to a virtual private database. A developer may also extend this method to initialize state in the ApplicationModule Session.

The application module may be assumed to be in a valid, connected state when this method is invoked.

This method is invoked when:

1. An ApplicationModule is first created.

2. An ApplicationModule is associated with a user session -- typically an ApplicationModuleHandle that was created by the pooling framework. Note that a handle may be disassociated from an ApplicationModule as ApplicationModules are recycled. prepareSession will be invoked when the handle is associated with a new ApplicationModule, before the handle's state is activated.

launchTester

passivateState

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

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

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

Parameters:

doc - the name of the XML document where the custom data will be stored.

parent - the name of the parent element under which the custom data will be stored.

passivateConnectionState

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

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

activateConnectionState

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

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

handleDefinitionChangedOnActivate

Allows subclasses to abort activation, when the metadata for the component objects has changed and an attempt is made to activate an Application Module which was saved with an older version of the metadata.

Parameters:

activatedTS - The meta-data definition version that the ApplicationModule being activated was passivated with. Currently this version object is a Long value. However Applications should not rely on the fact that this object will be of type Long in future.

findViewObjectUsingEntity

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.

eoName - fully qualified name of the entity object. Should not be null.

attrNames - if empty, i.e., null or an array of length 0, then the attribute matching rule will be skipped (see the above discussion). If not empty, it should have only one element and that element should be the name of an attribute of the entity. The attribute matching rule will apply. If a matching view object is found, attrName[0] upon return should have the name of a view object mapped to the entity attribute.

Internal:Applications should not use this method. This method uses findViewObjectUsingEntity() to get the first view object that this entity is used in and then transforms the parameters from a given JboException from their entity layer equivalents to the view object equivalents. This method is primarily used by JboException subclasses to map their parameters when doEntityToVOMapping() is called on those Exceptions.

fetchAttributeProperties

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

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

passivateStateForUndo

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

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

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

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

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

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

getReleaseLevel

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

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

Two release levels are currently supported:

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

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

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

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

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

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

beforeValidate

Callback from the transaction before starting a validation iteration. Transaction will call this hook on the root application module. The root application module in turn will call the beforeValidate method on all its children

Parameters:

te - a transaction event.

afterValidate

Callback from the transaction after completing a validation iteration. Transaction will call this hook on the root application module. The root application module in turn will call the afterValidate method on all its children

Parameters:

te - a transaction event.

processChangeNotifications

This method is invoked by the framework at a specific point in the request lifecycle. Auto refreshing view objects register themselves with the database to listen for data change notification. On receiving a notification such view objects will mark themselves for refresh. During the datacontrol render phase the pending notifications will be processed by purging the data collections and revering to unqueried state.