Error starting the SOA Suite

I tried starting the Oracle SOA Suite from the command prompt,
${SOA_HOME}opmn\bin>opmnctl.exe startall

But, I got an error as under,

opmnctl: starting opmn and all managed processes...
================================================================================
opmn id=localhost:6200
2 of 3 processes started.

ias-instanceid=oracleAS++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
ias-component/process-type/process-set:
default_group/oc4j_soa/default_group/

Error
--> Process (index=1,uid=936119581,pid=5296)
failed to start a managed process after the maximum retry limit
Log:
C:\SOA\product\10.1.3.1\OracleAS\opmn\logs\\default_group~oc4j_soa~default_group~1.log

After doing some research, I found that this is caused due to improper shutdown of the SOA suite. Some of the locks (JMS locks, DB locks ) are not released which needs to be manually removed from the file system.

Navigate to ${SOA_HOME}\j2ee\{OC4J Instance Name}\persistence and remove all the files.

Now start the SOA suite and it should work.

Issues with <exec> ANT task

The exec ant task is used to execute a system command. I came across the syntax that works on Windows but does not work on Linux.

Works on Windows:

<exec executable="${ant.home}/bin/ant" failonerror="true"
dir="${sandbox.path}/${processName}">
<arg value="-Dhttp.hostname"/>
<arg value="-Dhttp.hostname=${http.host}"/>
<arg value="-buildfile= build.xml"/>
</exec>

The tweak to make it working on the Linux,

<exec executable="${ant.home}/bin/ant" failonerror="true"
dir="${sandbox.path}/${processName}">
<arg value="-Dhttp.hostname"/>
<arg value="-Dhttp.hostname=${http.host}"/>
<arg value="-buildfile"/>
<arg value="build.xml"/>
</exec>

Adapter Configuration for seamless migration to different environments

Adapter Configuration for seamless migration to different environments

A general issue with the adapters is how to configure their properties for different environments at deployment time such as,

· File Adapters: [Logical/Physical]Directory Location
· DBAdapters: Mapping File
· AQAdapters: Queue Name

The list goes on, but the multi-environment configuration details works the same way. The important thing to note is that these properties are defined in the [adapter_service_name].wsdl under the //binding/jca:operation Xpath. The Outbound Adapter configuration uses the Interaction Specification and Inbound Adapter uses the Activation Specification and the way they need to be configured varies too,

A) Outbound Adapters: I will take an example of Outbound File Adapter to explain the modifications to the BPEL project,

1. [adapter_service_name].wsdl

<binding name="Write_binding" type="tns:Write_ptt">
<jca:binding />
<operation name="Write">
<jca:operation
LogicalDirectory="OutputDirectory"
InteractionSpec="oracle.tip.adapter.file.outbound.FileInteractionSpec"
FileNamingConvention="data_%yyyyMMdd%.xml"
NumberMessages="1"
OpaqueSchema="false" >
</jca:operation>
<input>
<jca:header message="hdr:OutboundHeader_msg" part="outboundHeader"/>
</input>
</operation>
</binding>

2. bpel.xml

<partnerLinkBinding name="FileAdpater">
<property name="OutputDirectory">D:\temp</property>
</partnerLinkBinding>

The Adapter configuration will use the value of OutputDirectory in the deployment descriptor and the value in the bpel.xml can be changed using the custom ant task.

B) Inbound Adapters: I will take an example of Inbound File Adapter to explain the modifications to the BPEL project,

1. [adapter_service_name].wsdl

<binding name="Read_binding" type="tns:Read_ptt">
<pc:inbound_binding />
<operation name="Read">
<jca:operation
LogicalDirectory="InputDirectory"
ActivationSpec="oracle.tip.adapter.file.inbound.FileActivationSpec"
DeleteFile="true"
IncludeFiles=".*\.xml"
PollingFrequency="60"
MinimumAge="0"
OpaqueSchema="false" >
</jca:operation>
<input>
<jca:header message="hdr:InboundHeader_msg" part="inboundHeader"/>
</input>
</operation>
</binding>

2. bpel.xml

<partnerLinkBindings>
<partnerLinkBinding name="InboundFileAdapter">
<property name="wsdlLocation">InboundFileAdapter.wsdl</property>
</partnerLinkBinding>
</partnerLinkBindings>
<activationAgents>
<activationAgent className="oracle.tip.adapter.fw.agent.jca.JCAActivationAgent" partnerLink="InboundFileAdapter">
<property name="InputDirectory">C:\temp</property>
<property name="portType">Read_ptt</property>
</activationAgent>
</activationAgents>

The Adapter configuration will use the value of InputDirectory in the deployment descriptor (bpel.xml) .For different environment this value can be modified using the using the custom ant task.

Seamless deployment and migration of BPEL processes (DEV ->QA->PROD)

One of the aspects that need to be taken care in developing the BPEL processes is the seamless migration of code from one environment to another (DEV -> QA -> PROD). After the development of the BPEL processes, it is well expected that the code would be tested in various environments before finally been promoted to the Production environment. With the kind of benefits SOA promised, it is a mandatory requirement that there are no modifications to the code, once out of source control, while migrating the functionality in any of the environments. In order to accomplish smooth transition, certain guidelines should be laid down right from the design to development to deployment process.

Most of the artifacts in the BPEL suitcase are XML files and shall be re-written for each environment to reflect the service-endpoints, properties and the best way for enabling the seamless transition is to modify these files before deployment. The artifacts that needs to be configurable in Oracle BPEL project are as under,

1. bpel.xml – This is the deployment descriptor for the BPEL project and may define either of the following as part of the configuration.


1. PartnerLinkBinding properties
2. ActivationAgent properties for Inbound adapters
3. Configuration properties
4. Preference properties
   


2. <service_name>.wsdl – The Web Service Description Language (WSDL) encapsulates the interface definition for the service. The BPEL project/suitcase will contain a WSDL for each of the following,


1. <bpel_service>.wsdl: The file will hold the interface definition for the BPEL service. The details that shall be modified for each environment are,


• WSDL Locations
• Schema Locations


2. <adapter_service>.wsdl: For each adapter (Inbound/Outbound), there will be a separate wsdl file that will hold the adapter interface definition.The details that shall be modified for each environment in the adapter WSDL are,


• WSDL Locations
• Schema Locations
• <jca:operation> details
• <jca:address> location


3. <partner_sevice>.wsdl: The BPEL project/suitcase will hold the WSDL for the services that are invoked and are non-BPEL (Java, .Net, etc .). The details that shall be modified for each environment in the adapter WSDL are


• WSDL Location


3. <bpel_project>.bpel – The BPEL process XML file holds the process details as per WS-BPEL specifications. The BPEL engine will execute the file and build the respective modules/files.


4. <file_name>.xsl – The BPEL process will create a separate XSL file for each of the transformations performed within the BPEL process.

All these configuration details are environment specific and are required to be modified. We will cover later in the article about how to make these changes during deployment for environment.

Without getting into the details of the above-mentioned artifacts, I will rather explain how to configure each of the artifacts for different environments. All the above-mentioned artifacts are pure XML files, which make our life easy and can be modified using an ANT script file (build.xml). Every BPEL project creates a build.xml (will refer as parent script in rest of the article) file for compiling and deploying the BPEL project automatically. We will need to develop another build.xml (will refer as child script) file for making the environment related changes and package within the BPEL suitcase. Oracle recommends creating the child script in ${project.dir}/bpel/ folder and call it from within the parent script before the compile task.

The rest article will focus on how to write ant script for modifying the XML files and will require good understanding of ANT. We will also use some of the ant tasks that are provided with the software and develop some ant tasks in Java. You may refer the document on custom ant tasks here.

Qualify bpel.xml for the environment

bpel.xml is the deployment descriptor and most of the details in the file can be modified at deployment time using the custom ant task <bpelc> that comes out of the box. I will explain each of the modifications with an example,

1. PartnerLinkBinding properties: The example will include the details on how to modify the WSDL location of the partner link for different environments. Include the XML tag in the child configuration script as under,


<bpelc input="${process.dir}/bpel/bpel.xml" out="${process.dir}/output"
rev="${rev}" home="${bpel.home}">
<customize>
<partnerLinkBinding name="partner_name">
<property name="wsdlLocation">
http://${ENV.hostname}:${ENV.port}/orabpel/${domain}/
{partner_service}/1.0/{partner_service}?wsdl
</property>
</partnerLinkBinding>
</customize>
</bpelc>


2. ActivationAgent properties for Inbound adapters: The example will explain on how to change the polling file location of the file adapter in various environments. Include the following in the configuration script,


<bpelc input="${process.dir}/bpel/bpel.xml" out="${process.dir}/output"
rev="${rev}" home="${bpel.home}">
<customize>
<activationAgent className="oracle.tip.adapter.fw.agent.jca.
JCAActivationAgent" partnerLink="InboundFileAdapter">
<property name="InputDirectory">${dir}</property>
</activationAgent>
</customize>
</bpelc>


Refer the blog entry http://ora-soa.blogspot.com/2008/05/adapter-configuration-for- seamless.html for configuring the Inbound/Outbound Adapters properties in bpel.xml.

3. Configuration properties: The example will explain on how to change the configuration property “inMemoryOptimization” in various environments. Include the following in the configuration script,


<bpelc input="${process.dir}/bpel/bpel.xml" out="${process.dir}/output"
rev="${rev}" home="${bpel.home}">
<customize>
<configurations>
<property name="inMemoryOptimization">true</property>
</configurations>
</customize>
</bpelc>

4. Preference properties: The example will explain on how to change the preference property “MAX_AMOUNT” in various environments. Include the following in the configuration script,

<bpelc input="${process.dir}/bpel/bpel.xml" out="${process.dir}/output"
rev="${rev}" home="${bpel.home}">
<customize>
<activationAgent className="oracle.tip.adapter.fw.agent.jca.
JCAActivationAgent" partnerLink="InboundFileAdapter">
<property name="InputDirectory">${dir}</property>
</activationAgent>
</customize>
</bpelc>

Modify various WSDL files for the environment

WSDL defines the interface definition of a webservice.The references in the WSDL file can be modified at deployment time using the custom ant task that shall perform the following sequence of tasks,

1. Accept an XML file,


2. Build a DOM object,


3. Modify attributes, values, etc. of the XML elements


4. Write the modified DOM into another XML file

Refer the blog entry http://blogs.oracle.com/rammenon/2007/11/22#a72 to download one of the developed custom ant tasks <customizeDocument> for modifying the XML files. Using <customizeDocument> ant task, you may configure the imported schema locations and WSDL locations for the environment. I will explain by taking an example on how to use the downloaded custom ant task to modify the schema and WSDL locations specified in the import element.

1. Schema Locations: In order to reuse the schema definition in various BPEL projects, it is a recommended practice to store at a centralized location and refer them. Usually, they are kept under the {bpel_home}/system/xmllib but you may host them on any HTTP Server. The centralized schema location will change for each environment and it becomes mandatory to make these changes in the WSDL file too. The example below will demonstrate it,

• Sample WSDL file:

<definitions name="InteractiveProcess"
targetNamespace="http://xmlns.oracle.com/InteractiveProcess"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:ns1="http://schemas.oracle.com/bpel/extension"
xmlns:plnk="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
xmlns:client="http://xmlns.oracle.com/InteractiveProcess">

<types>
<schema xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://xmlns.oracle.com/InteractiveProcess"
schemaLocation="http://server:7778/orabpel/xmllib/xsd/InteractiveProcess.xsd"/>
</schema>
</types>
:
:
</definitions>

• Child Configuration file: In order to modify the XSD import, include the below XML element in the configuration file,

<property name="prefix.xsd" value="http://www.w3.org/2001/XMLSchema"/>

<!-- Update the XSD import of the InteractiveProcess schema -->

<customizeDocument inFile="${process.dir}/bpel/InteractiveProcess.wsdl" outFile="${process.dir}/bpel/InteractiveProcess.wsdl">
<setTextContent select='/wsdl:definitions/wsdl:types/xsd:schema/xsd:import
[@namespace="http://xmlns.oracle.com/InteractiveProcess"]/@schemaLocation' textContent="http://${http.hostname}:${http.port}/orabpel/xmllib/xsd/
InteractiveProcess.xsd"/>
</customizeDocument>

2. WSDL Locations: The WSDL import in a WSDL appears when the service refers to the schema definition of another service. The example will explain on how to change the wsdl location imports in the WSDL file for various environments.

• Sample WSDL file:

<definitions name="InteractiveProcess"
targetNamespace="http://xmlns.oracle.com/InteractiveProcess"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:ns1="http://schemas.oracle.com/bpel/extension"
xmlns:plnk="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
xmlns:client="http://xmlns.oracle.com/InteractiveProcess">

<import namespace="http://schemas.oracle.com/bpel/extension"
location="http://server:7778/orabpel/xmllib/RuntimeFault.wsdl"/>
:
:
</definitions>

• Child Configuration Script: In order to modify the WSDL import, include the below XML element in the child configuration file,

<property name="prefix.wsdl" value="http://schemas.xmlsoap.org/wsdl/"/>

<!-- Update the WSDL import of the RuntimeFault-->

<customizeDocument inFile="${process.dir}/bpel/ InteractiveProcess.wsdl" outFile="${process.dir}/bpel/ InteractiveProcess.wsdl">
<setTextContent select="/wsdl:definitions/wsdl:import/@location" textContent="http://${http.hostname}:${http.port}/orabpel/xmllib/
RuntimeFault.wsdl"/>
</customizeDocument>

3. <jca:operation> details: The jca binding details in the adapter wsdl file can be modified at deployment and the details are well explained for both Outbound and Inbound adapters in the blog entry.


4. <jca:address> location: The connection details of the adapters shall be managed by the application server and should be referred in the BPEL WSDL file using the JNDI. You may create and configure the managed connections in the application server using the Server console and shall be referred in the J2EE_HOME/application-deployments/domain_name/Adapter_Type/oc4j-ra.xml file.

Modify the process(.bpel) file for the environment

Most of the details in the process file are static and need not be changed to reflect the environment details. Right now, I can only think about reference to the location of the transformation files, used for manipulating the XML data. In order to reuse the same xsl file in different projects, we shall host them at a centralized location and shall not be a part of the BPEL project/suitcase. You may host them on a web server or create a folder xsl within ${bpel.home}/system/xmllib/ folder. The XSLs can then be referred using the http://server:port/orabpel/xmllib/xsl/file.xsl Url. The developers need to make sure that the BPEL process shall be written in a way that the process file need not be modified for different environment. One of the ways is to refer the XSL as under,

<from expression="ora:processXSLT(concat(substring-before(
ora:getProcessURL(),ora:getDomainId()),'xmllib/xsl/file1.xsl'),
bpws:getVariableData ('inputVariable','payload'))"/>

Modify the transformation file (XSL) for the environment

The XSL files that are specific to the BPEL process and are bundled in the BPEL suitcase may need to modify at deployment time. The transformation files sometimes refer the source and target schema locations that are accessed from a centralized location specific to each environment. You will require to build a custom ant task or use <customizeDocument> task as mentioned above for modifying the XML files at deployment time.