Providing a Service

To provide a service with the BPEL component, you will have to:

1. Define your process using WS-BPEL (e.g. using the Eclipse BPEL editor bundled with JBossTools).

2. Define a WSDL interface for the BPEL service.

3. Define a Deployment Descriptor (e.g. using the ODE Deployment Descriptor editor bundled with JBossTools).

4. Add the component containing the implementation and service interface to the SwitchYard configuration.

Here is an example of the component section of the SwitchYard configuration:

<sca:component name="SayHelloService">
    <bpel:implementation.bpel process="sh:SayHello" />
    <sca:service name="SayHelloService">
        <sca:interface.wsdl interface="SayHelloArtifacts.wsdl#wsdl.porttype(SayHello)"/>
    </sca:service>
</sca:component>

The BPEL component contains a single 'implementation.bpel' element that identifies the fully qualified name of the BPEL process.

The component may also contain one or more service elements defining the WSDL port types through which the BPEL process can be accessed.

In the packaged Switchyard application, the BPEL process associated with this fully qualified name, must be present within the root folder of the distribution, along with the deployment descriptor (deploy.xml). An example of the deployment descriptor for the BPEL process referenced above is:

<deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03"
	xmlns:examples="http://www.jboss.org/bpel/examples" >

	<process name="examples:SayHello">
		<active>true</active>
		<retired>false</retired>
		<process-events generate="all"/>
		<provide partnerLink="client">
			<service name="examples:SayHelloService" port="SayHelloPort"/>
		</provide>
	</process>
</deploy>

Consuming a Service

This section describes how a BPEL process can invoke other services.

The first step is to define the WSDL interface(s), representing the service(s) to be consumed, using an invoke element within the deployment descriptor, e.g.

<process name="ls:loanApprovalProcess">
		<active>true</active>
		<process-events generate="all"/>
		<provide partnerLink="customer">
			<service name="ls:loanService" port="loanService_Port"/>
		</provide>
		<invoke partnerLink="assessor" usePeer2Peer="false">
			<service name="ra:riskAssessor" port="riskAssessor_Port"/>
		</invoke>
	</process>

The 'usePeer2Peer' property informs the BPEL engine not to use internal communications for sending messages between BPEL processes that may be executing within the same engine, and instead pass messages through the SwitchYard infrastructure.

For each consumed service, we then need to create a reference element within the SwitchYard configuration, to locate the WSDL file and identify the port type associated with the required WSDL service/port.

<sca:component name="loanService">
             <bpel:implementation.bpel process="ls:loanApprovalProcess" />
             <sca:service name="loanService">
                 <sca:interface.wsdl interface="loanServicePT.wsdl#wsdl.porttype(loanServicePT)"/>
             </sca:service>
             <sca:reference name="riskAssessor" >
                 <sca:interface.wsdl interface="riskAssessmentPT.wsdl#wsdl.porttype(riskAssessmentPT)"/>
             </sca:reference>
         </sca:component>

.....
<bpel:copy>
     <bpel:from xmlns:property="java:org.switchyard.component.bpel.riftsaw.SwitchYardPropertyFunction"
                expressionLanguage="urn:oasis:names:tc:wsbpel:2.0:sublang:xpath2.0">
         <![CDATA[concat(property:resolveProperty('Greeting'), $ReceiveSayHelloVar.parameters/tns:input)]]>
     </bpel:from>
     <bpel:to part="parameters" variable="ReplySayHelloVar">
         <bpel:query queryLanguage="urn:oasis:names:tc:wsbpel:2.0:sublang:xpath1.0"><![CDATA[tns:result]]></bpel:query>
     </bpel:to>
</bpel:copy>

Maintain Multiple Versions of a BPEL Process

BPEL processes can be used to implement long lived stateful business processes. However the BPEL process may need to change, over the course of its lifetime, to accomodate new requirements.

This introduces the problem of how to deal with existing active instances of the BPEL process that may not complete for weeks, months or even years. In these situations we need to have a strategy for dealing with multiple version of a BPEL process, to enable new requirements to be introduced, while still preserving the original process definitions associated with existing active process instances.

This is achieved by simply associating a version number with the BPEL process by adding it as a suffix to the BPEL file name. For example, if our BPEL process would normally be located in the file 'HelloWorld.bpel', then we simply add a hyphen followed by the version number, e.g. 'HelloWorld-32.bpel' would indicate that this is the 32nd version of this BPEL process.

When a new version of the BPEL process has been defined, it is packaged in the SwitchYard application, along side the previous versions of the BPEL process. It is important that the older version of the BPEL process remain in the SwitchYard application until there are no longer any active process instances associated with that version.

It is then important that the SwitchYard application is re-deployed, without undeploying the previous version. If the previous version of the SwitchYard application is undeployed, it will cause the BPEL engine to delete all outstanding active instances associated with the process definitions that have bene removed.

Although the BPEL process is versioned, the WSDL interfaces are not. It is important to ensure that any changes made to the WSDL interfaces are backward compatible, so that both the new and older versions of the BPEL (that still have active process instances) are not affected by the changes.

Structure of a SwitchYard BPEL Application

The following image shows the structure of the say_hello SwitchYard BPEL quickstart:

The important part is how the artifacts are structured within the src/main/resources folder.

The switchyard.xml configuration file is located in the META-INF folder as usual. However the BPEL deployment descriptor (deploy.xml), and the BPEL process definition are located in the root folder.

The WSDL interface definitions, and any accompanying XSD schemas, can be located in sub-folders. If they are, then the BPEL process and SwitchYard BPEL component configuration must define the correct relative path.