[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Shane Bryzak
sbryzak at redhat.com
Sun Jun 24 07:07:11 EDT 2007
User: sbryzak2
Date: 07/06/24 07:07:11
Added: doc/reference/en/modules webservices.xml
Log:
started web services documentation
Revision Changes Path
1.1 date: 2007/06/24 11:07:11; author: sbryzak2; state: Exp;jboss-seam/doc/reference/en/modules/webservices.xml
Index: webservices.xml
===================================================================
<chapter id="webservices">
<title>Web Services</title>
<para>
Seam integrates with JBossWS to allow standard JEE web services to take full advantage of Seam's contextual framework,
including support for conversational web services. This chapter walks through the steps required to allow web
services to run within a Seam environment.
</para>
<sect1>
<title>Configuration and Packaging</title>
<para>
To allow Seam to intercept web service requests so that the necessary Seam contexts can be created for the request,
a special SOAP handler must be configured; <literal>org.jboss.seam.webservice.SOAPRequestHandler</literal>
is a <literal>SOAPHandler</literal> implementation that does the work of managing Seam's lifecycle during the scope
of a web service request. The easiest way to configure a project to use this handler, is to place a file called
<literal>standard-jaxws-endpoint-config.xml</literal> into the <literal>META-INF</literal> directory of the
<literal>jar</literal> file that contains the web service classes. This file contains the following SOAP handler
configuration:
</para>
<programlisting><![CDATA[<jaxws-config xmlns="urn:jboss:jaxws-config:2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:javaee="http://java.sun.com/xml/ns/javaee"
xsi:schemaLocation="urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
<endpoint-config>
<config-name>Seam WebService Endpoint</config-name>
<pre-handler-chains>
<javaee:handler-chain>
<javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
<javaee:handler>
<javaee:handler-name>SOAP Request Handler</javaee:handler-name>
<javaee:handler-class>org.jboss.seam.webservice.SOAPRequestHandler</javaee:handler-class>
</javaee:handler>
</javaee:handler-chain>
</pre-handler-chains>
</endpoint-config>
</jaxws-config>]]></programlisting>
</sect1>
<sect1>
<title>Conversational Web Services</title>
<para>
So how are conversations propagated between web service requests? Seam uses a SOAP header element present
in both the SOAP request and response messages to carry the conversation ID from the consumer to the service,
and back again. Here's an example of a web service request that contains a conversation ID:
</para>
<programlisting><![CDATA[<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:seam="http://seambay.example.seam.jboss.org/">
<soapenv:Header>
<seam:conversationId xmlns:seam='http://www.jboss.org/seam/webservice'>2</seam:conversationId>
</soapenv:Header>
<soapenv:Body>
<seam:confirmAuction/>
</soapenv:Body>
</soapenv:Envelope>
]]></programlisting>
<para>
As you can see in the above SOAP message, there is a <literal>conversationId</literal> element within the
SOAP header that contains the conversation ID for the request, in this case <literal>2</literal>.
Unfortunately, because web services may be consumed by a variety of web service clients written in a
variety of languages, it is up to the developer to implement conversation ID propagation between individual
web services that are intended to be used within the scope of a single conversation.
</para>
<para>
An important thing to note is that the <literal>conversationId</literal> header element must be qualified
with a namespace of <literal>http://www.jboss.org/seam/webservice</literal>. Here's an example of a response
to the above request message:
</para>
<programlisting><![CDATA[<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
<env:Header>
<seam:conversationId xmlns:seam='http://www.jboss.org/seam/webservice'>2</seam:conversationId>
</env:Header>
<env:Body>
<confirmAuctionResponse xmlns="http://seambay.example.seam.jboss.org/"/>
</env:Body>
</env:Envelope>
]]></programlisting>
<para>
As you can see, the response message contains the same <literal>conversationId</literal> element as the request.
</para>
</sect1>
<sect1>
<title>An example web service</title>
<para>
Let's walk through an example web service. The code in this section all comes from the seamBay example
application in Seam's <literal>/examples</literal> directory. Let's first take a look at the web service
class and one of it's web service methods:
</para>
<programlisting><![CDATA[@Stateless
@WebService(name = "AuctionService", serviceName = "AuctionService")
public class AuctionService implements AuctionServiceRemote
{
@WebMethod
public boolean login(String username, String password)
{
Identity.instance().setUsername(username);
Identity.instance().setPassword(password);
Identity.instance().login();
return Identity.instance().isLoggedIn();
}
// snip
}]]></programlisting>
<para>
As you can see, our web service is a stateless session bean, and is annotated using the JWS annotations
from the <literal>javax.jws</literal> package, as defined by JSR-181. The <literal>@WebService</literal>
annotation tells the container that this class implements a web service, and the <literal>@WebMethod</literal>
annotation on the <literal>login()</literal> method identifies the method as a web service method.
The <literal>name</literal> and <literal>serviceName</literal> attributes in the <literal>@WebService</literal>
annotation are optional.
</para>
<para>
As is required by the specification, each method that is to be exposed as a web service method must also be
declared in the remote interface of the web service class (when the web service is a stateless session bean).
In the above example, the <literal>AuctionServiceRemote</literal> interface must declare the <literal>login()</literal>
method as it is annotated as a <literal>@WebMethod</literal>.
</para>
<para>
</para>
</sect1>
</chapter>
More information about the jboss-cvs-commits
mailing list