6:58 a.m.
Author: heiko.braun(a)jboss.com
Date: 2007-07-11 07:58:28 -0400 (Wed, 11 Jul 2007)
New Revision: 3847
Added:
tags/jbossws-2.0.0.GA/docs/
tags/jbossws-2.0.0.GA/docs/jaxrpc-userguide.xml
tags/jbossws-2.0.0.GA/docs/jaxws-userguide.xml
tags/jbossws-2.0.0.GA/docs/quickstart.xml
Log:
Exported WIKI documentation (docbook format)
Added: tags/jbossws-2.0.0.GA/docs/jaxrpc-userguide.xml
===================================================================
--- tags/jbossws-2.0.0.GA/docs/jaxrpc-userguide.xml (rev 0)
+++ tags/jbossws-2.0.0.GA/docs/jaxrpc-userguide.xml 2007-07-11 11:58:28 UTC (rev 3847)
@@ -0,0 +1,2010 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<book>
+<bookinfo><title>JBossWS 2.0.GA - JAX-RPC User
Guide</title><legalnotice><para>Permission to use, copy, modify and
distribute this document under the GNU Free Documentation License
(GFDL).</para></legalnotice></bookinfo><article
id="JAX_RPC_User_Guide">
+<title>JAX-RPC User Guide</title>
+<para>
+Category:Build and Deploy (Category:Build and Deploy)
+</para>
+<para>
+Since 1.2
+</para>
+<para>
+After JBoss J2EE-1.4 certification we have decided to develop our own JAXRPC SOAP stack
that fits better in the overall JBoss architecture and is generally more suiteable for the
specific J2EE requirements for web services. JBossWS is our new implementation of J2EE
compatible web services. This document describes the JAX-RPC feature set and its usage.
+</para>
+<para>
+In this guide we cover JAX-RPC functionality only, if you are looking for JavaEE5
compliant web services (i.e. the JAX-WS programming model) please goto the JAX-WS User
Guide.
+</para>
+<para>
+To get started you need to <emphasis
role="bold">download</emphasis> jbossws and <emphasis
role="bold">install</emphasis> JBossWS on your preferred target
container.
+</para>
+<para>
+This user guide applies to <emphasis
role="bold">jbossws-1.2.0</emphasis> and higher. For older versions,
please consult the <ulink
url="http://labs.jboss.com/portal/jbossws/user-guide/en/html/index.h...
User Guide</citetitle></ulink> on <ulink
url="http://labs.jboss.com/portal/jbossws"><citetitle>...;.
+</para>
+<section><title>Features</title>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+RPC style and Document style endpoints (wrapped and bare)
+</para>
+</listitem>
+<listitem>
+<para>
+SOAP header values bound/unbound to endpoint parameters
+</para>
+</listitem>
+<listitem>
+<para>
+J2EE endpoint development model for EJB and Java (JSR-109)
+</para>
+</listitem>
+<listitem>
+<para>
+J2EE client development model (JSR-109)
+</para>
+</listitem>
+<listitem>
+<para>
+Dynamic Invocation Interface (DII)
+</para>
+</listitem>
+<listitem>
+<para>
+JAX-RPC client/server side handlers
+</para>
+</listitem>
+<listitem>
+<para>
+Holders for INOUT/OUT parameters
+</para>
+</listitem>
+<listitem>
+<para>
+Message style endpoints
+</para>
+</listitem>
+<listitem>
+<para>
+Attachments Profile Version 1.0
+</para>
+</listitem>
+<listitem>
+<para>
+Dynamic client/server side handler injection
+</para>
+</listitem>
+<listitem>
+<para>
+WS-Security1.0 for XML Encryption/Signature of the SOAP message
+</para>
+</listitem>
+<listitem>
+<para>
+WS-Addressing (W3C candidate release) and JSR-261
+</para>
+</listitem>
+<listitem>
+<para>
+MTOM/XOP for optimized binary transport
+</para>
+</listitem>
+</itemizedlist>
+
+</section>
+<section><title>Installation</title>
+<para>
+Please refer to JAX-WS User Guide#Installation for details.
+</para>
+
+</section>
+<section><title>Getting started</title>
+<para>
+In order to get started we will begin with some simple endpoint implementations. This
chapter will walk you through the standard J2EE 1.4 development model and explore the
different style/use models to bind your endpoint implementations. A WSDL binding describes
how the service is bound to a messaging protocol, particularly the SOAP messaging
protocol. JBossWS conforms to the WS-I basic profile, which eliminates the encoded use.
This leaves you with the following style/use models:
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+RPC/Literal
+</para>
+</listitem>
+<listitem>
+<para>
+Document/Literal
+</para>
+</listitem>
+<listitem>
+<para>
+Message style
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Let's begin with a simple RPC web service endpoint implementation.
+</para>
+<section><title>Simple RPC Style Endpoint</title>
+<para>
+With RPC there is a wrapper element that names the endpoint operation. Child elements of
the RPC parent are the individual parameters. The SOAP body is constructed based on some
simple rules:
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+The port type operation name defines the endpoint method name
+</para>
+</listitem>
+<listitem>
+<para>
+Message parts are are endpoint method parameters
+</para>
+</listitem>
+</itemizedlist>
+<para>
+This chapter describes portable J2EE-1.4 web service endpoint development model for plain
java endpoints.
+</para>
+<para>
+Let's start with a trivial service endpoint interface (SEI) that has a single
operation, which takes two string parameters and returns a string.<programlisting>
public interface TrivialService extends
Remote</programlisting><programlisting>
{</programlisting><programlisting> String purchase (String person, String
product) throws RemoteException;</programlisting><programlisting>
}</programlisting>
+</para>
+<para>
+There are certain rules you have to follow for a valid SEI.
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+The SEI must extend java.rmi.Remote
+</para>
+</listitem>
+<listitem>
+<para>
+All methods must include java.rmi.RemoteException in their throws clause
+</para>
+</listitem>
+<listitem>
+<para>
+Method parameter types are limited to the ones specified by the JAXRPC-1.1 specification
+</para>
+</listitem>
+</itemizedlist>
+<para>
+<emphasis role="bold">The endpoint implementation bean</emphasis>
+</para>
+<para>
+The SEI defines the java contract of the web service. You will also need to provide an
implementation bean. Here it is<programlisting> public class TrivialEndpointJSE
implements TrivialService</programlisting><programlisting>
{</programlisting><programlisting> public String purchase (String person,
String product)</programlisting><programlisting>
{</programlisting><programlisting> log.info("purchase: " +
person + "," + product);</programlisting><programlisting>
return "ok" + person + product;</programlisting><programlisting>
}</programlisting><programlisting> }</programlisting>
+</para>
+<para>
+<emphasis role="bold">Generating required deployment
artifacts</emphasis>
+</para>
+<para>
+JSR-109 requires a number of deployment artifacts, which are:
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+webservices.xml, the descriptor that identifies a deployment a web service endpoint
+</para>
+</listitem>
+<listitem>
+<para>
+wsdl, the abstract webservice contract
+</para>
+</listitem>
+<listitem>
+<para>
+jaxrpc-mapping.xml, the mapping desriptor that bridges WSDL to java
+</para>
+</listitem>
+</itemizedlist>
+<para>
+JBossWS comes with a tool collection called WSTools. WSTools that can generate these
artifacts from the given SEI. There is a command line version and an Apache Ant task
available. Both take a configuration file as input. For details of the wstools
configuration, see #Apendix A
+</para>
+<para>
+<programlisting><configuration
...><java-wsdl><service name="SampleService"
style="rpc"
+
endpoint="org.jboss.test.ws.jaxrpc.samples.rpcstyle.TrivialService"/><namespaces
target-namespace="http://org.jboss.ws/samples/rpcstyle"
+
type-namespace="http://org.jboss.ws/samples/rpcstyle/types"/><mapping
file="jaxrpc-mapping.xml"/><webservices
servlet-link="TrivialEndpoint"/></java-wsdl></configuration></programlisting>
+</para>
+<para>
+You can run WSTools from the command line
+</para>
+<para>
+<programlisting>> jboss-inst/bin/wstools.sh -cp {path to
TrivialService.class} -config wstools-config.xml
+</programlisting>
+</para>
+<para>
+or from an ant task
+</para>
+<para>
+<programlisting><taskdef name="wstools"
classname="org.jboss.ws.tools.ant.wstools"><classpath
refid="library.classpath"/><classpath
refid="test.client.classpath"/><classpath
path="${build.test.classes.dir}"/></taskdef><wstools
dest="${build.wstools.resources.dir}/samples/rpcstyle/WEB-INF"
+
config="${test.resources.dir}/samples/rpcstyle/wstools-config.xml"/></programlisting>
+</para>
+<para>
+<emphasis role="bold"> The endpoint as a web
application</emphasis>
+</para>
+<para>
+A java service endpoint is deployed as a web application.
+</para>
+<para>
+<programlisting><web-app xmlns="http://java.sun.com/xml/ns/j2ee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
+ http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
+
version="2.4"><servlet><servlet-name>TrivialEndpoint</servlet-name>
+ (1)
<servlet-class>org.jboss.test.ws.jaxrpc.samples.rpcstyle.TrivialEndpointJSE</servlet-class></servlet><servlet-mapping><servlet-name>TrivialEndpoint</servlet-name><url-pattern>/*</url-pattern></servlet-mapping></web-app></programlisting>
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+The content of <servlet-class> element is not at all a servlet as required
by the servlet spec. It is the endpoint implementation bean that is shown above.
+</para>
+<para>
+<emphasis role="bold">Packaging the endpoint</emphasis>
+</para>
+<para>
+A JSR-109 java service endpoint (JSE) is packaged as a web application in a *.war file.
Note, that all descriptors are located in the WEB-INF directory with the WSDL in a
predefined subdirectory.
+</para>
+<para>
+<programlisting><war
warfile="${build.dir}/libs/jbossws-samples-rpcstyle.war"
+
webxml="${build.resources.dir}/samples/rpcstyle/WEB-INF/web.xml"><classes
dir="${build.dir}/classes"><include
name="org/jboss/test/ws/samples/rpcstyle/TrivialEndpointJSE.class"/><include
name="org/jboss/test/ws/samples/rpcstyle/TrivialService.class"/></classes><webinf
dir="${build.resources.dir}/samples/rpcstyle/WEB-INF"><include
name="jaxrpc-mapping.xml"/><include
name="webservices.xml"/><include
name="wsdl/**"/></webinf></war></programlisting>
+</para>
+<para>
+How a J2EE-1.4 portable web service client connects to the endpoint is described in
#JSR-109 Client Proxies
+</para>
+<para>
+<emphasis role="bold">SOAP message exchange</emphasis>
+</para>
+<para>
+Below you see the SOAP messages that are beeing exchanged.
+</para>
+<para>
+Incomming SOAPMessage<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/rpcstyle'><String_1>Kermit</String_1><String_2>Ferrari</String_2></ns1:purchase></env:Body></env:Envelope></programlisting>
+</para>
+<para>
+Outgoing SOAPMessage
+</para>
+<para>
+<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/rpcstyle'><result>okKermitFerrari</result></ns1:purchaseResponse></env:Body></env:Envelope></programlisting>
+</para>
+
+</section>
+<section><title>Document Style Endpoints</title>
+<para>
+With document style web services two business partners agree on the exchange of complex
business documents that are well defined in XML schema. For example, one party sends a
document describing a purchase order, the other responds (immediately or later) with a
document that describes the status of the purchase order. No need to agree on such low
level details as operation names and their associated parameters.
+</para>
+<para>
+The payload of the SOAP message is an XML document that can be validated against XML
schema. No wrapping RPC element, no individual parameters.
+</para>
+<para>
+In chapter we develop a document/literal wrapped service endpoint that uses the same
service endpoint interface (SEI) as for the #Simple RPC Style Endpoint example.
<programlisting> public interface TrivialService extends
Remote</programlisting><programlisting>
{</programlisting><programlisting> String purchase (String person, String
product) throws RemoteException;</programlisting><programlisting>
}</programlisting>
+</para>
+<para>
+<emphasis role="bold">Generating required deployment
artifacts</emphasis>
+</para>
+<para>
+Run wstools on a document/literal configuration
+</para>
+<para>
+The wsdlStyle attribute is set to 'document'
+</para>
+<para>
+<programlisting><configuration
...><java-wsdl><service name="SampleService"
style="document"
+ endpoint="org.jboss.test.ws.jaxrpc.samples.docstyle.wrapped.TrivialService"
/><namespaces
target-namespace="http://org.jboss.ws/samples/docstyle/wrapped"
+
type-namespace="http://org.jboss.ws/samples/docstyle/wrapped/types"/><mapping
file="jaxrpc-mapping.xml"/><webservices
servlet-link="TrivialEndpoint"/></java-wsdl></configuration></programlisting>
+</para>
+<para>
+The generated WSDL contains complex type definitions for the request/response payloads,
which are referenced from the WSDL messages
+</para>
+<para>
+<programlisting><complexType
name="purchase"><sequence><element
name="String_1" type="string"
nillable="true"/><element name="String_2"
type="string"
nillable="true"/></sequence></complexType><complexType
name="purchaseResponse"><sequence><element
name="result" type="string"
nillable="true"/></sequence></complexType></programlisting>
+</para>
+<para>
+WSTools also generates request/response java objects that correspond to these schema
types. These java wrapper beans are mapped in jaxrpc-mapping.xml
+</para>
+<para>
+<programlisting><java-xml-type-mapping><java-type>
+ org.jboss.test.ws.jaxrpc.samples.docstyle.wrapped.TrivialService_purchase_RequestStruct
+ </java-type><root-type-qname
xmlns:typeNS="http://org.jboss.ws/samples/docstyle/wrapped/types">
+ typeNS:purchase
+
</root-type-qname><qname-scope>complexType</qname-scope><variable-mapping><java-variable-name>String_1</java-variable-name><xml-element-name>String_1</xml-element-name></variable-mapping><variable-mapping><java-variable-name>String_2</java-variable-name><xml-element-name>String_2</xml-element-name></variable-mapping></java-xml-type-mapping><java-xml-type-mapping><java-type>
+
org.jboss.test.ws.jaxrpc.samples.docstyle.wrapped.TrivialService_purchase_ResponseStruct
+ </java-type><root-type-qname
xmlns:typeNS="http://org.jboss.ws/samples/docstyle/wrapped/types">
+ typeNS:purchaseResponse
+
</root-type-qname><qname-scope>complexType</qname-scope><variable-mapping><java-variable-name>result</java-variable-name><xml-element-name>result</xml-element-name></variable-mapping></java-xml-type-mapping></programlisting>
+</para>
+<para>
+<emphasis role="bold">SOAP message exchange</emphasis>
+</para>
+<para>
+Below you see the SOAP messages that are beeing exchanged.
+</para>
+<para>
+Incomming SOAPMessage
+</para>
+<para>
+<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/docstyle/wrapped/types'><String_1>Kermit</String_1><String_2>Ferrari</String_2></ns1:purchase></env:Body></env:Envelope></programlisting>
<programlisting> </programlisting>
+</para>
+<para>
+Outgoing SOAPMessage<programlisting> </programlisting>
+</para>
+<para>
+<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/docstyle/wrapped/types'><result>okKermitFerrari</result></ns1:purchaseResponse></env:Body></env:Envelope></programlisting>
<programlisting> </programlisting>
+</para>
+<para>
+On the wire the message structure is no different to rpc/literal.
+</para>
+<para>
+<emphasis role="bold">Document Bare Endpoints</emphasis>
+</para>
+<para>
+What we have seen above is a document/literal (wrapped) endpoint. The endpoint operation
paramters and return are automatically wrapped in request/response structures. The SEI
methods deal with the individual properties from these request/response structures.
+</para>
+<para>
+Whith document/literal (bare), the SEI methods deal directly with the request/response
structures.<programlisting> public interface TrivialService extends
Remote</programlisting><programlisting>
{</programlisting><programlisting> TrivialOrderResponse
purchase(TrivialOrder order) throws
RemoteException;</programlisting><programlisting> }</programlisting>
+</para>
+<para>
+Run wstools with the following configuration
+</para>
+<para>
+<programlisting><configuration
...><java-wsdl><service name="SampleService"
style="document" parameter-style="bare"
+ endpoint="org.jboss.test.ws.samples.docstyle.bare.TrivialService"
/><namespaces
target-namespace="http://org.jboss.ws/samples/docstyle/bare"
+
type-namespace="http://org.jboss.ws/samples/docstyle/bare/types"/><mapping
file="jaxrpc-mapping.xml"/><webservices
servlet-link="TrivialEndpoint"/></java-wsdl></configuration></programlisting>
+</para>
+<para>
+<emphasis role="bold">SOAP message exchange</emphasis>
+</para>
+<para>
+Below you see the SOAP messages that are beeing exchanged.
+</para>
+<para>
+Incomming SOAPMessage
+</para>
+<para>
+<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/docstyle/bare/types'><person>Kermit</person><product>Ferrari</product></ns1:purchase></env:Body></env:Envelope></programlisting>
+</para>
+<para>
+Outgoing SOAPMessage<programlisting> </programlisting>
+</para>
+<para>
+<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/docstyle/bare/types'><result>okKermitFerrari</result></ns1:purchaseResponse></env:Body></env:Envelope></programlisting>
+</para>
+<para>
+On the wire the message structure is no different to document/literal wrapped. That the
implementation deals with the wrapper beans directly is an implementation detail.
+</para>
+
+</section>
+<section><title>Message Style Endpoints</title>
+<para>
+You may come to the point where RPC/Literal or Document/Literal is not what you are
looking for. This may be the case for instance, when you want to do the XML processing
yourself instead of deferring it to the SOAP stack. JBossWS offers the possiblity to setup
message style endpoints that do exchange raw XML documents mapped to DOM elements or
SOAPElements,
+</para>
+<para>
+This chapter describes a generic endpoint that can process arbitrary DOM elements.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+In the JAX-RPC specification this is not a permitted java type. JBossWS extends the
standard type support by DOM Element and SOAPElement.<programlisting> public
interface MessageTestService extends Remote</programlisting><programlisting>
{</programlisting><programlisting> public Element processElement(Element
msg) throws RemoteException;</programlisting><programlisting>
}</programlisting>
+</para>
+<para>
+<emphasis role="bold">Generating required deployment
artifacts</emphasis>
+</para>
+<para>
+Run wstools with the following configuration
+</para>
+<para>
+<programlisting><configuration
...><java-wsdl><service name="MessageService"
style="document" parameter-style="bare"
+
endpoint="org.jboss.test.ws.jaxrpc.samples.message.MessageTestService"><operation
name="processElement"
return-xml-name="Response"><parameter
type="javax.xml.soap.SOAPElement"
xml-name="Order"/></operation></service><namespaces
target-namespace="http://org.jboss.ws/samples/message"
+
type-namespace="http://org.jboss.ws/samples/message/types"/><mapping
file="jaxrpc-mapping.xml"/><webservices
servlet-link="TestService"/></java-wsdl></configuration></programlisting>
+</para>
+<para>
+WSTools generates schema elements with xsd:anyType
+</para>
+<para>
+<programlisting><schema
targetNamespace="http://org.jboss.ws/samples/message" ...><element
name="Order" type="anyType"/><element
name="Response"
type="anyType"/></schema><message
name="Message_processElement"><part name="order"
element="tns:Order"/></message><message
name="Message_processElementResponse"><part
name="result"
element="tns:Response"/></message></programlisting>
+</para>
+
+</section>
+
+</section>
+<section><title>Web Service Endpoints</title>
+<para>
+In the previous chapter we have seen how to package and deploy simple endpoints that were
all based on POJO implementations. If you really want to leverage J2EE technologies it
might be more appropriate to use EJB endpoint implementations. In this chapter we will use
EJB-2.1 stateless session beans as web service endpoints. To expose an EJB3 stateless
session bean using JAX-WS annotations have a look at the JAX-WS User Guide.
+</para>
+<para>
+JSR-109 promotes building portable web services in the J2EE 1.4 environment. It leverages
J2EE technologies to provide a standard for developing and deploying web services on the
J2EE platform.
+</para>
+<section><title>JSR-109 POJO Endpoint</title>
+<para>
+This chapter uses a more complex service endpoint interface (SEI) as in #Document Style
Endpoints. It contains a user defined type as one of the opertion parameters.
<programlisting> public interface JaxRpcTestService extends
Remote</programlisting><programlisting>
{</programlisting><programlisting> String echoString(String str1, String
str2) throws RemoteException;</programlisting><programlisting>
</programlisting><programlisting> SimpleUserType
echoSimpleUserType(String str1, SimpleUserType msg) throws
RemoteException;</programlisting><programlisting> }</programlisting>
+</para>
+<para>
+<emphasis role="bold">Generating required deployment
artifacts</emphasis>
+</para>
+<para>
+Run wstools with the following configuration
+</para>
+<para>
+<programlisting><configuration
...><java-wsdl><service name="TestService"
style="rpc"
+
endpoint="org.jboss.test.ws.jaxrpc.samples.jsr109pojo.JaxRpcTestService"/><namespaces
target-namespace="http://org.jboss.ws/samples/jsr109pojo"
+
type-namespace="http://org.jboss.ws/samples/jsr109pojo/types"/><mapping
file="jaxrpc-mapping.xml"/><webservices
servlet-link="TestService"/></java-wsdl></configuration></programlisting>
+</para>
+<para>
+WSTools generates request/response java objects that correspond to these schema types and
that are mapped in jaxrpc-mapping.xml.
+</para>
+<para>
+<emphasis role="bold">SOAP message exchange</emphasis>
+</para>
+<para>
+Incomming SOAPMessage
+</para>
+<para>
+<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/jsr109pojo'><String_1>Hello</String_1><SimpleUserType_2><a>1</a><b>2</b></SimpleUserType_2></ns1:echoSimpleUserType></env:Body></env:Envelope></programlisting>
+</para>
+<para>
+Outgoing SOAPMessage
+</para>
+<para>
+<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/jsr109pojo'><result><a>1</a><b>2</b></result></ns1:echoSimpleUserTypeResponse></env:Body></env:Envelope></programlisting>
+</para>
+
+</section>
+<section><title>JSR-109 EJB Endpoint</title>
+<para>
+This chapter uses the same service endpoint interface (SEI) as in #JSR-109 POJO Endpoint.
<programlisting> public interface JaxRpcTestService extends
Remote</programlisting><programlisting>
{</programlisting><programlisting> String echoString(String str1, String
str2) throws RemoteException;</programlisting><programlisting>
</programlisting><programlisting> SimpleUserType
echoSimpleUserType(String str1, SimpleUserType msg) throws
RemoteException;</programlisting><programlisting> }</programlisting>
+</para>
+<para>
+<emphasis role="bold">Generating required deployment
artifacts</emphasis>
+</para>
+<para>
+Run wstools with the following configuration
+</para>
+<para>
+<programlisting><configuration
...><java-wsdl><service name="TestService"
style="rpc"
+
endpoint="org.jboss.test.ws.jaxrpc.samples.jsr109ejb.JaxRpcTestService"/><namespaces
target-namespace="http://org.jboss.ws/samples/jsr109ejb"
+
type-namespace="http://org.jboss.ws/samples/jsr109ejb/types"/><mapping
file="jaxrpc-mapping.xml"/><webservices
ejb-link="TestService"/></java-wsdl></configuration>
</programlisting>
+</para>
+<para>
+<emphasis role="bold">The EJB deployment descriptor</emphasis>
+</para>
+<para>
+The attribute value for ejbLink element corresponds to ejb-name given in ejb-jar.xml. In
this example, the stateless session bean (SLSB) is only exposed as a service endpoint, it
does not have a Home nor Remote interface
+</para>
+<para>
+<programlisting><enterprise-beans><session><ejb-name>TestService</ejb-name>
+ (1) <service-endpoint>
+ org.jboss.test.ws.jaxrpc.samples.jsr109ejb.JaxRpcTestService
+ </service-endpoint>
+ (2)
<ejb-class>org.jboss.test.ws.jaxrpc.samples.jsr109ejb.JaxRpcEJBEndpoint</ejb-class><session-type>Stateless</session-type><transaction-type>Container</transaction-type></session></enterprise-beans></programlisting>
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+Exposing an SEI as a webservice endpoint
+</para>
+</listitem>
+<listitem>
+<para>
+The SLSB endpoint implementation
+</para>
+</listitem>
+</orderedlist>
+
+</section>
+<section><title>ServiceLifecycle and MessageContext</title>
+<para>
+<emphasis role="bold">Adding Service Lifecycle</emphasis>
+</para>
+<para>
+Your POJO endpoint may implement javax.xml.rpc.server.ServiceLifecycle to obtain access
to the javax.xml.rpc.server.ServletEndpointContext int the init() method.
+</para>
+<para>
+The ServletEndpointContext provides an endpoint context maintained by the underlying
servlet container based JAX-RPC runtime system. For service endpoints deployed on a
servlet container based JAX-RPC runtime system, the context parameter in the
ServiceLifecycle.init method is required to be of the Java type
javax.xml.rpc.server.ServletEndpointContext.
+</para>
+<para>
+A servlet container based JAX-RPC runtime system implements the ServletEndpointContext
interface. The JAX-RPC runtime system is required to provide appropriate session, message
context, servlet context and user principal information per method invocation on the
endpoint class.<programlisting> public class JaxRpcJSEEndpoint implements
JaxRpcTestService, ServiceLifecycle</programlisting><programlisting>
{</programlisting><programlisting> private ServletEndpointContext
context;</programlisting><programlisting>
</programlisting><programlisting> public String echoString(String str1,
String str2)</programlisting><programlisting>
{</programlisting><programlisting> log.info("echoString: " +
str1 + "," + str2);</programlisting><programlisting>
log.info("userPricipal: " +
context.getUserPrincipal());</programlisting><programlisting> return
str1 + str2;</programlisting><programlisting>
}</programlisting><programlisting> </programlist!
ing><programlisting> public void init(Object context) throws
ServiceException</programlisting><programlisting>
{</programlisting><programlisting> this.context =
(ServletEndpointContext)context;</programlisting><programlisting>
}</programlisting><programlisting>
</programlisting><programlisting> public void
destroy()</programlisting><programlisting>
{</programlisting><programlisting>
}</programlisting><programlisting> }</programlisting>
+</para>
+<para>
+Currently, POJO endpoints are not pooled like their EJB counterparts. As a consequence
and because WS4EE endpoints are essentially stateless, you will get a new instance of the
endpoint implementation bean for every request. For stateful behaviour see
#WS-Addressing.
+</para>
+
+</section>
+<section><title>Endpoint configuration</title>
+<para>
+Configuration templates provide a convenient way to setup a handler configuration for
JBossWS endpoints. A configuration basically includes a list of handlers that are
registered with a web service endpoint upon deployment. For details see #Headers &
Handlers
+</para>
+<para>
+<programlisting><jbossws-config
xmlns="urn:jboss:jbossws-config:5.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:j2ee="http://java.sun.com/xml/ns/j2ee"
+ xsi:schemaLocation="urn:jboss:jbossws-config:5.0
http://www.jboss.com/xml/jbossws-config_1_0.xsd"><endp...
Endpoint</config-name></endpoint-config><endpoint-config><config-name>Standard
Secure
Endpoint</config-name><pre-handler-chain><handler-chain-name>PreHandlerChain</handler-chain-name><handler><j2ee:handler-name>WSSecurityHandlerInbound</j2ee:handler-name><j2ee:handler-class>org.jboss.ws.extensions.security.jaxrpc.WSSecurityHandlerInbound</j2ee:handler-class></handler></pre-handler-chain></endpoint-config></jbossws-config></programlisting>
+</para>
+<para>
+These template configurations can be referenced from any jboss specific deplyoment
descriptor, i.e:
+</para>
+<para>
+<programlisting><jboss-client><jndi-name>jbossws-client</jndi-name><service-ref><service-ref-name>service/HelloService</service-ref-name><config-name>Standard
Secure
Client</config-name><wsdl-override>http://@jbosstest.host.name@:8080/jbossws-samples-wssecurity-encrypt?wsdl</wsdl-override></service-ref></jboss-client></programlisting>
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+This is a proprietary configuration mechanism. In order to stay portable it's
recommended to use the default JAXRPC handler configuration.
+</para>
+<para>
+<emphasis role="bold">Configuration reference from
web.xml</emphasis>
+</para>
+<para>
+Within web.xml the same approach can be taken.
+</para>
+<para>
+<programlisting><web-app ...><context-param>
+ (1) <param-name>jbossws-config-name</param-name>>
+ (2) <param-value>Standard Secure
Endpoint</param-value></context-param><servlet><servlet-name>HelloService</servlet-name><servlet-class>org.jboss.test.ws.jaxrpc.samples.wssecurity.HelloJavaBean</servlet-class></servlet><servlet-mapping><servlet-name>HelloService</servlet-name><url-pattern>/*</url-pattern></servlet-mapping></web-app></programlisting>
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+predefined servlet context parameter
+</para>
+</listitem>
+<listitem>
+<para>
+chosen endpoint config
+</para>
+</listitem>
+</orderedlist>
+
+</section>
+
+</section>
+<section><title>Web Services Clients</title>
+<section><title>Client Proxies</title>
+<para>
+<emphasis role="bold">A web service client connecting to an
endpoint</emphasis>
+</para>
+<para>
+The web service client programming model for J2EE is about accessing a remote web service
from a J2EE component. Please remember that with web services the client and the server
are fundamentally disconnected. There are server side issues and client side issues. In
other words, if you setup a web service endpoint any client that adhers to the abstract
contract in WSDL can talk to that endpoint.
+</para>
+<para>
+If you want to implement a WS client using JBossWS (to what server impl it talks to does
not matter) you use wstools to generate the required artifacts from WSDL. The artifacts
are
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+Required Service Endpoint Interface (SEI)
+</para>
+</listitem>
+<listitem>
+<para>
+Optional User Types
+</para>
+</listitem>
+<listitem>
+<para>
+Optional User Exceptions
+</para>
+</listitem>
+<listitem>
+<para>
+Required WSDL/Java mapping meta data (jaxrpc-mapping.xml)
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Here a wstools config file that generates the client side artifacts from WSDL
+</para>
+<para>
+<programlisting><configuration ...><wsdl-java
file="resources/samples/jsr181pojo/META-INF/wsdl/TestService.wsdl"><mapping
file="jaxrpc-mapping.xml"
/></wsdl-java></configuration></programlisting>
+</para>
+<para>
+This chapter uses a J2EE-1.4 client, but for all intents and purposes, this could also be
a Servlet, JSP, or EJB component. All of these J2EE components support
<service-ref> elements in their respective deployment descriptor.
+</para>
+<para>
+The J2EE client deployment model has many advantages over dynamic invocation (DII). Most
Java applications (except the most trivial ones) have a need for registry lookup (JNDI)
and management (JMX). A very minimal jboss configuration has a tiny footprint and provides
just that. Therefore, running your client app on jboss and mangage it through JMX and have
a layer of indirection for resource lookup through JNDI is recommended pratice.
Additionally, you can leverage the J2EE 1.4 client programming model and obtain
preconfigured web service clients from JNDI.
+</para>
+<para>
+<programlisting><service-ref><service-ref-name>service/TrivialService</service-ref-name><service-interface>javax.xml.rpc.Service</service-interface><wsdl-file>META-INF/wsdl/SampleService.wsdl</wsdl-file><jaxrpc-mapping-file>META-INF/jaxrpc-mapping.xml</jaxrpc-mapping-file><port-component-ref><service-endpoint-interface>org.jboss.test.ws.jaxrpc.samples.rpcstyle.TrivialService</service-endpoint-interface></port-component-ref></service-ref>
</programlisting>
+</para>
+<para>
+With the configuration given above, the SampleService.wsdl must contain the correct SOAP
target address. JBoss provides an override mechanism for the WSDL in jboss-client.xml.
+</para>
+<para>
+<programlisting><jboss-client><jndi-name>jbossws-client</jndi-name><service-ref><service-ref-name>service/TrivialService</service-ref-name><wsdl-override>http://jbosstesthost:8080/jbossws-samples-rpcstyle?wsdl</wsdl-override></service-ref></jboss-client></programlisting>
+</para>
+<para>
+When the WSDL is obtained from the server, the server has already performed all the
necessary address rewrites
+</para>
+<para>
+Once the J2EE application client jar is deployed on a JBoss instance, it can be accessed
by a separate standalone Java process.<programlisting> public void
testTrivialAccess() throws Exception</programlisting><programlisting>
{</programlisting><programlisting> InitialContext iniCtx =
getInitialContext();</programlisting><programlisting> Service service =
(Service)iniCtx.lookup("java:comp/env/service/TrivialService");</programlisting><programlisting>
TrivialService port =
(TrivialService)service.getPort(TrivialService.class);</programlisting><programlisting>
String person = "Kermit";</programlisting><programlisting>
String product = "Ferrari";</programlisting><programlisting>
String status = port.purchase(person,
product);</programlisting><programlisting> assertEquals("ok" +
person + product, status);</programlisting><programlisting>
}</programlisting><programlisting>
</programlisting><programlisting> protected InitialC!
ontext getInitialContext() throws
NamingException</programlisting><programlisting>
{</programlisting><programlisting> InitialContext iniCtx = new
InitialContext();</programlisting><programlisting> Hashtable env =
iniCtx.getEnvironment();</programlisting><programlisting>
env.put(Context.URL_PKG_PREFIXES,
"org.jboss.naming.client");</programlisting><programlisting>
env.put("j2ee.clientName",
"jbossws-client");</programlisting><programlisting> return new
InitialContext(env);</programlisting><programlisting>
}</programlisting>
+</para>
+
+</section>
+<section><title>Stub properties</title>
+<para>
+<emphasis role="bold">Standard JAXRPC Stub properties</emphasis>
+</para>
+<para>
+<programlisting>
+ /** User name for authentication. */
+ public static final String USERNAME_PROPERTY =
"javax.xml.rpc.security.auth.username";
+
+ /** Password for authentication. */
+ public static final String PASSWORD_PROPERTY =
"javax.xml.rpc.security.auth.password";
+
+ /** Target service endpoint address. */
+ public static final String ENDPOINT_ADDRESS_PROPERTY =
"javax.xml.rpc.service.endpoint.address";
+
+ /**
+ This boolean property is used by a service client to indicate
+ whether or not it wants to participate in a session with a service endpoint.
+ */
+ public static final String SESSION_MAINTAIN_PROPERTY =
"javax.xml.rpc.session.maintain";
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">JBossWS propriatary Stub
properties</emphasis>
+</para>
+<para>
+The propriatary properties are defined in org.jboss.ws.core.StubExt
+</para>
+<para>
+<programlisting>
+ /** ClientTimeout property: org.jboss.ws.timeout */
+ static final String PROPERTY_CLIENT_TIMEOUT = "org.jboss.ws.timeout";
+
+ /** KeyStore property: org.jboss.ws.keyStore */
+ static final String PROPERTY_KEY_STORE = "org.jboss.ws.keyStore";
+
+ /** KeyStorePassword property: org.jboss.ws.keyStorePassword */
+ static final String PROPERTY_KEY_STORE_PASSWORD =
"org.jboss.ws.keyStorePassword";
+
+ /** KeyStoreType property: org.jboss.ws.keyStoreType */
+ static final String PROPERTY_KEY_STORE_TYPE = "org.jboss.ws.keyStoreType";
+
+ /** TrustStore property: org.jboss.ws.trustStore */
+ static final String PROPERTY_TRUST_STORE = "org.jboss.ws.trustStore";
+
+ /** TrustStorePassword property: org.jboss.ws.trustStorePassword */
+ static final String PROPERTY_TRUST_STORE_PASSWORD =
"org.jboss.ws.trustStorePassword";
+
+ /** TrustStoreType property: org.jboss.ws.trustStoreType */
+ static final String PROPERTY_TRUST_STORE_TYPE =
"org.jboss.ws.trustStoreType";
+
+ /** Authentication type, used to specify basic, etc) */
+ static final String PROPERTY_AUTH_TYPE = "org.jboss.ws.authType";
+
+ /** Authentication type, BASIC */
+ static final String PROPERTY_AUTH_TYPE_BASIC = "org.jboss.ws.authType.basic";
+
+ /** Authentication type, WSEE */
+ static final String PROPERTY_AUTH_TYPE_WSSE = "org.jboss.ws.authType.wsse";
+
+ /** Enable MTOM on the stub */
+ static final String PROPERTY_MTOM_ENABLED= "org.jboss.ws.mtom.enabled";
+</programlisting>
+</para>
+
+</section>
+<section><title>Dynamic Invocation Interface</title>
+<para>
+<emphasis role="bold">An unconfigured DII client</emphasis>
+</para>
+<para>
+In the case of DII the client sets up the call object manually. This involves setting the
operation name and in/out parameters explicitly. There is no WSDL as abstract contract for
the web service communication involved. Of all the web service client technologies, this
is the least favorable.
+</para>
+<para>
+<programlisting>
+ public void testEchoString() throws Exception
+ {
+ ServiceFactory factory = ServiceFactory.newInstance();
+ Service service = factory.createService(new QName("ANY_SERVICE_NAME"));
+
+ Call call = service.createCall();
+ call.setOperationName(new QName(TARGET_NAMESPACE, "echoString"));
+ call.addParameter("String_1", Constants.TYPE_LITERAL_STRING,
ParameterMode.IN);
+ call.addParameter("String_2", Constants.TYPE_LITERAL_STRING,
ParameterMode.IN);
+ call.setReturnType(Constants.TYPE_LITERAL_STRING);
+
+ call.setTargetEndpointAddress(TARGET_ENDPOINT_ADDRESS);
+
+ String hello = "Hello";
+ String world = "world!";
+ Object retObj = call.invoke(new Object[]{hello, world});
+ assertEquals(hello + world, retObj);
+ }
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">A configured DII client</emphasis>
+</para>
+<para>
+A DII client can be configured from WSDL<programlisting> public void
testEchoString() throws Exception</programlisting><programlisting>
{</programlisting><programlisting> ServiceFactory factory =
ServiceFactory.newInstance();</programlisting><programlisting> URL
wsdlLocation = new URL(TARGET_ENDPOINT_ADDRESS +
"?wsdl");</programlisting><programlisting> QName serviceName =
new QName(TARGET_NAMESPACE,
"TestService");</programlisting><programlisting> ServiceImpl
service = (ServiceImpl)factory.createService(wsdlLocation,
serviceName);</programlisting><programlisting> call =
service.createCall();</programlisting><programlisting>
</programlisting><programlisting> QName operationName = new
QName(TARGET_NAMESPACE,
"echoString");</programlisting><programlisting>
call.setOperationName(operationName);</programlisting><programlisting>
assertFalse(call.isParameterAndReturnSpecRequired(operationName));</programlisting><programlist!
ing> </programlisting><programlisting> String hello =
"Hello";</programlisting><programlisting> String world =
"world!";</programlisting><programlisting> Object retObj =
call.invoke(new Object[]{hello, world});</programlisting><programlisting>
assertEquals(hello + world, retObj);</programlisting><programlisting>
}</programlisting>
+</para>
+<para>
+Note however, that the above example does not have a notion of JAXRPC mapping. The
abstract contract is given as an URL to the WSDL, but it is not expicitly said how the
various types in XML schema map to Java types. It works, because above we only use
strings. It would not work if complex user types were involved. Prior to standard J2EE-1.4
web services frameworks fell back to Java reflection to provide the mapping meta data.
+</para>
+<para>
+With JSR109 we have a standard mapping metadata format usually provided through
jaxrpc-mapping.xml. The name of the file is however not standardized. Unfortunately the
standard JAXRPC API does not accommodate this mapping information because it predates
JSR109. In JBossWS you have the option to use a propriatary API method or rely on
autodiscovery of META-INF/jaxrpc-mapping.xml.
+</para>
+<para>
+Here the propriatary API methods that we provide in
org.jboss.ws.jaxrpc.ServiceFactoryImpl
+</para>
+<para>
+<programlisting>
+ /**
+ * Create a <code>Service</code> instance.
+ *
+ * @param wsdlURL URL for the WSDL document location
+ * @param serviceName QName for the service.
+ * @param mappingURL URL for the jaxrpc-mapping.xml document location
+ */
+ public Service createService(URL wsdlURL, QName serviceName, URL mappingURL) throws
ServiceException
+ {
+ ...
+ }
+
+ /**
+ * Create a <code>Service</code> instance.
+ *
+ * @param wsdlURL URL for the WSDL document location
+ * @param serviceName QName for the service.
+ * @param mappingURL URL for the jaxrpc-mapping.xml document location
+ * @param securityURL URL for the jbossws-security.xml file
+ */
+ public Service createService(URL wsdlURL, QName serviceName, URL mappingURL, URL
securityURL) throws ServiceException
+ {
+ ...
+ }
+</programlisting>
+</para>
+
+</section>
+<section><title>Using SOAPConnection</title>
+<para>
+It is possible to use the standard javax.xml.soap.SOAPConnection to dispatch a precreated
SOAP message to a given endpoint
+</para>
+<para>
+<programlisting>
+ public void testSAAJClientFromEnvelope() throws Exception
+ {
+ MessageFactory mf = MessageFactory.newInstance();
+ SOAPMessage reqMsg = mf.createMessage();
+
+ String request =
+ "<ns1:Order xmlns:ns1='" + TARGET_NAMESPACE +
+ "' xmlns:ns2='http://somens' attrval='somevalue'>"
+
+ "<ns2:Customer>Kermit</ns2:Customer>" +
+ "<Item>Ferrari</Item>" +
+ "</ns1:Order>";
+
+ DocumentBuilder builder = getDocumentBuilder();
+ Document doc = builder.parse(new ByteArrayInputStream(request.getBytes()));
+ reqMsg.getSOAPBody().addDocument(doc);
+
+ SOAPConnectionFactory conFactory = SOAPConnectionFactory.newInstance();
+ SOAPConnection con = conFactory.createConnection();
+ SOAPMessage resMsg = con.call(reqMsg, new URL(TARGET_ENDPOINT));
+
+ SOAPBody soapBody = resMsg.getSOAPBody();
+ SOAPElement soapElement = (SOAPElement)soapBody.getChildElements().next();
+
+ validateResponse(soapElement);
+ }
+</programlisting>
+</para>
+
+</section>
+
+</section>
+<section><title>Headers & Handlers</title>
+<section><title>Bound SOAP Headers</title>
+<para>
+Bound SOAP header elements are visible on the SEI as operation parameters, unbound SOAP
headers are not. Both, bound and unbound headers are visible to JAXRPC handlers. Here is
an example that uses bound headers on three SEI methods.<programlisting> public
interface HeaderTestService extends Remote</programlisting><programlisting>
{</programlisting><programlisting> void testInHeader(String bodyMsg,
String headerMsg) throws RemoteException;</programlisting><programlisting>
</programlisting><programlisting> void testInOutHeader(String bodyMsg,
StringHolder headerMsg) throws
RemoteException;</programlisting><programlisting>
</programlisting><programlisting> void testOutHeader(String bodyMsg,
StringHolder headerMsg) throws
RemoteException;</programlisting><programlisting> }</programlisting>
+</para>
+<para>
+A bound header is a message part that is explicitly bound with the
<soap:header> element in the WSDL binding.
+</para>
+<para>
+<programlisting><message
name="HeaderTestService_testInHeader"><part
name="String_1" type="xsd:string"/><part
name="String_2"
type="xsd:string"/></message><portType
name="HeaderTestService"><operation name="testInHeader"
parameterOrder="String_1 String_2"><input
message="tns:HeaderTestService_testInHeader"/><output
message="tns:HeaderTestService_testInHeaderResponse"/></operation>
+ ...
+ </portType><binding name="HeaderTestServiceBinding"
type="tns:HeaderTestService"><soap:binding
transport="http://schemas.xmlsoap.org/soap/http"
style="rpc"/><operation
name="testInHeader"><soap:operation
soapAction=""/><input><soap:body
use="literal"
namespace="http://org.jboss.ws/samples/handler"/><soap:header
message="tns:HeaderTestService_testInHeader"
+ part="String_2" use="literal"
namespace="http://somens"/></input><output><soap:body
use="literal"
namespace="http://org.jboss.ws/samples/handler"/></output></operation>
+ ...
+ </binding></programlisting>
+</para>
+<para>
+<emphasis role="bold">SOAP message exchange</emphasis>
+</para>
+<para>
+Below you see the SOAP messages that are beeing exchanged.
+</para>
+<para>
+Incomming SOAPMessage
+</para>
+<para>
+<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns2='http://somens'>IN header
message</ns2:String_2></env:Header><env:Body><ns1:testInHeader
xmlns:ns1='http://org.jboss.ws/samples/handler'><String_1>Hello
world!</String_1></ns1:testInHeader></env:Body></env:Envelope></programlisting>
+</para>
+<para>
+Outgoing SOAPMessage<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/handler'/></env:Body></env:Envelope></programlisting>
+</para>
+
+</section>
+<section><title>Unbound SOAP Headers</title>
+<para>
+Unbound SOAP header elements are not visible on SEI methods, but in JAXRPC handlers
through the SAAJ API.
+</para>
+<para>
+<programlisting>
+ public class ServerSideHandler extends GenericHandler
+ {
+ public boolean handleResponse(MessageContext msgContext)
+ {
+ log.info("handleResponse");
+
+ try
+ {
+ SOAPMessage soapMessage = ((SOAPMessageContext)msgContext).getMessage();
+ SOAPHeader soapHeader = soapMessage.getSOAPHeader();
+
+ SOAPBody soapBody = soapMessage.getSOAPBody();
+ SOAPBodyElement soapBodyElement =
+ (SOAPBodyElement)soapBody.getChildElements().next();
+ String rpcName = soapBodyElement.getElementName().getLocalName();
+
+ SOAPFactory soapFactory = SOAPFactory.newInstance();
+ Name headerName =
+ soapFactory.createName("HeaderValue", "ns2",
"http://otherns");
+ SOAPHeaderElement she = soapHeader.addHeaderElement(headerName);
+ she.setValue("Unbound OUT header message");
+ }
+ catch (SOAPException e)
+ {
+ throw new JAXRPCException(e);
+ }
+
+ return true;
+ }
+ }
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">Unbound SOAP Headers on the client
proxy</emphasis>
+</para>
+<para>
+The web service client has access to unbound headers through the proxy
+</para>
+<para>
+<programlisting>
+ public void testUnboundInHeader() throws Exception
+ {
+ // Add a header to the stub
+ StubExt stub = (StubExt)endpoint;
+ QName xmlName = new QName("http://otherns", "HeaderValue");
+ stub.addUnboundHeader(xmlName, Constants.TYPE_LITERAL_STRING, String.class,
ParameterMode.IN);
+ stub.setUnboundHeaderValue(xmlName, "Unbound IN header message");
+
+ endpoint.testInHeader("Hello world!", "IN header message");
+
+ String unboundRet = (String)stub.getUnboundHeaderValue(xmlName);
+ assertEquals("Unbound OUT header message", unboundRet);
+ }
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">SOAP message exchange</emphasis>
+</para>
+<para>
+Below you see the SOAP messages that are beeing exchanged.
+</para>
+<para>
+Incomming SOAPMessage
+</para>
+<para>
+<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns2='http://somens'>INOUT header
message</ns2:String_2><ns3:HeaderValue
+ xmlns:ns3='http://otherns'>Unbound INOUT header
message</ns3:HeaderValue></env:Header><env:Body><ns1:testInOutHeader
xmlns:ns1='http://org.jboss.ws/samples/handler'><String_1>Hello
world!</String_1></ns1:testInOutHeader></env:Body></env:Envelope></programlisting>
+</para>
+<para>
+Outgoing SOAPMessage
+</para>
+<para>
+<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns2='http://somens'>INOUT header message -
response</ns2:String_2><ns2:HeaderValue
xmlns:ns2='http://otherns'>Unbound OUT header
message</ns2:HeaderValue></env:Header><env:Body><ns1:testInOutHeaderResponse
xmlns:ns1='http://org.jboss.ws/samples/handler'/></env:Body></env:Envelope></programlisting>
+</para>
+
+</section>
+<section><title>Message Handler</title>
+<para>
+JAX-RPC handler provide a convinient solution to intercept SOAP message processing both
inbound and outbound on the client and the server side:
+</para>
+<para>
+<programlisting>
+ package javax.xml.rpc.handler;
+ public interface Handler
+ {
+ boolean handleRequest(MessageContext context);
+
+ boolean handleResponse(MessageContext context);
+
+ boolean handleFault(MessageContext context);
+ }
+</programlisting>
+</para>
+<para>
+A Handler implementation class is required to provide a default constructor. The methods
handleRequest and handleResponse perform the actual processing work for a handler. The
method handleRequest processes the request SOAP message, while the method handleResponse
processes the response SOAP message. The method handleFault performs the SOAP fault
processing. The MessageContext parameter provides access to the message context (for
example: a SOAP message that carries an RPC request or response) that is processed by a
handler.
+</para>
+<para>
+In the following chapter we will implement a simple JAX-RPC handler and see how to
configure the handler chain for JSR-109 clients and web service endpoints.
+</para>
+<para>
+Run wstools with the following configuration
+</para>
+<para>
+<programlisting><configuration
...><java-wsdl><service name="TestService"
style="rpc"
+
endpoint="org.jboss.test.ws.jaxrpc.samples.handler.HeaderTestService"><operation
name="testInHeader"><parameter
type="java.lang.String"/><parameter
type="java.lang.String" xml-name="headerMsg"
header="true"/></operation><operation
name="testInOutHeader"><parameter
type="java.lang.String"/><parameter
type="javax.xml.rpc.holders.StringHolder"
+ xml-name="headerMsg" header="true"
mode="INOUT"/></operation><operation
name="testOutHeader"><parameter
type="java.lang.String"/><parameter
type="javax.xml.rpc.holders.StringHolder"
+ xml-name="headerMsg" header="true"
mode="OUT"/></operation></service><namespaces
target-namespace="http://org.jboss.ws/samples/handler"
+
type-namespace="http://org.jboss.ws/samples/handler/types"/><mapping
file="jaxrpc-mapping.xml"/><webservices
servlet-link="TestService"/></java-wsdl></configuration></programlisting>
+</para>
+<para>
+The handlers must be defined manualy in webservices.xml. WSTools does not generate
client/server side handler configurations.
+</para>
+<para>
+<programlisting><webservices
...><webservice-description>
+ ...
+ <port-component>
+ ...
+
<handler><handler-name>HeaderTestHandler</handler-name><handler-class>org.jboss.test.ws.jaxrpc.samples.handler.ServerSideHandler</handler-class></handler></port-component></webservice-description></webservices></programlisting>
+</para>
+<para>
+<emphasis role="bold">Generic Handler</emphasis>
+</para>
+<para>
+The javax.xml.rpc.handler.GenericHandler class is an abstract class that implements the
Handler interface. Developers typically subclass the GenericHandler class unless the
Handler implementation class needs another class as its superclass.
+</para>
+<para>
+The GenericHandler class is a convenience abstract class that makes writing handlers
easy. This class provides default implementations of the lifecycle methods init and
destroy and also different handle methods. A handler developer should only override
methods that it needs to specialize as part of the derived Handler implementation class.
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+On the client side, a request handler is invoked before an RPC request is communicated to
the target service endpoint.
+</para>
+</listitem>
+<listitem>
+<para>
+On the client side, a response or fault handler is invoked before an RPC response is
returned to the service client from the target service endpoint.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+On the endpoint a JAX-RPC handler may be configured and used as follows:
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+On the service endpoint side, a request handler is invoked before an RPC request is
dispatched to the target service endpoint.
+</para>
+</listitem>
+<listitem>
+<para>
+On the service endpoint side, a response or fault handler is invoked before communication
back to the service client from the target service endpoint.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+<emphasis role="bold">Configuring a client side handler</emphasis>
+</para>
+<para>
+Client side JAXRPC handlers are configured as part of the <service-ref>
element that is available in application-client.xml, ejb-jar.xml and web.xml.
+</para>
+<para>
+<programlisting><service-ref><service-ref-name>service/TestService</service-ref-name><service-interface>javax.xml.rpc.Service</service-interface><wsdl-file>META-INF/wsdl/TestService.wsdl</wsdl-file><jaxrpc-mapping-file>META-INF/jaxrpc-mapping.xml</jaxrpc-mapping-file><port-component-ref><service-endpoint-interface>
+ org.jboss.test.ws.jaxrpc.samples.handler.HeaderTestService
+
</service-endpoint-interface></port-component-ref><handler><handler-name>HeaderTestHandler</handler-name><handler-class>org.jboss.test.ws.jaxrpc.samples.handler.ClientSideHandler</handler-class></handler></service-ref></programlisting>
+</para>
+
+</section>
+<section><title>Dynamic Handlers</title>
+<para>
+<emphasis role="bold">Modifying the client side handler chain
dynamically</emphasis>
+</para>
+<para>
+The JSR-109 specification does not allow access to the HandlerRegistry that is associated
with the Service object. JBossWS extends the Service interface to provide full access to
the handler chains. There can be one handler chain per service port.
+</para>
+<para>
+<programlisting>
+ public void testRemoveServerHandlers() throws Exception
+ {
+ MBeanServerConnection server = getServer();
+ ObjectName oname =
ObjectNameFactory.create("jboss.ws:service=ServiceEndpointManager");
+ ObjectName serviceID = new
ObjectName("jboss.ws:di=jbossws-samples-dynamichandler.war," +
+ "service=TestService,port=HandlerTestServicePort");
+
+ List<HandlerInfo> infos = (List<HandlerInfo>)
+ server.invoke(oname, "getHandlerInfos",
+ new Object[]{serviceID}, new String[]{"javax.management.ObjectName"});
+
+ Iterator<HandlerInfo> it = infos.iterator();
+ while (it.hasNext())
+ {
+ HandlerInfo info = it.next();
+ if (info.getHandlerClass() == ServerSideHandler.class)
+ it.remove();
+ }
+
+ server.invoke(oname, "stopServiceEndpoint", new Object[]{serviceID},
+ new String[]{"javax.management.ObjectName"});
+
+ server.invoke(oname, "setHandlerInfos", new Object[]{serviceID, infos},
+ new String[]{"javax.management.ObjectName", "java.util.List"});
+
+ server.invoke(oname, "startServiceEndpoint", new Object[]{serviceID},
+ new String[]{"javax.management.ObjectName"});
+
+ String res = endpoint.testHandlers("InitalMessage");
+ assertEquals("InitalMessage", res);
+ }
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">Modifying the server side handler chain
dynamically</emphasis>
+</para>
+<para>
+JAXRPC-1.1 does not provide access to the service endpoint handler chain. JBossWS
provides full access to the handler chains through the ServiceEndpointManager. The
ServiceEndpointManager is an MBean that manages all service endpoints deployed to the
server.
+</para>
+<para>
+<programlisting>
+ public void testRemoveServerHandlers() throws Exception
+ {
+ MBeanServerConnection server = getServer();
+ ObjectName oname =
ObjectNameFactory.create("jboss.ws:service=ServiceEndpointManager");
+ String serviceID =
"jbossws-samples-dynamichandler.war#TestService/HandlerTestServicePort";
+
+ List<HandlerInfo> infos =
(List<HandlerInfo>)server.invoke(oname, "getHandlerInfos",
+ new Object[]{serviceID}, new String[]{"java.lang.String"});
+
+ Iterator<HandlerInfo> it = infos.iterator();
+ while (it.hasNext())
+ {
+ HandlerInfo info = it.next();
+ if (info.getHandlerClass() == ServerSideHandler.class)
+ it.remove();
+ }
+ server.invoke(oname, "stopServiceEndpoint",
+ new Object[]{serviceID}, new String[]{"java.lang.String"});
+
+ server.invoke(oname, "setHandlerInfos", new Object[]{serviceID, infos},
+ new String[]{"java.lang.String", "java.util.List"});
+
+ server.invoke(oname, "startServiceEndpoint",
+ new Object[]{serviceID}, new String[]{"java.lang.String"});
+
+ String res = endpoint.testHandlers("InitalMessage");
+ assertEquals("InitalMessage", res);
+ }
+</programlisting>
+</para>
+
+</section>
+
+</section>
+<section><title>Holders for INOUT parameters</title>
+<para>
+This chapter describes how a BigDecimalHolder can be used as an in/out
parameter.<programlisting> public interface HolderTestService extends
Remote</programlisting><programlisting>
{</programlisting><programlisting> void echoBigDecimal(BigDecimalHolder
val) throws RemoteException;</programlisting><programlisting> ...
</programlisting><programlisting> }</programlisting>
+</para>
+<para>
+<emphasis role="bold">Generating required deployment
artifacts</emphasis>
+</para>
+<para>
+Run wstools with the following configuration
+</para>
+<para>
+<programlisting><configuration
xmlns="http://www.jboss.org/jbossws-tools"><javaT...
name="TestService" wsdlStyle="rpc"
+
endpoint="org.jboss.test.ws.jaxrpc.samples.holder.HolderTestService"/><namespaces
targetNamespace="http://org.jboss.ws/samples/holder"
+
typeNamespace="http://org.jboss.ws/samples/holder/types"/><mapping
fileName="jaxrpc-mapping.xml"/><wsxml
servletLink="TestService"/></javaToWSDL></configuration></programlisting>
+</para>
+<para>
+WSTools generates WSDL messages with identical part names.
+</para>
+<para>
+<programlisting><message
name='HolderTestService_echoBigDecimal'><part
name='BigDecimal_1'
type='xsd:decimal'/></message><message
name='HolderTestService_echoBigDecimalResponse'><part
name='BigDecimal_1'
type='xsd:decimal'/></message><portType
name='HolderTestService'><operation name='echoBigDecimal'
parameterOrder='BigDecimal_1'><input
message='tns:HolderTestService_echoBigDecimal'/><output
message='tns:HolderTestService_echoBigDecimalResponse'/></operation>
+ ...
+ </portType></programlisting>
+</para>
+<para>
+The <service-endpoint-method-mapping> declares the parameter mode as
INOUT.
+</para>
+<para>
+<programlisting><service-endpoint-method-mapping><java-method-name>echoBigDecimal</java-method-name><wsdl-operation>echoBigDecimal</wsdl-operation><method-param-parts-mapping><param-position>0</param-position><param-type>java.math.BigDecimal</param-type><wsdl-message-mapping><wsdl-message
xmlns:wsdlMsgNS='http://org.jboss.ws/samples/holder'>
+ wsdlMsgNS:HolderTestService_echoBigDecimal
+
</wsdl-message><wsdl-message-part-name>BigDecimal_1</wsdl-message-part-name><parameter-mode>INOUT</parameter-mode></wsdl-message-mapping></method-param-parts-mapping></service-endpoint-method-mapping></programlisting>
+</para>
+<para>
+<emphasis role="bold">SOAP message exchange</emphasis>
+</para>
+<para>
+Below you see the SOAP messages that are beeing exchanged.
+</para>
+<para>
+Incomming SOAPMessage<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/holder'><BigDecimal_1>1000</BigDecimal_1></ns1:echoBigDecimal></env:Body></env:Envelope>
</programlisting>
+</para>
+<para>
+Outgoing SOAPMessage<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/holder'><BigDecimal_1>1001</BigDecimal_1></ns1:echoBigDecimalResponse></env:Body></env:Envelope></programlisting>
+</para>
+
+</section>
+<section><title>Custom Exceptions</title>
+<para>
+Custom exceptions in JAXRPC are about definig SOAP faults in your abstract contract and
mapping them to java exceptions. The SOAP message contains a <soap:fault>
element that contains information about the cause of the fault. Java specifics like stack
traces, exception class names, etc. are usually not transported because they maybe
meaningless to the non-java receiver.
+</para>
+<para>
+A good article about <ulink
url="http://www-128.ibm.com/developerworks/xml/library/ws-tip-jaxrpc...
Handling with JAX-RPC</citetitle></ulink> can be found at IBM's
developerworks.
+</para>
+<para>
+Lets use a service endpoint interface (SEI) that throws various user exception
+</para>
+<para>
+<programlisting>
+public interface ExceptionServiceInterface extends Remote
+{
+ void throwException() throws UserException, RemoteException;
+
+ void throwExceptionWithMessage(String message) throws UserMessageException,
RemoteException;
+
+ void throwComplexUserException(String message, int code) throws ComplexUserException,
RemoteException;
+
+ void throwComplexUserArrayException(String message, int[] code) throws
ComplexUserArrayException, RemoteException;
+}
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">Generating required deployment
artifacts</emphasis>
+</para>
+<para>
+Run wstools with the following configuration
+</para>
+<para>
+<programlisting><configuration
...><java-wsdl><service name="ExceptionService"
style="rpc"
+
endpoint="org.jboss.test.ws.jaxrpc.samples.exception.ExceptionServiceInterface"/><namespaces
target-namespace="http://org.jboss.ws/samples/exception"
+
type-namespace="http://org.jboss.ws/samples/exception/types"/><mapping
file="jaxrpc-mapping.xml"/><webservices
ejb-link="ExceptionBean"/></java-wsdl></configuration></programlisting>
+</para>
+<para>
+wstools produces the following abstract contract (WSDL)
+</para>
+<para>
+<programlisting><definitions
targetNamespace='http://org.jboss.ws/samples/exception' ...>
+ ...
+ <portType name='ExceptionServiceInterface'><operation
name='throwComplexUserArrayException'>
+ ...
+ <fault
message='tns:ComplexUserArrayException'/></operation><operation
name='throwComplexUserException'>
+ ...
+ <fault message='tns:ComplexUserException'
name='ComplexUserException'/></operation><operation
name='throwException'>
+ ...
+ <fault message='tns:UserException'
name='UserException'/></operation><operation
name='throwExceptionWithMessage'>
+ ...
+ <fault message='tns:UserMessageException'
name='UserMessageException'/></operation></portType>
+ ...
+ </definitions></programlisting>
+</para>
+<para>
+Note the various fault elements and how they are linked to XML schema complex types. The
WSDL does not contain any information about the java mapping. This is defined in
jaxrpc-maping.xml, for which I will only show the exception relevant parts.
+</para>
+<para>
+<programlisting><exception-mapping><exception-type>org.jboss.test.ws.jaxrpc.samples.exception.UserException</exception-type><wsdl-message>exMsgNS:UserException</wsdl-message></exception-mapping><exception-mapping><exception-type>org.jboss.test.ws.jaxrpc.samples.exception.UserMessageException</exception-type><wsdl-message>exMsgNS:UserMessageException</wsdl-message><constructor-parameter-order><element-name>message</element-name></constructor-parameter-order></exception-mapping><exception-mapping><exception-type>org.jboss.test.ws.jaxrpc.samples.exception.ComplexUserException</exception-type><wsdl-message>exMsgNS:ComplexUserException</wsdl-message><constructor-parameter-order><element-name>message</element-name><element-name>errorCode</element-name></constructor-parameter-order></exception-mapping><exception-!
mapping><exception-type>org.jboss.test.ws.jaxrpc.samples.exception.ComplexUserArrayException</exception-type><wsdl-message>exMsgNS:ComplexUserArrayException</wsdl-message><constructor-parameter-order><element-name>message</element-name><element-name>errorCodes</element-name></constructor-parameter-order></exception-mapping></programlisting>
+</para>
+<para>
+<emphasis role="bold">SOAP message exchange</emphasis>
+</para>
+<para>
+Here some SOAP messages as they would appear on the wire
+</para>
+<para>
+<programlisting><soapenv:Envelope
...><soapenv:Body><soapenv:Fault><faultcode>soapenv:Client</faultcode><faultstring>org.jboss.test.webservice.exception.UserException</faultstring><detail><ns1:UserException
xmlns:ns1="http://org.jboss.webservice/exception/types"><message
xsi:nil="1"/></ns1:UserException></detail></soapenv:Fault></soapenv:Body></soapenv:Envelope><soapenv:Envelope
...><soapenv:Body><soapenv:Fault><faultcode>soapenv:Client</faultcode><faultstring>Don't
worry it's just a
test</faultstring><detail><ns1:UserMessageException
xmlns:ns1="http://org.jboss.webservice/exception/types"><message>Don't
worry it's just a
test</message></ns1:UserMessageException></detail></soapenv:Fault></soapenv:Body></soapenv:Envelope><soapenv:Envelope
...><soapenv:Body><soapenv:Fault><!
;faultcode>soapenv:Client</faultcode><faultstring>Don't
worry it's just a
test</faultstring><detail><ns1:ComplexUserException
xmlns:ns1="http://org.jboss.webservice/exception/types"><message>Don't
worry it's just a
test</message><errorCode>200</errorCode></ns1:ComplexUserException></detail></soapenv:Fault></soapenv:Body></soapenv:Envelope><soapenv:Envelope
...><soapenv:Body><soapenv:Fault><faultcode>soapenv:Client</faultcode><faultstring>Don't
worry it's just a
test</faultstring><detail><ns1:ComplexUserArrayException
xmlns:ns1="http://org.jboss.webservice/exception/types"><message>Don't
worry it's just a
test</message><errorCodes>100</errorCodes><errorCodes>200</errorCodes></ns1:ComplexUserArrayException></detail></soapenv:Fault></soapenv:Body></soapenv:Envelope></progra!
mlisting>
+</para>
+
+</section>
+<section><title>OneWay Invocations</title>
+<para>
+This chapter describes an asynchronous one way endpoint invocation<programlisting>
public interface OneWayTestService extends
Remote</programlisting><programlisting>
{</programlisting><programlisting> void oneWay(String str1) throws
RemoteException;</programlisting><programlisting> }</programlisting>
+</para>
+<para>
+<emphasis role="bold">Generating required deployment
artifacts</emphasis>
+</para>
+<para>
+Run wstools with the following configuration
+</para>
+<para>
+<programlisting><configuration
...><java-wsdl><service name="TestService"
style="rpc"
+
endpoint="org.jboss.test.ws.jaxrpc.samples.oneway.OneWayTestService"><operation
name="oneWay" one-way="true"><parameter
type="java.lang.String"/></operation></service><namespaces
target-namespace="http://org.jboss.ws/samples/oneway"
+
type-namespace="http://org.jboss.ws/samples/one-way=/types"/><mapping
file="jaxrpc-mapping.xml"/><webservices
servlet-link="TestService"/></java-wsdl></configuration></programlisting>
+</para>
+<para>
+WSTools does not generate output elements in the WSDL portType nor in the binding
+</para>
+<para>
+<programlisting><portType
name='OneWayTestService'><operation name='oneWay'
parameterOrder='String_1'><input
message='tns:OneWayTestService_oneWay'/></operation></portType><binding
name='OneWayTestServiceBinding'
type='tns:OneWayTestService'><soap:binding style='rpc'
transport='http://schemas.xmlsoap.org/soap/http'/><...
name='oneWay'><soap:operation
soapAction=''/><input><soap:body
namespace='http://org.jboss.ws/samples/oneway'
use='literal'/></input></operation></binding>
</programlisting>
+</para>
+<para>
+<emphasis role="bold">SOAP message exchange</emphasis>
+</para>
+<para>
+Below you see the incomming SOAP message. There is no outgoing message.
+</para>
+<para>
+<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/oneway'><String_1>Hello</String_1></ns1:oneWay></env:Body></env:Envelope></programlisting>
+</para>
+
+</section>
+<section><title>SOAP with Attachments</title>
+<para>
+This chapter describes SOAP with Attachments. JBossWS conform to the <ulink
url="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0.html"&...
AttachmentsProfile-1.0</citetitle></ulink>
+</para>
+<para>
+<emphasis role="bold">MIME mapping required by
JAXRPC-1.1</emphasis><table>
+<title/><tgroup cols="2"><tbody><row>
+<entry>
+image/gif
+</entry>
+<entry>
+java.awt.Image
+</entry>
+
+</row>
+<row>
+<entry>
+image/jpeg
+</entry>
+<entry>
+java.awt.Image
+</entry>
+
+</row>
+<row>
+<entry>
+text/plain
+</entry>
+<entry>
+java.lang.String
+</entry>
+
+</row>
+<row>
+<entry>
+multipart/*
+</entry>
+<entry>
+javax.mail.internet.MimeMultipart
+</entry>
+
+</row>
+<row>
+<entry>
+text/xml
+</entry>
+<entry>
+javax.xml.transform.Source
+</entry>
+
+</row>
+<row>
+<entry>
+application/xml
+</entry>
+<entry>
+javax.xml.transform.Source
+</entry>
+
+</row>
+</tbody></tgroup>
+</table>
+<programlisting/>
+</para>
+<para>
+The sample code uses the following service endpoint interface
+</para>
+<para>
+<programlisting>
+ public interface Attachment extends Remote
+ {
+ /** Service endpoint method for image/gif */
+ String sendMimeImageGIF(String message, Object mimepart) throws RemoteException;
+
+ /** Service endpoint method for image/jpeg */
+ String sendMimeImageJPEG(String message, Image mimepart) throws RemoteException;
+
+ /** Service endpoint method for text/plain */
+ String sendMimeTextPlain(String message, String mimepart) throws RemoteException;
+
+ /** Service endpoint method for multipart/* */
+ String sendMimeMultipart(String message, MimeMultipart mimepart) throws
RemoteException;
+
+ /** Service endpoint method for text/xml */
+ String sendMimeTextXML(String message, Object mimepart) throws RemoteException;
+
+ /** Service endpoint method for application/xml */
+ String sendMimeApplicationXML(String message, Source mimepart) throws RemoteException;
+ }
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">Generating required deployment
artifacts</emphasis>
+</para>
+<para>
+Run wstools with the following configuration
+</para>
+<para>
+<ulink
url="http://jira.jboss.org/jira/browse/JBWS-700"><citetit...:
JBWS-700</citetitle></ulink>
+</para>
+<para>
+WSTools does generate message parts of type xsd:hexBinary and the associated mime
bindings<programlisting><message
name="Attachment_sendMimeImageGIF"><part name="message"
type="xsd:string"/><part name="mimepart"
type="xsd:hexBinary"/></message><binding
name="AttachmentBinding"
type="tns:Attachment"><soap:binding
transport="http://schemas.xmlsoap.org/soap/http"
style="rpc"/><operation
name="sendMimeImageGIF"><soap:operation
soapAction=""/><input><mime:multipartRelated><mime:part><soap:body
part="message" use="literal"
+
namespace="http://org.jboss.ws/samples/swa"/></mime:part><mime:part><mime:content
part="mimepart"
type="image/gif"/></mime:part></mime:multipartRelated></input><output><soap:body
use="literal"
namespace="http://org.jboss.ws/samples/swa"/></output></operation>
+ ...
+ </binding></programlisting>
+</para>
+<section><title>Access attachments on the server side</title>
+<para>
+Your endpoint bean may access the attachment parts using the standard SAAJ API:
<programlisting>
+ ServletEndpointContext context =
+ (ServletEndpointContext)ctxWhichIsSetIn_ServiceLifecycle_init;
+
+ SOAPMessageContext msgContext = (SOAPMessageContext)context.getMessageContext();
+ SOAPMessage soapMessage = msgContext.getMessage();
+
+ Iterator attachments = soapMessage.getAttachments();
+ if (attachments.hasNext())
+ {
+ AttachmentPart ap = (AttachmentPart)attachments.next();
+ String contentType = ap.getContentType();
+
+ if (expContentType.equals("multipart/*"))
+ {
+ MimeMultipart mmp = (MimeMultipart)ap.getContent();
+ int mmpCount = mmp.getCount();
+ for (int i = 0; i < mmpCount; i++)
+ {
+ BodyPart bp = mmp.getBodyPart(i);
+ String bpct = bp.getContentType();
+ Object bpc = bp.getContent();
+ ...
+ }
+ }
+ else if (expContentType.equals("image/gif"))
+ {
+ Image image = (Image)ap.getContent();
+ ...
+ }
+ else
+ {
+ ...
+ }
+ }
+</programlisting>
+</para>
+
+</section>
+<section><title>Sending an attachment from a DII client</title>
+<para>
+To send an image, we can use the standard DII API and make use of the Java activation
framework. From the javadoc for DataHandler:
+</para>
+<para>
+<emphasis>The DataHandler class provides a consistent interface to data available
in many different sources and formats. It manages simple stream to string conversions and
related operations using DataContentHandlers.</emphasis>
+</para>
+<para>
+<programlisting>
+ ServiceFactory factory = ServiceFactory.newInstance();
+ Service service = factory.createService(SERVICE_NAME);
+
+ Call call = service.createCall(PORT_NAME, new QName(NS_URI, rpcMethodName));
+ call.addParameter("message", Constants.XSD_STRING, ParameterMode.IN);
+ call.addParameter("mimepart", Constants.MIME_IMAGE, ParameterMode.IN);
+ call.setReturnType(Constants.XSD_STRING);
+ call.setTargetEndpointAddress("http://" + getServerHost() +
":8080/ws4ee-attachment");
+
+ URL url = new File("resources/webservice/attachment/attach.gif").toURL();
+
+ String message = "Some text message";
+ String value = (String)call.invoke(new Object[]{message, new DataHandler(url)});
+
+ System.out.println(value);
+</programlisting>
+</para>
+
+</section>
+<section><title>Building a multipart message using SAAJ</title>
+<para>
+Using the SAAJ API directly, you can also construct a MIME multipart message and send it
on the wire without using an JAX-RPC client.
+</para>
+<para>
+<programlisting>
+ MessageFactory mf = MessageFactory.newInstance();
+
+ // Create a soap message from the message factory.
+ SOAPMessage msg = mf.createMessage();
+
+ // Message creation takes care of creating the SOAPPart
+ // a required part of the message as per the SOAP 1.1 spec.
+ SOAPPart sp = msg.getSOAPPart();
+
+ // Retrieve the envelope from the soap part to start building the soap message.
+ SOAPEnvelope envelope = sp.getEnvelope();
+
+ // Create a soap body from the envelope.
+ SOAPBody bdy = envelope.getBody();
+
+ // Add a soap body element
+ SOAPBodyElement sbe = bdy.addBodyElement(envelope.createName(rpcMethodName, NS_PREFIX,
NS_URI));
+
+ // Add a some child elements
+ sbe.addChildElement(envelope.createName("message")).addTextNode("Some
text message");
+
sbe.addChildElement(envelope.createName("mimepart")).addAttribute(envelope.createName("href"),
CID_MIMEPART);
+
+ AttachmentPart ap = msg.createAttachmentPart(new DataHandler(url));
+ ap.setContentType("image/gif");
+ ap.setContentId(CID_MIMEPART);
+
+ // Add the attachments to the message.
+ msg.addAttachmentPart(ap);
+
+ SOAPConnectionFactory conFactory = SOAPConnectionFactory.newInstance();
+ SOAPConnection con = conFactory.createConnection();
+ SOAPMessage resMessage = con.call(msg, new
URL("http://localhost:8080/ws4ee-attachment"));
+</programlisting>
+</para>
+
+</section>
+
+</section>
+<section><title>MTOM/XOP</title>
+<para>
+This chapter describes Message Transmission Optimization Mechanism (MTOM) and XML-binary
Optimized Packaging (XOP), a means of more efficiently serializing XML Infosets that have
certain types of content. The related specifications are <ulink
url="http://www.w3.org/TR/soap12-mtom/"><citetitle>SOAP Message
Transmission Optimization Mechanism (MTOM)</citetitle></ulink> and <ulink
url="http://www.w3.org/TR/xop10/"><citetitle>XML-binary Optimized
Packaging (XOP)</citetitle></ulink>
+</para>
+<para>
+The MTOM/XOP example uses a service endpoint interface with the same operations as in
#SOAP with Attachments
+</para>
+<section><title>MTOM schema elements</title>
+<para>
+Currently neither wstools nor wscompile has support for MTOM. Fortunatly a MTOM
optimizable element decalaration isn't that difficult to understand and can easily be
created manually:
+</para>
+<para>
+<programlisting><schema xmlns="http://www.w3.org/2001/XMLSchema"
+ targetNamespace="http://org.jboss.ws/samples/mtom"
+ xmlns:xmime="http://www.w3.org/2005/05/xmlmime">
+
+ (1) <import schemaLocation="http://www.w3.org/2005/05/xmlmime"
namespace="http://www.w3.org/2005/05/xmlmime"/>
+
+ (2) <element name="imagejpeg" xmime:contentType="image/jpeg"
type="xmime:base64Binary"/></schema></programlisting>
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+Import the xmime schema declarations
+</para>
+</listitem>
+<listitem>
+<para>
+Derive your element declaration from xmime:base64Binary
+</para>
+</listitem>
+</orderedlist>
+
+</section>
+<section><title>Supported MTOM parameter types</title>
+<table>
+<title/><tgroup cols="2"><tbody><row>
+<entry>
+image/jpeg
+</entry>
+<entry>
+java.awt.Image
+</entry>
+
+</row>
+<row>
+<entry>
+text/xml
+</entry>
+<entry>
+javax.xml.transform.Source
+</entry>
+
+</row>
+<row>
+<entry>
+application/xml
+</entry>
+<entry>
+javax.xml.transform.Source
+</entry>
+
+</row>
+<row>
+<entry>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+/*
+</para>
+</listitem>
+</itemizedlist>
+
+</entry>
+<entry>
+javax.activation.DataHandler
+</entry>
+
+</row>
+</tbody></tgroup>
+</table>
+<para>
+The above table shows a list of supported endpoint parameter types. The recommended
approach is to use the <ulink
url="http://java.sun.com/j2ee/1.4/docs/api/javax/activation/DataHand...
classes to represent binary data as service endpoint parameters.
+</para>
+
+</section>
+<section><title>Enabling MTOM</title>
+<para>
+Since 1.2
+</para>
+<para>
+Before the 1.2 release MTOM was enabled for any JAX-RPC endpoint. This was alinged with
the JAX-WS default, and thus <emphasis role="bold">is disabled by
default</emphasis> now. In order to enable MTOM per endpoint you need to make sure
the MTOM feature is set in the ednpoint config,
i.e.<programlisting><endpoint-config><config-name>Standard
MTOM
Endpoint</config-name><feature>http://org.jboss.ws/mtom</feature>
(1)
+</endpoint-config></programlisting>
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+This may added to any endpoint config you are using
+</para>
+</listitem>
+</orderedlist>
+
+</section>
+<section><title>An example MTOM request</title>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+The fact that a SOAP message might be XOP encoded is actually transparent to any SOAP
intermediary. This also applies to JAXRPC handlers. What does this mean? It means that
JAXRPC handlers don't get to see the XOP encoded wireformat (xop:Include), instead
they can access the message as if it was inlined. This is necessary in order not to break
any SOAP processing modules that work on the real payload (i.e. Security). In JBossWS this
results in the binary data being transformed into a base64 representation, which can
easily negate the optimization efforts in the first place.
+</para>
+<para>
+The incomming message is multipart/related. The first part is the SOAP Envelope.
+</para>
+<para>
+<programlisting>
+POST /jbossws-samples-mtom HTTP/1.1
+SOAPAction: ""
+Content-Type: multipart/related; start-info="text/xml";
+ type="application/xop+xml";
+start="&lt;rootpart(a)ws.jboss.org&gt;";
+boundary="----=_Part_2_29441291.1153833579421"
+User-Agent: Java/1.5.0_07
+Host: localhost:8081
+Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
+Connection: keep-alive
+Content-Length: 915
+
+
+------=_Part_2_29441291.1153833579421
+Content-Type: application/xop+xml; type="text/xml"
+Content-Transfer-Encoding: 8bit
+Content-ID: <rootpart@ws.jboss.org><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/mtom'><message>Some
text message</message><ns1:textxml><xop:Include
+ href='cid:textxml-590c9216-9871-48a8-9239-f73831644442@ws.jboss.org'
+
xmlns:xop='http://www.w3.org/2004/08/xop/include'/><...
+------=_Part_2_29441291.1153833579421
+Content-Type: text/xml
+Content-Transfer-Encoding: binary
+Content-Id:
&lt;textxml-590c9216-9871-48a8-9239-f73831644442(a)ws.jboss.org&gt;&lt;?xml
version="1.0"
encoding="ISO-8859-1"?><mime-message>This is an xml
attachment.</mime-message>
+
+------=_Part_2_29441291.1153833579421--
+
+</programlisting>
+</para>
+
+</section>
+
+</section>
+<section><title>JMS Transport</title>
+<para>
+JBossWS supports J2EE-1.4 message driven beans (MDB) as service endpoints. A JMS message
that is targeted to MDB may contain a SOAP envelope that is then dispatched to the same
MDB. The MDB implements the methods on the Service Endpoint Interface (SEI), onMessage()
is implemented by a base class that we provide.
+</para>
+<section><title>JMS Endpoint</title>
+<para>
+In this section we describe how to expose an EJB Message Driven Bean as service
endpoint.
+</para>
+<para>
+<emphasis role="bold">The Message Driven Bean</emphasis>
+</para>
+<para>
+First you setup an ordinary message driven bean in ejb-jar.xml and jboss.xml
+</para>
+<para>
+<programlisting><ejb-jar><enterprise-beans><message-driven><ejb-name>OrganizationMDB</ejb-name><ejb-class>org.jboss.test.ws.jaxrpc.samples.jmstransport.OrganizationJMSEndpoint</ejb-class><message-selector></message-selector><transaction-type>Container</transaction-type><acknowledge-mode>AUTO_ACKNOWLEDGE</acknowledge-mode><message-driven-destination><destination-type>javax.jms.Queue</destination-type><subscription-durability>NonDurable</subscription-durability></message-driven-destination></message-driven></enterprise-beans></ejb-jar><jboss><enterprise-beans><message-driven><ejb-name>OrganizationMDB</ejb-name><destination-jndi-name>queue/RequestQueue</destination-jndi-name><depends>jboss.mq.destination:service=Queue,name=RequestQueue</depends></message-driven></enterprise-beans>&l!
t;/jboss></programlisting>
+</para>
+<para>
+The implementation extends <ulink
url="http://fisheye.jboss.com/viewrep/JBoss/jboss/src/main/org/jboss...;,
which is the actual MDB and takes care of decoding the incomming JMS message and
dispatching it to the target endpoint bean.
+</para>
+<para>
+<programlisting>
+ public class OrganizationJMSEndpoint extends JMSTransportSupport
+ {
+ // provide logging
+ private static final Logger log = Logger.getLogger(OrganizationJMSEndpoint.class);
+
+ /** Get the contact info */
+ public String getContactInfo(String organization) throws RemoteException
+ {
+ log.info("getContactInfo: " + organization);
+ return "The '" + organization + "' boss is currently out of
office, please call again.";
+ }
+ }
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">Packaging the JMS Endpoint</emphasis>
+</para>
+<para>
+A JMS endpoint is packaged like an #JSR-109 EJB Endpoint and uses the standard
webservices.xml descriptor
+</para>
+<para>
+<programlisting><webservices
...><webservice-description><webservice-description-name>OrganizationService</webservice-description-name><wsdl-file>META-INF/wsdl/OrganizationService.wsdl</wsdl-file><jaxrpc-mapping-file>META-INF/jaxrpc-mapping.xml</jaxrpc-mapping-file><port-component><port-component-name>OrganizationPort</port-component-name><wsdl-port>impl:OrganizationPort</wsdl-port><service-endpoint-interface>
+ org.jboss.test.ws.jaxrpc.samples.jmstransport.Organization
+
</service-endpoint-interface><service-impl-bean><ejb-link>OrganizationMDB</ejb-link></service-impl-bean></port-component></webservice-description></webservices></programlisting>
+</para>
+
+</section>
+<section><title>JMS Client</title>
+<para>
+To send a SOAP message to a JMS endpoint you use the normal JMS message producer
metodology. Here is an example:
+</para>
+<para>
+There is not yet transparent JMS transport available for web service clients. Please
monitor <ulink
url="http://jira.jboss.com/jira/browse/JBWS-670"><citetit...
progress on this.
+</para>
+<para>
+<programlisting>
+ InitialContext context = new InitialContext();
+ QueueConnectionFactory connectionFactory =
(QueueConnectionFactory)context.lookup("ConnectionFactory");
+
+ Queue reqQueue = (Queue)context.lookup("queue/RequestQueue");
+ Queue resQueue = (Queue)context.lookup("queue/ResponseQueue");
+
+ QueueConnection con = connectionFactory.createQueueConnection();
+ QueueSession session = con.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
+ QueueReceiver receiver = session.createReceiver(resQueue);
+ ResponseListener responseListener = new ResponseListener();
+ receiver.setMessageListener(responseListener);
+ con.start();
+
+ TextMessage message = session.createTextMessage(reqMessage);
+ message.setJMSReplyTo(resQueue);
+
+ QueueSender sender = session.createSender(reqQueue);
+ sender.send(message);
+ sender.close();
+
+ done.acquire();
+
+ assertNotNull("Expected response message", responseListener.resMessage);
+ assertEquals(DOMUtils.parse(resMessage), DOMUtils.parse(responseListener.resMessage));
+
+ con.stop();
+ session.close();
+ con.close();
+</programlisting>
+</para>
+
+</section>
+
+</section>
+<section><title>Secure Endpoints</title>
+<para>
+<emphasis role="bold">Secure the access to the SLSB</emphasis>
+</para>
+<para>
+First we secure the access to the SLSB as we would do for normal (non web service)
invocations.
+</para>
+<para>
+In ejb-jar.xml, we setup the method permissions for the SLSB endpoint. Note, that it is
not necessarily required for the endpoint to have home/remote interfaces.
+</para>
+<para>
+<programlisting><enterprise-beans><session><ejb-name>RoleSecuredSLSB</ejb-name><remote>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationRemote</remote><home>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationHome</home><service-endpoint>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationService</service-endpoint><ejb-class>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationImpl</ejb-class><session-type>Stateless</session-type><transaction-type>Container</transaction-type><security-role-ref><role-name>friend</role-name></security-role-ref></session><session><ejb-name>BasicSecuredSLSB</ejb-name><remote>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationRemote</remote><home>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationHome</home><service-endpoint>org.jboss.test.ws.jaxrpc.sam!
ples.secureejb.OrganizationService</service-endpoint><ejb-class>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationImpl</ejb-class><session-type>Stateless</session-type><transaction-type>Container</transaction-type></session></enterprise-beans><assembly-descriptor><security-role><role-name>friend</role-name></security-role><method-permission><role-name>friend</role-name><method><ejb-name>RoleSecuredSLSB</ejb-name><method-name>*</method-name></method></method-permission><method-permission><unchecked/><method><ejb-name>BasicSecuredSLSB</ejb-name><method-name>*</method-name></method></method-permission></assembly-descriptor></programlisting>
+</para>
+<para>
+<emphasis role="bold">Define the security domain</emphasis>
+</para>
+<para>
+Next, define the security domain for this deployment in jboss.xml. The JBossWS security
context is configured in login-config.xml and uses the <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=UsersRolesLoginModule&...;.
+</para>
+<para>
+<programlisting><jboss><security-domain>java:/jaas/JBossWS</security-domain><enterprise-beans><session><ejb-name>RoleSecuredSLSB</ejb-name><jndi-name>ejb/RoleSecuredSLSB</jndi-name><port-component><port-component-name>RoleSecured</port-component-name><port-component-uri>/jaxrpc-samples-ejb/RoleSecured</port-component-uri></port-component></session><session><ejb-name>BasicSecuredSLSB</ejb-name><jndi-name>ejb/BasicSecuredSLSB</jndi-name><port-component><port-component-name>BasicSecured</port-component-name><port-component-uri>/jaxrpc-samples-ejb/BasicSecured</port-component-uri></port-component></session></enterprise-beans></jboss></programlisting>
+</para>
+<para>
+In login-config.xml, that lives in the server config dir, you will find the definition of
the JBossWS security domain.
+</para>
+<para>
+<programlisting><application-policy
name="JBossWS"><authentication><login-module
code="org.jboss.security.auth.spi.UsersRolesLoginModule"
+ flag="required"><module-option
name="usersProperties">props/jbossws-users.properties</module-option><module-option
name="rolesProperties">props/jbossws-roles.properties</module-option><module-option
name="unauthenticatedIdentity">anonymous</module-option></login-module></authentication></application-policy>
</programlisting>
+</para>
+<para>
+<emphasis role="bold">Use the JAXRPC Stub to set
principal/credential</emphasis>
+</para>
+<para>
+A web service client may use the javax.xml.rpc.Stub object to set the username/password
combination
+</para>
+<para>
+<programlisting>
+ public void testWebServiceAccess() throws Exception
+ {
+ OrganizationEndpoint endpoint = service.getPort(OrganizationEndpoint.class);
+
+ Stub stub = (Stub)endpoint;
+ stub._setProperty(Stub.USERNAME_PROPERTY, "kermit");
+ stub._setProperty(Stub.PASSWORD_PROPERTY, "thefrog");
+
+ String info = endpoint.getContactInfo("mafia");
+ assertEquals("The 'mafia' boss is currently out of office, please call
again.", info);
+ }
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">Using HTTP Basic Auth for
security</emphasis>
+</para>
+<para>
+To enable HTTP Basic authentication you need to add a port-component descriptor to your
jboss.xml file, which contains an auth-method tag. We just modify the jboss.xml from
above.
+</para>
+<para>
+<programlisting><jboss><security-domain>java:/jaas/JBossWS</security-domain><enterprise-beans><session><ejb-name>RoleSecuredSLSB</ejb-name><jndi-name>ejb/RoleSecuredSLSB</jndi-name><port-component><port-component-name>RoleSecured</port-component-name><port-component-uri>/ws4ee-samples-ejb/RoleSecured</port-component-uri><auth-method>BASIC</auth-method></port-component></session><session><ejb-name>BasicSecuredSLSB</ejb-name><jndi-name>ejb/BasicSecuredSLSB</jndi-name><port-component><port-component-name>BasicSecured</port-component-name><port-component-uri>/ws4ee-samples-ejb/BasicSecured</port-component-uri><auth-method>BASIC</auth-method></port-component></session></enterprise-beans></jboss></programlisting>
+</para>
+<para>
+<emphasis role="bold">Secure HTTP transport</emphasis>
+</para>
+<para>
+You can also require that all webservice requests use SSL by adding the
transport-guarantee tag in your jboss.xml file. Modify jboss.xml file to also require the
transport guarantee CONFIDENTIAL.
+</para>
+<para>
+<programlisting><jboss><security-domain>java:/jaas/JBossWS</security-domain><enterprise-beans><session><ejb-name>RoleSecuredSLSB</ejb-name><jndi-name>ejb/RoleSecuredSLSB</jndi-name><port-component><port-component-name>RoleSecured</port-component-name><port-component-uri>/ws4ee-samples-ejb/RoleSecured</port-component-uri><auth-method>BASIC</auth-method><transport-guarantee>CONFIDENTIAL</transport-guarantee></port-component></session><session><ejb-name>BasicSecuredSLSB</ejb-name><jndi-name>ejb/BasicSecuredSLSB</jndi-name><port-component><port-component-name>BasicSecured</port-component-name><port-component-uri>/ws4ee-samples-ejb/BasicSecured</port-component-uri><auth-method>BASIC</auth-method><transport-guarantee>CONFIDENTIAL</transport-guarantee></port-component></s!
ession></enterprise-beans></jboss></programlisting>
+</para>
+<para>
+At last, make sure that the endpoint address in your WSDL file uses a secure protocol.
The easiest way is to add "https://" to the SOAP Address entry:
+</para>
+<para>
+<programlisting><service
name="OrganizationService"><port name="BasicSecuredPort"
binding="tns:OrganizationServiceBinding"><soap:address
location="https://localhost:8443/ws4ee-samples-ejb/BasicSecured"/></port><port
name="RoleSecuredPort"
binding="tns:OrganizationServiceBinding"><soap:address
location="https://localhost:8443/ws4ee-samples-ejb/RoleSecured"/></port></service></programlisting>
+</para>
+<para>
+For this to work the Tomcat+SSL connector must be enabled.
+</para>
+<para>
+<programlisting><Connector port="8443"
address="${jboss.bind.address}"
+ maxThreads="100" minSpareThreads="5" maxSpareThreads="15"
+ scheme="https" secure="true" clientAuth="want"
+ keystoreFile="${jboss.server.home.dir}/conf/keystores/wsse.keystore"
+ keystorePass="jbossws"
+ truststoreFile="${jboss.server.home.dir}/conf/keystores/wsse.keystore"
+ truststorePass="jbossws"
+ sslProtocol = "TLS" /></programlisting>
+</para>
+<para>
+For details see: <ulink
url="http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html">...
SSL Configuration HOWTO</citetitle></ulink>
+</para>
+<para>
+On the client side the truststore must be installed<programlisting>
</programlisting><programlisting>
</programlisting><programlisting>
</programlisting><programlisting>
</programlisting><programlisting>
</programlisting><programlisting>
</programlisting><programlisting> </programlisting>
+</para>
+<para>
+In case you see the following exception, you should disable URL checking on the client
side<programlisting> java.io.IOException: HTTPS hostname wrong: should be
<localhost></programlisting><programlisting> at
sun.net.www.protocol.https.HttpsClient.checkURLSpoofing(HttpsClient.java:493)</programlisting><programlisting>
at
sun.net.www.protocol.https.HttpsClient.afterConnect(HttpsClient.java:418)</programlisting><programlisting>
</programlisting><programlisting> </programlisting>
+</para>
+
+</section>
+<section><title>WS-Addressing</title>
+<para>
+The WS-Addressing sample has been migrated to JAX-WS User Guide#WS-Addressing.
WS-Addressing handlers are however still available for JAX-RPC.See JAX-RPC Endpoint
Configuration#Standard WSAddressing Endpoint
+</para>
+
+</section>
+<section><title>WS-BPEL</title>
+<para>
+This chapter is dedicated to show how to use <ulink
url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsbp...
specify business process behavior based on web services.
+</para>
+<section><title>Specification</title>
+<para>
+Originally authored by a reduced vendor charter, WS-BPEL is currently under
standardization at OASIS. The latest approved document as of August 22, 2006 is:
+</para>
+<para>
+<ulink url="http://tinyurl.com/nw54b"><citetitle>Web Services
Business Process Execution Language 2.0 Committee Draft</citetitle></ulink>
+</para>
+<para>
+In the Java space, JSR-207 aims at defining metadata, interfaces and a runtime model that
enable business processes to be easily and rapidly implemented using Java and deployed in
J2EE containers. The request submission is:
+</para>
+<para>
+<ulink url="http://jcp.org/en/jsr/detail?id=207"><citetitle>JSR
207: Process Definition for Java</citetitle></ulink>
+</para>
+<para>
+The provided foundation would support tasks commonly encountered when programming
business processes such as parallel execution and asynchronous messaging.
+</para>
+
+</section>
+<section><title>Defining a business process</title>
+<para>
+Business processes model the stateful behavior of a participant in a business
interaction. In BPEL, a process exports and imports functionality to/from participants
using web service interfaces exclusively.
+</para>
+<para>
+At its simplest, BPEL can be used as a scripting language for web services. Consider a
trivial endpoint that receives a person name, composes a greeting phrase and then replies
with the greeting.
+</para>
+<para>
+The flow diagram below represents the processing logic.
+</para>
+<para>
+<mediaobject>
+<imageobject>
+<imagedata fileref="http:///images/c/cd/Wsbpel-hello.gif"/>
+</imageobject>
+<textobject>
+<phrase>Graphical representation of the Hello World process</phrase>
+</textobject>
+</mediaobject>
+
+</para>
+<para>
+The interface our endpoint presents to the world appears in the following WSDL document.
Observe no binding or service elements are present. A BPEL process is defined in terms of
the interfaces (message and port type elements) of the participants, not their possible
deployments.<programlisting><definitions
targetNamespace="http://jbpm.org/examples/hello"
+ xmlns="http://schemas.xmlsoap.org/wsdl/"
+ xmlns:tns="http://jbpm.org/examples/hello"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"><mes...
name="NameMessage"><part name="name"
type="xsd:string"/></message><message
name="GreetingMessage"><part name="greeting"
type="xsd:string"/></message><portType
name="Greeter"><operation
name="sayHello"><input
message="tns:NameMessage"/><output
message="tns:GreetingMessage"/></operation></portType></definitions></programlisting>The
document that describes our business behavior appears below. There are three major
sections in it.
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+The <literal>partnerLinks</literal> section lists the parties that interact
with the process in the course of greeting the world. The sole partner link shown here
corresponds to the agent sending the person name (the
<emphasis>caller</emphasis>).
+</para>
+</listitem>
+<listitem>
+<para>
+The <literal>variables</literal> section defines the data items held by the
process between message exchanges. The ability to mantain data effectively makes the
service provided by the process stateful. The state includes received and sent messages as
well as intermediate data used in business logic.
+</para>
+</listitem>
+<listitem>
+<para>
+The rest of the document describes the normal activities for handling a greeting request.
BPEL also provides the means to perform activities in response to faults. Our trivial
endpoint does not require them, tough.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+<programlisting><process name="HelloWorld"
targetNamespace="http://jbpm.org/examples/hello"
+ xmlns="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
+ xmlns:tns="http://jbpm.org/examples/hello"
+
xmlns:bpel="http://schemas.xmlsoap.org/ws/2003/03/business-process/&...
name="caller" partnerLinkType="tns:Greeter-Caller"
myRole="Greeter"
/></partnerLinks><variables><variable
name="request" messageType="tns:NameMessage" /><variable
name="response" messageType="tns:GreetingMessage"
/></variables><sequence><receive
operation="sayHello" partnerLink="caller"
portType="tns:Greeter"
+ variable="request" createInstance="yes"
/><assign><copy><from
expression="concat('Hello, ',
+ bpel:getVariableData('request', 'name'),
+ '!')" /><to variable="response"
part="greeting"
/></copy></assign><reply
operation="sayHello" partnerLink="caller"
portType="tns:Greeter"
+ variable="response"
/></sequence></process></programlisting>Notice
the <literal>caller</literal> partner link references a
<literal>partnerLinkType</literal> artifact not introduced so far. Partner
link types are WSDL extensibility elements that represent the relationship between two
services. WS-BPEL uses them as the glue between the process and its partner services.
+</para>
+<para>
+For the process definition to be complete, we add the partner link type to the WSDL
document presented earlier.<programlisting><definitions
targetNamespace="http://jbpm.org/examples/hello"
+ ...
+
xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"...
name="Greeter-Caller"><plt:role
name="Greeter"><plt:portType
name="tns:Greeter"/></plt:role></plt:partnerLinkType></definitions></programlisting>
+</para>
+
+</section>
+<section><title>Storing the process definition in the jBPM
database</title>
+<para>
+In the domain of business processes, traceability is important. Process engines are
expected to maintain not only the current state of each process instance, but also the
history of performed activities and updated variables.
+</para>
+<para>
+To provide these features, the JBoss BPEL implementation builds on <ulink
url="http://www.jboss.com/products/jbpm"><citetitle>JBoss
jBPM</citetitle></ulink>. The Graph Oriented Programming (<ulink
url="http://jbpm.org/gop"><citetitle>GOP</citetitle...>)
foundation in jBPM maintains past and present graph state in a database.
+</para>
+<para>
+Installing the jBPM service in JBoss AS is a prerrequisite. The samples suite installs a
preconfigured service archive automatically. Please refer to the jBPM BPEL <ulink
url="http://docs.jboss.com/jbpm/bpel/getstarted.html#getstarted.setu...
guide</citetitle></ulink>for details on how to customize the service to match
your requirements and deployment environment. The sample code that accompanies this
chapter was developed and tested with jBPM BPEL version 1.1.Beta3.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+The preconfigured jBPM service comes with an <ulink
url="http://www.hsqldb.org/"><citetitle>HSQL</citet...
database, useful for development purposes. In production, you can switch to the database
of your choice.
+</para>
+<para>
+Before the process can serve requests, its definition must be stored in the jBPM
database. The unit test setup code shown below performs this operation. This code comes
from class
<literal>org.jboss.test.ws.jaxrpc.samples.wsbpel.JbpmBpelTestSetup</literal>.
The argument is a zip file containing your BPEL process and related WSDL interfaces. The
<literal>submitRequest</literal> method submits the zip file to a web module
deployed as part of the jBPM BPEL service. The web module connects to the database and
stores the process definition.<programlisting>public static void deployProcess(File
processFile) throws Exception
+{
+ // format file component
+ String file = getJbpmBpelDeployContext() + "?processfile=" +
URLEncoder.encode(processFile.toURI().toString(), "UTF-8");
+
+ // create target URL
+ URL targetUrl = new URL("http", JBossWSTestHelper.getServerHost(),
getServerHttpPort(), file);
+
+ // submit process deploy request
+ int responseCode = submitRequest(targetUrl);
+
+ if (responseCode != HttpURLConnection.HTTP_OK)
+ throw new IOException("could not deploy process: " + processFile);
+}</programlisting>The file <literal>bpel-definition.xml</literal> tells
the location of the BPEL and WSDL documents inside the
archive.<programlisting><bpelDefinition location="hello.bpel"
xmlns="http://jbpm.org/bpel"><imports>&...
location="hello.wsdl"
/></imports></bpelDefinition></programlisting><emphasis
role="bold">Note</emphasis>
+</para>
+<para>
+The definition descriptor can also reference external WSDL documents.
+</para>
+
+</section>
+<section><title>Generating the required artifacts</title>
+<para>
+Deploying a BPEL process is similar to deploying a JSR-109 endpoint starting with WSDL.
+</para>
+<para>
+A BPEL process references the port types of the participants only, not their possible
bindings or actual endpoint addresses, as mentioned in defining a process. On the other
hand, a JSR-109 deployment requires the presence of binding and service elements. JBoss
BPEL supplies a tool that generates SOAP 1.1 binding and service elements required for
deploying the web service provided by the process.<programlisting><taskdef
name="servicegen"
classname="org.jbpm.bpel.ant.ServiceGeneratorTask"><classpath
refid="jbpm.bpel.classpath"/></taskdef><servicegen
processfile="${tests.output.dir}/libs/jaxrpc-samples-wsbpel-hello-process.zip"
+
outputdir="${tests.output.dir}/wstools/resources/jaxrpc/samples/wsbpel/hello/WEB-INF/wsdl"
+ bindingfile="hello-binding-.wsdl" servicefile="hello-service.wsdl"
/></programlisting>The generated WSDL can be passed to
<literal>wstools</literal>. Use the following
configuration.<programlisting><configuration
xmlns="http://www.jboss.org/jbossws-tools"><globa...
package="org.jboss.test.ws.jaxrpc.samples.wsbpel.hello"
+ namespace="http://jbpm.org/examples/hello"
/></global><wsdl-java
location="wstools/resources/jaxrpc/samples/wsbpel/hello/WEB-INF/wsdl/hello-service.wsdl"><mapping
file="jaxrpc-mapping.xml"
/></wsdl-java></configuration></programlisting>
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+
+</para>
+<para>
+JBoss BPEL does not use the Java mapping artifacts that
<literal>wstools</literal> produces. Keep in mind that variables in a BPEL
process are defined in terms of XML types and WSDL messages. JBoss BPEL extracts XML
content from SOAP messages and places it in the process variables directly.
+</para>
+<para>
+Nevertheless, the Java mapping artifacts still must be present for the JSR-109 deployment
to be valid. Notice the supplied service implementation bean has empty methods only. The
BPEL process specifies the behavior instead.
+</para>
+
+</section>
+<section><title>Configuring the port component</title>
+<para>
+Similar to the Addressing and Security components, JBoss BPEL uses a JAX-RPC message
handler to extract XML content from SOAP
messages.<programlisting><handler><handler-name>GreeterSoapHandler</handler-name><handler-class>org.jbpm.bpel.integration.server.SoapHandler</handler-class><init-param><description>name
of the partner link served by this
port</description><param-name>partnerLinkHandle</param-name><param-value>caller</param-value></init-param></handler></programlisting>A
separate descriptor, <literal>bpel-application.xml</literal>, specifies the
name of the process definition.<programlisting><bpelApplication
name="HelloWorld" xmlns="http://jbpm.org/bpel"
/></programlisting><emphasis
role="bold">Note</emphasis>
+</para>
+<para>
+This name will be used to retrieve the process definition from the jBPM database. It must
match the process name in your BPEL document.
+</para>
+
+</section>
+<section><title>Consuming the published web service</title>
+<para>
+No special configuration is needed on the client side. You consume a service provided by
a WS-BPEL process the same way you consume any other service.
+</para>
+<para>
+You can reuse the Java mapping artifacts generated earlier to develop a J2EE-1.4
Client.<programlisting>InitialContext iniCtx = getInitialContext();
+helloService =
(HelloWorldService)iniCtx.lookup("java:comp/env/service/BpelHello");
+
+Greeter proxy = helloService.getGreeterPort();
+String greeting = proxy.sayHello("Popeye");
+assertEquals("Hello, Popeye!", greeting);</programlisting>
+</para>
+
+</section>
+
+</section>
+<section><title>WS-Eventing</title>
+<para>
+WS-Eventing has been migrated to JAX-WS User Guide#WS-Eventing. It is no longer supported
in JAX-RPC.
+</para>
+
+</section>
+<section><title>WS-Security</title>
+<para>
+This section is specific to WS-Security for JAX-RPC endpoints/client. For general
information, please refer to JAX-WS User Guide#WS-Security
+</para>
+<para>
+<emphasis role="bold">Generating required deployment
artifacts</emphasis>
+</para>
+<para>
+Lets start with a trivial service endpoint interface (SEI) that echos a user defined
type.<programlisting> public interface Hello extends
Remote</programlisting><programlisting>
{</programlisting><programlisting> public UserType echoUserType(UserType
in0) throws RemoteException;</programlisting><programlisting>
}</programlisting>
+</para>
+<para>
+Run wstools with the following configuration
+</para>
+<para>
+<programlisting><configuration
...><java-wsdl><service name="HelloService"
style="rpc"
+
endpoint="org.jboss.test.ws.jaxrpc.samples.wssecurity.Hello"/><namespaces
target-namespace="http://org.jboss.ws/samples/wssecurity"
+
type-namespace="http://org.jboss.ws/samples/wssecurity/types"/><mapping
file="jaxrpc-mapping.xml"/><webservices
servlet-link="HelloService"/></java-wsdl></configuration></programlisting>
+</para>
+<para>
+<emphasis role="bold">Configuration and setup</emphasis>
+</para>
+<para>
+JBossWS uses handlers to identify ws-security encoded requests and invoke the security
components to sign and encrypt messages. In order to enable security processing, the
client and server side need to include a corressponding handler configuration. The
preferred way is to reference a JAX-RPC Client Configuration#Standard WSSecurity Client
+</para>
+<para>
+<programlisting><jboss-client><jndi-name>jbossws-client</jndi-name><service-ref><service-ref-name>service/HelloService</service-ref-name><config-name>Standard
WSSecurity
Client</config-name><wsdl-override>http://@jbosstest.host.name@:8080/jbossws-samples-wssecurity-encrypt?wsdl</wsdl-override></service-ref></jboss-client></programlisting>
+</para>
+
+</section>
+<section><title>WS-Transaction</title>
+<para>
+Support for the WS-Coordination, WS-AtomicTransaction and WS-BusinessActivity
specifications will be provided by technology recently acquired from Arjuna Technologies
Ltd. This technology will be present within the JBoss Transactions 4.2.1 release. Further
information can be obtained from the <ulink
url="http://labs.jboss.org/portal/jbosstm"><citetitle>...
Transactions Project</citetitle></ulink>
+</para>
+
+</section>
+<section><title>XML Registries</title>
+<para>
+The JAXR sample has been migrated to JAX-WS User Guide#XML Registries.
+</para>
+
+</section>
+<section><title>Apendix A</title>
+<para>
+<ulink
url="http://labs.jboss.com/file-access/default/members/jbossws/downl...
configuration syntax</citetitle></ulink>
+</para>
+<para>
+JAX-RPC Endpoint Configuration
+</para>
+<para>
+JAX-RPC Client Configuration
+</para>
+</section>
+</article>
+</book>
\ No newline at end of file
Property changes on: tags/jbossws-2.0.0.GA/docs/jaxrpc-userguide.xml
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ LF
Added: tags/jbossws-2.0.0.GA/docs/jaxws-userguide.xml
===================================================================
--- tags/jbossws-2.0.0.GA/docs/jaxws-userguide.xml (rev 0)
+++ tags/jbossws-2.0.0.GA/docs/jaxws-userguide.xml 2007-07-11 11:58:28 UTC (rev 3847)
@@ -0,0 +1,2694 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<book>
+<bookinfo><title>JBossWS 2.0.GA - JAX-WS User
Guide</title><legalnotice><para>Permission to use, copy, modify and
distribute this document under the GNU Free Documentation License
(GFDL).</para></legalnotice></bookinfo><article
id="User_Guide">
+<title>User Guide</title>
+<para>
+Category:Build and Deploy (User Guide)
+</para>
+<para>
+
+</para>
+<para>
+This guide does cover <emphasis role="bold">JAX-WS</emphasis>
functionality only, if you are looking for J2EE-1-4 compliant web services (i.e. the
JSR-109 programming model) please goto the JAX-RPC User Guide.
+</para>
+<para>
+To get started you need to <emphasis
role="bold">download</emphasis> jbossws and <emphasis
role="bold">install</emphasis> JBossWS on your preferred target
container.
+</para>
+<para>
+This user guide applies to <emphasis
role="bold">jbossws-1.2.0</emphasis> and higher. For older versions,
please consult the <ulink
url="http://labs.jboss.com/portal/jbossws/user-guide/en/html/index.h...
User Guide</citetitle></ulink> on <ulink
url="http://labs.jboss.com/portal/jbossws"><citetitle>...;.
+</para>
+<para>
+Since 1.2
+</para>
+<section><title>Web Service Concepts</title>
+<section><title>Document/Literal</title>
+<para>
+With document style web services two business partners agree on the exchange of complex
business documents that are well defined in XML schema. For example, one party sends a
document describing a purchase order, the other responds (immediately or later) with a
document that describes the status of the purchase order. No need to agree on such low
level details as operation names and their associated parameters.
+</para>
+<para>
+The payload of the SOAP message is an XML document that can be validated against XML
schema.
+</para>
+<para>
+Document is defined by the style attribute on the SOAP binding.
+</para>
+<para>
+<programlisting><binding name='EndpointInterfaceBinding'
type='tns:EndpointInterface'><soap:binding style='document'
transport='http://schemas.xmlsoap.org/soap/http'/><...
name='concat'><soap:operation
soapAction=''/><input><soap:body
use='literal'/></input><output><soap:body
use='literal'/></output></operation></binding></programlisting>
+</para>
+<para>
+With document style web services the payload of every message is defined by a complex
type in XML schema.
+</para>
+<para>
+<programlisting><complexType
name='concatType'><sequence><element
name='String_1' nillable='true'
type='string'/><element name='long_1'
type='long'/></sequence></complexType><element
name='concat' type='tns:concatType'/></programlisting>
+</para>
+<para>
+Therefore, message parts <emphasis role="bold">must</emphasis>
refer to an <emphasis role="bold">element</emphasis> from the
schema.
+</para>
+<para>
+<programlisting><message
name='EndpointInterface_concat'><part name='parameters'
element='tns:concat'/></message></programlisting>
+</para>
+<para>
+The following message definition <emphasis role="bold">is
invalid</emphasis>.
+</para>
+<para>
+<programlisting><message
name='EndpointInterface_concat'><part name='parameters'
type='tns:concatType'/></message></programlisting>
+</para>
+<section><title>Document/Literal (Bare)</title>
+<para>
+Bare is an implementation detail from the Java domain. Neither in the abstract contract
(i.e. wsdl+schema) nor at the SOAP message level is a bare endpoint recognizable.
+</para>
+<para>
+A bare endpoint or client uses a Java bean that represents the entire document payload.
+</para>
+<para>
+<programlisting>
+@WebService
+@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
+public class DocBareServiceImpl
+{
+ @WebMethod
+ public SubmitBareResponse submitPO(SubmitBareRequest poRequest)
+ {
+ ...
+ }
+}
+</programlisting>
+</para>
+<para>
+The trick is that the Java beans representing the payload contain JAXB annotations that
define how the payload is represented on the wire.
+</para>
+<para>
+<programlisting>
+(a)XmlAccessorType(XmlAccessType.FIELD)
+@XmlType(name = "SubmitBareRequest",
namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/";, propOrder = {
"product" })
+@XmlRootElement(namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/",
name = "SubmitPO")
+public class SubmitBareRequest
+{
+ @XmlElement(namespace="http://soapbinding.samples.jaxws.ws.test.jboss.org/",
required = true)
+ private String product;
+
+ ...
+}
+</programlisting>
+</para>
+
+</section>
+<section><title>Document/Literal (Wrapped)</title>
+<para>
+Wrapped is an implementation detail from the Java domain. Neither in the abstract
contract (i.e. wsdl+schema) nor at the SOAP message level is a wrapped endpoint
recognizable.
+</para>
+<para>
+A wrapped endpoint or client uses the individual document payload properties. Wrapped is
the default and does not have to be declared explicitly.
+</para>
+<para>
+<programlisting>
+@WebService
+public class DocWrappedServiceImpl
+{
+ @WebMethod
+ @RequestWrapper (className="org.somepackage.SubmitPO")
+ @ResponseWrapper (className="org.somepackage.SubmitPOResponse")
+ public String submitPO(String product, int quantity)
+ {
+ ...
+ }
+}
+</programlisting>
+</para>
+<para>
+Note, that with JBossWS the request/response wrapper annotations are <emphasis
role="bold">not required</emphasis>, they will be generated on demand
using sensible defaults.
+</para>
+
+</section>
+
+</section>
+<section><title>RPC/Literal</title>
+<para>
+With RPC there is a wrapper element that names the endpoint operation. Child elements of
the RPC parent are the individual parameters.
+</para>
+<para>
+The SOAP body is constructed based on some simple rules:
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+The port type operation name defines the endpoint method name
+</para>
+</listitem>
+<listitem>
+<para>
+Message parts are endpoint method parameters
+</para>
+</listitem>
+</itemizedlist>
+<para>
+RPC is defined by the style attribute on the SOAP binding.
+</para>
+<para>
+<programlisting><binding name='EndpointInterfaceBinding'
type='tns:EndpointInterface'><soap:binding style='rpc'
transport='http://schemas.xmlsoap.org/soap/http'/><...
name='echo'><soap:operation
soapAction=''/><input><soap:body
namespace='http://org.jboss.ws/samples/jsr181pojo'
use='literal'/></input><output><soap:body
namespace='http://org.jboss.ws/samples/jsr181pojo'
use='literal'/></output></operation></binding></programlisting>
+</para>
+<para>
+With rpc style web services the portType names the operation (i.e. the java method on the
endpoint)
+</para>
+<para>
+<programlisting><portType
name='EndpointInterface'><operation name='echo'
parameterOrder='String_1'><input
message='tns:EndpointInterface_echo'/><output
message='tns:EndpointInterface_echoResponse'/></operation></portType></programlisting>
+</para>
+<para>
+Operation parameters are defined by individual message parts.
+</para>
+<para>
+<programlisting><message
name='EndpointInterface_echo'><part name='String_1'
type='xsd:string'/></message><message
name='EndpointInterface_echoResponse'><part name='result'
type='xsd:string'/></message></programlisting>
+</para>
+<para>
+Note, there is no complex type in XML schema that could validate the entire SOAP message
payload.
+</para>
+<para>
+<programlisting>
+@WebService
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+public class JSEBean01
+{
+ @WebMethod
+ @WebResult(name="result")
+ public String echo(@WebParam(name="String_1") String input)
+ {
+ ...
+ }
+}
+</programlisting>
+</para>
+<para>
+The element names of RPC parameters/return values may be defined using the JAX-WS
Annotations#javax.jws.WebParam and JAX-WS Annotations#javax.jws.WebResult respectively.
+</para>
+
+</section>
+<section><title>RPC/Encoded</title>
+<para>
+SOAP encodeding style is defined by the infamous <ulink
url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383512&quo...
5</citetitle></ulink> of the <ulink
url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508"><citet...
specification. <emphasis role="bold">It has inherent interoperability
issues</emphasis> that cannot be fixed. The <ulink
url="http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html&q...
Profile-1.0</citetitle></ulink> prohibits this encoding style in <ulink
url="http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html#r...
SOAP encodingStyle Attribute</citetitle></ulink>.
+</para>
+<para>
+JBossWS has basic support for rpc/encoded that is <emphasis
role="bold">provided as is</emphasis> for simple interop scenarios with
SOAP stacks that do not support literal encoding.
+</para>
+<para>
+Specifically, JBossWS does not support
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+element references
+</para>
+</listitem>
+<listitem>
+<para>
+soap arrays as bean properties
+</para>
+</listitem>
+</itemizedlist>
+
+</section>
+
+</section>
+<section><title>Web Service Endpoints</title>
+<para>
+JAX-WS simplifies the development model for a web service endpoint a great deal. In
short, an endpoint implementation bean is annotated with JAX-WS annotations and deployed
to the server. The server automatically generates and publishes the abstract contract
(i.e. wsdl+schema) for client consumption. All marshalling/unmarshalling is delegated to
JAXB [2].
+</para>
+<section><title>Plain old Java Object (POJO)</title>
+<para>
+Let's take a look at simple POJO endpoint implementation. All endpoint associated
metadata is provided via JSR-181 annotations
+</para>
+<para>
+<programlisting>
+ @WebService
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ public class JSEBean01
+ {
+ @WebMethod
+ public String echo(String input)
+ {
+ ...
+ }
+ }
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">The endpoint as a web application</emphasis>
+</para>
+<para>
+A JAX-WS java service endpoint (JSE) is deployed as a web application.
+</para>
+<para>
+<programlisting><web-app
...><servlet><servlet-name>TestService</servlet-name><servlet-class>org.jboss.test.ws.jaxws.samples.jsr181pojo.JSEBean01</servlet-class></servlet><servlet-mapping><servlet-name>TestService</servlet-name><url-pattern>/*</url-pattern></servlet-mapping></web-app></programlisting>
+</para>
+<para>
+<emphasis role="bold">Packaging the endpoint</emphasis>
+</para>
+<para>
+A JSR-181 java service endpoint (JSE) is packaged as a web application in a *.war file.
+</para>
+<para>
+<programlisting><war
warfile="${build.dir}/libs/jbossws-samples-jsr181pojo.war"
webxml="${build.resources.dir}/samples/jsr181pojo/WEB-INF/web.xml"><classes
dir="${build.dir}/classes"><include
name="org/jboss/test/ws/samples/jsr181pojo/JSEBean01.class"/></classes></war></programlisting>
+</para>
+<para>
+Note, only the endpoint implementation bean and web.xml are required.
+</para>
+<para>
+<emphasis role="bold">Accessing the generated WSDL</emphasis>
+</para>
+<para>
+A successfully deployed service endpoint will show up in the service endpoint manager.
This is also where you find the links to the generated wsdl.
+</para>
+<para>
+<programlisting>
+ http://yourhost:8080/jbossws/services
+</programlisting>
+</para>
+<para>
+Note, it is also possible to generate the abstract contract off line using jbossw tools.
For details of that please see #Top Down (Java to WSDL)
+</para>
+
+</section>
+<section><title>EJB3 Stateless Session Bean (SLSB)</title>
+<para>
+The JAX-WS programming model support the same set of annotations on EJB3 stateless
session beans as on # Plain old Java Object (POJO) endpoints. EJB-2.1 endpoints are
supported using the JAX-RPC progamming model.
+</para>
+<para>
+<programlisting>
+ @Stateless
+ @Remote(EJB3RemoteInterface.class)
+ @RemoteBinding(jndiBinding = "/ejb3/EJB3EndpointInterface")
+
+ @WebService
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ public class EJB3Bean01 implements EJB3RemoteInterface
+ {
+ @WebMethod
+ public String echo(String input)
+ {
+ ...
+ }
+ }
+</programlisting>
+</para>
+<para>
+Above you see an EJB-3.0 stateless session bean that exposes one method both on the
remote interface and on and as an endpoint operation.
+</para>
+<para>
+<emphasis role="bold">Packaging the endpoint</emphasis>
+</para>
+<para>
+A JSR-181 EJB service endpoint is packaged as an ordinary ejb deployment.
+</para>
+<para>
+<programlisting><jar
jarfile="${build.dir}/libs/jbossws-samples-jsr181ejb.jar"><fileset
dir="${build.dir}/classes"><include
name="org/jboss/test/ws/samples/jsr181ejb/EJB3Bean01.class"/><include
name="org/jboss/test/ws/samples/jsr181ejb/EJB3RemoteInterface.class"/></fileset></jar></programlisting>
+</para>
+<para>
+<emphasis role="bold">Accessing the generated WSDL</emphasis>
+</para>
+<para>
+A successfully deployed service endpoint will show up in the service endpoint manager.
This is also where you find the links to the generated wsdl.
+</para>
+<para>
+<programlisting>
+ http://yourhost:8080/jbossws/services
+</programlisting>
+</para>
+<para>
+Note, it is also possible to generate the abstract contract off line using jbossw tools.
For details of that please see #Top Down (Java to WSDL)
+</para>
+
+</section>
+<section><title>Endpoint Provider</title>
+<para>
+JAX-WS services typically implement a native Java service endpoint interface (SEI),
perhaps mapped froma WSDL port type, either directly or via the use of annotations.
+</para>
+<para>
+Java SEIs provide a high level Java-centric abstraction that hides the details of
converting between Javaobjects and their XML representations for use in XML-based
messages. However, in some cases it isdesirable for services to be able to operate at the
XML message level. The Provider interface offers analternative to SEIs and may be
implemented by services wishing to work at the XML message level.
+</para>
+<para>
+A Provider based service instance?s invoke method is called for each message received for
the service.
+</para>
+<para>
+<programlisting>
+ @WebServiceProvider
+ @ServiceMode(value = Service.Mode.PAYLOAD)
+ public class ProviderBeanPayload implements Provider<Source>
+ {
+ public Source invoke(Source req)
+ {
+ // Access the entire request PAYLOAD and return the response PAYLOAD
+ }
+ }
+</programlisting>
+</para>
+<para>
+Note, Service.Mode.PAYLOAD is the default and does not have to be declared explicitly.
You can also use Service.Mode.MESSAGE to access the entire SOAP message (i.e. with MESSAGE
the Provider can also see SOAP Headers)
+</para>
+
+</section>
+<section><title>WebServiceContext</title>
+<para>
+The WebServiceContext is treated as an injectable resource that can be set at the time an
endpoint isinitialized. The WebServiceContext object will then use thread-local
information to return the correctinformation regardless of how many threads are
concurrently being used to serve requests addressed to thesame endpoint object.
+</para>
+<para>
+<programlisting>
+ @WebService
+ public class EndpointJSE
+ {
+ @Resource
+ WebServiceContext wsCtx;
+
+ @WebMethod
+ public String testGetMessageContext()
+ {
+ SOAPMessageContext jaxwsContext = (SOAPMessageContext)wsCtx.getMessageContext();
+ return jaxwsContext != null ? "pass" : "fail";
+ }
+
+ @WebMethod
+ public String testGetUserPrincipal()
+ {
+ Principal principal = wsCtx.getUserPrincipal();
+ return principal.getName();
+ }
+
+ @WebMethod
+ public boolean testIsUserInRole(String role)
+ {
+ return wsCtx.isUserInRole(role);
+ }
+ }
+</programlisting>
+</para>
+
+</section>
+
+</section>
+<section><title>Web Service Clients</title>
+<section><title>Service</title>
+<para>
+<literal>Service</literal> is an abstraction that represents a WSDL service.
A WSDL service is a collection of related ports, each of which consists of a port type
bound to a particular protocol and available at a particular endpoint address.
+</para>
+<section><title>Service Usage</title>
+<para>
+<emphasis role="bold">Dynamic case</emphasis>
+</para>
+<para>
+In the dynamic case, when nothing is generated, a web service client uses
<literal>Service.create</literal> to createService instances, the following
code illustrates this process.
+</para>
+<para>
+<programlisting>
+ URL wsdlLocation = new URL("http://example.org/my.wsdl");
+ QName serviceName = new QName("http://example.org/sample";,
"MyService");
+ Service service = Service.create(wsdlLocation, serviceName);
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">Static case</emphasis>
+</para>
+<para>
+When starting from a WSDL document, a concrete service implementation class
<emphasis>MUST</emphasis> be generated by jbossws tools. The generated
implementation class will have two public constructors, one with no arguments and one with
two arguments, representing the wsdl location (a java.net.URL) and the servicename (a
javax.xml.namespace.QName) respectively.
+</para>
+<para>
+When using the no-argument constructor, the WSDL location and service name are implicitly
taken from the WebServiceClient annotation that decorates the generated class.
+</para>
+<para>
+The following code snippet shows the generated constructors:
+</para>
+<para>
+<programlisting>
+ // Generated Service Class
+
+ @WebServiceClient(name="StockQuoteService",
targetNamespace="http://example.com/stocks";,
wsdlLocation="http://example.com/stocks.wsdl")
+ public class StockQuoteService extends javax.xml.ws.Service
+ {
+ public StockQuoteService()
+ {
+ super(new URL("http://example.com/stocks.wsdl"), new
QName("http://example.com/stocks";, "StockQuoteService"));
+ }
+
+ public StockQuoteService(String wsdlLocation, QName serviceName)
+ {
+ super(wsdlLocation, serviceName);
+ }
+
+ ...
+}
+</programlisting>
+</para>
+<para>
+Section #Dynamic Proxy explains how to obtain a port from the service and how to invoke
an operation on the port. If you need to work with the XML payload directly or with the
XML representation of the entire SOAP message, have a look at #Dispatch.
+</para>
+
+</section>
+<section><title>Handler Resolver</title>
+<para>
+JAX-WS provides a flexible plug-in framework for message processing modules, known as
handlers, that may be used to extend the capabilities of a JAX-WS runtime system. #Handler
Framework describes the handler framework in detail. A Service instance provides access to
a HandlerResolver via a pair of getHandlerResolver/setHandlerResolver methods that may be
used to configure a set of handlers on a per-service, per-port or per-protocol binding
basis.
+</para>
+<para>
+When a Service instance is used to create a proxy or a Dispatch instance then the handler
resolver currently registered with the service is used to create the required handler
chain. Subsequent changes to the handler resolver configured for a Service instance do not
affect the handlers on previously created proxies, or Dispatch instances.
+</para>
+<para>
+[TODO] <ulink
url="http://jira.jboss.org/jira/browse/JBWS-1512"><citeti...
Provide a sample for Service HandlerResolver</citetitle></ulink>
+</para>
+
+</section>
+<section><title>Executor</title>
+<para>
+Service instances can be configured with a java.util.concurrent.Executor. The executor
willthen be used to invoke any asynchronous callbacks requested by the application. The
setExecutor andgetExecutor methods of Service can be used to modify and retrieve the
executor configured for aservice.
+</para>
+<para>
+[TODO] <ulink
url="http://jira.jboss.org/jira/browse/JBWS-1513"><citeti...
Provide a sample for Service Executor</citetitle></ulink>
+</para>
+
+</section>
+
+</section>
+<section><title>Dynamic Proxy</title>
+<para>
+You can create an instance of a client proxy using one of getPort methods on the
#Service.
+</para>
+<para>
+<programlisting>
+ /**
+ * The getPort method returns a proxy. A service client
+ * uses this proxy to invoke operations on the target
+ * service endpoint. The
<code>serviceEndpointInterface</code>
+ * specifies the service endpoint interface that is supported by
+ * the created dynamic proxy instance.
+ **/
+ public <T> T getPort(QName portName, Class<T>
serviceEndpointInterface)
+ {
+ ...
+ }
+
+ /**
+ * The getPort method returns a proxy. The parameter
+ * <code>serviceEndpointInterface</code> specifies the
service
+ * endpoint interface that is supported by the returned proxy.
+ * In the implementation of this method, the JAX-WS
+ * runtime system takes the responsibility of selecting a protocol
+ * binding (and a port) and configuring the proxy accordingly.
+ * The returned proxy should not be reconfigured by the client.
+ *
+ **/
+ public <T> T getPort(Class<T> serviceEndpointInterface)
+ {
+ ...
+ }
+</programlisting>
+</para>
+<para>
+The service endpoint interface (SEI) is usually generated using tools. For details see #
Top Down (WSDL to Java)
+</para>
+<para>
+A generated static #Service usually also offers typed methods to get ports. These methods
also return dynamic proxies that implement the SEI.
+</para>
+<para>
+<programlisting>
+@WebServiceClient(name = "TestEndpointService", targetNamespace =
"http://org.jboss.ws/wsref",
+ wsdlLocation =
"http://localhost.localdomain:8080/jaxws-samples-webserviceref?wsdl")
+
+public class TestEndpointService extends Service
+{
+ ...
+
+ public TestEndpointService(URL wsdlLocation, QName serviceName) {
+ super(wsdlLocation, serviceName);
+ }
+
+ @WebEndpoint(name = "TestEndpointPort")
+ public TestEndpoint getTestEndpointPort()
+ {
+ return (TestEndpoint)super.getPort(TESTENDPOINTPORT, TestEndpoint.class);
+ }
+}
+</programlisting>
+</para>
+
+</section>
+<section><title>WebServiceRef</title>
+<para>
+The WebServiceRef annotation is used to declare a reference to a Web service. It follows
the resource pattern exemplified by the javax.annotation.Resource annotation in JSR-250
[5]
+</para>
+<para>
+There are two uses to the WebServiceRef annotation:
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+To define a reference whose type is a generated service class. In this case, the type and
value element will both refer to the generated service class type. Moreover, if the
reference type can be inferred by the field/method declaration the annotation is applied
to, the type and value elements MAY have the default value (Object.class, that is). If the
type cannot be inferred, then at least the type element MUST be present with a non-default
value.
+</para>
+</listitem>
+<listitem>
+<para>
+To define a reference whose type is a SEI. In this case, the type element MAY be present
with its default value if the type of the reference can be inferred from the annotated
field/method declaration, but the value element MUST always be present and refer to a
generated service class type (a subtype of javax.xml.ws.Service). The wsdlLocation
element, if present, overrides theWSDL location information specified in the WebService
annotation of the referenced generated service class.
+</para>
+</listitem>
+</orderedlist>
+<para>
+<programlisting>
+public class EJB3Client implements EJB3Remote
+{
+ @WebServiceRef
+ public TestEndpointService service4;
+
+ @WebServiceRef
+ public TestEndpoint port3;
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">WebServiceRef Customization</emphasis>
+</para>
+<para>
+In jboss-5.0.x we offer a number of overrides and extensions to the WebServiceRef
annotation. These include
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+define the port that should be used to resolve a container-managed port
+</para>
+</listitem>
+<listitem>
+<para>
+define default Stub property settings for Stub objects
+</para>
+</listitem>
+<listitem>
+<para>
+define the URL of a final WSDL document to be used
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Example:
+</para>
+<para>
+<programlisting><service-ref><service-ref-name>OrganizationService</service-ref-name><wsdl-override>file:/wsdlRepository/organization-service.wsdl</wsdl-override></service-ref><service-ref><service-ref-name>OrganizationService</service-ref-name><config-name>Secure
Client
Config</config-name><config-file>META-INF/jbossws-client-config.xml</config-file><handler-chain>META-INF/jbossws-client-handlers.xml</handler-chain></service-ref><service-ref><service-ref-name>SecureService</service-ref-name><service-class-name>org.jboss.tests.ws.jaxws.webserviceref.SecureEndpointService</service-class-name><service-qname>{http://org.jboss.ws/wsref}SecureEndpointService</service-qname><port-info><service-endpoint-interface>org.jboss.tests.ws.jaxws.webserviceref.SecureEndpoint</service-endpoint-interface><port-qname>{http://org.jbos!
s.ws/wsref}SecureEndpointPort</port-qname><stub-property><name>javax.xml.ws.security.auth.username</name><value>kermit</value></stub-property><stub-property><name>javax.xml.ws.security.auth.password</name><value>thefrog</value></stub-property></port-info></service-ref></programlisting>
+</para>
+<para>
+For details please see <emphasis
role="bold">service-ref_5_0.dtd</emphasis> in the jboss docs
directory.
+</para>
+
+</section>
+<section><title>Dispatch</title>
+<para>
+XMLWeb Services use XML messages for communication between services and service clients.
The higher level JAX-WS APIs are designed to hide the details of converting between Java
method invocations and the corresponding XML messages, but in some cases operating at the
XML message level is desirable. The Dispatch interface provides support for this mode of
interaction.
+</para>
+<para>
+Dispatch supports two usage modes, identified by the constants
javax.xml.ws.Service.Mode.MESSAGE and javax.xml.ws.Service.Mode.PAYLOAD respectively:
+</para>
+<para>
+<emphasis role="bold">Message</emphasis> In this mode, client
applications work directly with protocol-specific message structures. E.g., when used with
a SOAP protocol binding, a client application would work directly with a SOAP message.
+</para>
+<para>
+<emphasis role="bold">Message Payload</emphasis> In this mode,
client applications work with the payload of messages rather than the messages themselves.
E.g., when used with a SOAP protocol binding, a client application would work with the
contents of the SOAP Body rather than the SOAP message as a whole.
+</para>
+<para>
+Dispatch is a low level API that requires clients to construct messages or message
payloads as XML and requires an intimate knowledge of the desired message or payload
structure. Dispatch is a generic class that supports input and output of messages or
message payloads of any type.
+</para>
+<para>
+<programlisting>
+ Service service = Service.create(wsdlURL, serviceName);
+ Dispatch dispatch = service.createDispatch(portName, StreamSource.class, Mode.PAYLOAD);
+
+ String payload = "<ns1:ping
xmlns:ns1='http://oneway.samples.jaxws.ws.test.jboss.org/'/&g...;
+ dispatch.invokeOneWay(new StreamSource(new StringReader(payload)));
+
+ payload = "<ns1:feedback
xmlns:ns1='http://oneway.samples.jaxws.ws.test.jboss.org/'/&g...;
+ Source retObj = (Source)dispatch.invoke(new StreamSource(new StringReader(payload)));
+</programlisting>
+</para>
+
+</section>
+<section><title>Asynchronous Invocations</title>
+<para>
+The BindingProvider interface represents a component that provides a protocol binding for
use by clients, it is implemented by proxies and is extended by the Dispatch interface.
+</para>
+<para>
+<mediaobject>
+<imageobject>
+<imagedata fileref="http:///images/3/3e/Binding-provider.gif"/>
+</imageobject>
+<textobject>
+<phrase>Binding Provider Class Relationships</phrase>
+</textobject>
+</mediaobject>
+
+</para>
+<para>
+BindingProvider instances may provide asynchronous operation capabilities. When used,
asynchronous operation invocations are decoupled from the BindingProvider instance at
invocation time such that the response context is not updated when the operation
completes. Instead a separate response context is made available using the Response
interface.
+</para>
+<para>
+<programlisting>
+ public void testInvokeAsync() throws Exception
+ {
+ URL wsdlURL = new URL("http://" + getServerHost() +
":8080/jaxws-samples-asynchronous?wsdl");
+ QName serviceName = new QName(targetNS, "TestEndpointService");
+ Service service = Service.create(wsdlURL, serviceName);
+ TestEndpoint port = service.getPort(TestEndpoint.class);
+
+ Response response = port.echoAsync("Async");
+
+ // access future
+ String retStr = (String) response.get();
+ assertEquals("Async", retStr);
+ }
+</programlisting>
+</para>
+
+</section>
+<section><title>Oneway Invocations</title>
+<para>
+@Oneway indicates that the given web method has only an input message and no output.
Typically, a oneway method returns the thread of control to the calling application prior
to executing the actual business method.
+</para>
+<para>
+<programlisting>
+@WebService (name="PingEndpoint")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+public class PingEndpointImpl
+{
+ private static String feedback;
+
+ @WebMethod
+ @Oneway
+ public void ping()
+ {
+ log.info("ping");
+ feedback = "ok";
+ }
+
+ @WebMethod
+ public String feedback()
+ {
+ log.info("feedback");
+ return feedback;
+ }
+}
+</programlisting>
+</para>
+
+</section>
+
+</section>
+<section><title>Common API</title>
+<para>
+This sections describes concepts that apply equally to #Web Service Endpoints and #Web
Service Clients
+</para>
+<section><title>Handler Framework</title>
+<para>
+The handler framework is implemented by a JAX-WS protocol binding in both client and
server side runtimes. Proxies, and Dispatch instances, known collectively as binding
providers, each use protocol bindings to bind their abstract functionality to specific
protocols.
+</para>
+<para>
+Client and server-side handlers are organized into an ordered list known as a handler
chain. The handlers within a handler chain are invoked each time a message is sent or
received. Inbound messages are processed by handlers prior to binding provider processing.
Outbound messages are processed by handlers after any binding provider processing.
+</para>
+<para>
+Handlers are invoked with a message context that provides methods to access and modify
inbound and outbound messages and to manage a set of properties. Message context
properties may be used to facilitate communication between individual handlers and between
handlers and client and service implementations. Different types of handlers are invoked
with different types of message context.
+</para>
+<para>
+<mediaobject>
+<imageobject>
+<imagedata fileref="http:///images/0/07/Binding-handler.gif"/>
+</imageobject>
+<textobject>
+<phrase/>
+</textobject>
+</mediaobject>
+
+</para>
+<section><title>Logical Handler</title>
+<para>
+Handlers that only operate on message context properties and message payloads. Logical
handlersare protocol agnostic and are unable to affect protocol specific parts of a
message. Logical handlersare handlers that implement javax.xml.ws.handler.LogicalHandler.
+</para>
+
+</section>
+<section><title>Protocol Handler</title>
+<para>
+Handlers that operate on message context properties and protocol specific messages.
Protocol handlers are specific to a particular protocol and may access and change protocol
specific aspects of a message. Protocol handlers are handlers that implement any interface
derived from javax.xml.ws.handler.Handler except javax.xml.ws.handler.LogicalHandler.
+</para>
+
+</section>
+<section><title>Service endpoint handlers</title>
+<para>
+On the service endpoint, handlers are defined using the @HandlerChain annotation.
+</para>
+<para>
+<programlisting>
+@WebService
+@HandlerChain(file = "jaxws-server-source-handlers.xml")
+public class SOAPEndpointSourceImpl
+{
+ ...
+}
+</programlisting>
+</para>
+<para>
+The location of the handler chain file supports 2 formats
+</para>
+<para>
+1. An absolute java.net.URL in externalForm.(ex:
http://myhandlers.foo.com/handlerfile1.xml)
+</para>
+<para>
+2. A relative path from the source file or class file.(ex: bar/handlerfile1.xml)
+</para>
+
+</section>
+<section><title>Service client handlers</title>
+<para>
+On the client side, handler can be configured using the @HandlerChain annotation on the
SEI or dynamically using the API.
+</para>
+<para>
+<programlisting>
+ Service service = Service.create(wsdlURL, serviceName);
+ Endpoint port = (Endpoint)service.getPort(Endpoint.class);
+
+ BindingProvider bindingProvider = (BindingProvider)port;
+ List<Handler> handlerChain = new ArrayList<Handler>();
+ handlerChain.add(new LogHandler());
+ handlerChain.add(new AuthorizationHandler());
+ handlerChain.add(new RoutingHandler());
+ bindingProvider.getBinding().setHandlerChain(handlerChain); // important!
+</programlisting>
+</para>
+
+</section>
+
+</section>
+<section><title>Message Context</title>
+<para>
+MessageContext is the super interface for all JAX-WS message contexts. It extends
Map<String,Object> with additional methods and constants to manage a set of
properties that enable handlers in a handler chain to share processing related state. For
example, a handler may use the put method to insert a property in the message context that
one or more other handlers in the handler chain may subsequently obtain via the get
method.
+</para>
+<para>
+Properties are scoped as either APPLICATION or HANDLER. All properties are available to
all handlers for an instance of an MEP on a particular endpoint. E.g., if a logical
handler puts a property in the message context, that property will also be available to
any protocol handlers in the chain during the execution of an MEP instance. APPLICATION
scoped properties are also made available to client applications (see section 4.2.1) and
service endpoint implementations. The defaultscope for a property is HANDLER.
+</para>
+<section><title>Accessing the message context</title>
+<para>
+There is currently no portable way of doing this in 4.0.5.
<literal>@WebServiceContext</literal> injection will be available with 4.2. In
the meantime you can access the message context like this:
+</para>
+<para>
+<programlisting>
+CommonMessageContext msgContext = MessageContextAssociation.peekMessageContext();
+msgContext.setProperty(<Name>, <Value>);
+</programlisting>
+</para>
+
+</section>
+<section><title>Logical Message Context</title>
+<para>
+#Logical Handlers are passed a message context of type LogicalMessageContext when
invoked. LogicalMessageContext extends MessageContext with methods to obtain and modify
the message payload, it does not provide access to the protocol specific aspects of
amessage. A protocol binding defines what component of a message are available via a
logical message context. The SOAP binding defines that a logical handler deployed in a
SOAP binding can access the contents of the SOAP body but not the SOAP headers whereas the
XML/HTTP binding defines that a logical handler can access the entire XML payload of a
message.
+</para>
+
+</section>
+<section><title>SOAP Message Context</title>
+<para>
+SOAP handlers are passed a SOAPMessageContext when invoked. SOAPMessageContext extends
MessageContext with methods to obtain and modify the SOAP message payload.
+</para>
+
+</section>
+
+</section>
+<section><title>Fault Handling</title>
+<para>
+An implementation may thow a SOAPFaultException
+</para>
+<para>
+<programlisting>
+ public void throwSoapFaultException()
+ {
+ SOAPFactory factory = SOAPFactory.newInstance();
+ SOAPFault fault = factory.createFault("this is a fault string!", new
QName("http://foo", "FooCode"));
+ fault.setFaultActor("mr.actor");
+ fault.addDetail().addChildElement("test");
+ throw new SOAPFaultException(fault);
+ }
+</programlisting>
+</para>
+<para>
+or an application specific user exception
+</para>
+<para>
+<programlisting>
+ public void throwApplicationException() throws UserException
+ {
+ throw new UserException("validation", 123, "Some validation
error");
+ }
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+In case of the latter JBossWS generates the required fault wrapper beans at runtime if
they are not part of the deployment
+</para>
+
+</section>
+
+</section>
+<section><title>Tools</title>
+<para>
+The JAX-WS tools provided by JBossWS can be used in a variety of ways. First we will look
at server-side development strategies, and then proceed to the client. When developing a
Web Service Endpoint (the server-side) you have the option of starting from Java
(bottom-up development), or from the abstact contract (WSDL) that defines your service
(top-down development). If this is a new service (no existing contract), the bottom-up
approach is the fastest route; you only need to add a few annotations to your classes to
get a service up and running. However, if you are developing a service with an already
defined contract, it is far simpler to use the top-down approach, since the provided tool
will generate the annotated code for you.
+</para>
+<para>
+Bottom-up use cases:
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+Exposing an already existing EJB3 bean as a Web Service
+</para>
+</listitem>
+<listitem>
+<para>
+Providing a new service, and you want the contract to be generated for you
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Top-down use cases:
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+Replacing the implementation of an existing Web Service, and you can't break
compatibility with older clients
+</para>
+</listitem>
+<listitem>
+<para>
+Exposing a service that conforms to a contract specified by a third party (e.g. a vender
that calls you back using an already defined protocol).
+</para>
+</listitem>
+<listitem>
+<para>
+Creating a service that adheres to the XML Schema and WSDL you developed by hand up
front
+</para>
+</listitem>
+</itemizedlist>
+<para>
+The following JAX-WS command line tools are included in JBossWS:<table>
+<title/><tgroup cols="2"><tbody><row>
+<entry>
+Command
+</entry>
+<entry>
+Description
+</entry>
+
+</row>
+<row>
+<entry>
+wsprovide
+</entry>
+<entry>
+Generates JAX-WS portable artifacts, and provides the abstract contract. Used for
bottom-up development.
+</entry>
+
+</row>
+<row>
+<entry>
+wsconsume
+</entry>
+<entry>
+Consumes the abstract contract (WSDL and Schema files), and produces artifacts for both a
server and client. Used for top-down and client development
+</entry>
+
+</row>
+<row>
+<entry>
+wsrunclient
+</entry>
+<entry>
+Executes a Java client (has a main method) using the JBossWS classpath.
+</entry>
+
+</row>
+</tbody></tgroup>
+</table>
+
+</para>
+<section><title>Bottom-Up (Using wsprovide)</title>
+<para>
+The bottom-up strategy involves developing the Java code for your service, and then
annotating it using JAX-WS annotations. These annotations can be used to customize the
contract that is generated for your service. For example, you can change the operation
name to map to anything you like. However, all of the annotations have sensible defaults,
so only the @WebService annotation is required.
+</para>
+<para>
+This can be as simple as creating a single class:<programlisting>
+package echo;
+
+(a)javax.jws.WebService
+public class Echo
+{
+ public String echo(String input)
+ {
+ return input;
+ }
+}
+</programlisting>
+</para>
+<para>
+A JSE or EJB3 deployment can be built using this class, and it is the only Java code
needed to deploy on JBossWS. The WSDL, and all other Java artifacts called "wrapper
classes" will be generated for you at deploy time. This actually goes beyond the
JAX-WS specification, which requires that wrapper classes be generated using an offline
tool. The reason for this requirement is purely a vender implementation problem, and since
we do not believe in burdening a developer with a bunch of additional steps, we generate
these as well. However, if you want your deployment to be portable to other application
servers, you will unfortunately need to use a tool and add the generated classes to your
deployment.
+</para>
+<para>
+This is the primary purpose of the wsprovide tool, to generate portable JAX-WS artifacts.
Additionally, it can be used to "provide" the abstract contract (WSDL file) for
your service. This can be obtained by invoking wsprovide using the "-w" option:
+</para>
+<para>
+<programlisting>
+$ javac -d . -classpath jboss-jaxws.jar Echo.java
+$ wsprovide -w echo.Echo
+Generating WSDL:
+EchoService.wsdl
+Writing Classes:
+echo/jaxws/Echo.class
+echo/jaxws/EchoResponse.class
+</programlisting>
+</para>
+<para>
+Inspecting the WSDL reveals a service called
EchoService:<programlisting><service
name='EchoService'><port binding='tns:EchoBinding'
name='EchoPort'><soap:address
location='REPLACE_WITH_ACTUAL_URL'/></port></service></programlisting>
+</para>
+<para>
+As expected, this service defines one operation,
"echo":<programlisting><portType
name='Echo'><operation name='echo'
parameterOrder='echo'><input
message='tns:Echo_echo'/><output
message='tns:Echo_echoResponse'/></operation></portType></programlisting>
+</para>
+<para>
+Remember that <emphasis role="bold">when deploying on JBossWS you do not
need to run this tool.</emphasis> You only need it for generating portable artifacts
and/or the abstract contract for your service.
+</para>
+<para>
+Let's create a POJO endpoint for deployment on JBoss AS. A simple web.xml needs to be
created:<programlisting><web-app
xmlns="http://java.sun.com/xml/ns/j2ee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
+
version="2.4"><servlet><servlet-name>Echo</servlet-name><servlet-class>echo.Echo</servlet-class></servlet><servlet-mapping><servlet-name>Echo</servlet-name><url-pattern>/Echo</url-pattern></servlet-mapping></web-app></programlisting>
+</para>
+<para>
+The web.xml and the single class can now be used to create a war:<programlisting>
+$ mkdir -p WEB-INF/classes
+$ cp -rp echo WEB-INF/classes/
+$ cp web.xml WEB-INF
+$ jar cvf echo.war WEB-INF
+added manifest
+adding: WEB-INF/(in = 0) (out= 0)(stored 0%)
+adding: WEB-INF/classes/(in = 0) (out= 0)(stored 0%)
+adding: WEB-INF/classes/echo/(in = 0) (out= 0)(stored 0%)
+adding: WEB-INF/classes/echo/Echo.class(in = 340) (out= 247)(deflated 27%)
+adding: WEB-INF/web.xml(in = 576) (out= 271)(deflated 52%)
+</programlisting>
+</para>
+<para>
+The war can then be deployed:<programlisting>
+cp echo.war /usr/local/jboss-4.2.0.GA-ejb3/server/default/deploy
+</programlisting>
+</para>
+<para>
+This will internally invoke wsprovide, which will generate the WSDL. If deployment was
successful, and you are using the default settings, it should be available here:
http://localhost:8080/echo/Echo?wsdl
+</para>
+<para>
+For a portable JAX-WS deployment, the wrapper classes generated earlier could be added to
the deployment.
+</para>
+
+</section>
+<section><title>Top-Down (Using wsconsume)</title>
+<para>
+The top-down development strategy begins with the abstract contract for the service,
which includes the WSDL file and zero or more schema files. The wsconsume tool is then
used to consume this contract, and produce annotated Java classes (and optionally sources)
that define it.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+wsconsume seems to have a problem with symlinks on unix systems
+</para>
+<para>
+Using the WSDL file from the bottom-up example, a new Java implementation that adheres to
this service can be generated. The "-k" option is passed to wsconsume to
preserve the Java source files that are generated, instead of providing just classes:
+</para>
+<para>
+<programlisting>
+$ wsconsume -k EchoService.wsdl
+echo/Echo.java
+echo/EchoResponse.java
+echo/EchoService.java
+echo/Echo_Type.java
+echo/ObjectFactory.java
+echo/package-info.java
+echo/Echo.java
+echo/EchoResponse.java
+echo/EchoService.java
+echo/Echo_Type.java
+echo/ObjectFactory.java
+echo/package-info.java
+</programlisting>
+</para>
+<para>
+The following table shows the purpose of each generated file:<table>
+<title/><tgroup cols="2"><tbody><row>
+<entry>
+File
+</entry>
+<entry>
+Purpose
+</entry>
+
+</row>
+<row>
+<entry>
+Echo.java
+</entry>
+<entry>
+Service Endpoint Interface
+</entry>
+
+</row>
+<row>
+<entry>
+Echo_Type.java
+</entry>
+<entry>
+Wrapper bean for request message
+</entry>
+
+</row>
+<row>
+<entry>
+EchoResponse.java
+</entry>
+<entry>
+Wrapper bean for response message
+</entry>
+
+</row>
+<row>
+<entry>
+ObjectFactory.java
+</entry>
+<entry>
+JAXB XML Registry
+</entry>
+
+</row>
+<row>
+<entry>
+package-info.java
+</entry>
+<entry>
+Holder for JAXB package annotations
+</entry>
+
+</row>
+<row>
+<entry>
+EchoService.java
+</entry>
+<entry>
+Used only by JAX-WS clients
+</entry>
+
+</row>
+</tbody></tgroup>
+</table>
+
+</para>
+<para>
+Examining the Service Endpoint Interface reveals annotations that are more explicit than
in the class written by hand in the bottom-up example, however, these evaluate to the same
contract:<programlisting>
+@WebService(name = "Echo", targetNamespace = "http://echo/")
+public interface Echo {
+ @WebMethod
+ @WebResult(targetNamespace = "")
+ @RequestWrapper(localName = "echo", targetNamespace =
"http://echo/", className = "echo.Echo_Type")
+ @ResponseWrapper(localName = "echoResponse", targetNamespace =
"http://echo/", className = "echo.EchoResponse")
+ public String echo(
+ @WebParam(name = "arg0", targetNamespace = "")
+ String arg0);
+
+}
+</programlisting>
+</para>
+<para>
+The only missing piece (besides the packaging) is the implementation class, which can now
be written, using the above interface.<programlisting>
+package echo;
+
+(a)javax.jws.WebService(endpointInterface="echo.Echo")
+public class EchoImpl implements Echo
+{
+ public String echo(String arg0)
+ {
+ return arg0;
+ }
+}
+</programlisting>
+</para>
+
+</section>
+<section><title>Client Side</title>
+<para>
+Before going to detail on the client-side it is important to understand the decoupling
concept that is central to Web Services. Web Services are not the best fit for internal
RPC, even though they can be used in this way. There are much better technologies for this
(CORBA, and RMI for example). Web Services were designed specifically for interoperable
coarse-grained correspondence. There is no expectation or guarantee that any party
participating in a Web Service interaction will be at any particular location, running on
any particular OS, or written in any particular programming language. So because of this,
it is important to clearly separate client and server implementations. The only thing they
should have in common is the abstract contract definition. If, for whatever reason, your
software does not adhere to this principal, then you should not be using Web Services. For
the above reasons, the <emphasis role="bold"><emphasis>recommended
methodology for developing a clie!
nt is</emphasis></emphasis> to follow <emphasis
role="bold"><emphasis>the top-down
approach</emphasis></emphasis>, even if the client is running on the same
server.
+</para>
+<para>
+Let's repeat the process of the top-down section, although using the deployed WSDL,
instead of the one generated offline by wsprovide. The reason why we do this is just to
get the right value for soap:address. This value must be computed at deploy time, since it
is based on container configuration specifics. You could of course edit the WSDL file
yourself, although you need to ensure that the path is correct.
+</para>
+<para>
+Offline version:<programlisting><service
name='EchoService'><port binding='tns:EchoBinding'
name='EchoPort'><soap:address
location='REPLACE_WITH_ACTUAL_URL'/></port></service></programlisting>
+</para>
+<para>
+Online version:<programlisting><service
name="EchoService"><port binding="tns:EchoBinding"
name="EchoPort"><soap:address
location="http://localhost.localdomain:8080/echo/Echo"/></port></service></programlisting>
+</para>
+<para>
+Using the online deployed version with wsconsume:<programlisting>
+$ wsconsume -k http://localhost:8080/echo/Echo?wsdl
+echo/Echo.java
+echo/EchoResponse.java
+echo/EchoService.java
+echo/Echo_Type.java
+echo/ObjectFactory.java
+echo/package-info.java
+echo/Echo.java
+echo/EchoResponse.java
+echo/EchoService.java
+echo/Echo_Type.java
+echo/ObjectFactory.java
+echo/package-info.java
+</programlisting>
+</para>
+<para>
+The one class that was not examined in the top-down section, was EchoService.java. Notice
how it stores the location the WSDL was obtained from. <programlisting>
+@WebServiceClient(name = "EchoService", targetNamespace =
"http://echo/", wsdlLocation =
"http://localhost:8080/echo/Echo?wsdl")
+public class EchoService extends Service
+{
+ private final static URL ECHOSERVICE_WSDL_LOCATION;
+
+ static {
+ URL url = null;
+ try {
+ url = new URL("http://localhost:8080/echo/Echo?wsdl");
+ } catch (MalformedURLException e) {
+ e.printStackTrace();
+ }
+ ECHOSERVICE_WSDL_LOCATION = url;
+ }
+
+ public EchoService(URL wsdlLocation, QName serviceName) {
+ super(wsdlLocation, serviceName);
+ }
+
+ public EchoService() {
+ super(ECHOSERVICE_WSDL_LOCATION, new QName("http://echo/",
"EchoService"));
+ }
+
+ @WebEndpoint(name = "EchoPort")
+ public Echo getEchoPort() {
+ return (Echo)super.getPort(new QName("http://echo/", "EchoPort"),
Echo.class);
+ }
+}
+</programlisting>
+</para>
+<para>
+As you can see, this generated class extends the main client entry point in JAX-WS,
javax.xml.ws.Service. While you can use Service directly, this is far simpler since it
provides the configuration info for you. The only method we really care about is the
getEchoPort() method, which returns an instance of our Service Endpoint Interface. Any WS
operation can then be called by just invoking a method on the returned interface.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+It's not recommended to refer to a remote WSDL URL in a production application. This
causes network I/O every time you instantiate the Service Object. Instead, use the tool on
a saved local copy, or use the URL version of the constructor to provide a new WSDL
location.
+</para>
+<para>
+All that is left to do, is write and compile the client:<programlisting>
+import echo.*;
+
+public class EchoClient
+{
+ public static void main(String args[])
+ {
+ if (args.length != 1)
+ {
+ System.err.println("usage: EchoClient <message>");
+ System.exit(1);
+ }
+
+ EchoService service = new EchoService();
+ Echo echo = service.getEchoPort();
+ System.out.println("Server said: " + echo.echo(args[0]));
+ }
+}
+</programlisting>
+</para>
+<para>
+It can then be easily executed using the wsrunclient tool. This is just a convenience
tool that invokes java with the needed classpath:<programlisting>
+$ wsrunclient EchoClient 'Hello World!'
+Server said: Hello World!
+</programlisting>
+</para>
+
+</section>
+<section><title>Command-line & Ant Task Reference</title>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+wsconsume reference page
+</para>
+</listitem>
+<listitem>
+<para>
+wsprovide reference page
+</para>
+</listitem>
+<listitem>
+<para>
+wsrunclient reference page
+</para>
+</listitem>
+</itemizedlist>
+
+</section>
+
+</section>
+<section><title>Web Service Extensions</title>
+<section><title>WS-Addressing</title>
+<para>
+This section describes how <ulink
url="http://www.w3.org/TR/ws-addr-core"><citetitle>WS-...
can be used to provide a staful service endpoint.
+</para>
+<section><title>Specifications</title>
+<para>
+WS-Addressing is defined by a combination of the following specifications from the W3C
Candidate Recommendation 17 August 2005. The WS-Addressing API is standardized by
<ulink
url="http://www.jcp.org/en/jsr/detail?id=261"><citetitle&... - Java
API for XML Web Services Addressing</citetitle></ulink>
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+<ulink url="http://www.w3.org/TR/ws-addr-core"><citetitle>Web
Services Addressing 1.0 - Core</citetitle></ulink>
+</para>
+</listitem>
+<listitem>
+<para>
+<ulink url="http://www.w3.org/TR/ws-addr-soap"><citetitle>Web
Services Addressing 1.0 - SOAP Binding</citetitle></ulink>
+</para>
+</listitem>
+</itemizedlist>
+
+</section>
+<section><title>Addressing Endpoint</title>
+<para>
+The following endpoint implementation has a set of operation for a typical stateful
shopping chart application.
+</para>
+<para>
+<programlisting>
+ @WebService(name = "StatefulEndpoint", targetNamespace =
"http://org.jboss.ws/samples/wsaddressing", serviceName =
"TestService")
+ @EndpointConfig(configName = "Standard WSAddressing Endpoint")
+ @HandlerChain(file = "WEB-INF/jaxws-handlers.xml")
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ public class StatefulEndpointImpl implements StatefulEndpoint, ServiceLifecycle
+ {
+ @WebMethod
+ public void addItem(String item)
+ { ... }
+
+ @WebMethod
+ public void checkout()
+ { ... }
+
+ @WebMethod
+ public String getItems()
+ { ... }
+ }
+</programlisting>
+</para>
+<para>
+It uses the JAX-WS Endpoint Configuration# Standard WSAddressing Endpoint to enable the
server side addressing handler. It processes the incomming WS-Addressing header elements
and provides access to them through the JSR-261 API.
+</para>
+<para>
+The endpoint handler chain
+</para>
+<para>
+<programlisting><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
javaee_web_services_1_2.xsd"><handler-chain><protocol-bindings>##SOAP11_HTTP</protocol-bindings><handler><handler-name>Application
Server
Handler</handler-name><handler-class>org.jboss.test.ws.jaxws.samples.wsaddressing.ServerHandler</handler-class></handler></handler-chain></handler-chains></programlisting>
+</para>
+<para>
+defines an application specific hander that assignes/processes stateful client ids.
+</para>
+
+</section>
+<section><title>Addressing Client</title>
+<para>
+On the client side there are simmilar handlers that does the reverse. It uses the JSR-261
API to add WS-Addressing header elements including the clientid
association.<programlisting> </programlisting>
+</para>
+<para>
+The client sets a custom handler chain in the binding<programlisting>
</programlisting>
+</para>
+<para>
+<programlisting>
+ Service service = Service.create(wsdlURL, serviceName);
+ port1 = (StatefulEndpoint)service.getPort(StatefulEndpoint.class);
+ BindingProvider bindingProvider = (BindingProvider)port1;
+
+ List<Handler> customHandlerChain = new
ArrayList<Handler>();
+ customHandlerChain.add(new ClientHandler());
+ customHandlerChain.add(new WSAddressingClientHandler());
+ bindingProvider.getBinding().setHandlerChain(customHandlerChain);
+</programlisting><programlisting> </programlisting>
+</para>
+<para>
+The WSAddressingClientHandler is provided by JBossWS and reads/writes the addressing
properties and puts then into the message context.
+</para>
+<para>
+<emphasis role="bold">A client connecting to the stateful
endpoint</emphasis>
+</para>
+<para>
+<programlisting>
+ public class AddressingStatefulTestCase extends JBossWSTest
+ {
+ public void testAddItem() throws Exception
+ {
+ port1.addItem("Ice Cream");
+ port1.addItem("Ferrari");
+
+ port2.addItem("Mars Bar");
+ port2.addItem("Porsche");
+ }
+
+ public void testGetItems() throws Exception
+ {
+ String items1 = port1.getItems();
+ assertEquals("[Ice Cream, Ferrari]", items1);
+
+ String items2 = port2.getItems();
+ assertEquals("[Mars Bar, Porsche]", items2);
+ }
+ }
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">SOAP message exchange</emphasis>
+</para>
+<para>
+Below you see the SOAP messages that are beeing exchanged.
+</para>
+<para>
+<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'&...
xmlns:ns1='http://somens'>clientid-1</ns1:clientid></wsa:ReferenceParameters></env:Header><env:Body><ns1:addItem
xmlns:ns1='http://org.jboss.ws/samples/wsaddr'><String_1>Ice
Cream</String_1></ns1:addItem></env:Body></env:Envelope><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'&...!
ntid
xmlns:ns1='http://somens'>clientid-1</ns1:clientid></env:Header><env:Body><ns1:addItemResponse
xmlns:ns1='http://org.jboss.ws/samples/wsaddr'/></env:Body></env:Envelope>
+
+ ...
+
+<env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'&...
xmlns:ns1='http://somens'>clientid-1</ns1:clientid></wsa:ReferenceParameters></env:Header><env:Body><ns1:getItems
xmlns:ns1='http://org.jboss.ws/samples/wsaddr'/></env:Body></env:Envelope><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'&...
xmlns:ns1='http://somens'>clientid-1</ns1:clientid></env:He!
ader><env:Body><ns1:getItemsResponse
xmlns:ns1='http://org.jboss.ws/samples/wsaddr'><result>[Ice
Cream,
Ferrari]</result></ns1:getItemsResponse></env:Body></env:Envelope></programlisting>
+</para>
+
+</section>
+
+</section>
+<section><title>WS-BPEL</title>
+<para>
+WS-BPEL is not supported with JAX-WS, please refer to JAX-RPC User Guide#WS-BPEL.
+</para>
+
+</section>
+<section><title>WS-Eventing</title>
+<para>
+WS-Eventing specifies a set of operations that allow an event consumer to register
(subscribe) with an event producer (source) to receive events (notifications) in an
asynchronous fashion.
+</para>
+<section><title>Specifications</title>
+<para>
+WS-Eventing is defined by the combination of the following specifications:
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+<ulink
url="ftp://www6.software.ibm.com/software/developer/library/ws-event...
specification</citetitle></ulink>
+</para>
+</listitem>
+<listitem>
+<para>
+<ulink
url="http://www.w3.org/TR/ws-addr-core"><citetitle>WS-...
Specifications</citetitle></ulink>
+</para>
+</listitem>
+</itemizedlist>
+<para>
+The following section will introduce the main eventing actors and their responsiblities.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+The original eventing specification builds upon WS-Addressing 2004/08. JBossWS however
decided to stick to the latest version, which is the W3C candidate release.
+</para>
+
+</section>
+<section><title>Collaboration</title>
+<para>
+<mediaobject>
+<imageobject>
+<imagedata fileref="http:///images/8/8a/EventingCollaboration.gif"/>
+</imageobject>
+<textobject>
+<phrase>Eventing collaboration</phrase>
+</textobject>
+</mediaobject>
+
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+An event sink (web service client) sends a subscribtion request to the event source
endpoint. This includes the event sink endpoint address where notifications should
delivered. Upon successful subscription the sink receives a leased subscription ID that
can be used to identify the client in subsequent requests.
+</para>
+</listitem>
+<listitem>
+<para>
+A successfully registered event sink directs management requests (Renew, GetStatus,
Unsubscribe) to the subscription manager endpoint using the previously received
subscription ID. The subscription manager endpoint address was returned as part of the
subscription response in the first place.
+</para>
+</listitem>
+<listitem>
+<para>
+The actual event sink (application) emits notification messages through the
JBossWS-Eventing module. JBossWS-Eventing dispatches the notification to any subscriber
endpoint that is registered with a particular event source.s
+</para>
+</listitem>
+<listitem>
+<para>
+Besides notifications JBossWS-Eventing may emit lifecycle events at any time, i.e. to
inform an event sink that a subscription was canceled. This can be the case when the
subscription expired or the event source was undeployed.
+</para>
+</listitem>
+</orderedlist>
+<para>
+It is the users responsibilty to supply the web service endpoints (EventSourceEndpoint,
SubscriptionManagerEndpoint) that are required for a complete event source deployment.
Fortunatly JBossWS-Eventing already ships with a implementation that can be used right
away. All that's left todo is packaging of standard JSR-109 deployment archive that
includes the event source specific WSDL and points to the JBossWS-Eventing endpoint
implementations.
+</para>
+<para>
+The relevant steps are:
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+Create a custom WSDL that describes your event source, in respect to the notification
schema (1) and the fact that is actually contains an event source port (2)
+</para>
+</listitem>
+<listitem>
+<para>
+Use the JBossWS SEI (3) and endpoint (4) implementations (webservices.xml, web.xml).
+</para>
+</listitem>
+</itemizedlist>
+
+</section>
+<section><title>Setup an event source endpoint</title>
+<para>
+With JAX-WS the event source setup has actually become quiet easy. All you need to do is
to subclass your endpoint implementation from
<literal>AbstractEventSourceEndpoint</literal> and a subscription manager from
<literal>AbstractSubscriptionManagerEndpoint</literal> and finally point that
implementation to a event source specific WSDL.
+</para>
+<para>
+<programlisting>
+package org.jboss.test.ws.jaxws.samples.wseventing;
+
+import javax.jws.WebService;
+
+import org.jboss.logging.Logger;
+import org.jboss.ws.annotation.EndpointConfig;
+import org.jboss.ws.extensions.eventing.jaxws.AbstractEventSourceEndpoint;
+
+/**
+ * @author Heiko.Braun(a)jboss.org
+ * @version $Id$
+ * @since 18.01.2007
+ */
+@WebService( (1)
+ name = "EventSource",
+ portName = "EventSourcePort",
+ targetNamespace = "http://schemas.xmlsoap.org/ws/2004/08/eventing",
+ wsdlLocation = "/WEB-INF/wsdl/sysmon.wsdl", (2)
+ endpointInterface =
"org.jboss.ws.extensions.eventing.jaxws.EventSourceEndpoint")
+@EndpointConfig(configName = "Standard WSAddressing Endpoint") (3)
+public class SysmonRegistrationEndpoint extends AbstractEventSourceEndpoint { (4)
+
+ private static final Logger log = Logger.getLogger(SysmonRegistrationEndpoint.class);
+
+ protected Logger getLogger()
+ {
+ return log;
+ }
+}
+
+</programlisting>
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+Of course we need a <literal>@WebService</literal> annotation
+</para>
+</listitem>
+<listitem>
+<para>
+It's important to override the WSDL here
+</para>
+</listitem>
+<listitem>
+<para>
+You need to tell JBossWS that it requires WS-Addressing for this endpoint
+</para>
+</listitem>
+<listitem>
+<para>
+Subclass a predefined implementation that knows how to delegate to the actual eventing
service implementation
+</para>
+</listitem>
+</orderedlist>
+
+</section>
+<section><title>The WSDL that describes an event source</title>
+<para>
+Even though we are already using the annotation driven approach, JBossWS eventing still
requires an event source specific WSDL.
+</para>
+<para>
+The following excerpt shows the relevant WSDL details that describe an event source.
+</para>
+<para>
+<programlisting><?xml version="1.0"
encoding="UTF-8"?><wsdl:definitions
+ targetNamespace="http://www.jboss.org/sysmon"
+ xmlns:tns="http://www.jboss.org/sysmon"
+ xmlns:wse='http://schemas.xmlsoap.org/ws/2004/08/eventing'
+ xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/'
+ xmlns:wsa10='http://www.w3.org/2005/08/addressing'
+ xmlns:xs='http://www.w3.org/2001/XMLSchema'
+ xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">&...
+(1) namespace='http://schemas.xmlsoap.org/ws/2004/08/eventing'
+ location='jbwse.wsdl' /><wsdl:types><xs:schema
targetNamespace='http://schemas.xmlsoap.org/ws/2004/08/eventing'&...
+(2) <xs:include
schemaLocation='jbwse.xsd'/></xs:schema>
+
+(3) <xs:schema
+ targetNamespace="http://www.jboss.org/sysmon"
+ elementFormDefault="qualified"
+ blockDefault="#all"><xs:element
name="SystemStatus"><xs:complexType><xs:sequence><xs:element
name="Time " type="xs:dateTime"/><xs:element
name="HostName" type="xs:string"/><xs:element
name="HostAddress" type="xs:string"/><xs:element
name="ActiveThreadCount" type="xs:int"/><xs:element
name="FreeMemory" type="xs:string"/><xs:element
name="MaxMemory"
type="xs:string"/></xs:sequence></xs:complexType></xs:element></xs:schema></wsdl:types><wsdl:message
name='SystemInfoMsg'><wsdl:part name='body'
element='tns:SystemStatus'/></wsdl:message>
+
+(4) <wsdl:portType name='SystemInfo'
wse:EventSource='true'><wsdl:operation
name='SysmonOp'><wsdl:output
message='tns:SystemInfoMsg'/></wsdl:operation></wsdl:portType><wsdl:binding
name="SystemInfoBinding"
type="tns:SystemInfo"><soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>&l...
name="SysmonOp"><soap:operation
soapAction=""/><wsdl:output><soap:body
use="literal"/></wsdl:output></wsdl:operation></wsdl:binding></wsdl:definitions></programlisting>
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+Import the default eventing WSDL, that includes service and port declarations.
+</para>
+</listitem>
+<listitem>
+<para>
+Include the default eventing Types
+</para>
+</listitem>
+<listitem>
+<para>
+Specifiy the notitification message schema.
+</para>
+</listitem>
+<listitem>
+<para>
+Declare a port type, attributed "wse:EventSource='true'" that points to
your notification message schema.
+</para>
+</listitem>
+</orderedlist>
+
+</section>
+<section><title>Emitting notifications</title>
+<para>
+JBossWS-Eventing registeres a event dispatcher within local JNDI tree that can be used to
emit notifications from applications. <programlisting>
+ java:/EventDispatcher
+</programlisting>
+</para>
+<para>
+The event dispatcher interface: <programlisting>
+ public interface EventDispatcher
+ {
+ void dispatch(URI eventSourceNS, Element payload);
+ }
+</programlisting>
+</para>
+<para>
+<emphasis role="bold"> Example notification </emphasis>
+</para>
+<para>
+<programlisting>
+
+(1) URI eventSourceURI = new
URI("http://http://www.jboss.org/sysmon/SystemInfo");
+(2) Element payload = DOMUtils.parse("SOME XML STRING");
+ try
+ {
+ InitialContext iniCtx = getInitialContext();
+(3) EventDispatcher delegate = (EventDispatcher)
+ iniCtx.lookup(EventingConstants.DISPATCHER_JNDI_NAME);
+(4) delegate.dispatch(eventSourceURI, payload);
+ }
+ catch (Exception e)
+ {
+ //
+ }
+
+</programlisting>
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+Address your event source correctly (TargetNamespace+PortTypeName)
+</para>
+</listitem>
+<listitem>
+<para>
+Create your payload
+</para>
+</listitem>
+<listitem>
+<para>
+Lookup dispatcher from JNDI
+</para>
+</listitem>
+<listitem>
+<para>
+Dispatch notification.
+</para>
+</listitem>
+</orderedlist>
+<para>
+The SubscriptionManager MBean is the actual core component that drives the
JBossWS-Eventing implementation. It can be accessed through the jmx-console.
<programlisting>
+ jboss.ws.eventing:service=SubscriptionManager
+</programlisting>
+</para>
+<para>
+Management operations exist to monitor and maintain active subscritions and deployed
event sources. The current implementation is backed by a ThreadPoolExecutor, that
asynchronously delivers messages to event sink endpoints. It can be configured through the
following attributes:
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+corePoolSize - average number of idle threads
+</para>
+</listitem>
+<listitem>
+<para>
+maximumPoolSize - maximum number of threads
+</para>
+</listitem>
+<listitem>
+<para>
+eventKeepAlive - keep alive before an undelivered event message is discarded.
+</para>
+</listitem>
+</itemizedlist>
+
+</section>
+
+</section>
+<section><title>WS-Security</title>
+<para>
+WS-Security addresses message level security. It standardizes authorization, encryption,
and digital signature processing of web services. Unlike transport security models, such
as SSL, WS-Security applies security directly to the elements of the web service message.
This increases the flexibility of your web services, by allowing any message model to be
used (point to point, multi-hop relay, etc).
+</para>
+<para>
+This chapter describes how to use WS-Security to sign and encrypt a simple SOAP message.
+</para>
+<para>
+<emphasis role="bold">Specifications</emphasis>
+</para>
+<para>
+WS-Security is defined by the combination of the following specifications:
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+<ulink
url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-me...
Message Security 1.0</citetitle></ulink>
+</para>
+</listitem>
+<listitem>
+<para>
+<ulink
url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-usernam...
Token Profile 1.0</citetitle></ulink>
+</para>
+</listitem>
+<listitem>
+<para>
+<ulink
url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-to...
Token Profile 1.0</citetitle></ulink>
+</para>
+</listitem>
+<listitem>
+<para>
+<ulink url="http://www.w3.org/TR/xmlenc-core"><citetitle>W3C XML
Encryption</citetitle></ulink>
+</para>
+</listitem>
+<listitem>
+<para>
+<ulink url="http://www.w3.org/TR/xmldsig-core"><citetitle>W3C XML
Signature</citetitle></ulink>
+</para>
+</listitem>
+<listitem>
+<para>
+<ulink
url="http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0.html"...
Security Profile 1.0 (Still in Draft)</citetitle></ulink>
+</para>
+</listitem>
+</itemizedlist>
+<para>
+<emphasis role="bold">Configuration and setup</emphasis>
+</para>
+<para>
+JBossWS uses handlers to identify ws-security encoded requests and invoke the security
components to sign and encrypt messages. In order to enable security processing, the
client and server side need to include a corressponding handler configuration. The
preferred way is to reference a predefined JAX-WS Endpoint Configuration or JAX-WS Client
Configuration respectively.
+</para>
+<section><title>Server side configuration
(jboss-wsse-server.xml)</title>
+<para>
+In this example we configure both the client and the server to sign the message body.
Both also require this from each other. So, if you remove either the client or the server
security deployment descriptor, you will notice that the other party will throw a fault
explaining that the message did not conform to the proper security requirements.
+</para>
+<para>
+<programlisting><jboss-ws-security
xmlns="http://www.jboss.com/ws-security/config"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.jboss.com/ws-security/config
+ http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd"&a...
+ (1) <key-store-file>WEB-INF/wsse.keystore</key-store-file>
+ (2) <key-store-password>jbossws</key-store-password>
+ (3)
<trust-store-file>WEB-INF/wsse.truststore</trust-store-file>
+ (4) <trust-store-password>jbossws</trust-store-password>
+ (5) <config>
+ (6) <sign type="x509v3" alias="wsse"/>
+ (7) <requires>
+ (8)
<signature/></requires></config></jboss-ws-security></programlisting>
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+This specifies that the key store we wish to use is WEB-INF/wsse.keystore, which is
located in our war file.
+</para>
+</listitem>
+<listitem>
+<para>
+This specifies that the store password is "jbossws". Password can be encypted
using the {EXT} and {CLASS} commands. Please see samples for their usage.
+</para>
+</listitem>
+<listitem>
+<para>
+This specifies that the trust store we wish to use is WEB-INF/wsse.truststore, which is
located in our war file.
+</para>
+</listitem>
+<listitem>
+<para>
+This specifies that the trust store password is also "jbossws". Password can be
encypted using the {EXT} and {CLASS} commands. Please see samples for their usage.
+</para>
+</listitem>
+<listitem>
+<para>
+Here we start our root config block. The root config block is the default configuration
for all services in this war file.
+</para>
+</listitem>
+<listitem>
+<para>
+This means that the server must sign the message body of all responses. Type means that
we are to use a X.509v3 certificate (a standard certificate). The alias option says that
the certificate/key pair to use for signing is in the key store under the "wsse"
alias
+</para>
+</listitem>
+<listitem>
+<para>
+Here we start our optional requires block. This block specifies all security requirements
that must be met when the server receives a message.
+</para>
+</listitem>
+<listitem>
+<para>
+This means that all web services in this war file require the message body to be siged.
+</para>
+</listitem>
+</orderedlist>
+
+</section>
+<section><title>Client configuration (jboss-wsse-client.xml)</title>
+<para>
+<programlisting><jboss-ws-security
xmlns="http://www.jboss.com/ws-security/config"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.jboss.com/ws-security/config
+ http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd"&a...
+ (1) <config>
+ (2) <sign type="x509v3" alias="wsse"/>
+ (3) <requires>
+ (4)
<signature/></requires></config></jboss-ws-security></programlisting>
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+Here we start our root config block. The root config block is the default configuration
for all web service clients (Call, Proxy objects).
+</para>
+</listitem>
+<listitem>
+<para>
+This means that the client must sign the message body of all requests it sends. Type
means that we are to use a X.509v3 certificate (a standard certificate). The alias option
says that the certificate/key pair to use for signing is in the key store under the
"wsse" alias
+</para>
+</listitem>
+<listitem>
+<para>
+Here we start our optional requires block. This block specifies all security requirements
that must be met when the client receives a response.
+</para>
+</listitem>
+<listitem>
+<para>
+This means that all web service clients must receive signed response messages.
+</para>
+</listitem>
+</orderedlist>
+<para>
+We did not specify a key store or trust store, because client apps instead use the wsse
System properties instead. If this was a web or ejb client (meaning a webservice client in
a war or ejb jar file), then we would have specified them in the client descriptor.
+</para>
+<para>
+<emphasis role="bold">SOAP message exchange</emphasis>
+</para>
+<para>
+Below you see the incomming SOAP message with the details of the security headers
ommited. The idea is, that the SOAP body is still plain text, but it is signed in the
security header and can therefore not manipulated in transit.
+</para>
+<para>
+Incomming SOAPMessage<programlisting><env:Envelope
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">&a...
env:mustUnderstand="1" ...><wsu:Timestamp
wsu:Id="timestamp">...</wsu:Timestamp><wsse:BinarySecurityToken
...>
+ ...
+ </wsse:BinarySecurityToken><ds:Signature
xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
+ ...
+
</ds:Signature></wsse:Security></env:Header><env:Body
wsu:Id="element-1-1140197309843-12388840" ...><ns1:echoUserType
xmlns:ns1="http://org.jboss.ws/samples/wssecurity"><UserType_1
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">&a...
+</para>
+
+</section>
+<section><title>Installing the BouncyCastle JCE provider (JDK
1.4)</title>
+<para>
+The information below has originaly been provided by <ulink
url="http://www.bouncycastle.org/specifications.html#install"&g...
Legion of the Bouncy Castle</citetitle></ulink>.
+</para>
+<para>
+The provider can be configured as part of your environment via static registration by
adding an entry to the java.security properties file (found in
$JAVA_HOME/jre/lib/security/java.security, where $JAVA_HOME is the location of your
JDK/JRE distribution). You'll find detailed instructions in the file but basically it
comes down to adding a line:
+</para>
+<para>
+<programlisting>
+ security.provider.<n>=org.bouncycastle.jce.provider.BouncyCastleProvider
+</programlisting>
+</para>
+<para>
+Where <n> is the preference you want the provider at.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+Issues may arise if the Sun provided providers are not first.
+</para>
+<para>
+Where you put the jar is mostly up to you, although with jdk1.4 the best (and in some
cases only) place to have it is in $JAVA_HOME/jre/lib/ext. Under Windows there will
normally be a JRE and a JDK install of Java if you think you have installed it correctly
and it still doesn't work chances are you have added the provider to the installation
not being used.
+</para>
+
+</section>
+<section><title>Keystore, truststore - What?</title>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+If you having a hard time understanding how the different trust- and keystore
configurationsare used for signature and encryption, then read this thread
first:http://www.jboss.org/index.html?module
+</para>
+
+</section>
+
+</section>
+<section><title>WS-Transaction</title>
+<para>
+Support for the WS-Coordination, WS-AtomicTransaction and WS-BusinessActivity
specifications will be provided by technology recently acquired from Arjuna Technologies
Ltd. This technology will be present within the JBoss Transactions 4.2.1 release. Further
information can be obtained from the <ulink
url="http://labs.jboss.org/portal/jbosstm"><citetitle>...
Transactions Project</citetitle></ulink>
+</para>
+
+</section>
+<section><title>MTOM/XOP</title>
+<para>
+This chapter describes Message Transmission Optimization Mechanism (MTOM) and XML-binary
Optimized Packaging (XOP), a means of more efficiently serializing XML Infosets that have
certain types of content. The related specifications are
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+<ulink url="http://www.w3.org/TR/soap12-mtom/"><citetitle>SOAP
Message Transmission Optimization Mechanism (MTOM)</citetitle></ulink>
+</para>
+</listitem>
+<listitem>
+<para>
+<ulink url="http://www.w3.org/TR/xop10/"><citetitle>XML-binary
Optimized Packaging (XOP)</citetitle></ulink>
+</para>
+</listitem>
+</itemizedlist>
+<section><title>Supported MTOM parameter types</title>
+<table>
+<title/><tgroup cols="2"><tbody><row>
+<entry>
+image/jpeg
+</entry>
+<entry>
+java.awt.Image
+</entry>
+
+</row>
+<row>
+<entry>
+text/xml
+</entry>
+<entry>
+javax.xml.transform.Source
+</entry>
+
+</row>
+<row>
+<entry>
+application/xml
+</entry>
+<entry>
+javax.xml.transform.Source
+</entry>
+
+</row>
+<row>
+<entry>
+application/octet-stream
+</entry>
+<entry>
+javax.activation.DataHandler
+</entry>
+
+</row>
+</tbody></tgroup>
+</table>
+<para>
+<programlisting/>
+</para>
+<para>
+The above table shows a list of supported endpoint parameter types. The recommended
approach is to use the <ulink
url="http://java.sun.com/j2ee/1.4/docs/api/javax/activation/DataHand...
classes to represent binary data as service endpoint parameters.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+Microsoft endpoints tend to send any data as application/octet-stream. The only Java type
that can easily cope with this ambiguity is javax.activation.DataHandler
+</para>
+
+</section>
+<section><title>Enabling MTOM per endpoint</title>
+<para>
+On the server side MTOM processing is enabled through the
<literal>@BindingType</literal> annotation.JBossWS does handle SOAP1.1 and
SOAP1.2. Both come with or without MTOM flavours:
+</para>
+<para>
+<emphasis role="bold"> MTOM enabled service implementations
</emphasis>
+</para>
+<para>
+<programlisting>
+package org.jboss.test.ws.jaxws.samples.xop.doclit;
+
+import javax.ejb.Remote;
+import javax.jws.WebService;
+import javax.jws.soap.SOAPBinding;
+import javax.xml.ws.BindingType;
+
+@Remote
+@WebService(targetNamespace = "http://org.jboss.ws/xop/doclit")
+@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, parameterStyle =
SOAPBinding.ParameterStyle.BARE)
+@BindingType(value="http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true") (1)
+public interface MTOMEndpoint {
+
+ [...]
+}
+</programlisting>
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+The MTOM enabled SOAP 1.1 binding ID
+</para>
+</listitem>
+</orderedlist>
+<para>
+<emphasis role="bold"> MTOM enabled clients </emphasis>
+</para>
+<para>
+Web service clients can use the same approach described above or rely on the
<literal>Binding</literal> API to enable MTOM(Excerpt taken from the
<literal>org.jboss.test.ws.jaxws.samples.xop.doclit.XOPTestCase</literal>):
+</para>
+<para>
+<programlisting>
+[...]
+Service service = Service.create(wsdlURL, serviceName);
+port = service.getPort(MTOMEndpoint.class);
+
+// enable MTOM
+binding = (SOAPBinding)((BindingProvider)port).getBinding();
+binding.setMTOMEnabled(true);
+
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+You might as well use the JBossWS configuration templates to setup deployment defaults.
+</para>
+
+</section>
+
+</section>
+<section><title>XML Registries</title>
+<para>
+J2EE 1.4 mandates support for Java API for XML Registries (JAXR). Inclusion of a XML
Registry with the J2EE 1.4 certified Application Server is optional. Starting jboss-4.0.2,
JBoss ships a UDDI v2.0 compliant registry, the Apache jUDDI registry. We also provide
support for JAXR Capability Level 0 (UDDI Registries) via integration of Apache Scout.
+</para>
+<para>
+This chapter describes how to configure the jUDDI registry in JBoss and some sample code
outlines for using JAXR API to publish and query the jUDDI registry.
+</para>
+<section><title>Apache jUDDI Configuration</title>
+<para>
+Configuration of the jUDDI registry happens via an MBean Service that is deployed in the
juddi-service.sar archive in the "all" configuration. The configuration of this
service can be done in the jboss-service.xml of the META-INF directory in the
juddi-service.sar
+</para>
+<para>
+Let us look at the individual configuration items that can be changed.
+</para>
+<para>
+DataSources configuration
+</para>
+<para>
+<programlisting><attribute
name="DataSourceUrl">java:/DefaultDS</attribute></programlisting>
+</para>
+<para>
+Database Tables (Should they be created on start, Should they be dropped on stop, Should
they be dropped on start etc)
+</para>
+<para>
+<programlisting><attribute
name="CreateOnStart">false</attribute><attribute
name="DropOnStop">true</attribute><attribute
name="DropOnStart">false</attribute></programlisting>
+</para>
+<para>
+JAXR Connection Factory to be bound in JNDI. (Should it be bound? and under what name?)
+</para>
+<para>
+<programlisting><attribute
name="ShouldBindJaxr">true</attribute><attribute
name="BindJaxr">JAXR</attribute></programlisting>
+</para>
+<para>
+Other common configuration:
+</para>
+<para>
+Add authorized users to access the jUDDI registry. (Add a sql insert statement in a
single line)
+</para>
+<para>
+<programlisting>
+ Look at the script META-INF/ddl/juddi_data.ddl for more details. Example for a user
'jboss'
+
+ INSERT INTO PUBLISHER (PUBLISHER_ID,PUBLISHER_NAME,
+ EMAIL_ADDRESS,IS_ENABLED,IS_ADMIN)
+ VALUES ('jboss','JBoss
User','jboss@xxx','true','true');
+</programlisting>
+</para>
+
+</section>
+<section><title>JBoss JAXR Configuration</title>
+<para>
+In this section, we will discuss the configuration needed to run the JAXR API. The JAXR
configuration relies on System properties passed to the JVM. The System properties that
are needed are:
+</para>
+<para>
+<programlisting>
+
javax.xml.registry.ConnectionFactoryClass=org.apache.ws.scout.registry.ConnectionFactoryImpl
+ jaxr.query.url=http://localhost:8080/juddi/inquiry
+ jaxr.publish.url=http://localhost:8080/juddi/publish
+ juddi.proxy.transportClass=org.jboss.jaxr.juddi.transport.SaajTransport
+</programlisting>
+</para>
+<para>
+Please remember to change the hostname from "localhost" to the hostname of the
UDDI service/JBoss Server.
+</para>
+<para>
+You can pass the System Properties to the JVM in the following ways:
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+When the client code is running inside JBoss (maybe a servlet or an EJB). Then you will
need to pass the System properties in the run.sh/run.bat scripts to the java process via
the "-D" option.
+</para>
+</listitem>
+<listitem>
+<para>
+When the client code is running in an external JVM. Then you can pass the properties
either as "-D" options to the java process or explicitly set them in the client
code(not recommended).
+</para>
+</listitem>
+</itemizedlist>
+<para>
+<programlisting>
+ System.setProperty(propertyname, propertyvalue);
+</programlisting>
+</para>
+
+</section>
+<section><title>JAXR Sample Code</title>
+<para>
+There are two categories of API: JAXR Publish API and JAXR Inquiry API. The important
JAXR interfaces that any JAXR client code will use are the following.
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+<ulink
url="http://java.sun.com/j2ee/1.4/docs/api/javax/xml/registry/Regist...
From J2EE 1.4 JavaDoc: "This is the principal interface implemented by a JAXR
provider. A registry client can get this interface from a Connection to a registry. It
provides the methods that are used by the client to discover various capability specific
interfaces implemented by the JAXR provider."
+</para>
+</listitem>
+<listitem>
+<para>
+<ulink
url="http://java.sun.com/j2ee/1.4/docs/api/javax/xml/registry/Busine...
From J2EE 1.4 JavaDoc: "The BusinessLifeCycleManager interface, which is exposed by
the Registry Service, implements the life cycle management functionality of the Registry
as part of a business level API. Note that there is no authentication information
provided, because the Connection interface keeps that state and context on behalf of the
client."
+</para>
+</listitem>
+<listitem>
+<para>
+<ulink
url="http://java.sun.com/j2ee/1.4/docs/api/javax/xml/registry/Busine...
From J2EE 1.4 JavaDoc: "The BusinessQueryManager interface, which is exposed by the
Registry Service, implements the business style query interface. It is also referred to as
the focused query interface."
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Let us now look at some of the common programming tasks performed while using the JAXR
API:
+</para>
+<para>
+Getting a JAXR Connection to the registry.
+</para>
+<para>
+<programlisting>
+ String queryurl = System.getProperty("jaxr.query.url",
"http://localhost:8080/juddi/inquiry");
+ String puburl = System.getProperty("jaxr.publish.url",
"http://localhost:8080/juddi/publish");
+
+ Properties props = new Properties();
+ props.setProperty("javax.xml.registry.queryManagerURL", queryurl);
+ props.setProperty("javax.xml.registry.lifeCycleManagerURL", puburl);
+
+ String transportClass = System.getProperty("juddi.proxy.transportClass",
"org.jboss.jaxr.juddi.transport.SaajTransport");
+ System.setProperty("juddi.proxy.transportClass", transportClass);
+
+ // Create the connection, passing it the configuration properties
+ factory = ConnectionFactory.newInstance();
+ factory.setProperties(props);
+ connection = factory.createConnection();
+</programlisting>
+</para>
+<para>
+Authentication with the registry.
+</para>
+<para>
+<programlisting>
+ /**
+ * Does authentication with the uddi registry
+ */
+ protected void login() throws JAXRException
+ {
+ PasswordAuthentication passwdAuth = new PasswordAuthentication(userid,
passwd.toCharArray());
+ Set creds = new HashSet();
+ creds.add(passwdAuth);
+
+ connection.setCredentials(creds);
+ }
+</programlisting>
+</para>
+<para>
+Save a Business
+</para>
+<para>
+<programlisting>
+ /**
+ * Creates a Jaxr Organization with 1 or more services
+ */
+ protected Organization createOrganization(String orgname) throws JAXRException
+ {
+ Organization org = blm.createOrganization(getIString(orgname));
+ org.setDescription(getIString("JBoss Inc"));
+ Service service = blm.createService(getIString("JBOSS JAXR Service"));
+ service.setDescription(getIString("Services of XML Registry"));
+ //Create serviceBinding
+ ServiceBinding serviceBinding = blm.createServiceBinding();
+ serviceBinding.setDescription(blm.createInternationalString("Test Service
Binding"));
+
+ //Turn validation of URI off
+ serviceBinding.setValidateURI(false);
+ serviceBinding.setAccessURI("http://testjboss.org");
+
+ // Add the serviceBinding to the service
+ service.addServiceBinding(serviceBinding);
+
+ User user = blm.createUser();
+ org.setPrimaryContact(user);
+ PersonName personName = blm.createPersonName("Anil S");
+ TelephoneNumber telephoneNumber = blm.createTelephoneNumber();
+ telephoneNumber.setNumber("111-111-7777");
+ telephoneNumber.setType(null);
+ PostalAddress address = blm.createPostalAddress("111", "My Drive",
"BuckHead", "GA", "USA", "1111-111",
"");
+ Collection postalAddresses = new ArrayList();
+ postalAddresses.add(address);
+ Collection emailAddresses = new ArrayList();
+ EmailAddress emailAddress = blm.createEmailAddress("anil(a)apache.org");
+ emailAddresses.add(emailAddress);
+
+ Collection numbers = new ArrayList();
+ numbers.add(telephoneNumber);
+ user.setPersonName(personName);
+ user.setPostalAddresses(postalAddresses);
+ user.setEmailAddresses(emailAddresses);
+ user.setTelephoneNumbers(numbers);
+
+ ClassificationScheme cScheme = getClassificationScheme("ntis-gov:naics",
"");
+ Key cKey = blm.createKey("uuid:C0B9FE13-324F-413D-5A5B-2004DB8E5CC2");
+ cScheme.setKey(cKey);
+ Classification classification = blm.createClassification(cScheme, "Computer Systems
Design and Related Services", "5415");
+ org.addClassification(classification);
+ ClassificationScheme cScheme1 = getClassificationScheme("D-U-N-S",
"");
+ Key cKey1 = blm.createKey("uuid:3367C81E-FF1F-4D5A-B202-3EB13AD02423");
+ cScheme1.setKey(cKey1);
+ ExternalIdentifier ei = blm.createExternalIdentifier(cScheme1, "D-U-N-S
number", "08-146-6849");
+ org.addExternalIdentifier(ei);
+ org.addService(service);
+ return org;
+ }
+</programlisting>
+</para>
+<para>
+Query a Business
+</para>
+<para>
+<programlisting>
+ /**
+ * Locale aware Search a business in the registry
+ */
+ public void searchBusiness(String bizname) throws JAXRException
+ {
+ try
+ {
+ // Get registry service and business query manager
+ this.getJAXREssentials();
+
+ // Define find qualifiers and name patterns
+ Collection findQualifiers = new ArrayList();
+ findQualifiers.add(FindQualifier.SORT_BY_NAME_ASC);
+ Collection namePatterns = new ArrayList();
+ String pattern = "%" + bizname + "%";
+ LocalizedString ls = blm.createLocalizedString(Locale.getDefault(), pattern);
+ namePatterns.add(ls);
+
+ // Find based upon qualifier type and values
+ BulkResponse response = bqm.findOrganizations(findQualifiers, namePatterns, null, null,
null, null);
+
+ // check how many organisation we have matched
+ Collection orgs = response.getCollection();
+ if (orgs == null)
+ {
+ log.debug(" -- Matched 0 orgs");
+
+ }
+ else
+ {
+ log.debug(" -- Matched " + orgs.size() + " organizations -- ");
+
+ // then step through them
+ for (Iterator orgIter = orgs.iterator(); orgIter.hasNext();)
+ {
+ Organization org = (Organization)orgIter.next();
+ log.debug("Org name: " + getName(org));
+ log.debug("Org description: " + getDescription(org));
+ log.debug("Org key id: " + getKey(org));
+ checkUser(org);
+ checkServices(org);
+ }
+ }
+ }
+ finally
+ {
+ connection.close();
+ }
+ }
+</programlisting>
+</para>
+<para>
+For more examples of code using the JAXR API, please refer to the resources in the
Resources Section.
+</para>
+
+</section>
+<section><title>Trouble Shooting</title>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+I cannot connect to the registry from JAXR. Please check the inquiry and publish url
passed to the JAXR ConnectionFactory.
+</para>
+</listitem>
+<listitem>
+<para>
+I cannot connect to the jUDDI registry. Please check the jUDDI configuration and see if
there are any errors in the server.log. And also remember that the jUDDI registry is
available only in the "all" configuration.
+</para>
+</listitem>
+<listitem>
+<para>
+I cannot authenticate to the jUDDI registry. Have you added an authorized user to the
jUDDI database, as described earlier in the chapter?
+</para>
+</listitem>
+<listitem>
+<para>
+I would like to view the SOAP messages in transit between the client and the UDDI
Registry. Please use the tcpmon tool to view the messages in transit. <ulink
url="http://tcpmon.dev.java.net/"><citetitle>TCPMon<...
+</para>
+</listitem>
+</itemizedlist>
+
+</section>
+<section><title>Resources</title>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+<ulink
url="http://java.sun.com/webservices/jaxr/learning/tutorial/index.ht...
Tutorial and Code Camps</citetitle></ulink>
+</para>
+</listitem>
+<listitem>
+<para>
+<ulink
url="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/"><ci...
1.4 Tutorial</citetitle></ulink>
+</para>
+</listitem>
+<listitem>
+<para>
+<ulink
url="http://www.amazon.com/exec/obidos/ASIN/0321146182"><...
Web Services by Richard Monson-Haefel</citetitle></ulink>
+</para>
+</listitem>
+</itemizedlist>
+
+</section>
+
+</section>
+<section><title>WS-Policy</title>
+<para>
+Since 2.1
+</para>
+<para>
+The Web Services Policy Framework (WS-Policy) provides a general purpose model and
corresponding syntax to describe the policies of a Web Service.
+</para>
+<para>
+WS-Policy defines a base set of constructs that can be used and extended by other Web
services specifications to describe a broad range of service requirements and
capabilities.
+</para>
+<para>
+Current JBoss implementation can instrument a webservice with policies attached at
endpoint, port or port-type scope level only.There are two different methods to attach
policies: providing a wsdl decorated with policies and policy attachments as defined by
specifications, or using JBoss proprietary annotations. The first way has the advantage of
being standard, while the second one is much more simple to implement. Of course the wsdl
generated by these annotations conforms to standard defined in specifications and can be
used with any ws-policy compliant client.
+</para>
+<para>
+Please note that ws-policy specifications only define policy requirements and their
attachment method to wsdl through specific extensions. It is out of the scope of ws-policy
specifications and thus implementation to define and use the content of assertions. The
way these assertions (called domain assertions or domain policies) have to be deployed and
used is left to other specification like WS-Security-Policy or more generally to domain
specific implementation.
+</para>
+<section><title>Specification</title>
+<para>
+WS-Policy is defined by the combination of the following
specifications:<programlisting> * <ulink
url="http://www.w3.org/Submission/WS-Policy/"><citetitle&...
specification</citetitle></ulink></programlisting><programlisting>
* <ulink
url="http://www.w3.org/Submission/WS-PolicyAttachment/"><...
specification</citetitle></ulink></programlisting>
+</para>
+
+</section>
+<section><title>Using policies in a user provided wsdl</title>
+<para>
+To attach policies in this manner, the only thing you have to do in a webservice class is
to provide a custom wsdl. This will cause JBossws to skip wsdl generation at deploy time,
since the wsdl file you provided will be published. Please refer to specification
(WS-Policy-Attachment) to learn how to modify wsdl to attach a policy.
+</para>
+<para>
+Here you find an example of a webservice class and provided wsdl with a policy containing
a domain assertion for JBoss wssecurity.
+</para>
+<para>
+<programlisting>
+@WebService(name = "Hello",
+targetNamespace = "http://org.jboss.ws/samples/wssecuritypolicy",
+wsdlLocation="WEB-INF/wsdl/HelloService.wsdl")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+public class HelloJavaBean
+{
+ private Logger log = Logger.getLogger(HelloJavaBean.class);
+
+ @WebMethod
+ public UserType echoUserType(@WebParam(name = "user") UserType in0)
+ {
+ log.info(in0);
+ return in0;
+ }
+}
+</programlisting>
+</para>
+<para>
+<programlisting><?xml version="1.0"
encoding="UTF-8"?><definitions name='HelloService'
targetNamespace='http://org.jboss.ws/samples/wssecuritypolicy'
xmlns='http://schemas.xmlsoap.org/wsdl/'
xmlns:ns1='http://org.jboss.ws/samples/wssecurity'
xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'
xmlns:tns='http://org.jboss.ws/samples/wssecuritypolicy'
xmlns:wsp='http://schemas.xmlsoap.org/ws/2004/09/policy'
xmlns:xsd='http://www.w3.org/2001/XMLSchema'><types...
targetNamespace='http://org.jboss.ws/samples/wssecurity' version='1.0'
xmlns:xs='http://www.w3.org/2001/XMLSchema'><xs:com...
name='UserType'><xs:sequence><xs:element
minOccurs='0' name='msg'
type='xs:string'/></xs:sequence></xs:complexType></xs:schema></types><wsp:Policy
wsu:Id='X509EndpointPolicy'
xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-ws...
xmlns!
:sp='http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd'><sp:key-store-file>WEB-INF/wsse.keystore</sp:key-store-file><sp:key-store-password>jbossws</sp:key-store-password><sp:trust-store-file>WEB-INF/wsse.truststore</sp:trust-store-file><sp:trust-store-password>jbossws</sp:trust-store-password><sp:config><sp:encrypt
alias='wsse'
type='x509v3'/><sp:requires><sp:encryption/></sp:requires></sp:config></sp:jboss-ws-security></wsp:All></wsp:Policy><message
name='Hello_echoUserType'><part name='user'
type='ns1:UserType'/></message><message
name='Hello_echoUserTypeResponse'><part name='return'
type='ns1:UserType'/></message><portType
name='Hello'><operation name='echoUserType'
parameterOrder='user'><input
message='tns:Hello_echoUserType'/><output
message='tns:Hello_echoUserTypeResponse'/></operation&g!
t;</portType><binding name='HelloBinding'
type='tns:Hello'>
;<wsp:PolicyReference
URI='#X509EndpointPolicy'/><soap:binding style='rpc'
transport='http://schemas.xmlsoap.org/soap/http'/><...
name='echoUserType'><soap:operation
soapAction=''/><input><soap:body
namespace='http://org.jboss.ws/samples/wssecuritypolicy'
use='literal'/></input><output><soap:body
namespace='http://org.jboss.ws/samples/wssecuritypolicy'
use='literal'/></output></operation></binding><service
name='HelloService'><port binding='tns:HelloBinding'
name='HelloPort'><soap:address
location='REPLACE_WITH_ACTUAL_URL'/></port></service></definitions></programlisting>
+</para>
+<para>
+Please note in the wsdl file the wsp:Policy element and the wsp:PolicyReference in
'HelloBinding' binding Element.
+</para>
+
+</section>
+<section><title>Using policies with JBoss annotations</title>
+<para>
+Using JBoss proprietary annotation you only have to provide the policy xml, leaving wsdl
generation to the JBossWS deployer.
+</para>
+<para>
+There are two annotations to use, the first one (@PolicyAttachment) containing an array
of the second one (@Policy): this lets you have many policies attached to a class or
method.In future domain policy implementations might ship domain annotations extending the
@Policy annotation to provide needed metadata directly as annotation parameters. The
current @Policy annotation takes a reference to a xml file containing a generic policy
description written respecting ws-policy specification rules.
+</para>
+<para>
+<programlisting>
+/**
+
+(a)Target(ElementType.TYPE)
+(a)Retention(RetentionPolicy.RUNTIME)
+public @interface PolicyAttachment {
+ Policy[] value();
+}
+
+</programlisting>
+</para>
+<para>
+<programlisting>
+(a)Retention(RetentionPolicy.RUNTIME)
+public @interface Policy {
+
+ public String policyFileLocation();
+
+ public PolicyScopeLevel scope();
+}
+</programlisting>
+</para>
+<para>
+And here you have the previous section example re-implemented using annotations and xml
policy file:
+</para>
+<para>
+<programlisting>
+@WebService(name = "Hello", targetNamespace =
"http://org.jboss.ws/samples/wssecurityAnnotatedpolicy")
+@PolicyAttachment({@Policy( policyFileLocation="WEB-INF/Policy.xml", scope =
PolicyScopeLevel.WSDL_PORT ) })
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+public class HelloJavaBean
+{
+ private Logger log = Logger.getLogger(HelloJavaBean.class);
+
+ @WebMethod
+ public UserType echoUserType(@WebParam(name = "user") UserType in0)
+ {
+ log.info(in0);
+ return in0;
+ }
+}
+</programlisting>
+</para>
+<para>
+<programlisting><?xml version="1.0"
encoding="UTF-8"?><wsp:Policy
wsu:Id="X509EndpointPolicy"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
+
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-w...
xmlns:sp="http://www.jboss.com/ws-security/schema/jboss-ws-security_...
type="x509v3"
alias="wsse"/><sp:requires><sp:encryption/></sp:requires></sp:config></sp:jboss-ws-security></wsp:All></wsp:ExactlyOne></wsp:Policy></programlisting>
+</para>
+
+</section>
+
+</section>
+<section><title>SwaRef</title>
+<para>
+Since 2.0
+</para>
+<para>
+<ulink
url="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24....
Attachment Profile 1.0</citetitle></ulink> defines mechanism to reference MIME
attachment parts using <ulink
url="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24....;.
In this mechanism the content of XML element of type wsi:swaRef is sent as MIME attachment
and the element inside SOAP Body holds the reference to this attachment in the CID URI
scheme as defined by RFC 2111.
+</para>
+<section><title>Using SwaRef with JAX-WS endpoints</title>
+<para>
+JAX-WS endpoints delegate all marshalling/unmarshalling to the JAXB API. The most simple
way to enable SwaRef encoding for <literal>DataHandler</literal> types is to
annotate a payload bean with the <literal>@XmlAttachmentRef</literal>
annotation as shown below:
+</para>
+<para>
+<programlisting>
+/**
+* Payload bean that will use SwaRef encoding
+*/
+@XmlRootElement
+public class DocumentPayload
+{
+ private DataHandler data;
+
+ public DocumentPayload()
+ {
+ }
+
+ public DocumentPayload(DataHandler data)
+ {
+ this.data = data;
+ }
+
+ @XmlElement
+ @XmlAttachmentRef
+ public DataHandler getData()
+ {
+ return data;
+ }
+
+ public void setData(DataHandler data)
+ {
+ this.data = data;
+ }
+}
+</programlisting>
+</para>
+<para>
+With document wrapped endpoints you may even specify the
<literal>@XmlAttachmentRef</literal> annotation on the service endpoint
interface:
+</para>
+<para>
+<programlisting>
+@WebService
+public interface DocWrappedEndpoint
+{
+ @WebMethod
+ DocumentPayload beanAnnotation(DocumentPayload dhw, String test);
+
+ @WebMethod
+ @XmlAttachmentRef
+ DataHandler parameterAnnotation(@XmlAttachmentRef DataHandler data, String test);
+
+}
+</programlisting>
+</para>
+<para>
+The message would then refer to the attachment part by CID:
+</para>
+<para>
+<programlisting><env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns2='http://swaref.samples.jaxws.ws.test.jboss.org/'>...
test</arg1></ns2:parameterAnnotation></env:Body></env:Envelope></programlisting>
+</para>
+
+</section>
+<section><title>Starting from WSDL</title>
+<para>
+If you chose the contract first approach then you need to ensure that any element
declaration that should use SwaRef encoding simply refers to wsi:swaRef schema type:
+</para>
+<para>
+<programlisting><element name="data" type="wsi:swaRef"
+xmlns:wsi="http://ws-i.org/profiles/basic/1.1/xsd"/></programlisting>
+</para>
+<para>
+Any wsi:swaRef schema type would then be mapped to DataHandler.
+</para>
+
+</section>
+
+</section>
+
+</section>
+<section><title>JBossWS Extenstions</title>
+<para>
+This section describes propriatary JBoss extensions to JAX-WS.
+</para>
+<section><title>Proprietary Annotations</title>
+<para>
+For the set of standard annotations, please have a look at JAX-WS Annotations
+</para>
+<section><title>EndpointConfig</title>
+<para>
+<programlisting>
+/**
+ * Defines an endpoint or client configuration.
+ * This annotation is valid on an endpoint implementaion bean or a SEI.
+ *
+ * @author Heiko.Braun(a)jboss.org
+ * @since 16.01.2007
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = { ElementType.TYPE })
+public @interface EndpointConfig {
+
+ /**
+ * The optional config-name element gives the configuration name that must be present in
+ * the configuration given by element config-file.
+ *
+ * Server side default: Standard Endpoint
+ * Client side default: Standard Client
+ */
+ String configName() default "";
+
+ /**
+ * The optional config-file element is a URL or resource name for the configuration.
+ *
+ * Server side default: standard-jaxws-endpoint-config.xml
+ * Client side default: standard-jaxws-client-config.xml
+ */
+ String configFile() default "";
+}
+</programlisting>
+</para>
+
+</section>
+<section><title>WebContext</title>
+<para>
+<programlisting>
+/**
+ * Provides web context specific meta data to EJB based web service endpoints.
+ *
+ * @author thomas.diesler(a)jboss.org
+ * @since 26-Apr-2005
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = { ElementType.TYPE })
+public @interface WebContext {
+
+ /**
+ * The contextRoot element specifies the context root that the web service endpoint is
deployed to.
+ * If it is not specified it will be derived from the deployment short name.
+ *
+ * Applies to server side port components only.
+ */
+ String contextRoot() default "";
+
+ /**
+ * The virtual hosts that the web service endpoint is deployed to.
+ *
+ * Applies to server side port components only.
+ */
+ String[] virtualHosts() default {};
+
+ /**
+ * Relative path that is appended to the contextRoot to form fully qualified
+ * endpoint address for the web service endpoint.
+ *
+ * Applies to server side port components only.
+ */
+ String urlPattern() default "";
+
+ /**
+ * The authMethod is used to configure the authentication mechanism for the web service.
+ * As a prerequisite to gaining access to any web service which are protected by an
authorization
+ * constraint, a user must have authenticated using the configured mechanism.
+ *
+ * Legal values for this element are "BASIC", or "CLIENT-CERT".
+ */
+ String authMethod() default "";
+
+ /**
+ * The transportGuarantee specifies that the communication
+ * between client and server should be NONE, INTEGRAL, or
+ * CONFIDENTIAL. NONE means that the application does not require any
+ * transport guarantees. A value of INTEGRAL means that the application
+ * requires that the data sent between the client and server be sent in
+ * such a way that it can't be changed in transit. CONFIDENTIAL means
+ * that the application requires that the data be transmitted in a
+ * fashion that prevents other entities from observing the contents of
+ * the transmission. In most cases, the presence of the INTEGRAL or
+ * CONFIDENTIAL flag will indicate that the use of SSL is required.
+ */
+ String transportGuarantee() default "";
+
+ /**
+ * A secure endpoint does not by default publish it's wsdl on an unsecure transport.
+ * You can override this behaviour by explicitly setting the secureWSDLAccess flag to
false.
+ *
+ * Protect access to WSDL. See http://jira.jboss.org/jira/browse/JBWS-723
+ */
+ boolean secureWSDLAccess() default true;
+}
+</programlisting>
+</para>
+
+</section>
+<section><title>SecurityDomain</title>
+<para>
+<programlisting>
+/**
+ * Annotation for specifying the JBoss security domain for an EJB
+ *
+ * @author <a href="mailto:bill@jboss.org">Bill
Burke</a>
+ **/
+(a)Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
+public @interface SecurityDomain
+{
+ /**
+ * The required name for the security domain.
+ *
+ * Do not use the JNDI name
+ *
+ * Good: "MyDomain"
+ * Bad: "java:/jaas/MyDomain"
+ */
+ String value();
+
+ /**
+ * The name for the unauthenticated pricipal
+ */
+ String unauthenticatedPrincipal() default "";
+}
+</programlisting>
+</para>
+
+</section>
+
+</section>
+
+</section>
+<section><title>Appendix A</title>
+<para>
+JAX-WS Endpoint Configuration
+</para>
+<para>
+JAX-WS Client Configuration
+</para>
+<para>
+JAX-WS Annotations
+</para>
+<para>
+Common features and properties
+</para>
+
+</section>
+<section><title>References</title>
+<para>
+[1] <ulink
url="http://www.jcp.org/en/jsr/detail?id=224"><citetitle&... - Java
API for XML-Based Web Services (JAX-WS) 2.0</citetitle></ulink>
+</para>
+<para>
+[2] <ulink url="http://jaxb.dev.java.net"><citetitle>JSR 222 - Java
Architecture for XML Binding (JAXB) 2.0</citetitle></ulink>
+</para>
+<para>
+[3] <ulink
url="http://www.jcp.org/en/jsr/detail?id=261"><citetitle&... - Java
API for XML Web Services Addressing</citetitle></ulink>
+</para>
+<para>
+[4] <ulink
url="http://www.w3.org/TR/soap12-part1"><citetitle>SOA... - Messaging
Framework</citetitle></ulink>
+</para>
+<para>
+[5] <ulink
url="http://jcp.org/en/jsr/detail?id=250"><citetitle>J... - Common
Annotations for the Java Platform</citetitle></ulink>
+</para>
+<para>
+[6] <ulink url="http://jcp.org/en/jsr/detail?id=181"><citetitle>JSR
181 - Web Services Metadata for the Java Platform</citetitle></ulink>
+</para>
+</section>
+</article>
+</book>
\ No newline at end of file
Property changes on: tags/jbossws-2.0.0.GA/docs/jaxws-userguide.xml
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ LF
Added: tags/jbossws-2.0.0.GA/docs/quickstart.xml
===================================================================
--- tags/jbossws-2.0.0.GA/docs/quickstart.xml (rev 0)
+++ tags/jbossws-2.0.0.GA/docs/quickstart.xml 2007-07-11 11:58:28 UTC (rev 3847)
@@ -0,0 +1,442 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<book>
+<bookinfo><title>JBossWS 2.0.GA - Quick
Start</title><legalnotice><para>Permission to use, copy, modify and
distribute this document under the GNU Free Documentation License
(GFDL).</para></legalnotice></bookinfo><article
id="Quick_Start">
+<title>Quick Start</title>
+<para>
+Category:Build and Deploy (Quick Start)
+</para>
+<section><title>Right on'</title>
+<para>
+JBossWS uses the JBoss application server as it's primary target container. The
following examples focus on web service deployments that leverage EJB3 service
implementations and the JAX-WS programming models.For further information on POJO service
implementations, other target containers and advanced topics you need consult the user
guide.
+</para>
+<para>
+In the following sections we will explore the samples that ship the JBossWS distribution.
They do already provide a build structure based on Ant in order to get you started
quickly.
+</para>
+<section><title>Installing JBossWS</title>
+<para>
+The following steps assume that you already do have a JBoss installation. Currently, we
have integration layers for the JBoss application server 4.0.5, 4.2 and 5.0.For detailed
instructions please refer to the installation guide
+</para>
+
+</section>
+<section><title>Setup your development environment</title>
+<para>
+The samples that ship with the distribution are build on <ulink
url="http://ant.apache.org"><citetitle>Apache
Ant</citetitle></ulink>.
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+Get and install <ulink
url="http://ant.apache.org"><citetitle>Apache
Ant</citetitle></ulink>
+</para>
+</listitem>
+<listitem>
+<para>
+Get and install <ulink url="http://java.sun.com"><citetitle>JDK
5</citetitle></ulink>
+</para>
+</listitem>
+</orderedlist>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+If you ask yourself which JAR files are required to setup your IDE, take a look at the
build file (build.xml) that ships with the sample distribution. It contains class-path
declarations that point you to the required files.
+</para>
+
+</section>
+
+</section>
+<section><title>Developing web service implementations</title>
+<para>
+JAX-WS does leverage <ulink
url="http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations....
5 annotations</citetitle></ulink> in order to express web service meta data on
Java components and to describe the mapping between Java data types and XML. When
developing web service implementations you need to decide whether you are going start with
an abstract contract (<ulink
url="http://www.w3.org/TR/wsdl"><citetitle>WSDL</ci...>)
or a Java component.
+</para>
+<para>
+If you are in charge to provide the service implementation, then you are probably going
to start with the implementation and derive the abstract contract from it. You are
probably not even getting in touch with the WSDL unless you hand it to 3rd party clients.
For this reason we are going to look at a service implementation that leverages <ulink
url="http://jcp.org/en/jsr/detail?id=181"><citetitle>J...
annotations</citetitle></ulink>.<programlisting/>
+</para>
+<para>
+
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+
+</para>
+<para>
+Even though detailed knowledge of web service meta data is not required, it will
definitely help if you make yourself familiar with it. For further information see
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+[http://jcp.org/en/jsr/detail?id
+</para>
+</listitem>
+</itemizedlist>
+<section><title>The service implementation class</title>
+<para>
+When starting from Java you must provide the service implementation. A valid endpoint
implementation class must meet the following requirements:
+</para>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+It <emphasis>must</emphasis> carry a
<literal>javax.jws.WebService</literal> annotation (see JSR 181)
+</para>
+</listitem>
+<listitem>
+<para>
+All method parameters and return types <emphasis>must</emphasis> be
compatible with the JAXB 2.0
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Let's look at a sample EJB3 component that is going to be exposed as a web service.
(This is based on the Retail example).
+</para>
+<para>
+Don't be confused with the EJB3 annotation <literal>@Stateless</literal>.
We concentrate on the <literal>@WebService</literal> annotation for now.
+</para>
+<para>
+<emphasis role="bold">The service implementation class</emphasis>
+</para>
+<para>
+<programlisting>
+
+package org.jboss.test.ws.jaxws.samples.retail.profile;
+
+import javax.ejb.Stateless;
+import javax.jws.WebService;
+import javax.jws.WebMethod;
+import javax.jws.soap.SOAPBinding;
+
+@Stateless (1)
+@WebService( (2)
+ name="ProfileMgmt",
+ targetNamespace = "http://org.jboss.ws/samples/retail/profile",
+ serviceName = "ProfileMgmtService")
+@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE) (3)
+public class ProfileMgmtBean {
+
+ @WebMethod (4)
+ public DiscountResponse getCustomerDiscount(DiscountRequest request) {
+ return new DiscountResponse(request.getCustomer(), 10.00);
+ }
+}
+
+</programlisting>
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+We are using a stateless session bean implementation
+</para>
+</listitem>
+<listitem>
+<para>
+Exposed a web service with an explicit namespace
+</para>
+</listitem>
+<listitem>
+<para>
+It's a doc/lit bare endpoint
+</para>
+</listitem>
+<listitem>
+<para>
+And offers an 'getCustomerDiscount' operation
+</para>
+</listitem>
+</orderedlist>
+<para>
+<emphasis role="bold"> What about the payload? </emphasis>
+</para>
+<para>
+The method parameters and return values are going to represent our XML payload and thus
require being compatible with <ulink
url="http://java.sun.com/webservices/jaxb/"><citetitle>...;.
Actually you wouldn't need any JAXB annotations for this particular example, because
JAXB relies on meaningful defaults. For the sake of documentation we put the more
important ones here.
+</para>
+<para>
+Take a look at the request parameter:
+</para>
+<para>
+<programlisting>
+
+package org.jboss.test.ws.jaxws.samples.retail.profile;
+
+import javax.xml.bind.annotation.XmlAccessType;
+import javax.xml.bind.annotation.XmlAccessorType;
+import javax.xml.bind.annotation.XmlType;
+
+import org.jboss.test.ws.jaxws.samples.retail.Customer;
+
+(a)XmlAccessorType(XmlAccessType.FIELD)
+@XmlType( (1)
+ name = "discountRequest",
+ namespace="http://org.jboss.ws/samples/retail/profile",
+ propOrder = { "customer" }
+)
+public class DiscountRequest {
+
+ protected Customer customer;
+
+ public DiscountRequest() {
+ }
+
+ public DiscountRequest(Customer customer) {
+ this.customer = customer;
+ }
+
+ public Customer getCustomer() {
+ return customer;
+ }
+
+ public void setCustomer(Customer value) {
+ this.customer = value;
+ }
+
+}
+
+</programlisting>
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+In this case we use <literal>@XmlType</literal> to specify an XML complex
type name and override the namespace.
+</para>
+</listitem>
+</orderedlist>
+<itemizedlist mark="opencircle"><listitem>
+<para>
+If you have more complex mapping problems you need to consult the <ulink
url="http://java.sun.com/webservices/jaxb/"><citetitle>...
documentation</citetitle></ulink>.
+</para>
+</listitem>
+</itemizedlist>
+
+</section>
+<section><title>Deploying service implementations</title>
+<para>
+Service deployment basically depends on the implementation type. As you may already know
web services can be implemented as EJB3 components or plain old Java objects. This quick
start leverages EJB3 components in all examples, thats why we are going to look at this
case in the next sections.
+</para>
+<para>
+<emphasis role="bold"> EJB3 services </emphasis>
+</para>
+<para>
+Simply wrap up the service implementation class, the endpoint interface and any custom
data types in a JAR and drop them in the <literal>deploy</literal> directory.
No additional deployment descriptors required. Any meta data required for the deployment
of the actual web service is taken from the annotations provided on the implementation
class and the service endpoint interface. JBossWS will intercept that EJB3 deployment (the
bean will also be there) and create an HTTP endpoint at deploy-time:
+</para>
+<para>
+<emphasis role="bold">The JAR package structure</emphasis>
+</para>
+<para>
+<programlisting>
+jar -tf jaxws-samples-retail.jar
+
+org/jboss/test/ws/jaxws/samples/retail/profile/DiscountRequest.class
+org/jboss/test/ws/jaxws/samples/retail/profile/DiscountResponse.class
+org/jboss/test/ws/jaxws/samples/retail/profile/ObjectFactory.class
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmt.class
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtBean.class
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtService.class
+org/jboss/test/ws/jaxws/samples/retail/profile/package-info.class
+</programlisting>
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+If the deployment was successful you should be able to see your endpoint at
http://localhost:8080/jbossws/services
+</para>
+
+</section>
+
+</section>
+<section><title>Consuming web services</title>
+<para>
+When creating web service clients you would usually start from the WSDL. JBossWS ships
with a set of tools to generate the required JAX-WS artefacts to build client
implementations. In the following section we will look at the most basic usage patterns.
For a more detailed introductoin to web service client please consult the user
guide.<programlisting/>
+</para>
+<section><title>Creating the client artefacts</title>
+<para>
+<emphasis role="bold"> Using wsconsume </emphasis>
+</para>
+<para>
+The wsconsume tool is used to consume the abstract contract (WSDL) and produce annotated
Java classes (and optionally sources) that define it. We are going to start with the WSDL
from our retail example (ProfileMgmtService.wsdl). For a detailed tool reference you need
to consult the user guide.
+</para>
+<para>
+<programlisting>
+wsconsume is a command line tool that generates
+portable JAX-WS artifacts from a WSDL file.
+
+usage: org.jboss.ws.tools.jaxws.command.wsconsume [options] <wsdl-url>
+
+options:
+ -h, --help Show this help message
+ -b, --binding=<file> One or more JAX-WS or JAXB binding files
+ -k, --keep Keep/Generate Java source
+ -c --catalog=<file> Oasis XML Catalog file for entity resolution
+ -p --package=<name> The target package for generated source
+ -w --wsdlLocation=<loc> Value to use for @WebService.wsdlLocation
+ -o, --output=<directory> The directory to put generated artifacts
+ -s, --source=<directory> The directory to put Java source
+ -q, --quiet Be somewhat more quiet
+ -t, --show-traces Show full exception stack traces
+</programlisting>
+</para>
+<para>
+Let's try it on our retail sample:
+</para>
+<para>
+<programlisting>
+~./wsconsume.sh -k
+-p org.jboss.test.ws.jaxws.samples.retail.profile ProfileMgmtService.wsdl (1)
+
+org/jboss/test/ws/jaxws/samples/retail/profile/Customer.java
+org/jboss/test/ws/jaxws/samples/retail/profile/DiscountRequest.java
+org/jboss/test/ws/jaxws/samples/retail/profile/DiscountResponse.java
+org/jboss/test/ws/jaxws/samples/retail/profile/ObjectFactory.java
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmt.java
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtService.java
+org/jboss/test/ws/jaxws/samples/retail/profile/package-info.java
+
+</programlisting>
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+As you can see we did use the <literal>-p</literal> switch to specify the
package name of the generated sources.
+</para>
+</listitem>
+</orderedlist>
+<para>
+<emphasis role="bold"> The generated artefacts explained
</emphasis><table>
+<title/><tgroup cols="2"><tbody><row>
+<entry>
+File
+</entry>
+<entry>
+Purpose
+</entry>
+
+</row>
+<row>
+<entry>
+ProfileMgmt.java
+</entry>
+<entry>
+Service Endpoint Interface
+</entry>
+
+</row>
+<row>
+<entry>
+Customer.java
+</entry>
+<entry>
+Custom data type
+</entry>
+
+</row>
+<row>
+<entry>
+Discount*.java
+</entry>
+<entry>
+Custom data type
+</entry>
+
+</row>
+<row>
+<entry>
+ObjectFactory.java
+</entry>
+<entry>
+JAXB XML Registry
+</entry>
+
+</row>
+<row>
+<entry>
+package-info.java
+</entry>
+<entry>
+Holder for JAXB package annotations
+</entry>
+
+</row>
+<row>
+<entry>
+ProfileMgmtService.java
+</entry>
+<entry>
+Service factory
+</entry>
+
+</row>
+</tbody></tgroup>
+</table>
+
+</para>
+<para>
+Basically <literal>wsconsume</literal> generates all custom data types (JAXB
annotated classes), the service endpoint interface and a service factory class. We will
look at how these artefacts can be used the build web service client implementations in
the next section.
+</para>
+
+</section>
+<section><title>Constructing a service stub</title>
+<para>
+Web service clients make use of a service stubs that hide the details of a remote web
service invocation. To a client application a WS invocation just looks like an invocation
of any other business component. In this case the service endpoint interface acts as the
business interface. JAX-WS does use a service factory class to construct this as
particular service stub:
+</para>
+<para>
+<programlisting>
+import javax.xml.ws.Service;
+
+Service service = Service.create( (1)
+ new URL("http://example.org/service?wsdl"),
+ new QName("MyService")
+);
+ProfileMgmt profileMgmt = service.getPort(ProfileMgmt.class); (2)
+
+// do something with the service stub here... (3)
+</programlisting>
+</para>
+<orderedlist numeration="arabic"><listitem>
+<para>
+Create a service factory using the WSDL location and the service name
+</para>
+</listitem>
+<listitem>
+<para>
+Use the tool created service endpoint interface to build the service stub
+</para>
+</listitem>
+<listitem>
+<para>
+Use the stub like any other business interface
+</para>
+</listitem>
+</orderedlist>
+<para>
+<emphasis role="bold">Note</emphasis>
+</para>
+<para>
+The creation of the service stub is quite costly. You should take care that it gets
reused by your application code (However <emphasis role="bold">it's
not thread safe</emphasis>). Within a EE5 environment you might want to investigate
the <literal>@WebServiceRef</literal> functionality.
+</para>
+
+</section>
+
+</section>
+<section><title>Appendix</title>
+<section><title>ProfileMgmtService.wsdl</title>
+<para>
+<programlisting><definitions
+ name='ProfileMgmtService'
+ targetNamespace='http://org.jboss.ws/samples/retail/profile'
+ xmlns='http://schemas.xmlsoap.org/wsdl/'
+ xmlns:ns1='http://org.jboss.ws/samples/retail'
+ xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'
+ xmlns:tns='http://org.jboss.ws/samples/retail/profile'
+
xmlns:xsd='http://www.w3.org/2001/XMLSchema'><types...
targetNamespace='http://org.jboss.ws/samples/retail'
+ version='1.0'
xmlns:xs='http://www.w3.org/2001/XMLSchema'><xs:com...
name='customer'><xs:sequence><xs:element
minOccurs='0' name='creditCardDetails'
type='xs:string'/><xs:element minOccurs='0'
name='firstName' type='xs:string'/><xs:element
minOccurs='0' name='lastName'
type='xs:string'/></xs:sequence></xs:complexType></xs:schema><xs:schema
+ targetNamespace='http://org.jboss.ws/samples/retail/profile'
+ version='1.0'
+ xmlns:ns1='http://org.jboss.ws/samples/retail'
+ xmlns:tns='http://org.jboss.ws/samples/retail/profile'
+ xmlns:xs='http://www.w3.org/2001/XMLSchema'><xs:import
namespace='http://org.jboss.ws/samples/retail'/><xs:element
name='getCustomerDiscount'
+ nillable='true' type='tns:discountRequest'/><xs:element
name='getCustomerDiscountResponse'
+ nillable='true'
type='tns:discountResponse'/><xs:complexType
name='discountRequest'><xs:sequence><xs:element
minOccurs='0' name='customer'
type='ns1:customer'/></xs:sequence></xs:complexType><xs:complexType
name='discountResponse'><xs:sequence><xs:element
minOccurs='0' name='customer'
type='ns1:customer'/><xs:element name='discount'
type='xs:double'/></xs:sequence></xs:complexType></xs:schema></types><message
name='ProfileMgmt_getCustomerDiscount'><part
element='tns:getCustomerDiscount'
name='getCustomerDiscount'/></message><message
name='ProfileMgmt_getCustomerDiscountResponse'><part
element='tns:getCustomerDiscountResponse'
+
name='getCustomerDiscountResponse'/></message><portType
name='ProfileMgmt'><operation name='getCustomerDiscount'
+ parameterOrder='getCustomerDiscount'><input
message='tns:ProfileMgmt_getCustomerDiscount'/><output
message='tns:ProfileMgmt_getCustomerDiscountResponse'/></operation></portType><binding
name='ProfileMgmtBinding'
type='tns:ProfileMgmt'><soap:binding style='document'
+ transport='http://schemas.xmlsoap.org/soap/http'/><...
name='getCustomerDiscount'><soap:operation
soapAction=''/><input><soap:body
use='literal'/></input><output><soap:body
use='literal'/></output></operation></binding><service
name='ProfileMgmtService'><port
binding='tns:ProfileMgmtBinding'
name='ProfileMgmtPort'><soap:address
+
location='http://<HOST>:<PORT>/jaxws-samples-retail/ProfileMgmtBean'/></port></service></definitions></programlisting>
+</para>
+</section>
+
+</section>
+</article>
+</book>
\ No newline at end of file
Property changes on: tags/jbossws-2.0.0.GA/docs/quickstart.xml
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ LF
6391
days inactive
6391
days old
jbossws-commits@lists.jboss.org
0 comments
1 participants
participants (1)
-
jbossws-commits＠lists.jboss.org