Forum Stats

  • 3,757,878 Users
  • 2,251,286 Discussions
  • 7,869,960 Comments

Discussions

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

Bob Rhubart-Oracle
Bob Rhubart-Oracle Member Posts: 692 Silver Badge
edited Jul 24, 2015 12:36PM in JDeveloper and ADF

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

  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:

image001.png

Figure 1

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

image002.jpg

Figure 2

Click Next.

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

image003.jpg

Figure 3

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

image004.jpg

Figure 4

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

image005.png
  Figure 5

Wait for JDeveloper to be restarted:

image006.png

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:

image007.png
  Figure 7

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

image008.jpg

Figure 8

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

image009.jpg

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:

image010.png

Figure 10

The files will now be available under the Application Sources:
  image011.png

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:

image012.jpg

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:

image013.jpg

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:

image007.png

Figure 14

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

image014.png

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.

image015.jpg

Figure 16

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

image016.png

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.

image017.jpg

Figure 18

Click the refresh button on the Data Control panel:

image018.png

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:

image019.jpg

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:

image020.jpg

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:

image021.jpg

Figure 22

Within the adfc-config file, drag and drop a View activity, as shown in Figure 23:

image022.jpg

Figure 23

As a name, enter "Department":
  image023.png
  Figure 24

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

image024.jpg

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):
  image025.jpg

Figure 26

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

image027.jpg

Figure 28

You'll then see this JSF file:

image028.png

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

Figure 30

In the Create menu, select ADF Form:

image026.png

Figure 31

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

Figure 32

You'll see Department.jsf, as shown below:
  image031.jpg

Figure 33

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

image032.png

Figure 34

5.4 Run the page

Right click within the Department.jsf and select Run:

image033.png

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:

image034.png

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

Figure 37

Enter the following properties:

  • Name: EmployeeCust
  • Package: org.example.firstdc.view.cust

Click OK:
  image036.jpg

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

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:

image038.jpg
  Figure 40

Paste it as target in the annotation:

image039.jpg

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:

image040.png

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

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

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:

image043.png

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:

image044.jpg

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:
  image045.png
  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:
  image046.jpg

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

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

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.


Comments

  • I am using JDev 12.1.3 but not able to find the extension,"ADF EMG Extension : XML Data Control" under check for updates in Open Source...

    I also checked the new gallery, Business Tier-->Data Controls to see if it was already installed earlier.

    But it is not present. Please let me know if I am missing anything.


    Thanks,

    Vishnu Gillella

  • 3433618
    3433618 Member Posts: 7

    I am using JDev 12.1.3 but not able to find the extension,"ADF EMG Extension : XML Data Control" under check for updates in Open Source...

    I also checked the new gallery, Business Tier-->Data Controls to see if it was already installed earlier.

    But it is not present. Please let me know if I am missing anything.


    Thanks,

    Vishnu Gillella

    Hi Vishnu,

    Any luck on this?I am looking for it for Jdeveloper 12.2.

    Regards,

    Rahul

  • Timo Hahn
    Timo Hahn Senior Principal Technical Consultant - Oracle ACE Director Member, Moderator Posts: 37,548 Red Diamond

    Hi Vishnu,

    Any luck on this?I am looking for it for Jdeveloper 12.2.

    Regards,

    Rahul

    You cna get the extension from https://adfxmldc.atlassian.net/wiki/display/XMLDC/ADF+XML+DataControl

    Check hte Download page for your verison.

    Timo


  • 3433618
    3433618 Member Posts: 7

    Hi Vishnu,

    Any luck on this?I am looking for it for Jdeveloper 12.2.

    Regards,

    Rahul

    Hi Timo,

    Thanks ,I was able to download.

    I had one more question before proceeding with this approach. My XML payload is stored in one of the columns of a database table.Is there a way it can be extracted directly as I could not see any database option under Data Provider.

    Regards,

    Rahul

  • dvohra21
    dvohra21 Member Posts: 14,227 Gold Crown

    Hi Timo,

    Thanks ,I was able to download.

    I had one more question before proceeding with this approach. My XML payload is stored in one of the columns of a database table.Is there a way it can be extracted directly as I could not see any database option under Data Provider.

    Regards,

    Rahul

    What is the column type in which the XML is stored?

  • 3433618
    3433618 Member Posts: 7

    Hi Timo,

    Thanks ,I was able to download.

    I had one more question before proceeding with this approach. My XML payload is stored in one of the columns of a database table.Is there a way it can be extracted directly as I could not see any database option under Data Provider.

    Regards,

    Rahul

    It is going to be Oracle Database ,so I was thinking of storing it in a CLOB type.

    If CLOB is not possible for this approach ,we can consider varchar as well as will will store only one record (failed) in one row for every failed message.

    Regards,

    Rahul

  • User_HWUPC
    User_HWUPC Member Posts: 2 Red Ribbon

    Hi Team,

    We are using XML DC everything is fine but its generating lot of errors in server logs. How to resolve below error logs,

     <Error> <oracle.adf.model.log.adapteddc.share.SharedDataControl> <BEA-000000> <No key attributes were found for the bean structure definition com.abc.view.ABC_Reprocess.getXML.message.>

    Thanks,

    Mahesh