|
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 oracle.jbo.common.NamedObjectImpl oracle.jbo.server.NamedObjectImpl oracle.jbo.server.ComponentObjectImpl oracle.jbo.server.ContainerObjectImpl oracle.jbo.server.ApplicationModuleImpl
The base class of Application Modules.
An Application Module is a logical container for coordinated objects related
to a particular task, with optional programming logic. Application Modules
provide a simple runtime data connection model (one connection per
Application Module) and a context for defining and executing transactions.
The framework provides an ApplicationPool
interface that clients can use to manage and share a pool of Application
Modules. An Application Module provides the following functionality:
getTransaction
, to obtain references to
application View Objects getViewObjects
, and to invoke
custom application methods. For more information about custom
application methods please see Extending the Application
Module Implementation which describes extending the default
Application Module implementation.
create()
on
the Application Module's home, ApplicationModuleHome
.
Nested Application Modules may be instantiated by the Business Components for Java framework when its
parent application module is instantiated (static nesting) or when an
application invokes createApplicationModule
on an existing Application Module instance (dynamic nesting). Please see
Nesting Application Modules for more information
about nested Application Modules.
Customers can use the Application Module wizard to declare custom Application Module implemenations to the BC4J framework.
DBTransactionImpl
.
The root Application Module provides the transaction context for its
contained Application Modules. A nested Application Module design is useful
for applications that define several functional sub-applications that share
the same transaction context and transaction caches. With a nested
Application Module design, it is easy to re-deploy nested Application
Modules as standalone Application Modules in different client applications
without having to modify the metadata for the other existing Application
Modules.
ApplicationPool
Field Summary | |
static java.lang.String |
DEFAULT_DEF_NAME
Default Def name for Application Module. |
Fields inherited from class oracle.jbo.server.ContainerObjectImpl |
mComponentList, mComponents |
Fields inherited from class oracle.jbo.common.NamedObjectImpl |
mFullName, mObjName, mParent, mProperties |
Fields inherited from interface oracle.jbo.common.ws.WSApplicationModuleMarshaller |
ACTIVATION_AFTER_LOSS_OF_AFFINITY, ACTIVATION_AFTER_RESTART, ACTIVATION_NONE, SYNC_INT_BATCH, SYNC_INT_BATCH_DO_WORK |
Constructor Summary | |
protected |
ApplicationModuleImpl()
constructs a new Application Module. |
Method Summary | |
protected void |
activate(Session session)
Called by the framework when a root Application Module is created. |
protected void |
activateConnectionState(Element parent)
Allow subclasses to retrieve custom data associated with connection state. |
void |
activateOpenVOs(XMLDocument out)
Internal: Applications should not call this method. |
protected void |
activateState(Element parent)
Allows subclasses to retrieve custom data from an XML-node under the given parent element. |
byte[] |
activateState(int id,
boolean remove)
|
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(ComponentObjectImpl object)
Internal: Applications should not use this method. |
void |
addResponse(java.io.Serializable resp)
|
void |
addWarning(JboWarning warn)
Specifies the name of the handler that will perform special processing of warnings on the client. |
void |
afterActivation(int activationMode)
|
void |
afterCommit(TransactionEvent e)
Called to report that a Commit operation has occurred. |
protected void |
afterConnect()
Invoked after the application module database connection has been established. |
void |
afterRemove(TransactionEvent e)
A cleanup routine to be invoked by transaction manager when this transaction listener is removed from the manager's list. |
void |
afterRollback(TransactionEvent e)
Called to report that a Rollback operation has occurred. |
void |
beforeCommit(TransactionEvent e)
Called to report that a Commit operation is imminent. |
protected void |
beforeDisconnect()
Invoked before the application module database connection has been released. |
void |
beforeRollback(TransactionEvent e)
Called to report that a Rollback operation is imminent. |
void |
bindToWorkingSet(WSApplicationModuleImpl wsam)
|
void |
clearVOCaches(java.lang.String entityName,
boolean recurse)
Clears the caches of all View Objects that use the specified entity. |
ApplicationModule |
createApplicationModule(java.lang.String amName,
java.lang.String defName)
Creates an instance of an Application Module within this Application Module; that is, a nested Application Module. |
ComponentObject |
createComponentObject(java.lang.String coName,
java.lang.String comDefName)
Creates a Component object in the context of this Application Module. |
static ApplicationModuleImpl |
createRootApplicationModule(java.lang.String applicationModuleDefName,
Session sess)
Internal: Applications should not call this method. |
static void |
createSharedDataHandle()
Internal: Applications should not call this method. |
ViewLink |
createViewLink(java.lang.String viewLinkName,
java.lang.String viewLinkDefName,
ViewObject master,
ViewObject detail)
Creates a View Link, given the View Link name, the Def name, and the names of the master and detail View Objects. |
ViewLink |
createViewLinkBetweenViewObjects(java.lang.String viewLinkName,
java.lang.String accessorName,
ViewObject master,
AttributeDef[] srcAttrs,
ViewObject detail,
AttributeDef[] destAttrs,
java.lang.String assocClause)
Creates a View Link given either a View Link Definition or an Entity Association. |
ViewLink |
createViewLinkFromEntityAssocName(java.lang.String viewLinkName,
java.lang.String entityAssocName,
ViewObject master,
ViewObject detail)
Creates a View Link, given the View Objects and an Entity Association. |
ViewObject |
createViewObject(java.lang.String voName,
java.lang.String vDefName)
Creates an updateable View Object. |
protected ViewObject |
createViewObject(java.lang.String voName,
ViewDefImpl viewDef)
|
ViewObject |
createViewObjectFromQueryClauses(java.lang.String voName,
java.lang.String eoName,
java.lang.String selectClause,
java.lang.String fromClause,
java.lang.String whereClause,
java.lang.String orderByClause)
Creates an updateable View Object. |
ViewObject |
createViewObjectFromQueryStmt(java.lang.String voName,
java.lang.String query)
Creates a read-only View Object, given a query statement and a name for the View Object. |
ApplicationModule |
createWorkerApplicationModule(java.lang.Object sessionCookie)
|
static void |
createXMLSharedDataHandle()
Deprecated. This method was to be used in conjunction with Java-in-the-database configuration which is no longer supported. |
void |
detach()
Internal: Applications should not use this method. |
ServiceMessage |
doMessage(ServiceMessage msg)
|
ApplicationPoolSvcMsgContext |
doPoolMessage(ApplicationPoolSvcMsgContext ctx)
Internal use only. |
java.lang.String |
dumpQueryResult(java.lang.String query,
java.lang.String dumpClassName,
java.lang.String[] data)
Writes the result of the query to a (potentially very long) string. |
int |
executeCommand(java.lang.String command)
Specifies a valid SQL statement to be executed by the server. |
void |
fetchAttributeProperties(java.lang.String[] voNames,
java.lang.String[][] attrs,
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 compName)
Finds the component object from the Application Module. |
java.lang.Object |
findObject(java.lang.String name)
|
java.lang.Object |
findObject(java.lang.String name,
java.lang.Class type)
|
RowSetIterator |
findRSIForEntity(RowSetIterator[] rsis,
int eRowHandle)
Finds the RowSetIterator associated with the specified 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 eoName,
java.lang.String[] attrNames)
Given an array of View Objects (the vos parameter), finds the first matching View Object. |
void |
findVOsWithEntityUsage(java.lang.String entityName,
boolean recurse,
com.sun.java.util.collections.ArrayList vos)
Finds the View Objects that use the specified entity. |
void |
findVOsWithEntityUsage(java.lang.String entityName,
boolean recurse,
java.util.Vector vos)
|
void |
finishLoadingComponents(boolean recurse)
|
void |
finishSyncWorkingSet(WSApplicationModuleImpl wsAM,
boolean isEndOfSvcMsg)
|
ApplicationModuleDefImpl |
getApplicationModuleDef()
Returns the Def (definition) associated with this Application Module. |
ApplicationModuleImpl[] |
getApplicationModuleImpls()
Internal: Applications should not use this method. |
java.lang.String[] |
getApplicationModuleNames()
Returns an array of 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. |
AppModuleRequestHandler |
getAppModuleRequestHandler()
|
static AttributeDefValue[] |
getAttributeDefs(StructureDef def)
|
static AttributeDefValue[] |
getAttributeDefsForVO(ViewObject vo)
|
java.lang.String |
getClientProxyClassName()
Internal: Applications should not use this method. |
java.lang.String |
getClientProxyClassName(java.lang.String serverType)
Deprecated. Platform specific proxies not required. Use getClientProxyClassName() instead. |
java.lang.String |
getClientProxyInterfaceName()
|
WSApplicationModuleImpl |
getCurrentWorkingSet()
|
DBTransaction |
getDBTransaction()
Gets this Application Module's database transaction. |
java.lang.String |
getDefFullName()
Returns the fully-qualified (that is, package-qualified) name of this Application Module's Def (definition) object. |
java.lang.String |
getDefName()
Returns the name of this Application Module's Def (definition) object. |
byte[] |
getEntityAttributesPermission(java.lang.String entityName)
Returns the current authenticated user permission for entity attributes. |
Row |
getEntityRowFromHandle(int eRowHandle)
Internal: Applications should not use this method. |
JboExceptionHandler |
getExceptionHandler()
|
int |
getMostRecentStackId()
Internal: Applications should not use this method. |
ObjectMarshaller |
getObjectMarshaller()
|
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()
|
Session |
getSession()
Returns the session information. |
ClientDocument |
getStyles(java.lang.String name)
Gets the Application Module's style definitions from the middle tier. |
java.lang.Object |
getSyncLock()
Gets the locking object for this Application Module. |
int |
getSyncMode()
Returns the sync mode for this Application Module. |
Transaction |
getTransaction()
Returns the transaction information. |
java.lang.String |
getUserPrincipalName()
Returns the session user principal name. |
byte[] |
getViewAttributesPermission(ViewObject vo)
Returns the current authenticated user permission for view attributes. |
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. |
ViewLinkImpl[] |
getViewLinks()
Returns an array of the View Links contained 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. |
ViewObject[] |
getViewObjects()
Constructs an array of this Application Module's View Objects. |
WSApplicationModuleMarshaller |
getWorkingSetMarshaller()
Internal: Applications should not use this method. |
protected void |
handleDefinitionChangedOnActivate(java.lang.Object activatedTS)
Allows subclasses to abort activation, when the metadata for the component objects has changed and an attempt is made to activate an Application Module which was saved with an older version of the metadata. |
boolean |
hasPendingDataPosts()
|
java.lang.Object |
invokeMethod(java.lang.Object target,
java.lang.String methodName,
java.lang.String[] argTypeNames,
java.lang.Object[] args)
|
boolean |
isLoadComponentsLazily()
|
boolean |
isNameGenerated()
Tests if the Application Module's name was generated by the system. |
boolean |
isRoot()
Determines if this is the root Application Module. |
boolean |
isTransientTransactionListener()
Tests whether this transaction listener is transient or permanent. |
boolean |
isValidIdForUndo(java.lang.String id)
Determines if an id created using passivateStateForUndo(String, byte[], int)
is still valid. |
static void |
launchTester(java.lang.String packageName,
java.lang.String configName)
|
java.lang.Object |
marshal(java.lang.Object obj)
|
java.lang.Object |
marshalForActivate(java.lang.Object obj)
|
protected void |
passivateConnectionState(Document doc,
Element parent)
Allows subclasses to store custom data associated with connection state. |
XMLDocument |
passivateOpenVOs(boolean close)
Internal: Applications should not call this method. |
int |
passivateState(byte[] clientData)
|
int |
passivateState(byte[] clientData,
int flags)
Internal: Applications should not use this method. |
protected void |
passivateState(Document doc,
Element parent)
Allows subclasses to store custom data as XML-nodes under the given parent element, in the given document. |
int |
passivateState(int id,
byte[] clientData)
Internal: Applications should not 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. |
protected void |
prepareForActivation(Element amNode)
Override this method to activate custom data in the ApplicationModule from this AM's xml node. |
protected void |
prepareForPassivation(Document out,
Element parent)
Override this method to passivate custom data in the ApplicationModule. |
protected void |
prepareSession(Session session)
Prepares the ApplicationModule session. |
void |
prepareSession(SessionData info)
Internal: Applications should not use this method. |
void |
remove()
Deletes this Application Module. |
protected void |
removeChild(ComponentObjectImpl object)
Internal: Applications should not use this method. |
void |
removeState(int id)
Internal: Applications should not use this method. |
int |
reservePassivationId()
Internal: Applications should not user this method. |
int |
reserveSnapshotId(int flags)
Internal: Applications should not use this method. |
protected void |
reset()
BC4J invokes this method when a ApplicationModule is being reset for potential reuse by another client session. |
void |
resetState(boolean reload)
|
void |
resetState(int flags)
Internal: Applications should not use this method. |
ServiceMessage |
sendServiceMessage(ServiceMessage svcMsgIn)
|
ServiceMessage |
sendWorkingSetRequests(java.lang.String reqName,
WSApplicationModuleImpl wsAM,
ServiceMessage msg)
|
void |
setBoundToWorkingSet(boolean b)
|
void |
setDataModelRefresh(boolean b)
|
void |
setExceptionHandler(JboExceptionHandler hndlr)
Specifies the name of the handler which will perform special processing of the exceptions on the client. |
void |
setLoadComponentsLazily(boolean isLoadComponentsLazily)
|
void |
setReleaseLevel(int releaseLevel)
|
void |
setRemoteAdapter(ApplicationModuleRemoteAdapter adapter)
|
void |
setStoreForPassiveState(byte storageType)
Internal: Applications should not use this method. |
void |
setStyles(java.lang.String name,
ClientDocument clientDocument)
Saves the Application Module's style definitions to the middle tier. |
void |
setSyncMode(int mode)
Sets the data synchronization mode between the client and the middle tier. |
void |
setWorkingSetMarshaller(WSApplicationModuleMarshaller marshaller)
Internal: Applications should not use this method. |
void |
sync()
Synchronizes all the result sets defined in this Application Module in the client with the application tier. |
void |
syncMarshaller(ServiceMessage msg)
|
void |
syncWorkingSet(WSApplicationModuleImpl wsAM)
Internal: Applications should not use this method. |
java.lang.Object[] |
transformExceptionParams(ViewObject[] inVOs,
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. |
protected java.lang.Object[] |
transformExceptionParams(ViewObject vo,
java.lang.String entityDefName,
java.lang.String className,
java.lang.Object[] params)
Internal: Applications should not call this method. |
java.lang.Object |
transPostGetAttr(int op,
int hdl,
int index,
java.lang.String name)
Internal: Applications should not use this method. |
void |
transPostPushback(int hdl)
Internal: Applications should not use this method. |
void |
transPostRefresh(int refreshMode,
int hdl)
|
void |
transPostRemove(int hdl)
Internal: Applications should not use this method. |
void |
transPostRevert(int hdl)
Internal: Applications should not use this method. |
void |
transPostRowOp(int op,
int hdl)
Internal: Applications should not use this method. |
void |
transPostSetAttr(int op,
int hdl,
int index,
java.lang.String name,
java.lang.Object value)
Internal: Applications should not use this method. |
Methods inherited from class oracle.jbo.server.ContainerObjectImpl |
addContainerListener, removeContainerListener |
Methods inherited from class oracle.jbo.server.ComponentObjectImpl |
addListener, create, createRef, getApplicationModule, getCompListeners, getCompListenersList, getProxyClassName, getProxyClassName, getRootApplicationModule, isRegWithPiggyMan, setName, setParent, setProxyClassName |
Methods inherited from class oracle.jbo.server.NamedObjectImpl |
setParent, setPropertiesMap |
Methods inherited from class oracle.jbo.common.NamedObjectImpl |
getFullName, getName, getParent, getProperties, getPropertiesAsStrings, getPropertiesMap, getProperty, refreshProperty, setFullName, setProperty |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Methods inherited from interface oracle.jbo.ComponentObject |
getFullName, getName |
Methods inherited from interface oracle.jbo.Properties |
getProperties, getProperty, refreshProperty |
Field Detail |
public static final java.lang.String DEFAULT_DEF_NAME
Constructor Detail |
protected ApplicationModuleImpl()
Method Detail |
public final 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 static ApplicationModuleImpl createRootApplicationModule(java.lang.String applicationModuleDefName, Session sess)
A factory method for creating a root Application Module.
applicationModuleDefName
- the name of an Application Module definition.sess
- the session.public static void createSharedDataHandle()
Call this function to register a shared data handle with the
MetaObjectManager
and use it later.
public static void createXMLSharedDataHandle()
MetaObjectManager
and use it later.
protected void activate(Session session) throws java.lang.IllegalStateException
create
method which is called even when
nested Application Modules are created, this method is called only for
the root Application Module.
Subclasses can override this method to perform customizations. For example, it can be overriden to initialize connection pools. Another example is to override activate to automatically create a connection in the middle tier when the root Application Module is created.
If this method is overriden, then subclasses must call the super class first in the custom implementation.
Please take special note that this method will only be called once
when the root ApplicationModule is created. Subclasses should extend
prepareSession(Session)
to initialize true session state.
session
- the session in which the root Application Module is
created.
java.lang.IllegalStateException
prepareSession(oracle.jbo.Session)
public boolean isLoadComponentsLazily()
public void setLoadComponentsLazily(boolean isLoadComponentsLazily)
public void finishLoadingComponents(boolean recurse)
public ApplicationModuleDefImpl getApplicationModuleDef()
This method should not be overridden.
public boolean isRoot()
isRoot
in interface ApplicationModule
true
if this is the root; false otherwise.protected void addChild(ComponentObjectImpl object)
Adds names to this Application Module's own list of child components.
The child components can be View Objects, View Links,
or other Application Modules. This method overrides an internal
addChild method in
NamedObjectImpl
.
object
- an object to add to the component list.NamedObjectImpl
protected void removeChild(ComponentObjectImpl object)
Removes names from this Application Module's own list of child components.
The child components can be View Objects, View Links,
or other Application Modules. This method overrides an internal
removeChild method in
NamedObjectImpl
.
object
- an object to remove from the component list.NamedObjectImpl
public java.lang.String getDefName()
getDefName
in interface ComponentObject
getDefName
in class ComponentObjectImpl
public java.lang.String getDefFullName()
getDefFullName
in interface ComponentObject
getDefFullName
in class ComponentObjectImpl
public ApplicationModule createApplicationModule(java.lang.String amName, java.lang.String defName)
oracle.jbo.ApplicationModule nestedAM = yourAm.createApplicationModule("subAppMod", "PackageName.AppModuleName");
You can override this method to also create View Objects within the "scope" of the Application Module, and make it available to other code. In this case, the code in the Application Module can make assumptions about what View Objects are available and contain code for customizing the View Objects. It can control the namespace of objects that are contained within it.
createApplicationModule
in interface ApplicationModule
amName
- the name to be given to the Application Module.
If amName
is empty, a name is generated.defName
- the name of the Application Module definition to be used.
If null
a default definition is used.
public java.lang.Object findObject(java.lang.String name)
public java.lang.Object findObject(java.lang.String name, java.lang.Class type)
public 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");
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.
InvalidObjNameException
- if amName
is an invalid name.
amName
must be a vaild Java name.public 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
.
#getApplicatonModuleNames(boolean, boolean)
getApplicationModuleNames
in interface ApplicationModule
findApplicationModule(String)
public java.lang.String[] getApplicationModuleNames(boolean inclLoadedOnes, boolean inclNotLoadedOnes)
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 getApplicationModuleNames()
getApplicationModuleNames(true, false)
.
getApplicationModuleNames
in interface ApplicationModule
inclLoadedOnes
- if true
, only loaded ones are
returned.inclNotLoadedOnes
- if true
, only those that are not yet
loaded are returned.
public void transPostPushback(int hdl)
transPostPushback
in interface TransPostControl
public void transPostRemove(int hdl)
transPostRemove
in interface TransPostControl
public void transPostRevert(int hdl)
transPostRevert
in interface TransPostControl
public void transPostRefresh(int refreshMode, int hdl)
transPostRefresh
in interface TransPostControl
public void transPostRowOp(int op, int hdl)
public java.lang.Object transPostGetAttr(int op, int hdl, int index, java.lang.String name)
public void transPostSetAttr(int op, int hdl, int index, java.lang.String name, java.lang.Object value)
public Row getEntityRowFromHandle(int eRowHandle)
public void sync()
sync
in interface ApplicationModule
public void setBoundToWorkingSet(boolean b)
setBoundToWorkingSet
in interface WSApplicationModuleMarshaller
public void setSyncMode(int mode)
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
.getSyncMode()
,
ApplicationModule.SYNC_LAZY
,
ApplicationModule.SYNC_IMMEDIATE
public void setWorkingSetMarshaller(WSApplicationModuleMarshaller marshaller)
marshaller
- Working Set AM marshallerpublic WSApplicationModuleMarshaller getWorkingSetMarshaller()
public void detach()
detach
in interface WSApplicationModuleMarshaller
public void afterActivation(int activationMode)
afterActivation
in interface WSApplicationModuleMarshaller
public void bindToWorkingSet(WSApplicationModuleImpl wsam)
bindToWorkingSet
in interface WSApplicationModuleMarshaller
public WSApplicationModuleImpl getCurrentWorkingSet()
getCurrentWorkingSet
in interface WSApplicationModuleMarshaller
public boolean hasPendingDataPosts()
hasPendingDataPosts
in interface WSApplicationModuleMarshaller
public ApplicationModule createWorkerApplicationModule(java.lang.Object sessionCookie)
createWorkerApplicationModule
in interface WSApplicationModuleMarshaller
public AppModuleRequestHandler getAppModuleRequestHandler()
getAppModuleRequestHandler
in interface WSApplicationModuleMarshaller
public void syncWorkingSet(WSApplicationModuleImpl wsAM)
syncWorkingSet
in interface WSApplicationModuleMarshaller
wsAM
- Working Set AMpublic void finishSyncWorkingSet(WSApplicationModuleImpl wsAM, boolean isEndOfSvcMsg)
finishSyncWorkingSet
in interface WSApplicationModuleMarshaller
public ServiceMessage sendWorkingSetRequests(java.lang.String reqName, WSApplicationModuleImpl wsAM, ServiceMessage msg)
sendWorkingSetRequests
in interface WSApplicationModuleMarshaller
public java.lang.String getResponseName()
getResponseName
in interface WSApplicationModuleMarshaller
public int getRemoteObjectId(java.lang.Object obj)
getRemoteObjectId
in interface WSApplicationModuleMarshaller
public java.lang.Object marshal(java.lang.Object obj)
marshal
in interface WSApplicationModuleMarshaller
public java.lang.Object marshalForActivate(java.lang.Object obj)
marshalForActivate
in interface WSApplicationModuleMarshaller
public void addResponse(java.io.Serializable resp)
addResponse
in interface WSApplicationModuleMarshaller
public void setDataModelRefresh(boolean b)
setDataModelRefresh
in interface WSApplicationModuleMarshaller
public ObjectMarshaller getObjectMarshaller()
getObjectMarshaller
in interface WSApplicationModuleMarshaller
public int getSyncMode()
getSyncMode
in interface ApplicationModule
ApplicationModule.setSyncMode(int mode)
,
ApplicationModule.SYNC_LAZY
,
ApplicationModule.SYNC_IMMEDIATE
public 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)
getViewObjectNames
in interface ApplicationModule
findViewObject(String)
public java.lang.String[] getViewObjectNames(boolean inclLoadedOnes, boolean inclNotLoadedOnes)
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)
.
getViewObjectNames
in interface ApplicationModule
inclLoadedOnes
- if true
, only loaded ones are
returned.inclNotLoadedOnes
- if true
, only those that are not yet
loaded are returned.
public 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 Links that are not yet loaded,
use
.
getViewLinkNames(boolean, boolean)
getViewLinkNames
in interface ApplicationModule
findViewLink(String)
public java.lang.String[] getViewLinkNames(boolean inclLoadedOnes, boolean inclNotLoadedOnes)
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)
.
getViewLinkNames
in interface ApplicationModule
inclLoadedOnes
- if true
, only loaded ones are
returned.inclNotLoadedOnes
- if true
, only those that are not yet
loaded are returned.
public ViewLinkImpl[] getViewLinks()
The following example uses this method to remove the View Links contained in the Application Module:
ViewLink[] vls = yourAM.getViewLinks(); for (j = 0; j < vls.length; j++) { vls[j].remove(); }
public ViewLink createViewLink(java.lang.String viewLinkName, java.lang.String viewLinkDefName, ViewObject master, ViewObject detail)
For example, assume that during design time, you used the Design-Time View Object Wizard to create two View Objects, DeptVO and EmpVO inside of a package named package1. Then, assume that you invoked the View Link Wizard from the package node to create a View Link Definition named MyViewLinkDef, that links DeptVO and EmpVO in a master-detail relationship.
Given that you have the names of the View Link Definition and the master and detail View Objects, you can provide code such as the following that executes during runtime and creates a View Link named MyLink1:
ViewObject voDept = myAM.createViewObject("MyDept", "package1.DeptVO"); ViewObject voEmp = myAM.createViewObject("MyEmp", "package1.EmpVO"); ViewLink vl = myAM.createViewLink("MyLink1", "package1.MyViewLinkDef", voDept, voEmp);
This will set up a master-detail relationship between the voDept and the voEmp.
createViewLink
in interface ApplicationModule
viewLinkName
- the name to be given to the View Link.
If empty, a name is generated.viewLinkDefName
- the name of the definition to be used to create the link.
If empty, a default definition will be used.master
- the link's source View Object.detail
- the link's destination View Object.
InvalidParamException
- if master
or detail
are invalid.
InvalidObjNameException
- if viewLinkName
is invalid.
NameClashException
- if viewLinkName
already exists.ApplicationModule.createViewObject(String, String)
public ViewLink createViewLinkFromEntityAssocName(java.lang.String viewLinkName, java.lang.String entityAssocName, ViewObject master, ViewObject detail)
Use this method to create a View Link when your code can access the View Objects and an Entity Association. This method can create a View Link because a View Link Definition can be built from the Entity Association between the underlying Entity Objects.
For example, during Design Time you can define View Objects such as DeptVO for the DeptEO Entity Object, and EmpVO for the EmpEO Entity Object. Then you can define an Association named MyAssoc that associates DeptEO to EmpEO. With this information, you can build a View Link Definition, say MyViewLinkBasedOnAssoc, which relates DeptVO to EmpVO, based on this Entity Association.
During runtime, you can create a View Link with code like this:
ViewObject voDept = myAM.createViewObject("MyDept", "package1.DeptVO"); ViewObject voEmp = myAM.createViewObject("MyEmp", "package1.EmpVO"); ViewLink vl = myAM.createViewLinkFromEntityAssocName("MyLink2", "package1.MyAssoc", voDept, voEmp);
The primary difference between
createViewLink
and
createViewLinkFromEntityAssocName is that the former requires
the View Link Definition name, and the latter requires the Entity
Association name.
createViewLinkFromEntityAssocName
in interface ApplicationModule
viewLinkName
- the name to be given to the View Link.
If empty a name is generated.entityAssocName
- the entity association that the View Link will represent.master
- the link's source View Object.detail
- the link's destination View Object.
InvalidParamException
- if master
,
detail
, or entityAssocName
are invalid.
InvalidObjNameException
- if viewLinkName
is invalid.
NameClashException
- if viewLinkName
already exists.ApplicationModule.createViewObject(String, String)
public ViewLink createViewLinkBetweenViewObjects(java.lang.String viewLinkName, java.lang.String accessorName, ViewObject master, AttributeDef[] srcAttrs, ViewObject detail, AttributeDef[] destAttrs, java.lang.String assocClause)
During design time, you could define View Objects such as DeptVO for the DeptEO Entity Object, and EmpVO for the EmpEO Entity Object, but not define an Entity Association or a View Link Definition.
During runtime, you can use createViewLinkBetweenViewObjects to create a View Link by associating attributes from DeptVO and EmpVO. For example, if both DeptVO and EmpVO have a DeptNum attribute, you can associate the attributes and create the View Link with the following block of code:
ViewObject voDept = myAM.createViewObject("MyDept", "package1.DeptVO"); ViewObject voEmp = myAM.createViewObject("MyEmp", "package1.EmpVO"); // Build an attribute array, consisting of DeptVO.DeptNum. AttributeDef[] deptAttrs = new AttributeDef[1]; deptAttrs[0] = voDept.findAttributeDef("DeptNum"); // Build an attribute array, consisting of EmpVO.DeptNum. AttributeDef[] empAttrs = new Attributedef[1]; empAttrs[0] = voEmp.findAttributeDef("DeptNum"); ViewLink vl = myAM.createViewLinkBetweenViewObjects("MyLink3", "Employees", // accessor name--more on this below voDept, // master deptAttrs, // department attributes voEmp, // detail empAttrs, // employee attributes null); // assoc clause
The createViewLinkBetweenViewObjects call builds a View Link that makes voEmp a detail of voDept. The voEmp View Object will display employees for the current department in voDept.
Using the Accessor Name
The createViewLinkBetweenViewObjects method lets you specify an
accessor name. The accessor lets you retrieve details by calling
getAttribute with that name. In the above code example, the
accessor was specified as Employees. Calling getAttribute
on Employees will return an iterator through which you can
enumerate employees in the current department.
For example, you can write code like this that will return an iterator that can enumerate employees in the first department.
Row row = voDept.first(); // get the first dept RowIterator iter = (RowIterator) row.getAttribute("Employees");
If your code does not need an accessor, the accessorName parameter can be set to null.
Using the Association Clause
The createViewLinkBetweenViewObjects method lets you specify a
custom association clause, replacing the one generated by the
Business Components runtime. Passing in null means that the
method will use the association clause generated by runtime which relates
the source attributes to the destination attributes. For example, since
assocClause is null in the above code snippet, runtime
will use the equivalent of the PL/SQL association clause WHERE
voDept.DeptNum=voEmp.DeptNum.
createViewLinkBetweenViewObjects
in interface ApplicationModule
viewLinkName
- the name to be given to the View Link.
If empty, a name is generated.accessorName
- the name to be given to the View Link's accessor.master
- the link's source View Object.srcAttrs
- link attributes taken from the master View Object.detail
- the link's destination View Object.destAttrs
- link attributes taken from the detail View Object.assocClause
- the association clause. Can be null.
InvalidParamException
- if master
or detail
are invalid.
InvalidObjNameException
- if viewLinkName
or accessorName
are invalid.
NameClashException
- if viewLinkName
or accessorName
already exist.ApplicationModule.createViewObject(String, String)
,
StructureDef.findAttributeDef(String)
,
RowIterator.next()
,
AttributeList.getAttribute(String)
public 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");
findViewObject
in interface ApplicationModule
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)
public ComponentObject findComponentObject(java.lang.String compName)
ComponentObject
interface. This method
allows for integration of other applications.
findComponentObject
in interface ApplicationModule
findComponentObject
in class ContainerObjectImpl
compName
- name of the component object.public 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");
findViewLink
in interface ApplicationModule
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)
public DBTransaction getDBTransaction()
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 haspublic ViewObject[] getViewObjects()
ViewObject[] vos = yourAM.getViewObjects(); for (j = 0; j < vos.length; j++) { vos[j].remove(); }
public ViewObject createViewObjectFromQueryStmt(java.lang.String voName, java.lang.String query)
The following example of a simple fetch uses a static SQL statement with all information hard-coded. After printing the results, the View Object is removed.
public static void demoSimpleFetch(ApplicationModule appMod) { // Define basic query string. String sqlStr = "SELECT Emp.ename, Emp.mgr FROM EMP Emp "; ViewObject vo = appMod.createViewObjectFromQueryStmt("QueryDemo", sqlStr); printViewObject(vo); vo.remove();}
createViewObjectFromQueryStmt
in interface ApplicationModule
query
- the SQL query that defines the View Object.
InvalidObjNameException
- if qName
is invalid.
NoObjException
- if qName
does not exist.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)
Use this method to build a View Object from SQL clauses. The View Object can be based on an Entity Object. For example, the following statement creates a View Object from attributes of the EMP Entity Object. Attributes related to EMP (such as E.ENAME) are updateable.
ViewObject v = appMod.createViewObjectFromQueryClauses("xyz", "demo.hr.EMP", // The one updateable Entity Object Name "E.ENAME, E.EMPNO", // select clause "EMP E", // from clause "E.DEPTNO = 10", // where clause null); // order by clause
createViewObjectFromQueryClauses
in interface ApplicationModule
voName
- the name to be given to the View Object.
If empty, a name is generated.eoName
- the name of the Entity Object from which the
View Object is to be derived.selectClause
- a SQL statement SELECT clause.fromClause
- a SQL statement FROM clause.whereClause
- a SQL statement WHERE clause.orderByClause
- a SQL statement ORDER-BY clause. If null
no order-by clause is established.
InvalidParamException
- if voName
is invalid.
NameClashException
- if voName
already exists.public int executeCommand(java.lang.String command)
The following code example uses executeCommand. The SQL string is designed to update the EMP table. This example passes the string to executeCommand, then prints a message to report how many rows were actually updated.
public static void demoUpdateColumn(ApplicationModule appMod) { String sqlStr = "UPDATE EMP " + "SET MGR=7007 " + "WHERE MGR=7698 "; int n = appMod.getTransaction().executeCommand(sqlStr); System.out.println("Updated " + n + " rows."); }
Be careful when using executeCommand, because it will execute any valid SQL statement. For example, you could perform an operation like the following DDL command:
appMod.getTransaction().executeCommand("DROP TABLE MYTEMPTABLE");
A pending database transaction could be committed inadvertently due to the implicit commit performed by DDL operations, as well as having any row locks released.
command
- a valid SQL statement.public java.lang.String dumpQueryResult(java.lang.String query, java.lang.String dumpClassName, java.lang.String[] data)
The following code example uses dumpQueryResult.
public static void demoSimpleFetch(ApplicationModule appMod) { // Define and execute a simple SQL statement. String sqlStr = "SELECT Emp.ename FROM EMP Emp "; // dumpQueryResult is a utility method for testing queries. String result = appMod.getTransaction().dumpQueryResult(sqlStr, "oracle.jbo.server.QueryDumpTab", null); System.out.println(sqlStr); System.out.println(result); }
data
- an array of data items.protected ViewObject createViewObject(java.lang.String voName, ViewDefImpl viewDef)
public ViewObject createViewObject(java.lang.String voName, java.lang.String vDefName)
This method is useful for instantiating View Objects within a generic Application Module, but you can use it with any Application Module. The code calls createViewObject, passing in the name of the View Object metadata (that is, the name you provided for the View Object at design time) that defines the View Object and a View instance name to identify this instance. You can use this View instance name to find the View Object later, if needed.
// Specify the Java file that defines the View Object. // Format: package.filename String voDefFile = "d2e.DeptView"; // Identify the View Object. Must be a valid Java identifier. String voName = "demoDeptVO"; // Create the View Object within the context defined by the // Application Module. ViewObject vo = appMod.createViewObject(voName, voDefFile);
createViewObject
in interface ApplicationModule
voName
- the name to be given to the View Object.
If empty, a name is generated.vDefName
- a view definition.
InvalidObjNameException
- if voName
is invalid.
NoObjException
- if voName
does not exist.public ComponentObject createComponentObject(java.lang.String coName, java.lang.String comDefName)
An Application
Module typically contains View Objects, View Links, or other
Application Modules. This method will create a generic
component in the context of the Application Module. A generic
component is any object that implements the
ComponentObject
interface. This method
allows for integration of other applications.
createComponentObject
in interface ApplicationModule
createComponentObject
in class ContainerObjectImpl
coName
- name of the component object. If empty, a name will be generated.comDefName
- name of the component Def (definition) object.
InvalidObjNameException
- if an invalid component name is used.public ApplicationModuleImpl[] getApplicationModuleImpls()
Creates an array of Application Modules.
public final boolean isNameGenerated()
true
if the name was generated by the system.
false
if the name was given by the user and
not generated by the system.public static AttributeDefValue[] getAttributeDefs(StructureDef def)
public static AttributeDefValue[] getAttributeDefsForVO(ViewObject vo)
public void remove()
This method should not be overridden.
remove
in interface ComponentObject
remove
in class ComponentObjectImpl
protected void reset()
Examples of session ApplicationModule state include custom instance variables.
resetState(boolean)
public void resetState(boolean reload)
resetState
in interface ApplicationModule
public void resetState(int flags)
ApplicationModule
Applications should override/extend 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 findVOsWithEntityUsage(java.lang.String entityName, boolean recurse, com.sun.java.util.collections.ArrayList vos)
clearVOCaches
.
If entityName is null, then this method finds all View Objects in the Application Module. If recurse is true, it recurses into nested (child) Application Modules.
entityName
- name of the Entity Object that the View Objects use. Can be
null.recurse
- true recurses to (child) Application Modules;
false applies this method only to the top-level Application Module.vos
- a vector of View Objects.clearVOCaches(String, boolean)
public void findVOsWithEntityUsage(java.lang.String entityName, boolean recurse, java.util.Vector vos)
public void clearVOCaches(java.lang.String entityName, boolean recurse)
clearCache()
on each View Object.
If entityName is null, then the caches of all View Objects in the Application Module are cleared. If recurse is true, it recurses into nested (child) Application Modules.
clearVOCaches
in interface ApplicationModule
entityName
- name of the Entity Object that the View Objects use. Can be
null.recurse
- true recurses to (child) Application Modules;
false applies this method only to the top-level Application Module.ViewObject.clearCache()
public java.lang.String getClientProxyClassName()
Returns the client proxy's class name for this Application Module.
public java.lang.String getClientProxyClassName(java.lang.String serverType)
Returns the client proxy's class name for this Application Module. for the given server platform type
public java.lang.String getClientProxyInterfaceName()
getClientProxyInterfaceName
in interface WSApplicationModuleMarshaller
public JboExceptionHandler getExceptionHandler()
getExceptionHandler
in interface ApplicationModule
public void setExceptionHandler(JboExceptionHandler hndlr)
In typical use in three tier mode, a user enters values at the client. A user response, such as pressing the Return key or a Submit button, pushes the values to the server. The values are applied to the Entities and validated. Any exceptions that are thrown, are collected and shipped back to the client. Typically, exceptions are given, one-by-one, to the client. Instead, a handler can be specified to perform special processing of the exceptions.
setExceptionHandler
in interface ApplicationModule
hndlr
- an exception handler.public void addWarning(JboWarning warn)
addWarning
in interface ApplicationModule
warn
- a warning.public void setStyles(java.lang.String name, ClientDocument clientDocument)
setStyles
in interface ApplicationModule
name
- a name under which the style definitions are to be stored.clientDocument
- the ClientDocument
to be saved.ClientDocument
public ClientDocument getStyles(java.lang.String name)
getStyles
in interface ApplicationModule
name
- a name under which the style definitions are stored.
ClientDocument
.ClientDocument
public Session getSession()
activate
call.
getSession
in interface ApplicationModule
java.lang.IllegalStateException
- if the session information cannot be found.activate(Session)
public Transaction getTransaction()
getTransaction
in interface ApplicationModule
java.lang.IllegalStateException
- if the transaction information cannot be found.public void beforeCommit(TransactionEvent e)
TransactionListener
beforeCommit
in interface TransactionListener
e
- a transaction event.public void beforeRollback(TransactionEvent e)
TransactionListener
beforeRollback
in interface TransactionListener
e
- a transaction event.public void afterCommit(TransactionEvent e)
TransactionListener
afterCommit
in interface TransactionListener
e
- a transaction event.public void afterRollback(TransactionEvent e)
TransactionListener
afterRollback
in interface TransactionListener
e
- a transaction event.public void afterRemove(TransactionEvent e)
TransactionListener
afterRemove
in interface TransactionListener
e
- a transaction event.public boolean isTransientTransactionListener()
TransactionListener
Transient listeners are automatically removed at the end of a transaction commit or rollback cycle; permanent listeners remain across these cycles.
isTransientTransactionListener
in interface TransactionListener
true
if the listener is transient.public RowSetIterator findRSIForEntity(RowSetIterator[] rsis, int eRowHandle)
If an error occurs while an entity
is being posted to database, the framework throws a
DMLException
. Inside the DMLException instance is an opaque
handle (in reality an integer) identifying the Entity (an
instance of EntityImpl) that caused the error.
For example, the DMLException could have been thrown because the row violated a database constraint. The client might want to give the user a chance to correct the problem by displaying the the ViewRow that uses this Entity.
To do this, the client would "gather" all RowSetIterators that can be used to report and fix the problem. It would then call findRSIForEntity, passing in the array of RowSetIterators and the Entity row handle returned by DMLException.
Among the RowSetIterator elements in the array, findRSIForEntity will pick the "best" one and return it to the client. The client then can use the RowSetIterator to report the problem and give the user a chance to fix the problem.
findRSIForEntity
in interface ApplicationModule
rsis
- an array of RowSetIteratorseRowHandle
- an Entity row handle returned by DMLException.
RowSetIterator
.DMLException
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 int reservePassivationId()
ApplicationModule
reservePassivationId
in interface ApplicationModule
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 passivateState(byte[] clientData)
passivateState
in interface ApplicationModule
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 int passivateState(int id, byte[] clientData)
ApplicationModule
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 byte[] activateState(int id, boolean remove)
activateState
in interface ApplicationModule
public byte[] activateState(int id, boolean remove, SessionData info)
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 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 void prepareSession(SessionData info)
ApplicationModule
prepareSession
in interface ApplicationModule
protected void prepareSession(Session session)
The application module may be assumed to be in a valid, connected state when this method is invoked. Application developers may extend this method to prepare custom session state. For example, an application developer could extend this method to prepare PL/SQL session state which is related to a virtual private database.
The default implementation of this method will store the current ApplicationModuleHandle on the ApplicationModule session.
getSession()
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 static void launchTester(java.lang.String packageName, java.lang.String configName)
protected void passivateState(Document doc, Element parent)
This method lets customized Application Modules determine how they want to store private data. The only requirement is that this data should be stored under a child node under the parent element. Note that the data cannot be stored under the first child, because that is where default passivation routines always store the key.
By default, the Application Module does not store anything in this method. On
activation, the ApplicationModule calls activateState(Element)
with the parent element for the
reverse operation.
doc
- the name of the XML document where the custom data will be stored.parent
- the name of the parent element under which the custom data will be stored.protected void activateState(Element parent)
parent
- the name of the parent element under which the custom data resides.protected void passivateConnectionState(Document doc, Element parent)
In addition to being invoked prior to full passivation (which allows subclasses to encapsulate their connection state data storage), this method is also invoked as part of disconnect(true). In this latter case, the aim is to allow subclasses to store their connection specific data in memory prior to recycling of the JDBC connection. This data (such as open cursors or PL-SQL global variables) can then be restored when the connection is restored.
For reference, the call order during full passivation is:
Passivate Custom Connection State --------------------------------- 1. For each nested AM in root AM, cycle from step 1: 1.1. For each nested AM in the nested AM, cycle from step 1 (recursion). 1.2. passivateConnectionState() on nested AM. 2. passivateConnectionState() on root AM.
Passivate Overall State ----------------------- 3. prepareForPassivation() on root AM. 4. passivateState() on VOs in root AM. 5. For each nested AM in root AM, cycle from step 1: 5.1. prepareForPassivation() on nested AM. 5.2. passivateState() on VOs in nested AM. 5.3. For each nested AM in the nested AM, cycle from step 1 (recursion). 5.4. passivateState() on nested AM. 6. passivateState() on root AM.
In all cases, clients may expect the application module connection to be valid during these callback methods.
doc
- the XML document in which custom data may be stored.parent
- the parent element under which custom data may be stored.protected void activateConnectionState(Element parent)
In addition to being invoked at the conclusion of full passivation (which allows subclasses to encapsulate their connection state data retrieval), this method is also invoked during reconnect() whenever disconnect(true) has been previously called.
For reference, the call order during full activation is:
Activate Overall State ----------------------- 1. prepareForActivation() on root AM. 2. For each nested AM in root AM, cycle from step 1: 2.1. prepareForActivation() on nested AM. 2.2. For each nested AM in the nested AM, cycle from step 1 (recursion). 2.3. activateState() on VOs in the nested AM. 2.4. activateState() on nested AM. 3. activateState() on VOs in root AM. 4. activateState() on root AM.
Activate Custom Connection State --------------------------------- 5. activateConnectionState() on root AM. 6. For each nested AM in root AM, cycle from step 1: 6.1. activateConnectionState() on nested AM. 6.2. For each nested AM in the nested AM, cycle from step 1 (recursion).
In all cases, clients may expect the application module connection to be valid during these callback methods.
parent
- the parent element under which the custom data resides.protected void handleDefinitionChangedOnActivate(java.lang.Object activatedTS)
public ViewObject findViewObjectUsingEntity(ViewObject[] vos, java.lang.String eoName, java.lang.String[] attrNames)
ApplicationModule
findViewObjectUsingEntity
in interface ApplicationModule
vos
- an array of possible View Objects.eoName
- 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[] inVOs, java.lang.String entityDefName, java.lang.String className, java.lang.Object[] params)
ApplicationModule
transformExceptionParams
in interface ApplicationModule
inVOs
- 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.protected java.lang.Object[] transformExceptionParams(ViewObject vo, java.lang.String entityDefName, java.lang.String className, java.lang.Object[] params)
protected void afterConnect()
protected void beforeDisconnect()
public XMLDocument passivateOpenVOs(boolean close)
public void activateOpenVOs(XMLDocument out)
public void fetchAttributeProperties(java.lang.String[] voNames, java.lang.String[][] attrs, 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 ServiceMessage sendServiceMessage(ServiceMessage svcMsgIn)
sendServiceMessage
in interface SvcMsgSender
protected void prepareForPassivation(Document out, Element parent)
out
- Document in which to create xml nodes.parent
- Element node under which this AM's data is being passivated.protected void prepareForActivation(Element amNode)
public java.lang.String getUserPrincipalName()
public byte[] getEntityAttributesPermission(java.lang.String entityName)
entityName
- the full name of the entity definition.public byte[] getViewAttributesPermission(ViewObject vo)
public void setRemoteAdapter(ApplicationModuleRemoteAdapter adapter)
public ServiceMessage doMessage(ServiceMessage msg)
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[] 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 java.lang.Object invokeMethod(java.lang.Object target, java.lang.String methodName, java.lang.String[] argTypeNames, java.lang.Object[] args)
invokeMethod
in interface WSApplicationModuleMarshaller
public ApplicationPoolSvcMsgContext doPoolMessage(ApplicationPoolSvcMsgContext ctx)
ApplicationModule
doPoolMessage
in interface ApplicationModule
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 syncMarshaller(ServiceMessage msg)
syncMarshaller
in interface WSApplicationModuleMarshaller
|
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.