Skip to Main Content

Java Development Tools


For appeals, questions and feedback, please email

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

Bob Rhubart-OracleJun 9 2015 — edited Jul 24 2015

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


  1. Introduction
  2. Setting up the Environment
  3. Creating the Application
  4. Set Up XML Data Control
  5. Create a View on the Data Control
  6. Manipulate the Data
  7. The Web Service Data Provider
  8. Nesting Data Providers
  9. Conclusion
  10. 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:

  1. HR.xsd: An XML Schema file that describes the traditional Oracle HR department
  2. HRdata.xml: An XML file with department 10, 20 & 30 from the traditional Oracle HR data
  3. HRflat.xsd: An XML Schema file that describes an Employee with jobs information included in the Employee element instead of as a sub-element
  4. 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:


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.

Post Details
Added on Jun 9 2015