|
Oracle Fusion Middleware Java API Reference for Oracle ADF Model 11g Release 1 (11.1.1.4.0) E10653-05 |
||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
public interface ApplicationModule
The interface for application modules. An application module is a logical container for coordinated objects related to a particular task with optional programming logic.
Root Application Module and Nested Application Module
An application module may be a root application module or a nested application module. A root application module is not contained in another applicatin module. It provides transaction context for all objects contained in it. It may optionally contain nested application modules. A root application module is created through JDNI calls. See below for details.
A nested application module is contained in another application module. The containing application module is referred to as the parent application module. If one traverses this containership ancestry, one will eventually find the root application module (which does not have a parent application module). A nested application module uses the transaction context provided by the root application module. Thus, data modifications performed in application modules parented by one root application module will commit or rollback together.
Transaction
Associated with the root application module is the Transaction
object, which provides this transaction context. From any (root or nested)
application module, the user can retrieve the transaction object through
a call to getTransaction(). In reality, getTransaction()
first locates the root application module and then returns the transaction
object from it.
The transaction object manages connection to database and entity caches. Thus, changes made through one view object are visible to other view objects as long as these view objects all parented by the one root application module. In contrast, if two view objects are parented by two separate root application modules, then changes made through the view object will not be seen by the second view object until the changes are committed to database through the first root application module and the second VO executes query (to retrieve the most up-to-date data from database).
Creating Application Module
A root application module is created by:
create() on the application module home.Here is a sample code to create a root application module:
java.util.Hashtable env = new java.util.Hashtable();
// Add environment entries into env...
javax.naming.Context ic = new InitialContext(env);
// 'defName' is the JNDI name for the application module
// definition from which the root application module is to
// be created
String defName = ...;
oracle.jbo.ApplicationModuleHome home = ic.lookup(defName);
oracle.jbo.ApplicationModule am = home.create();
One creates a nested application module by calling
createApplicationModule on the parent Application
module.
Component Object
As metioned earlier, an application module may contain other nested application modules. In addition, it may contain view objects and view links. View objects enable the user to set up queries to database and retrieve data through them. View links enable the user to related two view objects, such that events occuring on one of them (referred to as master) will cause the other view object (referred to as detail) to refresh its result set based on master's data values. These objects that an application module may contain are referred to as component objects.
A component object may be included in an application module during
design time or be created in it during runtime. Component
objects included during design time are referred to as static
component objects. Those that are created during runtime as
dynamic component objects. Dynamic component objects are
created through a call to a create... method.
Each component object (whether static or dynamic) is given a
name within the application module. This name can be used to
locate a component object. * find... methods are provided
for that purpose.
When using a find... method, the user may pass in
a relative or absolute component object name.
A relative name causes the application module to look for the component
object starting from this application module. An absolute name causes
the search to start from the root application module.
Application Module Custom Methods
The user may attach custom methods to an application module. BC4J
Design Time tools allows one to declare a method at the application
module interface level. The ApplicationModule interface
is extended to include declaration fo such a method. Then, the user
implements the method in the middle iter implementation class
(which extends oracle.jbo.server.ApplicationModuleImpl).
For the client tier, BC4J Design Time tools generate a client tier proxy for that
method (based on the user's choice of cli-tier-to-middle-tier interaction platform).
This enables the user to invoke the custom method in the client tier
(3 tier mode) or directly in the middle iter (2 tier mode).
For the middle tier, ApplicationModuleImpl.
is the base implementation of this interface.
The framework provides an ApplicationPool
interface that clients can use to manage and share a pool of application
modules.
Application Module Definition
Behind every instance of application module is a definition (or metaobject) that describes the application module. One can look at the application module definition as the factory for application module instance. Another way of looking at this is that the definition objects is akin to the Java class (in that the class describes instances and in that one uses the class to create instances).
An application module definition is identified by its full name. The definition's full name is qualified by the package in which the definition resides (just like a Java class).
In the middle tier, application module definitions are managed by
oracle.jbo.server.MetaObjectManager. One can find a
specific definition object by issuing:
String defName = ...;
oracle.jbo.server.ApplicationModuleDefImpl def;
def = oracle.jbo.server.ApplicationModuleDefImpl.findDefObject(defName);
where defName is a fully (package) qualified application
module definition name.
The user has the option of using the default application module definition or a custom application module definition. The default application module definition produces application module instances that do not have any custom methods or static component objects.
If the user wishes to include custom methods or static component objects,
he should define a custom application module definition in BC4J design time.
The default application module definition has a special definition name (see
DEFAULT_DEF_FULL_NAME below).
ApplicationModuleHome,
ViewObject,
ViewLink,
Transaction,
ApplicationPool,
ApplicationModuleImpl,
ApplicationModuleDefImpl,
MetaObjectManager| Field Summary | |
|---|---|
static int |
ACTIVATE_CLIENT_FLAG
|
static int |
ACTIVATE_REMOVE_FLAG
An activation flag. |
static int |
ACTIVATE_SKIP_RESTORE_VO_FROM_DEF
An activation flag. |
static int |
ACTIVATE_TRANSIENT_FLAG
|
static int |
ACTIVATE_UNDO_FLAG
|
static java.lang.String |
DEFAULT_DEF_FULL_NAME
The name of the default application module definition (one that represents oracle.jbo.server.ApplicationModuleDefImpl). |
static java.lang.String |
DEFAULT_ROOT_APP_MOD_NAME
The default name of root application module. |
static 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 java.lang.String |
IMAGE_LOC
The name of the (default) icon that can be used to represent an Application Module instance. |
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. |
| Fields inherited from interface oracle.jbo.GenericHints |
|---|
PROPERTY_LABEL, PROPERTY_LABEL_PLURAL, PROPERTY_TOOLTIP |
| Method Summary | |
|---|---|
byte[] |
activateState(int id,
boolean remove)
Deprecated. deprecated since 9.0.5. Use activateState(int, SessionData, int) with the
PERSISTNENT_SNAPSHOT bit set and a null SessionData instead. |
byte[] |
activateState(int id,
boolean remove,
SessionData info)
Deprecated. deprecated since 9.0.5. Use activateState(int, SessionData, int) with the
PERSISTNENT_SNAPSHOT bit set instead. |
byte[] |
activateState(int id,
SessionData info,
int flags)
Internal: Applications should not use this method. |
byte[] |
activateStateForUndo(java.lang.String id,
int flags)
Restore an application module undo record. |
void |
addWarning(JboWarning warn)
Override from WarningContainer |
void |
clearVOCaches(java.lang.String entityName,
boolean recurse)
Clears the view object cache for all view objects that use an entity object identified by entityName. |
ApplicationModule |
createApplicationModule(java.lang.String amName,
java.lang.String defName)
Creates a nested application module in this application module from the application module definition. |
ComponentObject |
createComponentObject(java.lang.String coName,
java.lang.String coDefName)
Creates a component object in this application module from the component object definition. |
ViewDef |
createCompositeViewDef(java.lang.String name,
java.lang.String fullName)
|
ViewLink |
createViewLink(java.lang.String vlName,
java.lang.String defName,
ViewObject master,
ViewObject detail)
Creates a view link in this application module from the view link definition. |
ViewLink |
createViewLinkBetweenViewObjects(java.lang.String vlName,
java.lang.String accessorName,
ViewObject master,
AttributeDef[] srcAttrs,
ViewObject detail,
AttributeDef[] destAttrs,
java.lang.String assocClause)
Creates a view link in this application module. |
ViewLink |
createViewLinkFromEntityAssocName(java.lang.String vlName,
java.lang.String entityAssocName,
ViewObject master,
ViewObject detail)
Creates a view link in this application module from an entity association. |
ViewObject |
createViewObject(java.lang.String voName,
java.lang.String defName)
Creates a view object in this application module from the view definition. |
ViewObject |
createViewObjectFromQueryClauses(java.lang.String voName,
java.lang.String eoName,
java.lang.String selectClause,
java.lang.String fromClause,
java.lang.String whereClause,
java.lang.String orderByClause)
Creates a view object in this application module from an entity Object and additional SQL clauses. |
ViewObject |
createViewObjectFromQueryStmt(java.lang.String voName,
java.lang.String sqlStatement)
Creates a view object in this application module based on a SQL statement. |
ViewObject |
createViewObjectFromQueryStmt(java.lang.String voName,
java.lang.String sqlStatement,
java.lang.String voImplClassName)
Creates a read-only view object similar to createViewObjectFromQueryStmt(String, String). |
ViewObject |
createViewObjectOnEntity(java.lang.String voName,
java.lang.String eoName)
|
ViewObject |
createViewObjectOnRowSet(java.lang.String voName,
RowSet rs)
|
ApplicationPoolSvcMsgContext |
doPoolMessage(ApplicationPoolSvcMsgContext ctx)
Internal use only. |
RowSet |
executeQueryOnViewObjects(java.lang.String sqlStmt)
|
void |
fetchAttributeProperties(java.lang.String[] voNames,
java.lang.String[][] voAttrNames,
LocaleContext locale)
Fetches all custom properties for the given list of attributes for the named view objects in this application module over to the remote client objects in one network roundtrip. |
ApplicationModule |
findApplicationModule(java.lang.String amName)
Finds the named application module. |
ComponentObject |
findComponentObject(java.lang.String coName)
Finds the named component object. |
RowSetIterator |
findRSIForEntity(RowSetIterator[] rsis,
int eRowHandle)
Finds the RowSetIterator associated with the
specified entity row handle. |
ViewLink |
findViewLink(java.lang.String vlName)
Finds the named view link. |
ViewObject |
findViewObject(java.lang.String voName)
Finds the named view object. |
ViewObject |
findViewObjectUsingEntity(ViewObject[] vos,
java.lang.String entityName,
java.lang.String[] attrName)
Given an array of view objects (the vos parameter), finds the first matching view object. |
ViewObject |
findViewObjectWithParameters(java.lang.String voname,
VariableManager params,
boolean executeIfNeeded)
Internal: Applications should not use this method. Given a view object name, use findViewObject(String name) to find the view object and set it's named bind parameters with the values passed in the 'params' argument. |
java.lang.String[] |
getApplicationModuleNames()
Returns an array of names of the nested application modules that are currently loaded within this application module. |
java.lang.String[] |
getApplicationModuleNames(boolean inclLoadedOnes,
boolean fromDef)
Returns an array of names of the nested application modules in this application module. |
JboExceptionHandler |
getExceptionHandler()
|
java.lang.String |
getListBindingName(RowSetIterator rsi,
Key rowKey,
java.lang.String attrName,
java.lang.String lbName)
|
RowSetIterator |
getListBindingRSI(RowSetIterator rsi,
Key rowKey,
java.lang.String attrName,
java.lang.String lbName)
|
int |
getMostRecentStackId()
Internal: Applications should not use this method. |
RowSetIterator |
getPreferredListRSI(RowSetIterator rsi,
Key rowKey,
java.lang.String attrName,
java.lang.String lbName)
|
int |
getReleaseLevel()
Returns the release level that should be employed by clients of this application module. |
Session |
getSession()
Gets the application module's session. |
ClientDocument |
getStyles(java.lang.String name)
Gets the style definition from an XML file in the middle tier. |
java.lang.Object |
getSyncLock()
Gets the locking object for this application module. |
int |
getSyncMode()
Returns the sync mode for this application module. |
Transaction |
getTransaction()
Gets this application module's database transaction. |
java.lang.String[] |
getViewLinkNames()
Returns an array of the names of the view links that are currently loaded within this application module. |
java.lang.String[] |
getViewLinkNames(boolean inclLoadedOnes,
boolean fromDef)
Returns an array of names of the view links in this application module. |
java.lang.String[] |
getViewObjectNames()
Returns an array of names of the view objects that are currently loaded within this application module. |
java.lang.String[] |
getViewObjectNames(boolean inclLoadedOnes,
boolean fromDef)
Returns an array of names of the view objects in this application module. |
boolean |
isRoot()
Returns true if this application module is a root application module. |
boolean |
isValidIdForUndo(java.lang.String id)
Determines if an id created using passivateStateForUndo(String, byte[], int)
is still valid. |
int |
passivateState(byte[] clientData)
Deprecated. deprecated since 9.0.5. Use passivateState(byte[]) with the PERSISTNENT_SNAPSHOT bit set
instead. |
int |
passivateState(byte[] clientData,
int flags)
Internal: Applications should not use this method. |
int |
passivateState(int id,
byte[] clientData)
Deprecated. deprecated since 9.0.5. Use passivateState(int, byte[], int) with the PASSIVATE_TRANSIENT_FLAG
not set instead. |
int |
passivateState(int id,
byte[] clientData,
int flags)
Internal: Applications should not use this method. |
java.lang.String |
passivateStateForUndo(java.lang.String id,
byte[] clientData,
int flags)
Create an application module undo record. |
void |
prepareSession(SessionData info)
Internal: Applications should not use this method. |
void |
prepareViewObjects(java.lang.String[] voNames,
java.lang.String[][] voAttrNames,
LocaleContext locale)
Prepares view objects for execution. |
void |
processChangeNotifications()
|
void |
removeState(int id)
Internal: Applications should not use this method. |
int |
reservePassivationId()
Deprecated. deprecated since 9.0.5. Use reserveSnapshotId(int) with the PERSISTNENT_SNAPSHOT bit set
instead. |
int |
reserveSnapshotId(int flags)
Internal: Applications should not use this method. |
void |
resetState(boolean reload)
Deprecated. since 9.0.5. Use resetState(int) with
the RESET_RELOAD_FLAG enabled instead. |
void |
resetState(int flags)
Advanced use only |
void |
setExceptionHandler(JboExceptionHandler hndlr)
Sets the exception handler for this application module. |
void |
setReleaseLevel(int releaseLevel)
|
void |
setStoreForPassiveState(byte storageType)
Internal: Applications should not use this method. |
void |
setStyles(java.lang.String name,
ClientDocument clientDocument)
Saves a style definition XML file in the middle tier. |
void |
setSyncMode(int mode)
Sets the data synchronization mode between the client and the middle tier. |
void |
sync()
In 3 tier mode, this method enumerates through all row sets contained in this application module and flushes any changes pending in these row sets to the middle tier. |
java.lang.Object[] |
transformExceptionParams(ViewObject[] vos,
java.lang.String entityName,
java.lang.String exceptionClassName,
java.lang.Object[] params)
Internal: Applications should not use this method. This method uses findViewObjectUsingEntity() to get the first view object that this entity is used in and then transforms the parameters from a given JboException from their entity layer equivalents to the view object equivalents. |
| Methods inherited from interface oracle.jbo.ComponentObject |
|---|
getDefFullName, getDefName, getFullName, getName, remove |
| Methods inherited from interface oracle.jbo.GenericHints |
|---|
getHintValue, getLabel, getLabelPlural, getTooltip |
| Methods inherited from interface oracle.jbo.Properties |
|---|
getProperties, getProperty, getProperty, refreshProperty |
| Field Detail |
|---|
static final java.lang.String DEFAULT_ROOT_APP_MOD_NAME
static final java.lang.String DEFAULT_DEF_FULL_NAME
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.
static final int REMOVE_SNAPSHOT
ACTIVATE_REMOVE_FLAG instead
static final int PASSIVATE_TRANSIENT_FLAG
passivateState(byte[], int) and
activateState(int, SessionData, int) for more
information.
static final int PASSIVATE_DEFER_FLAG
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.
static final int PASSIVATE_UNDO_FLAG
static final int PASSIVATE_HINT_FLAG
static final int PASSIVATE_TO_STACK_FLAG
static final int ACTIVATE_TRANSIENT_FLAG
static final int ACTIVATE_REMOVE_FLAG
static final int ACTIVATE_CLIENT_FLAG
static final int ACTIVATE_UNDO_FLAG
static final int ACTIVATE_SKIP_RESTORE_VO_FROM_DEF
static final int RESET_ROLLBACK_FLAG
static final int RESET_RELOAD_FLAG
static final int RESET_MANAGE_SNAPSHOTS
static final int RESET_KEEP_ALL_SNAPSHOTS_FLAG
static final int RESET_CLIENT_ONLY_FLAG
static final int RESET_INTERNAL_FLAG
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.
static final int RELEASE_LEVEL_MANAGED
static final int RELEASE_LEVEL_RESERVED
static final int RELEASE_LEVEL_UNMANAGED
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.
getSyncMode(),
setSyncMode(int),
Constant Field Valuesstatic 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.
getSyncMode(),
setSyncMode(int),
Constant Field Valuesstatic final int SYNC_BATCH
static final byte PASSIVATE_TO_DATABASE
setStoreForPassiveState(byte),
Constant Field Valuesstatic final byte PASSIVATE_TO_FILE
setStoreForPassiveState(byte),
Constant Field Valuesstatic final byte PASSIVATE_TO_MEMORY
setStoreForPassiveState(byte),
Constant Field Valuesstatic final java.lang.String EFF_DT_PROPERTY_STR
static final java.lang.String IMAGE_LOC
| Method Detail |
|---|
ApplicationModule createApplicationModule(java.lang.String amName,
java.lang.String defName)
defName parameter.
Example code:
ApplicationModule nestedAM = parentAM.createApplicationModule("MyAM", "package1.Package1Module");
amName - the name to be assigned to the application module.
If null, a system generated
name is assigned.defName - the name of the application module definition from which the new
nested application module is to be created. It must
be a fully qualified definition name (including
the package name).
If DEFAULT_DEF_FULL_NAME or null is passed,
a generic application module (one without custom
code or static component objects) is created.
InvalidObjNameException - if amName is an invalid name.
amName must be a vaild Java name.
NameClashException - if a nested application module of amName
already exists in this application module. The
application module name must be unique.
NoDefException - if application module definition (named by the
defName parameter) was not found.
Make sure defName is fully qualified
with the package name.
PersistenceException - if some error was found while loading the
application module definition.ApplicationModule findApplicationModule(java.lang.String amName)
amName) may be a single part name or a multi-part
name. If it is multi-part (separated by dots), each part from
left represents the containing (parent) application module.
Based on the name, findApplicationModule first tries to find the nested application module starting with this application module. If it finds a match, it returns it. In this case, the name is said to be relative.
If it does not find a match, it starts searching for the application module from the root application module. If it finds a match, it returns it. In this case, the name is said to be absolute.
For example, suppose we have the following containership of nested application modules:
Root (root Application Module)
ChildAM1
GrandChildAM1_1
GrandChildAM1_2
GreatGrandChildAM1_2_1
ChildAM2
GrandChildAM2_1
If one calls findApplicationModule("GrandChildAM1_2") on ChildAM1, it will find it from ChildAM1 and return it.
If one calls findApplicationModule("GrandChildAM1_2.GreatGrandChildAM1_2_1") on ChildAM1, it will find it from ChildAM1 and return it.
Both these are relative name cases.
If one calls findApplicationModule("Root.ChildAM2.GrandChildAM2_1") on ChildAM1, it will first try to find it from ChildAM1. This will fail because ChildAM1 does not have a nested application module named Root. After that, the search begins from the root application module. This will succeed because Root has a nested application module named ChildAM2 and ChildAM2 in turn has a nested nested application module named GrandChildAM2_1. This is an absolute name case.
For application module searching, findApplicationModule() makes no distinction between nested application modules included in other application modules during design time and those created programmatically during runtime.
Example code:
ApplicationModule nestedAM = parentAM.findApplicationModule("MyNestedAM");
amName - the name of the nested application module. It may be
a relative name or an absolute name. If null,
the root application module is returned.
null if
the application module is not found.
InvalidObjNameException - if amName is an invalid name.
amName must be a vaild Java name.java.lang.String[] getApplicationModuleNames()
Example code:
String[] nestedAMNames = parentAM.getApplicationModuleNames();
// If you want to retrieve all currently loaded nested Application Modules
ApplicationModule[] nestedAMs = new ApplicationModule[nestedAMNames.length];
for (int i = 0; i < nestedAMNames.length; i++)
{
nestedAM[i] = parentAM.findApplicationModule(nestedAMNames[i]);
}
If you need names of application modules that are not yet loaded,
use getApplicationModuleNames(boolean, boolean)
findApplicationModule(String)
java.lang.String[] getApplicationModuleNames(boolean inclLoadedOnes,
boolean fromDef)
This method allows the user to control whether the returning names are those of loaded (instantiated) nested application modules, or those of not yet loaded (uninstantiated) nested application modules, or both. Not yet loaded application modules would appear only if lazy loading is turned on.
Note that getApplicationModuleNames()getApplicationModuleNames(true, false).
If this method is called with loadedOnes = true and
fromDef = true, both loaded and not-yet-loaded
application module names are returned. No duplicate name is returned.
Note that loaded application modules include dynamically created ones.
inclLoadedOnes - if true, loaded ones are
returned.fromDef - if true, names of the child application modules from the
application module definition are returned. Some of
these child AMs could have already been loaded and some may
have not yet been loaded.
void sync()
SYNC_IMMEDIATE,
no pending changes would be found, and sync() will
effectively be a no-op.
In 2 tier mode, this method is a no-op, as all changes are applied immediately.
void setSyncMode(int mode)
SYNC_LAZY and SYNC_IMMEDIATE.
SYNC_LAZY is typically more efficient in that it causes fewer round trips to the middle tier.
Note that the sync mode is an attribute of the root application
module. If one calls getSyncMode or setSyncMode
on a nested application module, it is routed to the root
application module. Also, note that pending changes are
managed at the root application module. When the changes
are flushed from the client to the middle tier, all changes
pending under the root application module are flushed.
mode - the new synchronization mode: SYNC_LAZY or
SYNC_IMMEDIATE.getSyncMode(),
SYNC_LAZY,
SYNC_IMMEDIATEint getSyncMode()
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.
setSyncMode(int mode),
SYNC_LAZY,
SYNC_IMMEDIATE
ViewObject createViewObject(java.lang.String voName,
java.lang.String defName)
defName parameter.
Example code:
ViewObject vo = am.createViewObject("MyVO", "package1.DeptView");
voName - the name to be assigned to the view object.
If null, a system generated
name is assigned.defName - the name of the view definition from which the new
view object is to be created. It must
be a fully qualified name (including the package name).
InvalidObjNameException - if voName is an invalid name.
voName must be a vaild Java name.
NameClashException - if a view object of voName
already exists in this application module. The
view object name must be unique.
NoDefException - if view definition (named by the
defName parameter) was not found.
Make sure defName is fully qualified
with the package name.
PersistenceException - if some error was found while loading the
view definition.
ViewObject createViewObjectFromQueryClauses(java.lang.String voName,
java.lang.String eoName,
java.lang.String selectClause,
java.lang.String fromClause,
java.lang.String whereClause,
java.lang.String orderByClause)
For example, suppose we have an entity object named
Emp in a package named package1.
The following code block creates a view object using
this method:
ViewObject vo = am.createViewObjectFromQueryClauses("MyVO",
"package1.Emp", // Fully qualified EO name
"E.ENAME as EmpName, E.EMPNO as EmpNo", // select clause
"EMP E", // from clause
"E.DEPTNO = 10", // where clause
null); // order by clause
Internally, this methods create a temporary view definition from the entity object and sets the select, from, where, and order-by clauses of the view definition. Then, it uses that view definition to create the view object.
voName - the name to be assigned the view object.
If null, a system generated
name is assigned.eoName - the name of the entity object from which the
new view object is to be derived.selectClause - a SQL statement SELECT clause.
The name or alias of each column should match
the name of the corresponding entity object's
attribute. In the above example code,
"ENAME" and "EMPNO" are database column names,
and "EmpName" and "EmpNo" are entity object's
attribute names. If null, a default
SELECT clause will be generated from the entity
definition (selecting all entity attributes that
are mapped to database query columns).fromClause - a SQL statement FROM clause. If null, a
default FROM clause will be generated from the entity
definition.whereClause - a SQL statement WHERE clause. If null,
no where clause is specified, i.e., all rows from
the database table/view are retrieved.orderByClause - a SQL statement ORDER-BY clause. If null
no order-by clause is established.
InvalidObjNameException - if voName is an invalid name.
voName must be a vaild Java name.
NameClashException - if a view object of voName
already exists in this application module. The
view object name must be unique.
NoDefException - if entity object (named by the
eoName parameter) was not found.
Make sure eoName is fully qualified
with the package name.
PersistenceException - if some error was found while loading the
entity definition.
SQLStmtException - if a SQL syntax problem has been discovered while
attempting to parse the SQL clauses.
ViewObject createViewObjectOnEntity(java.lang.String voName,
java.lang.String eoName)
ViewObject createViewObjectOnRowSet(java.lang.String voName,
RowSet rs)
ViewObject createViewObjectFromQueryStmt(java.lang.String voName,
java.lang.String sqlStatement)
Example code:
ViewObject vo = am.createViewObjectFromQueryStmt("MyVO",
"SELECT EMP.ENAME as EmpName, EMP.MGR as EmpMgr FROM EMP");
In this example, the resulting view object will have two attributes, named EmpName and EmpMgr.
Internally, this method create a temporary view definition with no entity object base and maps database columns to attribute definitions. Then, it uses that view definition to create the view object.
voName - the name to be assigned the view object.
If null, a system generated
name is assigned.sqlStatement - the SQL query statement for the view object.
InvalidObjNameException - if voName is an invalid name.
voName must be a vaild Java name.
NameClashException - if a view object of voName
already exists in this application module. The
view object name must be unique.
SQLStmtException - if a SQL syntax problem has been discovered while
attempting to parse the SQL statement.
ViewObject createViewObjectFromQueryStmt(java.lang.String voName,
java.lang.String sqlStatement,
java.lang.String voImplClassName)
createViewObjectFromQueryStmt(String, String).
Example code:
ViewObject vo = am.createViewObjectFromQueryStmt("MyVO",
"SELECT EMP.ENAME as EmpName, EMP.MGR as EmpMgr FROM EMP", "MyEmpVOImpl");
In this example the ViewObject returned is an instance of MyEmpVOImpl. MyEmpVOImpl must
extend the oracle.jbo.ViewObjectImpl class.
InvalidObjNameException - if voName is an invalid name.
voName must be a vaild Java name.
NameClashException - if a view object of voName
already exists in this application module. The
view object name must be unique.
SQLStmtException - if a SQL syntax problem has been discovered while
attempting to parse the SQL statement.
CustomClassNotFoundException - if voImplClassName is not found.ViewObject findViewObject(java.lang.String voName)
voName) may or may not be qualified with the name
of the containing application module. If it is, the view object
name is said to be an AM-qualified view object name. If not, the name
is said to be an unqualified view object name.
An AM-qualified name is a multi-part name (separated by dots).
The last part of the name is the view object name (view object
part of the name). All preceding parts consistitute the name of
the application module that contains the view object. For an AM-qualified
name, findViewObject() first locates the containing application
module using the application module name. In fact, it uses
findApplicationModule(String) to find the application
module. Thus, the application module name in an AM-qualified view object
name may be relative or absolute application module name.
See findApplicationModule() discussions on absolute
and relative application module names. Once
the application module is found, the view object part is used to
find the view object in that application module.
If the view object name is unqualified, the search for the view object is made on this application module.
For example, suppose we have the following containership of nested application modules and view objects:
Root (root Application Module)
ChildAM1
ViewObjectA
GrandChildAM1_1
ViewObjectB
GrandChildAM1_2
GreatGrandChildAM1_2_1
ViewObjectC
ChildAM2
GrandChildAM2_1
ViewObjectD
ChildAM1.findViewObject("GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewObjectC") will succeed (using relative application module name).
ChildAM2.findViewObject("Root.ChildAM1.GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewObjectC") will succeed (using absolute application module name) and return the same view object as ChildAM1.findViewObject("GrandChildAM1_2.GreatGrandChildAM1_2_1.ViewObjectC").
Both these are AM-qualified name cases.
GrandChildAM2_1.findViewObject("ViewObjectD") will succeed. This is is an unqualified name case.
For view object searching, findViewObject() makes no distinction between view objects included the application module during design time and those created programmatically during runtime.
Example code:
ViewObject vo = am.findViewObject("MyVO");
voName - the name of the view object.
null if the view object
is not found.
NoObjException - if an AM-qualified name was specified and the
containing application module could not be found.
InvalidObjNameException - if voName is an invalid name.
voName must be a vaild Java name.findApplicationModule(String),
findViewLink(String)java.lang.String[] getViewObjectNames()
Example code:
String[] voNames = am.getViewObjectNames();
// If you want to retrieve all currently loaded view objects
ViewObject[] vos = new ViewObject[voNames.length];
for (int i = 0; i < voNames.length; i++)
{
vos[i] = am.findViewObject(voNames[i]);
}
If you need names of view objects that are not yet loaded,
use getViewObjectNames(boolean, boolean)
findViewObject(String)
java.lang.String[] getViewObjectNames(boolean inclLoadedOnes,
boolean fromDef)
This method allows the user to control whether the returning names are those of loaded (instantiated) view objects, or those of not yet loaded (uninstantiated) view objects, or both. Not yet loaded view objects would appear only if lazy loading is turned on.
Note that getViewObjectNames()getViewObjectNames(true, false).
If this method is called with loadedOnes = true and
fromDef = true, both loaded and not-yet-loaded
view object names are returned. No duplicate name is returned.
Note that loaded view objects include dynamically created ones.
inclLoadedOnes - if true, loaded ones are
returned.fromDef - if true, names of the view objects from the
application module definition are returned. Some of
these VOs could have already been loaded and some may
have not yet been loaded.
ViewLink createViewLink(java.lang.String vlName,
java.lang.String defName,
ViewObject master,
ViewObject detail)
defName parameter.
master and detail identifies two
view objects that will linked by this new view link.
For example, assume that during design time, the user used the design time view object Wizard to create two view objects, DeptView and EmpView inside of a package named package1. Then, assume that the user invoked the view link wizard to create a view link definition (in the same package) named DeptEmpViewLink, that correlates the DeptNo attribute of DeptView to the DeptNo attribute of EmpView.
Given these, the user can use the code block like the following to
create in this application module (represented by am)
two view objects and a view link programmatically (during runtime):
ViewObject voDept = am.createViewObject("MyDeptVO", "package1.DeptView");
ViewObject voEmp = am.createViewObject("MyEmpVO", "package1.EmpView");
ViewLink vl = am.createViewLink("MyDeptEmpLink", "package1.DeptEmpViewLink",
voDept, voEmp);
This will set up a master-detail relationship between voDept and voEmp. Whenever voDept's currency moves, voEmp's result set will be refreshed to show employees that work in the department.
This method verifies that the view objects passed in match
the view link definition. Specifically, in the above example,
createViewLink() checks to ensure that the master (voDept)
is an instance of package1.DeptView and that the detail
(voEmp) is an instance of package1.EmpView.
If match fails, an error (InvalidParamException) is reported,
as the user tried to set up a view link between two view objects where the View
Link definition does not match the view link definitions of master and
detail.
One exception to this match rule is that createViewLink() allows the user to reverse the view link direction. Thus, in the above example, the following would have succeeded:
ViewLink vl = am.createViewLink("MyEmpDeptLink", "package1.DeptEmpViewLink",
voEmp, voDept);
Note that in the above code block, voEmp is the master and voDept is the detail. The view link definition is used in the reverse direction.
vlName - the name to be assigned to the view link.
If null, a system generated
name is assigned.defName - the name of the link definition from which the new
view link is to be created. It must
be a fully qualified name (including the package name).master - the view object that is to play the role of master.detail - the view object that is to play the role of detail.
InvalidObjNameException - if vlName is an invalid name.
vlName must be a vaild Java name.
NameClashException - if a view link of vlName
already exists in this application module. The
view link name must be unique.
NoDefException - if view link definition (named by the
defName parameter) was not found.
Make sure defName is fully qualified
with the package name.
PersistenceException - if some error was found while loading the
view link definition.
InvalidParamException - (1) if master or detail is
null
(2) if master and detail
represent the same view object (circular view
link is disallowed)
(3) if master and detail's
definitions do not match the view link
definition. See the above discussion for
more info.
InvalidOperException - if a recursive view link chain is found.
Suppose we have three view objects, VO_A, VO_B, VO_C.
Suppose we have view links that link VO_A to
VO_B, VO_B to VO_C, and VO_C back to VO_A. Then,
we have a recursive view link chain. This is
disallowed and reported as an error.createViewObject(String, String)
ViewLink createViewLinkFromEntityAssocName(java.lang.String vlName,
java.lang.String entityAssocName,
ViewObject master,
ViewObject detail)
For example, suppose we have two entity objects in package package1: Dept and Emp. An entity association DeptEmpAssoc is created between the two entity objects relating the Deptno attribute. Two view objects are defined on these entity objects, DeptView and EmpView.
The following code creates two view objects in this application module and link them, using DeptEmpAssoc:
ViewObject voDept = am.createViewObject("MyDeptVO", "package1.DeptView");
ViewObject voEmp = am.createViewObject("MyEmpVO", "package1.EmpView");
ViewLink vl = am.createViewLinkFromEntityAssocName("MyDeptEmpLink",
"package1.DeptEmpAssoc",
voDept, voEmp);
This will set up a master-detail relationship between voDept and voEmp. Whenever voDept's currency moves, voEmp's result set will be refreshed to show employees that work in the department.
Internally, this method creates a temporary view link definition from the entity association and uses it to create the view link.
This method verifies that the view objects passed in match
the entity association definition. Specifically, in the above example,
createViewLinkFromEntityAssocName() checks to ensure that
the master (voDept) uses the Dept entity object
as one of its entity bases and the detail (voEmp) uses the
Emp entity object as one of its entity bases.
If match fails, an error (InvalidParamException) is reported,
as the user tried to set up a view link between two view objects where the
entity association is unable to relate the two view objects.
The primary difference between
createViewLink(String, String, ViewObject, ViewObject)
and
createViewLinkFromEntityAssocName is that the former requires
the view link definition name, and the latter requires the entity
association name.
vlName - the name to be assigned to the view link.
If null, a system generated
name is assigned.entityAssocName - the name of the entity association from which the
new view link is to be derived. It must
be a fully qualified name (including the package name).master - the view object that is to play the role of master.detail - the view object that is to play the role of detail.
InvalidObjNameException - if vlName is an invalid name.
vlName must be a vaild Java name.
NameClashException - if a view link of vlName
already exists in this application module. The
view link name must be unique.
NoDefException - if entity association (named by the
entityAssocName parameter) was not found.
Make sure entityAssocName is fully qualified
with the package name.
PersistenceException - if some error was found while loading the
entity association.
InvalidParamException - (1) if master or detail is
null
(2) if master and detail
represent the same view object (circular view
link is disallowed)
(3) if master and detail's
definitions do not match the entity association's
definition. See the above discussion for
more info.
InvalidOperException - if a recursive view link chain is found.
Suppose we have three view objects, VO_A, VO_B, VO_C.
Suppose we have view links that link VO_A to
VO_B, VO_B to VO_C, and VO_C back to VO_A. Then,
we have a recursive view link chain. This is
disallowed and reported as an error.createViewObject(String, String)
ViewLink createViewLinkBetweenViewObjects(java.lang.String vlName,
java.lang.String accessorName,
ViewObject master,
AttributeDef[] srcAttrs,
ViewObject detail,
AttributeDef[] destAttrs,
java.lang.String assocClause)
For example, suppose we have two view objects in package package1: DeptView and EmpView. Each of them has an attribute named Deptno.
The following code creates two view objects in this application module and link them by the Deptno attribute:
ViewObject voDept = am.createViewObject("MyDeptVO", "package1.DeptView");
ViewObject voEmp = am.createViewObject("MyEmpVO", "package1.EmpView");
AttributeDef[] deptLinkAttrs = new AttributeDef[] { voDept.findAttributeDef("Deptno") };
AttributeDef[] empLinkAttrs = new AttributeDef[] { voEmp.findAttributeDef("Deptno") };
ViewLink vl = am.createViewLinkFromEntityAssocName("MyDeptEmpLink",
"Employees",
voDept, deptLinkAttrs,
voEmp, empLinkAttrs,
null);
This will set up a master-detail relationship between voDept and voEmp. Whenever voDept's currency moves, voEmp's result set will be refreshed to show employees that work in the department.
Using the Association Clause
This view link will generate a SQL clause like EMP.DEPTNO=?
on voEmp. The Deptno value of the current row in voDept
(master) is bound into the bind variable ('?'). This results in limiting
query on voEmp to employees whose Deptno equals the current Dept's
Deptno.
By supplying a non-null association clause (the last parameter),
the user can override the default SQL clause and replace it with his.
For example, if he wishes to include only employees whose JOB is ANALYST, he
can supply the following assocClause:
EMP.DEPTNO=? AND EMP.JOB='ANALYST'.
Using the Accessor Name
If the user supplies a non-null accessorName (the second parameter), a
dynamic attribute is added to master view object which allows
the user retrieve related rows from a master row.
In the above code example, a dynamic attribute "Employees" is added to voDept, such that if the user retrieve that attribute on a row the came from voDept, it will return a row set of Emp's that are related to that row.
The code example below retrieves all rows from voDept and for each Dept row, retrieves its employees by using the "Employees" attribute and prints their names.
Row deptRow;
while ((deptRow = voDept.next()) != null)
{
System.out.println("Dept: " + deptRow.getAttribute("Dname"));
RowSet emps = (RowSet) deptRow.getAttribute("Employees");
Row empRow;
while ((empRow = emps.next()) != null)
{
System.out.println(" Emp: " + empRow.getAttribute("Ename"));
}
}
vlName - the name to be assigned to the view link.
If null, a system generated
name is assigned.accessorName - the name to be given to the dynamic attribute
to be added to master view object.
Given a row from the master view object, the
user can retrieve the attribute of this
name to get a row set of related rows from
the detail view object. See the above discussions
for more info. If null, no dynamic
attribute is added.master - the view object that is to play the role of master.srcAttrs - an array of attributes from master view object to be
related to detail.detail - the view object that is to play the role of detail.destAttrs - an array of attributes from detail view object to be
related to master.assocClause - a custom association clause. See the above
discussions for more info. If null,
system generated SQL clause will be used.
InvalidObjNameException - (1) if vlName is an invalid name.
vlName must be a vaild Java name.
(2) if accessorName is an invalid name.
accessorName must be valid Java name.
NameClashException - (1) if a view link of vlName
already exists in this application module. The
view link name must be unique.
(2) if an attribute of accessorName
already exists in the master view object. The
accessor (attribute) name must be unique.
InvalidParamException - (1) if master or detail is
null
(2) if master and detail
represent the same view object (circular view
link is disallowed)
InvalidOperException - if a recursive view link chain is found.
Suppose we have three view objects, VO_A, VO_B, VO_C.
Suppose we have view links that link VO_A to
VO_B, VO_B to VO_C, and VO_C back to VO_A. Then,
we have a recursive view link chain. This is
disallowed and reported as an error.createViewObject(String, String),
StructureDef.findAttributeDef(String),
RowIterator.next(),
AttributeList.getAttribute(String)ViewLink findViewLink(java.lang.String vlName)
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");
vlName - the name of the view link.
null if the view link
is not found.
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.findApplicationModule(String),
findViewObject(String)java.lang.String[] getViewLinkNames()
Example code:
String[] vlNames = am.getViewLinkNames();
// If you want to retrieve all currently loaded view links
ViewLink[] vls = new ViewLink[vlNames.length];
for (int i = 0; i < vlNames.length; i++)
{
vls[i] = am.findViewLink(vlNames[i]);
}
If you need names of view objects that are not yet loaded,
use getViewLinkNames(boolean, boolean)
findViewLink(String)
java.lang.String[] getViewLinkNames(boolean inclLoadedOnes,
boolean fromDef)
This method allows the user to control whether the returning names are those of loaded (instantiated) view links, or those of not yet loaded (uninstantiated) view links, or both. Not yet loaded view links would appear only if lazy loading is turned on.
Note that getViewLinkNames()getViewLinkNames(true, false).
If this method is called with loadedOnes = true and
fromDef = true, both loaded and not-yet-loaded
view link names are returned. No duplicate name is returned.
Note that loaded view links include dynamically created ones.
inclLoadedOnes - if true, loaded ones are
returned.fromDef - if true, names of the view links from the
application module definition are returned. Some of
these VLs could have already been loaded and some may
have not yet been loaded.
ComponentObject createComponentObject(java.lang.String coName,
java.lang.String coDefName)
defName parameter.
Example code:
ComponentObject vo = am.createComponentObject("MyCO", "package1.MyComponentDef");
A component object is a generic object that an application module
can contain. A Comonent object is any object that implements the
ComponentObject interface. In particular,
ViewObject and ViewLink implement
the ComponentObject interface.
Thus, this method enables the user to build a custom ComponentObject and have it be managed by application module. Specificially, he must first implement a Java class that implements ComponentObject.
Then, as is the case with view objects and view links, he must build a component object definition (an XML file) reachable from the class path. (Note that for view objects and view links, BC4J design time provides tools to produce these definition files. For custom component object, the user must provide a custom tool to produce definition files or provide finished definition files himself.)
coName - the name to be assigned to the component object.
If null, a system generated
name is assigned.coDefName - the name of the component object definition from which the new
component object is to be created. It must
be a fully qualified name (including the package name).
InvalidObjNameException - if coName is an invalid name.
coName must be a vaild Java name.
NameClashException - if a component object of coName
already exists in this application module. The
component object name must be unique.
NoDefException - if component object definition (named by the
defName parameter) was not found.
Make sure defName is fully qualified
with the package name.
PersistenceException - if some error was found while loading the
component object definition.ComponentObject findComponentObject(java.lang.String coName)
createComponentObject(String, String)
for explanation of BC4J's support for custom component objects.
See findViewObject(String) for explanation on AM-qualified
names and unqualified names.
coName - the name of the component object.
null if the component object
is not found.
NoObjException - if an AM-qualified name was specified and the
containing application module could not be found.
InvalidObjNameException - if coName is an invalid name.
coName must be a vaild Java name.findApplicationModule(String)boolean isRoot()
Transaction getTransaction()
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.
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.Session getSession()
If the user creates two root application modules, each has its own session.
Note that this is the same session
that is passed to the ApplicationModuleImpl.activate(Session) call.
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.ApplicationModuleImpl.activate(Session)java.lang.Object getSyncLock()
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.
}
void clearVOCaches(java.lang.String entityName,
boolean recurse)
entityName. This
method finds all view objects that use the entity, then calls
ViewObject.clearCache() on each view object.
If entityName is null, then the caches of all view objects in the application module are cleared. If recurse is true, it recurses into nested application modules.
entityName - fully qualified name of the entity object.
If null all view object caches
are cleared.recurse - a flag indicating whether to recurse into nested
application modules.
RowSetIterator findRSIForEntity(RowSetIterator[] rsis,
int eRowHandle)
RowSetIterator associated with the
specified entity row handle. This method is provided to handle
errors that occur during entity post cycle.
If an error occurs while an entity
is being posted to database, the system throws a
DMLException. Inside the DMLException
instance is an opaque handle (an integer) identifying the
entity (an instance of EntityImpl)
that caused the error.
For example, the DMLException could have been thrown because the row violated a database constraint. The client might want to give the user a chance to correct the problem by displaying the the view row that uses this entity.
To do this, the client would "gather" all row set iterators that can be used to report and fix the problem. It would then call this method, passing in the array of row set iterators and the entity row handle returned by DMLException.
Among the row set iterator in the array, findRSIForEntity will pick the "best" candidate and return it to the client. The client then can use the row set iterator to report the problem and give the user a chance to fix the problem.
rsis - an array of RowSetIterator's to look through.eRowHandle - the entity row handle.
RowSetIterator.DMLException,
RowSetIterator,
DMLException
RowSetIterator getListBindingRSI(RowSetIterator rsi,
Key rowKey,
java.lang.String attrName,
java.lang.String lbName)
RowSetIterator getPreferredListRSI(RowSetIterator rsi,
Key rowKey,
java.lang.String attrName,
java.lang.String lbName)
java.lang.String getListBindingName(RowSetIterator rsi,
Key rowKey,
java.lang.String attrName,
java.lang.String lbName)
ViewObject findViewObjectUsingEntity(ViewObject[] vos,
java.lang.String entityName,
java.lang.String[] attrName)
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.
NoDefException - if the entity could not be found.
PersistenceException - if some error was found while loading the
entity definition.
ViewObject findViewObjectWithParameters(java.lang.String voname,
VariableManager params,
boolean executeIfNeeded)
RowSet executeQueryOnViewObjects(java.lang.String sqlStmt)
java.lang.Object[] transformExceptionParams(ViewObject[] vos,
java.lang.String entityName,
java.lang.String exceptionClassName,
java.lang.Object[] params)
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 mappedparams - Parameters from the Exception that is to be transformed into view object
equivalents.
NoDefException - if the entity could not be found.
PersistenceException - if some error was found while loading the
entity definition.JboExceptionHandler getExceptionHandler()
void setExceptionHandler(JboExceptionHandler hndlr)
JboExceptionHandler
interface.
JboExceptionHandler handle exceptions (java.lang.Exception)
and warnings (JboWarning). In 2 tier mode,
the handler will only see warnings but no exception. In 2 tier mode,
Exceptions are thrown through the normal Java throw mechanism.
They should be handled through catch blocks.
For warnings, no throw/catch mechanism is available. The
handler must process them.
In 3 tier mode, the handler may have to process exceptions in addition to warnings. When a method call is marshalled from the client tier into the middle tier, the middle tier processing of the method may result in more than one exceptions. All these exceptions are caught by the marshalling code and brought back to the client tier. As Java's throw mechanism allows throwing of only one exception, these multiple exceptions cannot be processed through Java throw. Thus, for each of these exceptions, a call is made to handler's handleException(), so that the handler can process it.
hndlr - an exception handler.void addWarning(JboWarning warn)
Adds a warning message. In 2 tier mode, the warning is passed
to this method is sent to the exception handler immediately
if an exception handler is present (exception handler is
specified through a call to setExceptionHandler(JboExceptionHandler)).
This is done through a call to
JboExceptionHandler.handleWarning(JboWarning).
In 3 tier mode, the warnings that came to this application module
through calls to addWarning() in the middle tier are "chained"
until the middle tier processing completes. They are brought to
the client at the end of middle tier processing, and, for each
warning, a call is made to
JboExceptionHandler.handleWarning(JboWarning)
if an exception handler is present.
addWarning in interface WarningContainerwarn - warning message.ClientDocument getStyles(java.lang.String name)
This method retrieves the content of an XML document specified by name and returns it as a ClientDocument. It locates the XML file through the following logic:
ClientDocument enables the user to manipulate an arbitrary
tree of an XML style document. Thus, the user can retrieve a
ClientDocument using this method and modify parts of the
tree and write it back out using setStyles(String, ClientDocument).
name - the XML file name.
ClientDocument.ClientDocument
void setStyles(java.lang.String name,
ClientDocument clientDocument)
This method saves the content of the document (the clientDocument parameter) in an XML file specified by name. It locates the XML file through the following logic:
ClientDocument enables the user to build an arbitrary tree of an XML style document. Thus, this method can be used to programmatically build and save an XML file.
name - the XML file name.clientDocument - the ClientDocument to be saved.ClientDocumentint reserveSnapshotId(int flags)
Reserves a unique indentifier which may later be specified when passivating AM state as the identifier to be used for re-establishing AM state.
If the PASSIVATE_TRANSIENT_FLAG has not been set then this method
will return a passivation id from one of the persistent Serializers (File
and Database). This method will then reserve a stack snapshot id for
that persistent snapshot. The reserved stack id may be acquired by
invoking getMostRecentStackId().
If the PASSIVATE_TRANSIENT_FLAG has been set then this method will return a stack id. The stack id is unique for a session transaction only. This may need to be extended to provide a UUID so that applications do not inadvertantly try to undo state across transaction boundaries.
This method may be invoked to obtain a unique snapshot identifier before a snapshot is actually acquired. An example use case is an HTTP servlet that must encode all URLs with the snapshot id before the snapshot is acquired.
flags - a bit map defining passivation flags.
passivateState(int, byte[], int).int reservePassivationId()
reserveSnapshotId(int) with the PERSISTNENT_SNAPSHOT bit set
instead.
int passivateState(int id,
byte[] clientData,
int flags)
Serializes the current state of this application module's session, along with all changes cached, to a byte array and returns a unique identifier with which to re-establish the state.
This method accepts an id which represents the unique identifier that
should be used to re-establish the application module state. The id
must have been generated by invoking reserveSnapshotId(int).
The same snapshot type bit which was specified when the snapshot id was reserved should be specified when this method is invoked. For example, if reserveSnapshotId was invoked with the PASSIVATE_TRANSIENT_FLAG set then this method should be invoked with the PASSIVATE_TRANSIENT_FLAG set. Failing to do so may result in invalid snapshot id exceptions.
For more information regarding passivation please see
passivateState(byte[], int).
id - a reserved passivation idclientData - cached changes, or any information that a client might
want to store.flags - a bit map defining passivation flags.
reservePassivationId()
int passivateState(int id,
byte[] clientData)
passivateState(int, byte[], int) with the PASSIVATE_TRANSIENT_FLAG
not set instead.
int passivateState(byte[] clientData,
int flags)
Creates a snapshot of the current state of this application module's session. If the PASSIVATE_TRANSIENT_FLAG is not set then the snapshot bytes will be serialized to a persistent store (database or file). If the PASSIVATE_TRANSIENT_FLAG bit is set then the snapshot bytes will be pushed to the application module snapshot stack. The method will then return a unique identifier which may be used to activate the state. Please note that the same snapshot type bit should be used to activate the state as was used to passivate the state. Failing to do so could result in the snapshot record not being located.
This method always works from the top-level application module. If you have nested application modules and you call this method on a inner application module, it will still work from the top-level module.
In contrast to activateState(int, SessionData, int), which deserializes
a session-state from the persistent store, calling
passivateState, does not affect the transaction state.
The cached changes, or clientData, can be any information that a client might want to store. For example, a JSP client could store the additional client-state information in this byte array so that when the JSP client becomes active and connects to an application module later, it could get its passivated state from the application module. This would reduce the amount of state information stored at the client side to a bare minimum (typically just an application module persistence ID).
A value of null for clientData indicates that the state will be stored, but there is no client data to be preserved.
This method preserves currency. When activateState(int, SessionData, int) is
called, the active row is returned.
For example, the following code snippet inserts a new row in a view object, then calls passivateState to save the application module state. The transaction is rolled back and activateState is called. The value of getCurrentRow called before the passivateState should match the the value of getCurrentRow called after activateState.
// create a view object "depts"
ViewObject depts = appModule.createViewObject("myDeptView", "myDeptViewDef");
// insert a new row into depts
Row r = depts.createRow();
r.setAttribute("DeptNum","56");
depts.insertRow(r);
Row afterInsert = depts.getCurrentRow();
// Passivate the application module state
int id = appModule.passivateState(null);
// rollback the transaction
appModule.getTransaction.rollback();
// move the cursor to the last row -- just to make it interesting
depts.last();
// now activate the application module state
// currency should be on the new row inserted.
appModule.activateState(id, SessionData, int);
Row afterActivate = depts.getCurrentRow();
The values afterInsert and afterActivate should be the same.
clientData - cached changes, or any information that a client might
want to store.flags - a bit map defining passivation flags.
int passivateState(byte[] clientData)
passivateState(byte[]) with the PERSISTNENT_SNAPSHOT bit set
instead.
byte[] activateState(int id,
SessionData info,
int flags)
Deserializes a session-state from the persistent store based on the given id. This method always works from the top-level application module. If you have nested application modules and you call this method on a inner application module, it will still work from the top-level module.
When the PERSISTENT_SNAPSHOT bit is set then this method will attempt to locate the snapshot bytes in a persistent store (database or file). If the PERSISTENT_SNAPSHOT bit is not set then this method will locate the snapshot bytes on the stack.
When this method is called, the rows that are updated are locked; new rows
are inserted into the transaction cache and posted. This is in contrast
to passivateState(byte[], int), which does not affect the
transaction state.
The activateState method preserves currency. When it is
called, it will return the row that was active when
passivateState(byte[], int) was called.
For an example usage of activateState, see
passivateState(byte[], int).
If the REMOVE_SNAPSHOT bit is set in the flags then the activation framework will remove the snapshot from the persistent store after activation.
It is up to the developer to devise a clean-up strategy for the redundant store.
id - a unique integer identifier associated with an instance of the
application module.
passivateState(byte[], int) method.
byte[] activateState(int id,
boolean remove)
activateState(int, SessionData, int) with the
PERSISTNENT_SNAPSHOT bit set and a null SessionData instead.
byte[] activateState(int id,
boolean remove,
SessionData info)
activateState(int, SessionData, int) with the
PERSISTNENT_SNAPSHOT bit set instead.
int getMostRecentStackId()
Acquire the snapshot id of the most recent stack snapshot. This method may be used by clients to acquire the stack snapshot id of a persistent snapshot.
Please see passivateState(byte[]) for more information
regarding stack passivation.
void prepareSession(SessionData info)
void resetState(int flags)
Applications should override/extend ApplicationModuleImpl.reset()
to reset custom application module state. reset() is invoked by the
internal resetState before resetState begins cleaning up
internal application module state.
Flag usage:
RESET_RELOAD_FLAG directs resetState to eagerly reload the application module compoonents.
RESET_ROLLBACK_FLAG directs resetState to rollback the application module.
RESET_INTERNAL_FLAG directs resetState to perform an internal reset only. The ApplicationPool uses this to reset a managed state application module while also managing the previous session's state. For example, when RESET_INTERNAL has been specified the reset will not remove the persistent snapshot records on the snapshot stack.
Resets the non-transaction state of an application module. For example:
appModule.resetState(false);
void resetState(boolean reload)
resetState(int) with
the RESET_RELOAD_FLAG enabled instead.
void removeState(int id)
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);
id - an unique integer identifier associated with an instance of the
application module.void setStoreForPassiveState(byte storageType)
Determines where the application module will store serialized versions of its session-state, plus any cached changes. This information can be stored to the database, to a file, or to memory, based on the value of the storageType parameter. The storageType can be set to:
PASSIVATE_TO_DATABASE (default target)PASSIVATE_TO_FILEPASSIVATE_TO_MEMORY
This method should be called before calling passivateState(byte[]).
Note that once an application module has serialized
its state, it cannot be asked to change its store. This method will throw
an JboException if this application module has already
stored its state earlier.
For example, the following code will set the storage to database, file, or memory, based on the value of the str parameter. Database is the default target:
String str =
oracle.jbo.common.JboEnvUtil.getProperty("jbo.test.passivateStateTo");
if (str != null)
{
if (str.equals("file"))
{
appModule.setStoreForPassiveState(ApplicationModule.PASSIVATE_TO_FILE);
}
else
if (str.equals("memory"))
{
appModule.setStoreForPassiveState(ApplicationModule.PASSIVATE_TO_MEMORY);
}
storageType - where the application module state is stored. Can be one
of PASSIVATE_TO_DATABASE (default target),
PASSIVATE_TO_FILE, or PASSIVATE_TO_MEMORY.
JboException - if this application module has already
stored its state earlier.passivateState(byte[])
void fetchAttributeProperties(java.lang.String[] voNames,
java.lang.String[][] voAttrNames,
LocaleContext locale)
For clients like JClient applications, this method helps in downloading all the attribute properties over to the client side in one roundtrip so that startup of these applications are more performant. Calls to properties methods like getFormat(), getLabel(), etc. on the Attribute definition then, does not go over the network boundary for the attributes that are included in the parameter list.
voNames - An array of view object names in this application modulevoAttrNames - For each view object name, a list of attribute names for which
the custom properties need to be brought over to the client side.
void prepareViewObjects(java.lang.String[] voNames,
java.lang.String[][] voAttrNames,
LocaleContext locale)
voNames - An array of view object names in this application modulevoAttrNames - For each view object name, a list of attribute names for which
the custom properties need to be brought over to the client side.
java.lang.String passivateStateForUndo(java.lang.String id,
byte[] clientData,
int flags)
application module state that is passivated using this method will have transaction scope only -- the passivated state will be removed when a transaction commit/rollback occurs.
application module state snapshots that are created using this method will be pushed to an LIFO stack. This stack is defined as part of the application module transaction state and as such will be maintained by application module passivation/activation.
The application developer may specify their own snapshot id by passing an id in for the request. If no id has been specified then an id will be generated by the system and returned. If a snapshot already exists for this transaction with the specified id then the old snapshot will be removed from the snapshot stack.
The application developer may control whether a persistent snapshot
(on-disk) or a transient snapshot (in-memory) is taken with the
BC4J session property, PropertyConstants.ENV_SNAPSHOT_STORE_UNDO.
A value of PropertyConstants.SNAPSHOT_STORE_PERSISTENT
(default) directs the algorithm to create a persistent snapshot (on-disk)
for this undo request. The location of the persistent snapshot
may further be controlled by the BC4J propery PropertyConstants.ENV_PASSIVATION_STORE
which accepts values of {file,database}.
A value of PropertyConstants.SNAPSHOT_STORE_TRANSIENT
directs the algorithm to create a transient snapshot (in-memory).
Transient snapshots are not guaranteed to be maintained in the event of
system failure.
Setting the flags parameter value to PASSIVATE_DEFER_FLAG
allows the snapshot creation to be deferred until the application module
is checked in. For typical web-based applications, this means that the
snapshot would be created at the end of the request when the application
module checkin is invoked.
Most applications using the application module pool are highly encouraged to use this flag value for performance and memory usage optimization. Deferring the snapshot creation allows one snapshot to be used for both transaction undo and failover support.
Deferred passivation should not be requested if it is necessary to capture the application module state at the time of the undo request -- a deferred undo request does not guarantee that the passivated state equals the application module state at the time of the undo request.
id - the id which is to be used to identify this undo record.
The id should be unique within a transaction. If an id is not
specified then an id will be generated by the system and returned.clientData - a byte array representing any clientData which the
invoker wishes to associate with the undo record.flags - an int representing passivateStateForUndo flags. Valid
flags are:
ApplicationModule.PASSIVATE_DEFER_FLAG see the discussion above for more information regarding the use of this flag.
In order to specify default behaviour the application developer may pass 0 for the flags parameter. Default behaviour is defined as immediate passivation.
byte[] activateStateForUndo(java.lang.String id,
int flags)
Activates an application module state which was created using
passivateStateForUndo(String, byte[], int).
If the id is not on the undo stack then an exception will be thrown indicating that it is an invalid undo id.
Invoking this method will remove all those undo records that are above (more recent) than the specified undo record.
id - the id of an undo record that was created using passivateStateForUndo(String, byte[], int)flags - Valid flags are:
N/A -- The flags are currently unused. Please pass 0.
boolean isValidIdForUndo(java.lang.String id)
passivateStateForUndo(String, byte[], int)
is still valid.
An id may become invalid if a transaction boundary (commit/rollback) has occured since the id was created.
id - the id of an undo record that was created using passivateStateForUndo(String id, byte[] clientData, int flags)ApplicationPoolSvcMsgContext doPoolMessage(ApplicationPoolSvcMsgContext ctx)
int getReleaseLevel()
For example, the ADF/BC DataControl will invoke getReleaseLevel() to determine if this application module may be released to the ApplicationPool in SHARED_MANAGED_RELEASE_MODE or if the application module may be released in RESERVED_UNMANAGED_RELEASE_MODE.
Two release levels are currently supported:
RELEASE_LEVEL_MANAGED Default. Indicates that the application module is in a state that may be managed by BC4J state management service.
For more information about the BC4J state management service please see the passivation documentation.
RELEASE_LEVEL_RESERVED Indicates that the application module may not be managed by the BC4J state management service. Application modules may specify this release level if they reference session/txn state that may not be recreated by passivation/activation.
Common examples of state that is not currently managed by the state management service are posted database changes and database locks. Other custom examples may exist.
Care should be taken that the default RELEASE_LEVEL_MANAGED level is used for most releases. Using a RELEASE_LEVEL_RESERVED level throughout an application could result in scalability issues as application modules accumulate with the accumulation of new sessions.
If both flags have been specified then RELEASE_LEVEL_RESERVED will take precedence.
void setReleaseLevel(int releaseLevel)
getReleaseLevel()
ViewDef createCompositeViewDef(java.lang.String name,
java.lang.String fullName)
void processChangeNotifications()
|
Oracle Fusion Middleware Java API Reference for Oracle ADF Model 11g Release 1 (11.1.1.4.0) E10653-05 |
||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||