Tokenization of artifacts in a BPEL Project
This note describes a simple ant task that I had come up with that provides an easy and flexible method to enable migration of Process artifacts while deploying to multiple target environments.
Problem Statement
Most often, the BPEL process projects that you develop contain XSDs and WSDLs that fall into one or more of the following categories.
a) The artifacts themselves are hosted on a dedicated server for the specific environment. [For instance, in the OHS htdocs within the development server] The artifacts are referred from the project using absolute URLs, containing the host, port, and other server specific information.
b) The artifacts include or import other artifacts that are hosted on a dedicated server for the specific environment.
c) The WSDL contains a JNDI location that changes for each environment.
d) The WSDL defines inline schemas that contain imported remote XSDs that again are hosted on the dedicated development server.
If your process exhibits one or more of the above characteristics, then more often that not, you will encounter the challenge of automating the migration of these artifacts at deployment time, especially when you have a medium to large number of projects, and/or if you have multiple target environments to deploy to.
There are multiple approaches that are in prevelance today to tackle this.
a) The laborious error-prone way of manually replacing the URLs/JNDI names for the new environments.
b) Usage of <customize> and <customizeWSDL> ant tasks.
But what will be really useful is a generic customization infrastructure that enables users to tokenize any arbitrary XML based artifact within the BPEL Project that includes, but is not limited to
a) The BPEL file
b) The WSDL file(s)
c) XSDs
d) XSLT
e) Toplink Mappings
The list goes on.
Overview
The above issues are addressed through a new customization ant task, namely customizeDocument. This task is very similar in usage and behaviour to the existing customization tasks shipped with the product.
The task allows token replacements of contents of any element or attribute that can be reached through an XPath expression. The only limitation of the task is within the tokenization of Processing Instructions within your XML based documents. For instance, the Jdeveloper generated XSL Map file contains a PI indicating the URLs of the source and target XSDs for the map. These URLs cannot be tokenized using this task, nor is this supported through any of the existing customization task.
Setup and Usage
To setup this task, perform the following steps.
a) Copy the customtasks.jar available at http://blogs.oracle.com/ramkumarMenon/gems/customtasks.jar into $ORACLE_HOME\integration\lib directory.
b) Open up ant-orabpel.xml in $ORACLE_HOME\bpel\utilities directory and paste the following piece of code into the file within the <project> element.
<path id="custom.tasks.class.path">
<pathelement location="<absolute path to location of customtasks.jar>"/>
</path>
<property name="custom.tasks.class.path" refid="custom.tasks.class.path"/>
<taskdef name="customizeDocument" classname="com.collaxa.cube.ant.taskdefs.customize.document.CustomizeDocument">
<classpath>
<pathelement path="${custom.tasks.class.path}"/>
</classpath>
</taskdef>
The usage of this task is best illustrated through a simple running example.
You have a BPEL process project named ?CreatePurchaseOrder? that you have deployed to the ?test? environment. After you have performed all the necessary tests, you wish to promote this process to the production environment.
The project contains amongst others, the process WSDL named CreatePurchaseOrderService.wsdl that imports the local Process Schema named PurchaseOrder.xsd.
The WSDL also imports another WSDL named GeneralPOHeader.wsdl that is a shared WSDL amongst multiple BPEL Processes. This WSDL is hosted on the OHS on the ?test? environment. The CreatePurchaseOrderService.wsdl also imports an XSD named Addressing.xsd that is again hosted on the OHS on the test environment.
Moreover, each environment is associated with a specific support group ? that receives notification on faults and errors within processes deployed to that specific environment. The support team email is specified as a preference witihn the deployment descriptor of the BPEL process. [bpel.xml].
This is how a portion of CreatePurchaseOrderService.wsdl looks like.
<?xml version = '1.0' encoding = 'UTF-8'?>
<definitions name="PurchaseOrderService" targetNamespace="http://xmlns.oracle.com/PurchaseOrderService" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:client="http://xmlns.oracle.com/PurchaseOrderService" xmlns:plnk="http://schemas.xmlsoap.org/ws/2003/05/partner-link/">
<import namespace="http://xmlns.po.com/general" location="http://testsoa.server.com:7780/services/GeneralPOHeader.wsdl" />
<types>
<schema xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://xmlns.oracle.com/CreatePurchaseOrderService" schemaLocation="CreatePurchaseOrder.xsd"/>
<import namespace="http://xmlns.po.com/addressing" schemaLocation="http://testsoa.server.com:7780/schemas/Addressing.xsd"/>
</schema>
</types>
. . . . .
</definitions>
And the following is a snippet of bpel.xml.
<?xml version = '1.0' encoding = 'UTF-8'?>
<BPELSuitcase>
<BPELProcess id="CreatePurchaseOrderService" src="CreatePurchaseOrderService.bpel">
<partnerLinkBindings>
<partnerLinkBinding name="client">
<property name="wsdlLocation">CreatePurchaseOrderService.wsdl</property>
</partnerLinkBinding>
</partnerLinkBindings>
<preferences>
<property name="supportEmail" encryption="plaintext">test_support_group@clientcompany.com</property>
</preferences>
</BPELProcess>
</BPELSuitcase>
Note the lines highlighted in blue. The intent is to migrate these URLs and preferences to the values applicable for production. The corresponding values in the prod environment are
a) http://prodsoa.server.com:9876/services/GeneralPOHeader.wsdl
b) http://prodsoa.server.com:9876/schemas/Addressing.xsd
c) prod_support_group@clientcompany.com
Note: Steps 1 through 3 are only one of the different ways to manage multiple environments. You could have alternative mechanisms to manage multi-server deployments.
Step 1: Define multiple copies of ant-orabpel.properties, one for each environment - lets say as ant-orabpel_dev.properties, ant-orabpel_test.properties and ant-orabpel_prod.properties. Specify env specific parameters in each of these files.
Step 2: Define the following properties in the ant-orabpel_test.properties.
a) service_host=testsoa.server.com
b) service_ port = 7780
c) support_group_email=test_support_group@clientcompany.com
Define the following properties in the ant-orabpel_prod.properties.
a) service_ host=prodsoa.server.com
b) service_ port = 9876
c) support_group_email=prod_support_group@clientcompany.com
Step 3: Open the build.xml. Change the following line within it.
<property file="${bpel.home}/utilities/ant-orabpel.properties"/>
So that it looks like this.
<property file="${bpel.home}/utilities/ant-orabpel_${deploy_env}.properties"/>
This enables us to pass in a command line argument named deploy_env to the build script and have it import the appropriate ant-orabpel.properties.
For e.g., When you invoke the build for the test environment by typing in ant ?Ddeploy_env=test, the build.xml automatically imports the ant-orabpel_test.properties.
Step 4: Open up the compile target block. We will now define the customizations on the process WSDL and the bpel.xml.
<target name="compile">
<bpelc input="${process.dir}/bpel/bpel.xml" out="${process.dir}/output"
rev="${rev}" home="${bpel.home}">
</bpelc>
</target>
Before the bpelc node, add the customizeDocument task.
<target name=?compile?>
<customizeDocument inFile=?${process.dir}/bpel/CreatePurchaseOrderService.wsdl? outFile=?${process.dir}/bpel/CreatePurchaseOrderService.wsdl?>
</customizeDocument>
. . . .
</target>
The above step indicates the intent to customize the CreatePurchaseOrderService.wsdl.
Next, we need to add the nested ?setTextContent? task that allows us to set the text of any attribute or element within the WSDL. Use the setTextContent task to specify the element or attribute to be updated, together with the value that it should be updated with.
<target name=?compile?>
<customizeDocument inFile=?${process.dir}/bpel/CreatePurchaseOrderService.wsdl? outFile=?${process.dir}/bpel/CreatePurchaseOrderService.wsdl?>
<setTextContent select=?/wsdl:definitions/wsdl:import/@location? textContent=?http://${service_host}:${service_port}/services/GeneralPOHeader.wsdl?/>
</customizeDocument>
. . . .
</target>
The ?select? attribute on the customizeDocument indicates a qualified XPath expression that points to the node within the process WSDL that needs to be customized. In this example, it points to the location attribute of the WSDL import. The ?textContent? attribute will hold the text that will be set within the node. In this example, it points to the absolute URL of the imported WSDL. You can also specify the tokens in the URL ? The build script will automatically subsitute them with the actual values when it is executed. For instance, if the build were executed with the ?Ddeploy_env=test or prod, the appropriate values of service_host and service_port will be substituted from the ant-orabpel_test/prod.properties.
Next, we shall customize the XSD import within the WSDL. For this, add one more setTextContent task within the customizeDocument task. The semantics of this is identical to the earlier step.
<target name=?compile?>
<customizeDocument inFile=?${process.dir}/bpel/CreatePurchaseOrderService.wsdl? outFile=?${process.dir}/bpel/CreatePurchaseOrderService.wsdl?>
<setTextContent select=?/wsdl:definitions/wsdl:import/@location? textContent=?http://${service_host}:${service_port}/services/GeneralPOHeader.wsdl?/>
<setTextContent select=?/wsdl:definitions/wsdl:types/xsd:schema/xsd:import/@schemaLocation? textContent=?http://${service_host}:${service_port}/schemas/Addressing.xsd?/>
</customizeDocument>
. . . .
</target>
The definition of the customization for the WSDL and XSD is almost complete. The missing step is the namespace URI mappings for the prefixes used within the select expressions. In this case, there are two prefixes that need to be mapped to a namespace URI.
a) The ?xsd? namespace prefix
b) The ?wsdl? namespace prefix.
These prefixes are declared as properties within the same build file.
Declare two properties, one for each of the namespace URI, as below at the global level within the build.xml [i.e. as a child element of the <project> element. The name of the properties should be ?prefix.? Followed by the actual prefix. The value attribute contains the namespace URI for the prefix.
<property name="prefix.wsdl" value="http://schemas.xmlsoap.org/wsdl/"/>
<property name="prefix.xsd" value="http://www.w3.org/2001/XMLSchema"/>
Next, we specify the customization required for the bpel.xml.
Add another <customizeDocument> task within the compile block. We need to add another one since we are customizing a different document.
<project ?..>
. . . . .
<property name="prefix.wsdl" value="http://schemas.xmlsoap.org/wsdl/"/>
<property name="prefix.xsd" value="http://www.w3.org/2001/XMLSchema"/>
<target name=?compile?>
<customizeDocument inFile=?${process.dir}/bpel/CreatePurchaseOrderService.wsdl? outFile=?${process.dir}/bpel/CreatePurchaseOrderService.wsdl?>
<setTextContent select=?/wsdl:definitions/wsdl:import/@location? textContent=?http://${service_host}:${service_port}/services/GeneralPOHeader.wsdl?/>
<setTextContent select=?/wsdl:definitions/wsdl:types/xsd:schema/xsd:import/@schemaLocation? textContent=?http://${service_host}:${service_port}/schemas/Addressing.xsd?/>
</customizeDocument>
<customizeDocument inFile=?${process.dir}/bpel/bpel.xml? outFile=?${process.dir}/bpel/bpel.xml?>
<setTextContent select=?/BPELSuitcase/BPELProcess/preferences/property[@name=?supportEmail
?]? textContent=?${support_group_email}?/>
</customizeDocument>
. . . .
</target>
Note that the select expression used for this customization does not need any namespace prefixes. This is attributed to the fact that bpel.xml by itself is an unqualified document.
This completes the customization features provided by this task.
Note that the customizeDocument task can be used to customize any bpel process project artifact, although not illustrated in this document.
RSS
Email
