Powerful and Easy ADF Data Control for XML Data [ARTICLE]

Version 6

    ADF EMG XML Data Control, an open source initiative by the Enterprise Methology Group, provides an easy and declarative way to set up ADF Data Controls on XML files, services or payloads. Richrard Olrichs and Wilfred van der Deijl explain its history and use.


     

    By Richard Olrichs and Wilfred van der Deijl

     

    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. Traditionally, there have been a few good ways to work with XML in ADF; these are described in the “Alternatives” section (below). However, there is now a new way of handling XML within ADF, an open source initiative by the Enterprise Methology Group (EMG) community called “ADF EMG XML Data Control.” It’s 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.

     

    Brief History

     

    The development of the product has not been done overnight. We’d like to take a moment and explain the history of XML Data Control, because we believe it is part of the maturity of this product. Development started in 2012 on a SOA project in which the use case asked us to think of a custom ADF worklist instead of the default BPM worklist from Oracle. To create custom ADF tasks for within the worklist smoothly and easily, we wanted an easy way to handle the XML payloads of the business process management (BPM) tasks in ADF. To think of ways to do this, we looked at the already available abstraction layers in ADF:

    olrichs-adf-control-fig01.gif

    Figure 1: Abstraction Layers in ADF

     

    By default, a page (fragment) in ADF works through the ADF binding layer. The binding layer provides a consistent interface to the data regardless of where it comes from. The ADF Data Control again provides a consistent interface, abstracting the implementation technology from the business service and describing the service’s operations and data collections.

     

    Our goal was to create a new way of handling XML in ADF, but staying close to the default ADF framework and thus the comfort zone of the ADF developer. Creating a custom ADF Data Control seemed the way to go, because building a page (fragment) would be all the same, once the Data Control was in place at design time.

     

    In the early months of 2014, a second, large company in the Netherlands was facing the same issue as we had before in 2012 with our previous client. The Data Control used at that time was a very 0.1 like version. It had the ability to fetch XML data from a payload element, a web service or a static resource, but it did not have all the desirable data manipulation requirements. We came up with an idea to let the companies join forces in creating more functionality within this ADF Data Control, which finally led to the initiative to create   an open source product under the ADF EMG community.

     

    Version 1.0 was released at Oracle Open World in September 2014. Since then, several other companies have been involved in a proof of concept and/or are implementing ADF EMG XML Data Control in their production code.

     

    Alternatives

     

    Before we go on to describe the functionality of XML Data Control and how this product can be used, it might be wise to look at the alternatives. Why is there a need for a new product? How are ADF developers currently working with XML within ADF? And why would we want to change that?

     

    For using XML in ADF, or more specifically calling web services from ADF, there are three current methods:

     

    1. Default ADF Web Service Data Control, provided by Oracle and shipped with the product
    2. Programmatic ADF Business Components
    3. Creating Bean Data Controls on your custom Plain Old Java Objects (POJO) model

     

    ADF Web Service Data Control

    In ADF there is an ADF Web Service Data Control for calling web services. This is a standard ADF feature/component that in a declarative way can call simple web services (e.g., stock and weather reports, etc). However, this is less practical for calling more complex web services, it is not great in dealing with complex payloads, and it does not allow you to manipulate the data after calling the web services.

     

    For more details, see Frank Nimphius’ article in Oracle Magazine (July/August 2012): “SOAP-based Web services and Oracle ADF can be integrated in several different ways. Oracle ADF’s Web Service Data Control feature is easiest to configure at design time, but it does not provide much control of a service’s runtime behavior, nor of the exchanged data. Thus, using Web Service Data Control is best for simple interactions only.”

     

    We were gunning for the same declarative working and easy set up as ADF Web Service Data Control has. However, we required the easy manipulation of data and the ability to handle complex payloads that come from our BPM tasks or web services.

     

    Programmatic Business Components

    Programmatic Business Components (ADF BC) is a good option for applications that already use ADF BC, to benefit from developer knowledge and such BC features as master-detail relations and model-driven list of values (LOVs).

     

    This solution uses the standard Java-API (JAX-WS) supported in JDeveloper to generate proxy classes based on the WSDL location. Oracle recommends using the pattern of a Java Bean wrapper around these proxy classes, which creates a stable API for ADF BC to communicate with and decouple the ADF BC layer from the web service.

     

    This option seems less obvious when the project does not already use ADF BC because you’ll be forced to introduce ADF BC in your project, while you actually want to work with ADF on a web service. It forces the developer to keep in mind ADF BC-specific subjects, such as application module pooling, passivating/activating and more. Further, Entity and View Objects must be manually created based on the result set of the proxy service generated by JDeveloper. Keep in mind that a web service is usually not specific for one client, which may result in unwanted result sets. Further, the necessary ADF BC Framework (Java) code   can become very complex and hard to maintain. ADF BC is built for a database-driven model layer, and re-implementing all of these database features in a web service environment can be a challenge—or simply impossible. Things like commit, rollback to savepoint, row locking, database cursor handling, and entity fault-in selects make it very hard to implement all ADF BC features in a non-database environment. Most of the time, you end up with a limited implementation, and a developer needs to know which methods of all ADF BC classes can be invoked and which will fail.

     

    POJO bean data control

    A different alternative to the ADF Web Service Data Control is a POJO Bean Data Control. This is a data control based on a POJO model. As with the Programmatic Business Components, this uses the proxy classes generated by JDeveloper based on a WSDL location. This method seems to be the current de facto standard within ADF. JDeveloper supports the creation of out-of-the-box proxy services based on the web services, and a lot of ADF developers are already comfortable with creating Bean Data Controls on an MBean in ADF.

     

    The developer needs to create mapper classes to map the data from the proxy service to the POJO objects and back. This does not require extensive knowledge of Java or ADF and is relatively simple. However, since these mapper classes are strongly tied to the implementation in the proxy classes, the developer needs to redo a lot of work (if not all of it) when the service changes the interface, namespace or structure.

     

    Although the Java code is not necessary complex, there is still a need to write Java, meaning there is a possibility of developers making mistakes. Code tends to have bugs; the more code we write, the harder the application gets to maintain.

     

    XML Data Control Functionalities

     

    Now it is time to go into the functionality offered by the XML Data Control. We will talk about setting up the Data Control and getting the data on run time. After that, we will describe two different ways of data manipulation and end with a short overview of other functionalities offered by this extension.

     

    Set up the data control (design time)

    The JDeveloper extension you need to start with XML Data Control is available through the Help menu (check for update). Make sure you select the open source project. You should see the XML Data Control extension is available, as demonstrated by Figure 2:

    olrichs-adf-control-fig02.gif

    Figure 2:  ADF EMG Extenstion: XML Data Control

     

    Once the extension is installed in the New Gallery from JDeveloper, there is a new option: XML Data Control. A wizard will get you started. To create the structure of a data control in the Data Control palette, we need to provide the structure of the data we are going to work with. Luckily, in XML there is a very good standard tool called XML Schema Definition (XSD) to do this.

     

    The end user must provide an XSD location that we can reach at design time (in JDeveloper) and runtime (from the application). This could be a simple URL, Metadata Services (MDS) location, classpath resource, etc. Based on the information we gather at design time, we build our data control structure in JDeveloper, which is shown in the Data Control palette.

    olrichs-adf-control-fig03.gif

    Figure 3: Set Up the Data Control (run time)

     

    Depending on the kind of data provider (more details later) that suits your needs, you can use a variety of parameters to set up your ADF Data Control for run time. The easiest data provider is the resource data provider that gets the run-time information from a static resource. Simply tell the data provider where on the classpath it can find the static resource, and the data will be displayed on screen:

    olrichs-adf-control-fig04.gif

    Figure 4: Locating the Static Resource

     

    If you want to call a web service, there is a special web service data provider. This data provider takes a few more parameters, like the endpoint url and the request element. The key to setting up the run-time side of the data control is to tell the data provider where the data comes from and how to access it.

     

    Data manipulation through customization

    You might need to manipulate the data that has been fetched from the data provider. Inspired by the ViewRowImpl functionality from ADF BC, we created an annotation framework to manipulate XML Data Control (see the XML Data Control wiki page for detailed descriptions of the annotations). To demonstrate the functionality of this framework, we’ll walk you through an example class.

     

    Just as in the ViewRowImpl, you create a Java class to code the functionality of the data manipulation. This Java class is bound to an element in XML Data Control. In the example below, the Java class is to manipulate an Employee element. With the help of an annotation on the Java class, you inform the customization which data collection you want to customize. With the help of annotations above the different method signatures, you inform the Data Control of the manipulations you want to do.

    olrichs-adf-control-fig05.gif

    Figure 5: Data Control Manipulations

     

    Setting up this Customization Class and refreshing your Data Control panel will result in a new data control structure. We think working with customization will be close to the comfort zone of ADF developers used to manipulating a row in the ADF BC framework.

     

    An additional advantage of this manipulation is that it happens on the model side and thus eliminates the use of JSF MBeans for this.

    olrichs-adf-control-fig06.gif

    Figure 6: Data Control Attributes

     

    At the moment, we support 7 annotations. Find out what they do and how to use them on the XML Data Control wiki pagehttps://adfxmldc.atlassian.net/wiki/display/XMLDC/Data+Control+Customizations about annotations.

     

    Data Manipulation through transformation

    Data manipulation through customizations can be very powerful; in the SOA environment, however, and working with XML data, developers are often used to working with XSL transformations to manipulate XML data. Working with transformations can have several advantages over creating a Java Class (e.g., transformations are very powerful in manipulating collections).

     

    This is exactly the reason why we’ve build in support for XSL transformations within XML Data Control. This is achieved with the help of a special data provider that can be nested. Nesting data providers get their XML from the nested provider and can manipulate it before returning it to the caller.

    olrichs-adf-control-fig07.gif

    Figure 7: Nesting Data Providers

     

    As demonstrated in Figure 7, above, we nest the resource data provider with an XSL Transform Filter. This data provider also takes one parameter, which is the actual stylesheet. This stylesheet will be applied to the returned XML data from the resource data provider. Read the section on the wiki about XSL transformations to learn more.

     

    Data providers

    As you have seen, the data providers play an very important role in XML Data Control. They are responsible for fetching the XML element at runtime, as well as mapping the data from XML to Java types. There are several data providers to help you fetch data from different locations (we have seen the resource data provider and the web service data provider already). Besides these, there are also out-of-the-box data providers to get XML data through expression language or to provide an empty element, typically for the create functionality on screens.

     

    Nesting data providers

    Besides the data providers that get your data, there are also data providers that can nest another data provider. We have seen the XSL transformation as an example, but there are a few more. There is a nesting data provider to apply XML Schema Validation, to support caching the resultset in various scopes, and to combine multiple results from different data providers into one.

     

    Build your own

    We think XML Data Control delivers a lot of functionality out of the box. However, there might be a specific use case in which you need a new sort of data provider. In this case, you can try to convince us of the need for this data provider and wait for it, or build your own. Our whole XML Data Control is an open source initiative, but it is also a very pluggable framework. You could extend any part of the XML Data Control and plug in your own functionality.

     

    Read more about (nesting) data providers and extending this framework on thewiki

     

    Advantages of XML Data Control

     

    We have shown how to set up and use XML Data Control and we have discussed the alternatives. It might be nice to sum up the advantages that we see from working with XML Data Control above the alternatives:

     

    • XML Data Control works with JDeveloper 11g and 12c
    • No design-time work like:
      • Generating Proxies in JDeveloper
      • Creating Wrappers for calling the web service
      • Creating Mappers from and towards your POJO model
      • Creating BC objects in case of Programmatic BC
    • Support for all data types
    • The product is used by multiple larger companies in the Netherlands
    • Pluggable and open source framework

     

    DIY / tutorial

     

    Hopefully, by now you can’t wait to try out XML Data Control yourself. The whole project is hosted on the atlassian suite; on the wiki (Confluence) page, there is a developers guide available.

     

    In addition to the Developers Guide, there is also a tutorial that accompanies this article. This tutorial is a step-by-step guide to getting the JDeveloper extension, setting up your data control, and setting up customizations and data manipulations on the returned XML data. An example web service running on the Google app engine is used in the tutorial, so you can start calling a webservice without going to the trouble of creating your own web service first.

     

    Conclusion

     

    In this article, we have shown you the functionality of the product and have given you pointers to start working with XML Data Control. We hope that we have demonstrated the advantages of this product over the standard alternatives within ADF. There has been an enthusiastic response from the ADF community.

     

    Working with XML within ADF has never been this easy!

     

    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.