JBoss SOA BPEL Guide

Procedure 4.1. Deploy the "BPEL ESB Hello World" Quickstart

1. Check that the JBoss Enterprise SOA Platform server is running.
2. Navigate to the directory containing the quickstarts: cd SOA_ROOT/samples/quickstarts/bpel_helloworld (or chdir SOA_ROOT\samples\quickstarts\bpel_helloworld in Microsoft Windows).
3. Deploy the quickstart by running ant deploy.
4. Execute the quickstart by running ant runtest.

Procedure 5.1. Task

1. Launch JBoss Developer Studio.
2. Create or import the JBDS BPEL project.
   (In this example, we are going to import an existing project from the SOA_ROOT/jboss-as/samples/quickstart/bpel_esb_helloworld directory).
   Select the Import menu item (found in JBDS's left-side navigation panel->General->Existing Projects into Workspace->Next.
3. Click the Browse button.
4. Navigate to the bpel_esb_helloworld quickstart directory.

   Note

   Once the project has been imported, you can inspect its contents, including the BPEL process and WSDL description.
5. Create a server configuration for the JBoss Enterprise SOA Platform. (The Server tab should be visible in the lower region of the JBDS window. If it is not present, click Window->Show Views->Servers.)
6. Right-click in the Servers view and select New->Server.
7. Select the appropriate version of the JBoss Enterprise SOA Platform.
8. Click Finish.
9. Start the new server by right-clicking on the server in the Servers tab and selecting Start.
   The output from the server will be displayed in the Console tab.
10. Once the server has been started, right-click on the server entry again, and select Add and Remove->bpel_esb_helloworld.
11. Click Add->Finish.
    The project deploys to the server. (It will show up as an entry below the server in the Servers tab.)
12. Test the deployed BPEL process by using the Ant script provided with the quick start sample. Right-click on the project root folder's build.xml file and select Run As->Ant Build.

    Note

    It is important to select the menu item with the "...", as this launches a dialogue box that enables you to select which Ant target you wish to utilise.
13. De-select the deploy target.
14. Select the runtest target.
15. Click the Run button.
    A test 'hello' message is now sent to the server, and the response is displayed in the Console tab.
16. To update the BPEL process, select assignHelloMesg->Properties->Details->Expression to Variable.
    You can update the concat function's second parameter in order to perform tasks such as adding UPDATED to the text.
17. Save the update.
18. Go to the Server view.
19. Click bpel_esb_helloworld>Full Publish.
    The project redeploys.
20. Re-run the runtest target within the build.xml file in order to send a new request and view the new response.
    The response should now reflect the changes you made in the BPEL process.
21. Go to the Server view and expand the deployed project node.
    You will see that both of the deployed versions are shown. (The older version is retained as there may still be BPEL process instances using that version of the process.)
22. Use the Server view's project menu and click Add and Remove to undeploy the project.

    Warning

    If you right-click on each of the child nodes, you will see it is also possible to undeploy the specific versions. However, if you do manually undeploy a version, any remaining active process instances for that version will be terminated.
23. Go to the Server menu item and stop the server.

Procedure 5.2. Task

1. Launch JBoss Developer Studio.
2. Right-click on the process and select WSDL.
3. Click on Web Services.
4. Click on Test with Web Service Explorer.
5. Launch JBoss Developer Studio.

Procedure 5.3. Task

1. Open the process' Apache Ant build script in your text editor.
2. Modify it appropriately. Here is an example:

   <!-- Import the base Ant build script... -->
   	<property file="../../../install/deployment.properties" />
   	
   	<property name="version" value="1" />
   	
   	<property name="server.dir" value="${org.jboss.as.home}/server/${org.jboss.as.config}"/>
   	<property name="conf.dir" value="${server.dir}/conf"/>
   	<property name="deploy.dir" value="${server.dir}/deploy"/>
   	<property name="server.lib.dir" value="${server.dir}/lib"/>
   
   	<property name="sample.jar.name" value="${ant.project.name}-${version}.jar" />
   	
   	<target name="deploy">
   		<echo>Deploy ${ant.project.name}</echo>
   		<jar basedir="bpel" destfile="${deploy.dir}/${sample.jar.name}" />
   	</target> 
    
   	<target name="undeploy">
   		<echo>Undeploy ${ant.project.name}</echo>
   		<delete file="${deploy.dir}/${sample.jar.name}" />
   </target>
   

   Copy to Clipboard Toggle word wrap
3. Save the file and exit.

Procedure 5.4. Task

1. Check to see if the processes have any active process instances.
2. If there are any, use the BPEL Web Console to retire them first.
3. Remove the processes only when there are no longer any active process instances.

Procedure 5.5. Task

1. Create a sample end-point file: vi SOA_ROOT/jboss-as/samples/quickstart/hello_world/bpelContent/test.endpoint.
2. Add the following content to it:

   # 3 minutes
   mex.timeout=180000
   

   Copy to Clipboard Toggle word wrap
3. Save the file and exit.
   Once deployed, the helloworld example will wait up to three minutes to respond.
4. To test this out, edit the hello_world.bpel file and insert a wait activity before the response:

   <wait>
   	<for>'PT150S'</for>
   </wait>
   

   Copy to Clipboard Toggle word wrap
   This will make it wait two minutes and thirty seconds before responding, which is thirty seconds longer than the default timeout, but still within the limits of the new timeout period specified within the test.endpoint file.
5. Save the file and exit.
6. If you wish to force the timeout to occur, increase the wait duration to three minutes and thirty seconds and re-submit the test message using the ant runtest command.

   Note

   The BPEL Web Console does not yet support the global configuration file, so it can only obtain the configuration data from the deployed BPEL bundle. (Specifically, it looks in the root location within the BPEL deployment unit alongside the BPEL deployment descriptor.)

Procedure 6.1. Task

1. Navigate to where you have placed your BPEL process definition and deployment descriptor.
2. Create a file called jws_handler.xml: vi jws_handler.xml.
3. Add your configuration settings to the file. Here is an example pertaining to the bpel_service_handler quickstart:

   <handler-chains xmlns="http://java.sun.com/xml/ns/javaee" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://java.sun.com/xml/ns/javaee">
       <handler-chain>
     <handler>
      <handler-name>JAXWSHandler</handler-name>
      <handler-class>org.jboss.soa.bpel.examples.jaxws.JAXWSHandler</handler-class>
      <init-param>
          <param-name>TestParam</param-name>
          <param-value>TestValue</param-value>
      </init-param>
     </handler>
       </handler-chain>
   </handler-chains>
   

   Copy to Clipboard Toggle word wrap
   This file is in the standard JAX-WS handler chain configuration format. One or more handler elements can be specified, with each handler defining a name and a class. (The handler configuration can optionally provide initialization parameters that are passed to the handler implementation's init method).
4. Save the file and exit.

   Note

   This mechanism only installs JAX-WS handlers on the provider web service. At present, you cannot configure JAX-WS handlers for the client end-points that are used to invoke external web services from a BPEL process.

   Note

   To learn more, study the example of this mechanism that is provided with the service_handler quick start.

Procedure 6.2. Task

1. Navigate to the directory containing the BPEL deployment descriptor.
2. Create a file called jbossws-cxf.xml: vi jbossws-cxf.xml
3. Add your configuration settings to the file. Here is an example:

    
   <beans
     xmlns='http://www.springframework.org/schema/beans'
     xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
     xmlns:beans='http://www.springframework.org/schema/beans'
     xmlns:jaxws='http://cxf.apache.org/jaxws'
     xsi:schemaLocation='http://cxf.apache.org/core
       http://cxf.apache.org/schemas/core.xsd
       http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
       http://cxf.apache.org/jaxws
       http://cxf.apache.org/schemas/jaxws.xsd'>
     
     <bean id="UsernameTokenSign_Request"
        class="org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor">
       <constructor-arg>
         <map>
           <entry key="action" value="UsernameToken Timestamp Signature"/> 
           <entry key="passwordType" value="PasswordDigest"/>
        <entry key="user" value="serverx509v1"/>
           <entry key="passwordCallbackClass"
             value="org.jboss.test.ws.jaxws.samples.wsse.ServerUsernamePasswordCallback"/> 
           <entry key="signaturePropFile" value="etc/Server_SignVerf.properties"/>
           <entry key="signatureKeyIdentifier" value="DirectReference"/>
         </map>
       </constructor-arg>
     </bean>
     
     <bean id="UsernameTokenSign_Response"
        class="org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor">
       <constructor-arg>
         <map>
           <entry key="action" value="UsernameToken Timestamp Signature"/> 
           <entry key="passwordType" value="PasswordText"/>
        <entry key="user" value="serverx509v1"/>
           <entry key="passwordCallbackClass"
             value="org.jboss.test.ws.jaxws.samples.wsse.ServerUsernamePasswordCallback"/> 
           <entry key="signaturePropFile" value="etc/Server_Decrypt.properties"/>
           <entry key="signatureKeyIdentifier" value="DirectReference"/>
           <entry key="signatureParts"
             value="{Element}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;{Element}{http://schemas.xmlsoap.org/soap/envelope/}Body"/>
         </map>
       </constructor-arg>
     </bean>
   
     <jaxws:endpoint
       id='SecureHelloWorldWS'
       address='http://@jboss.bind.address@:8080/Quickstart_bpel_secure_serviceWS'
       implementor='@provider@'>
       <jaxws:inInterceptors>
           <ref bean="UsernameTokenSign_Request"/>
           <bean class="org.apache.cxf.binding.soap.saaj.SAAJInInterceptor"/>
       </jaxws:inInterceptors>
       <jaxws:outInterceptors>
           <ref bean="UsernameTokenSign_Response"/>
           <bean class="org.apache.cxf.binding.soap.saaj.SAAJOutInterceptor"/>
       </jaxws:outInterceptors>
     </jaxws:endpoint>
     
     
   </beans>
   

   Copy to Clipboard Toggle word wrap
   This example code configures the web service to use the username token in conjunction with digital signature authentication.

   Note

   The jaxws:endpoint element has an attribute called implementor. This attribute defines the Java class implementing the JAX-WS service. The BPEL Console dynamically creates this class automatically. Therefore, it is important that the attribute is set to the value @provider@ or it will not work.
4. Save the file and exit.

Procedure 6.3. Task

1. To edit the sample jbossws-cxf-SecureHelloWorldPort.xml CXF configuration file, issue this command: vi SOA_ROOT/jboss-as/samples/quickstarts/bpel_secure_invoke/bpelContent/jbossws-cxf-SecureHelloWorldPort.xml
2. The configuration information contained within this file is for the CXF bus. Edit the file like this:

   <beans xmlns="http://www.springframework.org/schema/beans"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xmlns:cxf="http://cxf.apache.org/core"
          xmlns:wsa="http://cxf.apache.org/ws/addressing"
          xmlns:http="http://cxf.apache.org/transports/http/configuration"
          xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
          xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager"
       xmlns:beans='http://www.springframework.org/schema/beans'
       xmlns:jaxws='http://cxf.apache.org/jaxws'
       xmlns:ns1='http://secure_invoke/helloworld'
          xsi:schemaLocation="
          http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd
          http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd
          http://schemas.xmlsoap.org/ws/2005/02/rm/policy http://schemas.xmlsoap.org/ws/2005/02/rm/wsrm-policy.xsd
          http://cxf.apache.org/ws/rm/manager http://cxf.apache.org/schemas/configuration/wsrm-manager.xsd
          http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
    http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd">
   
     <bean id="UsernameTokenSign_Request"
        class="org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor" >
       <constructor-arg>
         <map>
           <entry key="action" value="UsernameToken Timestamp Signature"/> 
           <entry key="passwordType" value="PasswordDigest"/>
     <entry key="user" value="clientx509v1"/>
           <entry key="passwordCallbackClass"
             value="org.jboss.test.ws.jaxws.samples.wsse.ClientUsernamePasswordCallback"/> 
           <entry key="signaturePropFile" value="etc/Client_Sign.properties"/>
           <entry key="signatureKeyIdentifier" value="DirectReference"/>
           <entry key="signatureParts"
             value="{Element}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;{Element}{http://schemas.xmlsoap.org/soap/envelope/}Body"/>
         </map>
       </constructor-arg>
     </bean>
     
     <bean id="UsernameTokenSign_Response" 
        class="org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor" >
       <constructor-arg>
         <map>
           <entry key="action" value="UsernameToken Timestamp Signature"/> 
           <entry key="passwordType" value="PasswordText"/>
        <entry key="user" value="serverx509v1"/>
           <entry key="passwordCallbackClass" 
             value="org.jboss.test.ws.jaxws.samples.wsse.ClientUsernamePasswordCallback"/> 
           <entry key="signaturePropFile" value="etc/Client_Encrypt.properties"/>
           <entry key="signatureKeyIdentifier" value="DirectReference"/>
         </map>
       </constructor-arg>
     </bean>
     
     <cxf:bus>
       <cxf:outInterceptors>
           <ref bean="UsernameTokenSign_Request"/>
           <bean class="org.apache.cxf.binding.soap.saaj.SAAJOutInterceptor"/>
       </cxf:outInterceptors>
       <cxf:inInterceptors>
           <ref bean="UsernameTokenSign_Response"/>
           <bean class="org.apache.cxf.binding.soap.saaj.SAAJInInterceptor"/>
       </cxf:inInterceptors>
     </cxf:bus>
   
   </beans>
   

   Copy to Clipboard Toggle word wrap
   These settings configure the web service client to utilise the username token and digital signature authentication.
3. Save the file and exit.

Procedure 6.4. Task

1. Look up the end-point URL of the service which has the "?wsdl" suffix.
2. Once it is displayed, the <soap:address> will, by default, become associated with the server's "host bind" address.

   Note

   This address is defined in the ${jboss.bind.address} property.

Procedure 6.5. Task

1. Launch your test editor and create a new file.
2. Add the relative locations of the key-store and trust-store files.
3. Save the file as jboss-wsse-client.xml in the top level directory alongside your BPEL process and exit.

   Note

   For more information, see the secure_invoke_native quickstart.

Procedure 6.6. Task

1. Launch your test editor and create a new file.
2. Add the relative locations of the key-store and trust-store files.
3. Save the file as jboss-wsse-server.xml in the top level directory alongside your BPEL process and exit.

   Note

   For more information, see the secure_service_native quickstart.

Procedure 7.1. Task

1. Open a jboss-esb.xml file in your text editor.
2. Add the the BPELInvoke ESB action.
   The following example shows the action being used together with the bpel_esb_helloworld quickstart:

         <action name="action2" class="org.jboss.soa.esb.actions.bpel.BPELInvoke">
       <property name="service" value="{http://www.jboss.org/bpel/examples/wsdl}HelloService"/>
       <property name="port" value="HelloPort" />
       <property name="operation" value="hello" />
       <property name="requestPartName" value="TestPart" />
       <property name="responsePartName" value="TestPart" />
   </action>
   

   Copy to Clipboard Toggle word wrap
3. Save the file and exit.