2:25 p.m.
Author: alessio.soldano(a)jboss.com
Date: 2010-11-02 15:25:45 -0400 (Tue, 02 Nov 2010)
New Revision: 13202
Added:
stack/native/trunk/src/main/doc/
stack/native/trunk/src/main/doc/Author_Group.xml
stack/native/trunk/src/main/doc/Book_Info.xml
stack/native/trunk/src/main/doc/JBossWS-Advancedsamples.xml
stack/native/trunk/src/main/doc/JBossWS-Articlesandspecs.xml
stack/native/trunk/src/main/doc/JBossWS-Asynchronousinvocationssample.xml
stack/native/trunk/src/main/doc/JBossWS-Authentication.xml
stack/native/trunk/src/main/doc/JBossWS-Endpointmanagement.xml
stack/native/trunk/src/main/doc/JBossWS-JAX-WSAnnotations.xml
stack/native/trunk/src/main/doc/JBossWS-JAX-WSClientConfiguration.xml
stack/native/trunk/src/main/doc/JBossWS-JAX-WSEndpointConfiguration.xml
stack/native/trunk/src/main/doc/JBossWS-JAX-WSTools.xml
stack/native/trunk/src/main/doc/JBossWS-Native.xml
stack/native/trunk/src/main/doc/JBossWS-NativeUserGuide.xml
stack/native/trunk/src/main/doc/JBossWS-NativeWS-AddressingTutorial.xml
stack/native/trunk/src/main/doc/JBossWS-NativeWS-ReliableMessagingTutorial.xml
stack/native/trunk/src/main/doc/JBossWS-QuickStart.xml
stack/native/trunk/src/main/doc/JBossWS-Recordsmanagement.xml
stack/native/trunk/src/main/doc/JBossWS-Securetransport.xml
stack/native/trunk/src/main/doc/JBossWS-Securityandattachmentssample.xml
stack/native/trunk/src/main/doc/JBossWS-UserGuide.xml
stack/native/trunk/src/main/doc/JBossWS-WS-Securityoptions.xml
stack/native/trunk/src/main/doc/JBossWS-wsconsume.xml
stack/native/trunk/src/main/doc/JBossWS-wsprovide.xml
stack/native/trunk/src/main/doc/JBossWS-wsrunclient.xml
Modified:
stack/native/trunk/pom.xml
stack/native/trunk/src/main/scripts/assembly-bin-dist.xml
Log:
[JBWS-2215] Adding docbook files and including doc generation in bin dist creation
Modified: stack/native/trunk/pom.xml
===================================================================
--- stack/native/trunk/pom.xml 2010-11-02 18:02:20 UTC (rev 13201)
+++ stack/native/trunk/pom.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -388,6 +388,32 @@
<!-- Plugins -->
<build>
+
+ <!-- PluginMangament-->
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jdocbook-plugin</artifactId>
+ <version>2.1.2</version>
+ <extensions>true</extensions>
+ <dependencies>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-docbook-xslt</artifactId>
+ <version>1.1.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-jdocbook-style</artifactId>
+ <version>1.0.0</version>
+ <type>jdocbook-style</type>
+ </dependency>
+ </dependencies>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+
<plugins>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
@@ -474,6 +500,49 @@
</descriptors>
</configuration>
</plugin>
+ <plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jdocbook-plugin</artifactId>
+ <executions>
+ <execution>
+ <goals>
+ <goal>resources</goal>
+ <goal>generate</goal>
+ </goals>
+ <phase>package</phase>
+ </execution>
+ </executions>
+ <configuration>
+ <sourceDocumentName>JBossWS-Native.xml</sourceDocumentName>
+ <sourceDirectory>src/main/doc</sourceDirectory>
+ <imageResource>
+ <directory>src/main/doc</directory>
+ <includes>
+ <include>images/*</include>
+ </includes>
+ </imageResource>
+ <formats>
+ <!--format>
+ <formatName>pdf</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
+ <finalName>JBossWS-Native_Guide.pdf</finalName>
+ </format-->
+ <format>
+ <formatName>html</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ <format>
+ <formatName>html_single</formatName>
+
<stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ </formats>
+ <options>
+ <xincludeSupported>true</xincludeSupported>
+ </options>
+ </configuration>
+ </plugin>
</plugins>
</build>
</profile>
Added: stack/native/trunk/src/main/doc/Author_Group.xml
===================================================================
--- stack/native/trunk/src/main/doc/Author_Group.xml (rev 0)
+++ stack/native/trunk/src/main/doc/Author_Group.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,17 @@
+<?xml version='1.0'?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+ ]>
+<authorgroup>
+ <author>
+ <firstname>Alessio</firstname>
+ <surname>Soldano</surname>
+ </author>
+ <author>
+ <firstname>Richard</firstname>
+ <surname>Opalka</surname>
+ </author>
+ <author>
+ <firstname>Jim</firstname>
+ <surname>Ma</surname>
+ </author>
+</authorgroup>
Added: stack/native/trunk/src/main/doc/Book_Info.xml
===================================================================
--- stack/native/trunk/src/main/doc/Book_Info.xml (rev 0)
+++ stack/native/trunk/src/main/doc/Book_Info.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,14 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+
+<bookinfo>
+<title>JBossWS-Native Guide</title>
+ <subtitle>JBoss Web Services with Native stack</subtitle>
+ <productname>JBossWS-Native</productname>
+ <!-- <pubdate>Nov 2010</pubdate> -->
+ <abstract>
+ <para>This book is the guide to JBoss Web Services with Native stack. It covers
information, details and usage of JBossWS-Native stack, as well as some tutorials /
examples.</para>
+ </abstract>
+ <!-- <subtitle>Authors</subtitle>-->
+ <xi:include href="Author_Group.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+</bookinfo>
Added: stack/native/trunk/src/main/doc/JBossWS-Advancedsamples.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Advancedsamples.xml
(rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Advancedsamples.xml 2010-11-02 19:25:45 UTC
(rev 13202)
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-Advancedsamples"><title>JBossWS-Advancedsamples</title><para>The
aim of this page is to help users coping with real world usecases. For this reason some
advanced sample have been
developed.</para><para> </para><section><title>How to use
the advanced samples</title><para>The JBossWS <ulink
url="http://community.jboss.org/docs/DOC-13550">basic samples</ulink>
introduce you to most of the available features, showing you how to use each of them
through simple JUnit test cases.</para><para> </para><para>Instead
the advanced samples covered here have their own scenario linking them to a real world use
case. They are meant to be used as stand alone applications: different reliable
implementations are proposed for each scenario, leveraging the most suitable JBossWS
features. The choices taken for the key points of each usecase are then discussed. You
should follow the steps in the documentation and run the applicatio!
ns whenever you're invited to. This way you'll be able to understand the
advantages and disadvantages of each
solution.</para><para> </para><para>Right now the advanced sample
are available in the source distribution only. You need to download it and run
<emphasis>ant</emphasis> (default target) to compile everything. The advanced
samples' archives (both client and server) are in the
<emphasis>output/tests/lib</emphasis> directory like the other
samples.</para><para> </para></section>
+<section><title>Available
samples</title><itemizedlist><listitem><para> <link
linkend="chap_JBossWS-Asynchronousinvocationssample">JBossWS - Asynchronous
invocations sample</link>: <emphasis>Asynchronous invocations to long running
ws endpoint operations</emphasis>
</para></listitem><listitem><para> <link
linkend="chap_JBossWS-Securityandattachmentssample">JBossWS - Security and
attachments sample</link>: <emphasis>Security and attachments</emphasis>
</para></listitem></itemizedlist></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Articlesandspecs.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Articlesandspecs.xml
(rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Articlesandspecs.xml 2010-11-02 19:25:45 UTC
(rev 13202)
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-Articlesandspecs"><title>JBossWS-Articlesandspecs</title><section><title>J2EE-5.0
Web Services Specifications</title><itemizedlist><listitem><para>
<ulink url="http://www.jcp.org/en/jsr/detail?id=244">J2EE-5.0 - Java2
Enterprise Edition Specification (JSR244)</ulink>
</para></listitem><listitem><para> <ulink
url="http://www.jcp.org/en/jsr/detail?id=921">WS4EE-1.1 - Enterprise Web
Services (JSR921)</ulink> </para></listitem><listitem><para>
<ulink url="http://www.jcp.org/en/jsr/detail?id=220">EJB-3.0 - Enterprise
Java Beans (JSR220)</ulink>
</para></listitem><listitem><para> <ulink
url="http://www.jcp.org/en/jsr/detail?id=224">JAXWS-2.0 - Java API for
XML-Based Web Services (JSR224)</ulink>
</para></listitem><listitem><para> <ulink
url="http://www.jcp.org/en/jsr/detail?id=222">JAXB-2.0 - Java Architecture
for XML Binding (JSR222)</ulink>
</para></listitem><listitem><para> <ulink
url="http://www.w3.org/TR/soap12-!
part1">SOAP-1.2 - SOAP Messaging Framework</ulink>
</para></listitem><listitem><para> <ulink
url="http://www.w3.org/TR/soap12-part0">SOAP-1.2 Primer</ulink>
</para></listitem><listitem><para> <ulink
url="http://schemas.xmlsoap.org/wsdl/soap12">WSDL 1.1 Binding Extension for
SOAP 1.2</ulink> </para></listitem><listitem><para>
<ulink url="http://www.w3.org/TR/wsdl20">WSDL-2.0 - Part 1: Core
Language</ulink> </para></listitem><listitem><para>
<ulink url="http://www.w3.org/TR/wsdl20-extensions">WSDL-2.0 - Part 2:
Predefined Extensions</ulink>
</para></listitem><listitem><para> <ulink
url="http://www.w3.org/TR/wsdl20-bindings">WSDL-2.0 - Part 3:
Bindings</ulink> </para></listitem><listitem><para>
<ulink url="http://www.w3.org/2002/ws/desc/wsdl20-primer">WSDL-2.0
Primer</ulink> </para></listitem><listitem><para> <ulink
url="http://www.ws-i.org/Profiles/BasicProfile-1.1.html">BP-1.1 - Basic
Profile</ulink> </para></listitem><listitem><para> <ulink
url="http://www.jcp.org/en/jsr/de!
tail?id=181">JSR181 - Web Services Metadata</ulink> </para></l!
istitem>
<listitem><para> <ulink
url="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0.html"&...
Attachments Profile 1.0</ulink>
</para></listitem><listitem><para> <ulink
url="http://www.w3.org/TR/soap12-mtom/">SOAP Message Transmission
Optimization Mechanism (MTOM)</ulink>
</para></listitem><listitem><para> <ulink
url="http://www.w3.org/TR/xop10/">XML-binary Optimized Packaging
(XOP)</ulink></para></listitem></itemizedlist></section>
+<section><title>J2EE-1.4 Web Services
Specifications</title><itemizedlist><listitem><para> <ulink
url="http://java.sun.com/j2ee/1.4/index.jsp">J2EE-1.4 - Java 2 Platform,
Enterprise Edition (J2EE) 1.4</ulink>
</para></listitem><listitem><para> <ulink
url="http://www.jcp.org/en/jsr/detail?id=921">WS4EE-1.1 - Enterprise Web
Services</ulink> </para></listitem><listitem><para>
<ulink url="http://www.jcp.org/en/jsr/detail?id=153">EJB-2.1 - Enterprise
Java Beans</ulink> </para></listitem><listitem><para>
<ulink url="http://www.jcp.org/en/jsr/detail?id=101">JAXRPC-1.1 - Java API
for XML-based RPC</ulink> </para></listitem><listitem><para>
<ulink url="http://www.jcp.org/en/jsr/detail?id=67">SAAJ-1.2 - SOAP with
Attachments</ulink> </para></listitem><listitem><para>
<ulink url="http://www.jcp.org/en/jsr/detail?id=93">JAXR-1.0 - Java API
for XML Registries</ulink>
</para></listitem><listitem><para> <ulink
url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508">SOAP-1.1 - Simple Object
Acc!
ess Protocol</ulink> </para></listitem><listitem><para>
<ulink url="http://www.w3.org/TR/wsdl">WSDL-1.1 - Web Services Description
Language</ulink> </para></listitem><listitem><para>
<ulink url="http://www.w3.org/TR/REC-xml/">XML-1.0 - Extensible Markup
Language</ulink> </para></listitem><listitem><para>
<ulink url="http://www.w3.org/TR/xmlschema-1/">XMLSchema -
Structures</ulink> </para></listitem><listitem><para>
<ulink url="http://www.w3.org/TR/xmlschema-2/">XMLSchema - Data
Types</ulink> </para></listitem><listitem><para> <ulink
url="http://www.w3.org/TR/xmlschema-0">XMLSchema Primer</ulink>
</para></listitem><listitem><para> <ulink
url="http://www.w3.org/TR/REC-xml-names">XMLNS - Namespaces in
XML</ulink> </para></listitem><listitem><para> <ulink
url="http://www.ws-i.org/Profiles/BasicProfile-1.0.html">BP-1.0 - Basic
Profile</ulink></para></listitem></itemizedlist></section>
+<section><title>Optional advanced Web Services
specifications</title><itemizedlist><listitem><para> <ulink
url="http://msdn.microsoft.com/library/default.asp?url=/library/en-u...
Web Services Specifications Index Page</ulink>
</para></listitem><listitem><para> <ulink
url="http://jira.jboss.com/jira/browse/JBWS-330">WS-Distributed
Managment</ulink> </para></listitem><listitem><para>
<ulink
url="http://jira.jboss.com/jira/browse/JBWS-326">WS-Notifica...
</para></listitem><listitem><para> <ulink
url="http://jira.jboss.com/jira/browse/JBWS-76">WS-ReliableM...
</para></listitem><listitem><para> <ulink
url="http://jira.jboss.com/jira/browse/JBWS-329">WS-Resource...
</para></listitem><listitem><para> <ulink
url="http://jira.jboss.com/jira/browse/JBWS-36">WS-Transacti...
</para></listitem><listitem><para> <ulink
url="http://jira.jboss.org/jira/browse/JBWS-447">WS-BPEL<...!
ablelist/><para>Please provide feedback on your needs of these optional WS
specifications as this will influence what we will put on the <ulink
url="http://jira.jboss.org/jira/browse/JBWS?report=com.atlassian.jir...
roadmap</ulink>.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Asynchronousinvocationssample.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Asynchronousinvocationssample.xml
(rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Asynchronousinvocationssample.xml 2010-11-02
19:25:45 UTC (rev 13202)
@@ -0,0 +1,844 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-Asynchronousinvocationssample"><title>JBossWS-Asynchronousinvocationssample</title><section
id="JBossWS-Asynchronousinvocationssample_Scenario"><title>Scenario</title><para>This
sample targets those business scenarios in which web services expose functionalities
requiring long running processes. Service consumers send the message requests and
don't want to actively wait for the response or use polling mechanism to find out
whether their response is ready.</para><para> </para><para>The
<emphasis role="bold">org.jboss.test.ws.jaxws.samples.dar</emphasis>
sample is about a Dial-a-ride optimization service. The Dial-a-Ride (DaR) is an emerging
transport system, in which a fleet of vehicles, without fixed routes and schedules,
carries people from the desired pickup point to the desired delivery point, during a
pre-specified time interval. Passengers ring the service provider office the day before
they want to trave!
l and book their ride. An optimization system works out the route to be as efficient as
possible, so that for instance people with similar travel requests are collected by the
same vehicle. Since the problem can be modeled as an NP-hard routing and scheduling
problem and exact approaches are insufficient for real-life problems, our software company
decides to provide a service that solves the DaR problem for transportation companies'
requests through complex custom heuristic algorithms. And of course, this takes some
time.</para><para> </para></section>
+<section
id="JBossWS-Asynchronousinvocationssample_The_service_provider"><title>The
service provider</title><para>We start defining and implementing the DaR
service provider (bottom-up approach):</para><screen
xml:space="preserve">@Stateless
+@WebService(name = "DarEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/dar",
+ serviceName = "DarService")
+@SOAPBinding(style = SOAPBinding.Style.RPC,
+ use = SOAPBinding.Use.LITERAL)
+@SecurityDomain("JBossWS")
+@WebContext(contextRoot="/dar",
+ urlPattern="/*",
+ authMethod="BASIC",
+ transportGuarantee="NONE",
+ secureWSDLAccess=<emphasis
role="bold">false</emphasis>)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> DarEndpoint
+{
+ @WebMethod(operationName = "process", action =
"http://org.jboss.test.ws.jaxws.samples.dar/action/processIn")
+ <emphasis role="bold">public</emphasis> DarResponse
process(DarRequest request)
+ {
+ DarProcessor processor = <emphasis role="bold">new</emphasis>
DarProcessor();
+ <emphasis role="bold">return</emphasis>
processor.process(request);
+ }
+}
+</screen><para>To keep this simple we use a SLSB endpoint and the rpc/literal
style/use, of course you can choose POJO endpoint and the better document style as well. A
BASIC authorization method is used to achieve request accountability; for ease we use the
default JBossWS security domain, of course you would need to authenticate transport
companies through your own login module as well as keep track of the requests for billing
reasons. The DarProcessor performs the actual DaR problem solution and optimization.
DarRequest and DarResponse, along with the referenced classes, define the request and
response model, with the pickup and delivery point on the map, the departure/arrival
times, etc. Every further detail (for instance about quality of service) is not considered
to keep the sample simple.</para><para>You can build the sample, take a look
at the simple service endpoint in <emphasis>jaxws-samples-dar.jar</emphasis>
and deploy it.</para><screen xml:space="preserve">[ale!
ssio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-dar.jar
+ 0 Fri Feb 01 17:55:20 CET 2008 META-INF/
+ 106 Fri Feb 01 17:55:18 CET 2008 META-INF/MANIFEST.MF
+ 0 Thu Jan 10 21:41:02 CET 2008 org/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/
+ 789 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Bus.class
+ 1643 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/DarEndpoint.class
+ 4231 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/DarProcessor.class
+ 1585 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarRequest.class
+ 1340 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/DarResponse.class
+ 1085 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Route.class
+ 1314 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/ServiceRequest.class
+ 834 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Stop.class
+</screen><para>Assume your bind address is
<emphasis>localhost.localdomain:8080</emphasis>; the JBossWS stack will deploy
the service and publish the wsdl contract at <ulink
url="http://localhost.localdomain:8080/dar?wsdl">http://localhost.localdomain:8080/dar?wsdl</ulink>.</para><para> </para></section>
+<section
id="JBossWS-Asynchronousinvocationssample_JAXWS_Asynchronous_API"><title>JAX-WS
Asynchronous API</title><section
id="JBossWS-Asynchronousinvocationssample_The_transportation_company_client"><title>The
transportation company client</title><para>Once the first implementation of
the service provider is ready, we generate a simple client to test it. This can be easily
achieved with the <ulink
url="http://community.jboss.org/docs/DOC-13542">wsconsume<...
script:</para><screen xml:space="preserve">wsconsume.sh -k -p
org.jboss.test.ws.jaxws.samples.dar.generated
http://localhost.localdomain:8080/dar?wsdl</screen><para>This outputs the
endpoint interface that our client has to use, as well as all the classes for
requests/responses. Since we need to perform asynchronous invocations using the <ulink
url="http://community.jboss.org/docs/DOC-13972#Asynchronous_Invocati...
async API</ulink>, we a need method with the same name of the existing one followed
by <emphas!
is>Async</emphasis> and returning a
javax.xml.ws.Response:</para><screen
xml:space="preserve">@WebService(name = "DarEndpoint",
targetNamespace = "http://org.jboss.ws/samples/dar")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">interface</emphasis> DarEndpoint {
+
+ @WebMethod(operationName = "process")
+ <emphasis role="bold">public</emphasis>
Response<DarResponse> processAsync(@WebParam(name = "arg0",
partName = "arg0") DarRequest arg0);
+
+ @WebMethod(action =
"http://org.jboss.test.ws.jaxws.samples.dar/action/processIn")
+ @WebResult(partName = "return")
+ <emphasis role="bold">public</emphasis> DarResponse
process(@WebParam(name = "arg0", partName = "arg0") DarRequest arg0);
+}
+</screen><para>Then we implement the client, invoking both the method to see
the different behaviors:</para><screen
xml:space="preserve"><emphasis
role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> Client
+{
+ <emphasis role="bold">protected</emphasis> DarEndpoint
endpoint;
+
+ <emphasis role="bold">public</emphasis> Client(URL url)
+ {
+ DarService service = <emphasis role="bold">new</emphasis>
DarService(url, <emphasis role="bold">new</emphasis>
QName("http://org.jboss.ws/samples/dar", "DarService"));
+ endpoint = service.getDarEndpointPort();
+ ClientHelper.setUsernamePassword((BindingProvider)endpoint, "kermit",
"thefrog");
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> run(<emphasis
role="bold">boolean</emphasis> asynch) <emphasis
role="bold">throws</emphasis> Exception
+ {
+ DarRequest request = ClientHelper.getRequest();
+ System.out.println(<emphasis role="bold">new</emphasis>
Date() + " Sending request...");
+ DarResponse darResponse;
+ <emphasis role="bold">if</emphasis> (asynch)
+ {
+ Response<DarResponse> response = endpoint.processAsync(request);
+ System.out.println("Doing something interesting in the mean time... ;-)
");
+ darResponse = response.get();
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ darResponse = endpoint.process(request);
+ }
+ System.out.println(<emphasis role="bold">new</emphasis>
Date() + " Response received: "+darResponse);
+ ClientHelper.printResponse(darResponse);
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">void</emphasis> main(String[] args)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ <emphasis role="bold">if</emphasis> (args.length == 1)
+ {
+ Client client = <emphasis role="bold">new</emphasis>
Client(<emphasis role="bold">new</emphasis> URL(args[0]));
+ System.out.println("* Synchronous invocation: ");
+ client.run(<emphasis role="bold">false</emphasis>);
+ System.out.println("\n* Asynchronous invocation: ");
+ client.run(<emphasis role="bold">true</emphasis>);
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ System.out.println("Client usage:");
+ System.out.println("wsrunclient.sh -classpath client.jar
org.jboss.test.ws.jaxws.samples.dar.Client http://host:port/dar?wsdl");
+ }
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+</screen><para>The ClientHelper contains utility methods for generating
sample requests and outputting responses to the log. Here is how the client package looks
like:</para><screen xml:space="preserve">[alessio@localhost trunk]$
jar -tvf output/tests/libs/jaxws-samples-dar-client.jar
+ 0 Fri Feb 01 17:55:20 CET 2008 META-INF/
+ 106 Fri Feb 01 17:55:18 CET 2008 META-INF/MANIFEST.MF
+ 0 Thu Jan 10 21:41:02 CET 2008 org/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/
+ 3493 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Client.class
+ 4407 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/ClientHelper.class
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/
+ 1017 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/Bus.class
+ 1447 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/DarEndpoint.class
+ 1619 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/DarRequest.class
+ 1389 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/DarResponse.class
+ 1597 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/DarService.class
+ 1681 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/ObjectFactory.class
+ 1267 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/Route.class
+ 1589 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/ServiceRequest.class
+ 1210 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/Stop.class
+ 282 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/package-info.class</screen></section>
+<section
id="JBossWS-Asynchronousinvocationssample_Running_the_client"><title>Running
the client</title><para>Now you can run the client and see whether we got the
expected behavior:</para><screen xml:space="preserve">wsrunclient.sh
-classpath jaxws-samples-dar-client.jar org.jboss.test.ws.jaxws.samples.dar.Client
http://localhost.localdomain:8080/dar?wsdl
+</screen><para>As you can see from the output below, both the standard and
asynchronous invocation took some time (5 sec):</para><screen
xml:space="preserve">Synchronous invocation:
+Mon Feb 04 15:10:44 CET 2008 Sending request...
+Mon Feb 04 15:10:50 CET 2008 Response received:
org.jboss.test.ws.jaxws.samples.dar.generated.DarResponse@1389b3f
+Bus1: 778 118 734 341
+Bus0: 298 142 788 876
+
+Asynchronous invocation:
+Mon Feb 04 15:10:50 CET 2008 Sending request...
+Doing something interesting in the mean time... ;-)
+Mon Feb 04 15:10:55 CET 2008 Response received:
org.jboss.test.ws.jaxws.samples.dar.generated.DarResponse@1265109
+Bus1: 169 863
+Bus0: 951 28 244 903 226 159
+</screen><para>The use of the async invocation does not block the client and
allows it to perform something else before waiting for the result from the server. We
could have also used an AsyncHandler as showed in the <ulink
url="http://community.jboss.org/docs/DOC-13550#orgjbosstestwsjaxwssa...
simple test case</ulink>.</para><para> </para></section>
+</section>
+<section
id="JBossWS-Asynchronousinvocationssample_WSAddressing"><title>WS-Addressing</title><para>Even
if the client can do something else while the server handles the request, it would be
better if the response could be received by another instance, leaving the client
completely free go on with its business. <link
linkend="WSAddressing">WS-Addressing</link> provides means of
specifying which address the response has to be sent to. This is performed through the
<emphasis>replyTo</emphasis> property.</para><section
id="JBossWS-Asynchronousinvocationssample_Addressing_service_provider"><title>Addressing
service provider</title><para>For this reason we create a new
AddressingEndpoint:</para><screen xml:space="preserve">@Stateless
+@WebService(name = "DarEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/dar",
+ serviceName = "DarService")
+@SOAPBinding(style = SOAPBinding.Style.RPC,
+ use = SOAPBinding.Use.LITERAL)
+@SecurityDomain("JBossWS")
+@WebContext(contextRoot="/dar",
+ urlPattern="/*",
+ authMethod="BASIC",
+ transportGuarantee="NONE",
+ secureWSDLAccess=<emphasis
role="bold">false</emphasis>)
+@EndpointConfig(configName = "Standard WSAddressing Endpoint")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> DarAddressingEndpoint
+{
+ @Resource
+ <emphasis role="bold">private</emphasis> WebServiceContext ctx;
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">static</emphasis> Logger log =
Logger.getLogger(DarAddressingEndpoint.class);
+
+ @WebMethod(operationName = "process", action =
"http://org.jboss.test.ws.jaxws.samples.dar/action/processIn")
+ @Action(input =
"http://org.jboss.test.ws.jaxws.samples.dar/action/processIn", output =
"http://org.jboss.test.ws.jaxws.samples.dar/action/processOut")
+ <emphasis role="bold">public</emphasis> DarResponse
process(DarRequest request)
+ {
+ DarProcessor processor = <emphasis role="bold">new</emphasis>
DarProcessor();
+ AddressingProperties props =
(AddressingProperties)ctx.getMessageContext().get(JAXWSAConstants.SERVER_ADDRESSING_PROPERTIES_INBOUND);
+ <emphasis role="bold">if</emphasis> (props!=<emphasis
role="bold">null</emphasis> &&
props.getReplyTo()!=<emphasis role="bold">null</emphasis>)
+ {
+ System.out.println(props.getReplyTo().getAddress().getURI());
+ }
+ <emphasis role="bold">return</emphasis>
processor.process(request);
+ }
+}
+</screen><para>As you can see, we used the proper endpoint config and
specified the input and output action names. The WS-Addressing implementation write/read
the <emphasis>replyTo</emphasis> property to/from the SOAP header, thus the
<emphasis>WebServiceContext</emphasis> allows us to retrieve the
<emphasis>replyTo</emphasis> address to be used for the current
invocation.</para><para> </para></section>
+<section
id="JBossWS-Asynchronousinvocationssample_Addressing_client"><title>Addressing
client</title><para>In order to provide the right
<emphasis>replyTo</emphasis> address, the client side too needs to be
changed:</para><screen xml:space="preserve"><emphasis
role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> AddressingClient
+{
+ <emphasis role="bold">protected</emphasis> DarEndpoint
endpoint;
+
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">static</emphasis> AddressingBuilder BUILDER;
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">final</emphasis> String WSA_TO =
"http://org.jboss.test.ws.jaxws.samples.dar/server";
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">final</emphasis> String WSA_ACTION =
"http://org.jboss.test.ws.jaxws.samples.dar/action/processIn";
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">final</emphasis> String WSA_ACTION_ONEWAY =
"http://org.jboss.test.ws.jaxws.samples.dar/action/onewayProcessIn";
+
+ <emphasis role="bold">static</emphasis>
+ {
+ BUILDER = AddressingBuilder.getAddressingBuilder();
+ }
+
+ <emphasis role="bold">public</emphasis> AddressingClient(URL
url)
+ {
+ DarService service = <emphasis role="bold">new</emphasis>
DarService(url, <emphasis role="bold">new</emphasis>
QName("http://org.jboss.ws/samples/dar", "DarService"));
+ endpoint = service.getDarEndpointPort();
+ ((StubExt)endpoint).setConfigName("Standard WSAddressing Client");
+ ClientHelper.setUsernamePassword((BindingProvider)endpoint, "kermit",
"thefrog");
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> run(<emphasis
role="bold">boolean</emphasis> asynch) <emphasis
role="bold">throws</emphasis> Exception
+ {
+ configureAddressingProperties((BindingProvider)endpoint, WSA_ACTION, WSA_TO,
"http://localhost:8080/dar-client/replyTo");
+ DarRequest request = ClientHelper.getRequest();
+ System.out.println(<emphasis role="bold">new</emphasis>
Date() + " Sending request...");
+ <emphasis role="bold">if</emphasis> (asynch)
+ {
+ Response<DarResponse> resp = endpoint.processAsync(request);
+ System.out.println("Doing something interesting in the mean time... ;-)
");
+ resp.get();
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ endpoint.process(request);
+ }
+ //don't care about the response: it is null since the real one went to the
replyTo address
+ System.out.println(<emphasis role="bold">new</emphasis>
Date() + " Done.");
+ }
+
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">void</emphasis>
configureAddressingProperties(BindingProvider bp, String wsaAction, String wsaTo, String
replyTo) <emphasis role="bold">throws</emphasis> URISyntaxException
+ {
+ AddressingProperties requestProps =
AddressingClientUtil.createDefaultProps(wsaAction, wsaTo);
+ AttributedURI messageId = AddressingClientUtil.createMessageID();
+ System.out.println("Sent message ID: " + messageId.getURI());
+ requestProps.setMessageID(messageId);
+ requestProps.setReplyTo(BUILDER.newEndpointReference(<emphasis
role="bold">new</emphasis> URI(replyTo)));
+ bp.getRequestContext().put(JAXWSAConstants.CLIENT_ADDRESSING_PROPERTIES_OUTBOUND,
requestProps);
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">void</emphasis> main(String[] args)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ <emphasis role="bold">if</emphasis> (args.length == 1)
+ {
+ AddressingClient client = <emphasis
role="bold">new</emphasis> AddressingClient(<emphasis
role="bold">new</emphasis> URL(args[0]));
+ System.out.println("* Synchronous invocation: ");
+ client.run(<emphasis role="bold">false</emphasis>);
+ System.out.println("\n* Asynchronous invocation: ");
+ client.run(<emphasis role="bold">true</emphasis>);
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ System.out.println("AddressingClient usage:");
+ System.out.println("wsrunclient.sh -classpath AddressingClient.jar
org.jboss.test.ws.jaxws.samples.dar.AddressingClient http://host:port/dar?wsdl");
+ }
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+</screen><para>You can see in the
<emphasis>configureAddressingProperties(...)</emphasis> method how the
WS-Addressing properties are configured. The <emphasis>Standard WSAddressing
Client</emphasis> client config needs also to be specified so that the WS-Addressing
stack extension is used.</para><para> </para></section>
+<section
id="JBossWS-Asynchronousinvocationssample_The_reply_sink"><title>The
reply sink</title><para>Thanks to the WS-Addressing implementation, the server
will automatically send the response to the specified address. Of course we need something
to receive it; for ease here we have a simple servlet dumping everything to the
logs:</para><screen xml:space="preserve"><emphasis
role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> ReplyToServlet <emphasis
role="bold">extends</emphasis> HttpServlet {
+
+ <emphasis role="bold">protected</emphasis> <emphasis
role="bold">void</emphasis> doGet(HttpServletRequest
httpServletRequest, HttpServletResponse httpServletResponse) <emphasis
role="bold">throws</emphasis> ServletException, IOException {
+ dump(httpServletRequest, httpServletResponse);
+ }
+
+ <emphasis role="bold">protected</emphasis> <emphasis
role="bold">void</emphasis> doPost(HttpServletRequest
httpServletRequest, HttpServletResponse httpServletResponse) <emphasis
role="bold">throws</emphasis> ServletException, IOException {
+ dump(httpServletRequest, httpServletResponse);
+ }
+
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">void</emphasis> dump(HttpServletRequest httpServletRequest,
HttpServletResponse httpServletResponse) {
+ System.out.println("ReplyTo sink:");
+
+ <emphasis role="bold">try</emphasis> {
+ BufferedReader reader = httpServletRequest.getReader();
+ String inputLine;
+
+ <emphasis role="bold">while</emphasis> ((inputLine =
reader.readLine()) != <emphasis role="bold">null</emphasis>) {
+ System.out.println(inputLine);
+ }
+ reader.close();
+ } <emphasis role="bold">catch</emphasis> (IOException e) {
+ e.printStackTrace();
+ }
+
+ httpServletResponse.setStatus(200);
+ }
+}
+</screen><para> </para></section>
+<section
id="JBossWS-Asynchronousinvocationssample_Oneway_invocations"><title>Oneway
invocations</title><para>Having splitted the client is actually not enough.
The reason is that even if the response is not received by the
<emphasis>AddressingClient</emphasis>, with the current JBossWS stack
implementation, the underlying connection between the ws consumer and provider is
nevertheless closed once the latter has sent the response to the
<emphasis>ReplyToServlet</emphasis> and this is a resource waste. Moreover, on
the server side, since a new thread is spanned for each invocation, the long running
process could cause the system to reach the max number of thread/http connections allowed
at the same time.</para><para>For this reason, we split the service too. A
oneway invocation is performed, then on the server side the collected requests are stored
into a queue. A message driven bean consumes the queue, performs the long running
optimization and finally replies to the addres!
s the client specified. The following paragraphs go deeper into the
details.</para><para> </para><section
id="JBossWS-Asynchronousinvocationssample_Response_service_implementation"><title>Response
service implementation</title><para>To get what has just been summarized, the
server has to send messages whose schema has to be somewhere declared: we'll use a
top-down development strategy. Here is the hand-coded reply service wsdl
contract:</para><screen xml:space="preserve"><definitions
name="DarReplyService" targetNamespace="<ulink
url="http://org.jboss.ws/samples/dar">http://org.jboss.ws/samples/dar</ulink>"
xmlns="<ulink
url="http://schemas.xmlsoap.org/wsdl/">http://schemas.xmlsoa...
xmlns:soap="<ulink
url="http://schemas.xmlsoap.org/wsdl/soap/">http://schemas.x...
xmlns:tns="<ulink
url="http://org.jboss.ws/samples/dar">http://org.jboss.ws/samples/dar</ulink>"
xmlns:xsd="<ulink url="http://www.w3.org/2001/XMLSchema">http://www!
.w3.org/2001/XMLSchema</ulink>"><types>
+ <xs:schema targetNamespace="<ulink
url="http://org.jboss.ws/samples/dar">http://org.jboss.ws/samples/dar</ulink>"
version="1.0" xmlns:tns="<ulink
url="http://org.jboss.ws/samples/dar">http://org.jboss.ws/samples/dar</ulink>"
xmlns:xs="<ulink
url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/200...
+ <xs:complexType name="serviceRequest">
+ <xs:sequence>
+ <xs:element minOccurs="0" name="from"
type="tns:stop"/>
+ <xs:element minOccurs="0" name="id"
type="xs:string"/>
+ <xs:element name="people" type="xs:int"/>
+ <xs:element minOccurs="0" name="to"
type="tns:stop"/>
+ </xs:sequence>
+ </xs:complexType>
+ <xs:complexType name="stop">
+ <xs:sequence>
+ <xs:element minOccurs="0" name="node"
type="xs:int"/>
+ <xs:element minOccurs="0" name="time"
type="xs:dateTime"/>
+ </xs:sequence>
+ </xs:complexType>
+ <xs:complexType name="darResponse">
+ <xs:sequence>
+ <xs:element maxOccurs="unbounded" minOccurs="0"
name="routes" nillable="true" type="tns:route"/>
+ <xs:element maxOccurs="unbounded" minOccurs="0"
name="unservedRequests" nillable="true"
type="tns:serviceRequest"/>
+ </xs:sequence>
+ </xs:complexType>
+ <xs:complexType name="route">
+ <xs:sequence>
+ <xs:element minOccurs="0" name="busId"
type="xs:string"/>
+ <xs:element maxOccurs="unbounded" minOccurs="0"
name="stops" nillable="true" type="tns:stop"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:schema></types><message
name="DarReplyEndpoint_receive">
+ <part name="arg0"
type="tns:darResponse"/></message><portType
name="DarReplyEndpoint">
+ <operation name="receive">
+ <input message="tns:DarReplyEndpoint_receive"/>
+ </operation></portType><binding
name="DarReplyEndpointBinding" type="tns:DarReplyEndpoint">
+ <soap:binding style="rpc" transport="<ulink
url="http://schemas.xmlsoap.org/soap/http">http://schemas.xm...
+ <operation name="receive">
+ <soap:operation soapAction="<ulink
url="http://org.jboss.test.ws.jaxws.samples.dar/action/receiveIn">http://org.jboss.test.ws.jaxws.samples.dar/action/receiveIn</ulink>"/>
+ <input>
+ <soap:body namespace="<ulink
url="http://org.jboss.ws/samples/dar">http://org.jboss.ws/samples/dar</ulink>"
use="literal"/>
+ </input>
+ </operation></binding><service
name="DarReplyService">
+ <port binding="tns:DarReplyEndpointBinding"
name="DarReplyEndpointPort">
+ <soap:address location="<ulink
url="http://localhost.localdomain:8080/dar-client/replyService">http://localhost.localdomain:8080/dar-client/replyService</ulink>"/>
+ </port></service>
+</definitions>
+</screen><para>The optimization system acts as a client here: it owns the
schema and gets the interface through the wsconsume script:</para><screen
xml:space="preserve">wsconsume.sh -k -p
org.jboss.test.ws.jaxws.samples.dar.generated.reply reply.wsdl
+</screen><para>The transportation companies play the server role instead,
thus they implement the generated endpoint interface:</para><screen
xml:space="preserve">@WebService(name = "DarReplyEndpoint",
targetNamespace = "http://org.jboss.ws/samples/dar")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">interface</emphasis> DarReplyEndpoint {
+
+
+ /**
+ *
+ * @param arg0
+ */
+ @WebMethod(action =
"http://org.jboss.test.ws.jaxws.samples.dar/action/receiveIn")
+ @Oneway
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> receive(
+ @WebParam(name = "arg0", partName = "arg0")
+ DarResponse arg0);
+
+}
+</screen><para>Here is the endpoint implementation: as for the request
service, the addressing configuration is specified as well as the action for the oneway
operation.</para><screen xml:space="preserve">@WebService(name =
"DarReplyEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/dar",
+ endpointInterface =
"org.jboss.test.ws.jaxws.samples.dar.generated.reply.DarReplyEndpoint",
+ wsdlLocation = "/WEB-INF/wsdl/reply.wsdl",
+ serviceName = "DarReplyService")
+@SOAPBinding(style = Style.RPC,
+ use = Use.LITERAL)
+@EndpointConfig(configName = "Standard WSAddressing Endpoint")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> DarReplyEndpointImpl <emphasis
role="bold">implements</emphasis> DarReplyEndpoint
+{
+ @Resource
+ <emphasis role="bold">private</emphasis> WebServiceContext ctx;
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">static</emphasis> Logger log =
Logger.getLogger(DarReplyEndpointImpl.class);
+
+ @WebMethod(action =
"http://org.jboss.test.ws.jaxws.samples.dar/action/receiveIn")
+ @Oneway
+ @Action(input =
"http://org.jboss.test.ws.jaxws.samples.dar/action/receiveIn")
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> receive(DarResponse arg0)
+ {
+ AddressingProperties props =
(AddressingProperties)ctx.getMessageContext().get(JAXWSAConstants.SERVER_ADDRESSING_PROPERTIES_INBOUND);
+ log.info("Result received; relationship message id: " +
props.getRelatesTo()[0].getID());
+ List<Route> routes = arg0.getRoutes();
+ <emphasis role="bold">for</emphasis> (Route route : routes)
+ {
+ log.info(route.getBusId() + ": ");
+ StringBuilder sb = <emphasis role="bold">new</emphasis>
StringBuilder();
+ <emphasis role="bold">for</emphasis> (Stop stop :
route.getStops())
+ {
+ sb.append(stop.getNode() + " ");
+ }
+ log.info(sb.toString());
+ }
+ }
+}
+</screen></section>
+<section
id="JBossWS-Asynchronousinvocationssample_Request_service_improvements"><title>Request
service improvements</title><para>Finally the request service endpoint needs a
new oneway operation method:</para><screen xml:space="preserve">
@WebMethod(operationName = "onewayProcess", action =
"http://org.jboss.test.ws.jaxws.samples.dar/action/onewayProcessIn")
+ @Action(input =
"http://org.jboss.test.ws.jaxws.samples.dar/action/onewayProcessIn")
+ @Oneway
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> onewayProcess(DarRequest request)
+ {
+ QueueSession queueSession =<emphasis
role="bold">null</emphasis>;
+ QueueSender sender = <emphasis role="bold">null</emphasis>;
+ <emphasis role="bold">try</emphasis> {
+ InitialContext context = <emphasis
role="bold">new</emphasis> InitialContext();
+ QueueConnectionFactory connectionFactory =
(QueueConnectionFactory)context.lookup("ConnectionFactory");
+ QueueConnection con = connectionFactory.createQueueConnection();
+ queueSession = con.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
+ Queue queue = (Queue)context.lookup("queue/DarQueue");
+ sender = queueSession.createSender(queue);
+ AsyncProcessRequest asyncRequest = <emphasis
role="bold">new</emphasis> AsyncProcessRequest();
+ asyncRequest.setRequest(request);
+ AddressingProperties props =
(AddressingProperties)ctx.getMessageContext().get(JAXWSAConstants.SERVER_ADDRESSING_PROPERTIES_INBOUND);
+ asyncRequest.setReplyTo(props.getReplyTo().getAddress().getURI());
+ asyncRequest.setMessageId(props.getMessageID().getURI());
+ ObjectMessage message = queueSession.createObjectMessage(asyncRequest);
+ sender.send(message);
+ log.info("AsyncProcessRequest sent...");
+ } <emphasis role="bold">catch</emphasis> (Exception e) {
+ <emphasis role="bold">throw</emphasis> <emphasis
role="bold">new</emphasis> WebServiceException(e);
+ } <emphasis role="bold">finally</emphasis> {
+ <emphasis role="bold">try</emphasis>
+ {
+ sender.close();
+ }
+ <emphasis role="bold">catch</emphasis>(Exception e1) {}
+ <emphasis role="bold">try</emphasis>
+ {
+ queueSession.close();
+ }
+ <emphasis role="bold">catch</emphasis>(Exception e1) {}
+ }
+
+ }
+</screen><para>As you can see this does a lookup of the local
<emphasis>queue/DarQueue</emphasis> and sends a custom
<emphasis>AsyncProcessRequest</emphasis> pojo. This way the invocation is
served and the endpoint thread is ready to receive another
request.</para><para>The afore-mentioned queue is consumed by the following
Message Driven bean:</para><screen
xml:space="preserve">@MessageDriven( name="DarListener",
activationConfig= {
+
@ActivationConfigProperty(propertyName="destinationType",propertyValue="javax.jms.Queue"),
+
@ActivationConfigProperty(propertyName="destination",propertyValue="queue/DarQueue")}
+)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> DarMessageBean <emphasis
role="bold">implements</emphasis> MessageListener
+{
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">static</emphasis> Logger log =
Logger.getLogger(DarMessageBean.class);
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">final</emphasis> String WSA_ACTION =
"http://org.jboss.test.ws.jaxws.samples.dar/action/receiveIn";
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> onMessage(Message arg0)
+ {
+ <emphasis role="bold">try</emphasis> {
+ ObjectMessage message = (ObjectMessage)arg0;
+ AsyncProcessRequest asyncRequest = (AsyncProcessRequest)message.getObject();
+ DarProcessor processor = <emphasis
role="bold">new</emphasis> DarProcessor();
+ DarResponse response = processor.process(asyncRequest.getRequest());
+
+ //convert the response and send it to the client reply service
+ org.jboss.test.ws.jaxws.samples.dar.generated.reply.DarResponse darResponse =
ReplyConverter.convertResponse(response);
+ String replyTo = asyncRequest.getReplyTo().toURL().toString();
+ log.info("Response will be sent to: " + replyTo);
+ QName serviceName = <emphasis role="bold">new</emphasis>
QName("http://org.jboss.ws/samples/dar", "DarReplyService");
+ Service service = Service.create(<emphasis
role="bold">new</emphasis> URL(replyTo + "?wsdl"),
serviceName);
+ DarReplyEndpoint endpoint =
(DarReplyEndpoint)service.getPort(DarReplyEndpoint.class);
+
+ //setup addressing configuration and properties
+ ((StubExt)endpoint).setConfigName("Standard WSAddressing Client");
+
((BindingProvider)endpoint).getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
replyTo);
+ AddressingProperties requestProps =
AddressingClientUtil.createOneWayProps(WSA_ACTION, replyTo);
+ requestProps.setMessageID(AddressingClientUtil.createMessageID());
+ Relationship[] relationships = <emphasis
role="bold">new</emphasis> Relationship[1];
+ relationships[0] = <emphasis role="bold">new</emphasis>
RelationshipImpl(asyncRequest.getMessageId());
+ requestProps.setRelatesTo(relationships);
+
((BindingProvider)endpoint).getRequestContext().put(JAXWSAConstants.CLIENT_ADDRESSING_PROPERTIES_OUTBOUND,
requestProps);
+
+ endpoint.receive(darResponse);
+ log.info("Response sent.");
+ } <emphasis role="bold">catch</emphasis> (Exception e) {
+ e.printStackTrace();
+ }
+ }
+}
+</screen><para>This basically delegates to the DarProcessor then invokes the
transportation company endpoint. Please note
that:</para><itemizedlist><listitem><para> the
<emphasis>Standard WSAddressing Client</emphasis> configuration is used so
that reply message ID can be associated to the request message ID; this allows the
transportation company to to link requests and responses;
</para></listitem><listitem><para> the endpoint address is of
course set at runtime according to the <emphasis>replyTo</emphasis> addressing
property found in the request message;
</para></listitem><listitem><para> a stupid
<emphasis>ReplyConverter</emphasis> is used since the classes generated from
the hand-coded wsdl contract differ from the server model
ones.</para></listitem></itemizedlist><para> </para></section>
+<section
id="JBossWS-Asynchronousinvocationssample_Addressing_client_changes"><title>Addressing
client changes</title><para>On the transportation company side, we have a new
<emphasis>AddressingClient</emphasis>'s method for the oneway request
service invocation:</para><screen xml:space="preserve"><emphasis
role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> runOneway() <emphasis
role="bold">throws</emphasis> Exception
+ {
+ configureAddressingProperties((BindingProvider)endpoint, WSA_ACTION_ONEWAY, WSA_TO,
"http://localhost:8080/dar-client/replyService");
+ DarRequest request = ClientHelper.getRequest();
+ System.out.println(<emphasis role="bold">new</emphasis>
Date() + " Sending request...");
+ endpoint.onewayProcess(request);
+ System.out.println(<emphasis role="bold">new</emphasis>
Date() + " Done.");
+ }
+</screen><screen xml:space="preserve"><emphasis
role="bold">public</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">void</emphasis> main(String[] args)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ <emphasis role="bold">if</emphasis> (args.length == 1)
+ {
+ AddressingClient client = <emphasis
role="bold">new</emphasis> AddressingClient(<emphasis
role="bold">new</emphasis> URL(args[0]));
+ System.out.println("* Synchronous invocation: ");
+ client.run(<emphasis role="bold">false</emphasis>);
+ System.out.println("\n* Asynchronous invocation: ");
+ client.run(<emphasis role="bold">true</emphasis>);
+ System.out.println("\n* Oneway invocation: ");
+ client.runOneway();
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ System.out.println("AddressingClient usage:");
+ System.out.println("wsrunclient.sh -classpath AddressingClient.jar
org.jboss.test.ws.jaxws.samples.dar.AddressingClient http://host:port/dar?wsdl");
+ }
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+</screen></section>
+<section
id="JBossWS-Asynchronousinvocationssample_Running_the_sample"><title>Running
the sample</title><para>Before trying the new addressing version of this
sample, please take a look at the three archives you'll use. The
<emphasis>jaxws-samples-dar-addressing.jar</emphasis> contains the
optimization system:</para><screen
xml:space="preserve">[alessio@localhost trunk]$ jar -tvf
output/tests/libs/jaxws-samples-dar-addressing.jar
+ 0 Fri Feb 01 17:55:20 CET 2008 META-INF/
+ 106 Fri Feb 01 17:55:18 CET 2008 META-INF/MANIFEST.MF
+ 0 Thu Jan 10 21:41:02 CET 2008 org/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/
+ 1175 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/AsyncProcessRequest.class
+ 789 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Bus.class
+ 5258 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/DarAddressingEndpoint.class
+ 4751 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/DarMessageBean.class
+ 4231 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/DarProcessor.class
+ 1585 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarRequest.class
+ 1340 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/DarResponse.class
+ 3747 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/ReplyConverter.class
+ 1085 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Route.class
+ 1314 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/ServiceRequest.class
+ 834 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Stop.class
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/reply/
+ 847 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/reply/DarReplyEndpoint.class
+ 1680 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/reply/DarReplyService.class
+ 1425 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/reply/DarResponse.class
+ 1336 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/reply/ObjectFactory.class
+ 1291 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/reply/Route.class
+ 1619 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/reply/ServiceRequest.class
+ 1222 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/reply/Stop.class
+ 288 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/reply/package-info.class
+</screen><para>The
<emphasis>jaxws-samples-dat-addressing-client.jar</emphasis> is the first
(request) part of the transportation companies software:</para><screen
xml:space="preserve">[alessio@localhost trunk]$ jar -tvf
output/tests/libs/jaxws-samples-dar-addressing-client.jar
+ 0 Fri Feb 01 17:55:20 CET 2008 META-INF/
+ 106 Fri Feb 01 17:55:18 CET 2008 META-INF/MANIFEST.MF
+ 0 Thu Jan 10 21:41:02 CET 2008 org/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/
+ 5859 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/AddressingClient.class
+ 4407 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/ClientHelper.class
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/
+ 1017 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/Bus.class
+ 1447 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/DarEndpoint.class
+ 1619 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/DarRequest.class
+ 1389 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/DarResponse.class
+ 1597 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/DarService.class
+ 1681 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/ObjectFactory.class
+ 1267 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/Route.class
+ 1589 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/ServiceRequest.class
+ 1210 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/Stop.class
+ 282 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/generated/package-info.class
+</screen><para>Finally, the
<emphasis>jaxws-samples-dar-addressing-client.war</emphasis> is the second
(response) part of the transportation company, including both the sink servlet and the
DarReplyEndpointImpl for response receipt:</para><screen
xml:space="preserve">[alessio@localhost trunk]$ jar -tvf
output/tests/libs/jaxws-samples-dar-addressing-client.war
+ 0 Fri Feb 01 17:55:20 CET 2008 META-INF/
+ 106 Fri Feb 01 17:55:18 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 01 17:55:20 CET 2008 WEB-INF/
+ 941 Thu Jan 31 16:07:30 CET 2008 WEB-INF/web.xml
+ 0 Fri Feb 01 17:55:20 CET 2008 WEB-INF/classes/
+ 0 Thu Jan 10 21:41:02 CET 2008 WEB-INF/classes/org/
+ 0 Thu Jan 10 21:07:24 CET 2008 WEB-INF/classes/org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 WEB-INF/classes/org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 WEB-INF/classes/org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/
+ 3850 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/DarReplyEndpointImpl.class
+ 1612 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/ReplyToServlet.class
+ 0 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/
+ 0 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/
+ 847 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/DarReplyEndpoint.class
+ 1680 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/DarReplyService.class
+ 1425 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/DarResponse.class
+ 1336 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/ObjectFactory.class
+ 1291 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/Route.class
+ 1619 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/ServiceRequest.class
+ 1222 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/Stop.class
+ 288 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/package-info.class
+ 228 Wed Jan 30 00:44:14 CET 2008 WEB-INF/jboss-web.xml
+ 0 Thu Jan 31 16:07:30 CET 2008 WEB-INF/wsdl/
+ 2457 Thu Jan 31 16:07:30 CET 2008 WEB-INF/wsdl/reply.wsdl
+</screen><para>You have to deploy both the
<emphasis>jaxws-samples-dar-addressing.jar</emphasis> and the
<emphasis>jaxws-samples-dar-addressing-client.war</emphasis>; for ease we run
the transportation company receipt system on the same host of the optimization system, of
course you can play with the addresses and simulate a real world architecture using two
hosts. Then we run the request service client...</para><screen
xml:space="preserve">wsrunclient.sh -classpath
jaxws-samples-dar-addressing-client.jar
org.jboss.test.ws.jaxws.samples.dar.AddressingClient
http://localhost.localdomain:8080/dar?wsdl
+</screen><para>...and verify the obtained behavior checking the log on the
client side:</para><screen xml:space="preserve">* Synchronous
invocation:
+Sent message ID: urn:uuid:321dee7b-953c-4405-9b06-dbc6743d36e6
+Tue Feb 05 11:31:37 CET 2008 Sending request...
+[Fatal Error] :-1:-1: Premature end of file.
+Tue Feb 05 11:31:42 CET 2008 Done.
+
+* Asynchronous invocation:
+Sent message ID: urn:uuid:b9076402-f52-4aca-9e5b-b6e80cf1c3e2
+Tue Feb 05 11:31:42 CET 2008 Sending request...
+Doing something interesting in the mean time... ;-)
+[Fatal Error] :-1:-1: Premature end of file.
+Tue Feb 05 11:31:47 CET 2008 Done.
+
+* Oneway invocation:
+Sent message ID: urn:uuid:cc5d90d1-d95-450d-a0cc-3a025f49d6c3
+Tue Feb 05 11:31:47 CET 2008 Sending request...
+Tue Feb 05 11:31:47 CET 2008 Done.
+</screen><para>... and on the server side:</para><screen
xml:space="preserve">11:31:37,218 INFO [STDOUT]
http://localhost:8080/dar-client/replyTo
+11:31:37,218 INFO [DarProcessor] Processing DAR request...
org.jboss.test.ws.jaxws.samples.dar.DarRequest@1c2cbee
+11:31:37,218 INFO [DarProcessor] 1 person(s) from 582 to 662
+11:31:37,218 INFO [DarProcessor] 2 person(s) from 260 to 962
+11:31:37,218 INFO [DarProcessor] 1 person(s) from 10 to 959
+11:31:37,218 INFO [DarProcessor] 3 person(s) from 138 to 722
+11:31:42,219 INFO [DarProcessor] Done
org.jboss.test.ws.jaxws.samples.dar.DarRequest@1c2cbee
+11:31:42,311 INFO [STDOUT] ReplyTo sink:
+11:31:42,314 INFO [STDOUT] <env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:wsa='http://www.w3.org/2005/08/addressing'><w...
xmlns:ns1='http://org.jboss.ws/samples/dar'><return><routes><busId>Bus1</busId></routes><routes><busId>Bus0</busId><stops><node>582</node><time>2008-02-05T11:31:36.443+01:00</time></stops><stops><node>662</node><time>2008-02-05T11:31:36.443+01:00</time></stops><stops><node>260</node><time>2008-02-05T11:31:36.444+01:00</time></stops><stops><node!
>962</node><time>2008-02-05T11:31:36.444+01:00</time></stops><stops><node>10</node><time>2008-02-05T11:31:36.444+01:00</time></stops><stops><node>959</node><time>2008-02-05T11:31:36.444+01:00</time></stops><stops><node>138</node><time>2008-02-05T11:31:36.444+01:00</time></stops><stops><node>722</node><time>2008-02-05T11:31:36.444+01:00</time></stops></routes><unservedRequests><from><node>425</node><time>2008-02-05T11:31:36.443+01:00</time></from><id>Req0</id><people>2</people><to><node>920</node><time>2008-02-05T11:31:36.443+01:00</time></to></unservedRequests></return></ns1:processResponse></env:Body></env:Envelope>
+
+11:31:42,362 INFO [STDOUT] http://localhost:8080/dar-client/replyTo
+11:31:42,362 INFO [DarProcessor] Processing DAR request...
org.jboss.test.ws.jaxws.samples.dar.DarRequest@807653
+11:31:42,362 INFO [DarProcessor] 3 person(s) from 89 to 328
+11:31:42,362 INFO [DarProcessor] 1 person(s) from 293 to 743
+11:31:42,362 INFO [DarProcessor] 3 person(s) from 651 to 371
+11:31:42,362 INFO [DarProcessor] 2 person(s) from 283 to 326
+11:31:47,363 INFO [DarProcessor] Done
org.jboss.test.ws.jaxws.samples.dar.DarRequest@807653
+11:31:47,374 INFO [STDOUT] ReplyTo sink:
+11:31:47,374 INFO [STDOUT] <env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:wsa='http://www.w3.org/2005/08/addressing'><w...
xmlns:ns1='http://org.jboss.ws/samples/dar'><return><routes><busId>Bus1</busId><stops><node>283</node><time>2008-02-05T11:31:42.341+01:00</time></stops><stops><node>326</node><time>2008-02-05T11:31:42.341+01:00</time></stops></routes><routes><busId>Bus0</busId><stops><node>89</node><time>2008-02-05T11:31:42.341+01:00</time></stops><stops><node&g!
t;328</node><time>2008-02-05T11:31:42.341+01:00</time></stops><stops><node>293</node><time>2008-02-05T11:31:42.341+01:00</time></stops><stops><node>743</node><time>2008-02-05T11:31:42.341+01:00</time></stops><stops><node>651</node><time>2008-02-05T11:31:42.341+01:00</time></stops><stops><node>371</node><time>2008-02-05T11:31:42.341+01:00</time></stops></routes><unservedRequests><from><node>205</node><time>2008-02-05T11:31:42.341+01:00</time></from><id>Req0</id><people>1</people><to><node>630</node><time>2008-02-05T11:31:42.341+01:00</time></to></unservedRequests></return></ns1:processResponse></env:Body></env:Envelope>
+
+11:31:47,527 INFO [DarAddressingEndpoint] AsyncProcessRequest sent...
+11:31:47,538 INFO [DarProcessor] Processing DAR request...
org.jboss.test.ws.jaxws.samples.dar.DarRequest@149f848
+11:31:47,538 INFO [DarProcessor] 1 person(s) from 209 to 184
+11:31:47,538 INFO [DarProcessor] 2 person(s) from 167 to 524
+11:31:47,538 INFO [DarProcessor] 2 person(s) from 805 to 883
+11:31:47,538 INFO [DarProcessor] 1 person(s) from 101 to 224
+11:31:52,539 INFO [DarProcessor] Done
org.jboss.test.ws.jaxws.samples.dar.DarRequest@149f848
+11:31:52,549 INFO [DarMessageBean] Response will be sent to:
http://localhost:8080/dar-client/replyService
+11:31:52,887 INFO [DarReplyEndpointImpl] Result received; relationship message id:
urn:uuid:cc5d90d1-d95-450d-a0cc-3a025f49d6c3
+11:31:52,888 INFO [DarReplyEndpointImpl] Bus1:
+11:31:52,888 INFO [DarReplyEndpointImpl] 209 184 101 224
+11:31:52,888 INFO [DarReplyEndpointImpl] Bus0:
+11:31:52,888 INFO [DarReplyEndpointImpl] 167 524 805 883
+11:31:52,890 INFO [DarMessageBean] Response sent.
+</screen><para>As you can see in the first and second invocations, simply
having added the use of the addressing <emphasis>replyTo</emphasis> properties
cause the response to be received from the sink servlet on the server side; however the
client nevertheless hangs until the response is produced and
sent.</para><para>The third run, using the couple of oneway invocations, shows
how the client is free almost immediately after the request has been sent; the response is
received through the <emphasis>DarReplyEndpointImpl</emphasis> 5 seconds
later. For this reason the latter solution proves to be the best one, even if it requires
more development.</para><para> </para></section>
+</section>
+</section>
+<section
id="JBossWS-Asynchronousinvocationssample_JMS_Endpoint"><title>JMS
Endpoint</title><para>The JBossWS stack also allows you to obtain a JMS
endpoint exposing message driven beans as web services. This gives us another way of
performing the asynchronous invocation required for the DaR
sample.</para><para> </para><section
id="JBossWS-Asynchronousinvocationssample_The_service_endpoint"><title>The
service endpoint</title><para>We use a bottom-up approach, thus we start
coding an EJB3 message driven bean that extends
<emphasis>org.jboss.ws.core.transport.jms.JMSTransportSupportEJB3</emphasis>;
to make it a web service endpoint we use the usual annotations (@WebService, @WebMethod,
etc.). Please note that even if we didn't do this here, you can fine tune the message
consumption configuration like for any other message driven bean.</para><screen
xml:space="preserve">@WebService (name = "DarEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/dar",
+ serviceName = "DarService")
+@WebContext(contextRoot="/dar")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+@MessageDriven(activationConfig = {
+ @ActivationConfigProperty(propertyName = "destinationType", propertyValue
= "javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName = "destination", propertyValue =
"queue/DarRequestQueue")
+ },
+ messageListenerInterface = javax.jms.MessageListener.class
+)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> DarJMSEndpoint <emphasis
role="bold">extends</emphasis> JMSTransportSupportEJB3
+{
+
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">final</emphasis> Logger log =
Logger.getLogger(DarJMSEndpoint.class);
+
+ @WebMethod(operationName = "process", action =
"http://org.jboss.test.ws.jaxws.samples.dar/action/processIn")
+ <emphasis role="bold">public</emphasis> DarResponse
process(DarRequest request)
+ {
+ DarProcessor processor = <emphasis role="bold">new</emphasis>
DarProcessor();
+ <emphasis role="bold">return</emphasis>
processor.process(request);
+ }
+
+ @Override
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> onMessage(Message message)
+ {
+ log.debug("onMessage: " + message);
+ super.onMessage(message);
+ }
+}
+</screen><para>Once this simple endpoint is ready, you can build the project
and take a look at the generated archive:</para><screen
xml:space="preserve">[alessio@localhost trunk]$ jar -tvf
output/tests/libs/jaxws-samples-dar-jms.jar
+ 0 Fri Feb 01 17:55:20 CET 2008 META-INF/
+ 106 Fri Feb 01 17:55:18 CET 2008 META-INF/MANIFEST.MF
+ 0 Thu Jan 10 21:41:02 CET 2008 org/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/
+ 789 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Bus.class
+ 2318 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/DarJMSEndpoint.class
+ 4231 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/DarProcessor.class
+ 1585 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarRequest.class
+ 1340 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/DarResponse.class
+ 1085 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Route.class
+ 1314 Fri Feb 01 17:55:08 CET 2008
org/jboss/test/ws/jaxws/samples/dar/ServiceRequest.class
+ 834 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Stop.class
+</screen><para>Nothing special, the JMS endpoint and the DaR model classes.
The JBossWS stack automatically generates the wsdl contract at deploy time and publishes
it for http use. We are however going to use this endpoint through
JMS...</para><para> </para></section>
+<section
id="JBossWS-Asynchronousinvocationssample_The_service_client"><title>The
service client</title><para>The JMS client could be everything able to write
to a JMS queue (here <emphasis>queue/DarRequestQueue</emphasis> on the server
running the endpoint described above). In this sample the client is obtained through a
simple servlet:</para><screen xml:space="preserve"><emphasis
role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> JMSClient <emphasis
role="bold">extends</emphasis> HttpServlet
+{
+ <emphasis role="bold">private</emphasis> Logger log =
Logger.getLogger(JMSClient.class);
+
+ <emphasis role="bold">protected</emphasis> <emphasis
role="bold">void</emphasis> doGet(HttpServletRequest
httpServletRequest, HttpServletResponse httpServletResponse) <emphasis
role="bold">throws</emphasis> ServletException, IOException {
+ runMessageClient(<emphasis role="bold">new</emphasis>
PrintStream(httpServletResponse.getOutputStream()));
+ }
+
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">void</emphasis> runMessageClient(PrintStream ps)
+ {
+ String reqMessage = "<env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>" +
+ "<env:Header></env:Header>" +
+ "<env:Body>" +
+ "<ns1:process
xmlns:ns1='http://org.jboss.ws/samples/dar'>" +
+ ...
+ "</ns1:process>" +
+ "</env:Body>" +
+ "</env:Envelope>";
+
+ QueueConnection con = <emphasis role="bold">null</emphasis>;
+ QueueSession session = <emphasis
role="bold">null</emphasis>;
+ <emphasis role="bold">try</emphasis>
+ {
+ InitialContext context = <emphasis
role="bold">new</emphasis> InitialContext();
+ QueueConnectionFactory connectionFactory =
(QueueConnectionFactory)context.lookup("ConnectionFactory");
+ Queue reqQueue = (Queue)context.lookup("queue/DarRequestQueue");
+ con = connectionFactory.createQueueConnection();
+ session = con.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
+ Queue resQueue = (Queue)context.lookup("queue/DarResponseQueue");
+ con.start();
+ TextMessage message = session.createTextMessage(reqMessage);
+ message.setJMSReplyTo(resQueue);
+ QueueSender sender = session.createSender(reqQueue);
+ sender.send(message);
+ sender.close();
+ ps.println("Request message sent, doing something interesting in the mean
time... ;-) ");
+ con.stop();
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace(ps);
+ }
+ <emphasis role="bold">finally</emphasis>
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ session.close();
+ }
+ <emphasis role="bold">catch</emphasis>(Exception e1) {}
+ <emphasis role="bold">try</emphasis>
+ {
+ con.close();
+ }
+ <emphasis role="bold">catch</emphasis>(Exception e1) {}
+ }
+ }
+
+
+ <emphasis role="bold">protected</emphasis> <emphasis
role="bold">void</emphasis> doPost(HttpServletRequest
httpServletRequest, HttpServletResponse httpServletResponse) <emphasis
role="bold">throws</emphasis> ServletException, IOException {
+ doGet(httpServletRequest,httpServletResponse);
+ }
+}
+</screen><para>The reason for using a servlet here instead of a standalone
java application we could launch through wsrunclient, is that running in the container
makes the queue connection factory lookup much easier. Of course you can do this in
another way.</para><para> </para><para>As you can see, the client
specifies the response queue where the server has to reply,
<emphasis>queue/DarResponseQueue</emphasis>, thus we'll need to define a
message listener to get the responses from
it.</para><para> </para><para>To invoke the JMS endpoint, we could
have of course done like <ulink
url="http://community.jboss.org/docs/DOC-13972#JMS_Transport_Clients... is
shown in the JAX-WS guide</ulink>: manually add a port binding with a jms
soap:address to the wsdl contract and invoke the endpoint as we would do for standard http
invocations. This however is useless in cases like ours, since the invocation fails if the
reply doesn't come within a short time period and the client hang!
s until the the response arrives or the timeout expires. So let's define our message
listener:</para><screen
xml:space="preserve">@MessageDriven(activationConfig = {
+ @ActivationConfigProperty(propertyName = "destinationType", propertyValue
= "javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName = "destination", propertyValue =
"queue/DarResponseQueue")
+ },
+ messageListenerInterface = javax.jms.MessageListener.class
+)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> DarResponseMessageBean
+{
+ <emphasis role="bold">private</emphasis> Logger log =
Logger.getLogger(DarResponseMessageBean.class);
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> onMessage(Message arg0)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ TextMessage textMessage = (TextMessage)arg0;
+ String result = textMessage.getText();
+ log.info("DAR response received: " + result);
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+</screen><para>It's another message driven bean that listens on
<emphasis>queue/DarResponseQueue</emphasis> and simply logs the received
messages.</para><para> </para></section>
+<section
id="JBossWS-Asynchronousinvocationssample_Running_the_sample_802346"><title>Running
the sample</title><para>Now it's time to run the sample; we already built
and deployed the server side (<emphasis>jaxws-samples-dar-jms.jar</emphasis>),
thus let's take a look at the generated client archives first. You'll get a
<emphasis>sar</emphasis> file containing two archives: the first one
(<emphasis>jaxws-samples-dar-jms-client.war</emphasis>) is the invocation part
of the client, containing the servlet...</para><screen
xml:space="preserve">[alessio@localhost trunk]$ jar -tvf
output/tests/libs/jaxws-samples-dar-jms-client.war
+ 0 Fri Feb 01 19:34:22 CET 2008 META-INF/
+ 106 Fri Feb 01 19:34:20 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 01 19:34:22 CET 2008 WEB-INF/
+ 625 Fri Feb 01 14:11:00 CET 2008 WEB-INF/web.xml
+ 0 Thu Jan 10 21:41:02 CET 2008 WEB-INF/classes/org/
+ 0 Thu Jan 10 21:07:24 CET 2008 WEB-INF/classes/org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 WEB-INF/classes/org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 WEB-INF/classes/org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/
+ 4407 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/ClientHelper.class
+ 4560 Fri Feb 01 19:34:10 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/JMSClient.class
+ 0 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/
+ 1017 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/Bus.class
+ 1447 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/DarEndpoint.class
+ 1619 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/DarRequest.class
+ 1389 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/DarResponse.class
+ 1597 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/DarService.class
+ 1681 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/ObjectFactory.class
+ 1267 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/Route.class
+ 1589 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/ServiceRequest.class
+ 1210 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/Stop.class
+ 282 Fri Feb 01 17:55:08 CET 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/package-info.class
+ 232 Fri Feb 01 14:11:00 CET 2008 WEB-INF/jboss-web.xml
+</screen><para>... the second one
(<emphasis>jaxws-samples-dar-jms-client.jar</emphasis>) ships the response
message bean instead:</para><screen
xml:space="preserve">[alessio@localhost trunk]$ jar -tvf
output/tests/libs/jaxws-samples-dar-jms-client.jar
+ 0 Fri Feb 01 19:34:22 CET 2008 META-INF/
+ 106 Fri Feb 01 19:34:20 CET 2008 META-INF/MANIFEST.MF
+ 0 Thu Jan 10 21:41:02 CET 2008 org/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/
+ 1513 Fri Feb 01 19:34:10 CET 2008
org/jboss/test/ws/jaxws/samples/dar/DarResponseMessageBean.class
+</screen><para>Here is the
<emphasis>jaxws-samples-dar-jms-client.sar</emphasis>
archive:</para><screen xml:space="preserve">[alessio@localhost
trunk]$ jar -tvf output/tests/libs/jaxws-samples-dar-jms-client.sar
+ 0 Fri Feb 01 19:34:22 CET 2008 META-INF/
+ 106 Fri Feb 01 19:34:20 CET 2008 META-INF/MANIFEST.MF
+ 2156 Fri Feb 01 19:34:22 CET 2008 jaxws-samples-dar-jms-client.jar
+ 14138 Fri Feb 01 19:34:22 CET 2008 jaxws-samples-dar-jms-client.war
+ 58 Fri Feb 01 17:47:20 CET 2008 META-INF/jboss-service.xml
+</screen><para>As you can see from the sources, the
<emphasis>jboss-service.xml</emphasis> doesn't define anything actually;
it could be used to install the two queue we use, but since the application server
automatically creates the queues any MDB listens to, we choose the easy way
here.</para><para> </para><para>Finally we can run the sample!
Please drop the <emphasis>sar</emphasis> archive in the deploy directory of
you already running application server, then just browse to <ulink
url="http://localhost:8080/dar-jms-client/JMSClient">http://localhost:8080/dar-jms-client/JMSClient</ulink>:
you'll immediately get a simple page saying the request has been sent, meaning the
invocation part of the client did his job. On the logs you'll see something like
this:</para><screen xml:space="preserve">10:13:47,279 INFO
[DarProcessor] Processing DAR request...
org.jboss.test.ws.jaxws.samples.dar.DarRequest@694b7e
+10:13:47,279 INFO [DarProcessor] 1 person(s) from 18 to 575
+10:13:47,279 INFO [DarProcessor] 2 person(s) from 713 to 845
+10:13:47,279 INFO [DarProcessor] 2 person(s) from 117 to 140
+10:13:47,279 INFO [DarProcessor] 1 person(s) from 318 to 57
+10:13:52,280 INFO [DarProcessor] Done
org.jboss.test.ws.jaxws.samples.dar.DarRequest@694b7e
+10:13:52,353 INFO [AbstractJMSTransportSupport] Sent response
+10:13:52,360 INFO [DarResponseMessageBean] DAR response received: <env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/dar'><return><routes><busId>Bus1</busId><stops><node>117</node></stops><stops><node>140</node><time>2008-02-01T14:25:12.114+01:00</time></stops><stops><node>318</node><time>2008-02-01T14:25:12.114+01:00</time></stops><stops><node>57</node><time>2008-02-01T14:25:12.114+01:00</time></stops></routes><routes><busId>Bus0</busId><stops><node>18</node><time>2008-02-01T14:25:12.114+01:00</time></stops><stops><node>575</node><time>2008-02-01T14:25:12.114+01:00</time></stops><s!
tops><node>713</node><time>2008-02-01T14:25:12.114+01:00</time></stops><stops><node>845</node><time>2008-02-01T14:25:12.114+01:00</time></stops></routes><unservedRequests><from><node>667</node><time>2008-02-01T14:25:12.114+01:00</time></from><id>Req0</id><people>2</people><to><node>17</node><time>2008-02-01T14:25:12.114+01:00</time></to></unservedRequests></return></ns1:processResponse></env:Body></env:Envelope></screen><para>Once
the DaR request processing is done, the response is put to the queue and the
<emphasis>DarResponseMessageBean</emphasis> consumes it. We achieved the
expected behavior using the JMS transport too,
however...</para><para> </para></section>
+<section
id="JBossWS-Asynchronousinvocationssample_Client_and_server_on_different_boxes"><title>Client
and server on different boxes</title><para>As previously said, for ease
we've been deploying both client and server sides of our application on the same JBoss
instance. We all know that web services are about different systems interoperability thus
running client and server on different boxes is the common situation. However obtaining
this is not straightforward when playing with queues and message bean endpoints. The
reason for this is that both the request and response queue belong to the service provider
side, even if the client says which response queue has to be used. A real world
architecture with client and server running on different boxes implies
that:</para><itemizedlist><listitem><para> you need to define the
response queue on the server side, using a
<emphasis>jboss-service.xml</emphasis> descriptor:
</para></listitem></itemizedlist><screen
xml:space="preserve"!
<?xml version="1.0"
encoding="UTF-8"?>
+<server>
+ <mbean code="org.jboss.mq.server.jmx.Queue"
name="jboss.mq.destination:service=Queue,name=DarResponseQueue">
+ <depends
optional-attribute-name="DestinationManager">jboss.mq:service=DestinationManager</depends>
+ </mbean>
+</server>
+</screen><para>Note if you're running on JBoss5 and above, you need to
define both request and response queues using
<emphasis>jboss-service.xml</emphasis> descriptor:</para><screen
xml:space="preserve"><?xml version="1.0"
encoding="UTF-8"?>
+<server>
+ <mbean code="org.jboss.mq.server.jmx.Queue"
name="jboss.mq.destination:service=Queue,name=DarRequestQueue">
+ <depends
optional-attribute-name="DestinationManager">jboss.mq:service=DestinationManager</depends>
+ </mbean>
+ <mbean code="org.jboss.mq.server.jmx.Queue"
name="jboss.mq.destination:service=Queue,name=DarResponseQueue">
+ <depends
optional-attribute-name="DestinationManager">jboss.mq:service=DestinationManager</depends>
+ </mbean>
+</server>
+</screen><itemizedlist><listitem><para> when sending the request,
your client has to lookup the queue using the remote provider; this is achieved properly
configuring the InitialContext:
</para></listitem></itemizedlist><screen
xml:space="preserve">Hashtable env = <emphasis
role="bold">new</emphasis> Hashtable();
+env.put(javax.naming.Context.INITIAL_CONTEXT_FACTORY,
"org.jnp.interfaces.NamingContextFactory");
+env.put("java.naming.factory.url.pkgs","org.jboss.naming:org.jnp.interfaces");
+env.put(javax.naming.Context.PROVIDER_URL, service_provider_host_address);
+InitialContext context = <emphasis role="bold">new</emphasis>
InitialContext(env);
+QueueConnectionFactory connectionFactory =
(QueueConnectionFactory)context.lookup("ConnectionFactory");
+Queue reqQueue = (Queue)context.lookup("queue/DarRequestQueue");
+con = connectionFactory.createQueueConnection();
+session = con.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
+Queue resQueue = (Queue)context.lookup("queue/DarResponseQueue");
+</screen><itemizedlist><listitem><para> if you want to stick to
the solution using the client response message bean, it has to listen to a remote queue.
The instruction for doing so are available at the <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=HowDoIConfigureAnEJB3M...
JBoss wiki</ulink> </para></listitem><listitem><para>
finally, you'll have to cope with the need of defining and advertising different
response queues for each service consumer, which might not be that good...
</para></listitem></itemizedlist></section>
+</section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Authentication.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Authentication.xml
(rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Authentication.xml 2010-11-02 19:25:45 UTC
(rev 13202)
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-Authentication"><title>JBossWS-Authentication</title><para>This
page explains the simplest way to authenticate a web service user with
JBossWS.</para><para>First we secure the access to the SLSB as we would do for
normal (non web service) invocations: this can be easily done through the @RolesAllowed,
@PermitAll, @DenyAll annotation. The allowed user roles can be set with these annotations
both on the bean class and on any of its business methods.</para><screen
xml:space="preserve">@Stateless
+@RolesAllowed("friend")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> EndpointEJB <emphasis
role="bold">implements</emphasis> EndpointInterface
+{
+ ...
+}
+</screen><para>Similarly POJO endpoints are secured the same way as we do for
normal web applications in web.xml:</para><screen
xml:space="preserve"> <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>All resources</web-resource-name>
+ <url-pattern>/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>friend</role-name>
+ </auth-constraint>
+ </security-constraint>
+
+ <security-role>
+ <role-name>friend</role-name>
+ </security-role></screen><section><title>Define the
security domain</title><para>Next, define the security domain for this
deployment. This is performed using the <ulink
url="http://community.jboss.org/docs/DOC-13972#SecurityDomain"&...
annotation for EJB3 endpoints</para><screen
xml:space="preserve">@Stateless
+@SecurityDomain("JBossWS")
+@RolesAllowed("friend")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> EndpointEJB <emphasis
role="bold">implements</emphasis> EndpointInterface
+{
+ ...
+}
+</screen><para>or modifying the jboss-web.xml for POJO
endpoints</para><screen
xml:space="preserve"><jboss-web>
+ <security-domain>java:/jaas/JBossWS</security-domain>
+</jboss-web>
+</screen><para>The JBossWS security context is configured in login-config.xml
and uses the <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=UsersRolesLoginModule&...;.
As a matter of fact login-config.xml, that lives in the server config dir, contains this
security domain definition:</para><screen xml:space="preserve">
<!--
+ A template configuration for the JBossWS security domain.
+ This defaults to the UsersRolesLoginModule the same as other and should be
+ changed to a stronger authentication mechanism as required.
+ -->
+ <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>
+</screen><para>Of course you can define and use your own security domain as
well as your login module (in order to check for users' identity querying a database
for example).</para></section>
+<section><title>Use BindingProvider to set
principal/credential</title><para>A web service client may use the
javax.xml.ws.BindingProvider interface to set the username/password
combination</para><screen xml:space="preserve">URL wsdlURL =
<emphasis role="bold">new</emphasis>
File("resources/jaxws/samples/context/WEB-INF/wsdl/TestEndpoint.wsdl").toURL();
+QName qname = <emphasis role="bold">new</emphasis>
QName("http://org.jboss.ws/jaxws/context", "TestEndpointService");
+Service service = Service.create(wsdlURL, qname);
+port = (TestEndpoint)service.getPort(TestEndpoint.class);
+
+BindingProvider bp = (BindingProvider)port;
+bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, "kermit");
+bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, "thefrog");
+</screen></section>
+<section><title>Using HTTP Basic Auth for
security</title><para>To enable HTTP Basic authentication you use the
<ulink
url="http://community.jboss.org/docs/DOC-13972#WebContext">@...
annotation on the bean class</para><screen
xml:space="preserve">@Stateless
+@SecurityDomain("JBossWS")
+@RolesAllowed("friend")
+@WebContext(contextRoot="/my-cxt", urlPattern="/*",
authMethod="BASIC", transportGuarantee="NONE",
secureWSDLAccess=<emphasis role="bold">false</emphasis>)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> EndpointEJB <emphasis
role="bold">implements</emphasis> EndpointInterface
+{
+ ...
+}
+</screen><para>For POJO endpoints, we modify the web.xml adding the
auth-method element:</para><screen xml:space="preserve">
<login-config>
+ <auth-method>BASIC</auth-method>
+ <realm-name>Test Realm</realm-name>
+ </login-config>
+</screen></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Endpointmanagement.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Endpointmanagement.xml
(rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Endpointmanagement.xml 2010-11-02 19:25:45 UTC
(rev 13202)
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-Endpointmanagement"><title>JBossWS-Endpointmanagement</title><para>JBossWS
registers MBeans that users can leverage to manage every webservice endpoint. Apart from
the obvious start/stop functionalities, they provide valuable information and statistics
about messages processed by the
endpoints.</para><para/><para> </para><section
id="JBossWS-Endpointmanagement_Getting_the_information"><title>Getting
the information</title><para>JBoss ships with a JMX-Console with all the
application server MBeans. It is usually available at URL <ulink
url="http://localhost:8080/jmx-console">http://localhost:8080/jmx-console</ulink>.
For endpoint management you might be interested in the MBeans belonging to the jboss.ws
domain.</para><para>The application server also has an applet based
web-console which basically has the same data as the JMX-Console plus some advanced
features including snapshot graphics.</para><para>Of course!
you can access an MBean programmatically too. Please refer to the <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=FAQJBossJMX">J... JMX
faq</ulink> for further details; here is a brief code snippet you might want to
start from in order to access a ManagedEndpointMBean from the same virtual
machine:</para><screen xml:space="preserve"><emphasis
role="bold">try</emphasis>
+{
+ MBeanServer server = MBeanServerLocator.locate();
+ ManagedEndpointMBean mep = (ManagedEndpointMBean)MBeanProxyExt.create(
+ ManagedEndpointMBean.class,
+ "jboss.ws:context=my-ctx,endpoint=MyEndpoit",
+ server);
+ ...
+}
+<emphasis role="bold">catch</emphasis> (Exception e)
+{
+ e.printStackTrace();
+}
+</screen></section>
+<section
id="JBossWS-Endpointmanagement_Metrics"><title>Metrics</title><para>For
each deployed endpoint you'll find an
<emphasis>org.jboss.wsf.framework.management.ManagedEndpoint</emphasis> MBean
providing basic start/stop functionalities and metrics. Calling a stopped endpoint will
always result in a SOAP fault message.</para><para>The metrics available for
each managed endpoint are:</para><itemizedlist><listitem><para>
Min, max, average and total processing time: processing includes both the WS stack plus
application server work and the user business logic
</para></listitem><listitem><para> Last start and stop time
</para></listitem><listitem><para> Request, response and fault
count</para></listitem></itemizedlist></section>
+<section
id="JBossWS-Endpointmanagement_Records"><title>Records</title><para>JBossWS
features a highly configurable records' collection and management system. Each record
is basically composed of a message plus additional information (for example the caller
address and the called endpoint operation).</para><para>Endpoints can be
configured with record processors that are invoked whenever a message flow is detected and
records are thus created.</para><para>Every deployed endpoint is configured
with default record processors. However custom processors as well as record filters can be
easily plugged in and managed at any time through JMX. This gives users the chance of
performing advanced analysis of the webservice traffic according to their business
requirements.</para><para>Please refer to the <ulink
url="http://jbossws.jboss.org/mediawiki/index.php?title=Records_mana...
management page</ulink> for further details.</para></section>
+<section
id="JBossWS-Endpointmanagement_Snapshots_and_threshold_monitors"><title>Snapshots
and threshold monitors</title><para>As previously said, the <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WebConsole">JBoss Web
Console</ulink> has interesting features including <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WebConsoleSnapshots&qu...
and <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WebConsoleMonitoring&q...
monitors</ulink>.</para><para>Snapshots allow users to record changes of
a given MBean attribute within a defined time interval. Data are sampled at a given rate
and may be plotted to graphs with a few clicks. Snapshots are listed in the Web console
and can be created simply browsing to <ulink
url="http://localhost:8080/web-console/createSnapshot.jsp">http://localhost:8080/web-console/createSnapshot.jsp</ulink>
.</para><para>Threshold monitors allow users to be notified whenever a given
MBean attribute exceed a certain range!
of values. The threshold monitor's creation and management processes are similar to
those mentioned above for the snapshots. Simply browse to <ulink
url="http://localhost:8080/web-console/createThresholdMonitor.jsp">http://localhost:8080/web-console/createThresholdMonitor.jsp</ulink>
.</para><para>Speaking of WS availability and SLA, this all becomes
interesting because users can monitor and take snapshots of critical attributes like the
average/max processing time of a managed endpoint. Moreover, advanced analysis can be
performed leveraging ad-hoc attributes of custom <ulink
url="http://jbossws.jboss.org/mediawiki/index.php?title=Endpoint_man...
processors</ulink>.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-JAX-WSAnnotations.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-JAX-WSAnnotations.xml
(rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-JAX-WSAnnotations.xml 2010-11-02 19:25:45 UTC
(rev 13202)
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-JAX-WSAnnotations"><title>JBossWS-JAX-WSAnnotations</title><para/><section
id="JBossWS-JAX-WSAnnotations_JAXWS_Annotations"><title>JAX-WS
Annotations</title><para>For details, see <ulink
url="http://www.jcp.org/en/jsr/detail?id=224">JSR-224 - Java API for
XML-Based Web Services (JAX-WS)
2.0</ulink></para><para> </para><section
id="JBossWS-JAX-WSAnnotations_javaxxmlwsServiceMode"><title>javax.xml.ws.ServiceMode</title><para>The
ServiceMode annotation is used to specify the mode for a provider class, i.e. whether a
provider wants to have access to protocol message payloads (e.g. a SOAP body) or the
entire protocol messages (e.g. a SOAP
envelope).</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebFault"><title>javax.xml.ws.WebFault</title><para>The
WebFault annotation is used when mapping WSDL faults to Java exceptions, see section 2.5.
It is used to capture the name of the fault element used when marshalling the JAXB type
generated from the global element referenced by the WSDL fault message. It can also be
used to customize the mapping of service specific exceptions to WSDL
faults.</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxxmlwsRequestWrapper"><title>javax.xml.ws.RequestWrapper</title><para>The
RequestWrapper annotation is applied to the methods of an SEI. It is used to capture the
JAXB generated request wrapper bean and the element name and namespace for marshalling /
unmarshalling the bean. The default value of localName element is the operationName as
defined in WebMethod annotation and the default value for the targetNamespace element is
the target namespace of the SEI.When starting from Java, this annotation is used to
resolve overloading conflicts in document literal mode. Only the className element is
required in this case.</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxxmlwsResponseWrapper"><title>javax.xml.ws.ResponseWrapper</title><para>The
ResponseWrapper annotation is applied to the methods of an SEI. It is used to capture the
JAXB generated response wrapper bean and the element name and namespace for marshalling /
unmarshalling the bean. The default value of the localName element is the operationName as
defined in the WebMethod appended with ”Response” and the default value of the
targetNamespace element is the target namespace of the SEI. When starting from Java, this
annotation is used to resolve overloading conflicts in document literal mode. Only the
className element is required in this
case.</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebServiceClient"><title>javax.xml.ws.WebServiceClient</title><para>The
WebServiceClient annotation is specified on a generated service class (see 2.7). It is
used to associate a class with a specific Web service, identify by a URL to a WSDL
document and the qualified name of a wsdl:service
element.</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebEndpoint"><title>javax.xml.ws.WebEndpoint</title><para>The
WebEndpoint annotation is specified on the getPortName() methods of a generated service
class (see 2.7). It is used to associate a get method with a specific wsdl:port,
identified by its local name (a
NCName).</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebServiceProvider"><title>javax.xml.ws.WebServiceProvider</title><para>The
WebServiceProvider annotation is specified on classes that implement a strongly typed
javax- .xml.ws.Provider. It is used to declare that a class that satisfies the
requirements for a provider (see 5.1) does indeed define a Web service endpoint, much like
the WebService annotation does for SEI-based endpoints.</para><para>The
WebServiceProvider and WebService annotations are mutually
exclusive.</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxxmlwsBindingType"><title>javax.xml.ws.BindingType</title><para>The
BindingType annotation is applied to an endpoint implementation class. It specifies the
binding to use when publishing an endpoint of this type.</para><para>The
default binding for an endpoint is the SOAP 1.1/HTTP
one</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebServiceRef"><title>javax.xml.ws.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 [32].
The WebServiceRef annotation is required to be honored when running on the Java EE 5
platform, where it is subject to the common resource injection rules described by the
platform specification [33].</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebServiceRefs"><title>javax.xml.ws.WebServiceRefs</title><para>The
WebServiceRefs annotation is used to declare multiple references to Web services on a
single class. It is necessary to work around the limition against specifying repeated
annotations of the same type on any given class, which prevents listing multiple
javax.ws.WebServiceRef annotations one after the other. This annotation follows the
resource pattern exemplified by the javax.annotation.Resources annotation in
JSR-250.</para><para>Since no name and type can be inferred in this case, each
WebServiceRef annotation inside a WebServiceRefs MUST contain name and type elements with
non-default values. The WebServiceRef annotation is required to be honored when running on
the Java EE 5 platform, where it is subject to the common resource injection rules
described by the platform
specification.</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxxmlwsAction"><title>javax.xml.ws.Action</title><para>The
Action annotation is applied to the methods of a SEI. It used to generate the wsa:Action
on wsdl:input and wsdl:output of each wsdl:operation mapped from the annotated
methods.</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxxmlwsFaultAction"><title>javax.xml.ws.FaultAction</title><para>The
FaultAction annotation is used within the Action annotation to generate the wsa:Action
element on the wsdl:fault element of each wsdl:operation mapped from the annotated
methods.</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_Annotations_Defined_by_JSR181"><title>Annotations
Defined by JSR-181</title><para>JSR-181 defines the syntax and semantics of
Java Web Service (JWS) metadata and default values.</para><para>For details,
see <ulink url="http://jcp.org/en/jsr/detail?id=181">JSR 181 - Web
Services Metadata for the Java
Platform</ulink></para><para> </para><section
id="JBossWS-JAX-WSAnnotations_javaxjwsWebService"><title>javax.jws.WebService</title><para>Marks
a Java class as implementing a Web Service, or a Java interface as defining a Web Service
interface.</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxjwsWebMethod"><title>javax.jws.WebMethod</title><para>Customizes
a method that is exposed as a Web Service
operation.</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxjwsOneWay"><title>javax.jws.OneWay</title><para>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. A JSR-181 processor is REQUIRED to report an error if an operation
marked @Oneway has a return value, declares any checked exceptions or has any INOUT or OUT
parameters.</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxjwsWebParam"><title>javax.jws.WebParam</title><para>Customizes
the mapping of an individual parameter to a Web Service message part and XML
element.</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxjwsWebResult"><title>javax.jws.WebResult</title><para>Customizes
the mapping of the return value to a WSDL part and XML
element.</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxjwsSOAPBinding"><title>javax.jws.SOAPBinding</title><para>Specifies
the mapping of the Web Service onto the SOAP message protocol.</para><para>The
SOAPBinding annotation has a target of TYPE and METHOD. The annotation may be placed on a
method if and only if the SOAPBinding.style is DOCUMENT. Implementations MUST report an
error if the SOAPBinding annotation is placed on a method with a SOAPBinding.style of RPC.
Methods that do not have a SOAPBinding annotation accept the SOAPBinding behavior defined
on the type.</para><para> </para></section>
+<section
id="JBossWS-JAX-WSAnnotations_javaxjwsHandlerChain"><title>javax.jws.HandlerChain</title><para>The
@HandlerChain annotation associates the Web Service with an externally defined handler
chain.</para><para>It is an error to combine this annotation with the
@SOAPMessageHandlers annotation.</para><para>The @HandlerChain annotation MAY
be present on the endpoint interface and service implementation bean. The service
implementation bean's @HandlerChain is used if @HandlerChain is present on
both.</para><para>The @HandlerChain annotation MAY be specified on the type
only. The annotation target includes METHOD and FIELD for use by
JAX-WS-2.0.</para></section>
+</section></section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-JAX-WSClientConfiguration.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-JAX-WSClientConfiguration.xml
(rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-JAX-WSClientConfiguration.xml 2010-11-02
19:25:45 UTC (rev 13202)
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-JAX-WSClientConfiguration"><title>JBossWS-JAX-WSClientConfiguration</title><para/><para> </para><para>The
standard client configuration is defined in <emphasis
role="bold">standard-jaxws-client-config.xml</emphasis></para><para> </para><section
id="JBossWS-JAX-WSClientConfiguration_Client_side_port_configuration"><title>Client
side port configuration</title><para>You can use stub properties on the client
side to chose from one of the configuration presets:</para><screen
xml:space="preserve"> Hello endpoint = service.getPort(Hello.class);
+((StubExt) endpoint).setConfigName("Standard WSSecurity Client");
+</screen><para> </para></section>
+<section
id="JBossWS-JAX-WSClientConfiguration_Available_configuration"><title>Available
configuration</title><section
id="JBossWS-JAX-WSClientConfiguration_Standard_Client"><title>Standard
Client</title><screen xml:space="preserve"><jaxws-config
xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
xmlns:javaee="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0
jaxws-config_2_0.xsd">
+
+ <client-config>
+ <config-name>Standard Client</config-name>
+
</client-config></jaxws-config>]</screen><para><anchor
id="Standard_WSAddressing_Client">#</anchor></para></section>
+<section
id="JBossWS-JAX-WSClientConfiguration_Standard_WSAddressing_Client"><title>Standard
WSAddressing Client</title><screen
xml:space="preserve"><jaxws-config
xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
xmlns:javaee="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0
jaxws-config_2_0.xsd">
+
+ <client-config>
+ <config-name>Standard WSAddressing
Client</config-name>
+ <post-handler-chains>
+ <javaee:handler-chain>
+
<javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSAddressing
Handler</javaee:handler-name>
+
<javaee:handler-class>org.jboss.ws.extensions.addressing.jaxws.WSAddressingClientHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+
</client-config></jaxws-config></screen><para> </para></section>
+<section
id="JBossWS-JAX-WSClientConfiguration_Standard_SOAP_12_WSAddressing_Client_Since_203_Native"><title>Standard
SOAP 1.2 WSAddressing Client Since 2.0.3 (Native)</title><screen
xml:space="preserve"><jaxws-config
xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
xmlns:javaee="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0
jaxws-config_2_0.xsd">
+
+ <client-config>
+ <config-name>Standard SOAP 1.2 WSAddressing
Client</config-name>
+ <post-handler-chains>
+ <javaee:handler-chain>
+
<javaee:protocol-bindings>##SOAP12_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSAddressing
Handler</javaee:handler-name>
+
<javaee:handler-class>org.jboss.ws.extensions.addressing.jaxws.WSAddressingClientHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+
</client-config></jaxws-config></screen></section>
+<section
id="JBossWS-JAX-WSClientConfiguration_Standard_WSSecurity_Client"><title>Standard
WSSecurity Client</title><screen
xml:space="preserve"><jaxws-config
xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
xmlns:javaee="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0
jaxws-config_2_0.xsd">
+
+ <client-config>
+ <config-name>Standard WSSecurity Client</config-name>
+ <post-handler-chains>
+ <javaee:handler-chain>
+
<javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+
<javaee:handler-name>WSSecurityHandlerOutbound</javaee:handler-name>
+
<javaee:handler-class>org.jboss.ws.extensions.security.jaxws.WSSecurityHandlerClient</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+ </client-config></jaxws-config>
+</screen></section>
+</section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-JAX-WSEndpointConfiguration.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-JAX-WSEndpointConfiguration.xml
(rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-JAX-WSEndpointConfiguration.xml 2010-11-02
19:25:45 UTC (rev 13202)
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-JAX-WSEndpointConfiguration"><title>JBossWS-JAX-WSEndpointConfiguration</title><para/><para> </para><para>The
standard endpoint configuration is defined in <emphasis
role="bold">standard-jaxws-endpoint-config.xml</emphasis></para><para> </para><section
id="JBossWS-JAX-WSEndpointConfiguration_Using_EndpointConfig"><title>Using
@EndpointConfig</title><para>On the server side you proabably use the
<computeroutput>@EndpointConfig</computeroutput> annotation to specify one of
the available (might be custom as well) configurations:</para><screen
xml:space="preserve">@WebService(name = "Hello", serviceName =
"HelloService", targetNamespace =
"http://org.jboss.ws/samples/wssecurity")
+@EndpointConfig(configName = "Standard WSSecurity Endpoint") (1)
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> HelloJavaBean
+{
+ <emphasis role="bold">private</emphasis> Logger log =
Logger.getLogger(HelloJavaBean.class);
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> UserType
echoUserType(@WebParam(name = "user") UserType in0)
+ {
+ log.info(in0);
+ <emphasis role="bold">return</emphasis> in0;
+ }
+}
+</screen><orderedlist><listitem><para> @EndpointConfig(configName
= "Standard WSSecurity
Endpoint")</para></listitem></orderedlist><para> </para><para> </para></section>
+<section
id="JBossWS-JAX-WSEndpointConfiguration_Configuration_presets"><title>Configuration
presets</title><section
id="JBossWS-JAX-WSEndpointConfiguration_Standard_Endpoint"><title>Standard
Endpoint</title><screen xml:space="preserve"><jaxws-config
xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
xmlns:javaee="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0
jaxws-config_2_0.xsd">
+
+ <endpoint-config>
+ <config-name>Standard Endpoint</config-name>
+
</endpoint-config></jaxws-config></screen></section>
+<section
id="JBossWS-JAX-WSEndpointConfiguration_Standard_WSAddressing_Endpoint"><title>Standard
WSAddressing Endpoint</title><screen
xml:space="preserve"><jaxws-config
xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
xmlns:javaee="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0
jaxws-config_2_0.xsd">
+
+ <endpoint-config>
+ <config-name>Standard WSAddressing
Endpoint</config-name>
+ <post-handler-chains>
+ <javaee:handler-chain>
+
<javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSAddressing
Handler</javaee:handler-name>
+
<javaee:handler-class>org.jboss.ws.extensions.addressing.jaxws.WSAddressingServerHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+ </endpoint-config></jaxws-config>
+</screen><para> </para><para> </para></section>
+<section
id="JBossWS-JAX-WSEndpointConfiguration_Standard_SOAP_12_WSAddressing_Endpoint_Since_203_Native"><title>Standard
SOAP 1.2 WSAddressing Endpoint Since 2.0.3 (Native)</title><screen
xml:space="preserve"><jaxws-config
xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
xmlns:javaee="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0
jaxws-config_2_0.xsd">
+
+ <endpoint-config>
+ <config-name>Standard SOAP 1.2 WSAddressing
Endpoint</config-name>
+ <post-handler-chains>
+ <javaee:handler-chain>
+
<javaee:protocol-bindings>##SOAP12_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSAddressing
Handler</javaee:handler-name>
+
<javaee:handler-class>org.jboss.ws.extensions.addressing.jaxws.WSAddressingServerHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+
</endpoint-config></jaxws-config></screen></section>
+<section
id="JBossWS-JAX-WSEndpointConfiguration_Standard_WSSecurity_Endpoint"><title>Standard
WSSecurity Endpoint</title><screen
xml:space="preserve"><jaxws-config
xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
xmlns:javaee="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0
jaxws-config_2_0.xsd">
+
+ <endpoint-config>
+ <config-name>Standard WSSecurity
Endpoint</config-name>
+ <post-handler-chains>
+ <javaee:handler-chain>
+
<javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSSecurity
Handler</javaee:handler-name>
+
<javaee:handler-class>org.jboss.ws.extensions.security.jaxws.WSSecurityHandlerServer</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+ </endpoint-config></jaxws-config>
+</screen></section>
+</section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-JAX-WSTools.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-JAX-WSTools.xml (rev
0)
+++ stack/native/trunk/src/main/doc/JBossWS-JAX-WSTools.xml 2010-11-02 19:25:45 UTC (rev
13202)
@@ -0,0 +1,171 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-JAX-WSTools"><title>JBossWS-JAX-WSTools</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.</para><para/><section
id="JBossWS-JAX-WSTools_Server_side"><title>Server
side</title><para>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><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><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:</para><informaltable><tgroup
cols="2"><colspec colnum="1"
colname="col1"/><colspec colnum="2"
colname="col2"/><thead><row><entry> Command
</entry><entry> Description </entry><!
/row></thead><tbody><row><entry><para><link
linkend="chap_JBos!
sWS-wspr
ovide">JBossWS -
wsprovide</link></para></entry><entry>Generates JAX-WS portable
artifacts, and provides the abstract contract. Used for bottom-up
development.</entry></row><row><entry><para><link
linkend="chap_JBossWS-wsconsume">JBossWS -
wsconsume</link></para></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><para><link
linkend="chap_JBossWS-wsrunclient">JBossWS -
wsrunclient</link></para></entry><entry>Executes a Java client
(has a main method) using the JBossWS
classpath.</entry></row></tbody></tgroup></informaltable><section
id="JBossWS-JAX-WSTools_BottomUp_Using_wsprovide"><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:</para><screen xml:space="preserve"><emphasis
role="bold">package</emphasis> echo;
+
+(a)javax.jws.WebService
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> Echo
+{
+ <emphasis role="bold">public</emphasis> String echo(String
input)
+ {
+ <emphasis role="bold">return</emphasis> input;
+ }
+}
+</screen><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
<link linkend="chap_JBossWS-wsprovide">JBossWS -
wsprovide</link>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 obt!
ained by invoking <link linkend="chap_JBossWS-wsprovide">JBossWS -
wsprovide</link> using the "-w" option:</para><screen
xml:space="preserve">$ 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
+</screen><para>Inspecting the WSDL reveals a service called
EchoService:</para><screen xml:space="preserve"><service
name='EchoService'><port binding='tns:EchoBinding'
name='EchoPort'>
+ <soap:address
location='REPLACE_WITH_ACTUAL_URL'/></port>
+</service>
+</screen><para>As expected, this service defines one operation,
"echo":</para><screen
xml:space="preserve"><portType
name='Echo'><operation name='echo'
parameterOrder='echo'>
+ <input message='tns:Echo_echo'/>
+ <output
message='tns:Echo_echoResponse'/></operation>
+</portType>
+</screen><note><para><para><emphasis><emphasis
role="bold">Note</emphasis></emphasis></para><para><emphasis>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.</emphasis></para></para></note><para>Let's
create a POJO endpoint for deployment on JBoss AS. A simple web.xml needs to be
created:</para><screen xml:space="preserve"><web-app
xmlns="<ulink
url="http://java.sun.com/xml/ns/j2ee">http://java.sun.com/xm...
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://java.sun.com/xml/ns/j2ee">http://java.sun.com/xm...
<ulink
url="http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">http:/...
+ 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>
+</screen><para>The web.xml and the single class can now be used to create a
war:</para><screen xml:space="preserve">$ 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%)
+</screen><para>The war can then be deployed:</para><screen
xml:space="preserve">cp echo.war
/usr/local/jboss-4.2.0.GA-ejb3/server/default/deploy
+</screen><para>This will internally invoke <link
linkend="chap_JBossWS-wsprovide">JBossWS - wsprovide</link>, which will
generate the WSDL. If deployment was successful, and you are using the default settings,
it should be available here: <ulink
url="http://localhost:8080/echo/Echo?wsdl">http://localhost:8080/echo/Echo?wsdl</ulink></para><para>For
a portable JAX-WS deployment, the wrapper classes generated earlier could be added to the
deployment.</para></section>
+<section
id="JBossWS-JAX-WSTools_TopDown_Using_wsconsume"><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 <link linkend="chap_JBossWS-wsconsume">JBossWS -
wsconsume</link> tool is then used to consume this contract, and produce annotated
Java classes (and optionally sources) that define
it.</para><note><para><para><emphasis
role="bold">Note</emphasis></para><para>wsconsume seems to
have a problem with symlinks on unix
systems</para></para></note><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 <link
linkend="chap_JBossWS-wsconsume">JBossWS - wsconsume</link> to preserve
the Java source files that are generated, instead of providing just
classes:</para><screen xml:space="preserve">
+$ 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
+</screen><para>The following table shows the purpose of each generated
file:</para><informaltable><tgroup cols="2"><colspec
colnum="1" colname="col1"/><colspec colnum="2"
colname="col2"/><thead><row><entry> File
</entry><entry> Purpose
</entry></row></thead><tbody><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></informaltable><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 sa!
me contract:</para><screen xml:space="preserve">@WebService(name =
"Echo", targetNamespace = "http://echo/")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">interface</emphasis> Echo {
+ @WebMethod
+ @WebResult(targetNamespace = "")
+ @RequestWrapper(localName = "echo", targetNamespace =
"http://echo/", className = "echo.Echo_Type")
+ @ResponseWrapper(localName = "echoResponse", targetNamespace =
"http://echo/", className = "echo.EchoResponse")
+ <emphasis role="bold">public</emphasis> String echo(
+ @WebParam(name = "arg0", targetNamespace = "")
+ String arg0);
+
+}
+</screen><para>The only missing piece (besides the packaging) is the
implementation class, which can now be written, using the above
interface.</para><screen xml:space="preserve"><emphasis
role="bold">package</emphasis> echo;
+
+(a)javax.jws.WebService(endpointInterface="echo.Echo")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> EchoImpl <emphasis
role="bold">implements</emphasis> Echo
+{
+ <emphasis role="bold">public</emphasis> String echo(String
arg0)
+ {
+ <emphasis role="bold">return</emphasis> arg0;
+ }
+}
+</screen></section>
+</section>
+<section id="JBossWS-JAX-WSTools_Client_Side"><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><emphasis role="bold">recommended methodology for
developing a client is</emphasis></emphasis> to follow
<emphasis><emphasis role="bold">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 <link
linkend="chap_JBossWS-wsprovide">JBossWS - wsprovide</link>. 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:</para><screen
xml:space="preserve"><service name='EchoService'>
+ <port binding='tns:EchoBinding' name='EchoPort'>
+ <soap:address location='REPLACE_WITH_ACTUAL_URL'/>
+ </port></service>
+</screen><para>Online version:</para><screen
xml:space="preserve"><service name="EchoService">
+ <port binding="tns:EchoBinding" name="EchoPort">
+ <soap:address location="<ulink
url="http://localhost.localdomain:8080/echo/Echo">http://localhost.localdomain:8080/echo/Echo</ulink>"/>
+ </port>
+</service>
+</screen><para>Using the online deployed version with <link
linkend="chap_JBossWS-wsconsume">JBossWS -
wsconsume</link>:</para><screen xml:space="preserve">$
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
+</screen><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.</para><screen xml:space="preserve">@WebServiceClient(name =
"EchoService", targetNamespace = "http://echo/", wsdlLocation =
"http://localhost:8080/echo/Echo?wsdl")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> EchoService <emphasis
role="bold">extends</emphasis> Service
+{
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">final</emphasis> <emphasis
role="bold">static</emphasis> URL ECHOSERVICE_WSDL_LOCATION;
+
+ <emphasis role="bold">static</emphasis> {
+ URL url = <emphasis role="bold">null</emphasis>;
+ <emphasis role="bold">try</emphasis> {
+ url = <emphasis role="bold">new</emphasis>
URL("http://localhost:8080/echo/Echo?wsdl");
+ } <emphasis role="bold">catch</emphasis>
(MalformedURLException e) {
+ e.printStackTrace();
+ }
+ ECHOSERVICE_WSDL_LOCATION = url;
+ }
+
+ <emphasis role="bold">public</emphasis> EchoService(URL
wsdlLocation, QName serviceName) {
+ <emphasis role="bold">super</emphasis>(wsdlLocation,
serviceName);
+ }
+
+ <emphasis role="bold">public</emphasis> EchoService() {
+ <emphasis
role="bold">super</emphasis>(ECHOSERVICE_WSDL_LOCATION, <emphasis
role="bold">new</emphasis> QName("http://echo/",
"EchoService"));
+ }
+
+ @WebEndpoint(name = "EchoPort")
+ <emphasis role="bold">public</emphasis> Echo getEchoPort() {
+ <emphasis role="bold">return</emphasis>
(Echo)super.getPort(<emphasis role="bold">new</emphasis>
QName("http://echo/", "EchoPort"), Echo.class);
+ }
+}
+</screen><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><note><para><para><emphasis><emphasis
role="bold">Note</emphasis></emphasis></para><para><emphasis>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.</emphasis></para></para></note><para>All that is
left to do, is write and compile the client:</para><screen
xml:space="preserve"><emphasis
role="bold">import</emphasis> e!
cho.*;
+
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> EchoClient
+{
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">void</emphasis> main(String args[])
+ {
+ <emphasis role="bold">if</emphasis> (args.length != 1)
+ {
+ System.err.println("usage: EchoClient <message>");
+ System.exit(1);
+ }
+
+ EchoService service = <emphasis role="bold">new</emphasis>
EchoService();
+ Echo echo = service.getEchoPort();
+ System.out.println("Server said: " + echo.echo(args[0]));
+ }}
+</screen><para>It can then be easily executed using the <link
linkend="chap_JBossWS-wsrunclient">JBossWS - wsrunclient</link> tool.
This is just a convenience tool that invokes java with the needed
classpath:</para><screen xml:space="preserve">$ wsrunclient
EchoClient 'Hello World!'
+Server said: Hello World!
+</screen><para>It is easy to change the endpoint address of your operation at
runtime, setting the ENDPOINT_ADDRESS_PROPERTY as shown below:</para><screen
xml:space="preserve">...
+ EchoService service = <emphasis role="bold">new</emphasis>
EchoService();
+ Echo echo = service.getEchoPort();
+
+ /* Set NEW Endpoint Location */
+ String endpointURL = "http://NEW_ENDPOINT_URL";
+ BindingProvider bp = (BindingProvider)echo;
+ bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
endpointURL);
+
+ System.out.println("Server said: " + echo.echo(args[0]));
+...
+</screen></section>
+<section
id="JBossWS-JAX-WSTools_Commandline_Maven_Plugin_and_Ant_Task_Reference"><title>Command-line,
Maven Plugin and Ant Task
Reference</title><itemizedlist><listitem><para> <link
linkend="chap_JBossWS-wsconsume">JBossWS - wsconsume</link> reference
page </para></listitem><listitem><para> <link
linkend="chap_JBossWS-wsprovide">JBossWS - wsprovide</link> reference
page </para></listitem><listitem><para> <link
linkend="chap_JBossWS-wsrunclient">JBossWS - wsrunclient</link>
reference page</para></listitem></itemizedlist></section>
+<section
id="JBossWS-JAX-WSTools_JAXWS_binding_customization"><title>JAX-WS
binding customization</title><para>An introduction to binding
customizations:</para><itemizedlist><listitem><para> <ulink
url="http://java.sun.com/webservices/docs/2.0/jaxws/customizations.h...
</para></listitem><listitem><para> <ulink
url="https://jax-ws.dev.java.net/source/browse/jax-ws/guide/docs/wsd...
schema</ulink> </para></listitem><listitem><para> <ulink
url="https://jax-ws.dev.java.net/nonav/guide/customizations/"&g...
</para></listitem></itemizedlist><para>The schema for the binding
customization files can be found
here:</para><itemizedlist><listitem><para> <ulink
url="https://jax-ws.dev.java.net/source/browse/jax-ws/guide/docs/wsd...!
2&view=log</ulink>
</para></listitem></itemizedlist></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Native.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Native.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Native.xml 2010-11-02 19:25:45 UTC (rev
13202)
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<book>
+
+<xi:include href="Book_Info.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+<part id="Main documentation">
+ <title>Main Documentation</title>
+ <partintro>
+ <para>
+ Below you find the essential documentation on the current JBossWS-Native release.
That covers a quick start, a full user guide and tooling. You can read more on
+ JBoss Web Service Framework on the JBossWS Wiki at <ulink
url="http://community.jboss.org/wiki/JBossWS">http://communi...;.
+ </para>
+ <para>
+ Please note, the wiki also offers a <ulink
url="http://www.jboss.org/community/docs/DOC-13531">Guided Tour</ulink>
along the JBossWS documentation, for those who
+ don't know where to start from when dealing with webservices in general.
+ </para>
+ </partintro>
+ <xi:include href="JBossWS-QuickStart.xml" encoding="UTF-8"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-UserGuide.xml" encoding="UTF-8"
xmlns:xi="http://www.w3.org/2001/XInclude" /> <!-- remove WSF stuff from
generated page -->
+ <xi:include href="JBossWS-NativeUserGuide.xml" encoding="UTF-8"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-JAX-WSTools.xml" encoding="UTF-8"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-wsconsume.xml" encoding="UTF-8"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-wsprovide.xml" encoding="UTF-8"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-wsrunclient.xml" encoding="UTF-8"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+</part>
+
+
+<part id="Additional documentation">
+ <title>Additional documentation</title>
+ <partintro>
+ <para>
+ This section of the book provides documentation on common additional user
requirements, like enabling authentication, securing the transport, etc.
+ </para>
+ </partintro>
+ <xi:include href="JBossWS-Authentication.xml" encoding="UTF-8"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Securetransport.xml" encoding="UTF-8"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-WS-Securityoptions.xml"
encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Endpointmanagement.xml"
encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Recordsmanagement.xml"
encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-JAX-WSEndpointConfiguration.xml"
encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-JAX-WSClientConfiguration.xml"
encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</part>
+
+
+<part id="Samples, Tutorials, references">
+ <title>Samples & Tutorials</title>
+ <partintro>
+ <para>
+ Below you find few tutorials on WS-* technologies usage as well as a brief list
of reference links and the list of supported JAX-WS annotations.
+ </para>
+ </partintro>
+ <xi:include href="JBossWS-NativeWS-AddressingTutorial.xml"
encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-NativeWS-ReliableMessagingTutorial.xml"
encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Advancedsamples.xml" encoding="UTF-8"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Asynchronousinvocationssample.xml"
encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Securityandattachmentssample.xml"
encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Articlesandspecs.xml"
encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-JAX-WSAnnotations.xml"
encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</part>
+
+</book>
Added: stack/native/trunk/src/main/doc/JBossWS-NativeUserGuide.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-NativeUserGuide.xml
(rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-NativeUserGuide.xml 2010-11-02 19:25:45 UTC
(rev 13202)
@@ -0,0 +1,884 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-NativeUserGuide"><title>JBossWS-NativeUserGuide</title><para>This
page covers features available in <emphasis role="bold">JBossWS Native
stack only</emphasis>. <link linkend="chap_JBossWS-UserGuide">Please
refer to the common user guide</link> for a basic introduction to JAX-WS programming
as well as documentation on all features, tools, etc. the JBossWS Web Service Framework
provides for every supported stack (including Native stack).</para>
<para> </para><section
id="JBossWS-NativeUserGuide_Secure_endpoints"><title>Secure
endpoints</title><para>Securing an endpoint requires you to <ulink
url="http://jbossws.jboss.org/mediawiki/index.php?title=Authenticati...
the authentication configuration</ulink>.</para><para>Then you might
want to secure the communication between service provider and consumer. This can be done
at different levels:</para><itemizedlist><listitem><para>
<ulink url="http://jbossws.jboss.o!
rg/mediawiki/index.php?title=Secure_transport">Secure the HTTP
transport</ulink> </para></listitem><listitem><para>
WS-Security</para></listitem></itemizedlist></section>
+<section
id="JBossWS-NativeUserGuide_JBossWS_Native_WS_extensions"><title>JBossWS
Native WS-* extensions</title><section
id="JBossWS-NativeUserGuide_WSAddressing"><title>WS-Addressing</title><para>This
section describes how <ulink
url="http://www.w3.org/TR/ws-addr-core">WS-Addressing</ul... can be
used to provide a stateful service endpoint.</para><section
id="JBossWS-NativeUserGuide_Specifications"><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">JSR-261 - Java API for XML Web
Services
Addressing</ulink></para><itemizedlist><listitem><para>
<ulink url="http://www.w3.org/TR/ws-addr-core">Web Services Addressing 1.0
- Core</ulink> </para></listitem><listitem><para> <ulink
url="http://www.w3.org/TR/ws-addr-soap">Web Services Addressing 1.0 - SOAP
Binding</ulink></para></!
listitem></itemizedlist></section>
+<section
id="JBossWS-NativeUserGuide_Addressing_Endpoint"><title>Addressing
Endpoint</title><para>The following endpoint implementation has a set of
operation for a typical stateful shopping chart application.</para><screen
xml:space="preserve"> @WebService(name = "StatefulEndpoint",
targetNamespace = "<ulink
url="http://org.jboss.ws/samples/wsaddressing">http://org.jboss.ws/samples/wsaddressing</ulink>",
serviceName = "TestService")
+ @EndpointConfig(configName = "Standard WSAddressing Endpoint")
+ @HandlerChain(file = "WEB-INF/jaxws-handlers.xml")
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> StatefulEndpointImpl <emphasis
role="bold">implements</emphasis> StatefulEndpoint, ServiceLifecycle
+ {
+ @WebMethod
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> addItem(String item)
+ { ... }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> checkout()
+ { ... }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String getItems()
+ { ... }
+ }
+</screen><para>It uses the <link
linkend="chap_JBossWS-JAX-WSEndpointConfiguration">Standard WSAddressing
Endpoint</link> 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><screen
xml:space="preserve"><handler-chains xmlns="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
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>
+</screen><para>defines an application specific hander that assignes/processes
stateful client ids.</para></section>
+<section
id="JBossWS-NativeUserGuide_Addressing_Client"><title>Addressing
Client</title><para>On the client side there are similar handlers that does
the reverse. It uses the JSR-261 API to add WS-Addressing header elements including the
clientid association.</para><para> The client sets a custom handler chain in
the binding</para><screen xml:space="preserve"> Service
service = Service.create(wsdlURL, serviceName);
+ port1 = (StatefulEndpoint)service.getPort(StatefulEndpoint.class);
+ BindingProvider bindingProvider = (BindingProvider)port1;
+
+ List<Handler> customHandlerChain = <emphasis
role="bold">new</emphasis> ArrayList<Handler>();
+ customHandlerChain.add(<emphasis
role="bold">new</emphasis> ClientHandler());
+ customHandlerChain.add(<emphasis
role="bold">new</emphasis> WSAddressingClientHandler());
+ bindingProvider.getBinding().setHandlerChain(customHandlerChain);
+</screen><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><screen
xml:space="preserve"> <emphasis
role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> AddressingStatefulTestCase <emphasis
role="bold">extends</emphasis> JBossWSTest
+ {
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> testAddItem() <emphasis
role="bold">throws</emphasis> Exception
+ {
+ port1.addItem("Ice Cream");
+ port1.addItem("Ferrari");
+
+ port2.addItem("Mars Bar");
+ port2.addItem("Porsche");
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> testGetItems() <emphasis
role="bold">throws</emphasis> Exception
+ {
+ String items1 = port1.getItems();
+ assertEquals("[Ice Cream, Ferrari]", items1);
+
+ String items2 = port2.getItems();
+ assertEquals("[Mars Bar, Porsche]", items2);
+ }
+ }
+</screen><para><emphasis role="bold">SOAP message
exchange</emphasis></para><para>Below you see the SOAP messages that are
being exchanged.</para><screen
xml:space="preserve"><env:Envelope xmlns:env='<ulink
url="http://schemas.xmlsoap.org/soap/envelope/">http://schem...
xmlns:wsa='<ulink
url="http://schemas.xmlsoap.org/ws/2004/08/addressing">http:...
+ <wsa:To>uri:jbossws-samples-wsaddr/TestService</wsa:To>
+
<wsa:Action>http://org.jboss.ws/addressing/stateful/action</wsa:Action>
+ <wsa:ReferenceParameters>
+ <ns1:clientid xmlns:ns1='<ulink
url="http://somens">http://somens</ulink>'>clientid-1</ns1:clientid>
+
</wsa:ReferenceParameters></env:Header><env:Body>
+ <ns1:addItem xmlns:ns1='<ulink
url="http://org.jboss.ws/samples/wsaddr">http://org.jboss.ws/samples/wsaddr</ulink>'>
+ <String_1>Ice Cream</String_1>
+ </ns1:addItem></env:Body>
+</env:Envelope>
+
+<env:Envelope xmlns:env='<ulink
url="http://schemas.xmlsoap.org/soap/envelope/">http://schem...
xmlns:wsa='<ulink
url="http://schemas.xmlsoap.org/ws/2004/08/addressing">http:...
+
<wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To>
+
<wsa:Action>http://org.jboss.ws/addressing/stateful/actionReply</wsa:Action>
+ <ns1:clientid xmlns:ns1='<ulink
url="http://somens">http://somens</ulink>'>clientid-1</ns1:clientid></env:Header><env:Body>
+ <ns1:addItemResponse xmlns:ns1='<ulink
url="http://org.jboss.ws/samples/wsaddr'/">http://org.jboss.ws/samples/wsaddr'/</ulink>></env:Body>
+</env:Envelope>
+
+ ...
+
+<env:Envelope xmlns:env='<ulink
url="http://schemas.xmlsoap.org/soap/envelope/">http://schem...
+ <env:Header xmlns:wsa='<ulink
url="http://schemas.xmlsoap.org/ws/2004/08/addressing">http:...
+ <wsa:To>uri:jbossws-samples-wsaddr/TestService</wsa:To>
+
<wsa:Action>http://org.jboss.ws/addressing/stateful/action</wsa:Action>
+ <wsa:ReferenceParameters>
+ <ns1:clientid xmlns:ns1='<ulink
url="http://somens">http://somens</ulink>'>clientid-1</ns1:clientid>
+ </wsa:ReferenceParameters>
+ </env:Header>
+ <env:Body>
+ <ns1:getItems xmlns:ns1='<ulink
url="http://org.jboss.ws/samples/wsaddr'/">http://org.jboss.ws/samples/wsaddr'/</ulink>>
+ </env:Body>
+</env:Envelope>
+
+<env:Envelope xmlns:env='<ulink
url="http://schemas.xmlsoap.org/soap/envelope/">http://schem...
+ <env:Header xmlns:wsa='<ulink
url="http://schemas.xmlsoap.org/ws/2004/08/addressing">http:...
+
<wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To>
+
<wsa:Action>http://org.jboss.ws/addressing/stateful/actionReply</wsa:Action>
+ <ns1:clientid xmlns:ns1='<ulink
url="http://somens">http://somens</ulink>'>clientid-1</ns1:clientid>
+ </env:Header>
+ <env:Body>
+ <ns1:getItemsResponse xmlns:ns1='<ulink
url="http://org.jboss.ws/samples/wsaddr">http://org.jboss.ws/samples/wsaddr</ulink>'>
+ <result>[Ice Cream, Ferrari]</result>
+ </ns1:getItemsResponse>
+ </env:Body>
+</env:Envelope></screen></section>
+<section
id="JBossWS-NativeUserGuide_Tutorial"><title>Tutorial</title><para>For
further details please take a look at our <link
linkend="chap_JBossWS-NativeWS-AddressingTutorial">WS-Addressing
Tutorial</link>.</para><para> </para></section>
+</section>
+<section
id="JBossWS-NativeUserGuide_WSBPEL"><title>WS-BPEL</title><para>WS-BPEL
is not supported with JAX-WS, please refer to <ulink
url="http://jbossws.jboss.org/mediawiki/index.php?title=JAX-RPC_User...
User Guide#WS-BPEL</ulink>.</para><para> </para></section>
+<section
id="JBossWS-NativeUserGuide_WSEventing"><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
id="JBossWS-NativeUserGuide_Specifications_431795"><title>Specifications</title><para>WS-Eventing
is defined by the combination of the following
specifications:</para><itemizedlist><listitem><para> <ulink
url="ftp://www6.software.ibm.com/software/developer/library/ws-event...
specification</ulink> </para></listitem><listitem><para>
<ulink url="http://www.w3.org/TR/ws-addr-core">WS-Addressing
Specifications</ulink>
</para></listitem></itemizedlist><para>The following section will
introduce the main eventing actors and their
responsiblities.</para><note><para><para><emphasis
role="bold">Note</emphasis></para><para>The original
eventing specification builds upon WS-Add!
ressing 2004/08. JBossWS however decided to stick to the latest version, which is the W3C
candidate
release.</para><para> </para></para></note></section>
+<section
id="JBossWS-NativeUserGuide_Collaboration"><title>Collaboration</title><ulink
url="http://jbossws.jboss.org/mediawiki/index.php?title=Image:Eventi...
collaboration<orderedlist><listitem><para> An event sink (web service
client) sends a subscription 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 source
(application) emits notification messages through the JBos!
sWS-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
responsibility 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><listitem><para> Create a custom WSDL !
that describes your event source, in respect to the notificati!
on schem
a (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
(web.xml).</para></listitem></itemizedlist><para> </para></section>
+<section
id="JBossWS-NativeUserGuide_Setup_an_event_source_endpoint"><title>Setup
an event source endpoint</title><para>With JAX-WS the event source setup has
actually become quite easy. All you need to do is to subclass your endpoint
implementation from
<computeroutput>AbstractEventSourceEndpoint</computeroutput> and a
subscription manager from
<computeroutput>AbstractSubscriptionManagerEndpoint</computeroutput> and
finally point that implementation to a <ulink
url="http://community.jboss.org/docs/DOC-13541">event source specific
WSDL</ulink>.</para><screen xml:space="preserve"><emphasis
role="bold">package</emphasis>
org.jboss.test.ws.jaxws.samples.wseventing;
+
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+
+<emphasis role="bold">import</emphasis> org.jboss.logging.Logger;
+<emphasis role="bold">import</emphasis>
org.jboss.ws.annotation.EndpointConfig;
+<emphasis role="bold">import</emphasis>
org.jboss.ws.extensions.eventing.jaxws.AbstractEventSourceEndpoint;
+
+/**
+ * @author <ulink
url="mailto:Heiko.Braun@jboss.org">Heiko.Braun@jboss.org</ulink>
+ * @version $Id$
+ * @since 18.01.2007
+ */
+@WebService( (1)
+ name = "EventSource",
+ portName = "EventSourcePort",
+ targetNamespace = "<ulink
url="http://schemas.xmlsoap.org/ws/2004/08/eventing">http://...;,
+ wsdlLocation = "/WEB-INF/wsdl/sysmon.wsdl",
(2)
+ endpointInterface =
"org.jboss.ws.extensions.eventing.jaxws.EventSourceEndpoint")
+@EndpointConfig(configName = "Standard WSAddressing Endpoint")
(3)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> SysmonRegistrationEndpoint <emphasis
role="bold">extends</emphasis> AbstractEventSourceEndpoint { (4)
+
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">final</emphasis> Logger log =
Logger.getLogger(SysmonRegistrationEndpoint.class);
+
+ <emphasis role="bold">protected</emphasis> Logger getLogger()
+ {
+ <emphasis role="bold">return</emphasis> log;
+ }
+}</screen><orderedlist><listitem><para> Of course we need a
<computeroutput>@WebService</computeroutput> 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
id="JBossWS-NativeUserGuide_The_WSDL_that_describes_an_event_source"><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><screen
xml:space="preserve"> <?xml version="1.0"
encoding="UTF-8"?>
+
+ <wsdl:definitions
+ targetNamespace="<ulink
url="http://www.jboss.org/sysmon">http://www.jboss.org/sysmo...
+ xmlns:tns="<ulink
url="http://www.jboss.org/sysmon">http://www.jboss.org/sysmo...
+ xmlns:wse='<ulink
url="http://schemas.xmlsoap.org/ws/2004/08/eventing">http://...
+ xmlns:wsdl='<ulink
url="http://schemas.xmlsoap.org/wsdl/">http://schemas.xmlsoa...
+ xmlns:wsa10='<ulink
url="http://www.w3.org/2005/08/addressing">http://www.w3.org...
+ xmlns:xs='<ulink
url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/200...
+ xmlns:soap="<ulink
url="http://schemas.xmlsoap.org/wsdl/soap/">http://schemas.x...
+
+ <wsdl:import
+(1) namespace='<ulink
url="http://schemas.xmlsoap.org/ws/2004/08/eventing">http://...
+ location='jbwse.wsdl' />
+
+ <wsdl:types>
+
+ <xs:schema targetNamespace='<ulink
url="http://schemas.xmlsoap.org/ws/2004/08/eventing">http://...
+(2) <xs:include schemaLocation='jbwse.xsd'/>
+ </xs:schema>
+
+(3) <xs:schema
+ targetNamespace="<ulink
url="http://www.jboss.org/sysmon">http://www.jboss.org/sysmo...
+ 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="<ulink
url="http://schemas.xmlsoap.org/soap/http">http://schemas.xm...
+ <wsdl:operation name="SysmonOp">
+ <soap:operation soapAction=""/>
+ <wsdl:output>
+ <soap:body use="literal"/>
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:binding></wsdl:definitions>
+</screen><orderedlist><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
id="JBossWS-NativeUserGuide_Emitting_notifications"><title>Emitting
notifications</title><para>JBossWS-Eventing registeres a event dispatcher
within local JNDI tree that can be used to emit notifications from
applications.</para><screen xml:space="preserve">
java:/EventDispatcher
+</screen><para>The event dispatcher interface:</para><screen
xml:space="preserve"> <emphasis
role="bold">public</emphasis> <emphasis
role="bold">interface</emphasis> EventDispatcher
+ {
+ <emphasis role="bold">void</emphasis> dispatch(URI
eventSourceNS, Element payload);
+ }
+</screen><para><emphasis role="bold"> Example notification
</emphasis></para><screen xml:space="preserve">(1) URI
eventSourceURI = <emphasis role="bold">new</emphasis>
URI("<ulink
url="http://http://www.jboss.org/sysmon/SystemInfo">http://h...);
+(2) Element payload = DOMUtils.parse("SOME XML STRING");
+ <emphasis role="bold">try</emphasis>
+ {
+ InitialContext iniCtx = getInitialContext();
+(3) EventDispatcher delegate = (EventDispatcher)
+ iniCtx.lookup(EventingConstants.DISPATCHER_JNDI_NAME);
+(4) delegate.dispatch(eventSourceURI, payload);
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ //
+ }</screen><orderedlist><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> </para><para>The
SubscriptionManager MBean is the actual core component that drives the JBossWS-Eventing
implementation. It can be accessed through the jmx-console.</para><screen
xml:space="preserve">
jboss.ws.eventing:service=SubscriptionManager
+</screen><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><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><para> </para><para> </para></section>
+</section>
+<section
id="JBossWS-NativeUserGuide_WSSecurity"><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><listitem><para> <ulink
url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-me...
Message Security 1.0</ulink>
</para></listitem><listitem><para> <ulink
url="http://docs.oasis-open.org/wss/2004/01/o!
asis-200401-wss-username-token-profile-1.0.pdf">Username Token Profile
1.0</ulink> </para></listitem><listitem><para> <ulink
url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-to...
Token Profile 1.0</ulink> </para></listitem><listitem><para>
<ulink url="http://www.w3.org/TR/xmlenc-core">W3C XML
Encryption</ulink> </para></listitem><listitem><para>
<ulink url="http://www.w3.org/TR/xmldsig-core">W3C XML
Signature</ulink> </para></listitem><listitem><para>
<ulink
url="http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0.html"...
Security Profile 1.0 (Still in
Draft)</ulink></para></listitem></itemizedlist><section
id="JBossWS-NativeUserGuide_Endpoint_configuration"><title>Endpoint
configuration</title><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 corresponding
hand!
ler configuration. The preferred way is to reference a predefi!
ned <lin
k
linkend="chap_JBossWS-JAX-WSEndpointConfiguration">JAX-WS_Endpoint_Configuration</link>
or <link
linkend="chap_JBossWS-JAX-WSClientConfiguration">JAX-WS_Client_Configuration</link>
respectively.</para><note><para><para><emphasis><emphasis
role="bold">Note</emphasis></emphasis></para><para><emphasis>You
need to setup both the endpoint configuration and the WSSE declarations. That's two
separate steps.</emphasis></para></para></note></section>
+<section
id="JBossWS-NativeUserGuide_Server_side_WSSE_declaration_jbosswsseserverxml"><title>Server
side WSSE declaration (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><screen
xml:space="preserve"> <jboss-ws-security xmlns="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ <ulink
url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.x...
+ (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>
+</screen><para> </para><orderedlist><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 encrypted 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 signed.
</para></listitem></orderedlist><para>By default an endpoint does
not use the WS-Security configuration. Use the proprietary @EndpointConfig annotation to
set the config name. See <link
linkend="chap_JBossWS-JAX-WSEndpointConfiguration">JAX-WS_Endpoint_Configuration</link>
for the list of available config names.</para><screen
xml:space="preserve">@WebService
+@EndpointConfig(configName = "Standard WSSecurity Endpoint")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> HelloJavaBean
+{
+ ...
+}
+</screen></section>
+<section
id="JBossWS-NativeUserGuide_Client_side_WSSE_declaration_jbosswsseclientxml"><title>Client
side WSSE declaration (jboss-wsse-client.xml)</title><screen
xml:space="preserve"> <jboss-ws-security xmlns="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ <ulink
url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.x...
+ (1) <config>
+ (2) <sign type="x509v3" alias="wsse"/>
+ (3) <requires>
+ (4) <signature/>
+ </requires>
+ </config>
+ </jboss-ws-security>
+</screen><para> </para><orderedlist><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> </para><section
id="JBossWS-NativeUserGuide_Client_side_key_store_configuration"><title>Client
side key store configuration</title><para>We did not specify !
a key store or trust store, because client app uses 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 to specify them in the client descriptor.</para><para>Here
is an excerpt from the JBossWS samples:</para><screen
xml:space="preserve"><sysproperty
key="org.jboss.ws.wsse.keyStore"
+
value="${tests.output.dir}/resources/jaxrpc/samples/wssecurity/wsse.keystore"/>
+<sysproperty key="org.jboss.ws.wsse.trustStore"
+
value="${tests.output.dir}/resources/jaxrpc/samples/wssecurity/wsse.truststore"/>
+<sysproperty key="org.jboss.ws.wsse.keyStorePassword"
value="jbossws"/>
+<sysproperty key="org.jboss.ws.wsse.trustStorePassword"
value="jbossws"/>
+<sysproperty key="org.jboss.ws.wsse.keyStoreType"
value="jks"/>
+<sysproperty key="org.jboss.ws.wsse.trustStoreType"
value="jks"/>
+</screen><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</para><screen
xml:space="preserve"> <env:Envelope xmlns:env="<ulink
url="http://schemas.xmlsoap.org/soap/envelope/">http://schem...
+ <env:Header>
+ <wsse:Security env:mustUnderstand="1" ...>
+ <wsu:Timestamp
wsu:Id="timestamp">...</wsu:Timestamp>
+ <wsse:BinarySecurityToken ...>
+ ...
+ </wsse:BinarySecurityToken>
+ <ds:Signature xmlns:ds="<ulink
url="http://www.w3.org/2000/09/xmldsig#">http://www.w3.org/2...
+ ...
+ </ds:Signature>
+ </wsse:Security>
+ </env:Header>
+ <env:Body wsu:Id="element-1-1140197309843-12388840" ...>
+ <ns1:echoUserType xmlns:ns1="<ulink
url="http://org.jboss.ws/samples/wssecurity">http://org.jboss.ws/samples/wssecurity</ulink>">
+ <UserType_1 xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ <msg>Kermit</msg>
+ </UserType_1>
+ </ns1:echoUserType>
+ </env:Body>
+ </env:Envelope></screen></section>
+</section>
+<section
id="JBossWS-NativeUserGuide_Installing_the_BouncyCastle_JCE_provider_JDK_14"><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</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><screen
xml:space="preserve">
security.provider.<n>=org.bouncycastle.jce.provider.BouncyCastleProvider
+</screen><para>Where <n> is the preference you want the
provider at.</para><note><para><para><emphasis><emphasis
role="bold">Note</emphasis></emphasis></para><para><emphasis>Issues
may arise if the Sun providers are not
first.</emphasis></para></para></note><para><emphasis>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.</emphasis></para></section>
+<section
id="JBossWS-NativeUserGuide_Keystore_truststore__What"><title>Keystore,
truststore -
What?</title><note><para><para><emphasis><emphasis
role="bold">Note</emphasis></emphasis></para><para><emphasis>If
you having a hard time understanding how the different trust- and keystore configurations
are used for signature and encryption, then read this thread first: <link
linkend="chap_index">http://www.jboss.org/index.html?module=...
+<section
id="JBossWS-NativeUserGuide_Advanced_configuration"><title>Advanced
configuration</title><para>Further information and examples covering <link
linkend="chap_JBossWS-WS-Securityoptions">advanced WS-Security configuration
options</link> are available. Those might help when specific settings are required
to obtain interoperability with other vendors' WS-Security
implementation.</para></section>
+</section>
+<section
id="JBossWS-NativeUserGuide_WSReliable_Messaging"><title>WS-Reliable
Messaging</title><para>WS-Reliable Messaging specifies how a reliable web
service communication can be achieved.</para><para>Please take a look at our
<link
linkend="chap_JBossWS-NativeWS-ReliableMessagingTutorial">WS-Reliable
Messaging Tutorial</link> for configuration details.</para></section>
+<section
id="JBossWS-NativeUserGuide_WSTransaction"><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">JBoss
Transactions Project</ulink></para></section>
+<section id="JBossWS-NativeUserGuide_XML_Registries"><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
id="JBossWS-NativeUserGuide_Apache_jUDDI_Configuration"><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.s!
ar</para><para>Let us look at the individual configuration items that can be
changed.</para><para>DataSources configuration</para><screen
xml:space="preserve"> <!-- Datasource to Database-->
+ <attribute
name="DataSourceUrl">java:/DefaultDS</attribute>
+</screen><para>Database Tables (Should they be created on start, Should they
be dropped on stop, Should they be dropped on start etc)</para><screen
xml:space="preserve"> <!-- Should all tables be created on
Start-->
+ <attribute
name="CreateOnStart">false</attribute>
+ <!-- Should all tables be dropped on Stop-->
+ <attribute
name="DropOnStop">true</attribute>
+ <!-- Should all tables be dropped on Start-->
+ <attribute
name="DropOnStart">false</attribute>
+</screen><para>JAXR Connection Factory to be bound in JNDI. (Should it be
bound? and under what name?)</para><screen
xml:space="preserve"> <!-- Should I bind a Context to which
JaxrConnectionFactory bound-->
+ <attribute
name="ShouldBindJaxr">true</attribute>
+
+ <!-- Context to which JaxrConnectionFactory to bind to. If you have remote
clients, please bind it to the global namespace(default behavior).
+ To just cater to clients running on the same VM as JBoss, change to java:/JAXR
-->
+ <attribute
name="BindJaxr">JAXR</attribute></screen><para> </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><screen
xml:space="preserve"> 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');</screen></section>
+<section
id="JBossWS-NativeUserGuide_JBoss_JAXR_Configuration"><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><screen
xml:space="preserve">
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
+</screen><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><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><screen
xml:space="preserve"> System.setProperty(propertyname,
propertyvalue);</screen></section>
+<section id="JBossWS-NativeUserGuide_JAXR_Sample_Code"><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><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 b!
y 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><screen xml:space="preserve"> String queryurl =
System.getProperty("jaxr.query.url", "<ulink
url="http://localhost:8080/juddi/inqui!
ry">http://localhost:8080/juddi/inquiry</ulink>");
+ String puburl = System.getProperty("jaxr.publish.url", "<ulink
url="http://localhost:8080/juddi/publish">http://localhost:8080/juddi/publish</ulink>");
+
+ Properties props = <emphasis role="bold">new</emphasis>
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();
+</screen><para>Authentication with the registry.</para><screen
xml:space="preserve"> /**
+ * Does authentication with the uddi registry
+ */
+ <emphasis role="bold">protected</emphasis> <emphasis
role="bold">void</emphasis> login() <emphasis
role="bold">throws</emphasis> JAXRException
+ {
+ PasswordAuthentication passwdAuth = <emphasis
role="bold">new</emphasis> PasswordAuthentication(userid,
passwd.toCharArray());
+ Set creds = <emphasis role="bold">new</emphasis> HashSet();
+ creds.add(passwdAuth);
+
+ connection.setCredentials(creds);
+ }
+</screen><para>Save a Business</para><screen
xml:space="preserve"> /**
+ * Creates a Jaxr Organization with 1 or more services
+ */
+ <emphasis role="bold">protected</emphasis> Organization
createOrganization(String orgname) <emphasis
role="bold">throws</emphasis> 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(<emphasis
role="bold">false</emphasis>);
+ serviceBinding.setAccessURI("<ulink
url="http://testjboss.org">http://testjboss.org</ulink>");
+
+ // 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(<emphasis
role="bold">null</emphasis>);
+ PostalAddress address = blm.createPostalAddress("111", "My
Drive", "BuckHead", "GA", "USA", "1111-111",
"");
+ Collection postalAddresses = <emphasis
role="bold">new</emphasis> ArrayList();
+ postalAddresses.add(address);
+ Collection emailAddresses = <emphasis
role="bold">new</emphasis> ArrayList();
+ EmailAddress emailAddress = blm.createEmailAddress("<ulink
url="mailto:anil@apache.org">anil@apache.org</ulink>");
+ emailAddresses.add(emailAddress);
+
+ Collection numbers = <emphasis role="bold">new</emphasis>
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);
+ <emphasis role="bold">return</emphasis> org;
+ }
+</screen><para>Query a Business</para><screen
xml:space="preserve"> /**
+ * Locale aware Search a business in the registry
+ */
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> searchBusiness(String bizname) <emphasis
role="bold">throws</emphasis> JAXRException
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ // Get registry service and business query manager
+ this.getJAXREssentials();
+
+ // Define find qualifiers and name patterns
+ Collection findQualifiers = <emphasis
role="bold">new</emphasis> ArrayList();
+ findQualifiers.add(FindQualifier.SORT_BY_NAME_ASC);
+ Collection namePatterns = <emphasis
role="bold">new</emphasis> 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, <emphasis role="bold">null</emphasis>);
+
+ // check how many organisation we have matched
+ Collection orgs = response.getCollection();
+ <emphasis role="bold">if</emphasis> (orgs == <emphasis
role="bold">null</emphasis>)
+ {
+ log.debug(" -- Matched 0 orgs");
+
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ log.debug(" -- Matched " + orgs.size() + " organizations --
");
+
+ // then step through them
+ <emphasis role="bold">for</emphasis> (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);
+ }
+ }
+ }
+ <emphasis role="bold">finally</emphasis>
+ {
+ connection.close();
+ }
+ }
+</screen><para>For more examples of code using the JAXR API, please refer to
the resources in the Resources
Section.</para><para> </para></section>
+<section
id="JBossWS-NativeUserGuide_Trouble_Shooting"><title>Trouble
Shooting</title><itemizedlist><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/">TCPMon</ulink></p...
+<section
id="JBossWS-NativeUserGuide_Resources"><title>Resources</title><itemizedlist><listitem><para>
<ulink
url="http://java.sun.com/webservices/jaxr/learning/tutorial/index.ht...
Tutorial and Code Camps</ulink>
</para></listitem><listitem><para> <ulink
url="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/">J2EE 1.4
Tutorial</ulink> </para></listitem><listitem><para>
<ulink url="http://www.amazon.com/exec/obidos/ASIN/0321146182">J2EE Web
Services by Richard
Monson-Haefel</ulink></para></listitem></itemizedlist><para> </para></section>
+</section>
+<section
id="JBossWS-NativeUserGuide_WSPolicy"><title>WS-Policy</title><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
id="JBossWS-NativeUserGuide_Specification"><title>Specification</title><para>WS-Policy
is defined by the combination of the following specifications:</para><screen
xml:space="preserve"> * <ulink
url="http://www.w3.org/Submission/WS-Policy/">WS-Policy
specification</ulink> * <ulink
url="http://www.w3.org/Submission/WS-PolicyAttachment/">WS-P...
specification</ulink></screen></section>
+<section
id="JBossWS-NativeUserGuide_WSPolicy_Example"><title>WS-Policy
Example</title><para>Please take a look to our <link
linkend="chap_JBossWS-NativeWS-ReliableMessagingTutorial">WS-Reliable
Messaging Tutorial</link> to see how to combine WS-Policy specification with other
technologies.</para></section>
+<section
id="JBossWS-NativeUserGuide_Using_policies_in_a_user_provided_wsdl"><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><screen xml:space="preserve">@WebService(name =
"Hello",
+targetNamespace = "<ulink
url="http://org.jboss.ws/samples/wssecuritypolicy">http://org.jboss.ws/samples/wssecuritypolicy</ulink>",
+wsdlLocation="WEB-INF/wsdl/HelloService.wsdl")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> HelloJavaBean
+{
+ <emphasis role="bold">private</emphasis> Logger log =
Logger.getLogger(HelloJavaBean.class);
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> UserType
echoUserType(@WebParam(name = "user") UserType in0)
+ {
+ log.info(in0);
+ <emphasis role="bold">return</emphasis> in0;
+ }
+}
+</screen><screen xml:space="preserve"><?xml
version="1.0" encoding="UTF-8"?>
+<definitions name='HelloService' targetNamespace='<ulink
url="http://org.jboss.ws/samples/wssecuritypolicy">http://org.jboss.ws/samples/wssecuritypolicy</ulink>'
xmlns='<ulink
url="http://schemas.xmlsoap.org/wsdl/">http://schemas.xmlsoa...
xmlns:ns1='<ulink
url="http://org.jboss.ws/samples/wssecurity">http://org.jboss.ws/samples/wssecurity</ulink>'
xmlns:soap='<ulink
url="http://schemas.xmlsoap.org/wsdl/soap/">http://schemas.x...
xmlns:tns='<ulink
url="http://org.jboss.ws/samples/wssecuritypolicy">http://org.jboss.ws/samples/wssecuritypolicy</ulink>'
xmlns:wsp='<ulink
url="http://schemas.xmlsoap.org/ws/2004/09/policy">http://sc...
xmlns:xsd='<ulink
url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/200...
+ <xs:schema targetNamespace='<ulink
url="http://org.jboss.ws/samples/wssecurity">http://org.jboss.ws/samples/wssecurity</ulink>'
version='1.0' xmlns:xs='<ulink
url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/200...
+ <xs:complexType 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='<ulink
url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecur...
+ <wsp:All>
+ <sp:jboss-ws-security xmlns:sp='<ulink
url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.x...
+
<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></portType><binding
name='HelloBinding' type='tns:Hello'>
+ <wsp:PolicyReference URI='#X509EndpointPolicy'/>
+ <soap:binding style='rpc' transport='<ulink
url="http://schemas.xmlsoap.org/soap/http'/">http://sche...
+ <operation name='echoUserType'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body namespace='<ulink
url="http://org.jboss.ws/samples/wssecuritypolicy">http://org.jboss.ws/samples/wssecuritypolicy</ulink>'
use='literal'/>
+ </input>
+ <output>
+ <soap:body namespace='<ulink
url="http://org.jboss.ws/samples/wssecuritypolicy">http://org.jboss.ws/samples/wssecuritypolicy</ulink>'
use='literal'/>
+ </output>
+ </operation></binding><service
name='HelloService'>
+ <port binding='tns:HelloBinding' name='HelloPort'>
+ <soap:address location='REPLACE_WITH_ACTUAL_URL'/>
+ </port></service>
+</definitions>
+</screen><para>Please note in the wsdl file the wsp:Policy element and the
wsp:PolicyReference in 'HelloBinding' binding
Element.</para><para> </para></section>
+<section
id="JBossWS-NativeUserGuide_Using_policies_with_JBoss_annotations"><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> </para><screen
xml:space="preserve">@Target(ElementType.TYPE)
+(a)Retention(RetentionPolicy.RUNTIME)
+<emphasis role="bold">public</emphasis> @<emphasis
role="bold">interface</emphasis> PolicyAttachment {
+ Policy[] value();
+}</screen><screen
xml:space="preserve">@Retention(RetentionPolicy.RUNTIME)
+<emphasis role="bold">public</emphasis> @<emphasis
role="bold">interface</emphasis> Policy {
+
+ <emphasis role="bold">public</emphasis> String
policyFileLocation();
+
+ <emphasis role="bold">public</emphasis> PolicyScopeLevel
scope();
+}
+</screen><para>And here you have the previous section example re-implemented
using annotations and xml policy file:</para><screen
xml:space="preserve">@WebService(name = "Hello", targetNamespace =
"<ulink
url="http://org.jboss.ws/samples/wssecurityAnnotatedpolicy">http://org.jboss.ws/samples/wssecurityAnnotatedpolicy</ulink>")
+@PolicyAttachment({@Policy( policyFileLocation="WEB-INF/Policy.xml", scope =
PolicyScopeLevel.WSDL_PORT ) })
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> HelloJavaBean
+{
+ <emphasis role="bold">private</emphasis> Logger log =
Logger.getLogger(HelloJavaBean.class);
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> UserType
echoUserType(@WebParam(name = "user") UserType in0)
+ {
+ log.info(in0);
+ <emphasis role="bold">return</emphasis> in0;
+ }
+}
+</screen><screen xml:space="preserve"><?xml
version="1.0" encoding="UTF-8"?><wsp:Policy
wsu:Id="X509EndpointPolicy" xmlns:wsp="<ulink
url="http://schemas.xmlsoap.org/ws/2004/09/policy">http://sc...
+ xmlns:wsu="<ulink
url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecur...
+ <wsp:ExactlyOne>
+ <wsp:All>
+ <sp:jboss-ws-security xmlns:sp="<ulink
url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.x...
+
<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 type="x509v3"
alias="wsse"/>
+ <sp:requires>
+ <sp:encryption/>
+ </sp:requires>
+ </sp:config>
+ </sp:jboss-ws-security>
+ </wsp:All>
+ </wsp:ExactlyOne>
+
</wsp:Policy></screen><para> </para><para> </para><para> </para></section>
+</section>
+</section>
+<section
id="JBossWS-NativeUserGuide_JMS_Transport_Clients"><title>JMS Transport
Clients</title><para>Since jbossws-2.0.3 we support JAX-WS clients that use
JMS transport.</para><para>JMS transport is activated on the client side when
the endpoint location uses the 'jms' URL schema</para><screen
xml:space="preserve"> <binding name='JMSBinding'
type='tns:OrganizationJMSEndpoint'>
+ <soap:binding style='rpc' transport='<ulink
url="http://www.example.org/2006/06/soap/bindings/JMS/'/"&g...
+ <operation name='getContactInfo'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body namespace='<ulink
url="http://org.jboss.ws/samples/jmstransport">http://org.jboss.ws/samples/jmstransport</ulink>'
use='literal'/>
+ </input>
+ <output>
+ <soap:body namespace='<ulink
url="http://org.jboss.ws/samples/jmstransport">http://org.jboss.ws/samples/jmstransport</ulink>'
use='literal'/>
+ </output>
+ </operation>
+ </binding>
+
+ <service name='OrganizationJMSEndpointService'>
+ <port binding='tns:JMSBinding' name='JMSEndpointPort'>
+ <soap:address
location='jms://queue/RequestQueue?replyToName=queue/ResponseQueue'/>
+ </port>
+ </service>
+</screen><para>The service that implements the JMS remote connection is
loaded using the key</para><screen xml:space="preserve">
org.jboss.ws.core.client.RemoteConnection.jms
+</screen><para>Like any other service, this can be overwritten using a system
property.</para><para>The JAX-WS client code is essentially no different from
a client using HTTP as transport</para><screen
xml:space="preserve"> <emphasis
role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> testJMSEndpointPort() <emphasis
role="bold">throws</emphasis> Exception
+ {
+ URL wsdlURL = <emphasis role="bold">new</emphasis>
File("resources/jaxws/samples/jmstransport/jmsservice.wsdl").toURL();
+ QName serviceName = <emphasis role="bold">new</emphasis>
QName("http://org.jboss.ws/samples/jmstransport",
"OrganizationJMSEndpointService");
+ QName portName = <emphasis role="bold">new</emphasis>
QName("http://org.jboss.ws/samples/jmstransport", "JMSEndpointPort");
+
+ Service service = Service.create(wsdlURL, serviceName);
+ Organization port = service.getPort(portName, Organization.class);
+
+ String res = port.getContactInfo("mafia");
+ assertEquals("The 'mafia' boss is currently out of office, please call
again.", res);
+ }
+</screen><para> </para><para> </para></section>
+<section
id="JBossWS-NativeUserGuide_DataBinding"><title>DataBinding</title><section
id="JBossWS-NativeUserGuide_Using_JAXB_with_non_annotated_classes"><title>Using
JAXB with non annotated classes</title><para>JAXB is heavily driven by Java
Annotations on the Java Bindings. It currently doesn't support an external binding
configuration. This recently became an issue for us on JBossESB since the JBossWS 2.0.0
native SOAP stack uses JAXB to perform the SOAP to Java bindings (see 1, 2). It's an
issue for JBossESB simply because it needs to be able to support user definition of
JBossWS native Webservice Endpoints (e.g. JSR 181) using Java typesets that have not been
"JAXB Annotated" (see JAXB Introductions On JBossWS).</para><para>In
order to support this, we built on a JAXB RI feature whereby it allows you to specify a
RuntimeInlineAnnotationReader implementation during JAXBContext creation (see
JAXBRIContext).</para><para>We call this feature "JAXB Annotation
Introduction" an!
d we've made it available for general consumption i.e. it can be checked out, built
and used from SVN:</para><itemizedlist><listitem><para> <ulink
url="http://anonsvn.jboss.org/repos/jbossws/projects/jaxbintros/&quo...
</para></listitem></itemizedlist><para>Complete documentation can
be found here:</para><itemizedlist><listitem><para> <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JAXBIntroductions"...
+<section id="JBossWS-NativeUserGuide__Mapping_of_xsdany"><title>
Mapping of xsd:any</title><itemizedlist><listitem><para> <ulink
url="https://jaxb.dev.java.net/guide/Mapping_of__xs_any___.html"...
+</section>
+<section
id="JBossWS-NativeUserGuide_Attachments"><title>Attachments</title><section
id="JBossWS-NativeUserGuide_MTOMXOP"><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><listitem><para><ulink
url="http://www.w3.org/TR/soap12-mtom/">SOAP Message Transmission
Optimization Mechanism (MTOM)</ulink>
</para></listitem><listitem><para><ulink
url="http://www.w3.org/TR/xop10/">XML-binary Optimized Packaging
(XOP)</ulink></para></listitem></itemizedlist><para> </para><section
id="JBossWS-NativeUserGuide_Supported_MTOM_parameter_types"><title>Supported
MTOM parameter types</title><informaltable><tgroup
cols="2"><colspec colnum="1"
colname="col1"/><colspec colnum="2"
colname="col2"/><thead><row><entry>image/jpeg</entry><entry>java.awt.Image</entry></r!
ow></thead><tbody><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></informaltable><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><note><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></para></note></section>
+<section
id="JBossWS-NativeUserGuide_Enabling_MTOM_per_endpoint"><title>Enabling
MTOM per endpoint</title><para>On the server side MTOM processing is enabled
through the <computeroutput>@BindingType</computeroutput> 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><screen
xml:space="preserve"><emphasis
role="bold">package</emphasis>
org.jboss.test.ws.jaxws.samples.xop.doclit;
+
+<emphasis role="bold">import</emphasis> javax.ejb.Remote;
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+<emphasis role="bold">import</emphasis>
javax.jws.soap.SOAPBinding;
+<emphasis role="bold">import</emphasis> 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)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">interface</emphasis> MTOMEndpoint {
+
+ [...]
+}
+</screen><orderedlist><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 <computeroutput>Binding</computeroutput> API to
enable MTOM (Excerpt taken from the
<computeroutput>org.jboss.test.ws.jaxws.samples.xop.doclit.XOPTestCase</computeroutput>):</para><screen
xml:space="preserve">[...]
+Service service = Service.create(wsdlURL, serviceName);
+port = service.getPort(MTOMEndpoint.class);
+
+// enable MTOM
+binding = (SOAPBinding)((BindingProvider)port).getBinding();
+binding.setMTOMEnabled(<emphasis role="bold">true</emphasis>);
+
+</screen><para> </para><note><para><para><emphasis
role="bold">Note</emphasis></para><para>You might as well
use the JBossWS configuration templates to setup deployment
defaults.</para></para></note></section>
+</section>
+<section
id="JBossWS-NativeUserGuide_SwaRef"><title>SwaRef</title><para><ulink
url="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24....
Attachment Profile 1.0</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 <ulink url="http://www.ietf.org/rfc/rfc2111.txt">RFC
2111</ulink>.</para><section
id="JBossWS-NativeUserGuide_Using_SwaRef_with_JAXWS_endpoints"><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 <computeroutput>DataHandler</computeroutput> types is to annotate a payl!
oad bean with the <computeroutput>@XmlAttachmentRef</computeroutput>
annotation as shown below:</para><screen xml:space="preserve">/**
+* Payload bean that will use SwaRef encoding
+*/
+@XmlRootElement
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> DocumentPayload
+{
+ <emphasis role="bold">private</emphasis> DataHandler data;
+
+ <emphasis role="bold">public</emphasis> DocumentPayload()
+ {
+ }
+
+ <emphasis role="bold">public</emphasis>
DocumentPayload(DataHandler data)
+ {
+ this.data = data;
+ }
+
+ @XmlElement
+ @XmlAttachmentRef
+ <emphasis role="bold">public</emphasis> DataHandler getData()
+ {
+ <emphasis role="bold">return</emphasis> data;
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> setData(DataHandler data)
+ {
+ this.data = data;
+ }
+}
+</screen><para>With document wrapped endpoints you may even specify the
<computeroutput>@XmlAttachmentRef</computeroutput> annotation on the service
endpoint interface:</para><screen xml:space="preserve">@WebService
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">interface</emphasis> DocWrappedEndpoint
+{
+ @WebMethod
+ DocumentPayload beanAnnotation(DocumentPayload dhw, String test);
+
+ @WebMethod
+ @XmlAttachmentRef
+ DataHandler parameterAnnotation(@XmlAttachmentRef DataHandler data, String test);
+
+}
+</screen><para>The message would then refer to the attachment part by
CID:</para><screen xml:space="preserve"><env:Envelope
xmlns:env='<ulink
url="http://schemas.xmlsoap.org/soap/envelope/">http://schem...
+ <ns2:parameterAnnotation xmlns:ns2='<ulink
url="http://swaref.samples.jaxws.ws.test.jboss.org/">http://...
+ <arg0>cid:0-1180017772935-32455963@ws.jboss.org</arg0>
+ <arg1>Wrapped test</arg1>
+ </ns2:parameterAnnotation></env:Body>
+</env:Envelope></screen></section>
+<section
id="JBossWS-NativeUserGuide_Starting_from_WSDL"><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><screen
xml:space="preserve"><element name="data"
type="wsi:swaRef"
+xmlns:wsi="<ulink
url="http://ws-i.org/profiles/basic/1.1/xsd">http://ws-i.org...
+</screen><para>Any wsi:swaRef schema type would then be mapped to
DataHandler.</para><para> </para></section>
+</section>
+</section>
+<section
id="JBossWS-NativeUserGuide_Standard_Annotations"><title>Standard
Annotations</title><section
id="JBossWS-NativeUserGuide_PostConstruct_and_PreDestroy_annotations"><title>PostConstruct
and PreDestroy annotations</title><para>Users can use standard Java
<emphasis role="bold">javax.annotation.PostConstruct</emphasis> and
<emphasis role="bold">javax.annotation.PreDestroy</emphasis>
annotations for service lifecycle notification on all POJO endpoints. Here's the
sample POJO bean:</para><screen xml:space="preserve">@WebService(
+ serviceName = "EndpointService",
+ targetNamespace = "http://yourorganization.com/service",
+ endpointInterface="com.yourorganization.EndpointInterface"
+)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">final</emphasis> <emphasis
role="bold">class</emphasis> EndpointImpl
+{
+
+ @PostConstruct
+ <emphasis role="bold">protected</emphasis> <emphasis
role="bold">void</emphasis> init()
+ {
+ // lifecycle method for initialization
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String echo(String msg)
+ {
+ <emphasis role="bold">return</emphasis> msg;
+ }
+
+ @PreDestroy
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">void</emphasis> cleanUp()
+ {
+ // lifecycle method for cleanup
+ }
+
+}
+</screen></section>
+</section>
+<section
id="JBossWS-NativeUserGuide_JBossWSNative_JAXWS_Extensions"><title>JBossWS-Native
JAX-WS Extensions</title><para>This section describes propriatary JBoss
extensions to JAX-WS, provided for JBossWS-Native stack only. Please refer to the <link
linkend="chap_JBossWS-UserGuide">common user guide</link> for further
JBossWS Extensions.</para><para> </para><section
id="JBossWS-NativeUserGuide_Proprietary_Annotations"><title>Proprietary
Annotations</title><para>For the set of standard annotations, please have a
look at <link
linkend="chap_JBossWS-JAX-WSAnnotations">JAX-WS_Annotations</link>.</para><section
id="JBossWS-NativeUserGuide_EndpointConfig"><title>EndpointConfig</title><screen
xml:space="preserve">/**
+ * 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 })
+<emphasis role="bold">public</emphasis> @<emphasis
role="bold">interface</emphasis> 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() <emphasis role="bold">default</emphasis>
"";
+
+ /**
+ * 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() <emphasis role="bold">default</emphasis>
"";
+}
+</screen><para> </para></section>
+<section
id="JBossWS-NativeUserGuide_Documentation"><title>Documentation</title><screen
xml:space="preserve"><emphasis
role="bold">package</emphasis> org.jboss.ws.annotation;
+
+/**
+ * Annotation to be used to add wsdl:documentation elements to the generated wsdl.
+ *
+ * @author alessio.soldano(a)jboss.org
+ * @since 15-Jan-2008
+ */
+(a)Target({ElementType.TYPE, ElementType.METHOD})
+(a)Retention(RetentionPolicy.RUNTIME)
+<emphasis role="bold">public</emphasis> @<emphasis
role="bold">interface</emphasis> Documentation
+{
+ <emphasis role="bold">public</emphasis> String content();
+}
+</screen></section>
+<section
id="JBossWS-NativeUserGuide_SchemaValidation"><title>SchemaValidation</title><screen
xml:space="preserve">/**
+ * This feature represents the use of schema validation with a
+ * web service.
+ *
+ * @author Thomas.Diesler(a)jboss.com
+ * @since 29-Feb-2008
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = { ElementType.TYPE })
+<emphasis role="bold">public</emphasis> @<emphasis
role="bold">interface</emphasis> SchemaValidation
+{
+ /**
+ * Optional property for the schema location. If this is not specified the schema
+ * will be attempted to extract from the WSDL.
+ *
+ * The syntax is the same as for schemaLocation attributes in instance documents: e.g,
"http://www.example.com file_name.xsd".
+ */
+ String schemaLocation() <emphasis role="bold">default</emphasis>
"";
+
+ /**
+ * Optional property for the error handler.
+ * If this is not specified the @{ValidationErrorHandler} will be used.
+ */
+ Class errorHandler() <emphasis role="bold">default</emphasis>
StrictlyValidErrorHandler.class;
+
+ /**
+ * Specifies if the feature is enabled or disabled
+ */
+ <emphasis role="bold">boolean</emphasis> enabled() <emphasis
role="bold">default</emphasis> <emphasis
role="bold">true</emphasis>;
+}
+</screen></section>
+<section
id="JBossWS-NativeUserGuide_FastInfoset"><title>FastInfoset</title><screen
xml:space="preserve">/**
+ * This feature represents the use of FastInfoset
+ *
+ * @author Thomas.Diesler(a)jboss.com
+ * @since 29-Feb-2008
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = { ElementType.TYPE })
+<emphasis role="bold">public</emphasis> @<emphasis
role="bold">interface</emphasis> FastInfoset {
+
+ /**
+ * Specifies if the feature is enabled or disabled
+ */
+ <emphasis role="bold">boolean</emphasis> enabled() <emphasis
role="bold">default</emphasis> <emphasis
role="bold">true</emphasis>;
+}
+</screen></section>
+<section
id="JBossWS-NativeUserGuide_JsonEncoding"><title>JsonEncoding</title><screen
xml:space="preserve">/**
+ * This feature represents the use of JSON encoding
+ *
+ * @author Thomas.Diesler(a)jboss.com
+ * @since 29-Feb-2008
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = { ElementType.TYPE })
+<emphasis role="bold">public</emphasis> @<emphasis
role="bold">interface</emphasis> JsonEncoding {
+
+ /**
+ * Specifies if the feature is enabled or disabled
+ */
+ <emphasis role="bold">boolean</emphasis> enabled() <emphasis
role="bold">default</emphasis> <emphasis
role="bold">true</emphasis>;
+}
+</screen></section>
+</section>
+<section
id="JBossWS-NativeUserGuide_Proprietary_WebServiceFeatures"><title>Proprietary
WebServiceFeatures</title><section
id="JBossWS-NativeUserGuide_Schema_validation_for_incomingoutgoing_messages"><title>Schema
validation for incoming/outgoing messages</title><para>On the client, schema
validation can be enabled using the SchemaValidationFeature</para><screen
xml:space="preserve"><emphasis
role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis>
org.jboss.ws.feature.SchemaValidationFeature;
+
+Service service = Service.create(wsdlURL, SERVICE_NAME);
+SchemaValidationFeature feature = <emphasis
role="bold">new</emphasis> SchemaValidationFeature(xsdURL.toString());
+MyTest port = service.getPort(MyTest.class, feature);
+</screen><para>You can explicitly set the schema location and the error
handler. If the schema location is not set, the schema will be extracted from the
WSDL.</para><para>The default error handler is strict and causes a SAX
exception when the message does not conform to the schema.</para><para>The
SchemaValidationFeature has an equivalent @SchemaValidation annotation that can be used on
the endpoint.</para></section>
+<section
id="JBossWS-NativeUserGuide_Support_for_FastInfoset"><title>Support for
FastInfoset</title><para>On the client, FastInfoset can be enabled using the
FastInfosetFeature</para><screen xml:space="preserve"><emphasis
role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis>
org.jboss.ws.feature.FastInfosetFeature;
+
+Serviceservice = Service.create(wsdlURL, serviceName);
+FastInfosetFeature feature = <emphasis role="bold">new</emphasis>
FastInfosetFeature();
+FastInfoset port = service.getPort(FastInfoset.class, feature);
+</screen><para>The FastInfosetFeature has an equivalent @FastInfoset
annotation that can be used on the endpoint.</para></section>
+<section
id="JBossWS-NativeUserGuide_Support_for_JSON_data_binding"><title>Support
for JSON data binding</title><para>On the client, JSON data binding can be
enabled using the JsonEncodingFeature</para><screen
xml:space="preserve"><emphasis
role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis>
org.jboss.ws.feature.JsonEncodingFeature;
+
+Service service = Service.create(wsdlURL, SERVICE_NAME);
+JsonEncodingFeature feature = <emphasis role="bold">new</emphasis>
JsonEncodingFeature();
+JsonPort port = service.getPort(JsonPort.class, feature);
+</screen><para>The JsonEncodingFeature has an equivalent @JsonEncoding
annotation that can be used on the endpoint.</para></section>
+<section
id="JBossWS-NativeUserGuide_Chunked_encoding_setup"><title>Chunked
encoding setup</title><para>On the client, the chunked encoding can be
disabled (it's enabled by default) or the chunks size can be configured using the
ChunkedEncodingFeature</para><screen
xml:space="preserve"><emphasis
role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis>
org.jboss.ws.feature.ChunkedEncodingFeature;
+
+Service service = Service.create(wsdlURL, SERVICE_NAME);
+ChunkedEncodingFeature feature = <emphasis
role="bold">new</emphasis> ChunkedEncodingFeature(<emphasis
role="bold">false</emphasis>); //false to disable
+MyPort port = service.getPort(MyPort.class, feature);
+</screen><para>Alternatively, the <emphasis
role="bold">StubExt.PROPERTY_CHUNKED_ENCODING_SIZE</emphasis> property
can be used to set the chunk size in the request context (size 0 disables chunked
encoding).</para></section>
+<section
id="JBossWS-NativeUserGuide_Disable_Xerces_Deferred_Node_Expansion"><title>Disable
Xerces Deferred Node Expansion</title><para>To optimise the parsing of
messages Xerces has a feature called deferred node expansion which defers the expansion of
the nodes until they are actually accessed. For messages where not all of the nodes will
be visited this improves performance but the cost is increased memory overheads which can
be considerable for very large messages.</para><para>To disable this feature
the following system property can be set so that the nodes are eagerly
expanded.</para><screen xml:space="preserve">
-Dorg.jboss.ws.disable_deferred_node_expansion=true</screen></section>
+</section>
+<section
id="JBossWS-NativeUserGuide_Deployment_descriptor_attributes"><title>Deployment
descriptor attributes</title><section
id="JBossWS-NativeUserGuide_JSE_Endpoints"><title>JSE
Endpoints</title><para>The following is taken from <ulink
url="http://anonsvn.jboss.org/repos/jbossas/projects/metadata/trunk/...
and shows an excerpt of the jboss-web_5_0.dtd The most important bits
are:</para><itemizedlist><listitem><para>
<computeroutput>config-name</computeroutput>: JBossWS endpoint config name
(see <link linkend="chap_JBossWS-JAX-WSEndpointConfiguration">JBossWS -
JAX-WS Endpoint Configuration</link>)
</para></listitem><listitem><para>
<computeroutput>config-file</computeroutput>: JBossWS endpoint config file
</para></listitem><listitem><para>
<computeroutput>wsdl-publish-location</computeroutput>: Where to publish the
runtime !
gnerated WSDL </para></listitem></itemizedlist><screen
xml:space="preserve"><!--
+Runtime information about a web service.
+
+wsdl-publish-location is optionally used to specify
+where the final wsdl and any dependent files should be stored. This location
+resides on the file system from which deployment is initiated.
+
+-->
+<!ELEMENT webservice-description ( webservice-description-name, config-name?,
+ config-file?, wsdl-publish-location? )>
+
+<!--
+Unique name of a webservice within a module
+-->
+<!ELEMENT webservice-description-name ( #PCDATA )>
+
+<!--
+file: URL of a directory to which a web-service-description's wsdl should be
+published during deployment. Any required files will be published to this
+directory, preserving their location relative to the module-specific
+wsdl directory(META-INF/wsdl or WEB-INF/wsdl).
+
+Example :
+
+ For an ejb.jar whose webservices.xml wsdl-file element contains
+ META-INF/wsdl/a/Foo.wsdl
+
+ <wsdl-publish-location>file:/home/user1/publish
+ </wsdl-publish-location>
+
+ The final wsdl will be stored in /home/user1/publish/a/Foo.wsdl
+
+-->
+<!ELEMENT wsdl-publish-location ( #PCDATA
)></screen><para> </para></section>
+<section id="JBossWS-NativeUserGuide_EJB3_endpoints"><title>EJB3
endpoints</title><para>EJB deployment descriptor attributes are quite the
same. You can specify a top level <computeroutput>webservices</computeroutput>
element along with your ejb declaration that allows you to override certain deployment
aspects. The following excerpt is taken from <ulink
url="https://anonsvn.jboss.org/repos/jbossas/projects/metadata/trunk...
addition to the default properties that are customizable like in JSE deployments, the EJB
descriptor allows you to
specify:</para><itemizedlist><listitem><para>
<computeroutput>context-root</computeroutput>: A custom web context root.
Applies to all beans in this deployment unit
</para></listitem></itemizedlist><screen
xml:space="preserve"><!ELEMENT webservices (context-root?,
webservice-descri!
ption*)>
+
+<!-- The context-root element specifies the context root of the web
+application that the EJB service endpoints are deployed to.
+If it is not specified it will be derived from the deployment short name.
+-->
+<!ELEMENT context-root (#PCDATA)>
+
+<!--
+Runtime information about a web service.
+wsdl-publish-location is optionally used to specify
+where the final wsdl and any dependent files should be stored. This location
+resides on the file system from which deployment is initiated.
+-->
+<!ELEMENT webservice-description ( webservice-description-name, config-name?,
+ config-file?, wsdl-publish-location?
)></screen><para> </para></section>
+</section>
+</section>
+<section id="JBossWS-NativeUserGuide_Appendix_A"><title>Appendix
A</title><para><link
linkend="chap_JBossWS-JAX-WSEndpointConfiguration">JBossWS - JAX-WS Endpoint
Configuration</link></para><para><link
linkend="chap_JBossWS-JAX-WSClientConfiguration">JBossWS - JAX-WS Client
Configuration</link></para><para><link
linkend="chap_JBossWS-JAX-WSAnnotations">JBossWS - JAX-WS
Annotations</link></para></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-NativeWS-AddressingTutorial.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-NativeWS-AddressingTutorial.xml
(rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-NativeWS-AddressingTutorial.xml 2010-11-02
19:25:45 UTC (rev 13202)
@@ -0,0 +1,170 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-NativeWS-AddressingTutorial"><title>JBossWS-NativeWS-AddressingTutorial</title><para>
<link linkend="chap_JBossWS-NativeUserGuide">JBossWS - Native User
Guide</link> comes with support for <ulink
url="http://www.w3.org/TR/ws-addr-core/">WS-Addressing 1.0</ulink>. In
this sample we will show how to create a client and endpoint communicating each with other
using this feature.</para><para>Creating a WS-Addressing based service and
client is very simple. The user needs to create a regular JAX-WS service and client first.
The last step is to configure the addressing on both
sides.</para><para/><section
id="JBossWS-NativeWS-AddressingTutorial_The_service"><title>The
service</title><para>We will start with the following endpoint implementation
(bottom-up approach):</para><screen
xml:space="preserve">@WebService
+(
+ portName = "AddressingServicePort",
+ serviceName = "AddressingService",
+ targetNamespace =
"http://www.jboss.org/jbossws/ws-extensions/wsaddressing",
+ endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
+)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> ServiceImpl <emphasis
role="bold">implements</emphasis> ServiceIface
+{
+ <emphasis role="bold">public</emphasis> String sayHello()
+ {
+ <emphasis role="bold">return</emphasis> "Hello
World!";
+ }
+}
+</screen><para>The endpoint implements the following endpoint
interface:</para><screen xml:space="preserve"><emphasis
role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsa;
+
+<emphasis role="bold">import</emphasis> javax.jws.WebMethod;
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+
+@WebService
+(
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing"
+)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">interface</emphasis> ServiceIface
+{
+ @WebMethod
+ String sayHello();
+}
+</screen><para>Let's say that compiled endpoint and interface classes are
located in directory <emphasis
role="bold">/home/username/wsa/native/classes</emphasis>. Our next step
is to generate JAX-WS artifacts and WSDL that will be part of endpoint
archive.</para><para> </para></section>
+<section
id="JBossWS-NativeWS-AddressingTutorial_Generating_WSDL_and_JAXWS_Endpoint_Artifacts"><title>Generating
WSDL and JAX-WS Endpoint Artifacts</title><para>We will use wsprovide
commandline tool to generate WSDL and JAX-WS artifacts. Here's the
command:</para><screen xml:space="preserve">cd $JBOSS_HOME/bin
+
+./wsprovide.sh --keep --wsdl \
+ --classpath=/home/username/wsa/native/classes \
+ --output=/home/username/wsa/native/wsprovide/generated/classes \
+ --resource=/home/username/wsa/native/wsprovide/generated/wsdl \
+ --source=/home/username/wsa/native/wsprovide/generated/src \
+ org.jboss.test.ws.jaxws.samples.wsa.ServiceImpl
+</screen><para>The above command generates the following
artifacts:</para><screen xml:space="preserve"># compiled classes
+ls
/home/username/wsa/native/wsprovide/generated/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/
+SayHello.class SayHelloResponse.class
+
+# java sources
+ls
/home/username/wsa/native/wsprovide/generated/src/org/jboss/test/ws/jaxws/samples/wsa/jaxws/
+SayHello.java SayHelloResponse.java
+
+# contract artifacts
+ls /home/username/wsa/native/wsprovide/generated/wsdl/
+AddressingService.wsdl
+</screen><para>All aforementioned generated artifacts will be part of
endpoint archive. But before we will create the endpoint archive we need to reference
generated WSDL from endpoint. To achieve that we will use wsdlLocation annotation
attribute. Here's the updated endpoint implementation before packaging it to the war
file:</para><screen xml:space="preserve">@WebService
+(
+ portName = "AddressingServicePort",
+ serviceName = "AddressingService",
+ wsdlLocation = "WEB-INF/wsdl/AddressingService.wsdl",
+ targetNamespace =
"http://www.jboss.org/jbossws/ws-extensions/wsaddressing",
+ endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
+)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> ServiceImpl <emphasis
role="bold">implements</emphasis> ServiceIface
+{
+ <emphasis role="bold">public</emphasis> String sayHello()
+ {
+ <emphasis role="bold">return</emphasis> "Hello
World!";
+ }
+}
+</screen><para>Created endpoint war archive consists of the following
entries:</para><screen xml:space="preserve">jar -tvf
jaxws-samples-wsa.war
+ 0 Tue Apr 22 14:28:32 CEST 2008 META-INF/
+ 106 Tue Apr 22 14:28:30 CEST 2008 META-INF/MANIFEST.MF
+ 0 Tue Apr 22 14:28:32 CEST 2008 WEB-INF/
+ 593 Tue Apr 22 14:28:30 CEST 2008 WEB-INF/web.xml
+ 0 Tue Apr 22 14:28:32 CEST 2008 WEB-INF/classes/
+ 0 Tue Apr 22 14:28:22 CEST 2008 WEB-INF/classes/org/
+ 0 Tue Apr 22 14:28:22 CEST 2008 WEB-INF/classes/org/jboss/
+ 0 Tue Apr 22 14:28:22 CEST 2008 WEB-INF/classes/org/jboss/test/
+ 0 Tue Apr 22 14:28:24 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
+ 0 Tue Apr 22 14:28:28 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
+ 0 Tue Apr 22 14:28:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
+ 0 Tue Apr 22 14:28:26 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/
+ 374 Tue Apr 22 14:28:26 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/ServiceIface.class
+ 892 Tue Apr 22 14:28:26 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/ServiceImpl.class
+ 0 Tue Apr 22 14:28:26 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/
+ 703 Tue Apr 22 14:28:26 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/SayHello.class
+ 1067 Tue Apr 22 14:28:26 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/SayHelloResponse.class
+ 0 Tue Apr 22 14:28:32 CEST 2008 WEB-INF/wsdl/
+ 1731 Tue Apr 22 14:28:30 CEST 2008 WEB-INF/wsdl/AddressingService.wsdl
+</screen><para>The content of web.xml file is:</para><screen
xml:space="preserve"><?xml version="1.0"
encoding="UTF-8"?><web-app
+ version="2.5" xmlns="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
<ulink
url="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">http...
+ <servlet>
+ <servlet-name>AddressingService</servlet-name>
+
<servlet-class>org.jboss.test.ws.jaxws.samples.wsa.ServiceImpl</servlet-class>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>AddressingService</servlet-name>
+ <url-pattern>/*</url-pattern>
+ </servlet-mapping>
+</web-app></screen></section>
+<section
id="JBossWS-NativeWS-AddressingTutorial_Writing_Regular_JAXWS_Client"><title>Writing
Regular JAX-WS Client</title><para>The following is the regular JAX-WS client
using endpoint interface to lookup the webservice:</para><screen
xml:space="preserve"><emphasis
role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsa;
+
+<emphasis role="bold">import</emphasis> java.net.URL;
+<emphasis role="bold">import</emphasis> javax.xml.namespace.QName;
+<emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">final</emphasis> <emphasis
role="bold">class</emphasis> AddressingTestCase
+{
+
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">final</emphasis> String serviceURL = "http://" +
getServerHost() + ":8080/jaxws-samples-wsa/AddressingService";
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">void</emphasis> main(String[] args) <emphasis
role="bold">throws</emphasis> Exception
+ {
+ // create service
+ QName serviceName = <emphasis role="bold">new</emphasis>
QName("http://www.jboss.org/jbossws/ws-extensions/wsaddressing";,
"AddressingService");
+ URL wsdlURL = <emphasis role="bold">new</emphasis>
URL(serviceURL + "?wsdl");
+ Service service = Service.create(wsdlURL, serviceName);
+ ServiceIface proxy = (ServiceIface)service.getPort(ServiceIface.class);
+
+ // invoke method
+ proxy.sayHello();
+ }
+
+}
+</screen><para>Now we have both endpoint and client implementation but
without WS-Addressing in place. Our next goal is to turn on the WS-Addressing
feature.</para><para> </para></section>
+<section
id="JBossWS-NativeWS-AddressingTutorial_Turning_on_WSAddressing_10"><title>Turning
on WS-Addressing 1.0</title><para>In order to turn on WS-Addressing in
JBossWS-Native integration the last two steps are
remaining:</para><itemizedlist><listitem><para>annotate service
endpoint with @Addressing
annotation</para></listitem><listitem><para>modify client to
configure WS-Addressing using JAX-WS webservice
feature</para></listitem></itemizedlist><para> </para><section
id="JBossWS-NativeWS-AddressingTutorial_Updating_Endpoint_Code_to_Configure_WSAddressing"><title>Updating
Endpoint Code to Configure WS-Addressing</title><para>Now we need to update
endpoint implementation to configure WS-Addressing. Here's the updated endpoint
code:</para><screen xml:space="preserve"><emphasis
role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsa;
+
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+<emphasis role="bold">import</emphasis>
javax.xml.ws.soap.Addressing;
+
+@WebService
+(
+ portName = "AddressingServicePort",
+ serviceName = "AddressingService",
+ wsdlLocation = "WEB-INF/wsdl/AddressingService.wsdl",
+ targetNamespace =
"http://www.jboss.org/jbossws/ws-extensions/wsaddressing",
+ endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
+)
+@Addressing(enabled=true, required=<emphasis
role="bold">true</emphasis>)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> ServiceImpl <emphasis
role="bold">implements</emphasis> ServiceIface
+{
+ <emphasis role="bold">public</emphasis> String sayHello()
+ {
+ <emphasis role="bold">return</emphasis> "Hello
World!";
+ }
+}
+</screen><para>As users can see we added JAX-WS 2.1 <emphasis
role="bold">Addressing</emphasis> annotation to configure
WS-Addressing. The next step is to repackage the endpoint archive to apply this
change.</para><para> </para></section>
+<section
id="JBossWS-NativeWS-AddressingTutorial_Updating_Client_Code_to_Configure_WSAddressing"><title>Updating
Client Code to Configure WS-Addressing</title><para>Now we need to update
client implementation as well to configure WS-Addressing. Here's the updated client
code:</para><screen xml:space="preserve"><emphasis
role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsa;
+
+<emphasis role="bold">import</emphasis> java.net.URL;
+<emphasis role="bold">import</emphasis> javax.xml.namespace.QName;
+<emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis>
javax.xml.ws.soap.AddressingFeature;
+
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">final</emphasis> <emphasis
role="bold">class</emphasis> AddressingTestCase
+{
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">final</emphasis> String serviceURL = "http://" +
getServerHost() + ":8080/jaxws-samples-wsa/AddressingService";
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">void</emphasis> main(String[] args) <emphasis
role="bold">throws</emphasis> Exception
+ {
+ // construct proxy
+ QName serviceName = <emphasis role="bold">new</emphasis>
QName("http://www.jboss.org/jbossws/ws-extensions/wsaddressing";,
"AddressingService");
+ URL wsdlURL = <emphasis role="bold">new</emphasis>
URL(serviceURL + "?wsdl");
+ Service service = Service.create(wsdlURL, serviceName);
+ ServiceIface proxy = (ServiceIface)service.getPort(ServiceIface.class,
<emphasis role="bold">new</emphasis> AddressingFeature());
+ // invoke method
+ assertEquals("Hello World!", proxy.sayHello());
+ }
+
+}
+</screen><para>And that's all. Now we have both JAX-WS client and
endpoint communicating each other using WS-Addressing
feature.</para><para> </para></section>
+</section>
+<section
id="JBossWS-NativeWS-AddressingTutorial_Sample_Sources"><title>Sample
Sources</title><para>All sources from this tutorial are part of JBossWS-Native
distribution.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-NativeWS-ReliableMessagingTutorial.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-NativeWS-ReliableMessagingTutorial.xml
(rev 0)
+++
stack/native/trunk/src/main/doc/JBossWS-NativeWS-ReliableMessagingTutorial.xml 2010-11-02
19:25:45 UTC (rev 13202)
@@ -0,0 +1,333 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-NativeWS-ReliableMessagingTutorial"><title>JBossWS-NativeWS-ReliableMessagingTutorial</title><para>JBossWS-Native
comes with support for both <ulink
url="http://specs.xmlsoap.org/ws/2005/02/rm/ws-reliablemessaging.pdf...
1.0</ulink> and <ulink
url="http://docs.oasis-open.org/ws-rx/wsrm/v1.1/wsrm.pdf">WS-RM
1.1</ulink>. In this sample we will show how to create client and endpoint
communicating each other using WS-RM 1.1 The sample uses <ulink
url="http://schemas.xmlsoap.org/ws/2004/09/policy/">WS-Polic...
specification to configure WS-RM.</para><para>Creating the WS-RM based service
and client is very simple. User needs to create regular JAX-WS service and client first.
The last step is to configure
WSRM.</para><para/><para> </para><section
id="JBossWS-NativeWS-ReliableMessagingTutorial_The_service"><title>The
service</title><para>We will start with the following endpoint implementation
(bottom-up ap!
proach):</para><screen xml:space="preserve"><emphasis
role="bold">package</emphasis>
org.jboss.test.ws.jaxws.samples.wsrm.service;
+
+<emphasis role="bold">import</emphasis> javax.jws.Oneway;
+<emphasis role="bold">import</emphasis> javax.jws.WebMethod;
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+
+@WebService
+(
+ name = "SimpleService",
+ serviceName = "SimpleService",
+ wsdlLocation = "WEB-INF/wsdl/SimpleService.wsdl"
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsrm"
+)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> SimpleServiceImpl
+{
+ @Oneway
+ @WebMethod
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> ping()
+ {
+ System.out.println("ping()");
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String echo(String s)
+ {
+ System.out.println("echo(" + s + ")");
+ <emphasis role="bold">return</emphasis> s;
+ }
+}
+</screen><para>Let's say that compiled endpoint class is in directory
<emphasis role="bold">/home/username/wsrm/native/classes</emphasis>.
Our next step is to generate JAX-WS artifacts and
WSDL.</para><para> </para></section>
+<section
id="JBossWS-NativeWS-ReliableMessagingTutorial_Generating_WSDL_and_JAXWS_Endpoint_Artifacts"><title>Generating
WSDL and JAX-WS Endpoint Artifacts</title><para>We will use wsprovide
commandline tool to generate WSDL and JAX-WS artifacts. Here's the
command:</para><screen xml:space="preserve">cd $JBOSS_HOME/bin
+
+./wsprovide.sh --keep --wsdl \
+ --classpath=/home/username/wsrm/native/classes \
+ --output=/home/username/wsrm/native/wsprovide/generated/classes \
+ --resource=/home/username/wsrm/native/wsprovide/generated/wsdl \
+ --source=/home/username/wsrm/native/wsprovide/generated/src \
+ org.jboss.test.ws.jaxws.samples.wsrm.service.SimpleServiceImpl
+</screen><para>The above command generates the following
artifacts:</para><screen xml:space="preserve"># compiled classes
+ls
/home/username/wsrm/native/wsprovide/generated/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
+Echo.class EchoResponse.class Ping.class
+
+# java sources
+ls
/home/username/wsrm/native/wsprovide/generated/src/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
+Echo.java EchoResponse.java Ping.java
+
+# contract artifacts
+ls /home/username/wsrm/native/wsprovide/generated/wsdl/
+SimpleService.wsdl
+</screen><para>All aforementioned generated artifacts will be part of
endpoint archive. The endpoint archive consists of the following
files:</para><screen xml:space="preserve">jar -tvf
jaxws-samples-wsrm.war
+ 0 Tue Apr 15 19:06:14 CEST 2008 META-INF/
+ 106 Tue Apr 15 19:06:12 CEST 2008 META-INF/MANIFEST.MF
+ 0 Tue Apr 15 19:06:14 CEST 2008 WEB-INF/
+ 591 Tue Apr 15 19:05:42 CEST 2008 WEB-INF/web.xml
+ 0 Tue Apr 15 19:06:14 CEST 2008 WEB-INF/classes/
+ 0 Tue Apr 15 19:04:50 CEST 2008 WEB-INF/classes/org/
+ 0 Tue Apr 15 19:04:50 CEST 2008 WEB-INF/classes/org/jboss/
+ 0 Tue Apr 15 19:04:50 CEST 2008 WEB-INF/classes/org/jboss/test/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
+ 0 Tue Apr 15 19:05:10 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/
+ 0 Tue Apr 15 19:05:10 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/
+ 0 Tue Apr 15 19:05:10 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
+ 1385 Tue Apr 15 19:05:10 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/SimpleServiceImpl.class
+ 995 Tue Apr 15 19:05:10 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Echo.class
+ 1043 Tue Apr 15 19:05:10 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/EchoResponse.class
+ 679 Tue Apr 15 19:05:10 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Ping.class
+ 0 Tue Apr 15 19:06:14 CEST 2008 WEB-INF/wsdl/
+ 2934 Tue Apr 15 19:05:36 CEST 2008 WEB-INF/wsdl/SimpleService.wsdl
+</screen><para>The content of web.xml file is:</para><screen
xml:space="preserve"><?xml version="1.0"
encoding="UTF-8"?><web-app
+ version="2.5" xmlns="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
<ulink
url="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">http...
+ <servlet>
+ <servlet-name>SimpleService</servlet-name>
+
<servlet-class>org.jboss.test.ws.jaxws.samples.wsrm.service.SimpleServiceImpl</servlet-class>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>SimpleService</servlet-name>
+ <url-pattern>/*</url-pattern>
+ </servlet-mapping>
+</web-app></screen></section>
+<section
id="JBossWS-NativeWS-ReliableMessagingTutorial_Generating_JAXWS_Client_Artifacts"><title>Generating
JAX-WS Client Artifacts</title><para>Before we will write regular JAX-WS
client we need to generate client artifacts from WSDL. Here's the command to achieve
that:</para><screen xml:space="preserve">cd $JBOSS_HOME
+
+./wsconsume.sh --keep \
+ --package=org.jboss.test.ws.jaxws.samples.wsrm.generated \
+ --output=/home/username/wsrm/native/wsconsume/generated/classes \
+ --source=/home/username/wsrm/native/wsconsume/generated/src \
+ /home/username/wsrm/native/wsprovide/generated/wsdl/SimpleService.wsdl
+</screen><para>The above command generates the following
artifacts:</para><screen xml:space="preserve"># compiled classes
+ls
/home/username/wsrm/native/wsconsume/generated/classes/org/jboss/test/ws/jaxws/samples/wsrm/generated/
+Echo.class EchoResponse.class ObjectFactory.class package-info.class Ping.class
SimpleService.class SimpleService_Service.class
+
+# java sources
+ls
/home/username/wsrm/native/wsconsume/generated/src/org/jboss/test/ws/jaxws/samples/wsrm/generated/
+Echo.java EchoResponse.java ObjectFactory.java package-info.java Ping.java
SimpleService.java SimpleService_Service.java
+</screen><para>Now the last step is to write the regular JAX-WS client using
generated artifacts.</para><para> </para></section>
+<section
id="JBossWS-NativeWS-ReliableMessagingTutorial_Writing_Regular_JAXWS_Client"><title>Writing
Regular JAX-WS Client</title><para>The following is the regular JAX-WS client
using generated artifacts:</para><screen
xml:space="preserve"><emphasis
role="bold">package</emphasis>
org.jboss.test.ws.jaxws.samples.wsrm.client;
+
+<emphasis role="bold">import</emphasis> java.net.URL;
+<emphasis role="bold">import</emphasis> javax.xml.namespace.QName;
+<emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis>
org.jboss.test.ws.jaxws.samples.wsrm.generated.SimpleService;
+
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">final</emphasis> <emphasis
role="bold">class</emphasis> SimpleServiceTestCase
+{
+
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">final</emphasis> String serviceURL =
"http://localhost:8080/jaxws-samples-wsrm/SimpleService";
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">void</emphasis> main(String[] args) <emphasis
role="bold">throws</emphasis> Exception
+ {
+ QName serviceName = <emphasis role="bold">new</emphasis>
QName("http://www.jboss.org/jbossws/ws-extensions/wsrm";,
"SimpleService");
+ URL wsdlURL = <emphasis role="bold">new</emphasis>
URL(serviceURL + "?wsdl");
+ Service service = Service.create(wsdlURL, serviceName);
+ SimpleService proxy = (SimpleService)service.getPort(SimpleService.class);
+
+ proxy.ping(); // one way call
+ proxy.echo("Hello World!"); // request responce call
+ }
+
+}
+</screen><para>Now we have both endpoint and client implementation but
without WSRM in place. Our next goal is to turn on WS-RM
feature.</para><para> </para></section>
+<section
id="JBossWS-NativeWS-ReliableMessagingTutorial_Turning_on_WSRM_11"><title>Turning
on WS-RM 1.1</title><para>In order to turn on WS-RM in JBossWS-Native four
steps are necessary:</para><itemizedlist><listitem><para> extend
WSDL with WS-Policy containing both WSRM and WS-Addressing policy
</para></listitem><listitem><para> provide both endpoint and
client jaxws configuration files
</para></listitem><listitem><para> update endpoint implementation
to use endpoint jaxws file </para></listitem><listitem><para>
update client to use client jaxws file and close the
sequence</para></listitem></itemizedlist><para> </para><para> </para><section
id="JBossWS-NativeWS-ReliableMessagingTutorial_Extending_WSDL_Using_WSPolicy"><title>Extending
WSDL Using WS-Policy</title><para>To activate WSRM we need to extend WSDL with
WSRM and addressing policy. Here is how it looks like:</para><screen
xml:space="preserve"><?xml version="1.0"
encoding="UTF-8"?>
+<definitions name='SimpleService' targetNamespace='<ulink
url="http://www.jboss.org/jbossws/ws-extensions/wsrm">http:/...
xmlns='<ulink
url="http://schemas.xmlsoap.org/wsdl/">http://schemas.xmlsoa...
xmlns:soap='<ulink
url="http://schemas.xmlsoap.org/wsdl/soap/">http://schemas.x...
xmlns:tns='<ulink
url="http://www.jboss.org/jbossws/ws-extensions/wsrm">http:/...
xmlns:xsd='<ulink
url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/200...
xmlns:wsp="<ulink
url="http://schemas.xmlsoap.org/ws/2004/09/policy">http://sc...
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - -->
+ <!-- Created WS-Policy with WSRM addressing assertions -->
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - -->
+ <wsp:UsingPolicy/>
+ <wsp:Policy
+ wsu:Id="wsrm11policy"
+ xmlns:wsu="<ulink
url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecur...
+ <wsp:All>
+ <wsp:ExactlyOne>
+ <wsp:All>
+ <ns1:RMAssertion xmlns:ns1="<ulink
url="http://docs.oasis-open.org/ws-rx/wsrmp/200702">http://d...
+ <ns2:UsingAddressing xmlns:ns2="<ulink
url="http://www.w3.org/2006/05/addressing/wsdl">http://www.w...
+ </wsp:All>
+ </wsp:ExactlyOne>
+ </wsp:All>
+ </wsp:Policy><types>
+ <xs:schema targetNamespace='<ulink
url="http://www.jboss.org/jbossws/ws-extensions/wsrm">http:/...
version='1.0' xmlns:tns='<ulink
url="http://www.jboss.org/jbossws/ws-extensions/wsrm">http:/...
xmlns:xs='<ulink
url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/200...
+ <xs:element name='echo' type='tns:echo'/>
+ <xs:element name='echoResponse'
type='tns:echoResponse'/>
+ <xs:element name='ping' type='tns:ping'/>
+ <xs:complexType name='ping'>
+ <xs:sequence/>
+ </xs:complexType>
+ <xs:complexType name='echo'>
+ <xs:sequence>
+ <xs:element minOccurs='0' name='arg0'
type='xs:string'/>
+ </xs:sequence>
+ </xs:complexType>
+ <xs:complexType name='echoResponse'>
+ <xs:sequence>
+ <xs:element minOccurs='0' name='return'
type='xs:string'/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:schema></types><message
name='SimpleService_echo'>
+ <part element='tns:echo'
name='echo'/></message><message
name='SimpleService_echoResponse'>
+ <part element='tns:echoResponse'
name='echoResponse'/></message><message
name='SimpleService_ping'>
+ <part element='tns:ping'
name='ping'/></message><portType
name='SimpleService'>
+ <operation name='echo' parameterOrder='echo'>
+ <input message='tns:SimpleService_echo'/>
+ <output message='tns:SimpleService_echoResponse'/>
+ </operation>
+ <operation name='ping'>
+ <input message='tns:SimpleService_ping'/>
+ </operation></portType><binding
name='SimpleServiceBinding' type='tns:SimpleService'>
+ <!-- - - - - - - - - - - - - - - - - - - - -->
+ <!-- Associated WS-Policy with the binding -->
+ <!-- - - - - - - - - - - - - - - - - - - - -->
+ <wsp:PolicyReference URI="#wsrm11policy"/>
+ <soap:binding style='document' transport='<ulink
url="http://schemas.xmlsoap.org/soap/http'/">http://sche...
+ <operation name='echo'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body use='literal'/>
+ </input>
+ <output>
+ <soap:body use='literal'/>
+ </output>
+ </operation>
+ <operation name='ping'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body use='literal'/>
+ </input>
+ </operation></binding><service
name='SimpleService'>
+ <port binding='tns:SimpleServiceBinding'
name='SimpleServicePort'>
+ <soap:address location='REPLACE_WITH_ACTUAL_URL'/>
+ </port></service>
+</definitions>
+</screen><para>We added <emphasis
role="bold">wsp:UsingPolicy</emphasis>, <emphasis
role="bold">wsp:Policy</emphasis> and <emphasis
role="bold">wsp:PolicyReference</emphasis> elements to
WSDL.</para><para> </para></section>
+<section
id="JBossWS-NativeWS-ReliableMessagingTutorial_Providing_Endpoint_and_Client_JAXWS_Configuration_Files"><title>Providing
Endpoint and Client JAX-WS Configuration Files</title><para>In order to
activate WSRM in JBossWS-Native integration user have to provide both endpoint and client
jaxws configuration files containing both addressing and WSRM handlers in the processing
chain.</para><para>The endpoint jaxws configuration file, in our case we will
call it <emphasis
role="bold">wsrm-jaxws-endpoint-config.xml</emphasis> has the following
content:</para><screen xml:space="preserve"><?xml
version="1.0" encoding="UTF-8"?><jaxws-config
+ xmlns="urn:jboss:jaxws-config:2.0"
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xmlns:javaee="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
+
+ <endpoint-config>
+ <config-name>Standard WSRM Endpoint</config-name>
+ <post-handler-chains>
+ <javaee:handler-chain>
+
<javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSAddressing
Handler</javaee:handler-name>
+
<javaee:handler-class>org.jboss.ws.extensions.addressing.jaxws.WSAddressingServerHandler</javaee:handler-class>
+ </javaee:handler>
+ <javaee:handler>
+ <javaee:handler-name>WSRM
Handler</javaee:handler-name>
+
<javaee:handler-class>org.jboss.ws.extensions.wsrm.jaxws.RMServerHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+ </endpoint-config></jaxws-config>
+</screen><para>The client jaxws configuration file, in our case we will call
it <emphasis role="bold">wsrm-jaxws-client-config.xml</emphasis> has
the following content:</para><screen
xml:space="preserve"><?xml version="1.0"
encoding="UTF-8"?><jaxws-config
+ xmlns="urn:jboss:jaxws-config:2.0"
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xmlns:javaee="<ulink
url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/...
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
+
+ <client-config>
+ <config-name>Standard Anonymous WSRM
Client</config-name>
+ <reliable-messaging>
+ <message-retransmission attempts="50" interval="10"
timeout="10"/>
+ </reliable-messaging>
+ <post-handler-chains>
+ <javaee:handler-chain>
+
<javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSAddressing
Handler</javaee:handler-name>
+
<javaee:handler-class>org.jboss.ws.extensions.addressing.jaxws.WSAddressingClientHandler</javaee:handler-class>
+ </javaee:handler>
+ <javaee:handler>
+ <javaee:handler-name>WSRM
Handler</javaee:handler-name>
+
<javaee:handler-class>org.jboss.ws.extensions.wsrm.jaxws.RMClientHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+ </client-config></jaxws-config>
+</screen><note><para><para><emphasis><emphasis
role="bold">Note</emphasis></emphasis></para><para><emphasis>Both
client and endpoint jaxws configuration files are available in native WSRM tests. Users
can copy them from
there.</emphasis></para></para></note><para>The next step is
to include jaxws endpoint configuration file in META-INF directory of the endpoint
archive.</para><screen xml:space="preserve">jar -tvf
jaxws-samples-wsrm.war
+ 0 Tue Apr 15 19:06:14 CEST 2008 META-INF/
+ 106 Tue Apr 15 19:06:12 CEST 2008 META-INF/MANIFEST.MF
+ 0 Tue Apr 15 19:06:14 CEST 2008 WEB-INF/
+ 591 Tue Apr 15 19:05:42 CEST 2008 WEB-INF/web.xml
+ 0 Tue Apr 15 19:06:14 CEST 2008 WEB-INF/classes/
+ 0 Tue Apr 15 19:04:50 CEST 2008 WEB-INF/classes/org/
+ 0 Tue Apr 15 19:04:50 CEST 2008 WEB-INF/classes/org/jboss/
+ 0 Tue Apr 15 19:04:50 CEST 2008 WEB-INF/classes/org/jboss/test/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
+ 0 Tue Apr 15 19:05:10 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/
+ 0 Tue Apr 15 19:05:10 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/
+ 0 Tue Apr 15 19:05:10 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
+ 1385 Tue Apr 15 19:05:10 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/SimpleServiceImpl.class
+ 995 Tue Apr 15 19:05:10 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Echo.class
+ 1043 Tue Apr 15 19:05:10 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/EchoResponse.class
+ 679 Tue Apr 15 19:05:10 CEST 2008
WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Ping.class
+ 0 Tue Apr 15 19:06:14 CEST 2008 WEB-INF/wsdl/
+ 2934 Tue Apr 15 19:05:36 CEST 2008 WEB-INF/wsdl/SimpleService.wsdl
+ 2033 Tue Apr 15 19:05:52 CEST 2008 META-INF/wsrm-jaxws-endpoint-config.xml
+</screen><para>What about client side, the client jaxws configuration file
must be available on the client classpath, in our case it will be available as
<emphasis
role="bold">META-INF/wsrm-jaxws-client-config.xml</emphasis>
resource.</para><para> </para></section>
+<section
id="JBossWS-NativeWS-ReliableMessagingTutorial_Updating_Endpoint_Code_to_Reference_Custom_JAXWS_Config_File"><title>Updating
Endpoint Code to Reference Custom JAX-WS Config File</title><para>Now we need
to update endpoint implementation to reference custom JAX-WS configuration file.
Here's the updated endpoint code:</para><screen
xml:space="preserve"><emphasis
role="bold">package</emphasis>
org.jboss.test.ws.jaxws.samples.wsrm.service;
+
+<emphasis role="bold">import</emphasis> javax.jws.Oneway;
+<emphasis role="bold">import</emphasis> javax.jws.WebMethod;
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+
+<emphasis role="bold">import</emphasis>
org.jboss.ws.annotation.EndpointConfig;
+
+@WebService
+(
+ name = "SimpleService",
+ serviceName = "SimpleService",
+ wsdlLocation = "WEB-INF/wsdl/SimpleService.wsdl",
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsrm"
+)
+@EndpointConfig
+(
+ configFile = "META-INF/wsrm-jaxws-endpoint-config.xml",
+ configName = "Standard WSRM Endpoint"
+)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> SimpleServiceImpl
+{
+ @Oneway
+ @WebMethod
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> ping()
+ {
+ System.out.println("ping()");
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String echo(String s)
+ {
+ System.out.println("echo(" + s + ")");
+ <emphasis role="bold">return</emphasis> s;
+ }
+}
+</screen><para>As users can see we added JBossWS proprietary <emphasis
role="bold">EndpointConfig</emphasis> annotation to reference the
endpoint config.</para><para> </para></section>
+<section
id="JBossWS-NativeWS-ReliableMessagingTutorial_Updating_Client_Code_to_Reference_Custom_JAXWS_Config_File_and_Close_the_Sequence"><title>Updating
Client Code to Reference Custom JAX-WS Config File and Close the
Sequence</title><para>Now we need to update client implementation as well to
reference custom JAX-WS configuration file. We will also add the call to close the created
sequence there. Here's the updated client code:</para><screen
xml:space="preserve"><emphasis
role="bold">package</emphasis>
org.jboss.test.ws.jaxws.samples.wsrm.client;
+
+<emphasis role="bold">import</emphasis> java.net.URL;
+<emphasis role="bold">import</emphasis> javax.xml.namespace.QName;
+<emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis> org.jboss.ws.core.StubExt;
+<emphasis role="bold">import</emphasis>
org.jboss.ws.extensions.wsrm.api.RMProvider;
+<emphasis role="bold">import</emphasis>
org.jboss.test.ws.jaxws.samples.wsrm.generated.SimpleService;
+
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">final</emphasis> <emphasis
role="bold">class</emphasis> SimpleServiceTestCase
+{
+
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">final</emphasis> String serviceURL =
"http://localhost:8080/jaxws-samples-wsrm/SimpleService";
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">void</emphasis> main(String[] args) <emphasis
role="bold">throws</emphasis> Exception
+ {
+ QName serviceName = <emphasis role="bold">new</emphasis>
QName("http://www.jboss.org/jbossws/ws-extensions/wsrm";,
"SimpleService");
+ URL wsdlURL = <emphasis role="bold">new</emphasis>
URL(serviceURL + "?wsdl");
+ Service service = Service.create(wsdlURL, serviceName);
+ SimpleService proxy = (SimpleService)service.getPort(SimpleService.class);
+ ((StubExt)proxy).setConfigName("Standard Anonymous WSRM Client",
"META-INF/wsrm-jaxws-client-config.xml");
+
+ proxy.ping(); // one way call
+ proxy.echo("Hello World!"); // request responce call
+ ((RMProvider)proxy).closeSequence();
+ }
+
+}
+</screen><para>And that's all. Now user have both endpoint and client
using WS-RM 1.1 when communicating each
other.</para><para> </para></section>
+</section>
+<section
id="JBossWS-NativeWS-ReliableMessagingTutorial_Sample_Sources"><title>Sample
Sources</title><para>All sources from this tutorial are part of JBossWS-Native
distribution.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-QuickStart.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-QuickStart.xml (rev
0)
+++ stack/native/trunk/src/main/doc/JBossWS-QuickStart.xml 2010-11-02 19:25:45 UTC (rev
13202)
@@ -0,0 +1,193 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-QuickStart"><title>JBossWS-QuickStart</title><para/><para> </para><section
id="JBossWS-QuickStart_Right_on"><title>Right
on'</title><para>JBossWS uses the JBoss application server as its 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 and advanced topics you need consult the user
guide.</para><para>In the following sections we will explore the samples that
ship with the JBossWS distribution. They provide a build structure based on Ant to get you
started quickly.</para></section>
+<section
id="JBossWS-QuickStart_Developing_web_service_implementations"><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</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">WSDL</ulink>) 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">JSR-181 annot!
ations</ulink>.</para><note><para><para><emphasis
role="bold">Note</emphasis></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><listitem><para> <ulink
url="http://jcp.org/en/jsr/detail?id=181">Web service meta data
(JSR-181)</ulink> </para></listitem><listitem><para>
<ulink url="http://java.sun.com/webservices/jaxb/">Java API for XML
binding
(JAXB)</ulink></para></listitem></itemizedlist></para></note><para>When
starting from Java you must provide the service implementation. A valid endpoint
implementation class must meet the following
requirements:</para><itemizedlist><listitem><para> It
<emphasis>must</emphasis> carry a
<computeroutput>javax.jws.WebService</computeroutput> 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
sam!
ple 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
<computeroutput>@Stateless</computeroutput>. We concentrate on the
<computeroutput>@WebService</computeroutput> annotation for
now.</para><para><emphasis role="bold">The service
implementation class</emphasis></para><screen
xml:space="preserve"><emphasis
role="bold">package</emphasis>
org.jboss.test.ws.jaxws.samples.retail.profile;
+
+<emphasis role="bold">import</emphasis> javax.ejb.Stateless;
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+<emphasis role="bold">import</emphasis> javax.jws.WebMethod;
+<emphasis role="bold">import</emphasis>
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)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> ProfileMgmtBean {
+
+ @WebMethod (4)
+ <emphasis role="bold">public</emphasis> DiscountResponse
getCustomerDiscount(DiscountRequest request) {
+ <emphasis role="bold">return</emphasis> <emphasis
role="bold">new</emphasis> DiscountResponse(request.getCustomer(),
10.00);
+ }
+}
+
+</screen><orderedlist><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/">JAXB2</ulink>;. 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><screen
xml:space="preserve"><emphasis
role="bold">package</emphasis>
org.jboss.test.ws.jaxws.samples.retail.profile;
+
+<emphasis role="bold">import</emphasis>
javax.xml.bind.annotation.XmlAccessType;
+<emphasis role="bold">import</emphasis>
javax.xml.bind.annotation.XmlAccessorType;
+<emphasis role="bold">import</emphasis>
javax.xml.bind.annotation.XmlType;
+
+<emphasis role="bold">import</emphasis>
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" }
+)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> DiscountRequest {
+
+ <emphasis role="bold">protected</emphasis> Customer customer;
+
+ <emphasis role="bold">public</emphasis> DiscountRequest() {
+ }
+
+ <emphasis role="bold">public</emphasis> DiscountRequest(Customer
customer) {
+ this.customer = customer;
+ }
+
+ <emphasis role="bold">public</emphasis> Customer getCustomer()
{
+ <emphasis role="bold">return</emphasis> customer;
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> setCustomer(Customer value) {
+ this.customer = value;
+ }
+
+}
+
+</screen><orderedlist><listitem><para>In this case we use
<computeroutput>@XmlType</computeroutput> to specify an XML complex type name
and override the namespace.
</para></listitem></orderedlist><para> </para><variablelist/><section
id="JBossWS-QuickStart_Deploying_service_implementations"><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> </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 <computeroutput>deploy</computeroutput>
directory. No additional deployment descriptors required. Any meta data required for the
dep!
loyment 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> </para><para><emphasis
role="bold">The JAR package structure</emphasis></para><screen
xml:space="preserve">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
+</screen><note><para><para><emphasis><emphasis
role="bold">Note</emphasis></emphasis></para><para><emphasis>If
the deployment was successful you should be able to see your endpoint at <ulink
url="http://localhost:8080/jbossws/services">http://localhost:8080/jbossws/services</ulink></emphasis></para><para> </para></para></note></section>
+</section>
+<section
id="JBossWS-QuickStart_Consuming_web_services"><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 <ulink url="http://community.jboss.org/docs/DOC-13972">user
guide</ulink>.</para><para> </para><para> </para><para><emphasis
role="bold">Using wsconsume
</emphasis></para><para> </para><para>The <link
linkend="chap_JBossWS-wsconsume">wsconsume tool</link> 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
(<link
linkend="JBossWS-QuickStart_Profile_MgmtService">ProfileMgmtService.wsdl</link>).
For a detailed tool reference!
you need to consult the user guide.</para><screen
xml:space="preserve">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
+</screen><para>Let's try it on our retail sample:</para><screen
xml:space="preserve">~./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
+
+</screen><orderedlist><listitem><para> As you can see we did use
the <computeroutput>-p</computeroutput> switch to specify the package name of
the generated sources.
</para></listitem></orderedlist><para> </para><para><emphasis
role="bold"> The generated artifacts explained
</emphasis></para><informaltable><tgroup
cols="2"><colspec colnum="1"
colname="col1"/><colspec colnum="2"
colname="col2"/><thead><row><entry> File
</entry><entry> Purpose
</entry></row></thead><tbody><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></informaltable><para>B!
asically <computeroutput>wsconsume</computeroutput> generates all custom data
types (JAXB annotated classes), the service endpoint interface and a service factory
class. We will look at how these artifacts can be used the build web service client
implementations in the next section.</para><para> </para><bridgehead
id="Constructing_a_service_stub">Constructing a service
stub</bridgehead><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><screen
xml:space="preserve"><emphasis
role="bold">import</emphasis> javax.xml.ws.Service;
+
+Service service = Service.create( (1)
+ <emphasis role="bold">new</emphasis>
URL("http://example.org/service?wsdl"),
+ <emphasis role="bold">new</emphasis>
QName("MyService")
+);
+ProfileMgmt profileMgmt = service.getPort(ProfileMgmt.class); (2)
+
+// do something with the service stub here... (3)
+</screen><orderedlist><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> </para><para> </para><para><emphasis><emphasis
role="bold">Note</emphasis></emphasis></para><note><para><para><emphasis>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
<computeroutput>@WebServiceRef</computeroutput>
functionality.</emphasis></para><para> </para></para></note></section>
+<section
id="JBossWS-QuickStart_Appendix"><title>Appendix</title><section
id="JBossWS-QuickStart_Profile_MgmtService"><title>ProfileMgmtService.wsdl</title><screen
xml:space="preserve"><definitions
+ name='ProfileMgmtService'
+ targetNamespace='<ulink
url="http://org.jboss.ws/samples/retail/profile">http://org.jboss.ws/samples/retail/profile</ulink>'
+ xmlns='<ulink
url="http://schemas.xmlsoap.org/wsdl/">http://schemas.xmlsoa...
+ xmlns:ns1='<ulink
url="http://org.jboss.ws/samples/retail">http://org.jboss.ws/samples/retail</ulink>'
+ xmlns:soap='<ulink
url="http://schemas.xmlsoap.org/wsdl/soap/">http://schemas.x...
+ xmlns:tns='<ulink
url="http://org.jboss.ws/samples/retail/profile">http://org.jboss.ws/samples/retail/profile</ulink>'
+ xmlns:xsd='<ulink
url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/200...
+
+ <types>
+
+ <xs:schema targetNamespace='<ulink
url="http://org.jboss.ws/samples/retail">http://org.jboss.ws/samples/retail</ulink>'
+ version='1.0' xmlns:xs='<ulink
url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/200...
+ <xs:complexType 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='<ulink
url="http://org.jboss.ws/samples/retail/profile">http://org.jboss.ws/samples/retail/profile</ulink>'
+ version='1.0'
+ xmlns:ns1='<ulink
url="http://org.jboss.ws/samples/retail">http://org.jboss.ws/samples/retail</ulink>'
+ xmlns:tns='<ulink
url="http://org.jboss.ws/samples/retail/profile">http://org.jboss.ws/samples/retail/profile</ulink>'
+ xmlns:xs='<ulink
url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/200...
+
+ <xs:import namespace='<ulink
url="http://org.jboss.ws/samples/retail'/">http://org.jboss.ws/samples/retail'/</ulink>>
+ <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='<ulink
url="http://schemas.xmlsoap.org/soap/http'/">http://sche...
+ <operation 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='<ulink
url="http://">http://</ulink><HOST>:<PORT>/jaxws-samples-retail/ProfileMgmtBean'/>
+ </port>
+ </service>
+</definitions></screen><para> </para> </section>
+</section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Recordsmanagement.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Recordsmanagement.xml
(rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Recordsmanagement.xml 2010-11-02 19:25:45 UTC
(rev 13202)
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-Recordsmanagement"><title>JBossWS-Recordsmanagement</title><para>JBossWS
records' collection and management system gives administrators a means of performing
custom analysis of their webservice traffic as well as exporting communication
logs.</para><para/><para> </para><section
id="JBossWS-Recordsmanagement_What_is_recorded"><title>What is
recorded</title><para>Each record is basically composed of a message plus
additional information; here are the current record
attributes:</para><itemizedlist><listitem><para> Creation date
</para></listitem><listitem><para> Source host
</para></listitem><listitem><para> Destination host
</para></listitem><listitem><para> Message type (in/out)
</para></listitem><listitem><para> Invoked endpoint operation
</para></listitem><listitem><para> Message envelope (including
both soap:header and soap:body for SOAP messages)
</para></listitem><listitem><para> Http headers
</para></list!
item><listitem><para> Record group ID (allowing records belonging to the
same message flow to be linked together)
</para></listitem></itemizedlist><para>Of course records may also
have meaningful values for a subset of the afore mentioned record
attributes.</para><para> </para></section>
+<section id="JBossWS-Recordsmanagement_Use_cases"><title>Use
cases</title><para>What are records useful for? In spite of <link
linkend="chap_JBossWS-Endpointmanagement">endpoint metrics</link> that
provide response time information and counts of invocations, records provide users with
rich data about the content of the exchanged messages and their sender/receiver. The
record system allows fine grained management and is customizable according to the users
need; some of the use cases supported by the default configuration
are:</para><itemizedlist><listitem><para> Logging request and
response messages: being able to record messages received from and sent to a given service
consumer without stopping the provider may be really useful. You just need to set the
<emphasis>recording</emphasis> attribute of their endpoint's LogRecorder
to true. The added value of this logging solution comes from the use of filters through
which messages coming from a given address and related to a gi!
ven wsdl operation only can be logged.
</para></listitem><listitem><para> Accountability: service
providers may want to know which consumers are actually hitting a given service. This can
be done for example using the <emphasis>getClientHosts</emphasis>
functionality of the MemoryBufferRecorder once it has been switched to recording state.
</para></listitem><listitem><para> Getting statistics, filtering
records: service administrators might want to see the last records related to a given
endpoint or operation, the last records related to messages coming from a given customer
and the response the system gave them, etc. These information can be obtained using the
<emphasis>getRecordsByOperation</emphasis>,
<emphasis>getRecordsByClientHost</emphasis> or the more general
<emphasis>getMatchingRecords</emphasis> functionality of the
MemoryBufferRecorder.</para></listitem></itemizedlist><para> </para></section>
+<section
id="JBossWS-Recordsmanagement_How_it_works_and_how_to_use_it"><title>How
it works and how to use it</title><para>The recording system is composed
of</para><itemizedlist><listitem><para> JAX-WS handlers
intercepting inbound and outbound communication
</para></listitem><listitem><para> Record processors plugged into
deployed endpoints; handlers collect records and send them to every processors through the
current endpoint. Processors may store records, convert them, log them, ...
</para></listitem><listitem><para> MBean views of processors that
can be used to configure and fine tune recording at runtime
</para></listitem><listitem><para> Record filters allowing
selection of information to be recorded as well as providing means of performing custom
queries on the saved
records.</para></listitem></itemizedlist><para> </para><section
id="JBossWS-Recordsmanagement_Server_side"><title>Server
side</title><para>On server side records are collected by JAX-WS handlers and
pa!
ssed to the configured processors. JBossWS comes with two default record processors that
are plugged into every endpoint during the
deployment:</para><itemizedlist><listitem><para> LogRecorder: a
simple record processor that writes records to the configured log.
</para></listitem><listitem><para> MemoryBufferRecorder: a record
processor that keeps the last received records in memory and allows user to search / get
statistics on them. </para></listitem></itemizedlist><para>Every
processors can be fine tuned to process some record attributes only according to the user
and/or performance requirements. Default processors are not in recording mode upon
creation, thus you need to switch them to recording mode through their MBean interfaces
(see the <emphasis>Recording</emphasis> flag in the
jmx-console).</para><para>Common processor properties and their respective
defaults values are:</para><itemizedlist><listitem><para>
processDestinationHost (true) </para></listitem><listitem><!
para> processSourceHost (true) </para></listitem><listitem><pa!
ra> proc
essHeaders (true) </para></listitem><listitem><para>
processEnvelope (true) </para></listitem><listitem><para>
processMessageType (true) </para></listitem><listitem><para>
processOperation (true) </para></listitem><listitem><para>
processDate (true) </para></listitem><listitem><para> recording
(false) </para></listitem></itemizedlist><para>The recorders can
be configured in the stacks bean configuration</para><screen
xml:space="preserve"> <!-- Installed Record Processors-->
+ <bean name="WSMemoryBufferRecorder"
class="org.jboss.wsf.framework.management.recording.MemoryBufferRecorder">
+ <property name="recording">false</property>
+ </bean>
+ <bean name="WSLogRecorder"
class="org.jboss.wsf.framework.management.recording.LogRecorder">
+ <property name="recording">false</property>
+ </bean>
+</screen><para>The recording system is available for all the JBossWS
supported stacks. However slightly different procedure is required to enable it depending
on the used
stack.</para><variablelist><varlistentry><term><emphasis
role="bold">Native stack</emphasis>
</term><listitem/></varlistentry></variablelist><para>Native
stack comes with <link
linkend="chap_JBossWS-JAX-WSEndpointConfiguration">JBossWS - JAX-WS Endpoint
Configuration</link>. The default standard endpoint already has the server side
recording handler:</para><screen xml:space="preserve">
<endpoint-config>
+ <config-name>Standard Endpoint</config-name>
+ <pre-handler-chains>
+ <javaee:handler-chain>
+
<javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>Recording
Handler</javaee:handler-name>
+
<javaee:handler-class>org.jboss.wsf.framework.invocation.RecordingServerHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </pre-handler-chains>
+ </endpoint-config>
+</screen><para>thus nothing is required to use it since it is automatically
installed in the pre-handler-chain. Of course you might want to add it to other endpoint
configurations you're
using.</para><variablelist><varlistentry><term><emphasis
role="bold">Metro and CXF stacks
</emphasis></term><listitem/></varlistentry></variablelist><para>Other
stacks require users to manually add the
<emphasis>org.jboss.wsf.framework.invocation.RecordingServerHandler</emphasis>
to their endpoint handler chain. This can be done <link
linkend="chap_JBossWS-UserGuide">the same way common user handlers are
added</link>.</para><para>Once the handler is properly added to the
chain, log recording configuration is agnostic to the used stack. Users just need to tune
the processors parameters though their MBean
interfaces.</para><para> </para></section>
+<section id="JBossWS-Recordsmanagement_Client_side"><title>Client
side</title><para>JMX management of processors is of course available on
server side only. However users might also be interested in collecting and processing
records on client side. Since handlers can be set on client side too, customer handlers
could be configured to capture messages almost like the
<emphasis>RecordingServerHandler</emphasis> does. This is left to the users
since it is directly linked to their custom needs. For instance a common use could be to
pass client side collected records to the
LogRecorder.</para><para> </para></section>
+</section>
+<section
id="JBossWS-Recordsmanagement_Advanced_hints"><title>Advanced
hints</title><section
id="JBossWS-Recordsmanagement_Adding_custom_recorders"><title>Adding
custom recorders</title><para>As previously said, the recording system is
extensible: JBossWS users can write their own processors and plug them at runtime into
their deployed endpoints through the <emphasis>addRecordProcessor</emphasis>
functionality of the ManagedEndpoint MBean. Every processor needs to implement the
<emphasis>org.jboss.wsf.spi.management.recording.RecordProcessor</emphasis>
interface. Then you can choose one of the two following
options:</para><itemizedlist><listitem><para> Give you record
processor an MBean interface declaring the manageable attributes: the recording system
will plug your processor to the endpoint and register a management MBean for it using your
interface. This allows you to create highly configurable custom processors. For an example
of this development option, take a look at!
the
<emphasis>org.jboss.wsf.framework.management.recording.MemoryBufferRecorder</emphasis>.
</para></listitem><listitem><para> Add your record processor to
the managed endpoint as is: the recording system will plug it to the endpoint and register
a standard management MBean for its basic processing configuration. The
<emphasis>org.jboss.wsf.framework.management.recording.LogRecorder</emphasis>
is an example of this development option.
</para></listitem></itemizedlist><para>A code snippet showing how
to get the MBeanProxy instance which you can invoke MBean with can be found <link
linkend="chap_JBossWS-Endpointmanagement">here</link>.</para></section>
+<section
id="JBossWS-Recordsmanagement_Handlers_position"><title>Handler's
position</title><para>Of course the recording handler's position in the
handler chain influences the collected records. As a matter of fact some information may
or may not be available at a given point of the handler chain execution. The standard
endpoint configuration declares the RecordingServerHandler into the pre-handler-chain.
Speaking of the native stack, this means for example that you'll get the invoked
operation data and that decrypted messages will be recorded if using WS-Security, since
the WS-Security handler runs in the post-handler-chain. Users might want to change the
recording handler's position in the chain according to their
requirements.</para></section>
+<section
id="JBossWS-Recordsmanagement_Multiple_handlers"><title>Multiple
handlers</title><para>Records attributes include a record group ID that is
meant to link records whose messages belong to the same message flow (a request-response
for example). In order to set the right group ID to the records, the current ID is
associated to the thread that is processing the endpoint invocation. This means that
multiple related records can be linked together and extracted together from a
processor.</para><para>For this reason, you might want to install multiple
recording handlers into different points of the handler chain. For instance, it could make
sense to record messages both before and after encryption/decryption when using
WS-Security.</para></section>
+</section>
+<section
id="JBossWS-Recordsmanagement_Future_extensions"><title>Future
extensions</title><para>This paragraph covers eventual future extensions
and/or idea JBossWS users may want to leverage for their own
business.</para><section
id="JBossWS-Recordsmanagement_Database_recorder"><title>Database
recorder</title><para>The MemoryBufferRecorder provides interesting
functionalities to query the collected records set. For obvious reasons, records are
discarded once a given size of the buffer is reached.</para><para>A DB based
recorder could be developed; it should work the same way the MemoryBufferRecorder does,
except for records that should be saved through a given datasource. This will provide
persistence of data even in case of application server reboot and webservice application
redeploy. It will also allow records coming from different node of a cluster to be stored
together. Finally this would allow administrators to directly query the database, which
might be far more eff!
icient.</para></section>
+<section
id="JBossWS-Recordsmanagement_Custom_log_writer"><title>Custom log
writer</title><para>The idea of getting statistics from collected records
could be further exploited getting custom logs from the records. These logs could be
outputted by a custom processor in standard or proprietary formats allowing them to be
imported into eventual third-party log processing tools which might offer complex/funky
graphic or statistic functionalities and so on.</para></section>
+</section>
+<section
id="JBossWS-Recordsmanagement_References"><title>References</title><para>You
might want to take a look at the
<emphasis>org.jboss.wsf.framework.management.recording</emphasis> and
<emphasis>org.jboss.wsf.spi.management.recording</emphasis> packages in the
source code to better understand how all this works and can be
used.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Securetransport.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Securetransport.xml
(rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Securetransport.xml 2010-11-02 19:25:45 UTC
(rev 13202)
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-Securetransport"><title>JBossWS-Securetransport</title><para/><para>JBossWS
allows you to require that requests to a given endpoint use SSL by specifying the
<emphasis>transportGuarantee</emphasis> attribute in the <ulink
url="http://community.jboss.org/docs/DOC-13972#WebContext">@...
annotation.</para><para>Here is an example using a SLSB
endpoint:</para><screen xml:space="preserve">@Stateless
+@SecurityDomain("JBossWS")
+@RolesAllowed("friend")
+@WebContext
+(
+ contextRoot="/my-cxt",
+ urlPattern="/*",
+ authMethod="BASIC",
+ transportGuarantee="CONFIDENTIAL",
+ secureWSDLAccess=<emphasis role="bold">false</emphasis>
+)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> EndpointEJB <emphasis
role="bold">implements</emphasis> EndpointInterface
+{
+ ...
+}
+</screen><para>Similarly to enforce the same requirement on POJO endpoints,
you need to edit web.xml and add a user-data-constraint element to your
security-constraint element:</para><screen xml:space="preserve">
<security-constraint>
+ <web-resource-collection>
+ <web-resource-name>All resources</web-resource-name>
+ <url-pattern>/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>friend</role-name>
+ </auth-constraint>
+ <user-data-constraint>
+
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
+ </user-data-constraint>
+ </security-constraint>
+
+ <security-role>
+ <role-name>friend</role-name>
+ </security-role>
+</screen><para>If you're manually creating your service contract, make
sure that the endpoint address in your WSDL file uses a secure protocol. The easiest way
is to add "<ulink url="https://">https://</ulink>" to the
SOAP Address entry:</para><screen xml:space="preserve">
<service name="MyService">
+ <port name="BasicSecuredPort"
binding="tns:MyBinding">
+ <soap:address location="<ulink
url="https://localhost:8443/my-ctx/SecureEndpoint">https://localhost:8443/my-ctx/SecureEndpoint</ulink>"/>
+ </port>
+ </service>
+</screen><para>For this to work the Tomcat+SSL connector must be
enabled:</para><screen xml:space="preserve"> <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" />
+</screen><para>Please refer the <ulink
url="http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html">... SSL
Configuration HOWTO</ulink> for further
details.</para><para> </para><section
id="JBossWS-Securetransport_Client_side"><title>Client
side</title><para>On the client side the truststore must be
installed:</para><screen xml:space="preserve">
<sysproperty key="javax.net.ssl.keyStore"
value="${test.resources.dir}/wsse/wsse.keystore"/>
+ <sysproperty key="javax.net.ssl.trustStore"
value="${test.resources.dir}/wsse/wsse.truststore"/>
+ <sysproperty key="javax.net.ssl.keyStorePassword"
value="jbossws"/>
+ <sysproperty key="javax.net.ssl.trustStorePassword"
value="jbossws"/>
+ <sysproperty key="javax.net.ssl.keyStoreType"
value="jks"/>
+ <sysproperty key="javax.net.ssl.trustStoreType"
value="jks"/></screen><para>As you can see, this requires you
to setup the environment specifying both the location and type of your
truststore.</para><para>Finally, in case you see the following
exception:</para><screen xml:space="preserve"> java.io.IOException:
HTTPS hostname wrong: should be <localhost>
+ at sun.net.www.protocol.https.HttpsClient.checkURLSpoofing(HttpsClient.java:493)
+ at sun.net.www.protocol.https.HttpsClient.afterConnect(HttpsClient.java:418)
+</screen><para>you should disable URL checking on the client
side:</para><screen xml:space="preserve"> <sysproperty
key="org.jboss.security.ignoreHttpsHost"
value="true"/></screen></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Securityandattachmentssample.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Securityandattachmentssample.xml
(rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Securityandattachmentssample.xml 2010-11-02
19:25:45 UTC (rev 13202)
@@ -0,0 +1,685 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-Securityandattachmentssample"><title>JBossWS-Securityandattachmentssample</title><section
id="JBossWS-Securityandattachmentssample_Scenario"><title>Scenario</title><para>This
sample targets those web service business scenarios requiring both exchange of attachments
and different levels of communication
security.</para><para> </para><para>The <emphasis
role="bold">org.jboss.test.ws.jaxws.samples.news</emphasis> sample is
about an oversimplified newspaper system. News agencies provide press releases to the main
newspaper center. Information are processed, articles written and perhaps translated. Once
a newspaper edition is ready, printer/distributor centers can download it (as well as
previous editions).</para><para>This sample of course focuses on the web
service endpoints making the above-mentioned communication
possible.</para><para> </para></section>
+<section
id="JBossWS-Securityandattachmentssample_Attachments"><title>Attachments</title><para>The
JBossWS stack supports two means of using attachment (perhaps binary) to SOAP message:
<ulink
url="http://community.jboss.org/docs/DOC-13972#MTOMXOP">MTOM...
and <ulink
url="http://http://www.jboss.org/community/wiki/JBossWS-UserGuide#Sw...;.
Basically both technologies allows attachments to be referenced in SOAP messages, moreover
MTOM/XOP provides efficient data serialization for certain content types. Since
third-party system might support MTOM/XOP or SwaRef only, we decided here to implement two
different endpoints, each of them using one
technology.</para><para> </para><section
id="JBossWS-Securityandattachmentssample_The_press_release_endpoint"><title>The
press release endpoint</title><section
id="JBossWS-Securityandattachmentssample_Newspaper_server"><title>Newspaper
server</title><para>The press release endpoint implementation is provided in
t!
he <emphasis>AbstractPressReleaseEndpoint</emphasis> class and simply outputs
the received press release object to the logs:</para><screen
xml:space="preserve"><emphasis
role="bold">public</emphasis> <emphasis
role="bold">abstract</emphasis> <emphasis
role="bold">class</emphasis> AbstractPressReleaseEndpoint
+{
+ <emphasis role="bold">private</emphasis> Logger log =
Logger.getLogger(this.getClass());
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> submitPressRelease(PressRelease release)
+ {
+ log.info("Received a press release from agency: " +
release.getAgencyId());
+ log.info("- Title: " + release.getTitle());
+ log.info("- Text: " + release.getBody());
+ }
+}
+</screen><para>Here is the actual web service endpoint
implementation:</para><screen xml:space="preserve">@Stateless
+@WebService(name = "PressReleaseEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/news",
+ serviceName = "PressReleaseService")
+@SOAPBinding(style = SOAPBinding.Style.DOCUMENT,
+ use = SOAPBinding.Use.LITERAL)
+@WebContext(contextRoot="/news",
+ urlPattern="/pressRelease")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> PressReleaseEndpoint <emphasis
role="bold">extends</emphasis> AbstractPressReleaseEndpoint
+{
+
+}
+</screen><para>To make it really easy, we used a SLSB endpoint without even
defining an interface. We chose Document/Literal style/use and explicitely set the service
name and namespace, as well as the context root and url pattern through the
<emphasis>@WebContext</emphasis> annotation. Thus nothing special here, no
attachments stuff required, we're simply preparing a basic service that will be
secured in the next chapter.</para><para> </para></section>
+<section
id="JBossWS-Securityandattachmentssample_Agency_client"><title>Agency
client</title><para>Once the server is implemented, we can deploy it and get
the generated wsdl contract. This way we generate the client through the <ulink
url="http://community.jboss.org/docs/DOC-13542">wsconsume<...
script (assume your bind address is localhost.localdomain:8080):</para><screen
xml:space="preserve">wsconsume.sh -k -p
org.jboss.test.ws.jaxws.samples.news.generated.agency
http://localhost.localdomain:8080/news/pressRelease?wsdl
+</screen><para>Referencing the generated classes, we hand code the agency
client:</para><screen xml:space="preserve"><emphasis
role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> Agency
+{
+ <emphasis role="bold">protected</emphasis> PressReleaseEndpoint
endpoint;
+
+ <emphasis role="bold">public</emphasis> Agency(URL url)
+ {
+ PressReleaseService service = <emphasis
role="bold">new</emphasis> PressReleaseService(url, <emphasis
role="bold">new</emphasis>
QName("http://org.jboss.ws/samples/news", "PressReleaseService"));
+ endpoint = service.getPressReleaseEndpointPort();
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> run(String title, String body)
+ {
+ PressRelease pressRelease = <emphasis
role="bold">new</emphasis> PressRelease();
+ pressRelease.setAgencyId("agency01");
+ pressRelease.setTitle(title);
+ pressRelease.setBody(body);
+ pressRelease.setDate(<emphasis role="bold">new</emphasis>
XMLGregorianCalendarImpl(<emphasis role="bold">new</emphasis>
GregorianCalendar()));
+ endpoint.submitPressRelease(pressRelease);
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">void</emphasis> main(String[] args)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ <emphasis role="bold">if</emphasis> (args.length == 3)
+ {
+ Agency agency = <emphasis role="bold">new</emphasis>
Agency(<emphasis role="bold">new</emphasis> URL(args[0]));
+ agency.run(args[1], args[2]);
+ System.out.println("Press release sent.");
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ System.out.println("Agency client usage:");
+ System.out.println("wsrunclient.sh -classpath agency.jar
org.jboss.test.ws.jaxws.samples.news.Agency http://host:port/news/pressRelease?wsdl title
body");
+ }
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+</screen></section>
+</section>
+<section
id="JBossWS-Securityandattachmentssample_The_newspaper_edition_endpoint"><title>The
newspaper edition endpoint</title><section
id="JBossWS-Securityandattachmentssample_MTOMXOP_newspaper_server"><title>MTOM/XOP
newspaper server</title><para>The class used to ship newspaper edition from
the main center to the printers/distributors is the following one:</para><screen
xml:space="preserve"><emphasis
role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> EditionMTOM
+{
+ <emphasis role="bold">private</emphasis> Date date;
+ <emphasis role="bold">private</emphasis> DataHandler content;
+ <emphasis role="bold">private</emphasis> String id;
+
+ <emphasis role="bold">public</emphasis> Date getDate()
+ {
+ <emphasis role="bold">return</emphasis> date;
+ }
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> setDate(Date date)
+ {
+ this.date = date;
+ }
+ @XmlMimeType("text/plain")
+ <emphasis role="bold">public</emphasis> DataHandler
getContent()
+ {
+ <emphasis role="bold">return</emphasis> content;
+ }
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> setContent(DataHandler content)
+ {
+ this.content = content;
+ }
+ <emphasis role="bold">public</emphasis> String getId()
+ {
+ <emphasis role="bold">return</emphasis> id;
+ }
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> setId(String id)
+ {
+ this.id = id;
+ }
+}
+</screen><para>Please note the <emphasis>@XmlMimeType</emphasis>
annotation used to set the MIME type of the attachment being enclosed to the message. For
ease we're using text-plain here, of course a real world use case will almost always
require something else, perhaps
<emphasis>application/octet-stream</emphasis>.</para><para>The
sample newspaper endpoint implementation is quite trivial:</para><screen
xml:space="preserve"><emphasis
role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> AbstractNewspaperMTOMEndpoint
+{
+ <emphasis role="bold">private</emphasis> Logger log =
Logger.getLogger(this.getClass());
+
+ <emphasis role="bold">public</emphasis> EditionMTOM
getNewspaperEdition(String newspaperId)
+ {
+ log.info("Newspaper edition requested: " + newspaperId);
+ EditionMTOM edition = <emphasis role="bold">new</emphasis>
EditionMTOM();
+ edition.setContent(<emphasis role="bold">new</emphasis>
DataHandler("This is the newspaper document with id " + newspaperId,
"text/plain"));
+ edition.setDate(<emphasis role="bold">new</emphasis>
Date());
+ edition.setId(newspaperId);
+ <emphasis role="bold">return</emphasis> edition;
+ }
+
+ <emphasis role="bold">public</emphasis> String[]
getNewspaperEditionIdList(Date from, Date to)
+ {
+ String[] ids = <emphasis role="bold">new</emphasis>
String[2];
+ ids[0] = "doc01";
+ ids[1] = "doc02";
+ <emphasis role="bold">return</emphasis> ids;
+ }
+}
+</screen><para>As you can see the edition's content is provided through
the DataHandler class, which allows you to use every content-types you might need. The
actual web service configuration is provided through the
<emphasis>NewspaperMTOMEndpoint</emphasis>:</para><screen
xml:space="preserve">@Stateless
+@WebService(endpointInterface =
"org.jboss.test.ws.jaxws.samples.news.NewspaperMTOM",
+ name = "NewspaperMTOMEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/news",
+ serviceName = "NewspaperMTOMService")
+@SOAPBinding(style = SOAPBinding.Style.RPC,
+ use = SOAPBinding.Use.LITERAL)
+@WebContext(contextRoot="/news",
+ urlPattern="/newspaper/mtom")
+@BindingType(value = "http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> NewspaperMTOMEndpoint <emphasis
role="bold">extends</emphasis> AbstractNewspaperMTOMEndpoint
<emphasis role="bold">implements</emphasis> NewspaperMTOM
+{
+
+}
+</screen><para>In this example we're using RPC/Literal to keep things
easier; the <emphasis>@BindingType</emphasis> annotation is required to enable
MTOM processing.</para><para> </para></section>
+<section
id="JBossWS-Securityandattachmentssample_SwaRef_newspaper_server"><title>SwaRef
newspaper server</title><para>The class used to ship newspaper edition from
the main center to the printers/distributors is the following one:</para><screen
xml:space="preserve">@XmlRootElement
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> EditionSWA
+{
+ <emphasis role="bold">private</emphasis> Date date;
+ <emphasis role="bold">private</emphasis> DataHandler content;
+ <emphasis role="bold">private</emphasis> String id;
+
+ <emphasis role="bold">public</emphasis> Date getDate()
+ {
+ <emphasis role="bold">return</emphasis> date;
+ }
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> setDate(Date date)
+ {
+ this.date = date;
+ }
+ @XmlElement
+ @XmlAttachmentRef
+ <emphasis role="bold">public</emphasis> DataHandler
getContent()
+ {
+ <emphasis role="bold">return</emphasis> content;
+ }
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> setContent(DataHandler content)
+ {
+ this.content = content;
+ }
+ <emphasis role="bold">public</emphasis> String getId()
+ {
+ <emphasis role="bold">return</emphasis> id;
+ }
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> setId(String id)
+ {
+ this.id = id;
+ }
+}
+</screen><para>Please note the
<emphasis>@XmlAttachmentRef</emphasis> annotation used to define which
attribute will be enclosed as attachment. The <emphasis>DataHandler</emphasis>
class has to be used here too.</para><para> </para><para>The
sample newspaper endpoint implementation is the same as the MTOM one except for the
<emphasis>EditionSWA</emphasis> class used instead of
<emphasis>EditionMTOM</emphasis>. The web service endpoint configuration
instead is simpler, since nothing more than what you would have in an usual endpoint
implementation is required:</para><screen
xml:space="preserve">@Stateless
+@WebService(endpointInterface =
"org.jboss.test.ws.jaxws.samples.news.NewspaperSWA",
+ name = "NewspaperSWAEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/news",
+ serviceName = "NewspaperSWAService")
+@SOAPBinding(style = SOAPBinding.Style.RPC,
+ use = SOAPBinding.Use.LITERAL)
+@WebContext(contextRoot="/news",
+ urlPattern="/newspaper/swa")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> NewspaperSWAEndpoint <emphasis
role="bold">extends</emphasis> AbstractNewspaperSWAEndpoint
<emphasis role="bold">implements</emphasis> NewspaperSWA
+{
+
+}
+</screen></section>
+<section
id="JBossWS-Securityandattachmentssample_Printer_client"><title>Printer
client</title><para>As for the press release endpoint, we generate the client
stuff using the <ulink
url="http://community.jboss.org/docs/DOC-13542">wsconsume<...
script, given the published wsdl contract:</para><screen
xml:space="preserve">wsconsume.sh -k -p
org.jboss.test.ws.jaxws.samples.news.generated.printer.mtom
http://localhost.localdomain:8080/news/newspaper/mtom?wsdl
+wsconsume.sh -k -p org.jboss.test.ws.jaxws.samples.news.generated.printer.swa
http://localhost.localdomain:8080/news/newspaper/swa?wsdl
+</screen><para>The sample printer is coded referencing the generated classes
and allows invocation of both the endpoints:</para><screen
xml:space="preserve"><emphasis
role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> Printer
+{
+ <emphasis role="bold">protected</emphasis> NewspaperMTOMEndpoint
mtomEndpoint;
+ <emphasis role="bold">protected</emphasis> NewspaperSWAEndpoint
swaEndpoint;
+ <emphasis role="bold">protected</emphasis> <emphasis
role="bold">boolean</emphasis> mtom;
+
+ <emphasis role="bold">public</emphasis> Printer(URL url,
<emphasis role="bold">boolean</emphasis> mtom)
+ {
+ this.mtom = mtom;
+ <emphasis role="bold">if</emphasis> (mtom)
+ {
+ NewspaperMTOMService mtomService = <emphasis
role="bold">new</emphasis> NewspaperMTOMService(url, <emphasis
role="bold">new</emphasis>
QName("http://org.jboss.ws/samples/news", "NewspaperMTOMService"));
+ mtomEndpoint = mtomService.getNewspaperMTOMEndpointPort();
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ NewspaperSWAService swaService = <emphasis
role="bold">new</emphasis> NewspaperSWAService(url, <emphasis
role="bold">new</emphasis>
QName("http://org.jboss.ws/samples/news", "NewspaperSWAService"));
+ swaEndpoint = swaService.getNewspaperSWAEndpointPort();
+ }
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> run() <emphasis
role="bold">throws</emphasis> IOException
+ {
+ XMLGregorianCalendar from = <emphasis
role="bold">new</emphasis> XMLGregorianCalendarImpl(<emphasis
role="bold">new</emphasis> GregorianCalendar(2008,1,10));
+ XMLGregorianCalendar to = <emphasis
role="bold">new</emphasis> XMLGregorianCalendarImpl(<emphasis
role="bold">new</emphasis> GregorianCalendar(2008,1,14));
+ <emphasis role="bold">if</emphasis> (mtom)
+ {
+
((SOAPBinding)(((BindingProvider)mtomEndpoint).getBinding())).setMTOMEnabled(<emphasis
role="bold">true</emphasis>);
+ <emphasis role="bold">for</emphasis> (String id :
mtomEndpoint.getNewspaperEditionIdList(from, to).getItem())
+ {
+ System.out.println("Downloading newspaper document: " + id);
+ EditionMTOM edition = mtomEndpoint.getNewspaperEdition(id);
+ System.out.println("Content: " + edition.getContent());
+ }
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ <emphasis role="bold">for</emphasis> (String id :
swaEndpoint.getNewspaperEditionIdList(from, to).getItem())
+ {
+ System.out.println("Downloading newspaper document: " + id);
+ EditionSWA edition = swaEndpoint.getNewspaperEdition(id);
+ DataHandler dh = edition.getContent();
+ System.out.println("Content type: " + dh.getContentType());
+ System.out.println("Content: " + dh.getContent());
+ }
+ }
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">void</emphasis> main(String[] args)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ <emphasis role="bold">if</emphasis> (args.length == 1)
+ {
+ Printer printer = <emphasis role="bold">new</emphasis>
Printer(<emphasis role="bold">new</emphasis> URL(args[0]),
args[0].endsWith("mtom?wsdl"));
+ printer.run();
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ System.out.println("Printer client usage:");
+ System.out.println("wsrunclient.sh -classpath agency.jar
org.jboss.test.ws.jaxws.samples.news.Printer
http://host:port/news/newspaper/mtom?wsdl");
+ System.out.println("or");
+ System.out.println("wsrunclient.sh -classpath agency.jar
org.jboss.test.ws.jaxws.samples.news.Printer
http://host:port/news/newspaper/swa?wsdl");
+ }
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+</screen><para>Please note we used the SOAPBinding's
<emphasis>setMTOMEnabled(boolean enable)</emphasis> method to enable the
MTOM/XOP processing.</para><para> </para></section>
+</section>
+<section
id="JBossWS-Securityandattachmentssample_Running_the_sample"><title>Running
the sample</title><para>Let's build the sample and take a look at the
final contents of the generated archives; the newspaper main center is in
<emphasis>jaxws-samples-news-step1-newspaper.jar</emphasis>:</para><screen
xml:space="preserve">[alessio@localhost trunk]$ jar -tvf
output/tests/libs/jaxws-samples-news-step1-newspaper.jar
+ 0 Fri Feb 08 11:40:50 CET 2008 META-INF/
+ 106 Fri Feb 08 11:40:48 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 08 11:38:20 CET 2008 org/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/test/
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/
+ 1867 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/AbstractNewspaperMTOMEndpoint.class
+ 1861 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/AbstractNewspaperSWAEndpoint.class
+ 1281 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/AbstractPressReleaseEndpoint.class
+ 1223 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/EditionMTOM.class
+ 1301 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/EditionSWA.class
+ 951 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/NewspaperMTOM.class
+ 1298 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/NewspaperMTOMEndpoint.class
+ 948 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/NewspaperSWA.class
+ 1265 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/NewspaperSWAEndpoint.class
+ 1208 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/PressRelease.class
+ 1059 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/PressReleaseEndpoint.class
+</screen><para>As you can see, it contains both the press release and
newspaper edition endpoint implementations (the latter in MTOM and Swa versions). No
descriptor is required.</para><para>The agency archive is
<emphasis>jaxws-samples-news-step1-agency.jar</emphasis>:</para><screen
xml:space="preserve">[alessio@localhost trunk]$ jar -tvf
output/tests/libs/jaxws-samples-news-step1-agency.jar
+ 0 Fri Feb 08 11:40:50 CET 2008 META-INF/
+ 106 Fri Feb 08 11:40:48 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 08 11:38:20 CET 2008 org/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/test/
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/
+ 2592 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/Agency.class
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/
+ 0 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/
+ 2813 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/ObjectFactory.class
+ 1640 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/PressRelease.class
+ 865 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/PressReleaseEndpoint.class
+ 1725 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/PressReleaseService.class
+ 1035 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/SubmitPressRelease.class
+ 647 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/SubmitPressReleaseResponse.class
+ 291 Fri Feb 08 11:39:50 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/package-info.class
+</screen><para>It contains nothing more than the hand coded client class and
the wsconsume generated classes.</para><para>Finally, the printer archive is
<emphasis>jaxws-samples-news-step1-printer.jar</emphasis>:</para><screen
xml:space="preserve">[alessio@localhost trunk]$ jar -tvf
output/tests/libs/jaxws-samples-news-step1-printer.jar
+ 0 Fri Feb 08 11:40:50 CET 2008 META-INF/
+ 106 Fri Feb 08 11:40:48 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 08 11:38:20 CET 2008 org/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/test/
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/
+ 5444 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/Printer.class
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/
+ 0 Fri Feb 08 11:39:50 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/
+ 0 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/
+ 1599 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/EditionMTOM.class
+ 1115 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/NewspaperMTOMEndpoint.class
+ 1760 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/NewspaperMTOMService.class
+ 958 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/ObjectFactory.class
+ 993 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/StringArray.class
+ 295 Fri Feb 08 11:39:50 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/package-info.class
+ 0 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/
+ 1717 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/EditionSWA.class
+ 1108 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/NewspaperSWAEndpoint.class
+ 1746 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/NewspaperSWAService.class
+ 1896 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/ObjectFactory.class
+ 991 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/StringArray.class
+ 294 Fri Feb 08 11:39:50 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/package-info.class
+</screen><para>The same things just written for the agency archive apply here
too.</para><para> </para><para>You need to deploy the newspaper
archive to your application server (perhaps you already did so, if you tried creating the
client above); then just run the two clients using the <ulink
url="http://community.jboss.org/docs/DOC-13529">wsrunclient&...
script.</para><para>Running the agency client:</para><screen
xml:space="preserve">wsrunclient.sh -classpath
jaxws-samples-news-step1-agency.jar org.jboss.test.ws.jaxws.samples.news.Agency
http://localhost.localdomain:8080/news/pressRelease?wsdl Title Body
+</screen><para>you'll get something like this on the server
log:</para><screen xml:space="preserve">15:38:30,360 INFO
[PressReleaseEndpoint] Received a press release from agency: agency01
+15:38:30,360 INFO [PressReleaseEndpoint] - Title: Title
+15:38:30,360 INFO [PressReleaseEndpoint] - Text: Body
+</screen><para>Running the printer client (MTOM/XOP
version):</para><screen xml:space="preserve">wsrunclient.sh
-classpath jaxws-samples-news-step1-printer.jar
org.jboss.test.ws.jaxws.samples.news.Printer
http://localhost.localdomain:8080/news/newspaper/mtom?wsdl
+</screen><para>you'll get this on the client log:</para><screen
xml:space="preserve">Downloading newspaper document: doc01
+Content: VGhpcyBpcyB0aGUgbmV3c3BhcGVyIGRvY3VtZW50IHdpdGggaWQgZG9jMDE=
+Downloading newspaper document: doc02
+Content: VGhpcyBpcyB0aGUgbmV3c3BhcGVyIGRvY3VtZW50IHdpdGggaWQgZG9jMDI=
+</screen><para>The capture of one of the exchanged messages shows the
<emphasis>xop:Include</emphasis> element being used to reference the
attachment:</para><screen xml:space="preserve">HTTP/1.1 200 OK
+Server: Apache-Coyote/1.1
+X-Powered-By: Servlet 2.4; JBoss-4.2.3.GA (build: SVNTag=JBoss_4_2_3_GA
date=200801291425)/JBossWeb-2.0
+Content-Type: multipart/related; type="application/xop+xml";
start="&lt;rootpart(a)ws.jboss.org&gt;";
.start-info="text/xml";
.boundary="----=_Part_11_27939361.1202482223654"
+Transfer-Encoding: chunked
+Date: Fri, 08 Feb 2008 14:50:23 GMT
+
+------=_Part_11_27939361.1202482223654
+Content-Type: application/xop+xml; type="text/xml"
+Content-Transfer-Encoding: 8bit
+Content-ID: &lt;rootpart(a)ws.jboss.org&gt;
+
+<env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/news'><return><content><xop:Include
xmlns:xop="http://www.w3.org/2004/08/xop/include"
href="cid:content-454e2c56-10d9-4393-8050-241578a4f812@ws.jboss.org"/></content><date>2008-02-08T15:50:23.652+01:00</date><id>doc02</id></return></ns1:getNewspaperEditionResponse></env:Body></env:Envelope>
+
+------=_Part_11_27939361.1202482223654
+Content-Type: text/plain
+Content-Transfer-Encoding: binary
+Content-Id: &lt;content-454e2c56-10d9-4393-8050-241578a4f812(a)ws.jboss.org&gt;
+
+This is the newspaper document with id doc02
+
+------=_Part_11_27939361.1202482223654--
+</screen><para>Finally, running the SwaRef version of printer
client:</para><screen xml:space="preserve">wsrunclient.sh -classpath
jaxws-samples-news-step1-printer.jar org.jboss.test.ws.jaxws.samples.news.Printer
http://localhost.localdomain:8080/news/newspaper/swa?wsdl
+</screen><para>you'll get this on the client log:</para><screen
xml:space="preserve">Downloading newspaper document: doc01
+Content: text/plain
+Content: This is the newspaper document with id doc01
+Downloading newspaper document: doc02
+Content: text/plain
+Content: This is the newspaper document with id doc02
+</screen><para>The capture of one of the exchanged messages shows the MIME
attachment being used:</para><screen xml:space="preserve">HTTP/1.1
200 OK
+Server: Apache-Coyote/1.1
+X-Powered-By: Servlet 2.4; JBoss-4.2.3.GA (build: SVNTag=JBoss_4_2_3_GA
date=200801291425)/JBossWeb-2.0
+Content-Type: multipart/related; type="text/xml";
start="&lt;rootpart(a)ws.jboss.org&gt;";
.boundary="----=_Part_7_26058.1202481869751"
+Transfer-Encoding: chunked
+Date: Fri, 08 Feb 2008 14:44:29 GMT
+
+------=_Part_7_26058.1202481869751
+Content-Type: text/xml; charset=UTF-8
+Content-Transfer-Encoding: 8bit
+Content-ID: &lt;rootpart(a)ws.jboss.org&gt;
+
+<env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
xmlns:ns1='http://org.jboss.ws/samples/news'><return><content>cid:0-1202481869750-15993608@ws.jboss.org</content><date>2008-02-08T15:44:29.749+01:00</date><id>doc02</id></return></ns1:getNewspaperEditionResponse></env:Body></env:Envelope>
+
+------=_Part_7_26058.1202481869751
+Content-Type: text/plain
+Content-Transfer-Encoding: binary
+Content-Id: &lt;0-1202481869750-15993608(a)ws.jboss.org&gt;
+
+This is the newspaper document with id doc02
+
+------=_Part_7_26058.1202481869751--</screen></section>
+</section>
+<section
id="JBossWS-Securityandattachmentssample_Security"><title>Security</title><para>Securing
a web service application implies performing different changes to both consumers and
producers to achieve for example confidentiality, accountability, etc. Different degrees
of security might be required according to the application's aims. That's the
reason why the current sample shows different
solutions.</para><para> </para><section
id="JBossWS-Securityandattachmentssample_The_press_release_endpoint_305547"><title>The
press release endpoint</title><para>Suppose the newspaper and agency's
owners want the maximum confidentiality regarding the exchanged press release. Thus we
decide to obtain message level security using <link
linkend="WSSecurity">WS-Security</link>. In particular, messages will
be both encrypted and signed; moreover each of them will have a
timestamp.</para><para> </para><para>Assuming the client side to
be <emphasis>alice</emphasis> and the server side <emp!
hasis>bob</emphasis>, we're going to use the following jbossws ws-security
configuration files (jboss-wsse-client.xml first):</para><screen
xml:space="preserve"><jboss-ws-security xmlns="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ <ulink
url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.x...
+
<key-store-file>META-INF/alice-sign_enc.jks</key-store-file>
+ <key-store-password>password</key-store-password>
+ <key-store-type>jks</key-store-type>
+
<trust-store-file>META-INF/wsse10.truststore</trust-store-file>
+ <trust-store-password>password</trust-store-password>
+ <config>
+ <timestamp ttl="300"/>
+ <sign type="x509v3" alias="1"
includeTimestamp="true"/>
+ <encrypt type="x509v3" alias="bob"/>
+ <requires>
+ <signature/>
+ <encryption/>
+ </requires>
+ </config>
+</jboss-ws-security><jboss-ws-security xmlns="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ <ulink
url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.x...
+ <key-store-file>META-INF/bob-sign_enc.jks</key-store-file>
+ <key-store-password>password</key-store-password>
+ <key-store-type>jks</key-store-type>
+
<trust-store-file>META-INF/wsse10.truststore</trust-store-file>
+
<trust-store-password>password</trust-store-password>
+ <config>
+ <timestamp ttl="300"/>
+ <sign type="x509v3" alias="1"
includeTimestamp="true"/>
+ <encrypt type="x509v3" alias="alice"/>
+ <requires>
+ <signature/>
+ <encryption/>
+ </requires>
+ </config>
+</jboss-ws-security></screen><para>Please refer to the
<emphasis>src/test/resources/jaxws/samples/news/META-INF/readme.txt</emphasis>
file for a contents' explanation of the keystores, truststore and certificates used in
the sample.</para><para>The secure web service endpoint is obtained specifying
the ws-security endpoint configuration through the
<emphasis>@EndpointConfig</emphasis> annotation:</para><screen
xml:space="preserve">@Stateless
+@WebService(name = "PressReleaseEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/news",
+ serviceName = "PressReleaseService")
+@SOAPBinding(style = SOAPBinding.Style.DOCUMENT,
+ use = SOAPBinding.Use.LITERAL)
+@WebContext(contextRoot="/news",
+ urlPattern="/pressRelease")
+@EndpointConfig(configName = "Standard WSSecurity Endpoint")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> SecurePressReleaseEndpoint <emphasis
role="bold">extends</emphasis> AbstractPressReleaseEndpoint
+{
+
+}
+</screen><para>Of course also the secure agency client needs the right
configuration:</para><screen xml:space="preserve"><emphasis
role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> SecureAgency <emphasis
role="bold">extends</emphasis> Agency
+{
+ <emphasis role="bold">public</emphasis> SecureAgency(URL url)
+ {
+ <emphasis role="bold">super</emphasis>(url);
+ ((StubExt)endpoint).setConfigName("Standard WSSecurity Client");
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">void</emphasis> main(String[] args)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ <emphasis role="bold">if</emphasis> (args.length == 3)
+ {
+ Agency agency = <emphasis role="bold">new</emphasis>
SecureAgency(<emphasis role="bold">new</emphasis> URL(args[0]));
+ agency.run(args[1], args[2]);
+ System.out.println("Press release sent.");
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ System.out.println("SecureAgency client usage:");
+ System.out.println("./wsrunclient.sh -classpath agency.jar
org.jboss.test.ws.jaxws.samples.news.SecureAgency " +
+ "http://localhost.localdomain:8080/news/pressRelease?wsdl
title body");
+ }
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+</screen></section>
+<section
id="JBossWS-Securityandattachmentssample_The_newspaper_edition_endpoint_15069"><title>The
newspaper edition endpoint</title><para>Suppose the message exchange between
the newspaper main center and the printers/distributors has lower security requirements;
we decide to achieve accountability through BASIC <ulink
url="http://community.jboss.org/docs/DOC-13533">authenticati...
and confidentiality <ulink
url="http://community.jboss.org/docs/DOC-13534">securing the
transport</ulink> with HTTPS.</para><para>The secure MTOM/XOP endpoint
implementation is obtained this way:</para><screen
xml:space="preserve">@Stateless
+@WebService(endpointInterface =
"org.jboss.test.ws.jaxws.samples.news.NewspaperMTOM",
+ name = "NewspaperMTOMEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/news",
+ serviceName = "NewspaperMTOMService")
+@SOAPBinding(style = SOAPBinding.Style.RPC,
+ use = SOAPBinding.Use.LITERAL)
+@SecurityDomain("JBossWS")
+@WebContext(contextRoot="/news",
+ urlPattern="/newspaper/mtom",
+ authMethod="BASIC",
+ transportGuarantee="CONFIDENTIAL",
+ secureWSDLAccess=<emphasis role="bold">false</emphasis>)
+@BindingType(value = "http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> SecureNewspaperMTOMEndpoint <emphasis
role="bold">extends</emphasis> AbstractNewspaperMTOMEndpoint
<emphasis role="bold">implements</emphasis> NewspaperMTOM
+{
+
+}
+</screen><para>For ease, we use the <emphasis>JBossWS</emphasis>
default security domain, of course you might want to use another one with your own custom
login module. The <emphasis>@WebContext</emphasis> annotation sets the
authentication method and enforce the https use
(<emphasis>transportGuarantee="CONFIDENTIAL"</emphasis>). The secure
SwaRef endpoint implementation is obtained the same way as the MTOM/XOP
one.</para><para> </para><para>On the client side, we just need to
set the username/password:</para><screen
xml:space="preserve"><emphasis
role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> SecurePrinter <emphasis
role="bold">extends</emphasis> Printer
+{
+ <emphasis role="bold">public</emphasis> SecurePrinter(URL url,
<emphasis role="bold">boolean</emphasis> mtom)
+ {
+ <emphasis role="bold">super</emphasis>(url,mtom);
+ BindingProvider bp = mtom ? (BindingProvider)mtomEndpoint :
(BindingProvider)swaEndpoint;
+ bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, "kermit");
+ bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY,
"thefrog");
+ System.setProperty("org.jboss.security.ignoreHttpsHost",
"true");
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">static</emphasis> <emphasis
role="bold">void</emphasis> main(String[] args)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ <emphasis role="bold">if</emphasis> (args.length == 1)
+ {
+ SecurePrinter printer = <emphasis
role="bold">new</emphasis> SecurePrinter(<emphasis
role="bold">new</emphasis> URL(args[0]),
args[0].endsWith("mtom?wsdl"));
+ printer.run();
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ System.out.println("SecurePrinter client usage:");
+ System.out.println("wsrunclient.sh -classpath agency.jar
-Djavax.net.ssl.trustStore=truststorePath -Djavax.net.ssl.trustStorePassword=truststorePwd
" +
+ "org.jboss.test.ws.jaxws.samples.news.SecurePrinter
http://host:port/news/newspaper/mtom?wsdl");
+ System.out.println("or");
+ System.out.println("wsrunclient.sh -classpath agency.jar
-Djavax.net.ssl.trustStore=truststorePath -Djavax.net.ssl.trustStorePassword=truststorePwd
" +
+ "org.jboss.test.ws.jaxws.samples.news.SecurePrinter
http://host:port/news/newspaper/swa?wsdl");
+ }
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+</screen><para>For an explanation of the reason for setting the
<emphasis>org.jboss.security.ignoreHttpsHost</emphasis> property to true,
please read <ulink
url="http://community.jboss.org/docs/DOC-13534#Client_side">...
suggested in the SecurePrinter usage info, you would need to set the
<emphasis>javax.net.ssl.trustStore</emphasis> and
<emphasis>javax.net.ssl.trustStorePassword</emphasis> for the client to be
able to perform the https connection. Finally, we enabled the server Tomcat+SSL connector
adding this to the jboss-web.deployer/server.xml:</para><screen
xml:space="preserve"><Connector port="8443"
protocol="HTTP/1.1" SSLEnabled="true"
+ maxThreads="150" scheme="https" secure="true"
+ keystoreFile="${jboss.server.home.dir}/my.keystore"
+ truststoreFile="${jboss.server.home.dir}/my.truststore"
+ clientAuth="false" sslProtocol="TLS"
/></screen></section>
+<section
id="JBossWS-Securityandattachmentssample_Running_the_sample_824473"><title>Running
the sample</title><para>Once we build the sample we have the following
archives for the secure version:</para><screen
xml:space="preserve">[alessio@localhost trunk]$ jar -tvf
output/tests/libs/jaxws-samples-news-step2-newspaper.jar
+ 0 Fri Feb 08 17:41:44 CET 2008 META-INF/
+ 106 Fri Feb 08 17:41:42 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 08 11:38:20 CET 2008 org/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/test/
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/
+ 1867 Fri Feb 08 17:41:30 CET 2008
org/jboss/test/ws/jaxws/samples/news/AbstractNewspaperMTOMEndpoint.class
+ 1861 Fri Feb 08 17:41:30 CET 2008
org/jboss/test/ws/jaxws/samples/news/AbstractNewspaperSWAEndpoint.class
+ 1281 Fri Feb 08 17:41:30 CET 2008
org/jboss/test/ws/jaxws/samples/news/AbstractPressReleaseEndpoint.class
+ 1223 Fri Feb 08 17:41:30 CET 2008
org/jboss/test/ws/jaxws/samples/news/EditionMTOM.class
+ 1301 Fri Feb 08 17:41:30 CET 2008
org/jboss/test/ws/jaxws/samples/news/EditionSWA.class
+ 951 Fri Feb 08 17:41:30 CET 2008
org/jboss/test/ws/jaxws/samples/news/NewspaperMTOM.class
+ 948 Fri Feb 08 17:41:30 CET 2008
org/jboss/test/ws/jaxws/samples/news/NewspaperSWA.class
+ 1208 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/PressRelease.class
+ 1480 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/SecureNewspaperMTOMEndpoint.class
+ 1379 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/SecureNewspaperSWAEndpoint.class
+ 1173 Fri Feb 08 17:41:30 CET 2008
org/jboss/test/ws/jaxws/samples/news/SecurePressReleaseEndpoint.class
+ 2362 Fri Feb 08 11:40:32 CET 2008 META-INF/bob-sign_enc.jks
+ 850 Fri Feb 08 11:40:20 CET 2008 META-INF/jboss-wsse-server.xml
+ 1656 Fri Feb 08 11:40:30 CET 2008 META-INF/wsse10.truststore
+</screen><screen xml:space="preserve">[alessio@localhost trunk]$
jar -tvf output/tests/libs/jaxws-samples-news-step2-agency.jar
+ 0 Fri Feb 08 17:41:44 CET 2008 META-INF/
+ 106 Fri Feb 08 17:41:42 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 08 11:38:20 CET 2008 org/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/test/
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/
+ 2592 Fri Feb 08 17:41:30 CET 2008 org/jboss/test/ws/jaxws/samples/news/Agency.class
+ 1461 Fri Feb 08 17:41:30 CET 2008
org/jboss/test/ws/jaxws/samples/news/SecureAgency.class
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/
+ 0 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/
+ 2813 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/ObjectFactory.class
+ 1640 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/PressRelease.class
+ 865 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/PressReleaseEndpoint.class
+ 1725 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/PressReleaseService.class
+ 1035 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/SubmitPressRelease.class
+ 647 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/SubmitPressReleaseResponse.class
+ 291 Fri Feb 08 11:39:50 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/agency/package-info.class
+ 2358 Fri Feb 08 11:40:30 CET 2008 META-INF/alice-sign_enc.jks
+ 814 Fri Feb 08 17:41:32 CET 2008 META-INF/jboss-wsse-client.xml
+ 1656 Fri Feb 08 11:40:30 CET 2008 META-INF/wsse10.truststore
+</screen><screen xml:space="preserve">[alessio@localhost trunk]$
jar -tvf output/tests/libs/jaxws-samples-news-step2-printer.jar
+ 0 Fri Feb 08 18:01:14 CET 2008 META-INF/
+ 106 Fri Feb 08 18:01:12 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 08 11:38:20 CET 2008 org/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/test/
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/
+ 5464 Fri Feb 08 17:41:30 CET 2008 org/jboss/test/ws/jaxws/samples/news/Printer.class
+ 2324 Fri Feb 08 18:01:00 CET 2008
org/jboss/test/ws/jaxws/samples/news/SecurePrinter.class
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/
+ 0 Fri Feb 08 11:39:50 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/
+ 0 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/
+ 1599 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/EditionMTOM.class
+ 1115 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/NewspaperMTOMEndpoint.class
+ 1760 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/NewspaperMTOMService.class
+ 958 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/ObjectFactory.class
+ 993 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/StringArray.class
+ 295 Fri Feb 08 11:39:50 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/package-info.class
+ 0 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/
+ 1717 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/EditionSWA.class
+ 1108 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/NewspaperSWAEndpoint.class
+ 1746 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/NewspaperSWAService.class
+ 1896 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/ObjectFactory.class
+ 991 Fri Feb 08 11:39:52 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/StringArray.class
+ 294 Fri Feb 08 11:39:50 CET 2008
org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/package-info.class
+</screen><para>We basically added the secure version of endpoints and
clients, as well as the required ws-security descriptors and
keystores.</para><para>While running the agency
client...</para><screen xml:space="preserve">wsrunclient.sh
-classpath jaxws-samples-news-step2-agency.jar
org.jboss.test.ws.jaxws.samples.news.SecureAgency
http://localhost.localdomain:8080/news/pressRelease?wsdl title body
+</screen><para>we can for example capture the request message and verify that
it's encrypted and signed:</para><screen
xml:space="preserve">HTTP/1.1 200 OK
+Server: Apache-Coyote/1.1
+X-Powered-By: Servlet 2.4; JBoss-4.2.3.GA (build: SVNTag=JBoss_4_2_3_GA
date=200801291425)/JBossWeb-2.0
+Content-Type: text/xml;charset=UTF-8
+Transfer-Encoding: chunked
+Date: Fri, 08 Feb 2008 19:03:44 GMT
+
+<env:Envelope
xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>&...
env:mustUnderstand='1'
xmlns:wsse='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-w...
xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-ws...
wsu:Id='timestamp'><wsu:Created>2008-02-08T19:03:43.991Z</wsu:Created><wsu:Expires>2008-02-08T19:08:43.991Z</wsu:Expires></wsu:Timestamp><wsse:BinarySecurityToken
EncodingType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss...
ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x5...
wsu:Id='token-17-1202497424002-6508395'>MIIDDDCCAfSgAwIBAgIQM6YEf7FVYx/tZyEXgVComTANBgkqhkiG9w0BAQUFADAwMQ4wDAYDVQQK
+DAVPQVNJUzEeMBwGA1UEAwwVT0FTSVMgSW50ZXJvcCBUZXN0IENBMB4XDTA1MDMxOTAwMDAwMFoX
+DTE4MDMxOTIzNTk1OVowQjEOMAwGA1UECgwFT0FTSVMxIDAeBgNVBAsMF09BU0lTIEludGVyb3Ag
+VGVzdCBDZXJ0MQ4wDAYDVQQDDAVBbGljZTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAoqi9
+9By1VYo0aHrkKCNT4DkIgPL/SgahbeKdGhrbu3K2XG7arfD9tqIBIKMfrX4Gp90NJa85AV1yiNsE
+yvq+mUnMpNcKnLXLOjkTmMCqDYbbkehJlXPnaWLzve+mW0pJdPxtf3rbD4PS/cBQIvtpjmrDAU8V
+sZKT8DN5Kyz+EZsCAwEAAaOBkzCBkDAJBgNVHRMEAjAAMDMGA1UdHwQsMCowKKImhiRodHRwOi8v
+aW50ZXJvcC5iYnRlc3QubmV0L2NybC9jYS5jcmwwDgYDVR0PAQH/BAQDAgSwMB0GA1UdDgQWBBQK
+4l0TUHZ1QV3V2QtlLNDm+PoxiDAfBgNVHSMEGDAWgBTAnSj8wes1oR3WqqqgHBpNwkkPDzANBgkq
+hkiG9w0BAQUFAAOCAQEABTqpOpvW+6yrLXyUlP2xJbEkohXHI5OWwKWleOb9hlkhWntUalfcFOJA
+gUyH30TTpHldzx1+vK2LPzhoUFKYHE1IyQvokBN2JjFO64BQukCKnZhldLRPxGhfkTdxQgdf5rCK
+/wh3xVsZCNTfuMNmlAM6lOAg8QduDah3WFZpEA0s2nwQaCNQTNMjJC8tav1CBr6+E5FAmwPXP7pJ
+xn9Fw9OXRyqbRA4v2y7YpbGkG2GI9UvOHw6SGvf4FRSthMMO35YbpikGsLix3vAsXWWi4rwfVOYz
+QK0OFPNi9RMCUdSH06m9uLWckiCxjos0FQODZE9l4ATGy9s9hNVwryOJTw==</wsse:BinarySecurityToken><wsse:BinarySecurityToken
EncodingType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss...
ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x5...
wsu:Id='token-14-1202497424000-24093349'>MIIDCjCCAfKgAwIBAgIQYDju2/6sm77InYfTq65x+DANBgkqhkiG9w0BAQUFADAwMQ4wDAYDVQQK
+DAVPQVNJUzEeMBwGA1UEAwwVT0FTSVMgSW50ZXJvcCBUZXN0IENBMB4XDTA1MDMxOTAwMDAwMFoX
+DTE4MDMxOTIzNTk1OVowQDEOMAwGA1UECgwFT0FTSVMxIDAeBgNVBAsMF09BU0lTIEludGVyb3Ag
+VGVzdCBDZXJ0MQwwCgYDVQQDDANCb2IwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMCquMva
+4lFDrv3fXQnKK8CkSU7HvVZ0USyJtlL/yhmHH/FQXHyYY+fTcSyWYItWJYiTZ99PAbD+6EKBGbdf
+uJNUJCGaTWc5ZDUISqM/SGtacYe/PD/4+g3swNPzTUQAIBLRY1pkr2cm3s5Ch/f+mYVNBR41HnBe
+Ixybw25kkoM7AgMBAAGjgZMwgZAwCQYDVR0TBAIwADAzBgNVHR8ELDAqMCiiJoYkaHR0cDovL2lu
+dGVyb3AuYmJ0ZXN0Lm5ldC9jcmwvY2EuY3JsMA4GA1UdDwEB/wQEAwIEsDAdBgNVHQ4EFgQUXeg5
+5vRyK3ZhAEhEf+YT0z986L0wHwYDVR0jBBgwFoAUwJ0o/MHrNaEd1qqqoBwaTcJJDw8wDQYJKoZI
+hvcNAQEFBQADggEBAIiVGv2lGLhRvmMAHSlY7rKLVkv+zEUtSyg08FBT8z/RepUbtUQShcIqwWse
+mDU8JVtsucQLc+g6GCQXgkCkMiC8qhcLAt3BXzFmLxuCEAQeeFe8IATr4wACmEQE37TEqAuWEIan
+PYIplbxYgwP0OBWBSjcRpKRAxjEzuwObYjbll6vKdFHYIweWhhWPrefquFp7TefTkF4D3rcctTfW
+J76I5NrEVld+7PBnnJNpdDEuGsoaiJrwTW3Ixm40RXvG3fYS4hIAPeTCUk3RkYfUkqlaaLQnUrF2
+hZSgiBNLPe8gGkYORccRIlZCGQDEpcWl1Uf9OHw6fC+3hkqolFd5CVI=</wsse:BinarySecurityToken><xenc:EncryptedKey
xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'><xen...
Algorithm='http://www.w3.org/2001/04/xmlenc#rsa-1_5'
xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'/><ds...
xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<wsse:SecurityTokenReference
wsu:Id='reference-18-1202497424003-32714846'><wsse:Reference
URI='#token-17-1202497424002-6508395'
ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x5...
+</ds:KeyInfo><xenc:CipherData
xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'><xen...
xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'>N6udrhTegMr...
+/TwKi88yC5E/fDCojmYc1KJV3Jq3jp2j68Z+ZaopLmciiO49ySu7DKsdPL6Cc2bq6bSh6YKgOboH
+8eYfo9OsoAyK8QG4oIc=</xenc:CipherValue></xenc:CipherData><xenc:ReferenceList
xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'><xen...
URI='#encrypted-16-1202497424001-26591181'
xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'/></x...
xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<ds:SignedInfo xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<ds:CanonicalizationMethod
Algorithm='http://www.w3.org/2001/10/xml-exc-c14n#'
xmlns:ds='http://www.w3.org/2000/09/xmldsig#'/>
+<ds:SignatureMethod Algorithm='http://www.w3.org/2000/09/xmldsig#rsa-sha1'
xmlns:ds='http://www.w3.org/2000/09/xmldsig#'/>
+<ds:Reference URI='#element-13-1202497423991-15458568'
xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<ds:Transforms xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<ds:Transform Algorithm='http://www.w3.org/2001/10/xml-exc-c14n#'
xmlns:ds='http://www.w3.org/2000/09/xmldsig#'/>
+</ds:Transforms>
+<ds:DigestMethod Algorithm='http://www.w3.org/2000/09/xmldsig#sha1'
xmlns:ds='http://www.w3.org/2000/09/xmldsig#'/>
+<ds:DigestValue
xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>tfTeWLN1EkJG...
+</ds:Reference>
+<ds:Reference URI='#timestamp'
xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<ds:Transforms xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<ds:Transform Algorithm='http://www.w3.org/2001/10/xml-exc-c14n#'
xmlns:ds='http://www.w3.org/2000/09/xmldsig#'/>
+</ds:Transforms>
+<ds:DigestMethod Algorithm='http://www.w3.org/2000/09/xmldsig#sha1'
xmlns:ds='http://www.w3.org/2000/09/xmldsig#'/>
+<ds:DigestValue
xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>c7QCbyPei07w...
+</ds:Reference>
+</ds:SignedInfo>
+<ds:SignatureValue xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+Gib/sFAZQPX1cKtVp3UHbLr275lkOESbRRW/ShX6VVgJRgXaJlqEvzZzbHyzNh8XJdatsP2RJlOs
+A3/By6aejJLPU8bTmb9j2KMUkFid8arvLyF5ezNZc3/YHF+UNjH6JjK1lKwqjE8WF0i4sBFXzUkP
+oGMTkdDaNyLtqYJa+7k=
+</ds:SignatureValue>
+<ds:KeyInfo xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<wsse:SecurityTokenReference
wsu:Id='reference-15-1202497424000-2041959'><wsse:Reference
URI='#token-14-1202497424000-24093349'
ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x5...
+</ds:KeyInfo>
+</ds:Signature></wsse:Security></env:Header><env:Body
xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-ws...
wsu:Id='element-13-1202497423991-15458568'><xenc:EncryptedData
Id='encrypted-16-1202497424001-26591181'
Type='http://www.w3.org/2001/04/xmlenc#Content'
xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'><xen...
Algorithm='http://www.w3.org/2001/04/xmlenc#aes128-cbc'
xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'/>
+<xenc:CipherData
xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'><xen...
xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'>Wwt17Rt46aE...
+YxFboMBGjCCln7WqcLZBKUmVffAr/gzMod4OAkMUER2T/GhhQp1hyZH2eo65pgy5slA4dHN5une7
++LuSev4VQRGazsmHOv2ObI4fMUEdD9D/Luvt/WwvmNHd/dyvzBybEZOBuqsZLZA6hzEwWKp6JK0B
+TPiYvRyledLYDtAuZzVTWa70qIOdBlJpTbFmvY3CWZaxXtHWiRTX9I+x88N8hyf/HYbTb3nV+5ZE
+DZgcKjG8fMxF6nGPfcfXr5lm6GqlME4B4ImCPb9AtZqjVKyX3MO166hVLsy0EiqPbiikyWBD07p4
+hbKs1X8n+m9M3SdAVtEeh50zqzpIp96lKlbHmwZ27wro6KQ=
+</xenc:CipherValue>
+</xenc:CipherData>
+</xenc:EncryptedData>
+</env:Body></env:Envelope></screen><para>Instead
the MTOM/XOP printer client can be run this way...</para><screen
xml:space="preserve">wsrunclient.sh -classpath
jaxws-samples-news-step2-printer.jar -Djavax.net.ssl.trustStore=my.truststore
-Djavax.net.ssl.trustStorePassword=changeit
org.jboss.test.ws.jaxws.samples.news.SecurePrinter
http://localhost.localdomain:8080/news/newspaper/mtom?wsdl
+</screen><para>... and of course we can't see the messages' contents
due to the SSL encryption.</para></section>
+</section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-UserGuide.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-UserGuide.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-UserGuide.xml 2010-11-02 19:25:45 UTC (rev
13202)
@@ -0,0 +1,475 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-UserGuide"><title>JBossWS-UserGuide</title><para/><section
id="JBossWS-UserGuide_Introduction_and_architecture"><title>Introduction
and architecture</title><para> </para><para>The high level
architecture of the JBossWS Web Service Framework is presented in the image here
below:</para><para><ulink
url="http://jboss.org/file-access/default/members/jbossws/images/wsf...
fileref="images/wsf.png" depth="436"
width="579"/></imageobject></mediaobject></ulink></para><para> </para><para>This
basically means users can choose to download, install and use three different JBossWS
versions:</para><itemizedlist><listitem><para><emphasis
role="bold">JBossWS Native</emphasis>: this is the JBossWS Web Service
Framework integrating the original JBossWS native stack that has been developed in the
past years. This is what currently comes installed by default in every JBoss Application
Server!
released version and has been used on top of JBoss AS 5 to make it successfully
certified for Java EE 5. Please refer the <link
linkend="chap_JBossWS-NativeUserGuide">JBossWS Native stack user
guide</link> for a complete documentation of JBossWS-Native specific
features.</para></listitem><listitem><para><emphasis
role="bold">JBossWS CXF</emphasis>: this is the JBossWS Web Service
Framework integrating the <ulink url="http://cxf.apache.org/">Apache
CXF</ulink> web service stack. Please refer the <ulink
url="http://community.jboss.org/docs/DOC-13562">JBossWS CXF stack user
guide</ulink> for a complete documentation of JBossWS-CXF specific
features.</para></listitem><listitem><para><emphasis
role="bold">JBossWS Metro</emphasis>: this is the JBossWS Web Service
Framework integrating the <ulink
url="https://metro.dev.java.net/">GlassFish Metro</ulink> web service
stack. Please refer the <ulink
url="http://community.jboss.org/docs/DOC-13561">JBossWS Metro stack user
guide</ulink!
![url="http://jbossws.jboss.org/mediawiki/index.php?title=Image:Eventi...](http://url="http://jbossws.jboss.org/mediawiki/index.php?title=Image%3AEventingCollaboration.gif%22%2F%3EEventing){kind=link}
![url="http://jboss.org/file-access/default/members/jbossws/images/wsf...](http://url="http://jboss.org/file-access/default/members/jbossws/images/wsf.png%22%3E%3Cmediaobject%3E%3Cimageobject%3E%3Cimagedata){kind=link}
for a complete documentation of JBossWS-Metro specific featu!
res.</pa
ra></listitem></itemizedlist><para> </para><para>The
JBossWS web service framework provides common features, tooling, management, deployment
framework, etc. for all the supported stacks. At the same time, each stack comes with its
own specific functional feature set, performance characteristics and -of course-
community. So users can definitely choose the stack that best suits their needs and
successfully use it on top of JBoss Application
Server.</para><para> </para></section>
+<section id="JBossWS-UserGuide_Common_User_Guide"><title>Common
User Guide</title><para> </para><para>Here below is the
documentation that applies to every supported stacks. This includes basic JAX-WS usage as
well as references to common additional functionalities the JBossWS Web Service Framework
provides on top of the supported stacks.</para><section
id="JBossWS-UserGuide_Web_Service_Concepts"><title>Web Service
Concepts</title><section
id="JBossWS-UserGuide_DocumentLiteral"><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 XM!
L document that can be validated against XML schema.</para><para>Document is
defined by the style attribute on the SOAP binding.</para><screen
xml:space="preserve"> <binding name='EndpointInterfaceBinding'
type='tns:EndpointInterface'>
+ <soap:binding style='document' transport='<ulink
url="http://schemas.xmlsoap.org/soap/http'/">http://sche...
+ <operation name='concat'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body use='literal'/>
+ </input>
+ <output>
+ <soap:body use='literal'/>
+ </output>
+ </operation></binding>
+</screen><para>With document style web services the payload of every message
is defined by a complex type in XML schema.</para><screen
xml:space="preserve"> <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'/>
+</screen><para>Therefore, message parts <emphasis
role="bold">must</emphasis> refer to an <emphasis
role="bold">element</emphasis> from the schema.</para><screen
xml:space="preserve"> <message
name='EndpointInterface_concat'>
+ <part name='parameters'
element='tns:concat'/></message>
+</screen><para>The following message definition <emphasis
role="bold">is invalid</emphasis>.</para><screen
xml:space="preserve"> <message
name='EndpointInterface_concat'>
+ <part name='parameters'
type='tns:concatType'/></message></screen><section
id="JBossWS-UserGuide_DocumentLiteral_Bare"><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><screen
xml:space="preserve">@WebService
+@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> DocBareServiceImpl
+{
+ @WebMethod
+ <emphasis role="bold">public</emphasis> SubmitBareResponse
submitPO(SubmitBareRequest poRequest)
+ {
+ ...
+ }
+}
+</screen><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><screen
xml:space="preserve">@XmlAccessorType(XmlAccessType.FIELD)
+@XmlType(name = "SubmitBareRequest", namespace="<ulink
url="http://soapbinding.samples.jaxws.ws.test.jboss.org/">ht...;,
propOrder = { "product" })
+@XmlRootElement(namespace="<ulink
url="http://soapbinding.samples.jaxws.ws.test.jboss.org/">ht...;,
name = "SubmitPO")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> SubmitBareRequest
+{
+ @XmlElement(namespace="<ulink
url="http://soapbinding.samples.jaxws.ws.test.jboss.org/">ht...
required = <emphasis role="bold">true</emphasis>)
+ <emphasis role="bold">private</emphasis> String product;
+
+ ...
+}
+</screen></section>
+<section
id="JBossWS-UserGuide_DocumentLiteral_Wrapped"><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><screen
xml:space="preserve">@WebService
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> DocWrappedServiceImpl
+{
+ @WebMethod
+ @RequestWrapper (className="org.somepackage.SubmitPO")
+ @ResponseWrapper (className="org.somepackage.SubmitPOResponse")
+ <emphasis role="bold">public</emphasis> String submitPO(String
product, <emphasis role="bold">int</emphasis> quantity)
+ {
+ ...
+ }
+}
+</screen><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><para> </para></section>
+</section>
+<section
id="JBossWS-UserGuide_RPCLiteral"><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><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><screen
xml:space="preserve"> <binding name='EndpointInterfaceBinding'
type='tns:EndpointInterface'>
+ <soap:binding style='rpc' transport='<ulink
url="http://schemas.xmlsoap.org/soap/http'/">http://sche...
+ <operation name='echo'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body namespace='<ulink
url="http://org.jboss.ws/samples/jsr181pojo">http://org.jboss.ws/samples/jsr181pojo</ulink>'
use='literal'/>
+ </input>
+ <output>
+ <soap:body namespace='<ulink
url="http://org.jboss.ws/samples/jsr181pojo">http://org.jboss.ws/samples/jsr181pojo</ulink>'
use='literal'/>
+ </output>
+ </operation></binding>
+</screen><para>With rpc style web services the portType names the operation
(i.e. the java method on the endpoint)</para><screen
xml:space="preserve"> <portType
name='EndpointInterface'>
+ <operation name='echo' parameterOrder='String_1'>
+ <input message='tns:EndpointInterface_echo'/>
+ <output message='tns:EndpointInterface_echoResponse'/>
+ </operation></portType>
+</screen><para>Operation parameters are defined by individual message
parts.</para><screen xml:space="preserve"> <message
name='EndpointInterface_echo'>
+ <part name='String_1'
type='xsd:string'/></message><message
name='EndpointInterface_echoResponse'>
+ <part name='result'
type='xsd:string'/></message>
+</screen><para>Note, there is no complex type in XML schema that could
validate the entire SOAP message payload.</para><screen
xml:space="preserve">@WebService
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> JSEBean01
+{
+ @WebMethod
+ @WebResult(name="result")
+ <emphasis role="bold">public</emphasis> String
echo(@WebParam(name="String_1") String input)
+ {
+ ...
+ }
+}
+</screen><para>The element names of RPC parameters/return values may be
defined using the JAX-WS <link
linkend="chap_JBossWS-JAX-WSAnnotations">WebParam</link> and <link
linkend="chap_JBossWS-JAX-WSAnnotations">WebResult</link> annotations
respectively.</para></section>
+<section
id="JBossWS-UserGuide_RPCEncoded"><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</ulink> of the <ulink
url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508">SOAP-1.1&...
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</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</ulink>.</para><para> JBossWS doesn't
support rpc/encoded anymore.</para><para> </para></section>
+</section>
+<section id="JBossWS-UserGuide_Web_Service_Endpoints"><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.</para><para> </para><section
id="JBossWS-UserGuide_Plain_old_Java_Object_POJO"><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><screen xml:space="preserve"> @WebService
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> JSEBean01
+ {
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String echo(String
input)
+ {
+ ...
+ }
+ }
+</screen><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><screen
xml:space="preserve"> <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>
+</screen><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><screen
xml:space="preserve"> <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>
+</screen><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><screen xml:space="preserve">
http://yourhost:8080/jbossws/services
+</screen><para>Note, it is also possible to generate the abstract contract
off line using jbossw tools. For details of that please see <link
linkend="chap_JBossWS-JAX-WSTools">Bottom-Up (Java to
WSDL)</link></para><para> </para></section>
+<section
id="JBossWS-UserGuide_EJB3_Stateless_Session_Bean_SLSB"><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 <link
linkend="JBossWS-UserGuide_Plain_old_Java_Object_POJO">Plain old Java Object
(POJO)</link> endpoints. EJB-2.1 endpoints are supported using the JAX-RPC
progamming model (with JBossWS-Native only).</para><screen
xml:space="preserve"> @Stateless
+ @Remote(EJB3RemoteInterface.class)
+ @RemoteBinding(jndiBinding = "/ejb3/EJB3EndpointInterface")
+
+ @WebService
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> EJB3Bean01 <emphasis
role="bold">implements</emphasis> EJB3RemoteInterface
+ {
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String echo(String
input)
+ {
+ ...
+ }
+ }
+</screen><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><screen
xml:space="preserve"> <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>
+</screen><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><screen xml:space="preserve">
http://yourhost:8080/jbossws/services
+</screen><para>Note, it is also possible to generate the abstract contract
off line using jbossw tools. For details of that please see <link
linkend="chap_JBossWS-JAX-WSTools">Bottom-Up (Java to
WSDL)</link></para><para> </para></section>
+<section id="JBossWS-UserGuide_Endpoint_Provider"><title>Endpoint
Provider</title><para>JAX-WS services typically implement a native Java
service endpoint interface (SEI), perhaps mapped from a 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 Java objects and
their XML representations for use in XML-based messages. However, in some cases it is
desirable for services to be able to operate at the XML message level. The Provider
interface offers an alternative to SEIs and may be implemented by services wishing to work
at the XML message level.</para><para>A Provider based service instances
invoke method is called for each message received for the service.</para><screen
xml:space="preserve"> @WebServiceProvider(wsdlLocation =
"WEB-INF/wsdl/Provider.wsdl")
+ @ServiceMode(value = Service.Mode.PAYLOAD)
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> ProviderBeanPayload <emphasis
role="bold">implements</emphasis> Provider<Source>
+ {
+ <emphasis role="bold">public</emphasis> Source invoke(Source
req)
+ {
+ // Access the entire request PAYLOAD and return the response PAYLOAD
+ }
+ }
+</screen><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><para>The abstract contract for a provider endpoint cannot be
derived/generated automatically. Therefore it is necessary to specify the wsdlLocation
with the @WebServiceProvider
annotation.</para><para> </para></section>
+<section
id="JBossWS-UserGuide_WebServiceContext"><title>WebServiceContext</title><para>The
WebServiceContext is treated as an injectable resource that can be set at the time an
endpoint is initialized. The WebServiceContext object will then use thread-local
information to return the correct information regardless of how many threads are
concurrently being used to serve requests addressed to the same endpoint
object.</para><screen xml:space="preserve"> @WebService
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> EndpointJSE
+ {
+ @Resource
+ WebServiceContext wsCtx;
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String
testGetMessageContext()
+ {
+ SOAPMessageContext jaxwsContext =
(SOAPMessageContext)wsCtx.getMessageContext();
+ <emphasis role="bold">return</emphasis> jaxwsContext !=
<emphasis role="bold">null</emphasis> ? "pass" :
"fail";
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String
testGetUserPrincipal()
+ {
+ Principal principal = wsCtx.getUserPrincipal();
+ <emphasis role="bold">return</emphasis>
principal.getName();
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">boolean</emphasis> testIsUserInRole(String role)
+ {
+ <emphasis role="bold">return</emphasis>
wsCtx.isUserInRole(role);
+ }
+ }
+</screen><para> </para><para> </para><para> </para></section>
+</section>
+<section id="JBossWS-UserGuide_Web_Service_Clients"><title>Web
Service Clients</title><section
id="JBossWS-UserGuide_Service"><title>Service</title><para><computeroutput>Service</computeroutput>
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><para>For most clients, you
will start with a set of stubs generated from the WSDL. One of these will be the service,
and you will create objects of that class in order to work with the service (see
"static case" below).</para><section
id="JBossWS-UserGuide_Service_Usage"><title>Service
Usage</title><para><emphasis role="bold">Static
case</emphasis></para><para>Most clients will start with a WSDL file,
and generate some stubs using jbossws tools like
<emphasis>wsconsume</emphasis>. This usually gives a mass of files, one of
which is the top of the tree. This is!
the service implementation class.</para><para>The generated implementation
class can be recognised as it will have two public constructors, one with no arguments and
one with two arguments, representing the wsdl location (a java.net.URL) and the service
name (a javax.xml.namespace.QName) respectively.</para><para>Usually you will
use the no-argument constructor. In this case the WSDL location and service name are those
found in the WSDL. These are set implicitly from the WebServiceClient annotation that
decorates the generated class.</para><para>The following code snippet shows
the generated constructors from the generated class:</para><screen
xml:space="preserve">// Generated Service Class
+
+@WebServiceClient(name="StockQuoteService", targetNamespace="<ulink
url="http://example.com/stocks">http://example.com/stocks<...;,
wsdlLocation="<ulink
url="http://example.com/stocks.wsdl">http://example.com/stoc...)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> StockQuoteService <emphasis
role="bold">extends</emphasis> javax.xml.ws.Service
+{
+ <emphasis role="bold">public</emphasis> StockQuoteService()
+ {
+ <emphasis role="bold">super</emphasis>(<emphasis
role="bold">new</emphasis> URL("<ulink
url="http://example.com/stocks.wsdl">http://example.com/stoc...),
<emphasis role="bold">new</emphasis> QName("<ulink
url="http://example.com/stocks">http://example.com/stocks<...;,
"StockQuoteService"));
+ }
+
+ <emphasis role="bold">public</emphasis> StockQuoteService(String
wsdlLocation, QName serviceName)
+ {
+ <emphasis role="bold">super</emphasis>(wsdlLocation,
serviceName);
+ }
+
+ ...
+}
+</screen><para>Section <link
linkend="JBossWS-UserGuide_Dynamic_Proxy">Dynamic Proxy</link> 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 <link
linkend="JBossWS-UserGuide_Dispatch">Dispatch</link>.</para><para><emphasis
role="bold">Dynamic case</emphasis></para><para>In the
dynamic case, when nothing is generated, a web service client uses
<computeroutput>Service.create</computeroutput> to create Service instances,
the following code illustrates this process.</para><screen
xml:space="preserve"> URL wsdlLocation = <emphasis
role="bold">new</emphasis> URL("<ulink
url="http://example.org/my.wsdl">http://example.org/my.wsdl&...);
+ QName serviceName = <emphasis role="bold">new</emphasis>
QName("<ulink
url="http://example.org/sample">http://example.org/sample<...;,
"MyService");
+ Service service = Service.create(wsdlLocation, serviceName);
+</screen><para> </para><para> </para></section>
+<section id="JBossWS-UserGuide_Handler_Resolver"><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. <link
linkend="JBossWS-UserGuide_Handler_Framework">Handler Framework</link>
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></section>
+<section
id="JBossWS-UserGuide_Executor"><title>Executor</title><para>Service
instances can be configured with a java.util.concurrent.Executor. The executor will then
be used to invoke any asynchronous callbacks requested by the application. The setExecutor
and getExecutor methods of Service can be used to modify and retrieve the executor
configured for a service.</para></section>
+</section>
+<section id="JBossWS-UserGuide_Dynamic_Proxy"><title>Dynamic
Proxy</title><para>You can create an instance of a client proxy using one of
getPort methods on the <link
linkend="JBossWS-UserGuide_Service">Service</link>.</para><screen
xml:space="preserve"> /**
+ * 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.
+ **/
+ <emphasis role="bold">public</emphasis> <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.
+ *
+ **/
+ <emphasis role="bold">public</emphasis> <T> T
getPort(Class<T> serviceEndpointInterface)
+ {
+ ...
+ }
+</screen><para>The service endpoint interface (SEI) is usually generated
using tools. For details see <link linkend="chap_JBossWS-JAX-WSTools">Top
Down (WSDL to Java)</link></para><para>A generated static <ulink
url="http://community.jboss.org/Service">Service</ulink> usually also
offers typed methods to get ports. These methods also return dynamic proxies that
implement the SEI.</para><screen
xml:space="preserve">@WebServiceClient(name =
"TestEndpointService", targetNamespace = "<ulink
url="http://org.jboss.ws/wsref">http://org.jboss.ws/wsref</ulink>",
+ wsdlLocation = "<ulink
url="http://localhost.localdomain:8080/jaxws-samples-webserviceref?wsdl">http://localhost.localdomain:8080/jaxws-samples-webserviceref?wsdl</ulink>")
+
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> TestEndpointService <emphasis
role="bold">extends</emphasis> Service
+{
+ ...
+
+ <emphasis role="bold">public</emphasis> TestEndpointService(URL
wsdlLocation, QName serviceName) {
+ <emphasis role="bold">super</emphasis>(wsdlLocation,
serviceName);
+ }
+
+ @WebEndpoint(name = "TestEndpointPort")
+ <emphasis role="bold">public</emphasis> TestEndpoint
getTestEndpointPort()
+ {
+ <emphasis role="bold">return</emphasis>
(TestEndpoint)super.getPort(TESTENDPOINTPORT, TestEndpoint.class);
+ }
+}
+</screen><para> </para></section>
+<section
id="JBossWS-UserGuide_WebServiceRef"><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.</para><para>There are two uses to the WebServiceRef
annotation:</para><orderedlist><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 ca!
n 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><screen
xml:space="preserve"><emphasis
role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> EJB3Client <emphasis
role="bold">implements</emphasis> EJB3Remote
+{
+ @WebServiceRef
+ <emphasis role="bold">public</emphasis> TestEndpointService
service4;
+
+ @WebServiceRef
+ <emphasis role="bold">public</emphasis> TestEndpoint port3;
+</screen><para><emphasis role="bold">WebServiceRef
Customization</emphasis></para><para>Starting from jboss-5.0.x we offer
a number of overrides and extensions to the WebServiceRef annotation. These
include</para><itemizedlist><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><screen
xml:space="preserve"> <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-impl-class>org.jboss.tests.ws.jaxws.webserviceref.SecureEndpointService</service-impl-class>
+
<service-qname>{http://org.jboss.ws/wsref}SecureEndpointService</service-qname>
+ <port-component-ref>
+
<service-endpoint-interface>org.jboss.tests.ws.jaxws.webserviceref.SecureEndpoint</service-endpoint-interface>
+
<port-qname>{http://org.jboss.ws/wsref}SecureEndpointPort</port-qname>
+ <stub-property>
+
<prop-name>javax.xml.ws.security.auth.username</prop-name>
+ <prop-value>kermit</prop-value>
+ </stub-property>
+ <stub-property>
+
<prop-name>javax.xml.ws.security.auth.password</prop-name>
+ <prop-value>thefrog</prop-value>
+ </stub-property>
+ </port-component-ref>
+ </service-ref>
+</screen><para>For details please see <emphasis
role="bold">service-ref_5_0.dtd</emphasis> in the jboss docs
directory.</para><para> </para></section>
+<section
id="JBossWS-UserGuide_Dispatch"><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><screen
xml:space="preserve"> Service service = Service.create(wsdlURL,
serviceName);
+ Dispatch dispatch = service.createDispatch(portName, StreamSource.class,
Mode.PAYLOAD);
+
+ String payload = "<ns1:ping xmlns:ns1='<ulink
url="http://oneway.samples.jaxws.ws.test.jboss.org/'/">h...;
+ dispatch.invokeOneWay(<emphasis role="bold">new</emphasis>
StreamSource(<emphasis role="bold">new</emphasis>
StringReader(payload)));
+
+ payload = "<ns1:feedback xmlns:ns1='<ulink
url="http://oneway.samples.jaxws.ws.test.jboss.org/'/">h...;
+ Source retObj = (Source)dispatch.invoke(<emphasis
role="bold">new</emphasis> StreamSource(<emphasis
role="bold">new</emphasis> StringReader(payload)));
+</screen></section>
+<section
id="JBossWS-UserGuide_Asynchronous_Invocations"><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>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><screen
xml:space="preserve"> <emphasis
role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> testInvokeAsync() <emphasis
role="bold">throws</emphasis> Exception
+ {
+ URL wsdlURL = <emphasis role="bold">new</emphasis>
URL("<ulink url="http://">http://</ulink>" +
getServerHost() + ":8080/jaxws-samples-asynchronous?wsdl");
+ QName serviceName = <emphasis role="bold">new</emphasis>
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);
+ }
+</screen></section>
+<section id="JBossWS-UserGuide_Oneway_Invocations"><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><screen xml:space="preserve">@WebService
(name="PingEndpoint")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> PingEndpointImpl
+{
+ <emphasis role="bold">private</emphasis> <emphasis
role="bold">static</emphasis> String feedback;
+
+ @WebMethod
+ @Oneway
+ <emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> ping()
+ {
+ log.info("ping");
+ feedback = "ok";
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String feedback()
+ {
+ log.info("feedback");
+ <emphasis role="bold">return</emphasis> feedback;
+ }
+}
+</screen></section>
+<section
id="JBossWS-UserGuide_Oneway_Invocations_703501"><title>Timeout
Configuration</title><para>There are two properties to configure the http
connection timeout and client receive time out:</para><screen
xml:space="preserve"> public void testConfigureTimeout() throws Exception
{ //Set timeout until a connection is established ((BindingProvider)
port).getRequestContext(). put("javax.xml.ws.client.connectionTimeout",
"6000"); //Set timeout until the response is received
((BindingProvider) port).getRequestContext().
put("javax.xml.ws.client.receiveTimeout", "1000");
port.echo("testTimeout"); }
+</screen></section>
+</section>
+<section id="JBossWS-UserGuide_Common_API"><title>Common
API</title><para>This sections describes concepts that apply equally to
<link linkend="JBossWS-UserGuide_Web_Service_Endpoints">Web Service
Endpoints</link> and <link
linkend="JBossWS-UserGuide_Web_Service_Clients">Web Service
Clients</link>.</para><section
id="JBossWS-UserGuide_Handler_Framework"><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 a!
ny 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><section
id="JBossWS-UserGuide_Logical_Handler"><title>Logical
Handler</title><para>Handlers that only operate on message context properties
and message payloads. Logical handlers are protocol agnostic and are unable to affect
protocol specific parts of a message. Logical handlers are handlers that implement
javax.xml.ws.handler.LogicalHandler.</para></section>
+<section id="JBossWS-UserGuide_Protocol_Handler"><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
id="JBossWS-UserGuide_Service_endpoint_handlers"><title>Service
endpoint handlers</title><para>On the service endpoint, handlers are defined
using the @HandlerChain annotation.</para><screen
xml:space="preserve">@WebService
+@HandlerChain(file = "jaxws-server-source-handlers.xml")
+<emphasis role="bold">public</emphasis> <emphasis
role="bold">class</emphasis> SOAPEndpointSourceImpl
+{
+ ...
+}
+</screen><para>The location of the handler chain file supports 2
formats</para><para>1. An absolute java.net.URL in externalForm. (ex:
<ulink
url="http://myhandlers.foo.com/handlerfile1.xml">http://myha....
A relative path from the source file or class file. (ex:
bar/handlerfile1.xml)</para></section>
+<section
id="JBossWS-UserGuide_Service_client_handlers"><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><screen
xml:space="preserve"> Service service = Service.create(wsdlURL,
serviceName);
+ Endpoint port = (Endpoint)service.getPort(Endpoint.class);
+
+ BindingProvider bindingProvider = (BindingProvider)port;
+ List<Handler> handlerChain = <emphasis
role="bold">new</emphasis> ArrayList<Handler>();
+ handlerChain.add(<emphasis role="bold">new</emphasis>
LogHandler());
+ handlerChain.add(<emphasis role="bold">new</emphasis>
AuthorizationHandler());
+ handlerChain.add(<emphasis role="bold">new</emphasis>
RoutingHandler());
+ bindingProvider.getBinding().setHandlerChain(handlerChain); // important!
+</screen></section>
+</section>
+<section id="JBossWS-UserGuide_Message_Context"><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 i!
mplementations. The defaultscope for a property is HANDLER.</para><section
id="JBossWS-UserGuide_Logical_Message_Context"><title>Logical Message
Context</title><para><link
linkend="JBossWS-UserGuide_Logical_Handler">Logical Handlers</link> 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 id="JBossWS-UserGuide_SOAP_Message_Context"><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 id="JBossWS-UserGuide_Fault_Handling"><title>Fault
Handling</title><para>An implementation may thow a
SOAPFaultException</para><screen xml:space="preserve">
<emphasis role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> throwSoapFaultException()
+ {
+ SOAPFactory factory = SOAPFactory.newInstance();
+ SOAPFault fault = factory.createFault("this is a fault string!",
<emphasis role="bold">new</emphasis> QName("<ulink
url="http://foo">http://foo</ulink>", "FooCode"));
+ fault.setFaultActor("mr.actor");
+ fault.addDetail().addChildElement("test");
+ <emphasis role="bold">throw</emphasis> <emphasis
role="bold">new</emphasis> SOAPFaultException(fault);
+ }
+</screen><para>or an application specific user
exception</para><screen xml:space="preserve"> <emphasis
role="bold">public</emphasis> <emphasis
role="bold">void</emphasis> throwApplicationException() <emphasis
role="bold">throws</emphasis> UserException
+ {
+ <emphasis role="bold">throw</emphasis> <emphasis
role="bold">new</emphasis> UserException("validation", 123,
"Some validation error");
+ }
+</screen><note><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><para> </para></para></note>
+</section>
+<section id="JBossWS-UserGuide_JBossWS_Extensions"><title>JBossWS
Extensions</title><para>This section describes propriatary JBoss extensions to
JAX-WS, that works with all the supported
stacks.</para><para> </para><section
id="JBossWS-UserGuide_Proprietary_Annotations"><title>Proprietary
Annotations</title><para>For the set of standard annotations, please have a
look at <link
linkend="chap_JBossWS-JAX-WSAnnotations">JAX-WS_Annotations</link>.</para><para> </para><section
id="JBossWS-UserGuide_WebContext"><title>WebContext</title><screen
xml:space="preserve">/**
+ * Provides web context specific meta data to EJB based web service endpoints.
+ *
+ * @author <ulink
url="mailto:thomas.diesler@jboss.org">thomas.diesler@jboss.org</ulink>
+ * @since 26-Apr-2005
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = { ElementType.TYPE })
+<emphasis role="bold">public</emphasis> @<emphasis
role="bold">interface</emphasis> 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() <emphasis role="bold">default</emphasis>
"";
+
+ /**
+ * The virtual hosts that the web service endpoint is deployed to.
+ *
+ * Applies to server side port components only.
+ */
+ String[] virtualHosts() <emphasis role="bold">default</emphasis>
{};
+
+ /**
+ * 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() <emphasis role="bold">default</emphasis>
"";
+
+ /**
+ * 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() <emphasis role="bold">default</emphasis>
"";
+
+ /**
+ * 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() <emphasis
role="bold">default</emphasis> "";
+
+ /**
+ * A secure endpoint does not secure wsdl access by default.
+ * Explicitly setting secureWSDLAccess overrides this behaviour.
+ *
+ * Protect access to WSDL. See <ulink
url="http://jira.jboss.org/jira/browse/JBWS-723">http://jira...
+ */
+ <emphasis role="bold">boolean</emphasis> secureWSDLAccess()
<emphasis role="bold">default</emphasis> <emphasis
role="bold">false</emphasis>;
+}
+</screen></section>
+<section
id="JBossWS-UserGuide_SecurityDomain"><title>SecurityDomain</title><screen
xml:space="preserve">/**
+ * Annotation for specifying the JBoss security domain for an EJB
+ *
+ * @author <a href="mailto:<ulink
url="mailto:bill@jboss.org">bill@jboss.org</ulink>">Bill
Burke</a>
+ **/
+(a)Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
+<emphasis role="bold">public</emphasis> @<emphasis
role="bold">interface</emphasis> 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() <emphasis
role="bold">default</emphasis> "";
+</screen></section></section>
+</section>
+<section id="JBossWS-UserGuide_JAXB_Introductions"><title>JAXB
Introductions</title><para>As Kohsuke Kawaguchi writes on <ulink
url="http://weblogs.java.net/blog/kohsuke/archive/2007/07/binding_3r...
blog</ulink>, one common complaint from the JAXB users is the lack of support for
binding 3rd party classes. The scenario is this you are trying to annotate your classes
with JAXB annotations to make it XML bindable, but some of the classes are coming from
libraries and JDK, and thus you cannot put necessary JAXB annotations on
it.</para><para>To solve this JAXB has been designed to provide hooks for
programmatic introduction of annotations to the runtime.</para><para>This is
currently leveraged by the JBoss JAXB Introductions project, using which users can define
annotations in XML and make JAXB see those as if those were in the class files (perhaps
coming from 3rd party libraries).</para><para> </para><para>JAXB
Introductions are currently supported in JBossWS-N!
ative (server side only, since 3.0.2.GA) and JBossWS-CXF (both server and client side,
since 3.2.1.GA).</para><para>Take a look at the <ulink
url="http://community.jboss.org/docs/DOC-10075">JAXB Introductions
page</ulink> on the wiki and at the examples in the
sources.</para><para> </para></section>
+</section>
+<section
id="JBossWS-UserGuide_Tools"><title>Tools</title><para>The
JBossWS Web Service Framework provides unified tooling for all the supported stacks. This
currently includes common JAX-WS tools for both contract-first and code-first development
and common management tools.</para><section
id="JBossWS-UserGuide_JAXWS_tools"><title>JAX-WS
tools</title><para>Please refer to <link
linkend="chap_JBossWS-JAX-WSTools">JBossWS_JAX-WS_Tools</link> for
details. This covers directions on web service contract generation (bottom-up development)
and consumption (top-down and client development).</para></section>
+<section id="JBossWS-UserGuide_Management_tools"><title>Management
tools</title><para>JBoss and its web service framework come with some tools
allowing WS endpoint management.</para><para>Please refer the <link
linkend="chap_JBossWS-Endpointmanagement">Endpoint management</link>
page for an overview of the available tools. In particular the <link
linkend="chap_JBossWS-Recordsmanagement">JBossWS - Records
management</link> gives administrators a means of performing custom analysis of
their web service traffic as well as exporting communication
logs.</para></section>
+<section id="JBossWS-UserGuide_Web_Service_console"><title>Web
Service console</title><para>All supported stacks provide a web console for
getting the list of the endpoints currently deployed on a given host as well as basic
metrics regarding invocations to them. The console is available at <ulink
url="http://localhost:8080/jbossws/services">http://localhost:8080/jbossws/services</ulink>
assuming your application server is currently bound to
localhost:8080.</para><para> </para></section>
+</section>
+<section
id="JBossWS-UserGuide_Configuration"><title>Configuration</title><section
id="JBossWS-UserGuide_Address_rewrite"><title>Address
rewrite</title><para>JBossWS allows users to configure the soap:address
attribute in the wsdl contract of deployed services as well as wsdl address in the web
service console. [due to a known issue this does not currently work with JBossWS-Metro,
see: <ulink
url="https://jira.jboss.org/jira/browse/JBWS-2462">JBWS-2462...
role="bold">Server configuration
options</emphasis></para><para> </para><para>There're
few attributes in the jbossws deployers configuration (currently in
jbossws.deployer/META-INF/stack-agnostic-jboss-beans.xml) controlling the way the
soap:address attribute in the wsdl is rewritten.</para><screen
xml:space="preserve"><bean name="WSServerConfig"
class="org.jboss.webservices.integration.config.ServerConfigImpl">
+ <property name="mbeanServer"><inject
bean="WSMBeanServerLocator"
property="mbeanServer"/></property>
+
+ <property
name="webServiceHost">${jboss.bind.address}</property>
+ <property
name="modifySOAPAddress">true</property>
+
+ <!--
+ <property
name="webServiceSecurePort">8443</property>
+ <property
name="webServicePort">8080</property>
+ -->
+ </bean>
+</screen><para> </para><para>If the content of
<emphasis><soap:address></emphasis> in the wsdl is a valid URL,
JBossWS will not rewrite it unless <emphasis>modifySOAPAddress</emphasis> is
true. If the content of <emphasis><soap:address></emphasis> is
not a valid URL instead, JBossWS will always rewrite it using the attribute values given
below. Please note that the variable
<emphasis>${jboss.bind.address}</emphasis> can be used to set the address
which the application is bound to at each
startup.</para><para> </para><para>The webServiceSecurePort and
webServicePort attributes are used to explicitly define the ports to be used for rewriting
the SOAP address. If these attributes are not set, the ports will be identified by
querying the list of installed connectors. If multiple connectors are found the port of
the first connector is
used.</para><para> </para><para><emphasis
role="bold">Dynamic
rewrite</emphasis></para><para> </para><para>When the
application se!
rver is bound to multiple addresses or non-trivial real-world network architectures cause
request for different external addresses to hit the same endpoint, a static rewrite of the
soap:address may not be enough. JBossWS allows for both the soap:address in the wsdl and
the wsdl address in the console to be rewritten with the host use in the client request.
This way, users always get the right wsdl address assuming they're connecting to an
instance having the endpoint they're looking for. To trigger this behaviour, the
<emphasis role="bold">jbossws.undefined.host</emphasis> value has to
be specified for the <emphasis>webServiceHost</emphasis>
attribute.</para><screen xml:space="preserve"><property
name="webServiceHost">jbossws.undefined.host</property>
+<property
name="modifySOAPAddress">true</property></screen><para> </para><para>Of
course, when a confidential transport address is required, the addresses are always
rewritten using https protocol and the port currently configured for the https/ssl
connector.</para></section>
+</section></section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-WS-Securityoptions.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-WS-Securityoptions.xml
(rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-WS-Securityoptions.xml 2010-11-02 19:25:45 UTC
(rev 13202)
@@ -0,0 +1,200 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-WS-Securityoptions"><title>JBossWS-WS-Securityoptions</title><para>JBossWS
implements WS-Security 1.0 specifications to provide users with message level security.
The user guide explains <ulink
url="http://community.jboss.org/docs/DOC-13532#JBossWS_Native_WS_ext...
to configure WS-Security</ulink> through declaration files and annotations; for
this aim, a simple example shows how to sign (and require signature of)
messages.</para><para>This page instead goes deeper into the JBossWS
WS-Security configuration details, covering more advanced
topics.</para><para/><para> </para><section
id="JBossWS-WS-Securityoptions_Username_Token_Authentication"><title>Username
Token Authentication</title><para>The following configuration allows clients
to authenticate through a Username Token (1). Thanks to the <ulink
url="http://jbossws.jboss.org/mediawiki/index.php?title=WS-Security_...
int!
egration</ulink>, the received token will automatically be verified against the
configured JBoss JAAS Security Domain.</para><screen
xml:space="preserve"> <jboss-ws-security xmlns="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ <ulink
url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.x...
+ <config>
+(1) <username/>
+(2) <timestamp ttl="300"/>
+ </config>
+ </jboss-ws-security>
+</screen><para>Line (2) states that a timestamp element must be present in
the message and that the message can not be older than 300 seconds; this is used to
prevent replay attacks.</para><para>On the server side you should
have:</para><screen xml:space="preserve"> <jboss-ws-security
xmlns="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ <ulink
url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.x...
+ <config>
+ <timestamp ttl="300"/>
+ <requires>
+ <username/>
+ </requires>
+ </config>
+ </jboss-ws-security>
+</screen><para>Please note that this way username and password appear as
simple text in the SOAP header. Thus it is strongly suggested to use a <link
linkend="chap_JBossWS-Securetransport">JBossWS - Secure
transport</link>.</para><para> </para><section
id="JBossWS-WS-Securityoptions_Password_digest_nonces_and_timestamp"><title>Password
digest, nonces and timestamp</title><para>The afore mentioned configuration
causes the password to be sent on the wire as a plain text. The Username Token Profile
specification allows a digested passwords to be used, even if this doesn't offer real
additional security.</para><para>Moreover nonces and creation timestamp can be
used as salt to the password digest; this provides some countermeasures to prevent replay
attacks.</para><para>To enable password digesting, you basically need to
follow these steps:</para><itemizedlist><listitem><para> use the
<emphasis>digestPassword</emphasis> attribute in the client wsse configuration
(3) </para></l!
istitem><listitem><para> perhaps enable/disable use of nonces
(<emphasis>useNonce</emphasis> attribute, default true) and creation timestamp
(<emphasis>useCreated</emphasis> attribute, default true)
</para></listitem><listitem><para> properly setup the login module
of your security domain to use UsernameTokenCallback (4).
</para></listitem></itemizedlist><para>Here is an example of the
modified client config:</para><screen
xml:space="preserve"><jboss-ws-security xmlns="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ <ulink
url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.x...
+ <config>
+(3) <username digestPassword="true" useNonce="true"
useCreated="true"/>
+ <timestamp ttl="300"/>
+ </config>
+</jboss-ws-security>
+</screen><para>And here is a sample login-config.xml showing how to use the
UsernameTokenCallback (4):</para><screen
xml:space="preserve"><application-policy
name="JBossWSDigest">
+ <authentication>
+ <login-module
code="org.jboss.security.auth.spi.UsersRolesLoginModule"
flag="required">
+ <module-option
name="usersProperties">META-INF/jbossws-users.properties</module-option>
+ <module-option
name="rolesProperties">META-INF/jbossws-roles.properties</module-option>
+ <module-option
name="hashAlgorithm">SHA</module-option>
+ <module-option
name="hashEncoding">BASE64</module-option>
+ <module-option
name="hashUserPassword">false</module-option>
+ <module-option
name="hashStorePassword">true</module-option>
+ <module-option
name="storeDigestCallback">org.jboss.ws.extensions.security.auth.callback.UsernameTokenCallback</module-option>
+ <module-option
name="unauthenticatedIdentity">anonymous</module-option>
+ </login-module>
+ </authentication>
+</application-policy>
+</screen><para>Of course you could want to use different login module; the
provided <emphasis>UsernameTokenCallback</emphasis> simply adds the nonce and
creation timestamp to the digest.</para><para>You can use your custom login
module as long as you extend the
<emphasis>org.jboss.security.auth.spi.UsernamePasswordLoginModule</emphasis>:
then you just need to plug the UsernameTokenCallback into your module and set the hash
attributes (<emphasis>hashAlgorithm</emphasis>,
<emphasis>hashEncoding</emphasis>,
<emphasis>hashUserPassword</emphasis>,
<emphasis>hashStorePassword</emphasis>) the way shown
above.</para><para> </para></section>
+<section
id="JBossWS-WS-Securityoptions_Advanced_tuning_nonce_factory"><title>Advanced
tuning: nonce factory</title><para>The way nonces are created and
checked/stored on server side influences the overall security against replay attacks. In
particular currently JBossWS ships with a basic implementation of a nonce store that
doesn't cache the received tokens on server side. More complex implementation can be
easily plugged in implementing the <emphasis>NonceFactory</emphasis> and
<emphasis>NonceStore</emphasis> interfaces you can find in the
<emphasis>org.jboss.ws.extensions.security.nonce</emphasis> package. Then you
just need to specify you factory class through the
<emphasis>nonce-factory-class</emphasis> element in the wsse server config.
Future version of JBossWS might come with a nonce store implementation leveraging JBoss
Cache or Hibernate to store received
nonces.</para><para> </para></section>
+<section
id="JBossWS-WS-Securityoptions_Advanced_tuning_timestamp_verification"><title>Advanced
tuning: timestamp verification</title><para>By default if a Timestamp is
present in the wsse:Security header the verification of the header is very strict and does
not allow for any tolerance in the time comparisons - if the message appears to have been
created even slightly in the future or if the message has just expired then it will be
rejected. A new element called 'timestamp-verification' is now available for the
wsse configuration. Here is an example of the modified wsse
configuration:</para><screen
xml:space="preserve"><jboss-ws-security xmlns='<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ xmlns:xsi='<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation='<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ <ulink
url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.x...
+ <timestamp-verification createdTolerance="5"
warnCreated="false" expiresTolerance="10"
warnExpires="false" />
+</jboss-ws-security>
+</screen><para>The attributes allow you to specify the tolerance in seconds
that is used when verifying the 'Created' or 'Expires' element of the
'Timestamp' header.</para><itemizedlist><listitem><para>
<emphasis role="bold">createdTolerance</emphasis> - The number of
seconds in the future a message will be accepted.
</para></listitem><listitem><para> <emphasis
role="bold">expiresTolerance</emphasis> - The number of seconds a
message must have been expired for before it will be rejected.
</para></listitem></itemizedlist><para>The default value for both
of these is 0 which was the orignal behaviour.</para><para>It is also possible
to log a warning if a message is accepted due to the configured tolerances that would
normally have been rejected, this can then enable you to track down clients where their
time is out of synch with the server without rejecting their
messages.</para><itemizedlist><listitem><para> <emphasis
role="bold">warnCreated</emphasis> - log a warning if a me!
ssage is accepted with a 'Created' value in the future.
</para></listitem><listitem><para> <emphasis
role="bold">warnExpires</emphasis> - log a warning if a message is
accepted with an 'Expires' value in the past.
</para></listitem></itemizedlist><para>The default for both of
these is true so if you do not require logging you will need to disable
these.</para><para><emphasis>Please be aware that the purpose of this
tolerance is not to overcome differences relating to different timezones, according to the
WSSE specification these times should be UTC - the time and date comparisons used by
JBossWS are timezone
aware.</emphasis></para><para> </para></section>
+</section>
+<section
id="JBossWS-WS-Securityoptions_X509_Certificate_Token"><title>X509
Certificate Token</title><section
id="JBossWS-WS-Securityoptions_Encryption"><title>Encryption</title><para>Using
X509v3 certificates you can both sign and encrypt messages.</para><screen
xml:space="preserve"><jboss-ws-security xmlns="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ <ulink
url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.x...
+(1)
<key-store-file>WEB-INF/bob-sign_enc.jks</key-store-file>
+ <key-store-password>password</key-store-password>
+ <key-store-type>jks</key-store-type>
+
<trust-store-file>WEB-INF/wsse10.truststore</trust-store-file>
+ <trust-store-password>password</trust-store-password>
+
+ <config>
+ <timestamp ttl="300"/>
+(2) <sign type="x509v3" alias="1"
includeTimestamp="true"/>
+(3) <encrypt type="x509v3"
+ alias="alice"
+ algorithm="aes-256"
+ keyWrapAlgorithm="rsa_oaep"
+ tokenReference="keyIdentifier" />
+(4) <requires>
+ <signature/>
+ <encryption/>
+ </requires>
+ </config>
+</jboss-ws-security>
+</screen><para>The server configuration shown above
includes:</para><orderedlist><listitem><para> Keystore and
truststore information: location, password and type.
</para></listitem><listitem><para> Signature configuration: you
need to provide the certificate/key pair alias to use.
<emphasis>includeTimestamp</emphasis> specifies whether the timestamp is to
be signed too to prevent tampering.
</para></listitem><listitem><para> Encryption configuration: you
need to provide the certificate/key pair alias to use.
</para></listitem><listitem><para> Optional security requirements:
incoming messages should be both signed and encrypted.
</para></listitem></orderedlist><para>Client side configuration
works the same way.</para><para> </para><section
id="JBossWS-WS-Securityoptions_Algorithms"><title>Algorithms</title><para>Asymmetric
+ symmetric encryption is performed whenever the <emphasis>encrypt</emphasis>
element is found. Thus message data are encrypted using a generated symm!
etric secret key. This is written in the SOAP header after being encrypted (wrapped) with
the receiver public key. You can set both the encryption and key wrap
algorithms.</para><variablelist><varlistentry><term>Supported
encryption algorithms
</term><listitem/></varlistentry></variablelist><para> </para><itemizedlist><listitem><para>
AES 128 (aes-128) (<emphasis>default</emphasis>)
</para></listitem><listitem><para> AES 192 (aes-192)
</para></listitem><listitem><para> AES 256 (aes-256)
</para></listitem><listitem><para> Triple DES (triple-des)
</para></listitem></itemizedlist><variablelist><varlistentry><term>Supported
key wrap algorithms
</term><listitem/></varlistentry></variablelist><para> </para><itemizedlist><listitem><para>
RSA v.1.5 (rsa_15) (<emphasis>default</emphasis>)
</para></listitem><listitem><para> RSA OAEP (rsa_oaep)
</para></listitem></itemizedlist><para>The <ulink
url="http://java.sun.com/javase/downloads/index_jdk5.jsp">Un... Strength
Java(TM) Cryp!
tography Extension</ulink> installation might be required to r!
un some
strong algorithms (like AES-256). Please note that your country might have limits on
allowed crypto strength.</para><para> </para></section>
+<section
id="JBossWS-WS-Securityoptions_Dynamic_encryption"><title>Dynamic
encryption</title><para>When replying to multiple clients, a service provider
has to encrypt a message using the right public key according to its destination. The
JBossWS native implementation of WS-Security gets the right key to use from the signature
received (and verified) in the incoming message. You just need to require signature (1)
and do not specify any encryption alias on server side (2):</para><screen
xml:space="preserve"><jboss-ws-security xmlns="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ <ulink
url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.x...
+
<key-store-file>WEB-INF/bob-sign_enc.jks</key-store-file>
+ <key-store-password>password</key-store-password>
+ <key-store-type>jks</key-store-type>
+
<trust-store-file>WEB-INF/wsse10.truststore</trust-store-file>
+ <trust-store-password>password</trust-store-password>
+
+ <config>
+ <timestamp ttl="300"/>
+ <sign type="x509v3" alias="1"
includeTimestamp="true"/>
+(2) <encrypt type="x509v3"
+ algorithm="aes-256"
+ keyWrapAlgorithm="rsa_oaep"
+ tokenReference="keyIdentifier" />
+ <requires>
+(1) <signature/>
+ <encryption/>
+ </requires>
+ </config>
+</jboss-ws-security>
+</screen><para>Of course you'll have to add every new client's public
key to the server side keystore, but no change to the descriptors and service
implementation is required.</para><para> </para></section>
+<section
id="JBossWS-WS-Securityoptions_Token_references"><title>Token
references</title><para>For interoperability reason you might want to
configure the type of reference to encryption token to be used. For instance, Microsoft
Indigo doesn't support direct reference to local binary security tokens that is the
JBossWS default reference type choice. Allowed values for
<emphasis>tokenReference</emphasis> attribute
are:</para><itemizedlist><listitem><para> directReference
(<emphasis>default</emphasis>)
</para></listitem><listitem><para> keyIdentifier
</para></listitem><listitem><para> x509IssuerSerial
</para></listitem></itemizedlist><para>Please refer to the
<ulink
url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-to...
Token Profile 1.0</ulink> specification for further details on token
references.</para><para> </para></section>
+</section>
+<section
id="JBossWS-WS-Securityoptions_Targets_configuration"><title>Targets
configuration</title><para>JBossWS gives you a fine grained control over the
elements that have to be signed or encrypted.</para><para>This allows you to
encrypt important data only (like credit card numbers) without waisting time on other
information exchanged by the same service (email addresses, for example). To configure
this, you just need to specify the QName of the SOAP elements to encrypt. The default
behavior is to encrypt the whole SOAP body.</para><screen
xml:space="preserve"><encrypt type="x509v3"
alias="alice">
+ <targets>
+ <target
type="qname">{http://www.my-company.com/cc}CardNumber&am...
+ <target
type="qname">{http://www.my-company.com/cc}CardExpiratio...
+ <target type="qname"
contentOnly="true">{http://www.my-company.com/cc}Custome...
+ </targets>
+</encrypt>
+</screen><para>The <emphasis>contentOnly</emphasis> attribute
states whether the content of the element is to be encrypted as opposed to the entire
element (default behavior). Target can be specified also for requirements upon message
receipt.</para><para> </para></section>
+<section
id="JBossWS-WS-Securityoptions_Miscellanea"><title>Miscellanea</title><section
id="JBossWS-WS-Securityoptions_Signature_and_carriage_returns"><title>Signature
and carriage returns</title><para>Exchanging signed messages whose payload
contains carriage returns can lead to signature verification errors. That's because of
the way the <emphasis>\r</emphasis> special character is handled by xml
parsers. To prevent this kind of issue, besides custom encoding the payload before sending
it, users can either also encrypt the message or force JBossWS to perform canonical
normalization of messages. This can be triggered setting the
<emphasis>org.jboss.ws.DOMContentCanonicalNormalization</emphasis> property to
true in the MessageContext just before the invocation on client side and in the endpoint
implementation. Please note there's a convenient constant for this in
<emphasis>org.jboss.ws.Constants</emphasis>; also see the
<emphasis>org.jboss.test.ws.jaxws.jbws2011.CRLFTestCas!
e</emphasis> for an
example.</para><para> </para></section>
+</section>
+</section>
+<section
id="JBossWS-WS-Securityoptions_JAAS_integration"><title>JAAS
integration</title><para>The WS-Security implementation allows users to
achieve J2EE declarative security through JAAS integration. The calling user's
identity and credential are derived from the wsse headers of the incoming message
according to the parameters provided in the server wsse configuration file. Authentication
and authorization are then achieved delegating to the JAAS login modules configured for
the specified security domain.</para><para> </para><section
id="JBossWS-WS-Securityoptions_Username_token"><title>Username
token</title><para>Username Token Profile provides a mean of specifying the
caller's username and password. The wsse server configuration file can be used to have
those information used when performing authentication and authorization through configured
login module.</para><screen
xml:space="preserve"><jboss-ws-security xmlns="<ulink
url="http://www.jboss.com/ws-security/confi!
g">http://www.jboss.com/ws-security/config</ulink>"
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ <ulink
url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.x...
+ <config>
+ <username/>
+ <authenticate>
+ <usernameAuth/>
+ </authenticate>
+ </config>
+</jboss-ws-security>
+</screen><para>Prior to JBossWs 3.0.2 Native the username token was always
used to set principal and credential of the caller whenever specified. This means that for
backward compatibility reasons, this behavior is obtained also when no
<emphasis>authenticate</emphasis> tag at all is specified and the username
token is used.</para><para> </para></section>
+<section
id="JBossWS-WS-Securityoptions_X509_certificate_token"><title>X.509
certificate token</title><para>Whenever a WS-Security message containing X.509
certificates is received, every certificate is validated against the truststore specified
in the wsse configuration file. After this validation process, one of the X.509
certificate token can be chosen to extract the caller's principal and perform
authentication and authorization using it as credential.</para><para>The
current implementation allows the certificate token referenced by the signature token to
be used for this purpose (1):</para><screen
xml:space="preserve"><jboss-ws-security xmlns="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ xmlns:xsi="<ulink
url="http://www.w3.org/2001/XMLSchema-instance">http://www.w...
+ xsi:schemaLocation="<ulink
url="http://www.jboss.com/ws-security/config">http://www.jbo...
+ <ulink
url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.x...
+ <key-store-file>META-INF/bob-sign.jks</key-store-file>
+ <key-store-password>password</key-store-password>
+ <key-store-type>jks</key-store-type>
+
<trust-store-file>META-INF/wsse10.truststore</trust-store-file>
+ <trust-store-password>password</trust-store-password>
+ <config>
+ <sign type="x509v3" alias="1"
includeTimestamp="false"/>
+ <requires>
+ <signature/>
+ </requires>
+ <authenticate>
+(1) <signatureCertAuth
certificatePrincipal="org.jboss.security.auth.certs.SubjectCNMapping"/>
+ </authenticate>
+ </config>
+</jboss-ws-security>
+</screen><para>The optional
<emphasis>certificatePrincipal</emphasis> attributes specifies the class to be
used to get the principal from the X509 certificate's attributes; it has to implement
<ulink
url="http://wiki.jboss.org/wiki/CertificatePrincipal">Certif...
and the default one used when no attribute is specified is
<emphasis>org.jboss.security.auth.certs.SubjectDNMapping</emphasis>.</para><para>The
configured security domain needs at least a <ulink
url="http://wiki.jboss.org/wiki/BaseCertLoginModule">BaseCer...
to be set up. Here is an example of a security domain with a CertRolesLoginModule, which
also enables authorization (using the specified jbossws-roles.properties
file):</para><screen xml:space="preserve"><application-policy
name="JBossWSCert">
+ <authentication>
+ <login-module
code="org.jboss.security.auth.spi.CertRolesLoginModule"
flag="required">
+ <module-option
name="rolesProperties">jbossws-roles.properties</module-option>
+ <module-option
name="unauthenticatedIdentity">anonymous</module-option>
+ <module-option
name="securityDomain">java:/jaas/JBossWSCert</module-option>
+ </login-module>
+ </authentication>
+</application-policy>
+</screen><para>Finally, the BaseCertLoginModule of course uses a central
keystore to perform user validation. This store is configured through the
<emphasis>org.jboss.security.plugins.JaasSecurityDomain</emphasis> MBean as
shown in the following jboss-service.xml configuration fragment:</para><screen
xml:space="preserve"><mbean
code="org.jboss.security.plugins.JaasSecurityDomain"
+ name="jboss.security:service=SecurityDomain">
+ <constructor>
+ <arg type="java.lang.String" value="JBossWSCert"/>
+ </constructor>
+ <attribute
name="KeyStoreURL">resource:META-INF/keystore.jks</attribute>
+ <attribute
name="KeyStorePass">password</attribute>
+
<depends>jboss.security:service=JaasSecurityManager</depends>
+</mbean>
+</screen><para>The JBoss security code will access the keystore with the
principal that JBossWS got from the wsse header using the specified CertificatePrincipal
mapping class. If a certificate is found and is the same of the one specified in the wsse
header, the user is logged in.</para><para>For a working sample of X509
certificate authentication you may want to take a look at the
<emphasis>org.jboss.test.ws.jaxws.jbws2116.CertAuthTestCase</emphasis>.</para><para> </para></section>
+</section>
+<section
id="JBossWS-WS-Securityoptions_POJO_Endpoint__Authentication_and_Authorization"><title>POJO
Endpoint - Authentication and Authorization</title><para>In general the
credentials obtained by WS-Security are only used for EJB endpoints or for POJO endpoints
when they make a call to another secured resource, it is now possible to enable
authentication and authorization checking for POJO endpoints. (This should not be enabled
for EJB based endpoints as the EJB container will still take care of the security
requirements of the deployed bean).</para><para><emphasis>These
instructions assume WS-Security has already been enabled, these instructions describe the
additional configuration required to enable authentication and authorization for POJO
endpoints</emphasis></para><para>The first stage is that the war
containing the POJO endpoint needs to have a security domain defined, this is achieved by
defining a <security-domain> in the jboss-web deployment descriptor with!
in the WEB-INF folder.</para><screen
xml:space="preserve"><jboss-web>
+ <security-domain>java:/jaas/JBossWS</security-domain>
+</jboss-web>
+</screen><para>The remainder of the configuration to enable authentication
and authorization is within the jboss-wsse-server.xml deployment
descriptor.</para><para>To enable the POJO authentication and authorization
first a new <authorization> element needs to be added to the appropriate
<config> element within the descriptor: -</para><screen
xml:space="preserve"><jboss-ws-security>
+
+ <config>
+ <authorize>
+ <!-- Must contain either <unchecked/> or one or more
<role>RoleName</role> definitions. -->
+ </authorize>
+ </config>
+
+</jboss-ws-security>
+</screen><para>The config element can be defined globally, be port specific
or even be operation specific.</para><para>The authorize element must contain
either the <unchecked/> element or one or more
<role>RoleName</role> elements.</para><screen
xml:space="preserve"><jboss-ws-security>
+
+ <config>
+ <authorize>
+ <unchecked/>
+ </authorize>
+ </config>
+
+</jboss-ws-security>
+</screen><para>This first example had <unchecked/> defined,
this means that the authentication step will be performed to validate the users username
and credential but no further role checking will take place. If the users username and
credential are invalid then the request will be rejected otherwise the request will be
allowed to proceed.</para><screen
xml:space="preserve"><jboss-ws-security>
+
+ <config>
+ <authorize>
+ <role>friend</role>
+ <role>family</role>
+ </authorize>
+ </config>
+
+</jboss-ws-security>
+</screen><para>This second example has two roles defined, as before the user
will be authenticated using their username and credential and they will then be checked to
ensure that they have been assigned at least one of the roles 'friend' or
'family'.</para><para><emphasis>It should be noted that the
authentication and authorization still proceeds even if no username and password or
certificate was provided in the request message, in this scenario authentication may
proceed if the login module of the security domain has been configured with an anonymous
identity.</emphasis></para><para> </para></section>
+<section
id="JBossWS-WS-Securityoptions_Further_information"><title>Further
information</title><itemizedlist><listitem><para> The complete
wsse configuration is specified in the
<emphasis>src/main/resources/schema/jboss-ws-security_1_0.xsd</emphasis>
schema that is available in the source code base.
</para></listitem><listitem><para> The advanced examples described
above are covered by the interoperability scenarios available in the
<emphasis>org.jboss.test.ws.interop</emphasis> package.
</para></listitem><listitem><para> If you have doubts on the
keystore/truststore content requirements for signing/encrypting messages, <link
linkend="chap_index">read here</link>. Moreover you can find a text
file in the sources showing the store configuration used for the interoperability tests
(<emphasis>src/test/resources/interop/nov2007/wsse/shared/META-INF/readme.txt</emphasis>).
</para></listitem></itemizedlist></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-wsconsume.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-wsconsume.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-wsconsume.xml 2010-11-02 19:25:45 UTC (rev
13202)
@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-wsconsume"><title>JBossWS-wsconsume</title><para>wsconsume
is a command line tool and ant task that "consumes" the abstract contract (WSDL
file) and produces portable JAX-WS service and client artifacts. For a more detailed
overview, see <ulink
url="http://community.jboss.org/docs/DOC-13544#TopDown_Using_wsconsu...
wsconsume"</ulink>.</para><para/><section
id="JBossWS-wsconsume_Command_Line_Tool"><title>Command Line
Tool</title><para>The command line tool has the following
usage:</para><screen xml:space="preserve">usage: 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
@WebServiceClient.wsdlLocation
+ -o, --output=<directory> The directory to put generated artifacts
+ -s, --source=<directory> The directory to put Java source
+ -t, --target=<2.0|2.1|2.2> The JAX-WS specification target
+ -q, --quiet Be somewhat more quiet
+ -v, --verbose Show full exception stack traces
+ -l, --load-consumer Load the consumer and exit (debug utility)
+ -e, --extension Enable SOAP 1.2 binding extension
+ -a, --additionalHeaders Enables processing of implicit SOAP
headers</screen><para> </para><para><emphasis
role="bold">Note</emphasis> : The wsdlLocation is used when creating
the Service to be used by clients and will be added to the @WebServiceClient annotation,
for an endpoint implementation based on the generated service endpoint interface you will
need to manually add the wsdlLocation to the @WebService annotation on your web service
implementation and not the service endpoint interface.</para><section
id="JBossWS-wsconsume_Examples"><title>Examples</title><para>Generate
artifacts in Java class form only:</para><screen
xml:space="preserve">wsconsume Example.wsdl
+</screen><para>Generate source and class files:</para><screen
xml:space="preserve">wsconsume -k Example.wsdl
+</screen><para>Generate source and class files in a custom
directory:</para><screen xml:space="preserve">wsconsume -k -o custom
Example.wsdl
+</screen><para>Generate source and class files in the org.foo
package:</para><screen xml:space="preserve">wsconsume -k -p org.foo
Example.wsdl
+</screen><para>Generate source and class files using multiple binding
files:</para><screen xml:space="preserve">wsconsume -k -b
wsdl-binding.xml -b schema1-binding.xml -b
schema2-binding.xml</screen></section>
+</section>
+<section id="JBossWS-wsconsume_Maven_Plugin"><title>Maven
Plugin</title><para>The wsconsume tools is included in the <emphasis
role="bold">org.jboss.ws.plugins:maven-jaxws-tools-plugin</emphasis>
plugin. The plugin has two goals for running the tool,
<emphasis>wsconsume</emphasis> and
<emphasis>wsconsume-test</emphasis>, which basically do the same during
different maven build phases (the former triggers the sources generation during
<emphasis>generate-sources</emphasis> phase, the latter during the
<emphasis>generate-test-sources</emphasis> one).</para><para>The
wsconsume plugin has the following parameters:</para><informaltable><tgroup
cols="3"><colspec colnum="1"
colname="col1"/><colspec colnum="2"
colname="col2"/><colspec colnum="3"
colname="col3"/><thead><row><entry>Attribute</entry><entry>Description</entry><entry>Default
</entry></row></thead><tbody><row><entry>bindingFiles</entry><entry>JAXWS
or JAXB binding
file</entry><entry>true</entry></row><row><entry>classpath!
Elements</entry><entry><para>Each classpathElement provides
a</para><para>library file to be added to
classpath</para></entry><entry><para>${project.compileClasspathElements}</para><para>or</para><para>${project.testClasspathElements}</para></entry></row><row><entry>catalog</entry><entry>Oasis
XML Catalog file for entity
resolution</entry><entry>none</entry></row><row><entry>targetPackage</entry><entry>The
target Java package for generated
code.</entry><entry>generated</entry></row><row><entry>bindingFiles</entry><entry>One
or more JAX-WS or JAXB binding
file</entry><entry>none</entry></row><row><entry>wsdlLocation</entry><entry>Value
to use for
@WebServiceClient.wsdlLocation</entry><entry>generated</entry></row><row><entry>outputDirectory</entry><entry>The
output directory for generated
artifacts.</entry><entry><para>${project.build.outputDirectory}</para><para>or</para><para>${project.build.testOutputDirectory}</para></entry></row><row><entry>sourceDirectory</entry><entry!
The output directory for Java
source.</entry><entry>${project!
.build.d
irectory}/wsconsume/java</entry></row><row><entry>verbose</entry><entry>Enables
more informational output about command
progress.</entry><entry>false</entry></row><row><entry>wsdls</entry><entry>The
WSDL files or URLs to
consume</entry><entry>n/a</entry></row><row><entry>extension</entry><entry>Enable
SOAP 1.2 binding
extension.</entry><entry>false</entry></row></tbody></tgroup></informaltable><section
id="JBossWS-wsconsume_Examples_873412"><title>Examples</title><para>You
can use wsconsume in your own project build simply referencing the
<emphasis>maven-jaxws-tools-plugin</emphasis> in the configured plugins in
your pom.xml file.</para><para>The following example makes the plugin consume
the test.wsdl file and generate SEI and wrappers' java sources. The generated sources
are then compiled together with the other project classes.</para><screen
xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ <version>1.0.0.GA</version>
+ <configuration>
+ <wsdls>
+ <wsdl>${basedir}/test.wsdl</wsdl>
+ </wsdls>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsconsume</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen><para> </para><para>You can also specify multiple wsdl
files, as well as force the target package, enable SOAP 1.2 binding and turn the
tool's verbose mode on:</para><para> </para><screen
xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ <version>1.0.0.GA</version>
+ <configuration>
+ <wsdls>
+ <wsdl>${basedir}/test.wsdl</wsdl>
+ <wsdl>${basedir}/test2.wsdl</wsdl>
+ </wsdls>
+ <targetPackage>foo.bar</targetPackage>
+ <extension>true</extension>
+ <verbose>true</verbose>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsconsume</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen><para> </para><para>Finally, if the wsconsume invocation
is required for consuming a wsdl to be used in your testsuite only, you might want to use
the <emphasis>wsconsume-test</emphasis> goal as
follows:</para><para> </para><screen
xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ <version>1.0.0.GA</version>
+ <configuration>
+ <wsdls>
+ <wsdl>${basedir}/test.wsdl</wsdl>
+ </wsdls>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsconsume-test</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen></section>
+</section>
+<section id="JBossWS-wsconsume_Ant_Task"><title>Ant
Task</title><note><para><para><emphasis><emphasis
role="bold">Note</emphasis></emphasis></para><para><emphasis>With
2.0.GA the task was renamed to org.jboss.wsf.spi.tools.ant.WSConsumeTask. Also put
streamBuffer.jar and stax-ex.jar in the classpath of the ant task to generate the
appropriate artefacts. Both jar files are in the jbossws lib directory. For
jbossws-native-2.0.3.GA these files are not automatically installed if you run
jboss-deployXX.</emphasis></para></para></note><para>The
wsconsume ant task has the following
attributes:</para><informaltable><tgroup cols="3"><colspec
colnum="1" colname="col1"/><colspec colnum="2"
colname="col2"/><colspec colnum="3"
colname="col3"/><thead><row><entry>Attribute</entry><entry>Description</entry><entry>Default
</entry></row></thead><tbody><row><entry>fork</entry><entry>Whether
or not to run the generation task in a separate
VM.</entry><entry>true</entry></row><row><entry>keep</e!
ntry><entry>Keep/Enable Java source code
generation.</entry><entry>false</entry></row><row><entry>catalog</entry><entry>Oasis
XML Catalog file for entity
resolution</entry><entry>none</entry></row><row><entry>package</entry><entry>The
target Java package for generated
code.</entry><entry>generated</entry></row><row><entry>binding</entry><entry>A
JAX-WS or JAXB binding
file</entry><entry>none</entry></row><row><entry>wsdlLocation</entry><entry>Value
to use for
@WebServiceClient.wsdlLocation</entry><entry>generated</entry></row><row><entry>destdir</entry><entry>The
output directory for generated
artifacts.</entry><entry>"output"</entry></row><row><entry>sourcedestdir</entry><entry>The
output directory for Java source.</entry><entry>value of
destdir</entry></row><row><entry>target</entry><entry>The
JAX-WS specification target. Allowed values are 2.0, 2.1 and
2.2</entry><entry/></row><row><entry>verbose</entry><entry>Enables
more informational output about command progress.</en!
try><entry>false</entry></row><row><entry>wsdl</entry><entry>T!
he WSDL
file or
URL</entry><entry>n/a</entry></row><row><entry>extension</entry><entry>Enable
SOAP 1.2 binding
extension.</entry><entry><para>false</para></entry></row><row><entry>additionalHeaders</entry><entry>Enables
processing of implicit SOAP
headers</entry><entry>false</entry></row></tbody></tgroup></informaltable><para><emphasis
role="bold">Note</emphasis> : The wsdlLocation is used when creating
the Service to be used by clients and will be added to the @WebServiceClient annotation,
for an endpoint implementation based on the generated service endpoint interface you will
need to manually add the wsdlLocation to the @WebService annotation on your web service
implementation and not the service endpoint
interface.</para><para> </para><para>Also, the following nested
elements are supported:</para><informaltable><tgroup
cols="3"><colspec colnum="1"
colname="col1"/><colspec colnum="2"
colname="col2"/><colspec colnum="3"
colname="col3"/><thead><row><entry>Element</entry><entry>Des!
cription</entry><entry>Default
</entry></row></thead><tbody><row><entry>binding</entry><entry>A
JAXWS or JAXB binding
file</entry><entry>none</entry></row><row><entry>jvmarg</entry><entry>Allows
setting of custom jvm
arguments</entry><entry/></row></tbody></tgroup></informaltable><para> </para><section
id="JBossWS-wsconsume_Examples_49471"><title>Examples</title><para>Generate
JAX-WS source and classes in a separate JVM with separate directories, a custom wsdl
location attribute, and a list of binding files from foo.wsdl:</para><screen
xml:space="preserve"><wsconsume
+ fork="true"
+ verbose="true"
+ destdir="output"
+ sourcedestdir="gen-src"
+ keep="true"
+ wsdllocation="handEdited.wsdl"
+ wsdl="foo.wsdl">
+ <binding dir="binding-files" includes="*.xml"
excludes="bad.xml"/>
+</wsconsume></screen></section>
+</section>
+<section id="JBossWS-wsconsume_Related_information"><title>Related
information</title><itemizedlist><listitem><para> <ulink
url="http://java.sun.com/webservices/docs/2.0/jaxws/customizations.h...
binding customization</ulink>
</para></listitem></itemizedlist></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-wsprovide.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-wsprovide.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-wsprovide.xml 2010-11-02 19:25:45 UTC (rev
13202)
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-wsprovide"><title>JBossWS-wsprovide</title><para>wsprovide
is a command line tool and ant task that generates portable JAX-WS artifacts for a service
endpoint implementation. It also has the option to "provide" the abstract
contract for offline usage. See <ulink
url="http://community.jboss.org/docs/DOC-13544#BottomUp_Using_wsprov...
wsprovide"</ulink> for a detailed
walk-through.</para><para/><section
id="JBossWS-wsprovide_Command_Line_Tool"><title>Command Line
Tool</title><para>The command line tool has the following
usage:</para><screen xml:space="preserve"> usage: wsprovide
[options] <endpoint class name>
+ options:
+ -h, --help Show this help message
+ -k, --keep Keep/Generate Java source
+ -w, --wsdl Enable WSDL file generation
+ -c. --classpath=<path< The classpath that contains the endpoint
+ -o, --output=<directory> The directory to put generated artifacts
+ -r, --resource=<directory> The directory to put resource artifacts
+ -s, --source=<directory> The directory to put Java source
+ -e, --extension Enable SOAP 1.2 binding extension
+ -q, --quiet Be somewhat more quiet
+ -t, --show-traces Show full exception stack traces</screen><section
id="JBossWS-wsprovide_Examples"><title>Examples</title><para>Generating
wrapper classes for portable artifacts in the "generated"
directory:</para><screen xml:space="preserve">wsprovide -o generated
foo.Endpoint
+</screen><para>Generating wrapper classes and WSDL in the
"generated" directory</para><screen
xml:space="preserve">wsprovide -o generated -w foo.Endpoint
+</screen><para>Using an endpoint that references other
jars</para><screen xml:space="preserve">wsprovide -o generated -c
application1.jar:application2.jar foo.Endpoint</screen></section>
+</section>
+<section id="JBossWS-wsprovide_Maven_Plugin"><title>Maven
Plugin</title><para>The wsprovide tools is included in the <emphasis
role="bold">org.jboss.ws.plugins:maven-jaxws-tools-plugin</emphasis>
plugin. The plugin has two goals for running the tool,
<emphasis>wsprovide</emphasis> and
<emphasis>wsprovide-test</emphasis>, which basically do the same during
different maven build phases (the former triggers the sources generation during
<emphasis>process-classes</emphasis> phase, the latter during the
<emphasis>process-test-classes</emphasis> one).</para><para>The
wsprovide plugin has the following parameters:</para><informaltable><tgroup
cols="3"><colspec colnum="1"
colname="col1"/><colspec colnum="2"
colname="col2"/><colspec colnum="3"
colname="col3"/><thead><row><entry> Attribute
</entry><entry> Description </entry><entry> Default
</entry></row></thead><tbody><row><entry>testClasspathElements</entry><entry><para>Each
classpathElement provides a</para><para>library file to b!
e added to
classpath</para></entry><entry><para>${project.compileClasspathElements}</para><para>or</para><para>${project.testClasspathElements}</para></entry></row><row><entry>outputDirectory</entry><entry>The
output directory for generated
artifacts.</entry><entry><para>${project.build.outputDirectory}</para><para>or</para><para>${project.build.testOutputDirectory}</para></entry></row><row><entry>resourceDirectory</entry><entry>The
output directory for resource artifacts
(WSDL/XSD).</entry><entry>${project.build.directory}/wsprovide/resources</entry></row><row><entry>sourceDirectory</entry><entry>The
output directory for Java
source.</entry><entry>${project.build.directory}/wsprovide/java</entry></row><row><entry>extension</entry><entry>Enable
SOAP 1.2 binding
extension.</entry><entry>false</entry></row><row><entry>generateWsdl</entry><entry>Whether
or not to generate
WSDL.</entry><entry>false</entry></row><row><entry>verbose</entry><entry>Enables
more informational output!
about command
progress.</entry><entry>false</entry></row><row!
<entry>
<emphasis
role="bold">endpointClass</emphasis></entry><entry><emphasis
role="bold">Service Endpoint
Implementation.</emphasis></entry></row></tbody></tgroup></informaltable><section
id="JBossWS-wsprovide_Examples_309492"><title>Examples</title><para>You
can use wsprovide in your own project build simply referencing the
<emphasis>maven-jaxws-tools-plugin</emphasis> in the configured plugins in
your pom.xml file.</para><para>The following example makes the plugin provide
the wsdl file and artifact sources for the specified endpoint
class:</para><screen xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ &lt;version&gt;@pom.version(a)&lt;/version&gt;
+ <configuration>
+ <verbose>true</verbose>
+
<endpointClass>org.jboss.test.ws.plugins.tools.wsprovide.TestEndpoint</endpointClass>
+ <generateWsdl>true</generateWsdl>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsprovide</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen><para> </para><para>The following example does the same,
but is meant for use in your own testsuite:</para><screen
xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ &lt;version&gt;@pom.version(a)&lt;/version&gt;
+ <configuration>
+ <verbose>true</verbose>
+
<endpointClass>org.jboss.test.ws.plugins.tools.wsprovide.TestEndpoint2</endpointClass>
+ <generateWsdl>true</generateWsdl>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsprovide-test</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen><para> </para></section>
+</section>
+<section id="JBossWS-wsprovide_Ant_Task"><title>Ant
Task</title><note><para><para><emphasis><emphasis
role="bold">Note</emphasis></emphasis></para><para><emphasis>With
2.0.GA the task was renamed to
org.jboss.wsf.spi.tools.ant.WSProvideTask</emphasis></para></para></note><para>The
wsprovide ant task has the following
attributes:</para><informaltable><tgroup cols="3"><colspec
colnum="1" colname="col1"/><colspec colnum="2"
colname="col2"/><colspec colnum="3"
colname="col3"/><thead><row><entry> Attribute
</entry><entry> Description </entry><entry> Default
</entry></row></thead><tbody><row><entry>fork</entry><entry>Whether
or not to run the generation task in a separate
VM.</entry><entry>true</entry></row><row><entry>keep</entry><entry>Keep/Enable
Java source code
generation.</entry><entry>false</entry></row><row><entry>destdir</entry><entry>The
output directory for generated
artifacts.</entry><entry>"output"</entry></row><row><entry>resourcedestdir</entry><entry>The
output dir!
ectory for resource artifacts (WSDL/XSD).</entry><entry>value of
destdir</entry></row><row><entry>sourcedestdir</entry><entry>The
output directory for Java source.</entry><entry>value of
destdir</entry></row><row><entry>extension</entry><entry>Enable
SOAP 1.2 binding
extension.</entry><entry>false</entry></row><row><entry>genwsdl</entry><entry>Whether
or not to generate
WSDL.</entry><entry>false</entry></row><row><entry>verbose</entry><entry>Enables
more informational output about command
progress.</entry><entry>false</entry></row><row><entry><emphasis
role="bold">sei</emphasis></entry><entry><emphasis
role="bold">Service Endpoint
Implementation.</emphasis></entry></row><row><entry>classpath</entry><entry>The
classpath that contains the service endpoint
implementation.</entry><entry>"."</entry></row></tbody></tgroup></informaltable><section
id="JBossWS-wsprovide_Examples_651421"><title>Examples</title><para>Executing
wsprovide in verbose mode with separate output directorie!
s for source, resources, and classes:</para><screen xml:space=!
"preserv
e"><target name="test-wsproivde"
depends="init">
+ <taskdef name="wsprovide"
classname="org.jboss.wsf.spi.tools.ant.WSProvideTask">
+ <classpath refid="core.classpath"/>
+ </taskdef>
+ <wsprovide
+ fork="false"
+ keep="true"
+ destdir="out"
+ resourcedestdir="out-resource"
+ sourcedestdir="out-source"
+ genwsdl="true"
+ verbose="true"
+
sei="org.jboss.test.ws.jaxws.jsr181.soapbinding.DocWrappedServiceImpl">
+ <classpath>
+ <pathelement path="${tests.output.dir}/classes"/>
+ </classpath>
+ </wsprovide>
+</target>
+</screen></section>
+</section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-wsrunclient.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-wsrunclient.xml (rev
0)
+++ stack/native/trunk/src/main/doc/JBossWS-wsrunclient.xml 2010-11-02 19:25:45 UTC (rev
13202)
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter
id="chap_JBossWS-wsrunclient"><title>JBossWS-wsrunclient</title><para>wsrunclient
is a command line tool that invokes a JBossWS JAX-WS Web Service client. It builds the
correct classpath and endorsed libs for you. Feel free to use the code for this script to
make your own shell scripts. It is open source after
all.</para><section><title>Usage</title><screen
xml:space="preserve"> wsrunclient [-classpath <additional class
path>] <java-main-class> [arguments...]
+</screen></section>
+<section><title>Examples</title><para>Invoking a standalone
JAX-WS client:</para><screen xml:space="preserve">wsrunclient
echo.EchoClient</screen><para>Invoking a standalone JAX-WS client that uses
external jars:</para><screen xml:space="preserve">wsrunclient
-classpath jar1.jar:jar2.jar echo.EchoClient
+
+</screen></section>
+</chapter>
\ No newline at end of file
Modified: stack/native/trunk/src/main/scripts/assembly-bin-dist.xml
===================================================================
--- stack/native/trunk/src/main/scripts/assembly-bin-dist.xml 2010-11-02 18:02:20 UTC (rev
13201)
+++ stack/native/trunk/src/main/scripts/assembly-bin-dist.xml 2010-11-02 19:25:45 UTC (rev
13202)
@@ -55,6 +55,10 @@
<include>JBossORG-EULA.txt</include>
</includes>
</fileSet>
+ <fileSet>
+ <directory>target/docbook/publish</directory>
+ <outputDirectory>jbossws-native-bin-dist/docs</outputDirectory>
+ </fileSet>
<!-- deploy -->
<fileSet>
<directory>target/assembly/deploy-artifacts</directory>