|
Oracle ADF Model and Business Components API Reference 10.1.2 B14022-01 | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object java.util.AbstractMap oracle.jbo.common.JboAbstractMap oracle.jbo.common.ws.WSObject oracle.jbo.common.ws.WSApplicationModuleImpl
Nested Class Summary |
Nested classes inherited from class java.util.Map |
java.util.Map.Entry |
Field Summary | |
static int |
BATCH_ALLOW_CACHE
|
static int |
BATCH_ALLOW_INFO
|
static int |
BATCH_ALLOW_MASTER_DETL
|
static int |
BATCH_ALLOW_PASSIVATION
|
static int |
BATCH_ALLOW_RANGE
|
static int |
BATCH_ALLOW_RANGE_SET
|
static int |
BATCH_ALLOW_STRUCT
|
static int |
BATCH_ALLOW_XML
|
static int |
BATCH_ALLOW_XTN
|
static int |
BATCH_DEFAULT
|
static java.lang.String |
END_REQUEST_RELEASE_LEVEL
|
Fields inherited from interface oracle.jbo.Session |
JBO_SESSION_COOKIE, JBO_SESSION_LOCALE |
Constructor Summary | |
|
WSApplicationModuleImpl(ApplicationModule am)
|
|
WSApplicationModuleImpl(SessionCookie sessionCookie)
|
protected |
WSApplicationModuleImpl(java.lang.String name,
java.lang.String defName,
WSApplicationModuleImpl parent)
|
protected |
WSApplicationModuleImpl(java.lang.String name,
WSApplicationModuleImpl parent)
|
Method Summary | |
byte[] |
activateState(int id,
boolean remove)
|
byte[] |
activateState(int id,
boolean remove,
SessionData info)
|
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 ApplicationModule undo record. |
protected void |
addChild(java.lang.Object child)
|
void |
addChildAM(WSApplicationModuleImpl childAM)
|
void |
addResponse(java.io.Serializable resp)
|
void |
addWarning(JboWarning warn)
Adds a warning message. |
void |
beginRequest(java.util.HashMap ctx)
|
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. |
Request |
createRequest()
|
ServiceMessage |
createSyncMessage()
|
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 Object 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 an 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. |
void |
detach()
|
void |
doFinish(boolean isEndOfSvcMsg)
|
void |
doInit()
|
ApplicationPoolSvcMsgContext |
doPoolMessage(ApplicationPoolSvcMsgContext ctx)
Internal use only. |
void |
doWork()
|
void |
endRequest(java.util.HashMap ctx)
|
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 ViewObjects 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. |
ViewObject |
findCustomViewObject(java.lang.String voName,
java.lang.String voType)
|
ViewObject |
findCustomViewObject(WSViewObjectImpl wsvo,
java.lang.String voType)
|
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[] attrNames)
Given an array of View Objects (the vos parameter), finds the first matching View Object. |
WSApplicationModuleImpl |
findWSApplicationModule(java.lang.String amName)
|
WSComponentObjectImpl |
findWSComponentObject(java.lang.String coName)
|
WSViewLinkImpl |
findWSViewLink(java.lang.String vlName)
|
WSViewObjectImpl |
findWSViewObject(java.lang.String voName)
|
java.lang.Object |
get(java.lang.Object keyObj)
|
java.lang.String[] |
getAllApplicationModuleDefNames()
Gets the names of the Application Module definitions contained in all packages. |
java.lang.String[] |
getAllEntityAssociationDefNames()
Gets the names of the entity association definitions defined in all packages. |
java.lang.String[] |
getAllEntityDefNames()
Gets the names of the Entity Object definitions available in all packages. |
java.util.ArrayList |
getAllRowSetIterators()
|
java.lang.String[] |
getAllViewDefNames()
Gets the names of the View Object definitions available in all packages. |
java.lang.String[] |
getAllViewLinkDefNames()
Gets the names of the View Link definitions defined in all packages. |
java.lang.String |
getAMFullName()
|
java.lang.String[] |
getApplicationModuleDefNames(java.lang.String packageName)
Gets the names of the Application Module definitions contained in a package. |
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 inclNotLoadedOnes)
Returns an array of names of the nested Application Modules in this Application Module. |
int |
getBatchCommMode()
|
ApplicationModule |
getCustomApplicationModule()
|
java.lang.String |
getDefFullName()
Retrieves the fully-qualified name of the component's definition. |
java.lang.String |
getDefName()
Retrieves the name of the component's definition. |
java.lang.String[] |
getEntityAssociationDefNames(java.lang.String packageName)
Gets the names of the entity association definitions defined in a package. |
java.lang.String[] |
getEntityDefNames(java.lang.String packageName)
Gets the names of the Entity Object definitions available in a package. |
java.util.Hashtable |
getEnvironment()
Returns the BC4J context for the session. |
JboExceptionHandler |
getExceptionHandler()
|
java.lang.String |
getFullName()
Retrieves the fully-qualified name of this component. |
java.lang.Object |
getImplObject()
|
java.util.Locale |
getLocale()
Gets the current Locale used for localizing error messages. |
LocaleContext |
getLocaleContext()
retrieves the locale context for the session |
int |
getMostRecentStackId()
Internal: Applications should not use this method. |
java.lang.String |
getName()
Retrieves the name of this component. |
ObjectMarshaller |
getObjectMarshaller()
|
java.util.HashMap |
getObjects()
|
java.lang.String[] |
getPackageNames()
Gets names of the packages that make up this middle tier application. |
WSObject |
getParent()
|
java.util.Hashtable |
getProperties()
Gets the table of properties. |
java.lang.Object |
getProperty(java.lang.String hintName)
Retrieves the specified property, if it exists. |
int |
getReleaseLevel()
Returns the release level that should be employed by clients of this ApplicationModule. |
int |
getRemoteObjectId(java.lang.Object obj)
|
java.lang.String |
getResponseName()
|
WSApplicationModuleImpl |
getRootWSApplicationModule()
|
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.util.Hashtable |
getUserData()
Returns application context for the session. |
java.lang.String[] |
getUserRoles()
Returns the Roles/Groups for current user principal. |
java.lang.String |
getVersion()
Gets the middle tier's version information. |
java.lang.String[] |
getViewDefNames(java.lang.String packageName)
Gets the names of the View Object definitions available in a package. |
java.lang.String[] |
getViewLinkDefNames(java.lang.String packageName)
Gets the names of the View Link definitions defined in a package. |
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 inclNotLoadedOnes)
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 inclNotLoadedOnes)
Returns an array of names of the View Objects in this Application Module. |
WSApplicationModuleMarshaller |
getWSApplicationModuleMarshaller()
|
java.lang.String[] |
getWSApplicationModuleNames()
|
java.lang.String[] |
getWSViewLinkNames()
|
java.lang.String[] |
getWSViewObjectNames()
|
java.lang.Object |
invokeExportedMethod(java.lang.String methodName,
java.lang.String[] argTypes,
java.lang.Object[] args)
|
boolean |
isClient()
Returns whether this session is running as a client in 3 tier or not. |
static boolean |
isEmpty(java.lang.String s)
|
boolean |
isOnLine()
|
boolean |
isRoot()
Returns true if this Application Module is a root Application Module. |
boolean |
isSyncIteratorState()
|
boolean |
isSyncNeeded()
|
boolean |
isUserInRole(java.lang.String role)
|
boolean |
isValidIdForUndo(java.lang.String id)
Determines if an id created using passivateStateForUndo(String, byte[], int)
is still valid. |
void |
loadPackage(java.lang.String packageName)
Loads a package that may be browsed for defined objects. |
void |
markForError(java.lang.Exception ex,
boolean hasImplObject)
|
java.lang.Object |
marshal(java.lang.Object obj)
|
int |
passivateState(byte[] clientData)
|
int |
passivateState(byte[] clientData,
int flags)
Internal: Applications should not use this method. |
int |
passivateState(int id,
byte[] clientData)
Internal: Applications should not user this method. |
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 ApplicationModule undo record. |
void |
prepareResetState()
|
void |
prepareSession(SessionData info)
Internal: Applications should not use this method. |
java.lang.Object |
refreshProperty(java.lang.String hintName)
Retrieves the specified property, if it exists. |
void |
registerObjFromActivation(java.lang.Object obj)
|
void |
remove()
Deletes this component. |
void |
removeState(int id)
Internal: Applications should not use this method. |
int |
reservePassivationId()
Internal: Applications should not user this method. |
int |
reserveSnapshotId(int flags)
Internal: Applications should not use this method. |
void |
resetState(boolean reload)
|
void |
resetState(int flags)
Internal: Applications should not use this method. |
void |
resolve(ApplicationModule am)
Resolves the "impl" pointers |
ServiceMessage |
sendRequests(java.lang.String reqName,
ServiceMessage msg)
|
void |
setBatchCommMode(int mode)
|
void |
setDataModelRefresh(boolean b)
|
void |
setExceptionHandler(JboExceptionHandler hndlr)
Sets the exception handler for this Application Module. |
void |
setImplObject(java.lang.Object o)
|
void |
setIsSyncNeeded(boolean b)
|
void |
setLocale(java.util.Locale locale)
Sets a new Locale for localizing error messages. |
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 |
setSyncIteratorState(boolean b)
|
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. |
void |
syncIfNeeded()
|
java.lang.Object[] |
transformExceptionParams(ViewObject[] vos,
java.lang.String entityDefName,
java.lang.String className,
java.lang.Object[] params)
Internal: Applications should not use this method. This method uses findViewObjectUsingEntity() to get the first ViewObject that this entity is used in and then transforms the parameters from a given JboException from their Entity layer equivalents to the ViewObject equivalents. |
Methods inherited from class oracle.jbo.common.ws.WSObject |
getId |
Methods inherited from class oracle.jbo.common.JboAbstractMap |
entrySet, equals, hashCode, internalGet |
Methods inherited from class java.util.AbstractMap |
clear, clone, containsKey, containsValue, isEmpty, keySet, put, putAll, remove, size, toString, values |
Methods inherited from class java.lang.Object |
finalize, getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
public static final int BATCH_ALLOW_XTN
public static final int BATCH_ALLOW_RANGE_SET
public static final int BATCH_ALLOW_INFO
public static final int BATCH_ALLOW_CACHE
public static final int BATCH_ALLOW_PASSIVATION
public static final int BATCH_ALLOW_XML
public static final int BATCH_ALLOW_MASTER_DETL
public static final int BATCH_ALLOW_STRUCT
public static final int BATCH_ALLOW_RANGE
public static final int BATCH_DEFAULT
public static final java.lang.String END_REQUEST_RELEASE_LEVEL
Constructor Detail |
public WSApplicationModuleImpl(ApplicationModule am)
public WSApplicationModuleImpl(SessionCookie sessionCookie)
protected WSApplicationModuleImpl(java.lang.String name, WSApplicationModuleImpl parent)
protected WSApplicationModuleImpl(java.lang.String name, java.lang.String defName, WSApplicationModuleImpl parent)
Method Detail |
public boolean isOnLine()
public java.lang.String getResponseName()
public int getRemoteObjectId(java.lang.Object obj)
public java.lang.Object marshal(java.lang.Object obj)
public void setDataModelRefresh(boolean b)
public void addResponse(java.io.Serializable resp)
public ObjectMarshaller getObjectMarshaller()
public WSObject getParent()
getParent
in class WSObject
public java.util.HashMap getObjects()
public boolean isSyncIteratorState()
public void setSyncIteratorState(boolean b)
public java.lang.Object getImplObject()
getImplObject
in class WSObject
public void setImplObject(java.lang.Object o)
setImplObject
in class WSObject
public void markForError(java.lang.Exception ex, boolean hasImplObject)
markForError
in class WSObject
public void detach()
public java.lang.String getAMFullName()
public void registerObjFromActivation(java.lang.Object obj)
public void addChildAM(WSApplicationModuleImpl childAM)
protected void addChild(java.lang.Object child)
public void prepareResetState()
public void doInit()
public void doWork()
public void doFinish(boolean isEndOfSvcMsg)
public java.util.ArrayList getAllRowSetIterators()
public ApplicationModule createApplicationModule(java.lang.String amName, java.lang.String defName)
ApplicationModule
defName
parameter.
Example code:
ApplicationModule nestedAM = parentAM.createApplicationModule("MyAM", "package1.Package1Module");
createApplicationModule
in interface ApplicationModule
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 ApplicationModule.DEFAULT_DEF_FULL_NAME
or null
is passed,
a generic Application Module (one without custom
code or static Component Objects) is created.
public static boolean isEmpty(java.lang.String s)
public ApplicationModule findApplicationModule(java.lang.String amName)
ApplicationModule
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");
findApplicationModule
in interface ApplicationModule
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.public WSApplicationModuleImpl findWSApplicationModule(java.lang.String amName)
public java.lang.String[] getApplicationModuleNames()
ApplicationModule
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
.
#getApplicatonModuleNames(boolean, boolean)
getApplicationModuleNames
in interface ApplicationModule
ApplicationModule.findApplicationModule(String)
public java.lang.String[] getApplicationModuleNames(boolean inclLoadedOnes, boolean inclNotLoadedOnes)
ApplicationModule
This method allows the user to control whether the returning names are those of loaded (instantiated) nested Application Modules, or those of not yet loaded (uninstantiated) nested ApplicationModules, or both. Not yet loaded Application Modules would appear only if lazy loading is turned on.
Note that
is equivalent
to ApplicationModule.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.
getApplicationModuleNames
in interface ApplicationModule
inclNotLoadedOnes
- 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.
public java.lang.String[] getWSApplicationModuleNames()
public Request createRequest()
public ServiceMessage createSyncMessage()
public void setIsSyncNeeded(boolean b)
public boolean isSyncNeeded()
public void syncIfNeeded()
public void sync()
ApplicationModule
ApplicationModule.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.
sync
in interface ApplicationModule
public ServiceMessage sendRequests(java.lang.String reqName, ServiceMessage msg)
public void setBatchCommMode(int mode)
public int getBatchCommMode()
public void setSyncMode(int mode)
ApplicationModule
ApplicationModule.SYNC_LAZY
and ApplicationModule.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.
setSyncMode
in interface ApplicationModule
mode
- the new synchronization mode: SYNC_LAZY
or
SYNC_IMMEDIATE
.ApplicationModule.getSyncMode()
,
ApplicationModule.SYNC_LAZY
,
ApplicationModule.SYNC_IMMEDIATE
public int getSyncMode()
ApplicationModule
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
in interface ApplicationModule
ApplicationModule.setSyncMode(int mode)
,
ApplicationModule.SYNC_LAZY
,
ApplicationModule.SYNC_IMMEDIATE
public ViewObject createViewObject(java.lang.String voName, java.lang.String defName)
ApplicationModule
defName
parameter.
Example code:
ViewObject vo = am.createViewObject("MyVO", "package1.DeptView");
createViewObject
in interface ApplicationModule
voName
- the name to be assigned to the View Object.
If null
, a system generated
name is assigned.defName
- the name of the View Object definition from which the new
View Object is to be created. It must
be a fully qualified name (including the package name).
public 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)
ApplicationModule
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 Object definition from the Entity Object and sets the select, from, where, and order-by clauses of the View Definition. Then, it uses that View Object definition to create the View Object.
createViewObjectFromQueryClauses
in interface ApplicationModule
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 must 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.fromClause
- a SQL statement FROM clause.whereClause
- a SQL statement WHERE clause. If null
no where clause is established, 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.
public ViewObject createViewObjectFromQueryStmt(java.lang.String voName, java.lang.String sqlStatement)
ApplicationModule
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 Object definition with no Entity Object base and maps database columns to attribute definitions. Then, it uses that View Object definition to create the View Object.
createViewObjectFromQueryStmt
in interface ApplicationModule
sqlStatement
- the SQL query statement for the View Object.
public ViewObject findViewObject(java.lang.String voName)
ApplicationModule
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
ApplicationModule.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");
findViewObject
in interface ApplicationModule
voName
- the name of the View Object.
null
if the View Object
is not found.ApplicationModule.findApplicationModule(String)
,
ApplicationModule.findViewLink(String)
public WSViewObjectImpl findWSViewObject(java.lang.String voName)
public java.lang.String[] getViewObjectNames()
ApplicationModule
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
.
ApplicationModule.getViewObjectNames(boolean, boolean)
getViewObjectNames
in interface ApplicationModule
ApplicationModule.findViewObject(String)
public java.lang.String[] getViewObjectNames(boolean inclLoadedOnes, boolean inclNotLoadedOnes)
ApplicationModule
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 ApplicationModule.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.
getViewObjectNames
in interface ApplicationModule
inclNotLoadedOnes
- 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.
public java.lang.String[] getWSViewObjectNames()
public ViewLink createViewLink(java.lang.String vlName, java.lang.String defName, ViewObject master, ViewObject detail)
ApplicationModule
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.
createViewLink
in interface ApplicationModule
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.
ApplicationModule.createViewObject(String, String)
public ViewLink createViewLinkFromEntityAssocName(java.lang.String vlName, java.lang.String entityAssocName, ViewObject master, ViewObject detail)
ApplicationModule
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 (
The primary difference between
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.
ApplicationModule.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.
createViewLinkFromEntityAssocName
in interface ApplicationModule
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.
ApplicationModule.createViewObject(String, String)
public ViewLink createViewLinkBetweenViewObjects(java.lang.String vlName, java.lang.String accessorName, ViewObject master, AttributeDef[] srcAttrs, ViewObject detail, AttributeDef[] destAttrs, java.lang.String assocClause)
ApplicationModule
For example, suppose we have two Views 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")); } }
createViewLinkBetweenViewObjects
in interface ApplicationModule
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.
ApplicationModule.createViewObject(String, String)
,
StructureDef.findAttributeDef(String)
,
RowIterator.next()
,
AttributeList.getAttribute(String)
public ViewLink findViewLink(java.lang.String vlName)
ApplicationModule
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
ApplicationModule.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");
findViewLink
in interface ApplicationModule
vlName
- the name of the View Link.
null
if the View Link
is not found.ApplicationModule.findApplicationModule(String)
,
ApplicationModule.findViewObject(String)
public WSViewLinkImpl findWSViewLink(java.lang.String vlName)
public java.lang.String[] getViewLinkNames()
ApplicationModule
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
.
ApplicationModule.getViewLinkNames(boolean, boolean)
getViewLinkNames
in interface ApplicationModule
ApplicationModule.findViewLink(String)
public java.lang.String[] getViewLinkNames(boolean inclLoadedOnes, boolean inclNotLoadedOnes)
ApplicationModule
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 ApplicationModule.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.
getViewLinkNames
in interface ApplicationModule
inclNotLoadedOnes
- 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.
public java.lang.String[] getWSViewLinkNames()
public ComponentObject createComponentObject(java.lang.String coName, java.lang.String coDefName)
ApplicationModule
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.)
createComponentObject
in interface ApplicationModule
coName
- the name to be assigned to the Component Object.
If null
, a system generated
name is assigned.
public ComponentObject findComponentObject(java.lang.String coName)
ApplicationModule
ApplicationModule.createComponentObject(String, String)
for explanation of BC4J's support for custom Component Objects.
See ApplicationModule.findViewObject(String)
for explanation on AM-qualified
names and unqualified names.
findComponentObject
in interface ApplicationModule
coName
- the name of the Component Object.
null
if the Component Object
is not found.ApplicationModule.findApplicationModule(String)
public WSComponentObjectImpl findWSComponentObject(java.lang.String coName)
public boolean isRoot()
ApplicationModule
isRoot
in interface ApplicationModule
public WSApplicationModuleImpl getRootWSApplicationModule()
public Transaction getTransaction()
ApplicationModule
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.
getTransaction
in interface ApplicationModule
public Session getSession()
ApplicationModule
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.
getSession
in interface ApplicationModule
ApplicationModuleImpl.activate(Session)
public java.lang.Object getSyncLock()
ApplicationModule
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. }
getSyncLock
in interface ApplicationModule
public void clearVOCaches(java.lang.String entityName, boolean recurse)
ApplicationModule
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.
clearVOCaches
in interface ApplicationModule
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.public RowSetIterator findRSIForEntity(RowSetIterator[] rsis, int eRowHandle)
ApplicationModule
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.
findRSIForEntity
in interface ApplicationModule
rsis
- an array of RowSetIterator
's to look through.eRowHandle
- the Entity row handle.
RowSetIterator
.DMLException
,
RowSetIterator
,
DMLException
public ViewObject findViewObjectUsingEntity(ViewObject[] vos, java.lang.String entityName, java.lang.String[] attrNames)
ApplicationModule
findViewObjectUsingEntity
in interface ApplicationModule
vos
- an array of possible View Objects.entityName
- fully qualified name of the Entity object.
Should not be null
.attrNames
- if empty, i.e., null
or an array
of length 0, then the attribute matching
rule will be skipped (see the above discussion).
If not empty, it should have only one element
and that element should be the name of an
attribute of the Entity. The attribute matching
rule will apply. If a matching View Object is found,
attrName[0] upon return should have the name
of a View Object mapped to the Entity attribute.public java.lang.Object[] transformExceptionParams(ViewObject[] vos, java.lang.String entityDefName, java.lang.String className, java.lang.Object[] params)
ApplicationModule
transformExceptionParams
in interface ApplicationModule
vos
- an array of possible View Objects.entityDefName
- fully qualified name of the Entity object.
Should not be null
.className
- Qualified classname for the Exception which is being mappedparams
- Parameters from the Exception that is to be transformed into ViewObject
equivalents.public JboExceptionHandler getExceptionHandler()
getExceptionHandler
in interface ApplicationModule
public void setExceptionHandler(JboExceptionHandler hndlr)
ApplicationModule
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.
setExceptionHandler
in interface ApplicationModule
hndlr
- an exception handler.public void addWarning(JboWarning warn)
ApplicationModule
ApplicationModule.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 ApplicationModule
warn
- warning message.public ClientDocument getStyles(java.lang.String name)
ApplicationModule
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 ApplicationModule.setStyles(String, ClientDocument)
.
getStyles
in interface ApplicationModule
name
- the XML file name.
ClientDocument
.ClientDocument
public void setStyles(java.lang.String name, ClientDocument clientDocument)
ApplicationModule
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.
setStyles
in interface ApplicationModule
name
- the XML file name.clientDocument
- the ClientDocument
to be saved.ClientDocument
public int reserveSnapshotId(int flags)
ApplicationModule
Reserves a unique indentifier which may later be specified when passivating AM state as the identifier to be used for re-establishing AM state.
If the PASSIVATE_TRANSIENT_FLAG has not been set then this method
will return a passivation id from one of the persistent Serializers (File
and Database). This method will then reserve a stack snapshot id for
that persistent snapshot. The reserved stack id may be acquired by
invoking ApplicationModule.getMostRecentStackId()
.
If the PASSIVATE_TRANSIENT_FLAG has been set then this method will return a stack id. The stack id is unique for a session transaction only. This may need to be extended to provide a UUID so that applications do not inadvertantly try to undo state across transaction boundaries.
This method may be invoked to obtain a unique snapshot identifier before a snapshot is actually acquired. An example use case is an HTTP servlet that must encode all URLs with the snapshot id before the snapshot is acquired.
reserveSnapshotId
in interface ApplicationModule
flags
- a bit map defining passivation flags.
#passivateState(int, byte[], flags).
public int getMostRecentStackId()
ApplicationModule
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 #passivateToStack(byte[])
for more information
regarding stack passivation.
getMostRecentStackId
in interface ApplicationModule
public int reservePassivationId()
ApplicationModule
reservePassivationId
in interface ApplicationModule
public int passivateState(int id, byte[] clientData)
ApplicationModule
passivateState
in interface ApplicationModule
public int passivateState(byte[] clientData)
passivateState
in interface ApplicationModule
public int passivateState(int id, byte[] clientData, int flags)
ApplicationModule
Serializes the current state of this Application Module's session, along with all changes cached, to a byte array and returns a unique identifier with which to re-establish the state.
This method accepts an id which represents the unique identifier that
should be used to re-establish the application module state. The id
must have been generated by invoking ApplicationModule.reserveSnapshotId(int)
.
The same snapshot type bit which was specified when the snapshot id was reserved should be specified when this method is invoked. For example, if reserveSnapshotId was invoked with the PASSIVATE_TRANSIENT_FLAG set then this method should be invoked with the PASSIVATE_TRANSIENT_FLAG set. Failing to do so may result in invalid snapshot id exceptions.
For more information regarding passivation please see
ApplicationModule.passivateState(byte[], int)
.
passivateState
in interface ApplicationModule
id
- a reserved passivation idclientData
- cached changes, or any information that a client might
want to store.flags
- a bit map defining passivation flags.
oracle.jbo.server.ApplicationModule#reservePassivationId()
public int passivateState(byte[] clientData, int flags)
ApplicationModule
Creates a snapshot of the current state of thie ApplicationModule'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 ApplicationModule 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 ApplicationModule.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 ApplicationModule.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.
passivateState
in interface ApplicationModule
clientData
- cached changes, or any information that a client might
want to store.flags
- a bit map defining passivation flags.
public java.lang.String passivateStateForUndo(java.lang.String id, byte[] clientData, int flags)
ApplicationModule
ApplicationModule state that is passivated using this method will have transaction scope only -- the passivated state will be removed when a transaction commit/rollback occurs.
ApplicationModule state snapshots that are created using this method will be pushed to an LIFO stack. This stack is defined as part of the ApplicationModule transaction state and as such will be maintained by ApplicationModule 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 ApplicationModule.PASSIVATE_DEFER_FLAG
allows the snapshot creation to be deferred until the application module
is checked in. For typical web-based applications, this means that the
snapshot would be created at the end of the request when the application
module checkin is invoked.
Most applications using the application module pool are highly encouraged to use this flag value for performance and memory usage optimization. Deferring the snapshot creation allows one snapshot to be used for both transaction undo and failover support.
Deferred passivation should not be requested if it is necessary to capture the ApplicationModule state at the time of the undo request -- a deferred undo request does not guarantee that the passivated state equals the ApplicationModule state at the time of the undo request.
passivateStateForUndo
in interface ApplicationModule
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.
public byte[] activateState(int id, boolean remove, SessionData info)
activateState
in interface ApplicationModule
public byte[] activateState(int id, boolean remove)
activateState
in interface ApplicationModule
public byte[] activateState(int id, SessionData info, int flags)
ApplicationModule
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(/tt> bit is not set then this method will locate the snapshot bytes on the stack.
When this method is called, the rows that are updated are locked; new rows
are inserted into the transaction cache and posted. This is in contrast
to ApplicationModule.passivateState(byte[], int)
, which does not affect the
transaction state.
The activateState method preserves currency. When it is
called, it will return the row that was active when
ApplicationModule.passivateState(byte[], int)
was called.
For an example usage of activateState, see
ApplicationModule.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.
activateState
in interface ApplicationModule
id
- a unique integer identifier associated with an instance of the
Application Module.
ApplicationModule.passivateState(byte[], int)
method.public byte[] activateStateForUndo(java.lang.String id, int flags)
ApplicationModule
Activates an ApplicationModule state which was created using
ApplicationModule.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.
activateStateForUndo
in interface ApplicationModule
id
- the id of an undo record that was created using ApplicationModule.passivateStateForUndo(String, byte[], int)
public boolean isValidIdForUndo(java.lang.String id)
ApplicationModule
ApplicationModule.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.
isValidIdForUndo
in interface ApplicationModule
id
- the id of an undo record that was created using ApplicationModule.passivateStateForUndo(String id, byte[] clientData, int flags)
public ApplicationPoolSvcMsgContext doPoolMessage(ApplicationPoolSvcMsgContext ctx)
ApplicationModule
doPoolMessage
in interface ApplicationModule
public void prepareSession(SessionData info)
ApplicationModule
prepareSession
in interface ApplicationModule
public void resetState(boolean reload)
resetState
in interface ApplicationModule
public void resetState(int flags)
ApplicationModule
Applications should override/extend ApplicationModuleImpl.reset()
to reset custom ApplicationModule state. reset() is invoked by the
internal resetState before resetState begins cleaning up
internal ApplicationModuel state.
Flag usage:
RESET_RELOAD_FLAG directs resetState to eagerly reload the ApplicationModule compoonents.
RESET_ROLLBACK_FLAG directs resetState to rollback the ApplicationModule.
RESET_INTERNAL_FLAG directs resetState to perform an internal reset only. The ApplicationPool uses this to reset a managed state ApplicationModule 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);
resetState
in interface ApplicationModule
public void removeState(int id)
ApplicationModule
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);
removeState
in interface ApplicationModule
id
- an unique integer identifier associated with an instance of the
Application Module.public void setStoreForPassiveState(byte storageType)
ApplicationModule
Determines where the Application Module will store serialized versions of its session-state, plus any cached changes. This information can be stored to the database, to a file, or to memory, based on the value of the storageType parameter. The storageType can be set to:
ApplicationModule.PASSIVATE_TO_DATABASE
(default target)ApplicationModule.PASSIVATE_TO_FILE
ApplicationModule.PASSIVATE_TO_MEMORY
This method should be called before calling ApplicationModule.passivateState(byte[])
.
Note that once an Application Module has serialized
its state, it cannot be asked to change its store. This method will throw
an JboException
if this Application Module has already
stored its state earlier.
For example, the following code will set the storage to database, file, or memory, based on the value of the str parameter. Database is the default target:
String str = oracle.jbo.common.JboEnvUtil.getProperty("jbo.test.passivateStateTo"); if (str != null) { if (str.equals("file")) { appModule.setStoreForPassiveState(ApplicationModule.PASSIVATE_TO_FILE); } else if (str.equals("memory")) { appModule.setStoreForPassiveState(ApplicationModule.PASSIVATE_TO_MEMORY); }
setStoreForPassiveState
in interface ApplicationModule
storageType
- where the Application Module state is stored. Can be one
of ApplicationModule.PASSIVATE_TO_DATABASE
(default target),
ApplicationModule.PASSIVATE_TO_FILE
, or ApplicationModule.PASSIVATE_TO_MEMORY
.ApplicationModule.passivateState(byte[])
public void fetchAttributeProperties(java.lang.String[] voNames, java.lang.String[][] voAttrNames, LocaleContext locale)
ApplicationModule
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.
fetchAttributeProperties
in interface ApplicationModule
public java.lang.String getDefName()
ComponentObject
getDefName
in interface ComponentObject
public java.lang.String getDefFullName()
ComponentObject
getDefFullName
in interface ComponentObject
public java.lang.String getName()
ComponentObject
getName
in interface ComponentObject
getName
in class WSObject
public java.lang.String getFullName()
ComponentObject
getFullName
in interface ComponentObject
getFullName
in class WSObject
public void remove()
ComponentObject
remove
in interface ComponentObject
public java.lang.Object getProperty(java.lang.String hintName)
Properties
getProperty
in interface Properties
hintName
- Property name.
null
.public java.lang.Object refreshProperty(java.lang.String hintName)
Properties
getProperty
.
refreshProperty
in interface Properties
hintName
- Property name.
null
.public java.util.Hashtable getProperties()
Properties
getProperties
in interface Properties
public void resolve(ApplicationModule am)
public WSApplicationModuleMarshaller getWSApplicationModuleMarshaller()
public java.lang.Object get(java.lang.Object keyObj)
get
in interface java.util.Map
get
in class WSObject
public java.lang.String getVersion()
Session
getVersion
in interface Session
public java.util.Locale getLocale()
Session
Locale
used for localizing error messages.
getLocale
in interface Session
Locale
.public void setLocale(java.util.Locale locale)
Session
Locale
for localizing error messages.
setLocale
in interface Session
locale
- the new Locale
.public java.lang.String[] getPackageNames()
Session
getPackageNames
in interface Session
public java.lang.String[] getApplicationModuleDefNames(java.lang.String packageName)
Session
getApplicationModuleDefNames
in interface Session
packageName
- the name of the package.
ApplicationModule
definition names.public java.lang.String[] getAllApplicationModuleDefNames()
Session
getAllApplicationModuleDefNames
in interface Session
ApplicationModule
definition names.public java.lang.String[] getViewDefNames(java.lang.String packageName)
Session
getViewDefNames
in interface Session
packageName
- the name of the package.
ViewDef
names.public java.lang.String[] getAllViewDefNames()
Session
getAllViewDefNames
in interface Session
ViewDef
names.public java.lang.String[] getEntityDefNames(java.lang.String packageName)
Session
getEntityDefNames
in interface Session
packageName
- the name of the package.
EntityDef
names.public java.lang.String[] getAllEntityDefNames()
Session
getAllEntityDefNames
in interface Session
EntityDef
names.public java.lang.String[] getEntityAssociationDefNames(java.lang.String packageName)
Session
getEntityAssociationDefNames
in interface Session
packageName
- the name of the package.
EntityAssociationDef
names.public java.lang.String[] getAllEntityAssociationDefNames()
Session
getAllEntityAssociationDefNames
in interface Session
EntityAssociationDef
names.public java.lang.String[] getViewLinkDefNames(java.lang.String packageName)
Session
getViewLinkDefNames
in interface Session
packageName
- the name of the package.
ViewLinkDef
names.public java.lang.String[] getAllViewLinkDefNames()
Session
getAllViewLinkDefNames
in interface Session
ViewLinkDef
names.public void loadPackage(java.lang.String packageName)
Session
loadPackage
in interface Session
packageName
- a fully qualified package name.public java.util.Hashtable getEnvironment()
Session
PropertyMetadata
. Applications
should store custom session context in the Session userdata.
getEnvironment
in interface Session
Session.getUserData()
public LocaleContext getLocaleContext()
Session
getLocaleContext
in interface Session
public java.util.Hashtable getUserData()
Session
getUserData
in interface Session
public java.lang.String[] getUserRoles()
Session
getUserRoles
in interface Session
public boolean isUserInRole(java.lang.String role)
isUserInRole
in interface Session
role
- the name of the role.
public boolean isClient()
Session
isClient
in interface Session
public ApplicationModule getCustomApplicationModule()
public java.lang.Object invokeExportedMethod(java.lang.String methodName, java.lang.String[] argTypes, java.lang.Object[] args)
invokeExportedMethod
in interface Exportable
public ViewObject findCustomViewObject(java.lang.String voName, java.lang.String voType)
public ViewObject findCustomViewObject(WSViewObjectImpl wsvo, java.lang.String voType)
public int getReleaseLevel()
ApplicationModule
For example, the ADF/BC DataControl will invoke getReleaseLevel() to determine if this ApplicationModule may be released to the ApplicationPool in SHARED_MANAGED_RELEASE_MODE or if the ApplicationModule may be released in RESERVED_UNMANAGED_RELEASE_MODE.
Two release levels are currently supported:
RELEASE_LEVEL_MANAGED Default. Indicates that the ApplicationModule 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 ApplicationModule may not be managed by the BC4J state management service. ApplicationModules 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 ApplicationModules accumulate with the accumulation of new sessions.
If both flags have been specified then RELEASE_LEVEL_RESERVED will take precedence.
getReleaseLevel
in interface ApplicationModule
public void setReleaseLevel(int releaseLevel)
setReleaseLevel
in interface ApplicationModule
{@link #getReleaseLevel()}
public void beginRequest(java.util.HashMap ctx)
public void endRequest(java.util.HashMap ctx)
|
Oracle ADF Model and Business Components API Reference 10.1.2 B14022-01 | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright © 1997, 2004, Oracle. All rights reserved.