ADF EMG XML Data Control, an open source initiative under the ADF Enterprise Methology Group (EMG) community, is an easy and declarative way to set up ADF Data Controls on XML files, services or payloads. Part 2 of this article by Oracle ACE Richard Olrichs and Oracle ACE Director Wilfred van der Deijl continues with a hands-on, step-by-step tutorial for creating and using XML Data Control.

By Richard Olrichs and Wilfred van der Deijl

Continued from Tutorial: Powerful and Easy ADF Data Control for XML Data - Part 1 [ARTICLE]

In the Create form, select Text and choose ADF Input Text w/ Label:
 

Figure 51

Then drop the comment attribute after the commissionPercentage on the page:
 
  Figure 52

Again in the Create form, select Text and choose ADF Input Text w/ Label.

6.9 Run the Department page

Right click anywhere in Department.jsf and choose Run:
 
  Figure 53

You will see the fullName attribute being added with the correct value, as well as the comment attribute with its initial/default value:

Figure 54

Notice that the fullName attribute is a read-only inputText, but that we did not configure this. The data control understands that this is a calculated field and not a transient field.

Now, let’s try to lower the salary of this employee from 4400 to 4000 and click Submit:
 
  Figure 55

Although there is no logic behind the Submit button, the attribute validation will be fired by the data control when there has been a submit on the page.

7 The Web Service Data Provider

So far, we have been working on a static resource. While this demonstrates the easy use and the power of XML Data Control, there are more ways to obtain the data. In the Developers Guide you can read about the different Data Providers. We’d like to give some special attention to the Web Service Data Provider, which is used to call a web service by configuring the data control in the Datacontrols.dcx, just as we have seen with the Resource Data Provider.

7.1 Available resources

We have taken the liberty of setting up a web service at the Google app engine. The first time you call it, it might take some time to respond, but after that the service should be up for the next hour until it idles out again.

The web service resources are:

7.2 Create a new XML Data Control

Open the JDeveloper New Gallery again. Under Business Tier, select Data Controls and then XML Data Control:
 
  Figure 56

The Create XML Data Control Form will appear. Enter the name HrWebService, add the data control to the same package as the previous one, and fill in the WebService data, as shown in Figure 57, below. Click OK:

Figure 57

The XML Data Control will show the following message again. Click OK:
 

Figure 58

Notice that the DataControls.dxc is extended with another AdapterDataControl node. This time, the data-provider class is set to the WSDataProvider and different parameters are preconfigured:

Figure 59

To find out about all the properties you can set, check the Web Service Data Provider in the Developers Guide.

7.3 Configure the WSDataProvider

This time, it might be nice to change the dc-operation from the default getXML to a more descriptive name, like “getDepartments.” In this example, we will set the endPointUrl to the endpoint of the web service, and we will supply a requestElement to the data provider.
  You can delete the other parameters and enter the following information under the parameters:

Figure 60

The endPointUrl parameter has been set.

The requestElement is a CDATA tag in which we provide the Request element as expected by the web service.

Refresh your Data Control Panel and you should have a new data control in place:
 
  Figure 61

Notice that the name of the method has changed.

7.4 Create a new page

Open the adfc-config file and again drag a view activity onto the page:
 

Figure 62

Name the view activity “DeptWS”:

  Figure 63

Double click the newly created activity to open the Create JSF Page dialog:
 
  Figure 64

Accept the defaults and click OK.

7.5 Create the Departments form

We will follow the same steps as before when creating the page on the static XML file. Open the Data Controls panel within the Application Navigator, then open the HrWebService Data Control with the ListAllDepartmentsResponse in it.

Drag and drop the Department element on the jsf:
 
  Figure 65

In the Create menu, select ADF Form:
 
  Figure 66

In Create Form, check the Read-Only Form box. Under Include Controls for, check Row Navigation, as shown in Figure 67, below. Click OK:

Figure 67

You’ll see the following JSF file:

Figure 68

7.6 Create another Data Control operation

To fetch the details of the employee by department, we need to call a different web service operation. We can, however, reuse the same AdapterDataControl and add a new definition node under it. This way, we create a new operation on the data control.

Open the DataControls.dcx file and under the previously created AdapterDataControl, copy and paste the definition node:
 
  Figure 69

Rename the following properties:
  schema-root to: DepartmentEmployeesResponse
  dc-operation to: getEmpsByDeptId
  requestElement to:
  <hr:DepartmentEmployeesRequest xmlns:hr="http://adfemg.org/HR">
  <hr:departmentId>#{param.deptId}</hr:departmentId>
  </hr:DepartmentEmployeesRequest>

Last, after the </xml-parameter> tag, add the following:
  <dynamic-parameter name="deptId" java-type="java.lang.Long"/>

The result will be this definition node:
 

Figure 70

The dynamic parameter is a declarative way to add parameters to the operation on the data control (for more information, read the chapter on dynamic parameters in the Developers Guide).

If you now refresh the Data Control panel, the HrWebService Data Control will have a second operation called getEmpsByDeptId, which will show the use of a Long parameter:
 

Figure 71

7.7 Create a detail table

This time, we will create a detail table instead of a form, to show all the Employee data in a table overview. Open DeptWS.jsf and drag and drop the Employee element under the DepartmentEmployeesResponse on the page:

Figure 72

In the Create menu, select Table/List View and choose ADF Table:
 
  Figure 73

In the Create Table pop-up, select Single Row. Check the Enable Sorting and Read-Only Table boxes. Then select the Job information and click the red X (for Delete), because we are not interested in that now. See Figure 74, below.

Finally, click OK:

Figure 74

Because the ADF Framework notices that there is a parameter involved, the Edit Action Binding pop-up will appear. To select a value, open the Expression Builder:
 
  Figure 75

In the Variables pop-up, open ADF Bindings, then bindings, then id, then inputValue. Click OK:
 
  Figure 76

You’ll see a page that looks like this:
 
  Figure 77

To make the table react when a new master row is selected, we need to add partial triggers to the page’s buttons. With the table selected, go to the Properties window, select Behavior and open the PartialTriggers menu:

Figure 78

Select Edit:
 
  Figure 79

In the Edit Property: PartialTriggers window, open the Form, panelForm and facet (footer). In the facet, select the 4 buttons and press the shuttle icon to the right:
 

Figure 80

With the four buttons now moved to the right-hand panel, click OK:
 

Figure 81

7.8 Run the page

Right click in the DeptWS page and select Run:
 
  Figure 82

When the page is started, both web services are being called and the result will be shown on the page:
 

Figure 83

If we navigate to the next row, we see the data in the detail table being updated to the current department. The id in the Department row is being used as dynamic parameter in our data control and thus in the request element to the web service:
 

Figure 84

8 Nesting Data Providers

In addition to to data providers that collect the data, we also have something called nesting data providers (sometimes referred to as “filters”). Five nesting data providers come with version 1.0 of XML Data Control.

We will provide an easy example of using the XSL Transformation Filter in this section to give you an idea of how the nesting data providers work.

8.1 Resources

You should have already set up your resources at the start of the tutorial. In this chapter we will use the following 2 files:

• HRflat.xsd: An XML Schema file that describes an employee with jobs information included in the Employee element instead of as a sub-element
• HRtoHRflat.xsl: An XSL transformation file that maps the data from the HR.xsd sub-element Jobs to the jobs attributes within the Employee in the HRflat.xsd

8.2 The HRflat.xsd

In JDeveloper, open the HRflat.xsd file:

  Figure 85

Notice the difference in the Employee node: the job information is no longer a sub-element, but the attributes are directly under the Employee element.

8.3 The HRtoHRflat.xsl

Open the HRtoHRflat.xsl file in JDeveloper:
 

Figure 86

Here we see how the Job information is taken out of the sub-element and transformed to the attributes under the Employee.

8.4 Edit the Data Control

Once again, open the DataControl.dcx file and find the definition node that gets the employee element with the dc-operation getEmpsByDeptId. We will start with editing the information in the definition node to the following properties:

Figure 87

The definition node must describe the result of the final data-provider or nesting data-provider; that is why we work on the HRflat.xsd with the schema root set to the DepartmentEmployeesFlat from within the HRflat.xsd file.

Next, we will create a data-provider wrapping the existing data-provider.

Edit the XML as indicated in Figure 88:

Figure 88

The data-provider implementation class points to the XSLTransformFilter in the package org.adfemg.datacontrol.xml.provider.filter.XSLTransformFilter. The XSLTransformFilter takes one parameter with the name “stylesheet,” pointing to the xslt to apply to the result of the nested data provider.

If we now refresh the Data Controls panel, you should see this:

Figure 89

8.5 Edit the page

Open DeptWS.jsf. Just to be safe, we will not rebind the existing table but will delete it and recreate it with the new data control.

In the Structure pane, select af:table. Right click the table and choose Delete:

Figure 90

When using the Structure pane to delete items on the page, JDeveloper will clear the bindings from your pageDefinition as well. If we go to the pageDefinition file, we can take a look at this.

Right click in DeptWS.jsf and select Go to Page Definition:
 
  Figure 91

In the pageDef file, notice how the bindings to the Employee are all gone, but the method action is still in place. Select the method action getEmpsByDeptId and click the Edit icon:

Figure 92

Notice that the method action including the parameters are still intact.

Go back to DeptWS.jsf and once again drop the Employee element from the HrWebService Data Control under the form:

Figure 93

In the Create menu, select Table/List View and choose ADF Table:
 

Figure 94

In the Create Table pop-up, select Single Row under Row Selection, and click the boxes for Enable Sorting and Read-Only Table, as shown in Figure 95, below. This time, we will leave both the and the Job information on there. Click OK:
 
  Figure 95

Notice that the pop-up for the parameter does not show this time, because the method Action is still available in the pageDef.

The result of the page looks like this:

Figure 96

Remember to add the PartialTriggers to the table:

Figure 97

Here’s the result:

Figure 98

8.6 Run the page

Again, right click in the DeptWS.jsf page and select Run:
 
  Figure 99

When the page loads, notice that the job information is shown in the table:

  Figure 100

9 Conclusion

In this tutorial you have learned how to use the ADF EMG XML Data Control. You learned how to create a form based on XML payload, whether it comes from a classpath resource or a web service. You have seen different data providers and learned how to use them in different scenarios.

Apart from creating ADF pages and fragments on the XML payload, you have also learned how to manipulate the in memory XML data, either through Java classes and annotations to customize the XML or throughan XSL transformation.

You have also seen the concept of nesting data providers and learned about the ability to implement a cache or other filter.

The benefits of using this open-source, free tooling is that it integrates easily with your existing JDeveloper IDE, it should be within the comfort zone of any ADF developer, and the ease of use should give your team a productivity boost when working with XML payload.

Next steps: read through the ADF EMG XML Data Control wiki in more detail, if you have not already, and start using the XML Data Control within your projects!

10 Resources

• Powerful and Easy ADF Data Control (Companion article to this tutorial)
• ADF EMG community
• XML Data Control wiki
• Using ADF Model in a Fusion Web Application
• Data Controls in Oracle ADF Fusion Web Applications

About the Authors

Oracle ACE Director Wilfred van der Deijl has been working with Oracle's development tools and database ever since getting his degree in Computer Science in 1995. An active member of the Oracle community, Wilfred is a blogger, author, Oracle customer advisory board member, and a frequent presenter at international conferences, including ODTUG and Oracle OpenWorld.

Oracle ACE Richard Olrichs is an Oracle Developer at MN, a technology company based in the Netherlands. Richard Olrichs has an extensive in Oracle Fusion Middleware with deep specialization in the Oracle Application Development Framework. Richard initiated an open source project creating an ADF EMG Audit Rules extension for both JDeveloper 11g and JDeveloper12c, and was also one of the initiators of ADF EMG XML DataControl, an open source project for both JDeveloper ADF 11g and JDeveloper ADF 12c. Richard is has spoken at Tech 13, Tech 14, and Oracle Open World 2014.

This article represents the expertise, findings, and opinion of the author. It has been published by Oracle in this space as part of a larger effort to encourage the exchange of such information within this Community, and to promote evaluation and commentary by peers. This article has not been reviewed by the relevant Oracle product team for compliance with Oracle's standards and practices, and its publication should not be interpreted as an endorsement by Oracle of the statements expressed therein.