|
Oracle Fusion Middleware Java API Reference for Oracle ADF Model 11g Release 1 (11.1.1) E10653-03 |
||||||||
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. |
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.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
insteadstatic 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
is equivalent to 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_IMMEDIATE
int 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
is equivalent to 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
is equivalent to 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 WarningContainer
warn
- 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.ClientDocument
int 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_FILE
PASSIVATE_TO_MEMORY
This method should be called before calling passivateState(byte[])
. Note that once an application module has serialized its state, it cannot be asked to change its store. This method will throw an JboException
if this application module has already stored its state earlier.
For example, the following code will set the storage to database, file, or memory, based on the value of the str parameter. Database is the default target:
String str = oracle.jbo.common.JboEnvUtil.getProperty("jbo.test.passivateStateTo"); if (str != null) { if (str.equals("file")) { appModule.setStoreForPassiveState(ApplicationModule.PASSIVATE_TO_FILE); } else if (str.equals("memory")) { appModule.setStoreForPassiveState(ApplicationModule.PASSIVATE_TO_MEMORY); }
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) E10653-03 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |