Author: objectiser Date: 2010-05-28 10:39:11 -0400 (Fri, 28 May 2010) New Revision: 680 Added: trunk/docs/docbook/userguide/src/main/module/wsconfig.xml Modified: trunk/docs/docbook/userguide/src/main/master.xml Log: Added new section for WS configuration, and first sub-section on JAX-WS handlers. Modified: trunk/docs/docbook/userguide/src/main/master.xml =================================================================== --- trunk/docs/docbook/userguide/src/main/master.xml 2010-05-28 11:08:19 UTC (rev 679) +++ trunk/docs/docbook/userguide/src/main/master.xml 2010-05-28 14:39:11 UTC (rev 680) @@ -14,6 +14,7 @@ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/introduction.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/admin.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/deploy.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/wsconfig.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/uddi.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="module/esb.xml"/> </book> Added: trunk/docs/docbook/userguide/src/main/module/wsconfig.xml =================================================================== --- trunk/docs/docbook/userguide/src/main/module/wsconfig.xml (rev 0) +++ trunk/docs/docbook/userguide/src/main/module/wsconfig.xml 2010-05-28 14:39:11 UTC (rev 680) @@ -0,0 +1,93 @@ +<?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> + +</chapter>