|
Business Components | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
The interface for Application Modules. An Application Module is a logical container for coordinated objects related to a particular task with optional programming logic.
Root Application Module and Nested Application Module
An Application Module may be a root Application Module or a nested Application Module. A root Application Module is not contained in another Applicatin Module. It provides transaction context for all objects contained in it. It may optionally contain nested Application Modules. A root Application Module is created through JDNI calls. See below for details.
A nested Application Module is contained in another Application Module. The containing Application Module is referred to as the parent Application Module. If one traverses this containership ancestry, one will eventually find the root Application Module (which does not have a parent Application Module). A nested Application Module uses the transaction context provided by the root Application Module. Thus, data modifications performed in Application Modules parented by one root Application Module will commit or rollback together.
Transaction
Associated with the root Application Module is the Transaction
object, which provides this transaction context. From any (root or nested)
Application Module, the user can retrieve the transaction object through
a call to getTransaction(). In reality, getTransaction()
first locates the root Application Module and then returns the transaction
object from it.
The Transaction object manages connection to database
and Entity caches. Thus, changes made through one View Object are visible
to other View Objects as long as these View Objects all parented by the
one root Application Module. In contrast, if two View Objects are parented
by two separate root Application Modules, then changes made through the
View Object will not be seen by the second View Object until the changes
are committed to database through the first root Application Module and
the second VO executes query (to retrieve the most up-to-date data from
database).
Creating Application Module
A root Application Module is created by:
create() on the Application Module home.Here is a sample code to create a root Application Module:
java.util.Hashtable env = new java.util.Hashtable();
// Add environment entries into env...
javax.naming.Context ic = new InitialContext(env);
// 'defName' is the JNDI name for the Application Module
// definition from which the root Application Module is to
// be created
String defName = ...;
oracle.jbo.ApplicationModuleHome home = ic.lookup(defName);
oracle.jbo.ApplicationModule am = home.create();
One creates a nested Application Module by calling
createApplicationModule on the parent Application
Module.
Component Object
As metioned earlier, an Application Module may contain other nested Application Modules. In addition, it may contain View Objects and View Links. View Objects enable the user to set up queries to database and retrieve data through them. View Links enable the user to related two View Objects, such that events occuring on one of them (referred to as master) will cause the other View Object (referred to as detail) to refresh its result set based on master's data values. These objects that an Application Module may contain are referred to as Component Objects.
A Component Object may be included in an Application Module during
design time or be created in it during runtime. Component
Objects included during design time are referred to as static
Component Objects. Those that are created during runtime as
dynamic Component Objects. Dynamic Component Objects are
created through a call to a create... method.
Each Component Object (whether static or dynamic) is given a
name within the Application Module. This name can be used to
locate a Component Object. * find... methods are provided
for that purpose.
When using a find... method, the user may pass in
a relative or absolute Component Object name.
A relative name causes the Application Module to look for the Component
Object starting from this Application Module. An absolute name causes
the search to start from the root Application Module.
Application Module Custom Methods
The user may attach custom methods to an Application Module. BC4J
Design Time tools allows one to declare a method at the Application
Module interface level. The ApplicationModule interface
is extended to include declaration fo such a method. Then, the user
implements the method in the middle iter implementation class
(which extends oracle.jbo.server.ApplicationModuleImpl).
For the client tier, BC4J Design Time tools generate a client tier proxy for that
method (based on the user's choice of cli-tier-to-middle-tier interaction platform).
This enables the user to invoke the custom method in the client tier
(3 tier mode) or directly in the middle iter (2 tier mode).
For the middle tier, ApplicationModuleImpl.
is the base implementation of this interface.
The framework provides an ApplicationPool
interface that clients can use to manage and share a pool of Application
Modules.
Application Module Definition
Behind every instance of Application Module is a definition (or metaobject) that describes the Application Module. One can look at the Application Module definition as the factory for Application Module instance. Another way of looking at this is that the definition objects is akin to the Java class (in that the class describes instances and in that one uses the class to create instances).
An Application Module definition is identified by its full name. The definition's full name is qualified by the package in which the definition resides (just like a Java class).
In the middle tier, Application Module definitions are managed by
oracle.jbo.server.MetaObjectManager. One can find a
specific definition object by issuing:
String defName = ...;
oracle.jbo.server.ApplicationModuleDefImpl def;
def = oracle.jbo.server.ApplicationModuleDefImpl.findDefObject(defName);
where defName is a fully (package) qualified Application
Module definition name.
The user has the option of using the default Application Module definition or a custom Application Module definition. The default Application Module definition produces Application Module instances that do not have any custom methods or static Component Objects.
If the user wishes to include custom methods or static Component Objects,
he should define a custom Application Module definition in BC4J design time.
The default Application Module definition has a special definition name (see
DEFAULT_DEF_FULL_NAME below).
ApplicationModuleHome,
ViewObject,
ViewLink,
Transaction,
ApplicationPool,
ApplicationModuleImpl,
ApplicationModuleDefImpl,
MetaObjectManager| Field Summary |
| Type | Field |
|---|---|
static java.lang.String |
DEFAULT_DEF_FULL_NAME
The name of the default Application Module definition (one that represents oracle.jbo.server.ApplicationModuleDefImpl). |
static java.lang.String |
DEFAULT_ROOT_APP_MOD_NAME
The default name of root Application Module. |
static byte |
PASSIVATE_TO_DATABASE
Used by setStoreForPassivate to serialize the state of the Application Module's session and any cached changes to the database. |
static byte |
PASSIVATE_TO_FILE
Used by setStoreForPassivate to serialize the state of the Application Module's session and any cached changes to a file. |
static byte |
PASSIVATE_TO_MEMORY
Used by setStoreForPassivate to serialize the state of the Application Module's session and any cached changes to memory. |
static int |
SYNC_IMMEDIATE
SYNC_... constants are used to control how
often data changes in the client tier are flushed to
the middle tier cache. |
static int |
SYNC_LAZY
SYNC_... constants are used to control how
often data changes in the client tier are flushed to
the middle tier cache. |
| Method Summary |
| Type | Method |
|---|---|
byte[] |
activateState(int id,
boolean remove)
Internal: Applications should not use this method. |
void |
addWarning(JboWarning warn)
Adds a warning message. |
void |
clearVOCaches(java.lang.String entityName,
boolean recurse)
Clears the ViewObject cache for all View Objects that use an Entity Object identified by entityName. |
ApplicationModule |
createApplicationModule(java.lang.String amName,
java.lang.String defName)
Creates a nested Application Module in this Application Module from the Application Module definition. |
ComponentObject |
createComponentObject(java.lang.String coName,
java.lang.String coDefName)
Creates a Component Object in this Application Module from the Component Object definition. |
ViewLink |
createViewLink(java.lang.String vlName,
java.lang.String defName,
ViewObject master,
ViewObject detail)
Creates a View Link in this Application Module from the View Link definition. |
ViewLink |
createViewLinkBetweenViewObjects(java.lang.String vlName,
java.lang.String accessorName,
ViewObject master,
AttributeDef[] srcAttrs,
ViewObject detail,
AttributeDef[] destAttrs,
java.lang.String assocClause)
Creates a View Link in this Application Module. |
ViewLink |
createViewLinkFromEntityAssocName(java.lang.String vlName,
java.lang.String entityAssocName,
ViewObject master,
ViewObject detail)
Creates a View Link in this Application Module from an Entity Association. |
ViewObject |
createViewObject(java.lang.String voName,
java.lang.String defName)
Creates a View Object in this Application Module from the View Object definition. |
ViewObject |
createViewObjectFromQueryClauses(java.lang.String vuName,
java.lang.String eoName,
java.lang.String selectClause,
java.lang.String fromClause,
java.lang.String whereClause,
java.lang.String orderByClause)
Creates an View Object in this Application Module from an Entity Object and additional SQL clauses. |
ViewObject |
createViewObjectFromQueryStmt(java.lang.String vuName,
java.lang.String sqlStatement)
Creates a View Object in this Application Module based on a SQL statement. |
ApplicationModule |
findApplicationModule(java.lang.String amName)
Finds the named Application Module. |
ComponentObject |
findComponentObject(java.lang.String coName)
Finds the named Component Object. |
RowSetIterator |
findRSIForEntity(RowSetIterator[] rsis,
int eRowHandle)
Finds the RowSetIterator associated with the
specified Entity row handle. |
ViewLink |
findViewLink(java.lang.String vlName)
Finds the named View Link. |
ViewObject |
findViewObject(java.lang.String voName)
Finds the named View Object. |
ViewObject |
findViewObjectUsingEntity(ViewObject[] vos,
java.lang.String entityName,
java.lang.String[] attrName)
Given an array of View Objects (the vos parameter), finds the first matching View Object. |
java.lang.String[] |
getApplicationModuleNames()
Returns an array of names of the nested Application Modules that are contained within this Application Module. |
Session |
getSession()
Gets the Application Module's session. |
ClientDocument |
getStyles(java.lang.String name)
Gets the style definition from an XML file in the middle tier. |
java.lang.Object |
getSyncLock()
Gets the locking object for this Application Module. |
int |
getSyncMode()
Returns the sync mode for this Application Module. |
Transaction |
getTransaction()
Gets this Application Module's database transaction. |
java.lang.String[] |
getViewLinkNames()
Returns an array of the names of the View Links that are contained in this Application Module. |
java.lang.String[] |
getViewObjectNames()
Returns an array of names of the View Objects that are contained in this Application Module. |
boolean |
isRoot()
Returns true if this Application Module is a root Application Module. |
int |
passivateState(byte[] clientData)
Internal: Applications should not use this method. |
int |
passivateState(int id,
byte[] clientData)
Internal: Applications should not use this method. |
void |
removeState(int id)
Internal: Applications should not use this method. |
int |
reservePassivationId()
Internal: Applications should not use this method. |
void |
resetState(boolean reload)
Internal: Applications should not use this method. |
void |
setExceptionHandler(JboExceptionHandler hndlr)
Sets the exception handler for this Application Module. |
void |
setStoreForPassiveState(byte storageType)
Internal: Applications should not use this method. |
void |
setStyles(java.lang.String name,
ClientDocument clientDocument)
Saves a style definition XML file in the middle tier. |
void |
setSyncMode(int mode)
Sets the data synchronization mode between the client and the middle tier. |
void |
sync()
In 3 tier mode, this method enumerates through all Row Sets contained in this Application Module and flushes any changes pending in these Row Sets to the middle tier. |
| Methods inherited from interface oracle.jbo.ComponentObject |
getDefFullName, getDefName, getFullName, getName,
remove |
| Methods inherited from interface oracle.jbo.Properties |
getProperties, getProperty, refreshProperty |
| Field Detail |
public static final java.lang.String DEFAULT_ROOT_APP_MOD_NAME
public static final java.lang.String DEFAULT_DEF_FULL_NAME
oracle.jbo.server.ApplicationModuleDefImpl).
This definition object produces instances of
oracle.jbo.server.ApplicationModuleImpl, which
do not have any custom methods or static Component Objects.public static final int SYNC_LAZY
SYNC_... constants are used to control how
often data changes in the client tier are flushed to
the middle tier cache. As such, these constants only affect
3 tier mode and not 2 tier. In 2 tier mode, changes
are applied to cache immediately regardless of the sync
mode, i.e., the system effectively runs in the
SYNC_IMMEDIATE mode.
SYNC_LAZY means that attribute changes are kept in
the client tier until an operation forces changes
to be flushed. Examples of such operations are:
transaction commit, the currency movement (next(),
previous(), ...), etc.
getSyncMode(),
setSyncMode(int)
public static final int SYNC_IMMEDIATE
SYNC_... constants are used to control how
often data changes in the client tier are flushed to
the middle tier cache. As such, these constants only affect
3 tier mode and not 2 tier. In 2 tier mode, changes
are applied to cache immediately regardless of the sync
mode, i.e., the system effectively runs in the
SYNC_IMMEDIATE mode.
SYNC_IMMEDIATE means that attribute changes from
the client tier are applied (flushed) immediately to the middle tier.
to be flushed is issued. Examples of such operations are: if the
transaction is committed, if the currency moves (next(),
previous(), ...), if etc.
getSyncMode(),
setSyncMode(int)
public static final byte PASSIVATE_TO_DATABASE
setStoreForPassiveState(byte)public static final byte PASSIVATE_TO_FILE
setStoreForPassiveState(byte)public static final byte PASSIVATE_TO_MEMORY
setStoreForPassiveState(byte)| Method Detail |
public ApplicationModule createApplicationModule(java.lang.String amName,
java.lang.String defName)
defName parameter.
Example code:
ApplicationModule nestedAM = parentAM.createApplicationModule("MyAM", "package1.Package1Module");
amName - the name to be assigned to the Application Module.
If null, a system generated
name is assigned.defName - the name of the Application Module definition from which the new
nested Application Module is to be created. It must
be a fully qualified definition name (including
the package name).
If DEFAULT_DEF_FULL_NAME or null is passed,
a generic Application Module (one without custom
code or static Component Objects) is created.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. If it finds a match, it returns it. In this case, the name is said to be absolute.
For example, suppose we have the following containership of nested Application Modules:
Root (root Application Module)
ChildAM1
GrandChildAM1_1
GrandChildAM1_2
GreatGrandChildAM1_2_1
ChildAM2
GrandChildAM2_1
If one calls findApplicationModule("GrandChildAM1_2") on ChildAM1, it will find it from ChildAM1 and return it.
If one calls findApplicationModule("GrandChildAM1_2.GreatGrandChildAM1_2_1") on ChildAM1, it will find it from ChildAM1 and return it.
Both these are relative name cases.
If one calls findApplicationModule("Root.ChildAM2.GrandChildAM2_1") on ChildAM1, it will first try to find it from ChildAM1. This will fail because ChildAM1 does not have a nested Application Module named Root. After that, the search begins from the root Application Module. This will succeed because Root has a nested Application Module named ChildAM2 and ChildAM2 in turn has a nested nested Application Module named GrandChildAM2_1. This is an absolute name case.
For Application Module searching, findApplicationModule() makes no distinction between nested Application Modules included in other Application Modules during design time and those created programmatically during runtime.
Example code:
ApplicationModule nestedAM = parentAM.findApplicationModule("MyNestedAM");
amName - the name of the nested Application Module. It may be
a relative name or an absolute name. If null,
the root Application Module is returned.null if
the Application Module is not found.public java.lang.String[] getApplicationModuleNames()
Example code:
String[] nestedAMNames = parentAM.getApplicationModuleNames();
// If you want to retrieve all nested Application Modules
ApplicationModule[] nestedAMs = new ApplicationModule[nestedAMNames.length];
for (int i = 0; i < nestedAMNames.length; i++)
{
nestedAM[i] = parentAM.findApplicationModule(nestedAMNames[i]);
}
findApplicationModule(String)public void sync()
SYNC_IMMEDIATE,
no pending changes would be found, and sync() will
effectively be a no-op.
In 2 tier mode, this method is a no-op, as all changes are applied immediately.
public void setSyncMode(int mode)
SYNC_LAZY and SYNC_IMMEDIATE.
SYNC_LAZY is typically more efficient in that it causes fewer round trips to the middle tier.
mode - the new synchronization mode: SYNC_LAZY or
SYNC_IMMEDIATE.getSyncMode(),
SYNC_LAZY,
SYNC_IMMEDIATEpublic int getSyncMode()
setSyncMode(int mode),
SYNC_LAZY,
SYNC_IMMEDIATE
public ViewObject createViewObject(java.lang.String voName,
java.lang.String defName)
defName parameter.
Example code:
ViewObject vo = am.createViewObject("MyVO", "package1.DeptView");
voName - the name to be assigned to the View Object.
If null, a system generated
name is assigned.defName - the name of the View Object definition from which the new
View Object is to be created. It must
be a fully qualified name (including the package name).
public ViewObject createViewObjectFromQueryClauses(java.lang.String vuName,
java.lang.String eoName,
java.lang.String selectClause,
java.lang.String fromClause,
java.lang.String whereClause,
java.lang.String orderByClause)
For example, suppose we have an Entity Object named
Emp in a package named package1.
The following code block creates a View Object using
this method:
ViewObject vo = am.createViewObjectFromQueryClauses("MyVO",
"package1.Emp", // Fully qualified EO name
"E.ENAME as EmpName, E.EMPNO as EmpNo", // select clause
"EMP E", // from clause
"E.DEPTNO = 10", // where clause
null); // order by clause
Internally, this methods create a temporary View Object definition from the Entity Object and sets the select, from, where, and order-by clauses of the View Definition. Then, it uses that View Object definition to create the View Object.
voName - the name to be assigned the View Object.
If null, a system generated
name is assigned.eoName - the name of the Entity Object from which the
new View Object is to be derived.selectClause - a SQL statement SELECT clause.
The name or alias of each column must match
the name of the corresponding Entity Object's
attribute. In the above example code,
"ENAME" and "EMPNO" are database column names,
and "EmpName" and "EmpNo" are Entity Object's
attribute names.fromClause - a SQL statement FROM clause.whereClause - a SQL statement WHERE clause. If null
no where clause is established, i.e., all rows from
the database table/view are retrieved.orderByClause - a SQL statement ORDER-BY clause. If null
no order-by clause is established.
public ViewObject createViewObjectFromQueryStmt(java.lang.String vuName,
java.lang.String sqlStatement)
Example code:
ViewObject vo = am.createViewObjectFromQueryStmt("MyVO",
"SELECT EMP.ENAME as EmpName, EMP.MGR as EmpMgr FROM EMP");
In this example, the resulting View Object will have two attributes, named EmpName and EmpMgr.
Internally, this method create a temporary View Object definition with no Entity Object base and maps database columns to attribute definitions. Then, it uses that View Object definition to create the View Object.
voName - the name to be assigned the View Object.
If null, a system generated
name is assigned.sqlStatement - the SQL query statement for the View Object.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");
voName - the name of the View Object.null if the View Object
is not found.findApplicationModule(String),
findViewLink(String)public java.lang.String[] getViewObjectNames()
Example code:
String[] voNames = am.getViewObjectNames();
// If you want to retrieve all View Objects
ViewObject[] vos = new ViewObject[voNames.length];
for (int i = 0; i < voNames.length; i++)
{
vos[i] = am.findViewObject(voNames[i]);
}
findViewObject(String)
public ViewLink createViewLink(java.lang.String vlName,
java.lang.String defName,
ViewObject master,
ViewObject detail)
defName parameter.
master and detail identifies two
View Objects that will linked by this new View Link.
For example, assume that during design time, the user used the Design Time View Object Wizard to create two View Objects, DeptView and EmpView inside of a package named package1. Then, assume that the user invoked the View Link Wizard to create a View Link definition (in the same package) named DeptEmpViewLink, that correlates the DeptNo attribute of DeptView to the DeptNo attribute of EmpView.
Given these, the user can use the code block like the following to
create in this Application Module (represented by am)
two View Objects and a View Link programmatically (during runtime):
ViewObject voDept = am.createViewObject("MyDeptVO", "package1.DeptView");
ViewObject voEmp = am.createViewObject("MyEmpVO", "package1.EmpView");
ViewLink vl = am.createViewLink("MyDeptEmpLink", "package1.DeptEmpViewLink",
voDept, voEmp);
This will set up a master-detail relationship between voDept and voEmp. Whenever voDept's currency moves, voEmp's result set will be refreshed to show employees that work in the department.
This method verifies that the View Objects passed in match
the View Link definition. Specifically, in the above example,
createViewLink() checks to ensure that the master (voDept)
is an instance of package1.DeptView and that the detail
(voEmp) is an instance of package1.EmpView.
If match fails, an error (InvalidParamException) is reported,
as the user tried to set up a View Link between two View Objects where the View
Link definition does not match the View Link definitions of master and
detail.
One exception to this match rule is that createViewLink() allows the user to reverse the View Link direction. Thus, in the above example, the following would have succeeded:
ViewLink vl = am.createViewLink("MyEmpDeptLink", "package1.DeptEmpViewLink",
voEmp, voDept);
Note that in the above code block, voEmp is the master and voDept is the detail. The View Link definition is used in the reverse direction.
vlName - the name to be assigned to the View Link.
If null, a system generated
name is assigned.defName - the name of the link definition from which the new
View Link is to be created. It must
be a fully qualified name (including the package name).master - the View Object that is to play the role of master.detail - the View Object that is to play the role of detail.createViewObject(String, String)
public ViewLink createViewLinkFromEntityAssocName(java.lang.String vlName,
java.lang.String entityAssocName,
ViewObject master,
ViewObject detail)
For example, suppose we have two Entity Objects in package package1: Dept and Emp. An Entity Association DeptEmpAssoc is created between the two Entity Objects relating the Deptno attribute. Two View Objects are defined on these Entity Objects, DeptView and EmpView.
The following code creates two View Objects in this Application Module and link them, using DeptEmpAssoc:
ViewObject voDept = am.createViewObject("MyDeptVO", "package1.DeptView");
ViewObject voEmp = am.createViewObject("MyEmpVO", "package1.EmpView");
ViewLink vl = am.createViewLinkFromEntityAssocName("MyDeptEmpLink",
"package1.DeptEmpAssoc",
voDept, voEmp);
This will set up a master-detail relationship between voDept and voEmp. Whenever voDept's currency moves, voEmp's result set will be refreshed to show employees that work in the department.
Internally, this method creates a temporary View Link definition from the Entity Association and uses it to create the View Link.
This method verifies that the View Objects passed in match
the Entity Association definition. Specifically, in the above example,
createViewLinkFromEntityAssocName() checks to ensure that
the master (
The primary difference between
voDept) uses the Dept Entity Object
as one of its Entity bases and the detail (voEmp) uses the
Emp Entity Object as one of its Entity bases.
If match fails, an error (InvalidParamException) is reported,
as the user tried to set up a View Link between two View Objects where the
Entity Association is unable to relate the two View Objects.
createViewLink(String, String, ViewObject, ViewObject)
and
createViewLinkFromEntityAssocName is that the former requires
the View Link Definition name, and the latter requires the Entity
Association name.
vlName - the name to be assigned to the View Link.
If null, a system generated
name is assigned.entityAssocName - the name of the Entity Association from which the
new View Link is to be derived. It must
be a fully qualified name (including the package name).master - the View Object that is to play the role of master.detail - the View Object that is to play the role of detail.createViewObject(String, String)
public ViewLink createViewLinkBetweenViewObjects(java.lang.String vlName,
java.lang.String accessorName,
ViewObject master,
AttributeDef[] srcAttrs,
ViewObject detail,
AttributeDef[] destAttrs,
java.lang.String assocClause)
For example, suppose we have two Views Objects in package package1: DeptView and EmpView. Each of them has an attribute named Deptno.
The following code creates two View Objects in this Application Module and link them by the Deptno attribute:
ViewObject voDept = am.createViewObject("MyDeptVO", "package1.DeptView");
ViewObject voEmp = am.createViewObject("MyEmpVO", "package1.EmpView");
AttributeDef[] deptLinkAttrs = new AttributeDef[] { voDept.findAttributeDef("Deptno") };
AttributeDef[] empLinkAttrs = new AttributeDef[] { voEmp.findAttributeDef("Deptno") };
ViewLink vl = am.createViewLinkFromEntityAssocName("MyDeptEmpLink",
"Employees",
voDept, deptLinkAttrs,
voEmp, empLinkAttrs,
null);
This will set up a master-detail relationship between voDept and voEmp. Whenever voDept's currency moves, voEmp's result set will be refreshed to show employees that work in the department.
Using the Association Clause
This View Link will generate a SQL clause like EMP.DEPTNO=?
on voEmp. The Deptno value of the current row in voDept
(master) is bound into the bind variable ('?'). This results in limiting
query on voEmp to employees whose Deptno equals the current Dept's
Deptno.
By supplying a non-null association clause (the last parameter),
the user can override the default SQL clause and replace it with his.
For example, if he wishes to include only employees whose JOB is ANALYST, he
can supply the following assocClause:
EMP.DEPTNO=? AND EMP.JOB='ANALYST'.
Using the Accessor Name
If the user supplies a non-null accessorName (the second parameter), a
dynamic attribute is added to master View Object which allows
the user retrieve related rows from a master row.
In the above code example, a dynamic attribute "Employees" is added to voDept, such that if the user retrieve that attribute on a row the came from voDept, it will return a Row Set of Emp's that are related to that row.
The code example below retrieves all rows from voDept and for each Dept row, retrieves its employees by using the "Employees" attribute and prints their names.
Row deptRow;
while ((deptRow = voDept.next()) != null)
{
System.out.println("Dept: " + deptRow.getAttribute("Dname"));
RowSet emps = (RowSet) deptRow.getAttribute("Employees");
Row empRow;
while ((empRow = emps.next()) != null)
{
System.out.println(" Emp: " + empRow.getAttribute("Ename"));
}
}
vlName - the name to be assigned to the View Link.
If null, a system generated
name is assigned.accessorName - the name to be given to the dynamic attribute
to be added to master View Object.
Given a row from the master View Object, the
user can retrieve the attribute of this
name to get a Row Set of related rows from
the detail View Object. See the above discussions
for more info. If null, no dynamic
attribute is added.master - the View Object that is to play the role of master.srcAttrs - an array of attributes from master View Object to be
related to detail.detail - the View Object that is to play the role of detail.destAttrs - an array of attributes from detail View Object to be
related to master.assocClause - a custom association clause. See the above
discussions for more info. If null,
system generated SQL clause will be used.createViewObject(String,
String),
StructureDef.findAttributeDef(String),
RowIterator.next(),
AttributeList.getAttribute(String)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");
vlName - the name of the View Link.null if the View Link
is not found.findApplicationModule(String),
findViewObject(String)public java.lang.String[] getViewLinkNames()
Example code:
String[] vlNames = am.getViewLinkNames();
// If you want to retrieve all View Links
ViewLink[] vls = new ViewLink[vlNames.length];
for (int i = 0; i < vlNames.length; i++)
{
vls[i] = am.findViewLink(vlNames[i]);
}
findViewLink(String)
public ComponentObject createComponentObject(java.lang.String coName,
java.lang.String coDefName)
defName parameter.
Example code:
ComponentObject vo = am.createComponentObject("MyCO", "package1.MyComponentDef");
A Component Object is a generic object that an Application Module
can contain. A Comonent object is any object that implements the
ComponentObject interface. In particular,
ViewObject and ViewLink implement
the ComponentObject interface.
Thus, this method enables the user to build a custom ComponentObject and have it be managed by Application Module. Specificially, he must first implement a Java class that implements ComponentObject.
Then, as is the case with View Objects and View Links, he must build a Component Object definition (an XML file) reachable from the class path. (Note that for View Objects and View Links, BC4J design time provides tools to produce these definition files. For custom Component Object, the user must provide a custom tool to produce definition files or provide finished definition files himself.)
coName - the name to be assigned to the Component Object.
If null, a system generated
name is assigned.defName - the name of the Component Object definition from which the new
Component Object is to be created. It must
be a fully qualified name (including the package name).public ComponentObject findComponentObject(java.lang.String coName)
createComponentObject(String, String)
for explanation of BC4J's support for custom Component Objects.
See findViewObject(String) for explanation on AM-qualified
names and unqualified names.
coName - the name of the Component Object.null if the Component Object
is not found.findApplicationModule(String)public boolean isRoot()
public Transaction getTransaction()
If the user creates two root Application Modules, they normally do not share the transaction. To share a transaction acroos root Application Modules, the user would need to define a global transaction through JTA and have both Application Modules participate in it.
public Session getSession()
If the user creates two root Application Modules, each has its own session.
Note that this is the same session
that is passed to the ApplicationModuleImpl.activate(Session) call.
ApplicationModuleImpl.activate(Session)public java.lang.Object getSyncLock()
This locking object should be used to synchronize multiple calls into BC4J. The client application code rarely needs to worry about synchronization. It is the middle tier (the server) code that needs to synchronize calls into the middle tier to serialize updates to shared middle tier objects.
Here is an example of how to synchronize access using this method:
synchronized(am.getSyncLock())
{
// Code that needs to execute serially.
}
public void clearVOCaches(java.lang.String entityName,
boolean recurse)
entityName. This
method finds all View Objects that use the Entity, then calls
ViewObject.clearCache() on each View Object.
If entityName is null, then the caches of all View Objects in the Application Module are cleared. If recurse is true, it recurses into nested Application Modules.
entityName - fully qualified name of the Entity object.
If null all View Object caches
are cleared.recurse - a flag indicating whether to recurse into nested
Application Modules.
public RowSetIterator findRSIForEntity(RowSetIterator[] rsis,
int eRowHandle)
RowSetIterator associated with the
specified Entity row handle. This method is provided to handle
errors that occur during Entity post cycle.
If an error occurs while an Entity
is being posted to database, the system throws a
DMLException. Inside the DMLException
instance is an opaque handle (an integer) identifying the
Entity (an instance of EntityImpl)
that caused the error.
For example, the DMLException could have been thrown because the row violated a database constraint. The client might want to give the user a chance to correct the problem by displaying the the View Row that uses this Entity.
To do this, the client would "gather" all Row Set Iterators that can be used to report and fix the problem. It would then call this method, passing in the array of Row Set Iterators and the Entity row handle returned by DMLException.
Among the Row Set Iterator in the array, findRSIForEntity will pick the "best" candidate and return it to the client. The client then can use the Row Set Iterator to report the problem and give the user a chance to fix the problem.
rsis - an array of RowSetIterator's to look through.eRowHandle - the Entity row handle.RowSetIterator.DMLException,
RowSetIterator,
DMLException
public ViewObject findViewObjectUsingEntity(ViewObject[] vos,
java.lang.String entityName,
java.lang.String[] attrName)
vos - an array of possible View Objects.entityName - fully qualified name of the Entity object.
Should not be null.attrName - if empty, i.e., null or an array
of length 0, then the attribute matching
rule will be skipped (see the above discussion).
If not empty, it should have only one element
and that element should be the name of an
attribute of the Entity. The attribute matching
rule will apply. If a matching View Object is found,
attrName[0] upon return should have the name
of a View Object mapped to the Entity attribute.public void setExceptionHandler(JboExceptionHandler hndlr)
JboExceptionHandler
interface.
JboExceptionHandler handle exceptions (java.lang.Exception)
and warnings (JboWarning). In 2 tier mode,
the handler will only see warnings but no exception. In 2 tier mode,
Exceptions are thrown through the normal Java throw mechanism.
They should be handled through catch blocks.
For warnings, no throw/catch mechanism is available. The
handler must process them.
In 3 tier mode, the handler may have to process exceptions in addition to warnings. When a method call is marshalled from the client tier into the middle tier, the middle tier processing of the method may result in more than one exceptions. All these exceptions are caught by the marshalling code and brought back to the client tier. As Java's throw mechanism allows throwing of only one exception, these multiple exceptions cannot be processed through Java throw. Thus, for each of these exceptions, a call is made to handler's handleException(), so that the handler can process it.
hndlr - an exception handler.public void addWarning(JboWarning warn)
setExceptionHandler(JboExceptionHandler)).
This is done through a call to
JboExceptionHandler.handleWarning(JboWarning).
In 3 tier mode, the warnings that came to this Application Module
through calls to addWarning() in the middle tier are "chained"
until the middle tier processing completes. They are brought to
the client at the end of middle tier processing, and, for each
warning, a call is made to
JboExceptionHandler.handleWarning(JboWarning)
if an exception handler is present.
warn - warning message.public ClientDocument getStyles(java.lang.String name)
This method retrieves the content of an XML document specified by name and returns it as a ClientDocument. It locates the XML file through the following logic:
ClientDocument enables the user to manipulate an arbitrary
tree of an XML style document. Thus, the user can retrieve a
ClientDocument using this method and modify parts of the
tree and write it back out using setStyles(String, ClientDocument).
name - the XML file name.ClientDocument.ClientDocument
public void setStyles(java.lang.String name,
ClientDocument clientDocument)
This method saves the content of the document (the clientDocument parameter) in an XML file specified by name. It locates the XML file through the following logic:
ClientDocument enables the user to build an arbitrary tree of an XML style document. Thus, this method can be used to programmatically build and save an XML file.
name - the XML file name.clientDocument - the ClientDocument to be saved.ClientDocumentpublic int reservePassivationId()
Reserves a unique indentifier which may later be specified when passivating AM state as the identifier to be used for re-establishing AM state.
This method may be invoked to obtain a unique passivation identifier before passivation actually occurs. An example use case is an HTTP servlet that must encode all URLs with an Application Module's state identifier before that Application Module is passivated.
passivateState(int, byte[]).
public int passivateState(int id,
byte[] clientData)
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.
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 reservePassivationId().
For more information regarding passivation please see passivateState(byte[]).
id - a reserved passivation idclientData - cached changes, or any information that a client might
want to store.oracle.jbo.server.ApplicationModule#reservePassivationId()public int passivateState(byte[] clientData)
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.
This method always works from the top-level Application Module. If you have nested Application Modules and you call this method on a inner Application Module, it will still work from the top-level module.
In contrast to activateState(int, boolean), which deserializes
a session-state from the persistent store, calling
passivateState, does not affect the transaction state.
The cached changes, or clientData, can be any information that a client might want to store. For example, a JSP client could store the additional client-state information in this byte array so that when the JSP client becomes active and connects to an Application Module later, it could get its passivated state from the Application Module. This would reduce the amount of state information stored at the client side to a bare minimum (typically just an Application Module persistence ID).
A value of null for clientData indicates that the state will be stored, but there is no client data to be preserved.
This method preserves currency. When activateState(int, boolean) 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, false);
Row afterActivate = depts.getCurrentRow();
The values afterInsert and afterActivate should be the same.
clientData - cached changes, or any information that a client might
want to store.
public byte[] activateState(int id,
boolean remove)
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 this method is called, the rows that are updated are locked; new rows
are inserted into the transaction cache and posted. This is in contrast to
passivateState(byte[]), which does not affect the transaction state.
The activateState method preserves currency. When it is
called, it will return the row that was active when
passivateState(byte[]) was called.
For an example usage of activateState, see passivateState(byte[]).
The remove parameter gives you the option of removing the state or keeping it. A value of true will remove the session-state from the persistent store. If false is passed to the method, then the Application Module state remains in whatever persistence store was selected. It is up to the developer to devise a clean-up strategy for the redundant store.
id - a unique integer identifier associated with an instance of the
Application Module.remove - true to remove the session-state from the persistent
store.passivateState(byte[]) method.public void resetState(boolean reload)
Resets the non-transaction state of an application module. For example:
appModule.resetState(false);
reload - forces the application module to reload any child view usages,
application module usages, and view link usages.public void removeState(int id)
Removes the Application Module's session-state, and any cached change information, from the persistent store based on the given id. For example:
appModule.removeState(id);
id - an unique integer identifier associated with an instance of the
Application Module.public void setStoreForPassiveState(byte storageType)
Determines where the Application Module will store serialized versions of its session-state, plus any cached changes. This information can be stored to the database, to a file, or to memory, based on the value of the storageType parameter. The storageType can be set to:
PASSIVATE_TO_DATABASE (default target)PASSIVATE_TO_FILEPASSIVATE_TO_MEMORY
This method should be called before calling passivateState(byte[]).
Note that once an Application Module has serialized
its state, it cannot be asked to change its store. This method will throw
an JboException if this Application Module has already
stored its state earlier.
For example, the following code will set the storage to database, file, or memory, based on the value of the str parameter. Database is the default target:
String str =
oracle.jbo.common.JboEnvUtil.getProperty("jbo.test.passivateStateTo");
if (str != null)
{
if (str.equals("file"))
{
appModule.setStoreForPassiveState(ApplicationModule.PASSIVATE_TO_FILE);
}
else
if (str.equals("memory"))
{
appModule.setStoreForPassiveState(ApplicationModule.PASSIVATE_TO_MEMORY);
}
storageType - where the Application Module state is stored. Can be one
of PASSIVATE_TO_DATABASE (default target),
PASSIVATE_TO_FILE, or PASSIVATE_TO_MEMORY.JboException
- if this Application Module has already
stored its state earlier.passivateState(byte[])
|
Business Components | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||