Customizing an ADF Tree Binding

You can set an ADF hiearchical tree binding on this UI control that you insert from the Data Control Palette:

Tree

A tree binding lets users view a hierarchical list of attributes derived from master-detail relationships as specified by the business services in your Model project. You use the tree binding editor to define a set of rules that determine how the tree binding should traverse the relationships of the business service data collections you select.

In order for the tree binding to construct a tree with multiple branches, the business services should meet these requirements:

A starting or root data collection (for example, an ADF Business Components view object) that you will use as the control binding target.
One or more accessors (for example, an ADF Business Components viewlink) from that root collection and other data collections. The tree binding editor will display an allowable set of accessors for that node to drill down in to the next level.

Once you create the ADF binding for the tree control, you can use the tree control to let users navigate through the rows of the bound data collection. Currently, there is no navigation binding for the tree control, so you will need to add a JUTreeDefaultMouseListener on the control.

To set a tree binding:

Open the data panel in the Java Visual Editor and add a JScrollPane container to the panel.
In the top portion of the Data Control Palette, select the desired data collection to display.
From the Data Control Palette, add a Tree control to the scrollable pane.
From the Structure window, display the tree binding editor for the JTree control.

To define the root node of the tree:

In the tree binding editor, click the Edit Rule tab to define the parent node rule to display from the master data collection. For example, a master collection of "customers" has a detail collection of "orders".
In the Data Collection Definition list, select the data collection that you want to use to populate the tree root node. This is the master collection that defines the root node. For example, a customer's master collection that has an orders detail collection.
In the Display Attribute list, select a single attribute to display as the parent nodes for the tree. For example, the last name of each customer. Currently, the JTree control is limited to displaying a single attribute for each branch.
In the Branch Rule Accessor list, select the accessor that specifies the link between the master collection and the first branch in the tree. For example, a Business Components accessor for the customers and orders collections, might appear as OrdersView in the list.

Warning: If your data model does not contain master-detail accessors for the data collections you select, the Branch Rule Accessor list will appear empty. You must define an accessor for your business service in your Model project for all branches of the tree except the leaf (terminal) nodes.
Click the Add New Rule button to complete the rule definition for the root node.
Click the Show Rules tab to view the root node rule. For example, in the customers and orders example, it might appear as:

Viewobject rule: myPackage.CustomersView, CustLastName, OrdersView

This rule, based on ADF Business Components, defines: display the CustLastName attribute as the nodes for the root branch of the tree and use the OrdersView view link accessor to drilldown and display customer orders as the second branch in the tree. You must now add a rule to define the attributes to display from the orders view object.

To define the branches of the tree:

Click the Edit Rule tab to define the child-branch attributes rule to display from the first detail collection.
In the Data Collection Definition list, select the data collection you want to use to populate the tree's branch nodes. This is the detail collection that defines the nodes for the tree. For example, an orders detail collection from which you will display order id information in the tree.
In the Display Attribute list, select a single attribute to display as the branch nodes in the tree. For example, the last name of each customer.
In the Branch Rule Accessor list, select the accessor that specifies the link between the first branch data collection and the next branch in the tree. For example, a Business Components accessor for the orders and orderitems collections, might appear as OrderItemsView in the list.

Note: If the branch data collection you select has no further accessor defined for it in the business service Model project, the word <none> will appear in the list. This means no accessor is required because the selected collection's attribute will appear as leaf nodes in the tree.
Click Add New Rule to complete the rule definition for the child branch node.
Click Show Rules to view the root node rule. For example, in the customers and orders example, it might appear as:

Viewobject rule: myPackage.OrdersItemsView, OrderId, OrderStatus <none>

This rule, based on ADF Business Components, defines: display the OrderId and OrderStatus attributes as the nodes for the second branch of the tree. The word none means there is no accessor because this branch consists of leaf nodes.
You may repeat these steps in the Edit Rule tab to define new branches in the tree as long as your business services support accessors to traverse the branches.
Click OK to save the binding settings.

The binding editor performs error checking for the rules you defined. It displays the following error messages:
- "Invalid definition, either no root or no rules defined." Either you did not define a rule or you did not define a rule for the root node.
- "Defined root not found in this Application Module." The view object usage name defining the root node cannot be found in the application module defined in the form binding.
- "No rule found for accessor... ." There is no rule definition for every accessor in the rules table. Error checking does not verify that the number of polymorphic rules for a particular accessor; only that each accessor in the rules table has a rule definition.

JDeveloper adds the setModel() method in the jbInit() method to create the control binding. For example, after inserting a tree from the Data Control Palette, the method which references DataControlId to specify the meta-data, looks like this:

myTree.setModel((TreeModel)panelBinding.bindUIControl("DataControlId", myTree));

Meta-data for the new binding appears in the binding definition file (UIModel.xml):




<DCControl

         id="MyDataControl"

         DefClass="oracle.jbo.uicli.jui.JUTreeDef"

         SubType="DCTree"
         BindClass="oracle.jbo.uicli.jui.JUTreeBinding"

         IterBinding="DataCollectionIteratorId"

         ApplyValidation="false"

         ScrollPaneClass="javax.swing.JScrollPane"

         ShowsRootHandles="false" >

         <AttrNames>

            <Item Value="OrderId" />

            <Item Value="OrderDate" />

            <Item Value="OrderMode" />

            <Item Value="CustomerId" />

            <Item Value="OrderStatus" />

            <Item Value="OrderTotal" />

            <Item Value="SalesRepId" />

            <Item Value="PromotionId" />

         </AttrNames>

         <JUCtrlHierTypeBinding

            DefClass="oracle.jbo.uicli.binding.JUCtrlHierTypeBinding"

            SubType="DCTree"

            ApplyValidation="false"

            DefName="model.OrdersView" >

            <Contents >

               <Accessors>

                  <Item Value="MyAccessor" />

               </Accessors>

            </Contents>

            <AttrNames>

               <Item Value="MySelectedAttribute" />

            </AttrNames>

         </JUCtrlHierTypeBinding>

         <JUCtrlHierTypeBinding

            DefClass="oracle.jbo.uicli.binding.JUCtrlHierTypeBinding"

            SubType="DCTree"

            ApplyValidation="false"

            DefName="model.MyDataCollection" >

            <Contents >

               <Accessors>

               </Accessors>

            </Contents>

            <AttrNames>

               <Item Value="MySelectedAttribute" />

            </AttrNames>

         </JUCtrlHierTypeBinding>

      </DCControl>

To add images to display in the tree binding editor:

The tree binding editor lets you choose icons to display for each node in a branch and the open and close icon for each branch. In order to add the icons to the tree binding editor, you must add initialized images to your variable declarations. For example:

 



  ImageIcon deptImage = new ImageIcon(); 

  ImageIcon deptOpenImage = new ImageIcon(); 

  ImageIcon deptClosedImage = new ImageIcon(); 

  ImageIcon empImage = new ImageIcon(); 

  ImageIcon empOpenImage = new ImageIcon(); 

  ImageIcon empClosedImage = new ImageIcon();

The images must be initialized, if you have uninitialized images, edit the parameter list and then open the tree binding editor, you will loose your edits. When an image is uninitialized, Swing runtime will throw a NullPointerException when attempting to draw the node to display a node that should display the null image.