oracle.jbo
Interface ApplicationModule

All Known Implementing Classes:

ApplicationModuleImpl

public interface ApplicationModule

extends ComponentObject

Defines containers for coordinated objects related to a particular task.

Since:

JDeveloper 3.0

Field Summary

static java.lang.String	DEFAULT_DEF_FULL_NAME The metadata defintion of the default Application Module.
static java.lang.String	DEFAULT_ROOT_APP_MOD_NAME The name of the default root Application Module.
static byte	PASSIVATE_TO_DATABASE
static byte	PASSIVATE_TO_FILE
static byte	PASSIVATE_TO_MEMORY
static int	SYNC_IMMEDIATE All operations on middle-tier objects are performed immediately.
static int	SYNC_LAZY Operations to be performed on middle-tier objects are batched until an operation forces middle-tier synchronization.

Method Summary

byte[]	activateState(int id, boolean remove) Internal: Applications should not use this method.
void	addWarning(JboWarning warn) Adds a warning message to the warning stack.
void	clearVOCaches(java.lang.String entityName, boolean recurse) Clears ViewObject cache for all VOs that use an entity object identified by entityName.
ApplicationModule	createApplicationModule(java.lang.String amName, java.lang.String defName) Creates and names an Application Module within this Application Module; that is, it creates a nested Application Module.
ComponentObject	createComponentObject(java.lang.String coName, java.lang.String coDefName) Creates a Component object in the context of this Application Module.
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 vuName, java.lang.String voName) Creates an updateable View Object from the name of a ViewObject metadata definition.
ViewObject	createViewObjectFromQueryClauses(java.lang.String vuName, 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 from an Entity Object and additional SQL clauses.
ViewObject	createViewObjectFromQueryStmt(java.lang.String vuName, java.lang.String sqlStatement) Creates a read-only View Object definition from a SQL statement.
ApplicationModule	findApplicationModule(java.lang.String amName) Finds an Application Module by name.
ComponentObject	findComponentObject(java.lang.String coName) Finds the component object from the Application Module.
RowSetIterator	findRSIForEntity(RowSetIterator[] rsis, int eRowHandle) Finds the RowSetIterator associated with the specified entity row handle.
ViewLink	findViewLink(java.lang.String viewLinkName) Returns the specified View Link from this Application Module.
ViewObject	findViewObject(java.lang.String voName) Gets the named View Object that was created at runtime in the Application Module or created with Design Time tools.
java.lang.String[]	getApplicationModuleNames() Returns an array of the Application Modules that are contained within this Application Module.
Session	getSession() Gets the Application Module's current session.
ClientDocument	getStyles(java.lang.String name) Gets the Application Module's style definitions from the middle tier.
int	getSyncMode() Returns the sync mode for this Application Module.
Transaction	getTransaction() Gets the Application Module's current database transaction.
java.lang.String[]	getViewLinkNames() Returns an array of the names of the View Links contained in this Application Module.
java.lang.String[]	getViewObjectNames() Returns an array of the names of the View Objects contained in this Application Module.
int	passivateState(byte[] clientData) Internal: Applications should not use this method.
void	removeState(int id) Internal: Applications should not use this method.
void	setExceptionHandler(JboExceptionHandler hndlr) Sets the exception handler for the Application Module.
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 syncronization mode between the client and the middle tier.
void	sync() Synchronizes all the result sets defined in this Application Module with the server.

Methods inherited from interface oracle.jbo.ComponentObject

getDefFullName, getDefName, getFullName, getName, remove

Methods inherited from interface oracle.jbo.Properties

getProperties, getProperty, refreshProperty

Field Detail

DEFAULT_ROOT_APP_MOD_NAME

public static final java.lang.String DEFAULT_ROOT_APP_MOD_NAME

The name of the default root Application Module.

DEFAULT_DEF_FULL_NAME

public static final java.lang.String DEFAULT_DEF_FULL_NAME

The metadata defintion of the default Application Module.

SYNC_LAZY

public static final int SYNC_LAZY

Operations to be performed on middle-tier objects are batched until an operation forces middle-tier synchronization.

SYNC_IMMEDIATE

public static final int SYNC_IMMEDIATE

All operations on middle-tier objects are performed immediately.

PASSIVATE_TO_DATABASE

public static final byte PASSIVATE_TO_DATABASE

PASSIVATE_TO_FILE

public static final byte PASSIVATE_TO_FILE

PASSIVATE_TO_MEMORY

public static final byte PASSIVATE_TO_MEMORY

Method Detail

createApplicationModule

public ApplicationModule createApplicationModule(java.lang.String amName,
                                                 java.lang.String defName)

Creates and names an Application Module within this Application Module; that is, it creates a nested Application Module. For example,

 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.

If DEFAULT_DEF_FULL_NAME is passed for defName, a generic Application Module is created.

Parameters:

amName - the name to be assigned to the Application Module. If null, a system generated name is assigned.

defName - the name of the definition from which the new Application Module is to be created.

Returns:

a new Application Module.

findApplicationModule

public ApplicationModule findApplicationModule(java.lang.String amName)

Finds an Application Module by name.

The Application Module found is a contained reference, within this Application Module, having the given name. This method assumes that the Application Module has already been created. The following example returns the Application Module KpiAM:

 oracle.jbo.ApplicationModule am = findApplicationModule("KpiAM");
 

Parameters:

amName - the name of the Application Module.

Returns:

the named Application Module.

getApplicationModuleNames

public java.lang.String[] getApplicationModuleNames()

Returns an array of the Application Modules that are contained within this Application Module. Called from the root Application Module, this method can be invoked to browse and access any Application Module in the system.

The following code sample returns an array containing the names of Application Modules defined in the Application Module appMod (that is, nested Application Modules):

 // Get the names of Application Modules defined in the Application Module.
    String[] amNames = appMod.getApplicationModuleNames();
 

Returns:

an array of Application Module names.

sync

public void sync()

Synchronizes all the result sets defined in this Application Module with the server.

Any changes in the result sets are uploaded to the server and the server updates are downloaded to the client.

setSyncMode

public void setSyncMode(int mode)

Sets the data syncronization mode between the client and the middle tier. There are two sync modes:

• SYNC_IMMEDIATE - All operations on middle-tier objects are performed immediately. For example, attribute values are sent to the middle tier as they are set.
• SYNC_LAZY - Operations to be performed on middle-tier objects are batched until an operation forces middle-tier synchronization. Examples of operation that force middle-tier synchronization are changes in currency, calls to an exported method, a request for a rollback or commit, etc.

SYNC_LAZY is typically more efficient in that it means fewer round trips to the middle tier.

Parameters:

mode - the new syncronization mode: SYNC_LAZY or SYNC_IMMEDIATE.

getSyncMode

public int getSyncMode()

Returns the sync mode for this Application Module.

Returns:

the sync mode: SYNC_LAZY or SYNC_IMMEDIATE.

See Also:

setSyncMode(int mode)

getViewObjectNames

public java.lang.String[] getViewObjectNames()

Returns an array of the names of the View Objects contained in this Application Module. Called from the root Application Module, this method can be invoked to browse and access any View Object in the system.

The following code sample returns an array containing the names of View Objects defined in the Application Module appMod:

 // Get the names of View Objects defined in the Application Module.
 String[] voNames = appMod.getViewObjectNames();
 

Returns:

the array of View Object names.

findViewObject

public ViewObject findViewObject(java.lang.String voName)

Gets the named View Object that was created at runtime in the Application Module or created with Design Time tools.

The following sample code locates and returns a named View Object within an Application Module. This lets the Application Module reuse the View Object. The code sample calls findViewObject and passes in the name of a View Object.

 // appMod is an Application Module defined at design time.
    ViewObject vo = appMod.findViewObject("MyEmpView");
 

Parameters:

voName - a View Object name.

Returns:

a View Object.

findComponentObject

public ComponentObject findComponentObject(java.lang.String coName)

Finds the component object from the Application Module. An Application Module typically contains View Objects, View Links, or another Application Module. This method will instead, return a generic component that has been included in the Application Module. A generic component is any object that implements the ComponentObject interface. This method allows for integration of other applications.

Parameters:

coName - name of the component object.

createViewObject

public ViewObject createViewObject(java.lang.String vuName,
                                   java.lang.String voName)

Creates an updateable View Object from the name of a ViewObject metadata definition.

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);
 

Parameters:

vuName - the name that will be given to the ViewObject. If null, a system-generated name is assigned.

voName - the name of the ViewObject metadata definition.

Returns:

a View Object.

createComponentObject

public ComponentObject createComponentObject(java.lang.String coName,
                                             java.lang.String coDefName)

Creates a Component object in the context of this Application Module.

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.

Parameters:

coName - name of the component object. If null, a name will be generated.

coDefName - name of the component Def (definition) object.

Returns:

a Component Object.

createViewObjectFromQueryClauses

public ViewObject createViewObjectFromQueryClauses(java.lang.String vuName,
                                                   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 from an Entity Object and additional SQL clauses.

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
 

Parameters:

vuName - 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 ORDERBY clause.

Returns:

a new View Object.

createViewObjectFromQueryStmt

public ViewObject createViewObjectFromQueryStmt(java.lang.String vuName,
                                                java.lang.String sqlStatement)

Creates a read-only View Object definition from a SQL statement. View Objects created using this method are read-only because there are no underlying Entity Objects.

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();}
 

Parameters:

qName - the name to be given to the View Object. If null, a name is generated.

query - the SQL query that defines the View Object.

Returns:

a new View Object.

getViewLinkNames

public java.lang.String[] getViewLinkNames()

Returns an array of the names of the View Links contained in this Application Module. Called from the root Application Module, this method can be invoked to browse and access any View Link in the system.

The following code sample returns an array containing the View Links defined in the Application Module appMod:

  // Get the View Links defined in the Application Module.
     String[] linkNames = appMod.getViewLinkNames();
 

Returns:

an array of View Link names.

findViewLink

public ViewLink findViewLink(java.lang.String viewLinkName)

Returns the specified View Link from this Application Module.

For example, in the following code sample, this method is used to return the first View Link defined in the Application Module appMod:

 // Get the first link defined in the Application Module.
 String[] linkNames = appMod.getViewLinkNames();
 if (linkNames.length < 1) {
     System.out.println("\n No links.");
     return;
 }
 ViewLink link = appMod.findViewLink(linkNames[0]);
 

Parameters:

viewLinkName - the name of a View Link.

Returns:

a ViewLink.

createViewLink

public 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. You can use this method to dynamically create View Links.

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.

Parameters:

viewLinkName - the name for the new View Link. If null, a system generated name is assigned.

viewLinkDefName - the name of the link definition that defines the link.

master - the View Object that is the source of the link.

detail - the View Object that is the destination of the link.

Returns:

a new ViewLink.

createViewLinkFromEntityAssocName

public 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.

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.

Parameters:

viewLinkName - the name for the new View Link. If null, a system generated name is assigned.

entityAssocName - the name of the entity association from which the link is derived.

master - the View Object that is the source of the link.

detail - the View Object that is the destination of the link.

Returns:

a new ViewLink.

createViewLinkBetweenViewObjects

public 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. This method creates the View Link by identifying which View Object attributes to relate to each other. This method also gives you the option of creating a View Link accessor and specifying a custom association clause.

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.

Parameters:

viewLinkName - the name for the new View Link. If null, a system generated name is assigned.

accessorName -

master - the View Object that is the source of the link.

srcAttrs - the attributes of master that comprise the source of the link.

detail - the View Object that is the destination of the link.

destAttrs - the attributes of detail that comprise the destination of the link.

Returns:

a new ViewLink.

findRSIForEntity

public RowSetIterator findRSIForEntity(RowSetIterator[] rsis,
                                       int eRowHandle)

Finds the 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 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.

Parameters:

rsis - an array of RowSetIterator's to look through.

eRowHandle - the entity row handle.

Returns:

the RowSetIterator.

See Also:

DMLException

clearVOCaches

public void clearVOCaches(java.lang.String entityName,
                          boolean recurse)

Clears ViewObject cache for all VOs that use an entity object identified by 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 (child) Application Modules.

Parameters:

entityName - name of the Entity Object that the View Objects use. Can be null.

entityName - fully qualified name of the entity object. If null all view object caches are cleared.

recurs - a flag indicating whether to recurse into children application module.

setExceptionHandler

public void setExceptionHandler(JboExceptionHandler hndlr)

Sets the exception handler for the Application Module.

The exception handler catches exceptions thrown by the middle tier in response to transactions generated by the Application Module.

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.

Parameters:

hndlr - an exception handler.

addWarning

public void addWarning(JboWarning warn)

Adds a warning message to the warning stack.

This stack is erased when the method call on the middle-tier returns to the client.

Parameters:

hndlr - an warning handler.

setStyles

public void setStyles(java.lang.String name,
                      ClientDocument clientDocument)

Saves the Application Module's style definitions to the middle tier.

Parameters:

name - a name under which the style definitions are to be stored.

clientDocument - the ClientDocument to be saved.

getStyles

public ClientDocument getStyles(java.lang.String name)

Gets the Application Module's style definitions from the middle tier.

Parameters:

name - a name under which the style definitions are stored.

getTransaction

public Transaction getTransaction()

Gets the Application Module's current database transaction. This method can be called from the client.

Returns:

a Transaction.

getSession

public Session getSession()

Gets the Application Module's current session. Whenever a client connects to a middle tier server, a session is created. Note, this is the same session that is passed in the ApplicationModuleImpl.activate(Session) call.

Returns:

a Session.

See Also:

ApplicationModuleImpl.activate(Session)

passivateState

public int passivateState(byte[] clientData)

Internal: Applications should not use this method.

Serializes the current state of this Application Module's session, along with all changes cached, to a persistent store and returns a unique identifier with which to re-establish the state.

activateState

public byte[] activateState(int id,
                            boolean remove)

Internal: Applications should not use this method.

Deserializes a session-state from the persistent store based on the given id.

Parameters:

id -

removeState

public void removeState(int id)

Internal: Applications should not use this method.

Removes a session-state from the persistent store based on the given id.

Parameters:

id -

setStoreForPassiveState

public void setStoreForPassiveState(byte storageType)

Internal: Applications should not use this method.

Sets the Application Module to use the file-system to store serialized snapshots of the Application Module. Note that once an Application Module has serialized it's state once, it cannot be asked to change its store. This method will throw a JboException if this Application Module has already stored it's state earlier.