Creating View Link Instances in Code

At design time, you can invoke the View Link Wizard from the Package node to define a View Link Definition (viewLinkDefName). At run time, you can use this design time information to instantiate a View Link. The key methods for creating a View Link are defined on the ApplicationModule interface:

You can use a given View Link Definition more than once within an Application Module; the Business Component framework uses View Link instance names to distinguish between them. For example, at runtime, you can use createViewLink to assign a View Link Name to a View Link Definition instance.

Whether created dynamically or from a design-time definition, a View Link persists until it, or the Application Module from which it was created, is explicitly deleted (using remove methods).

The View Link methods described in this section are also available from the DBTransaction interface to create View Links on the database transaction. These View Links are anonymous in that they do not have a name (that is, there is no viewLinkName parameter in their signature) and do not require an Application Module. These View Links are typically used for programming against an Entity Object and are removed when they are no longer needed. The fact that the View Link is unnamed prevents it from clashing with View Links created on the Application Module.

Creating View Links from a View Link Definition

Use createViewLink if your code can access the name of the View Link Definition that you want to use for creating the View Link.

For example, assume that during design time, you used the 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.

Creating View Links from an Entity Association

Use the createViewLinkFromEntityAssocName 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. This relationship is illustrated below:

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.

Creating View Links by Associating View Object Attributes

Use the createViewLinkBetweenViewObjects method if your code can access either a View Link Definition or an Entity Association. This method creates the View Link by telling the framework 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,
  voEmp, // detail
  empAttrs,
  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.