Tutorial: Powerful and Easy ADF Data Control for XML Data - Part 1 [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. 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 Tutorial: Powerful and Easy ADF Data Control - Part 2

     

    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.