oracle.jbo
Interface ApplicationModule

All Superinterfaces:

ComponentObject, Properties, WarningContainer

All Known Implementing Classes:

ApplicationModuleImpl

public interface ApplicationModule
extends ComponentObject, WarningContainer

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

Field Summary

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

Method Summary

ComponentObject	createComponentObject(java.lang.String name, java.lang.String defName) Create the named ComponentObject (e.g.
ViewObject	createViewObject(java.lang.String viewName, java.lang.String defName) Creates a view object in this application module from the view definition.
ComponentObject	findComponentObject(java.lang.String name) Find the named ComponentObject
ViewLink	findViewLink(java.lang.String vlName) Finds the named view link.
ViewObject	findViewObject(java.lang.String viewName) Finds the named view object.
java.lang.String[]	getAllViewObjectNames() Returns an array of the names of all the view objects this app module knows about, including ones that have not been loaded.
DBTransaction	getDBTransaction() Gets this ApplicationModule's database transaction
java.lang.String[]	getLoadedViewObjectNames() Returns an array of the names of all the view objects that have been loaded into this app module thus far.
Session	getSession() Gets the application module's session.
java.lang.Object	getSyncLock() Gets the locking object for this application module.
Transaction	getTransaction() Gets this application module's database transaction.
void	sync(SyncOptions options) Synchronize local database(s) on device with remote database(s) on server.
java.lang.Object[]	transformExceptionParams(ViewObject[] vos, java.lang.String entityName, java.lang.String exceptionClassName, java.lang.Object[] params) Internal: Applications should not use this method. This method uses findViewObjectUsingEntity() to get the first view object that this entity is used in and then transforms the parameters from a given JboException from their entity layer equivalents to the view object equivalents.

Methods inherited from interface oracle.jbo.ComponentObject

getDefFullName, getDefName, getFullName, getName, remove

Methods inherited from interface oracle.jbo.Properties

getProperties, getProperty, getProperty, refreshProperty

Methods inherited from interface oracle.jbo.WarningContainer

addWarning

Field Detail

DEFAULT_ROOT_APP_MOD_NAME

static final java.lang.String DEFAULT_ROOT_APP_MOD_NAME

The default name of root application module.

See Also:

Constant Field Values

DEFAULT_DEF_FULL_NAME

static final java.lang.String DEFAULT_DEF_FULL_NAME

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

See Also:

Constant Field Values

REMOVE_SNAPSHOT

static final int REMOVE_SNAPSHOT

Deprecated. use ACTIVATE_REMOVE_FLAG instead

An activation flag. Setting this bit when performing activation will direct the activation framework to remove the snapshot record after activation.

See Also:

Constant Field Values

PASSIVATE_TRANSIENT_FLAG

static final int PASSIVATE_TRANSIENT_FLAG

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

See Also:

Constant Field Values

PASSIVATE_DEFER_FLAG

static final int PASSIVATE_DEFER_FLAG

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

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

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

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

See Also:

Constant Field Values

PASSIVATE_UNDO_FLAG

static final int PASSIVATE_UNDO_FLAG

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

See Also:

Constant Field Values

PASSIVATE_HINT_FLAG

static final int PASSIVATE_HINT_FLAG

An internal passivation flag. Indicates to passivation that it should passivate if a deferred passivation request is pending. Otherwise do nothing.

See Also:

Constant Field Values

PASSIVATE_TO_STACK_FLAG

static final int PASSIVATE_TO_STACK_FLAG

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

See Also:

Constant Field Values

ACTIVATE_TRANSIENT_FLAG

static final int ACTIVATE_TRANSIENT_FLAG

See Also:

Constant Field Values

ACTIVATE_REMOVE_FLAG

static final int ACTIVATE_REMOVE_FLAG

An activation flag. Setting this bit when performing activation will direct the activation framework to remove the snapshot record after activation.

See Also:

Constant Field Values

ACTIVATE_CLIENT_FLAG

static final int ACTIVATE_CLIENT_FLAG

See Also:

Constant Field Values

ACTIVATE_UNDO_FLAG

static final int ACTIVATE_UNDO_FLAG

See Also:

Constant Field Values

ACTIVATE_SKIP_RESTORE_VO_FROM_DEF

static final int ACTIVATE_SKIP_RESTORE_VO_FROM_DEF

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

See Also:

Constant Field Values

RESET_ROLLBACK_FLAG

static final int RESET_ROLLBACK_FLAG

A reset flag. Indicates that reset should first rollback the application module.

See Also:

Constant Field Values

RESET_RELOAD_FLAG

static final int RESET_RELOAD_FLAG

A reset flag. Indicates that reset should eagerly reload the application module.

See Also:

Constant Field Values

RESET_MANAGE_SNAPSHOTS

static final int RESET_MANAGE_SNAPSHOTS

A reset flag. Indicates that reset should not destroy the persistent snapshots that are managed by the snapshot stack. Used internally by the applicaiton pool.

See Also:

Constant Field Values

RESET_KEEP_ALL_SNAPSHOTS_FLAG

static final int RESET_KEEP_ALL_SNAPSHOTS_FLAG

A reset flag. Indicate that the none of the snapshots are destroyed by reset call.

See Also:

Constant Field Values

RESET_CLIENT_ONLY_FLAG

static final int RESET_CLIENT_ONLY_FLAG

May be used to indicate that reset should be performed on the client tier only.

See Also:

Constant Field Values

RESET_INTERNAL_FLAG

static final int RESET_INTERNAL_FLAG

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

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

See Also:

Constant Field Values

RELEASE_LEVEL_MANAGED

static final int RELEASE_LEVEL_MANAGED

See Also:

Constant Field Values

RELEASE_LEVEL_RESERVED

static final int RELEASE_LEVEL_RESERVED

See Also:

Constant Field Values

RELEASE_LEVEL_UNMANAGED

static final int RELEASE_LEVEL_UNMANAGED

See Also:

Constant Field Values

SYNC_LAZY

static final int SYNC_LAZY

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

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

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

See Also:

#getSyncMode(), #setSyncMode(int), Constant Field Values

SYNC_IMMEDIATE

static final int SYNC_IMMEDIATE

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

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

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

See Also:

#getSyncMode(), #setSyncMode(int), Constant Field Values

SYNC_BATCH

static final int SYNC_BATCH

Deprecated. deprecated since 9.0.5. This mode should not be used by client. Batch mode operations should be performed through working set objects instead.

See Also:

Constant Field Values

PASSIVATE_TO_DATABASE

static final byte PASSIVATE_TO_DATABASE

Used by setStoreForPassivate to serialize the state of the application module's session and any cached changes to the database. Database is the default target for setStoreForPassivate.

See Also:

#setStoreForPassiveState(byte), Constant Field Values

PASSIVATE_TO_FILE

static final byte PASSIVATE_TO_FILE

Used by setStoreForPassivate to serialize the state of the application module's session and any cached changes to a file.

See Also:

#setStoreForPassiveState(byte), Constant Field Values

PASSIVATE_TO_MEMORY

static final byte PASSIVATE_TO_MEMORY

Used by setStoreForPassivate to serialize the state of the application module's session and any cached changes to memory.

See Also:

#setStoreForPassiveState(byte), Constant Field Values

EFF_DT_PROPERTY_STR

static final java.lang.String EFF_DT_PROPERTY_STR

Used to set the current effective date value as a property value on a root application module. Use getProperties().put(ApplicationModule.EFF_DT_PROPERTY_STR, ) API to set the effective date. The runtime will use this value in parameter bindings for the queries.

See Also:

Constant Field Values

Method Detail

createViewObject

ViewObject createViewObject(java.lang.String viewName,
                            java.lang.String defName)

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

Parameters:

voName - the name to be assigned to the view object.

defName - the name of the view definition from which the new view object is to be created. It must be a fully qualified name (including the package name).

Returns:

a new view object.

findViewObject

ViewObject findViewObject(java.lang.String viewName)

Finds the named view object.

Parameters:

viewName - Name of view object to find

Returns:

ViewObject if found; null otherwise

getLoadedViewObjectNames

java.lang.String[] getLoadedViewObjectNames()

Returns an array of the names of all the view objects that have been loaded into this app module thus far. Does NOT include ViewObject's that have not been loaded.

Returns:

An array of view object names. If no view objects are found, will return an empty array.

getAllViewObjectNames

java.lang.String[] getAllViewObjectNames()

Returns an array of the names of all the view objects this app module knows about, including ones that have not been loaded.

Returns:

An array of view object names. If no view objects are found, will return an empty array.

createComponentObject

ComponentObject createComponentObject(java.lang.String name,
                                      java.lang.String defName)

Create the named ComponentObject (e.g. ViewObject) from the named component definition.

Parameters:

name - Name of the object

defName - Full name of the object's definition

Returns:

A ComponentObject if successful, or null otherwise

findComponentObject

ComponentObject findComponentObject(java.lang.String name)

Find the named ComponentObject

Parameters:

name - Name of the object

Returns:

The ComponentObject if found, or null otherwise

getDBTransaction

DBTransaction getDBTransaction()

Gets this ApplicationModule's database transaction

Returns:

The associated DBTransaction

getSession

Session getSession()

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

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

Note that this is the same session that is passed to the oracle.jbo.server.ApplicationModuleImpl#activate(Session) call.

Returns:

the session.

Throws:

java.lang.IllegalStateException - if no root application module is found. This could happen if the user calls this method on an application module that has been removed or has not fully been initialized.

See Also:

oracle.jbo.server.ApplicationModuleImpl#activate(Session)

getSyncLock

java.lang.Object getSyncLock()

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

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

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

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

Returns:

the locking object.

transformExceptionParams

java.lang.Object[] transformExceptionParams(ViewObject[] vos,
                                            java.lang.String entityName,
                                            java.lang.String exceptionClassName,
                                            java.lang.Object[] params)

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

Parameters:

vos - an array of possible view objects.

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

exceptionClassName - Qualified classname for the Exception which is being mapped

params - Parameters from the Exception that is to be transformed into view object equivalents.

Throws:

NoDefException - if the entity could not be found.

PersistenceException - if some error was found while loading the entity definition.

getTransaction

Transaction getTransaction()

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

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

Returns:

the transaction.

Throws:

java.lang.IllegalStateException - if no root application module is found. This could happen if the user calls this method on an application module that has been removed or has not fully been initialized.

findViewLink

ViewLink findViewLink(java.lang.String vlName)

Finds the named view link. The view link name passed in (vlName) may or may not be qualified with the name of the containing application module. If it is, the view link name is said to be an AM-qualified view link name. If not, the name is said to be an unqualified view link name.

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

If the view link name is unqualified, the search for the view link is made on this application module.

For example, suppose we have the following containership of nested application modules and view links:

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

ChildAM1.findViewLink("GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewLinkC") will succeed (using relative application module name).

ChildAM2.findViewLink("Root.ChildAM1.GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewLinkC") will succeed (using absolute application module name) and return the same view link as ChildAM1.findViewLink("GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewLinkC").

Both these are AM-qualified name cases.

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

For view link searching, findViewLink() makes no distinction between view links included the application module during design time and those created programmatically during runtime.

Example code:

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

Parameters:

vlName - the name of the view link.

Returns:

the view link. null if the view link is not found.

Throws:

NoObjException - if an AM-qualified name was specified and the containing application module could not be found.

InvalidObjNameException - if vlName is an invalid name. vlName must be a vaild Java name.

See Also:

#findApplicationModule(String), findViewObject(String)

sync

void sync(SyncOptions options)

Synchronize local database(s) on device with remote database(s) on server.

Parameters:

options -