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. This article by Oracle ACE Richard Olrichs and Oracle ACE Director Wilfred van der Deijl delivers a hands-on, step-by-step tutorial for creating and using XML Data Control.
By Wilfred van der Deijl and Richard Olrichs
Contents
- Introduction
- Setting up the Environment
- [Creating the Application](/#Creating_the_ Application)
- [Create a new application](/#Create_a_ new_application)
- [Set up the resources](/#Set_up_the_ resources)
- Set Up XML Data Control
- Create a View on the Data Control
- Manipulate the Data
- The Web Service Data Provider
- Nesting Data Providers
- Conclusion
- Resources
1 Introduction
In the more and more popular Service Oriented Architecture, websites and web applications are often based on services and no longer tightly coupled to a database. This has several advantages that the Oracle Application Development Framework (ADF) does not satisfactorily support.
Working with web services in an SOA environment usually involves working with XML. While there have been a few good ways to work with XML in ADF, there is now a new way that has a number of advantages.
The open-source ADF EMG XML Data Control initiative is an easy and declarative way to set up ADF Data Controls on XML files, services or payloads.
The technique for using XML Data Control is similar to that of the standard ADF web service data control, but with better support for complex types and the ability to customize the data control behavior at both design time and run time.This data control can be used in the same way as any other data control for dragging and dropping on pages.
This tutorial is based on JDeveloper 12c, but XML Data Control is also available on JDeveloper 11g Release 1. We suggest you get the latest and greatest version of JDeveloper (12.1.3 at the writing of this tutorial). However, if you are working with an earlier version of JDeveloper 12c, like 12.1.2, you should be able to follow this tutorial as well.
You can get JDeveloper 12.1.3 here.
2 Setting up the Environment
By default, JDeveloper does not include ADF EMG XML Data Control. This section describes what you need to do and how to configure JDeveloper to start using XML Data Control.
2.1 Prerequisites
We assume you have JDeveloper version 12.1.2 or 12.1.3 installed on your machine. If not, you can get it here.
2.2 XML Data Control
To get XML Data Control for Jdeveloper, go to the Help menu and select Check for Updates:

Figure 1
Uncheck the default checkboxes and click the Open Source and Partners Extensions checkbox:

Figure 2
Click Next.
Click the ADF EMG Extension : XML Data Control checkbox, then click Next, as shown in Figure 3:

Figure 3
After the installation downloads, you will see the New Installs:

Figure 4
Click Finish (Figure 4) and restart JDeveloper (Figure 5):

Figure 5
Wait for JDeveloper to be restarted:

Figure 6: Restarting JDeveloper
3 Creating the Application
3.1 Create a new application
We are going to create an ADF application in JDeveloper to work with XML Data Control.
In JDeveloper, click the New icon:

Figure 7
Select Applications and choose ADF Fusion Web Application, as shown in in Figure 8:

**Figure 8
**
Fill in the name, directory and default package for the application, as shown in Figure 9:

Figure 9
We'll leave all the other options to default, so just click Finish. <Q: Screen shows us clicking Next>
3.2 Set up the resources
To make following this tutorial easier, we have set up a few resources. From this XML Data Control wiki page, download the following resources:
- HR.xsd: An XML Schema file that describes the traditional Oracle HR department
- HRdata.xml: An XML file with department 10, 20 & 30 from the traditional Oracle HR data
- 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 subelement Jobs to the Jobs attributes within the Employee in the HRflat.xsd
Save these four resources under the \MyFirstDC\ViewController\src path.
4 Set Up XML Data Control
In this chapter you will set up XML Data Control on a static XML resource.
4.1 Refresh the application
Refresh the Application Navigator as demonstrated in Figure 10:

Figure 10
The files will now be available under the Application Sources:

Figure 11
4.2 The static XML file
The data control works with different data providers; you can read more about Data Providers in the Developers Guide on the XML Data Control wiki page.
The easiest provider to configure is the Resource Data Provider, which works on a static XML resource. We will start with configuring a data control on the static resource HRdata.xml.
Open the downloaded HRdata.xml resource:

Figure 12
Here you can see the data from the HR schema; we have Departments 10, 20, and 30, with their employees in it.
4.3 The XML Schema Definition
Open HR.xsd; the structure of the XML file is described therein:

Figure 13
The XSD is important for the data provider. We build the data control on design time, based on the provided XSD.
4.4 Create the XML Data Control
Open the New Gallery in JDeveloper:

Figure 14
Within the Business Tier category, select Data Controls. In the Items list, select XML Data Control and click OK:

Figure 15
You will now see a form to help you set up XML Data Control for the first time.
Enter the following properties:
- Name:
HRdataDC
- Package:
org.example.firstdc.view
- Runtime XML Schema:
HR.xsd
- Design time XML Schema: <leave blank>
- Schema Root:
DepartmentList
- Data Provider: Classpath Resource
We will leave the Design time XML Schema blank so that, at design time, the Runtime Schema will be used.
There is a list of Data Providers that are supported by XML Data Control. We will use the Classpath Resource to create a data control that uses the static XML file.

Figure 16
Click OK. JDeveloper will take some time to create the Data Control files. The following message should pop up when done:

Figure 17
4.5 An overview of the created files
Notice that JDeveloper has created the data control-related files, as well as opened the DataControls.dcx for you. If you open the Data Controls panel, it will be empty. You must manually refresh the Data Controls panel with the Refresh button.

Figure 18
Click the refresh button on the Data Control panel:

Figure 19
You can see the data control being refreshed. Under HRdataDC is a method with the default name getXML(). We see the SchemaRoot that we have entered as property and the department with its properties and elements under that.
Now go to the Source tab of the Datacontrols.dcx file:

Figure 20
Here you can find the properties filled in at the Create Form stage. You can change them later if you want to. The default dc-operation is filled with the name “getXML.” You can change this to something more meaningful, but for now we will leave it with the default.
Notice how the data control at design time works on the XSD file. There is no XML file available yet, but we do see the data control in the Data Control panel in JDeveloper.
Let's finish off by supplying the correct parameter in the resource element:

Figure 21
5 Create a View on the Data Control
We will use the created data control to create a simple view on Departments and Employees. It will be nothing fancy, but it will show how easy it is to create a page based on an XML payload.
5.1 Create the page
Open the adfc-config file:

Figure 22
Within the adfc-config
file, drag and drop a View activity, as shown in Figure 23:
**
**
Figure 23
As a name, enter "Department":

Figure 24
Double click the Department page. You'll see this Create JSF Page screen:

Figure 25
Accept the defaults and click OK.
JDeveloper will create the Department.jsf for you and open it in the Design mode.
5.2 Use the data control on the page
Open the Data Controls panel within the Applications navigator and open the DepartmentList response. Drag and drop the Department element onto the jsf (see Figure 26, below):

Figure 26
In the Create menu, select ADF Form:

Figure 27
When the Create Form screen appears, check Read-Only Form and Include Controls for Row Navigation, then click OK, as shown in figure 28, below:

Figure 28
You'll then see this JSF file:

Figure 29
5.3 Create a Detail Form
In the Data Controls panel, open the Employees element, then drag and drop the Employee under the created af:panelFormLayout in the Structure window:

Figure 30
In the Create menu, select ADF Form:

Figure 31
In the Create Form pop-up, check the Row Navigation and Submit checkboxes. Click OK:

Figure 32
You'll see Department.jsf, as shown below:

Figure 33
Check the Structure panel to make sure both the af:panelFormLayouts are within the af:form:

Figure 34
5.4 Run the page
Right click within the Department.jsf and select Run:

Figure 35
Wait for the Integrated WebLogic Server (WLS) to start and the page to load. The initial rendered page should look like this, showing Department 10 and Employee 200:

Figure 36
Navigate through the Departments and Employees.
This is all it takes to set up a straightforward page with XML Data Control.
6 Manipulate the Data
Now that we have created a simple page, we will take a look into one of the advantages of XML Data Control over standard ADF WebService Data Control:the option to manipulate data after it has been fetched. In this section, we will show you how to manipulate the data with the help of so-called “customizations.”
6.1 The annotation framework
Our customizations work through an annotation framework within XML Data Control. You can read more in the Developers Guide about customization in the Chapter Data Control Customizations.
For now, we will take you through 3 of the 8 customizations to show how the annotation and customization work.
6.2 Create the Java class
Once again, open the New Gallery in JDeveloper.
Under General, select Java and then choose Class, as shown in Figure 37:

Figure 37
Enter the following properties:
- Name:
EmployeeCust
- Package:
org.example.firstdc.view.cust
Click OK:

Figure 38
6.3 The ElementCustomization annotation
The Java class is a customization for one element in the data control—in this case, the Employee. On the class, we put an annotation called ElementCustomization
; the annotation takes one element (called "target"), to tell the Java class which element it is customizing:

Figure 39
The easiest way to find out the target is to copy and paste it from the PageDefinition
file. Open the DepartmentPageDef
. Find EmployeeIterator
and copy the BeanClass
:

Figure 40
Paste it as target in the annotation:

Figure 41
The BeanClass
that you need to copy as target is built according to the following structure:
<dc-package>.<dc-name>.<method-name>.<schemaroot>.<element>
6.4 A calculated attribute
To add a calculated attribute to the Employee element in the data control, we create a method in the Java class. We use the CalculatedAttr
annotation on the method to tell the annotation framework that we are creating a calculated attribute here:

Figure 42
The method signature is very important: the return type of the method determines the type of the attribute. The method name must be prefixed with "get"; the rest of the method name determines the name of the attribute, and the argument has to be of the type XMLDCElement
.
The XMLDCElement
is the internal representation of the in row that holds the data.
As you can see in Figure 41, above, you can use the input argument to collect information from the XML element. In this case, we are collecting the first name and the last name to present a combined full name.
The annotation framework works on compiled classes, so before the data control will pick up the annotation we need to build our Java class. Right click anywhere in the Java file and select Make:

Figure 43
6.5 Configure the data control
In version 1.0 of the data control, the annotation framework does not scan for the configured annotations (for reasons of performance). Therefore, we need to configure the Java class in the data control.
Open the Datacontrols.dcx
again:

Figure 44
Under the defined data-provider, we add a customization-provider, a special data provider for customization that has a different implementation class.
Under the customization-provider, add the list-parameter as shown in Figure 44, above.
When done, save your changes and move over to the Data Controls panel. Click the Refresh icon, as shown in Figure 45 below:
**
**
Figure 45
When you click Refresh, the data control should collapse. Reopen HRdataDC and navigate to the Employee element. Here we see the result of the attribute fullName being added to the data control:

Figure 46
Before we add the attribute to the page and check out the results at run time, we will first add two more annotations in our Java class.
6.6 A transient attribute
A transient attribute is a lot like a calculated attribute, but it has to be editable at run time. To add a transient attribute to your data control, we'll add another method to the Java class.
Open the EmployeeCust
again and add the following method:

Figure 47
Just as with the calculated attribute, we add an annotation to identify the kind of attribute we are adding, in this case TransientAttr
for a transient attribute. The method signature is very similar to the calculated attribute, except that the method name starts with "init" instead of "get".
The result of the init method will be used as default value for the attribute. Notice that the input argument is mandatory in the method signature, even if it is not used within the method.
Now, make or rebuild the Java class again and refresh the Data Control panel to see the comment attribute appear:

Figure 48
6.7 Attribute validation
The annotation framework supports both attribute and element validation. In this example, we will create an attribute validation.
We will implement a rule on the salary attribute within the Employee element; in our example, we will use the business rule that the salary attribute cannot be lowered.
Add the following method to the EmployeeCust
class:

Figure 49
The name of the annotation for an attribute validation is AttrValidation
. The method signature does not have a return type; if there is a violation, the method must throw an AttrValException
or an AttrSetValException
.
The prefix of the method name must be "validate" and the second part of the method name has to be an attribute within the target element. The input argument of the method is an AttrChangeEvent
, holding the old and the new value of the attribute.
The validation on an attribute is not shown on the data control at design time, so we need to run the page to see the validation in action.
6.8 Edit the Department page
Before we run the Department page, we want to add the newly created attributes on it. Open Department.jsf, open the Data Control panel and navigate to the Employee element, as shown in Figure 50.
Drag and drop the fullName attribute after the lastName attribute:

Figure 50
Continue to
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.