25 min read

(For more resources related to this topic, see here.)

The Business Process Execution Language (BPEL) is based on XML, which means that all the internal variables and data are presented in XML. BPEL and Java technologies are complementary, we seek ways to ease the integration of the technologies. In order to handle the XML content from BPEL variables in Java resources (classes), we have a couple of possibilities:

  • Use DOM (Document Object Model) API for Java, where we handle the XML content directly through API calls. An example of such a call would be reading from the input variable:

    oracle.xml.parser.v2.XMLElement input_cf= (oracle.xml.parser.
    v2.XMLElement)getVariableData("inputVariable","payload","/
    client:Cashflows");

    We receive the XMLElement class, which we need to handle further, either be assignment, reading of content, iteration, or something else.

  • As an alternative, we can use XML facade though Java Architecture for XML Binding (JAXB). JAXB provides a convenient way of transforming XML to Java or vice-versa. The creation of XML facade is supported through the xjc utility and of course via the JDeveloper IDE. The example code for accessing XML through XML facade is:

    java.util.List
    princEx= cf.getPrincipalExchange();

We can see that there is neither XML content nor DOM API anymore. Furthermore, we have to access the whole XML structure represented by Java classes.

The latest specification of JAXB at the time of writing is 2.2.7, and its specification can be found at the following location: https://jaxb.java.net/.

The purpose of an XML facade operation is the marshalling and un-marshalling of Java classes. When the originated content is presented in XML, we use un-marshalling methods in order to generate the correspondent Java classes. In cases where we have content stored in Java classes and we want to present the content in XML, we use the marshalling methods.

JAXB provides the ability to create XML facade from an XML schema definition or from the WSDL (Web Service Definition/Description Language). The latter method provides a useful approach as we, in most cases, orchestrate web services whose operations are defined in WSDL documents.

Throughout this article, we will work on a sample from the banking world. On top of this sample, we will show how to build the XML facade. The sample contains the simple XML types, complex types, elements, and cardinality, so we cover all the essential elements of functionality in XML facade.

Setting up an XML facade project

We start generating XML facade by setting up a project in a JDeveloper environment which provides convenient tools for building XML facades. This recipe will describe how to set up a JDeveloper project in order to build XML facade.

Getting ready

To complete the recipe, we need the XML schema of the BPEL process variables based on which we build XML facade. Explore the XML schema of our banking BPEL process. We are interested in the structure of the BPEL request message:



name="unadjustedPrincipalExchangeDate" type="xsd:date"/>
name="adjustedPrincipalExchangeDate" type="xsd:date"/>
type="xsd:decimal"/>
type="xsd:decimal"/>





name="principalExchange" type="prc:PrincipalExchange"/>


The request message structure presents just a small fragment of cash flows modeled in the banks. The concrete definition of a cash flow is much more complex. However, our definition contains all the right elements so that we can show the advantages of using XML facade in a BPEL process.

How to do it…

The steps involved in setting up a JDeveloper project for XML façade are as follows:

  1. We start by opening a new Java Project in JDeveloper and naming it CashflowFacade. Click on Next.
  2. In the next window of the Create Java Project wizard, we select the default package name org.packt.cashflow.facade. Click on Finish. We now have the following project structure in JDeveloper:

  3. We have created a project that is ready for XML facade creation.

How it works…

After the wizard has finished, we can see the project structure created in JDeveloper. Also, the corresponding file structure is created in the filesystem.

Generating XML facade using ANT

This recipe explains how to generate XML facade with the use of the Apache ANT utility. We use the ANT scripts when we want to build or rebuild the XML facade in many iterations, for example, every time during nightly builds. Using ANT to build XML façade is very useful when XML definition changes are constantly in phases of development. With ANT, we can ensure continuous synchronization between XML and generated Java code.

The official ANT homepage along with detailed information on how to use it can be found at the following URL: http://ant.apache.org/.

Getting ready

By completing our previous recipe, we built up a JDeveloper project ready to create XML facade out of XML schema. To complete this recipe, we need to add ANT project technology to the project. We achieve this through the Project Properties dialog:

How to do it…

The following are the steps we need to take to create a project in JDeveloper for building XML façade with ANT:

  1. Create a new ANT build file by right-clicking on the CashflowFacade project node, select New, and choose Buildfile from Project (Ant):

  2. The ANT build file is generated and added into the project under the Resources folder. Now we need to amend the build.xml file with the code to build XML facade.
  3. We will first define the properties for our XML facade:



  4. We define the location of the source XML schema (it is located in the BPEL process). Next, we define the destination of the generated Java files and the name of the package.
  5. Now, we define the ANT target in order to build XML facade classes. The ANT target presents one closed unit of ANT work. We define the build task for the XML façade as follows:













  6. Now we have XML facade packaged and ready to be used in BPEL processes.

How it works…

ANT is used as a build tool and performs various tasks. As such, we can easily use it to build XML facade. Java Architecture for XML Binding provides the xjc utility, which can help us in building XML facade.

We have provided the following parameters to the xjc utility:

  • Xmlschema: This is the threat input schema as XML schema
  • d: This specifies the destination directory of the generated classes
  • p: This specifies the package name of the generated classes

There are a number of other parameters, however we will not go into detail about them here. Based on the parameters we provided to the xjc utility, the Java representation of the XML schema is generated. If we examine the generated classes, we can see that there exists a Java class for every type defined in the XML schema. Also, we can see that the ObjectFactory class is generated, which eases the generation of Java class instances.

There’s more…

There is a difference in creating XML facade between Versions 10g and 11g of Oracle SOA Suite. In Oracle SOA Suite 10g, there was a convenient utility named schema, which is used for building XML facade. However, in Oracle SOA Suite 11g, the schema utility is not available anymore.

To provide a similar solution, we create a template class, which is later copied to a real code package when needed to provide functionality for XML facade. We create a new class Facade in the called facade package. The only method in the class is static and serves as a creation point of facade:

public static Object createFacade(String context, XMLElement doc)
throws Exception {
JAXBContext jaxbContext;
Object zz= null;
try {
jaxbContext = JAXBContext.newInstance(context);
Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
zz = unmarshaller.unmarshal(doc);
return zz;
} catch (JAXBException e) {
throw new Exception("Cannot create facade from the XML content. "
+ e.getMessage());
}
}

The class code implementation is simple and consists of creating the JAXB context. Further, we un-marshall the context and return the resulting class to the client. In case of problems, we either throw an exception or return a null object.

Now the calling code is trivial. For example, to create XML facade for the XML content, we call as follows:

Object zz = facade.Facade.createFacade("org.packt.cashflow.facade",
document.getSrcRoot());

Creating XML facade from XSD

This recipe describes how to create XML facade classes from XSD. Usually, the necessity to access XML content out of Java classes comes from already defined XML schemas in BPEL processes.

How to do it…

We have already defined the BPEL process and the XML schema (Derivative_Cashflow.xsd) in the project. The following steps will show you how to create the XML facade from the XML schema:

  1. Select the CashflowFacade project, right-click on it, and select New. Select JAXB 2.0 Content Model from XML Schema.

  2. Select the schema file from the Banking_BPEL project. Select the Package Name for Generated Classes checkbox and click on the OK button.

The corresponding Java classes for the XML schema were generated.

How it works…

Now compare the classes generated via the ANT utility in the Generating XML facade using ANT recipe with this one. In essence, the generated files are the same. However, we see the additional file jaxb.properties, which holds the configuration of the JAXB factory used for the generation of Java classes.

It is recommended to create the same access class (Facade.java) in order to simplify further access to XML facade.

Creating XML facade from WSDL

It is possible to include the definitions of schema elements into WSDL. To overcome the extraction of XML schema content from the WSDL document, we would rather take the WSDL document and create XML facade for it. This recipe explains how to create XML facade out of the WSDL document.

Getting ready

To complete the recipe, we need the WSDL document with the XML schema definition. Luckily, we already have one automatically generated WSDL document, which we received during the Banking_BPEL project creation.

We will amend the already created project, so it is recommended to complete the Generating XML facade using ANT recipe before continuing with this recipe.

How to do it…

The following are the steps involved in creating XML façade from WSDL:

  1. Open the ANT configuration file (build.xml) in JDeveloper.
  2. We first define the property which identifies the location of the WSDL document:

  3. Continue with the definition of a new target inside the ANT configuration file in order to generate Java classes from the WSDL document:













  4. From the configuration point of view, this step completes the recipe.
  5. To run the newly defined ANT task, we select the build.xml file in the Projects pane. Then, we select the xjc_wsdl task in the Structure pane of JDeveloper, right-click on it, and select Run Target “xjc_wsdl”:

How it works…

The generation of Java representation classes from WSDL content works similar to the generation of Java classes from XSD content. Only the source of the XML input content is different from the xjc utility.

In case we execute the ANT task with the wrong XML or WSDL content, we receive a kind notification from the xjc utility. For example, if we run the utility xjc with the parameter –xmlschema over the WSDL document, we get a warning that we should use different parameters for generating XML façade from WSDL.

Note that generation of Java classes from the WSDL document via JAXB is only available through ANT task definition or the xjc utility. If we try the same procedure with JDeveloper, an error is reported.

Packaging XML facade into JAR

This recipe explains how to prepare a package containing XML facade to be used in BPEL processes and in Java applications in general.

Getting ready

To complete this recipe, we need the XML facade created out of the XML schema. Also, the generated Java classes need to be compiled.

How to do it…

The steps involved for packaging XML façade into JAR are as follows:

  1. We open the Project Properties by right-clicking on the CashflowFacade root node.
  2. From the left-hand side tree, select Deployment and click on the New button. The Create Deployment Profile window opens where we set the name of the archive.

  3. Click on the OK button. The Edit JAR Deployment Profile Properties dialog opens where you can configure what is going into the JAR archive. We confirm the dialog and deployment profile as we don’t need any special configuration.
  4. Now, we right-click on the project root node (CashflowFacade), then select Deploy and CFacade. The window requesting the deployment action appears. We simply confirm it by pressing the Finish button:

  5. As a result, we can see the generated JAR file created in the deploy folder of the project.

There’s more…

In this article, we also cover the building of XML facade with the ANT tool. To support an automatic build process, we can also define an ANT target to build the JAR file. We open the build.xml file and define a new target for packaging purposes. With this target, we first recreate the deploy directory and then prepare the package to be utilized in the BPEL process:




basedir="./classes"
excludes="**/*data*"
/>

To automate the process even further, we define the target to copy generated JAR files to the location of the BPEL process. Usually, this means copying the JAR files to the SCA-INF/lib directory:



The task depends on the successful creation of a JAR package, and when the JAR package is created, it is copied over to the BPEL process library folder.

Generating Java documents for XML facade

Well prepared documentation presents important aspect of further XML facade integration. Suppose we only receive the JAR package containing XML facade. It is virtually impossible to use XML facade if we don’t know what the purpose of each data type is and how we can utilize it. With documentation, we receive a well-defined XML facade capable of integrating XML and Java worlds together. This recipe explains how to document the XML facade generated Java classes.

Getting ready

To complete this recipe, we only need the XML schema defined. We already have the XML schema in the Banking_BPEL project (Derivative_Cashflow.xsd).

How to do it…

The following are the steps we need to take in order to generate Java documents for XML facade:

  1. We open the Derivative_Cashflow.xsd XML schema file.
  2. Initially, we need to add an additional schema definition to the XML schema file:

    elementFormDefault="qualified"
    targetNamespace="http://

    jxb_version="2.1">

  3. In order to put documentation at the package level, we put the following code immediately after the tag in the XML schema file:





    This package represents the XML facade
    of the cashflows in the financial derivatives
    structure.




  4. In order to add documentation at the complexType level, we need to put the following lines into the XML schema file. The code goes immediately after the complexType definition:




    This class defines the data for the
    events, when principal exchange occurs.



  5. The elements of the complexType definition are annotated in a similar way. We put the annotation data immediately after the element definition in the XML schema file:




    Raw principal exchange
    date.



  6. In JDeveloper, we are now ready to build the javadoc documentation. So, select the project CashflowFacade root node. Then, from the main menu, select the Build and Javadoc CashflowFacade.jpr option. The javadoc content will be built in the javadoc directory of the project.

How it works…

During the conversion from XML schema to Java classes, JAXB is also processing possible annotations inside the XML schema file. When the conversion utility (xjc or execution through JDeveloper) finds the annotation in the XML schema file, it decorates the generated Java classes according to the specification.

The XML schema file must contain the following declarations. In the element, the following declaration of the JAXB schema namespace must exist:

jxb:version="2.1"

Note that the xjb:version attribute is where the Version of the JAXB specification is defined. The most common Version declarations are 1.0, 2.0, and 2.1.

The actual definition of javadoc resides within the and blocks. To annotate at package level, we use the following code:



TEXT

We define the package name to annotate and a javadoc text containing the documentation for the package level.

The annotation of javadoc at class or attribute level is similar to the following code:

class|property>
TEXT
class|property>

If we want to annotate the XML schema at complexType level, we use the element. To annotate the XML schema at element level, we use the element.

There’s more…

In many cases, we need to annotate the XML schema file directly for various reasons. The XML schema defined by different vendors is automatically generated. In such cases, we would need to annotate the XML schema each time we want to generate Java classes out of it. This would require additional work just for annotation decoration tasks.

In such situations, we can separate the annotation part of the XML schema to a separate file. With such an approach, we separate the annotating part from the XML schema content itself, over which we usually don’t have control. For that purpose, we create a binding file in our CashflowFacade project and name it extBinding.xjb. We put the annotation documentation into this file and remove it from the original XML schema. We start by defining the binding file header declaration:


>

We need to specify the name of the schema file location and the root node of the XML schema which corresponds to our mapping. We continue by declaring the package level annotation:



This package represents
the XML facade of the cashflows in the financial
derivatives structure.


Subscribe to the weekly Packt Hub newsletter. We'll send you the results of our AI Now Survey, featuring data and insights from across the tech landscape.

* indicates required