<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<chapter id="wsconfig">
  <title>Web Service Configuration</title>   
       
       <section>
       		<title>Overview</title>

       		<para>
       		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.
       		</para>
       		
       </section>
  
       <section>
       		<title>Configuring a JAX-WS Handler</title>

			<para>
			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.
			</para>
			
			<para>
			The handlers are usually installed either programmatically, or through a
			<emphasis>HandlerChain</emphasis> 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.
			</para>
			
			<para>
			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 <filename>jws_handler.xml</filename> alongside
			the BPEL process definition and deployment descriptor.
			</para>
       		
       		<para> 
       		The following provides an example of the XML configuration associated with
       		the <filename>jws_handler.xml</filename> file. This particular example is used by the
       		<emphasis>service_handler</emphasis> quickstart sample.
       		</para>
       		
			<informalexample>
  				<programlisting role="XML" ><![CDATA[
<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> 				 
				]]></programlisting>
			</informalexample>
       		
       		<para>
       		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 <emphasis>init</emphasis>
       		method on the handler implementation.
       		</para>

       		<note>
       		<para>
       		This mechanism only installs JAX-WS handlers on the 'provider' web service. It
       		is not currently possible to configure JAX-WS handlers for the client endpoints
       		that invoke external web services from a BPEL process.
       		</para>
       		</note>
       		
       		<para>
       		An example of this mechanism can be found in the <emphasis>service_handler</emphasis>
       		quickstart sample.
       		</para>
       		
       </section>
       
       <section>
       		<title>Apache CXF Configuration</title>
       		
       		<para>
       		RiftSaw integrates with JBossWS, using the JAX-WS standard API, to support the
       		following web service stacks: JBossWS native, Metro 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 <emphasis>Getting Started Guide</emphasis> for information on how to
       		switch to the Apache CXF stack when installing RiftSaw.
       		</para>
       		
       		<para>
       		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 <ulink url="http://cxf.apache.org/">http://cxf.apache.org</ulink>.
       		</para>
       		
       		<section>
      			<title>Configuring the Server endpoint</title>
      			
      			<para>
      			To create a CXF configuration that will be used by the RiftSaw web service provider
      			(i.e. the server), it is simply a case of placing a file called
      			<filename>jbossws-cxf.xml</filename> into the root folder of the BPEL deployment
      			(along side the deployment descriptor).
      			</para>
      			
      			<para>
      			This is the same filename as used by jbossws-cxf, when deploying a web service based
      			on the use of JAXWS annotations. An example of the file content is:
      			</para>
      			
			<informalexample>
  				<programlisting role="XML" ><![CDATA[
<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>
				]]></programlisting>
			</informalexample>

				<para>
				This example configures the web service to use username token and digital signature
				authentication.
				</para>
				
				<note>
				<para>
				The <emphasis>jaxws:endpoint</emphasis> element has an attribute called <emphasis>implementor</emphasis>
				that defines the Java class implementing the JAXWS service. RiftSaw dynamically creates this
				class, and therefore it is important that the attribute is set to the value <emphasis>@provider@</emphasis>
				to enable the dynamically created Java class to be correctly configured during deployment.
				</para>
				</note>		
       		</section>
      		
       		<section>
      			<title>Configuring the Client endpoint</title>
      			
      			<para>
      			When configuring client endpoints, representing web services invoked by a BPEL
      			process, the configuration is currently separated into different files on a per
      			port basis - similar to the approach used by the Axis2 ODE integration.
      			</para>
      			
      			<para>
      			The file name is of the form <filename>jbossws-cxf-{portname_local_part}.xml</filename>,
      			where the <emphasis>portname_local_part</emphasis> represents the local part of
      			the portname of the web service being invoked. For example, if the WSDL for the invoked
      			web service is:
     			</para>
     			
			<informalexample>
  				<programlisting role="XML" ><![CDATA[
<definitions name='SecureHelloWorldWSService'
		targetNamespace='http://secure_invoke/helloworld' .... >
    <portType name='SecureHelloWorld'>
        ...
    </portType>
    <service name='SecureHelloWorldWSService'>
       <port name='SecureHelloWorldPort' ... >
           ...
       </port>
    </service>
</definitions>
				]]></programlisting>
			</informalexample>
     			
     			<para>
     			then the CXF configuration file would be <filename>jbossws-cxf-SecureHelloWorldPort.xml</filename>.
     			</para>
     			
     			<para>
     			The CXF configuration information within this file is associated with the CXF bus. For
     			example:
     			</para>
     			
			<informalexample>
  				<programlisting role="XML" ><![CDATA[
<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>
				]]></programlisting>
			</informalexample>

				<para>
				This example configures the web service client to use username token and digital signature
				authentication.
				</para>      			
       		</section>
       </section>
</chapter>
