Tutorial: Powerful and Easy ADF Data Control for XML Data - Part 2 [ARTICLE]

Version 12

    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:
      image049.png

    Figure 51

     

    Then drop the comment attribute after the commissionPercentage on the page:
      image050.jpg
      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:
      image051.jpg
      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:

    image052.jpg

    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:
      image053.jpg
      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:

     

                                                                                                                          

    Endpoint URL:

    http://xmldc-sample.appspot.com/HumanResourcesService

    WSDL Location:

    http://xmldc-sample.appspot.com/HumanResourcesService.wsdl

    XML Schema Definition:

    http://xmldc-sample.appspot.com/HR.xsd

    Schema Root 1

    ListAllDepartmentsResponse

    Schema Root 2

    DepartmentEmployeesResponse

    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:
      image054.jpg
      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:

    image055.jpg

    Figure 57

     

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

    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:

    image056.jpg

    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:

    image057.jpg

    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:
      image058.jpg
      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:
      image059.jpg

    Figure 62

     

    Name the view activity “DeptWS”:

    image060.jpg
      Figure 63

     

    Double click the newly created activity to open the Create JSF Page dialog:
      image061.jpg
      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:
      image062.jpg
      Figure 65

     

    In the Create menu, select ADF Form:
      image026.png
      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:

    image063.jpg

    Figure 67

     

    You’ll see the following JSF file:

    image064.png

    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:
      image065.jpg
      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:
      image066.jpg

    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:
      image067.jpg

    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:

    image068.jpg

    Figure 72

     

    In the Create menu, select Table/List View and choose ADF Table:
      image069.png
      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:

    image070.png

    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:
      image071.jpg
      Figure 75

     

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

     

    You’ll see a page that looks like this:
      image073.jpg
      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:

    image074.jpg

    Figure 78

     

    Select Edit:
      image075.png
      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:
      image076.png

    Figure 80

     

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

    Figure 81

    7.8 Run the page

     

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

     

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

    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:
      image080.jpg

    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:

    image081.jpg
      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:
      image082.png

    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:

    image083.png

    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:

    image084.jpg

    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:

    image085.jpg

    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:

    image086.jpg

    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:
      image087.jpg
      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:

    image088.jpg

    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:

    image089.jpg

    Figure 93

     

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

    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:
      image090.jpg
      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:

    image091.jpg

    Figure 96

     

    Remember to add the PartialTriggers to the table:

    image092.jpg

    Figure 97

     

    Here’s the result:

    image093.jpg

    Figure 98

    8.6 Run the page

     

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

     

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

    image095.jpg
      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

     

     

    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.