This section outlines the mechanisms that are available for configuring the web service stack used in providing the web service for a BPEL process, as well as invoking external web services from a BPEL process.

JAX-WS is a standard Java API for client and server support of web services. The JAX-WS handler mechanism can be used by a client or server (i.e. the web service) to invoke a user specified class whenever a message (or fault) is sent or received. The handler is therefore installed into the message pipeline, and can manipulate the message header or body as required.

The handlers are usually installed either programmatically, or through a HandlerChain annotation on the Java interface representing the Web Service. However, in the case of a BPEL process deployed to RiftSaw, the JAX-WS service (representing the web service associated with the BPEL process) is dynamically created on deployment.

Therefore to associate the configuration of a JAX-WS handler chain with the Web Service dynamically created to support the BPEL process, the user must place a file called jws_handler.xml alongside the BPEL process definition and deployment descriptor.

The following provides an example of the XML configuration associated with the jws_handler.xml file. This particular example is used by the service_handler quickstart sample.

<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>                

                

The format of this file is the standard JAX-WS handler chain configuration. One or more handler elements can be specified, with each handler defining a name and class. The handler configuration can optionally provide initialization parameters that are passed to the init method on the handler implementation.

An example of this mechanism can be found in the service_handler quickstart sample.

RiftSaw integrates with JBossWS, using the JAX-WS standard API, to support the following web service stacks: JBossWS native and Apache CXF. This section explains how RiftSaw deployed BPEL processes can include additional configuration specifically applicable to the Apache CXF web service stack - and is therefore only relevant if the JBossAS application server has been configured to use this stack. See the Getting Started Guide for information on how to switch to the Apache CXF stack when installing RiftSaw.

This section will explain how web service endpoints, whether server (i.e. representing the BPEL process) or client (i.e. being used to invoke external web services), are configured using the Apache CXF configuration format. It will also discuss reasons why you may wish to do this additional CXF specific configuration. However, for further information on how to configure CXF, and the features that it offers, the reader is referred to the Apache CXF website http://cxf.apache.org.

<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>

                

<definitions name='SecureHelloWorldWSService'

        targetNamespace='http://secure_invoke/helloworld' .... >

    <portType name='SecureHelloWorld'>

        ...

    </portType>

    <service name='SecureHelloWorldWSService'>

       <port name='SecureHelloWorldPort' ... >

           ...

       </port>

    </service>

</definitions>

                

<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>

                

When a BPEL process is deployed, it results in a web service being created to represent the service endpoint, based on a WSDL description included with the deployed process. If the WSDL is displayed, using the endpoint URL of the service (with the ?wsdl suffix), then the <soap:address> by default will be associated with the host bind address of the server (as defined in the ${jboss.bind.address} property).

To change this default address, for example if wanting to present the web service via a firewall that has a different host address, then you will need to refer to the JBossWS documentation.

As an example, jbossws-native-3.2.2.GA uses a configuration file (${jbossas}/server/default/deployers/jbossws.deployer/META-INF/stack-agnostic-jboss-beans.xml) to define this information. The bean WSServerConfig has a property called webServiceHost that can be used to define the value to be used.