This chapter helps you understand these view object concepts as illustrated in Figure 6-1:

• You can link a view object to one or more others to create master-detail hierarchies of any complexity.

• You can arrange parent-child view object instances in the context of an application module such that at runtime the detail view instance is actively coordinated with the current row of the master view instance.

• At design time, you can define a view link accessor that specifies an accessor attribute that the master collection uses at runtime to return the detail collection row set.

• You can programmatically access the detail collection row set using the view link accessor attribute that you specify for the master view object in the master-detail relationship.

• You can tune master-detail collection queries, by caching the row set of the detail view instance and support UI components, like the ADF Faces tree component, where data for each master node in a tree needs to retain its distinct set of detail rows.

• You can create row finder conditions using view criteria to locate specific rows within the master view object.

• You can define a self-referential master and detail hierarchy such that the source and destination view link attributes derive from a single table.

• You can define an inline view criteria to filter the row set of the master view object using attribute values specified by attributes of the detail view object.

Figure 6-1 A View Object Defines a Query and Produces a Row Set of Rows

Description of "Figure 6-1 A View Object Defines a Query and Produces a Row Set of Rows"

You may find it helpful to understand other Oracle ADF features before you start working with view objects. Following are links to other functionality that may be of interest.

• For details about using the interactive Oracle ADF Model Tester to validate view object query results, see Testing View Instance Queries.

• For details about creating a data model consisting of view object instances, see Implementing Business Services with Application Modules.

• For a quick reference to the most common code that you will typically write, use, and override in your custom view object classes, see Most Commonly Used ADF Business Components Methods.

• For API documentation related to the oracle.jbo package, see the following Javadoc reference document:

  • Java API Reference for Oracle ADF Model

1. In the Applications window, right-click the package node of the project in which you want to create the view object and choose New and then View Link.
2. In the Create View Link wizard, on the Name page, supply a package and a component name.

   For example, given the purpose of the view link, a name like DeptToEmpFkLink is a valid name to identify the link between a department list and its employees when the link is based on a foreign key.

3. On the View Objects page, in the Select Source Attribute tree expand the source view object in the desired package. In the Select Destination Attribute tree, expand the destination view object.

   For entity-based view objects, notice that in addition to the view object attributes, relevant associations also appear in the list.

4. Select the same association in both Source and Destination trees. Then click Add to add the association to the table below.

   For example, Figure 6-3 shows the same SEmpDeptIdFkAssoc association in both Source and Destination trees selected.

   Figure 6-3 Master and Detail Related by an Association Selection

   
   Description of "Figure 6-3 Master and Detail Related by an Association Selection"
5. Click Finish.

1. In the Applications window, right-click the package node of the project in which you want to create the view object and choose New and then View Link.
2. In the Create View Link wizard, on the Name page, enter a package name and a view link name. Click Next.

   For example, given the purpose of the view link, a name like OrdersPlacedBy is a valid name to identify the link between a customer list and their orders.

3. On the View Objects page, select a "source" attribute from the view object that will act as the master.

   For example, Figure 6-4 shows the Id attribute selected from the CustomerVO view object to perform this role. Click Next.

4. On the View Objects page, select a corresponding destination attribute from the view object that will act as the detail.

   For example, if you want the detail query to show orders that were placed by the currently selected customer, select the Id attribute in the OrdersVO to perform this role.

5. Click Add to add the matching attribute pair to the table of source and destination attribute pairs below. When you are finished defining master and detail link, click Next.

   Figure 6-4 shows just one (CustomerVO.Id, OrderVO.Id) pair. However, if you require multiple attribute pairs to define the link between master and detail, repeat the steps for the View Objects page to add additional source-target attribute pairs.

   Figure 6-4 Defining Source/Target Attribute Pairs While Creating a View Link

   
6. On the View Link Properties page, you can use the Accessor Name field to change the default name of the accessor that lets you programmatically access the destination view object.

   By default, the accessor name will match the name of the destination view object. For example, you might change the default accessor name OrdersVO1 to CustomerOrders to better describe the master-detail relationship that the accessor defines.

7. Also on the View Link Properties page, you control whether the view link represents a one-way relationship or a bidirectional one.

   By default, a view link is a one-way relationship that allows the current row of the source (master) to access a set of related rows in the destination (detail) view object. Leave the default settings unchanged for Generate Accessor when you want to enable support for hierarchical UI components, such as databound trees which require a view link accessor with accessor generated in the master view object.

   For example, in Figure 6-5, the checkbox settings indicate that you'll be able to access a detail collection of rows from OrdersVO for the current row in CustomerVO, but not vice versa. In this case, this behavior is specified by the checkbox setting in the Destination Accessor group box for OrdersVO (the Generate Accessor In View Object: CustomerVO box is selected) and checkbox setting in the Source Accessor group box for CustomerVO (the Generate Accessor In View Object: OrdersVO box is not selected).

   Figure 6-5 View Link Properties Control Name and Direction of Accessors

   
8. On the Edit Source Query page, preview the view link SQL predicate that will be used at runtime to access the master row in the source view object and click Next.
9. On the Edit Destination Query page, preview the view link SQL predicate that will be used at runtime to access the correlated detail rows from the destination view object for the current row in the source view object and click Next.
10. On the Application Module page, add the view link to the data model for the desired application module and click Finish.

    By default the view link will not be added to the application module's data model. Later you can add the view link to the data model using the overview editor for the application module.

When you create a view link or an association-based view link, JDeveloper creates the XML document file that represents its declarative settings and saves it in the directory that corresponds to the name of its package. For example, if the view link is named DeptToEmpFkLink and it appears in the views.links package, then the XML file created will be ./views/links/DeptToEmpFkLink.xml under the project's source path. This XML file contains the declarative information about the source and target attribute pairs you've specified and, in the case of an association-based view link, contains the declarative information about the association that relates the source and target view objects you've specified.

In addition to saving the view link component definition itself, JDeveloper also updates the XML definition of the source view object in the view link relationship to add information about the view link accessors that you may have defined. As a confirmation of this, you can select the source view object in the Applications window and inspect its details in the Structure window. As shown in Figure 6-6, you can see the default destination accessor EmpVOAccessor under the ViewLink Accessors node for the DeptVO source view object that accesses the destination EmpVO view object. This allows the source view object, using the view link accessor, to traverse the destination side of the view link. In addition to the view link accessor definition for the source view object, you can directly customize the view link to define a view link accessor on the destination view object, which provides access to row set of the source view object.

Figure 6-6 View Object with View Link Accessor in the Structure Window

1. In the Applications window, double-click the application module for which you define a new view instance.
2. In the overview editor, click the Data Model navigation tab.
3. In the Data Model page, expand the View Object Instances section and, in the Available View Objects list, select the detail view object node that is indented beneath the master view object.

   Note that the list shows the detail view object twice: once on its own, and once as a detail view object via the view link. For example, in Figure 6-7 you would select the detail view object EmpVO via DeptToEmpFkLink instead of the view object labeled as EmpVO (which, in this case, appears beneath the highlighted view object).

   Figure 6-7 Detail View Object Selection from Available View Objects

   
4. In the Name View Instance field below the Available View Objects list, enter a name for the detail instance you're about to create.

   For example, Figure 6-7 shows the name EmpDetailsVO for the instance of the EmpVO view object that is a detail view.

5. In the Data Model list, select the instance of the view object that you want to be the actively coordinating master.
6. Click Add Instance to add the detail instance to the currently selected master instance in the data model, with the name you've chosen.

   For example, in Figure 6-8, the Data Model list shows a master-detail hierarchy of view object instances with EmpDetailsVO as the detail view object.

Figure 6-8 Data Model with View Linked View Object

To work with view links effectively, you should also understand that view link accessor attributes return a RowSet object and that you can access a detail collection using the view link accessor programmatically.

View objects support two different styles of master-detail coordination:

• View link instances for data model master-detail coordination, as described in Enabling a Dynamic Detail Row Set with Active Master-Detail Coordination.

• View link accessor attributes for programmatically accessing detail row sets on demand, as described in Programmatically Accessing a Detail Row Set Using View Link Accessor Attributes.

• You can combine both styles, as described in What Happens At Runtime: When You Combine the Programmatic Access Using View LInk Accessors.

• Customers and PaymentOptions

• Orders and PaymentOptions

Figure 6-9 shows what the data model panel looks like when you've configured both Customers and Orders view object instances to be masters of the same PaymentOptions view object instance.

Figure 6-9 Multiple Master View Object Instances for the Same Detail

Description of "Figure 6-9 Multiple Master View Object Instances for the Same Detail"

To set up the data model as shown in Figure 6-9 you use the overview editor for the application module and use the Data Model page.

Before you begin:

It may be helpful to have an understanding of view objects. For more information, see About View Objects.

To create a view instance with multiple master view objects:

1. Add an instance of the first master view object to the data model.

   Assume you name it Customers.

2. Add an instance of the second master view object to the data model.

   Assume you name it Orders.

3. Select the first master view object instance in the Data Model list
4. In the Available View Objects list, select the detail view object indented beneath the first master view object and enter the view object instance name in the New Instance Name field. Click > to shuttle it into data model as a detail of the existing Customers view object instance.
5. Select the second master view object instance in the Data Model list
6. In the Available View Objects list, select the detail view object indented beneath the second master view object and the New Instance Name field, enter the same view object instance name as the previously entered detail view object. Click > to shuttle it into data model as a detail of the existing Orders view object instance.

   An alert will appear: An instance of a View Object with the name PaymentOptionsVO has already been used in the data model. Would you like to use the same instance?

7. Click Yes to confirm you want the detail view object instance to also be the detail of the second view object instance.

1. In the Applications window, double-click the association that you want to customize.
2. In the overview editor, click the Tuning navigation tab and then click the Edit accessors icon for the Custom View Objects section.
3. In the Custom Views dialog, select Use Custom View Object for the nonpersistent entity object.
4. In the Select View Object list, select the view object that you created based on the nonpersistent entity-object.
5. Click OK.

Row finders are objects that the application may use to locate specific rows within a row set using a view criteria. The row finder may be invoked on the master row set to match one or more criteria attributes supplied by the detail row set.

Currently, row finders that you define at design time can participate in these master-detail scenarios where non-row key attribute lookup is desired at runtime:

• When you expose the row finder in an ADF Business Components web service, the end user may initiate row updates on the specific rows of the master service view instance that match one or more row-finder mapped attribute values on the detail service view instance. For more information about this use case, see What You May Need to Know About View Criteria and Row Finder Usage.

• Programmatically, in the application, when you want to obtain a set of master view rows that match one or more row-finder mapped, non-key attribute values in the detail view instance. For more information about this use case, see Programmatically Invoking the Row Finder.

The view criteria attributes defined by the view criteria can be any attribute that the detail view object defines and specifically need not be a row key attribute. For example, in a master-detail relationship, where PersonVO is the master view object and AddressVO is the detail view object, the attribute EmailAddress will locate the person row that matches the email address of the person in the AddressVO row set.

To create a row finder to locate rows of the master view object using criteria attributes supplied by the detail view object, perform the following steps:

1. Define an inline view criteria on the master view object to reference the detail view object and specify the criteria attributes as a view criteria items defined by bind variables.

2. Define an updatable transient attribute on the master view object to receive the value of each criteria attribute. At runtime, the transient attribute may be set programmatically or exposed in a web service payload to allow an end user to supply the criteria attribute value (for example, an email address).

3. Define the row finder on the master view object by selecting the view criteria and setting each criteria attribute's bind variable to a corresponding transient attribute from the master view object.

In a recursive master-detail hierarchy, the attributes of the view object that you select for the source and destination in the view link will typically be the same pair of attributes that define the self-referential association between the underlying entity object, if this association exists. While this underlying association is not required to create the view link, it does simplify the creation of the view link, so you will first create a foreign key association for the base entity object of the view object.

To create the recursive master-detail hierarchy:

1. Create an self-referential view link using the base entity object of the view object.

2. Expose the view object with a view criteria that will filter the view instance's results to include only those rows you want to see at the "root" of the hierarchy.

When you create an self-referential view link, JDeveloper creates the XML document file that represents its declarative settings and saves it in the directory that corresponds to the name of its package. This XML file contains the declarative information about the source and target attribute pairs that the association you selected specifies and contains the declarative information about the association that relates the source and target view object you selected.

The following example shows the EmpManagerFkLink defines the same view object EmployeesView for the source and destination in its XML document file.

<ViewLink
  xmlns="http://xmlns.oracle.com/bc4j"
  Name="EmpManagerFkLink"
  EntityAssociation="test.model.EmpManagerFkAssoc">
  <ViewLinkDefEnd
    Name="EmployeesView1"
    Cardinality="1"
    Owner="test.model.EmployeesView"
    Source="true">
    <DesignTime>
      <Attr Name="_finderName" Value="ManagerIdEmployeesView"/>
      <Attr Name="_isUpdateable" Value="true"/>
    </DesignTime>
    <AttrArray Name="Attributes">
      <Item Value="test.model.EmployeesView.EmployeeId"/>
    </AttrArray>
  </ViewLinkDefEnd>
  <ViewLinkDefEnd
    Name="EmployeesView2"
    Cardinality="-1"
    Owner="test.model.EmployeesView">
    <DesignTime>
      <Attr Name="_finderName" Value="StaffList"/>
      <Attr Name="_isUpdateable" Value="true"/>
    </DesignTime>
    <AttrArray Name="Attributes">
      <Item Value="test.model.EmployeesView.ManagerId"/>
    </AttrArray>
  </ViewLinkDefEnd>
</ViewLink>

In addition to saving the view link component definition itself, JDeveloper also updates the XML definition of the view object to add information about the view link accessor you've defined. As a confirmation of this, you can select the view object in the Applications window and inspect its details in the Structure window. As shown in Figure 6-15, you can see the defined accessor under the ViewLink Accessors node for the EmployeesView view object of the EmpManagerFkLink view link.

Figure 6-15 View Object with View Link Accessor in the Structure Window

Description of "Figure 6-15 View Object with View Link Accessor in the Structure Window"