Oracle Business Components for Java 9.0.2: Class ApplicationModuleImpl

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Business Components

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

oracle.jbo.server
Class ApplicationModuleImpl

java.lang.Object
  |
  +--oracle.jbo.common.NamedObjectImpl
        |
        +--oracle.jbo.server.ComponentObjectImpl
              |
              +--oracle.jbo.server.ContainerObjectImpl
                    |
                    +--oracle.jbo.server.ApplicationModuleImpl

All Implemented Interfaces:: ApplicationModule, ComponentObject, ContainerObject, Properties, TransPostControl

public class ApplicationModuleImpl
extends ContainerObjectImpl
implements ApplicationModule, TransPostControl

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

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

Uses of Application Module Instances

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

Root Application Modules

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

Extending the Application Module Implementation

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

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

Nesting Application Modules

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

Nested Application Modules and Transactions

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

Since:: JDevloper 3.0
See Also:: ApplicationPool

Field Summary
Type Field

static java.lang.String DEFAULT_DEF_NAME
          Default Def name for this Application Module.

Fields inherited from class oracle.jbo.server.ContainerObjectImpl

mComponentList, mComponents

Fields inherited from class oracle.jbo.common.NamedObjectImpl

mFullName, mObjName, mParent, mProperties

Fields inherited from interface oracle.jbo.ApplicationModule

DEFAULT_DEF_FULL_NAME, DEFAULT_ROOT_APP_MOD_NAME, PASSIVATE_TO_DATABASE, PASSIVATE_TO_FILE, PASSIVATE_TO_MEMORY, SYNC_IMMEDIATE, SYNC_LAZY

Fields inherited from interface oracle.jbo.common.TransPostControl

TRANS_POST_GET_ATTR_BY_INDEX, TRANS_POST_GET_ATTR_BY_NAME, TRANS_POST_GET_ATTR_COUNT, TRANS_POST_GET_ATTR_INDEX_OF, TRANS_POST_PUSHBACK, TRANS_POST_REMOVE, TRANS_POST_REVERT, TRANS_POST_SET_ATTR_BY_INDEX, TRANS_POST_SET_ATTR_BY_NAME

Constructor Summary
Type Constructor

protected ApplicationModuleImpl()
          constructs a new Application Module.

Method Summary
Type Method

protected void activate(Session session)
          Called by the framework when a root Application Module is created.

protected void activateState(Element parent)
          Allows subclasses to retrieve custom data from an XML-node under the given parent element.

byte[] activateState(int id, boolean remove)
          Internal: Applications should not use this method.

protected void addChild(ComponentObjectImpl object)
          Internal: Applications should not use this method.

void addWarning(JboWarning warn)
          Specifies the name of the handler that will perform special processing of warnings on the client.

protected void afterConnect()
          Invoked after the application module database connection has been established.

protected void beforeDisconnect()
          Invoked before the application module database connection has been released.

void clearVOCaches(java.lang.String entityName, boolean recurse)
          Clears the caches of all View Objects that use the specified entity.

ApplicationModule createApplicationModule(java.lang.String amName, java.lang.String defName)
          Creates an instance of an Application Module within this Application Module; that is, a nested Application Module.

ComponentObject createComponentObject(java.lang.String coName, java.lang.String comDefName)
          Creates a Component object in the context of this Application Module.

static ApplicationModuleImpl createRootApplicationModule(java.lang.String applicationModuleDefName, Session sess)
          Internal: Applications should not call this method.

static void createSharedDataHandle()
          Internal: Applications should not call this method.

ViewLink createViewLink(java.lang.String viewLinkName, java.lang.String viewLinkDefName, ViewObject master, ViewObject detail)
          Creates a View Link, given the View Link name, the Def name, and the names of the master and detail View Objects.

ViewLink createViewLinkBetweenViewObjects(java.lang.String viewLinkName, java.lang.String accessorName, ViewObject master, AttributeDef[] srcAttrs, ViewObject detail, AttributeDef[] destAttrs, java.lang.String assocClause)
          Creates a View Link given either a View Link Definition or an Entity Association.

ViewLink createViewLinkFromEntityAssocName(java.lang.String viewLinkName, java.lang.String entityAssocName, ViewObject master, ViewObject detail)
          Creates a View Link, given the View Objects and an Entity Association.

ViewObject createViewObject(java.lang.String voName, java.lang.String vDefName)
          Creates an updateable View Object.

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


ViewObject createViewObjectFromQueryClauses(java.lang.String vuName, java.lang.String eoName, java.lang.String selectClause, java.lang.String fromClause, java.lang.String whereClause, java.lang.String orderByClause)
          Creates an updateable View Object.

ViewObject createViewObjectFromQueryStmt(java.lang.String qName, java.lang.String query)
          Creates a read-only View Object, given a query statement and a name for the View Object.

static void createXMLSharedDataHandle()
          Call this function to register a shared data handle with MetaObjectManager and use it later.

java.lang.String dumpQueryResult(java.lang.String query, java.lang.String dumpClassName, java.lang.String[] data)
          Writes the result of the query to a (potentially very long) string.

int executeCommand(java.lang.String command)
          Specifies a valid SQL statement to be executed by the server.

ApplicationModule findApplicationModule(java.lang.String amName)
          Returns the named Application Module.

ComponentObject findComponentObject(java.lang.String compName)
          Finds the component object from the Application Module.

RowSetIterator findRSIForEntity(RowSetIterator[] rsis, int eRowHandle)
          Finds the RowSetIterator associated with the specified row handle.

ViewLink findViewLink(java.lang.String vlName)
          Returns the specified View Link from this Application Module.

ViewObject findViewObject(java.lang.String voName)
          Gets the named View Object that was created at runtime in the Application Module or created with Design Time tools.

ViewObject findViewObjectUsingEntity(ViewObject[] vos, java.lang.String eoName, java.lang.String[] attrNames)
          Given an array of View Objects (the vos parameter), finds the first matching View Object.

void findVOsWithEntityUsage(java.lang.String entityName, boolean recurse, com.sun.java.util.collections.ArrayList vos)
          Finds the View Objects that use the specified entity.

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


protected ApplicationModuleDefImpl getApplicationModuleDef()
          Returns the Def (definition) associated with this Application Module.

ApplicationModuleImpl[] getApplicationModuleImpls()
          Internal: Applications should not use this method.

java.lang.String[] getApplicationModuleNames()
          Returns an array of the Application Modules that are contained within this Application Module.

java.lang.String getClientProxyClassName()
          Internal: Applications should not use this method.

java.lang.String getClientProxyClassName(java.lang.String serverType)
          Internal: Applications should not use this method.

DBTransaction getDBTransaction()
          Returns the database transaction associated with the root Application Module.

java.lang.String getDefFullName()
          Returns the fully-qualified (that is, package-qualified) name of this Application Module's Def (definition) object.

java.lang.String getDefName()
          Returns the name of this Application Module's Def (definition) object.

Row getEntityRowFromHandle(int eRowHandle)
          Internal: Applications should not use this method.

oracle.jbo.common.remote.rAttributeDescription[] getQueryInfo(ViewObject vo)
          Internal: Applications should not use this method.

Session getSession()
          Returns the session information.

ClientDocument getStyles(java.lang.String name)
          Gets the Application Module's style definitions from the middle tier.

java.lang.Object getSyncLock()
          Gets the locking object for this Application Module.

int getSyncMode()
          Returns the sync mode for this Application Module.

Transaction getTransaction()
          Returns the transaction information.

java.lang.String[] getViewLinkNames()
          Returns an array of the names of the View Links contained in this Application Module.

ViewLinkImpl[] getViewLinks()
          Returns an array of the View Links contained in this Application Module.

java.lang.String[] getViewObjectNames()
          Returns an array of the names of the View Objects contained in this Application Module.

ViewObject[] getViewObjects()
          Constructs an array of this Application Module's View Objects.

boolean isRoot()
          Determines if this is the root Application Module.

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


int passivateState(byte[] clientData)
          Internal: Applications should not use this method.

protected void passivateState(Document doc, Element parent)
          Allows subclasses to store custom data as XML-nodes under the given parent element, in the given document.

int passivateState(int id, byte[] clientData)
          Internal: Applications should not use this method.

void remove()
          Deletes this Application Module.

protected void removeChild(ComponentObjectImpl object)
          Internal: Applications should not use this method.

void removeState(int id)
          Internal: Applications should not use this method.

int reservePassivationId()
          Internal: Applications should not use this method.

protected void reset()
          Override this method to reset any cached varaibles for objects that belong to this appModule.

void resetState(boolean reload)
          Internal: Applications should not use this method.

void setExceptionHandler(JboExceptionHandler hndlr)
          Specifies the name of the handler which will perform special processing of the exceptions on the client.

void setStoreForPassiveState(byte storageType)
          Internal: Applications should not use this method.

void setStyles(java.lang.String name, ClientDocument clientDocument)
          Saves the Application Module's style definitions to the middle tier.

void setSyncMode(int mode)
          Sets the mode in which the sync'ing of client data with the middle tier is performed.

void sync()
          Synchronizes all the result sets defined in this Application Module in the client with the application tier.

java.lang.Object transPostGetAttr(int op, int hdl, int index, java.lang.String name)
          Internal: Applications should not use this method.

void transPostPushback(int hdl)
          Internal: Applications should not use this method.

void transPostRemove(int hdl)
          Internal: Applications should not use this method.

void transPostRevert(int hdl)
          Internal: Applications should not use this method.

void transPostRowOp(int op, int hdl)
          Internal: Applications should not use this method.

void transPostSetAttr(int op, int hdl, int index, java.lang.String name, java.lang.Object value)
          Internal: Applications should not use this method.

Methods inherited from class oracle.jbo.server.ContainerObjectImpl

addContainerListener, removeContainerListener

Methods inherited from class oracle.jbo.server.ComponentObjectImpl

addListener, create, createRef, getApplicationModule, getCompListeners, getCompListenersList, getProxyClassName, getProxyClassName, getRootApplicationModule, isRegWithPiggyMan, setName, setParent, setProxyClassName

Methods inherited from class oracle.jbo.common.NamedObjectImpl

getFullName, getName, getParent, getProperties, getPropertiesAsStrings, getPropertiesMap, getProperty, refreshProperty, setFullName, setPropertiesMap, setProperty

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface oracle.jbo.ComponentObject

getFullName, getName

Methods inherited from interface oracle.jbo.Properties

getProperties, getProperty, refreshProperty

Type	Field
`static java.lang.String`	`DEFAULT_DEF_NAME` Default Def name for this Application Module.

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

Type	Method
`protected void`	`activate(Session session)` Called by the framework when a root Application Module is created.
`protected void`	`activateState(Element parent)` Allows subclasses to retrieve custom data from an XML-node under the given parent element.
`byte[]`	`activateState(int id, boolean remove)` Internal: Applications should not use this method.
`protected void`	`addChild(ComponentObjectImpl object)` Internal: Applications should not use this method.
`void`	`addWarning(JboWarning warn)` Specifies the name of the handler that will perform special processing of warnings on the client.
`protected void`	`afterConnect()` Invoked after the application module database connection has been established.
`protected void`	`beforeDisconnect()` Invoked before the application module database connection has been released.
`void`	`clearVOCaches(java.lang.String entityName, boolean recurse)` Clears the caches of all View Objects that use the specified entity.
`ApplicationModule`	`createApplicationModule(java.lang.String amName, java.lang.String defName)` Creates an instance of an Application Module within this Application Module; that is, a nested Application Module.
`ComponentObject`	`createComponentObject(java.lang.String coName, java.lang.String comDefName)` Creates a Component object in the context of this Application Module.
`static ApplicationModuleImpl`	`createRootApplicationModule(java.lang.String applicationModuleDefName, Session sess)` Internal: Applications should not call this method.
`static void`	`createSharedDataHandle()` Internal: Applications should not call this method.
`ViewLink`	`createViewLink(java.lang.String viewLinkName, java.lang.String viewLinkDefName, ViewObject master, ViewObject detail)` Creates a View Link, given the View Link name, the Def name, and the names of the master and detail View Objects.
`ViewLink`	`createViewLinkBetweenViewObjects(java.lang.String viewLinkName, java.lang.String accessorName, ViewObject master, AttributeDef[] srcAttrs, ViewObject detail, AttributeDef[] destAttrs, java.lang.String assocClause)` Creates a View Link given either a View Link Definition or an Entity Association.
`ViewLink`	`createViewLinkFromEntityAssocName(java.lang.String viewLinkName, java.lang.String entityAssocName, ViewObject master, ViewObject detail)` Creates a View Link, given the View Objects and an Entity Association.
`ViewObject`	`createViewObject(java.lang.String voName, java.lang.String vDefName)` Creates an updateable View Object.
`protected ViewObject`	`createViewObject(java.lang.String voName, ViewDefImpl viewDef)`
`ViewObject`	`createViewObjectFromQueryClauses(java.lang.String vuName, java.lang.String eoName, java.lang.String selectClause, java.lang.String fromClause, java.lang.String whereClause, java.lang.String orderByClause)` Creates an updateable View Object.
`ViewObject`	`createViewObjectFromQueryStmt(java.lang.String qName, java.lang.String query)` Creates a read-only View Object, given a query statement and a name for the View Object.
`static void`	`createXMLSharedDataHandle()` Call this function to register a shared data handle with `MetaObjectManager` and use it later.
`java.lang.String`	`dumpQueryResult(java.lang.String query, java.lang.String dumpClassName, java.lang.String[] data)` Writes the result of the query to a (potentially very long) string.
`int`	`executeCommand(java.lang.String command)` Specifies a valid SQL statement to be executed by the server.
`ApplicationModule`	`findApplicationModule(java.lang.String amName)` Returns the named Application Module.
`ComponentObject`	`findComponentObject(java.lang.String compName)` Finds the component object from the Application Module.
`RowSetIterator`	`findRSIForEntity(RowSetIterator[] rsis, int eRowHandle)` Finds the RowSetIterator associated with the specified row handle.
`ViewLink`	`findViewLink(java.lang.String vlName)` Returns the specified View Link from this Application Module.
`ViewObject`	`findViewObject(java.lang.String voName)` Gets the named View Object that was created at runtime in the Application Module or created with Design Time tools.
`ViewObject`	`findViewObjectUsingEntity(ViewObject[] vos, java.lang.String eoName, java.lang.String[] attrNames)` Given an array of View Objects (the `vos` parameter), finds the first matching View Object.
`void`	`findVOsWithEntityUsage(java.lang.String entityName, boolean recurse, com.sun.java.util.collections.ArrayList vos)` Finds the View Objects that use the specified entity.
`void`	`findVOsWithEntityUsage(java.lang.String entityName, boolean recurse, java.util.Vector vos)`
`protected ApplicationModuleDefImpl`	`getApplicationModuleDef()` Returns the Def (definition) associated with this Application Module.
`ApplicationModuleImpl[]`	`getApplicationModuleImpls()` Internal: Applications should not use this method.
`java.lang.String[]`	`getApplicationModuleNames()` Returns an array of the Application Modules that are contained within this Application Module.
`java.lang.String`	`getClientProxyClassName()` Internal: Applications should not use this method.
`java.lang.String`	`getClientProxyClassName(java.lang.String serverType)` Internal: Applications should not use this method.
`DBTransaction`	`getDBTransaction()` Returns the database transaction associated with the root Application Module.
`java.lang.String`	`getDefFullName()` Returns the fully-qualified (that is, package-qualified) name of this Application Module's Def (definition) object.
`java.lang.String`	`getDefName()` Returns the name of this Application Module's Def (definition) object.
`Row`	`getEntityRowFromHandle(int eRowHandle)` Internal: Applications should not use this method.
`oracle.jbo.common.remote.rAttributeDescription[]`	`getQueryInfo(ViewObject vo)` Internal: Applications should not use this method.
`Session`	`getSession()` Returns the session information.
`ClientDocument`	`getStyles(java.lang.String name)` Gets the Application Module's style definitions from the middle tier.
`java.lang.Object`	`getSyncLock()` Gets the locking object for this Application Module.
`int`	`getSyncMode()` Returns the sync mode for this Application Module.
`Transaction`	`getTransaction()` Returns the transaction information.
`java.lang.String[]`	`getViewLinkNames()` Returns an array of the names of the View Links contained in this Application Module.
`ViewLinkImpl[]`	`getViewLinks()` Returns an array of the View Links contained in this Application Module.
`java.lang.String[]`	`getViewObjectNames()` Returns an array of the names of the View Objects contained in this Application Module.
`ViewObject[]`	`getViewObjects()` Constructs an array of this Application Module's View Objects.
`boolean`	`isRoot()` Determines if this is the root Application Module.
`static void`	`launchTester(java.lang.String packageName, java.lang.String configName)`
`int`	`passivateState(byte[] clientData)` Internal: Applications should not use this method.
`protected void`	`passivateState(Document doc, Element parent)` Allows subclasses to store custom data as XML-nodes under the given parent element, in the given document.
`int`	`passivateState(int id, byte[] clientData)` Internal: Applications should not use this method.
`void`	`remove()` Deletes this Application Module.
`protected void`	`removeChild(ComponentObjectImpl object)` Internal: Applications should not use this method.
`void`	`removeState(int id)` Internal: Applications should not use this method.
`int`	`reservePassivationId()` Internal: Applications should not use this method.
`protected void`	`reset()` Override this method to reset any cached varaibles for objects that belong to this appModule.
`void`	`resetState(boolean reload)` Internal: Applications should not use this method.
`void`	`setExceptionHandler(JboExceptionHandler hndlr)` Specifies the name of the handler which will perform special processing of the exceptions on the client.
`void`	`setStoreForPassiveState(byte storageType)` Internal: Applications should not use this method.
`void`	`setStyles(java.lang.String name, ClientDocument clientDocument)` Saves the Application Module's style definitions to the middle tier.
`void`	`setSyncMode(int mode)` Sets the mode in which the sync'ing of client data with the middle tier is performed.
`void`	`sync()` Synchronizes all the result sets defined in this Application Module in the client with the application tier.
`java.lang.Object`	`transPostGetAttr(int op, int hdl, int index, java.lang.String name)` Internal: Applications should not use this method.
`void`	`transPostPushback(int hdl)` Internal: Applications should not use this method.
`void`	`transPostRemove(int hdl)` Internal: Applications should not use this method.
`void`	`transPostRevert(int hdl)` Internal: Applications should not use this method.
`void`	`transPostRowOp(int op, int hdl)` Internal: Applications should not use this method.
`void`	`transPostSetAttr(int op, int hdl, int index, java.lang.String name, java.lang.Object value)` Internal: Applications should not use this method.

Field Detail

DEFAULT_DEF_NAME

public static final java.lang.String DEFAULT_DEF_NAME

Default Def name for this Application Module.

Constructor Detail

ApplicationModuleImpl

protected ApplicationModuleImpl()

constructs a new Application Module.

Method Detail

getSyncLock

public final java.lang.Object getSyncLock()

Description copied from interface: ApplicationModule

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

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

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

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

Specified by:: getSyncLock in interface ApplicationModule

Following copied from interface: oracle.jbo.ApplicationModule

Returns:: the locking object.

createRootApplicationModule

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

Internal: Applications should not call this method.

A factory method for creating a root Application Module.

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

createSharedDataHandle

public static void createSharedDataHandle()

Internal: Applications should not call this method.

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

createXMLSharedDataHandle

public static void createXMLSharedDataHandle()

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

activate

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

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

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

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

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

getApplicationModuleDef

protected ApplicationModuleDefImpl getApplicationModuleDef()

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

This method should not be overridden.

Returns:: the Def associated with this Application Module.

isRoot

public boolean isRoot()

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

Specified by:: isRoot in interface ApplicationModule

Returns:: true if this is the root; false otherwise.

addChild

protected void addChild(ComponentObjectImpl object)

Internal: Applications should not use this method.

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

Parameters:: object - an object to add to the component list.
See Also:: oracle.jbo.server.NamedObjectImpl

removeChild

protected void removeChild(ComponentObjectImpl object)

Internal: Applications should not use this method.

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

Parameters:: object - an object to remove from the component list.
See Also:: oracle.jbo.server.NamedObjectImpl

getDefName

public java.lang.String getDefName()

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

Specified by:: getDefName in interface ComponentObject
Overrides:: getDefName in class ComponentObjectImpl

Returns:: the name of this Application Module's Def object.

getDefFullName

public java.lang.String getDefFullName()

Returns the fully-qualified (that is, package-qualified) name of this Application Module's Def (definition) object. Typically, this will have the format Packagename.AppModuleName in the XML file.

Specified by:: getDefFullName in interface ComponentObject
Overrides:: getDefFullName in class ComponentObjectImpl

Returns:: a fully-qualified name. The name typically has the format packageName.appModuleName

createApplicationModule

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

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

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

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

Specified by:: createApplicationModule in interface ApplicationModule

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

findApplicationModule

public ApplicationModule findApplicationModule(java.lang.String amName)

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

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

Specified by:: findApplicationModule in interface ApplicationModule

Parameters:: amName - the name of the Application Module. If amName is empty the root Application Module is returned.
Returns:: the Application Module.
Throws:: InvalidObjNameException - if the name cannot be found.

getApplicationModuleNames

public java.lang.String[] getApplicationModuleNames()

Returns an array of the Application Modules that are contained within this Application Module. Called from the root Application Module, this method can be invoked to browse and access any Application Module in the system.

The following code sample returns an array containing the names of Application Modules defined in the Application Module appMod (that is, nested Application Modules):

 // Get the names of Application Modules defined in the Application Module.
 String[] amNames = appMod.getApplicationModuleNames();

Specified by:: getApplicationModuleNames in interface ApplicationModule

Returns:: the array of Application Module names.

transPostPushback

public void transPostPushback(int hdl)

Internal: Applications should not use this method.

Specified by:: transPostPushback in interface TransPostControl

transPostRemove

public void transPostRemove(int hdl)

Internal: Applications should not use this method.

Specified by:: transPostRemove in interface TransPostControl

transPostRevert

public void transPostRevert(int hdl)

Internal: Applications should not use this method.

Specified by:: transPostRevert in interface TransPostControl

transPostRowOp

public void transPostRowOp(int op,
                           int hdl)

Internal: Applications should not use this method.

transPostGetAttr

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

Internal: Applications should not use this method.

transPostSetAttr

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

Internal: Applications should not use this method.

getEntityRowFromHandle

public Row getEntityRowFromHandle(int eRowHandle)

Internal: Applications should not use this method.

sync

public void sync()

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

Specified by:: sync in interface ApplicationModule

setSyncMode

public void setSyncMode(int mode)

Sets the mode in which the sync'ing of client data with the middle tier is performed. There are two sync modes:

SYNC_IMMEDIATE - All operations on middle-tier objects are performed immediately. For example, attribute values are sent to the middle tier as they are set.
SYNC_LAZY - Operations to be performed on middle-tier objects are batched until an operation forces middle-tier synchronization. Examples of operation that force middle-tier synchronization are changes in currency, calls to an exported method, a request for a rollback or commit, etc.

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

Specified by:: setSyncMode in interface ApplicationModule

Parameters:: mode - integer representation of the sync mode: 0=SYNC_LAZY, 1=SYNC_IMMEDIATE.

getSyncMode

public int getSyncMode()

Returns the sync mode for this Application Module.

Specified by:: getSyncMode in interface ApplicationModule

Returns:: integer representation of the sync mode: 0=SYNC_LAZY, 1=SYNC_IMMEDIATE.

getViewObjectNames

public java.lang.String[] getViewObjectNames()

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

The following code sample returns an array containing the names of View Objects defined in the Application Module appMod:

 // Get the names of View Objects defined in the Application Module.
 String[] voNames = appMod.getViewObjectNames();

Specified by:: getViewObjectNames in interface ApplicationModule

Returns:: the array of View Object names.

getViewLinkNames

public java.lang.String[] getViewLinkNames()

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

The following code sample returns an array containing the View Links defined in the Application Module appMod:

 // Get the View Links defined in the Application Module.
 String[] linkNames = appMod.getViewLinkNames();

Specified by:: getViewLinkNames in interface ApplicationModule

Returns:: the array of View Link names.

getViewLinks

public ViewLinkImpl[] getViewLinks()

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

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

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

Returns:: the array of View Links.

createViewLink

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

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

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

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

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

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

Specified by:: createViewLink in interface ApplicationModule

Parameters:: viewLinkName - the name to be given to the View Link. If empty, a name is generated.; viewLinkDefName - the name of the definition to be used to create the link. If empty, a default definition will be used.; master - the link's source View Object.; detail - the link's destination View Object.
Throws:: InvalidParamException - if master or detail are invalid.; InvalidObjNameException - if viewLinkName is invalid.; NameClashException - if viewLinkName already exists.

createViewLinkFromEntityAssocName

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

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

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

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

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

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

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

Specified by:: createViewLinkFromEntityAssocName in interface ApplicationModule

Parameters:: viewLinkName - the name to be given to the View Link. If empty a name is generated.; entityAssocName - the entity association that the View Link will represent.; master - the link's source View Object.; detail - the link's destination View Object.
Throws:: InvalidParamException - if master, detail, or entityAssocName are invalid.; InvalidObjNameException - if viewLinkName is invalid.; NameClashException - if viewLinkName already exists.

createViewLinkBetweenViewObjects

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

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

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

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

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

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

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

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

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

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

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

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

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

Specified by:: createViewLinkBetweenViewObjects in interface ApplicationModule

Parameters:: viewLinkName - the name to be given to the View Link. If empty, a name is generated.; accessorName - the name to be given to the View Link's accessor.; master - the link's source View Object.; srcAttrs - link attributes taken from the master View Object.; detail - the link's destination View Object.; destAttrs - link attributes taken from the detail View Object.; assocClause - the association clause. Can be null.
Throws:: InvalidParamException - if master or detail are invalid.; InvalidObjNameException - if viewLinkName or accessorName are invalid.; NameClashException - if viewLinkName or accessorName already exist.

findViewObject

public ViewObject findViewObject(java.lang.String voName)

Gets the named View Object that was created at runtime in the Application Module or created with Design Time tools.

The following sample code locates and returns a named View Object within an Application Module. This lets the Application Module reuse the View Object. The code sample calls findViewObject and passes in the name of a View Object.

 // appMod is an Application Module defined at design time.
    ViewObject vo = appMod.findViewObject("MyEmpView");

Specified by:: findViewObject in interface ApplicationModule

Parameters:: voName - a name.
Returns:: a View Object.
Throws:: InvalidObjNameException - if voName is invalid.; NoObjException - if voName does not exist.

findComponentObject

public ComponentObject findComponentObject(java.lang.String compName)

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

Specified by:: findComponentObject in interface ApplicationModule
Overrides:: findComponentObject in class ContainerObjectImpl

Parameters:: compName - name of the component object.

findViewLink

public ViewLink findViewLink(java.lang.String vlName)

Returns the specified View Link from this Application Module.

For example, in the following code sample, this method is used to return the first View Link defined in the Application Module appMod:

 // Get the first link defined in the Application Module.
 String[] linkNames = appMod.getViewLinkNames();
 if (linkNames.length < 1) {
     System.out.println("\n No links.");
     return;
 }
 ViewLink link = appMod.findViewLink(linkNames[0]);

Specified by:: findViewLink in interface ApplicationModule

Parameters:: vlName - a name.
Returns:: a View Link.
Throws:: InvalidObjNameException - if vlName is invalid.; NoObjException - if vlName does not exist.

getDBTransaction

public DBTransaction getDBTransaction()

Returns the database transaction associated with the root Application Module.

Returns:: a transaction.
Throws:: NotConnectedException - if the transaction or the root Application Module does not exist.

getViewObjects

public ViewObject[] getViewObjects()

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

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

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

createViewObjectFromQueryStmt

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

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

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

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

Specified by:: createViewObjectFromQueryStmt in interface ApplicationModule

Parameters:: qName - the name to be given to the View Object. If empty a name is generated.; query - the SQL query that defines the View Object.
Returns:: a new View Object.
Throws:: InvalidObjNameException - if qName is invalid.; NoObjException - if qName does not exist.

createViewObjectFromQueryClauses

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

Creates an updateable View Object.

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

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

Specified by:: createViewObjectFromQueryClauses in interface ApplicationModule

Parameters:: vuName - the name to be given to the View Object. If empty, a name is generated.; eoName - the name of the Entity Object from which the View Object is to be derived.; selectClause - a SQL statement SELECT clause.; fromClause - a SQL statement FROM clause.; whereClause - a SQL statement WHERE clause.; orderbyClause - a SQL statement ORDERBY clause.
Returns:: a new View Object.
Throws:: InvalidParamException - if vuName is invalid.; NameClashException - if vuName already exists.

executeCommand

public int executeCommand(java.lang.String command)

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

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

 public static void demoUpdateColumn(ApplicationModule appMod) {
     String sqlStr = "UPDATE EMP " +
                     "SET MGR=7007 " +
                     "WHERE MGR=7698 ";

     int n = appMod.getTransaction().executeCommand(sqlStr);
     System.out.println("Updated " + n + " rows.");
   }

Be careful when using executeCommand, because it will execute any valid SQL statement. For example, you could perform an operation like the following DDL command:

 appMod.getTransaction().executeCommand("DROP TABLE MYTEMPTABLE");

A pending database transaction could be committed inadvertently due to the implicit commit performed by DDL operations, as well as having any row locks released.

Parameters:: command - a valid SQL statement.

dumpQueryResult

public java.lang.String dumpQueryResult(java.lang.String query,
                                        java.lang.String dumpClassName,
                                        java.lang.String[] data)

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

The following code example uses dumpQueryResult.

 public static void demoSimpleFetch(ApplicationModule appMod) {
       // Define and execute a simple SQL statement.
       String sqlStr = "SELECT Emp.ename FROM EMP Emp ";
       // dumpQueryResult is a utility method for testing queries.
       String result = appMod.getTransaction().dumpQueryResult(sqlStr,
                                    "oracle.jbo.server.QueryDumpTab",
                                      null);

 System.out.println(sqlStr);
 System.out.println(result);  }

Parameters:: the - SQL query statement.; the - class that dumps the result to a string.; data - an array of data items.

createViewObject

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

createViewObject

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

Creates an updateable View Object.

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

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

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

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

Specified by:: createViewObject in interface ApplicationModule

Parameters:: voName - the name to be given to the View Object. If empty, a name is generated.; vDefName - a view definition.
Returns:: a new View Object.
Throws:: InvalidObjNameException - if voName is invalid.; NoObjException - if voName does not exist.

createComponentObject

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

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

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

Specified by:: createComponentObject in interface ApplicationModule
Overrides:: createComponentObject in class ContainerObjectImpl

Parameters:: coName - name of the component object. If empty, a name will be generated.; comDefName - name of the component Def (definition) object.
Throws:: InvalidObjNameException - if an invalid component name is used.

getApplicationModuleImpls

public ApplicationModuleImpl[] getApplicationModuleImpls()

Internal: Applications should not use this method.

Creates an array of Application Modules.

Returns:: the array of Application Modules.

getQueryInfo

public oracle.jbo.common.remote.rAttributeDescription[] getQueryInfo(ViewObject vo)

Internal: Applications should not use this method.

Constructs an array of a View Object's attribute descriptors.

Parameters:: vo - a View Object.
Returns:: the attribute descriptors array.

remove

public void remove()

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

This method should not be overridden.

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

reset

protected void reset()

Override this method to reset any cached varaibles for objects that belong to this appModule. It's a good practice to null out any variables that hold on to an instance of BC4J objects in this method. This method is invoked when a Transaction is disconnected for Transaction-pooling etc.

resetState

public void resetState(boolean reload)

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

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

 appModule.resetState(false);

Specified by:: resetState in interface ApplicationModule

Following copied from interface: oracle.jbo.ApplicationModule

Parameters:: reload - forces the application module to reload any child view usages, application module usages, and view link usages.

findVOsWithEntityUsage

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

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

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

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

findVOsWithEntityUsage

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

clearVOCaches

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

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

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

Specified by:: clearVOCaches in interface ApplicationModule

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

getClientProxyClassName

public java.lang.String getClientProxyClassName()

Internal: Applications should not use this method.

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

getClientProxyClassName

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

Internal: Applications should not use this method.

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

setExceptionHandler

public void setExceptionHandler(JboExceptionHandler hndlr)

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

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

Specified by:: setExceptionHandler in interface ApplicationModule

Parameters:: hndlr - an exception handler.

addWarning

public void addWarning(JboWarning warn)

Specifies the name of the handler that will perform special processing of warnings on the client.

Specified by:: addWarning in interface ApplicationModule

Parameters:: warn - a warning.

setStyles

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

Saves the Application Module's style definitions to the middle tier.

Specified by:: setStyles in interface ApplicationModule

Parameters:: name - a name under which the style definitions are to be stored.; clientDocument - the ClientDocument to be saved.

getStyles

public ClientDocument getStyles(java.lang.String name)

Gets the Application Module's style definitions from the middle tier.

Specified by:: getStyles in interface ApplicationModule

Parameters:: name - a name under which the style definitions are stored.

getSession

public Session getSession()

Returns the session information. Whenever a client connects to a middle tier server, a session is created. Note, this is the same session that is passed in the activate call.

Specified by:: getSession in interface ApplicationModule

See Also:: activate(Session)

getTransaction

public Transaction getTransaction()

Returns the transaction information. This method can be called from the client.

Specified by:: getTransaction in interface ApplicationModule

Following copied from interface: oracle.jbo.ApplicationModule

Returns:: the transaction.

findRSIForEntity

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

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

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

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

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

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

Specified by:: findRSIForEntity in interface ApplicationModule

Parameters:: rsis - an array of RowSetIterators; eRowHandle - an Entity row handle returned by DMLException.
See Also:: DMLException

setStoreForPassiveState

public void setStoreForPassiveState(byte storageType)

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

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

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

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

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

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

Specified by:: setStoreForPassiveState in interface ApplicationModule

Following copied from interface: oracle.jbo.ApplicationModule

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

reservePassivationId

public int reservePassivationId()

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

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

This method may be invoked to obtain a unique passivation identifier before passivation actually occurs. An example use case is an HTTP servlet that must encode all URLs with an Application Module's state identifier before that Application Module is passivated.

Specified by:: reservePassivationId in interface ApplicationModule

Following copied from interface: oracle.jbo.ApplicationModule

Returns:: a unique integer identifier that may later be used to passivate and activate Application Module state
See Also:: ApplicationModule.passivateState(int, byte[]).

passivateState

public int passivateState(byte[] clientData)

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

Serializes the current state of this Application Module's session, along with all changes cached, to a persistent store and returns a unique identifier with which to re-establish the state.

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

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

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

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

This method preserves currency. When ApplicationModule.activateState(int, boolean) 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, false);

 Row afterActivate = depts.getCurrentRow();

The values afterInsert and afterActivate should be the same.

Specified by:: passivateState in interface ApplicationModule

Following copied from interface: oracle.jbo.ApplicationModule

Parameters:: clientData - cached changes, or any information that a client might want to store.
Returns:: a unique integer identifier associated with an instance of the Application Module.

passivateState

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

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

Serializes the current state of this Application Module's session, along with all changes cached, to a persistent store 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.reservePassivationId().

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

Specified by:: passivateState in interface ApplicationModule

Following copied from interface: oracle.jbo.ApplicationModule

Parameters:: id - a reserved passivation id; clientData - cached changes, or any information that a client might want to store.
Returns:: a unique integer identifier associated with an instance of the Application Module.
See Also:: oracle.jbo.server.ApplicationModule#reservePassivationId()

activateState

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

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

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

When 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[]), which does not affect the transaction state.

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

The remove parameter gives you the option of removing the state or keeping it. A value of true will remove the session-state from the persistent store. If false is passed to the method, then the Application Module state remains in whatever persistence store was selected. It is up to the developer to devise a clean-up strategy for the redundant store.

Specified by:: activateState in interface ApplicationModule

Following copied from interface: oracle.jbo.ApplicationModule

Parameters:: id - a unique integer identifier associated with an instance of the Application Module.; remove - true to remove the session-state from the persistent store.
Returns:: a byte array containing any client information that was originally stored with the ApplicationModule.passivateState(byte[]) method.

removeState

public void removeState(int id)

Description copied from interface: ApplicationModule

Internal: Applications should not use this method.

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

 appModule.removeState(id);

Specified by:: removeState in interface ApplicationModule

Following copied from interface: oracle.jbo.ApplicationModule

Parameters:: id - an unique integer identifier associated with an instance of the Application Module.

launchTester

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

passivateState

protected void passivateState(Document doc,
                              Element parent)

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

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

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

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

activateState

protected void activateState(Element parent)

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

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

findViewObjectUsingEntity

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

Description copied from interface: ApplicationModule

Given an array of View Objects (the vos parameter), finds the first matching View Object. It uses the following rules to determine if the View Object matches the description.

Does the View Object use the specified Entity (entityName) as one of its Entity bases?
If attrName is not empty, is one of the View Object's attributes mapped to the Entity's attribute whose name is attrName[0]? If attrName is empty, i.e., it is either null or has no element, then this rule is skipped.
If the View Object passes the above two rules, then a check is made to see if the Entity base in this View Object is updateable or not. If it is, this View Object is returned. If it is not, we continue until we find one that with an updateable Entity base or until we exhaust the vos array. If none of the View Objects that pass the first two rules has an updateable Entity base, the first View Object that passed the first two rules is returned.

The method is used to find a View Object that can be used to edit an Entity Object's attribute. If a matching View Object is identified, and if attrName coming in was not empty, the View Object's attribute name is copied into the attrName.

Specified by:: findViewObjectUsingEntity in interface ApplicationModule

Following copied from interface: oracle.jbo.ApplicationModule

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.

afterConnect

protected void afterConnect()

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

beforeDisconnect

protected void beforeDisconnect()

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

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Business Components

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

oracle.jbo.server Class ApplicationModuleImpl

Uses of Application Module Instances

Root Application Modules

Extending the Application Module Implementation

Nesting Application Modules

Nested Application Modules and Transactions

DEFAULT_DEF_NAME

ApplicationModuleImpl

getSyncLock

createRootApplicationModule

createSharedDataHandle

createXMLSharedDataHandle

activate

getApplicationModuleDef

isRoot

addChild

removeChild

getDefName

getDefFullName

createApplicationModule

findApplicationModule

getApplicationModuleNames

transPostPushback

transPostRemove

transPostRevert

transPostRowOp

transPostGetAttr

transPostSetAttr

getEntityRowFromHandle

sync

setSyncMode

getSyncMode

getViewObjectNames

getViewLinkNames

getViewLinks

createViewLink

createViewLinkFromEntityAssocName

createViewLinkBetweenViewObjects

findViewObject

findComponentObject

findViewLink

getDBTransaction

getViewObjects

createViewObjectFromQueryStmt

createViewObjectFromQueryClauses

executeCommand

dumpQueryResult

createViewObject

createViewObject

createComponentObject

getApplicationModuleImpls

getQueryInfo

remove

reset

resetState

findVOsWithEntityUsage

findVOsWithEntityUsage

clearVOCaches

getClientProxyClassName

getClientProxyClassName

setExceptionHandler

addWarning

setStyles

getStyles

getSession

getTransaction

findRSIForEntity

setStoreForPassiveState

reservePassivationId

passivateState

passivateState

activateState

removeState

launchTester

passivateState

activateState

findViewObjectUsingEntity

afterConnect

beforeDisconnect

oracle.jbo.server
Class ApplicationModuleImpl