4:36 a.m.
Author: sam.griffith(a)jboss.com
Date: 2007-01-05 05:36:17 -0500 (Fri, 05 Jan 2007)
New Revision: 1802
Added:
trunk/jbossws-docs/online/tutorial-doc/en/images/tutorial_images/
trunk/jbossws-docs/online/tutorial-doc/en/images/tutorial_images/tutorial_1/
trunk/jbossws-docs/online/tutorial-doc/en/images/tutorial_images/tutorial_1/WSDL Test
in Oxygen.png
trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/
trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/doc-endpoints.xml
trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/getting-started.xml
trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/message-endpoints.xml
trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/rpc-endpoints.xml
trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/tutorial-1.xml
Modified:
trunk/jbossws-docs/online/tutorial-doc/en/master.template
trunk/jbossws-docs/online/tutorial-doc/en/master.xml
trunk/jbossws-docs/online/tutorial-doc/en/modules/introduction.xml
Log:
Merged my stuff from old project format to new
Added: trunk/jbossws-docs/online/tutorial-doc/en/images/tutorial_images/tutorial_1/WSDL
Test in Oxygen.png
===================================================================
(Binary files differ)
Property changes on:
trunk/jbossws-docs/online/tutorial-doc/en/images/tutorial_images/tutorial_1/WSDL Test in
Oxygen.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: trunk/jbossws-docs/online/tutorial-doc/en/master.template
===================================================================
--- trunk/jbossws-docs/online/tutorial-doc/en/master.template 2007-01-05 10:26:27 UTC (rev
1801)
+++ trunk/jbossws-docs/online/tutorial-doc/en/master.template 2007-01-05 10:36:17 UTC (rev
1802)
@@ -11,10 +11,7 @@
<!ENTITY ch-installation SYSTEM
"modules/installation/installation.xml">
<!ENTITY s-install-jboss SYSTEM
"modules/installation/install-jboss.xml">
<!ENTITY s-install-on-jboss-5 SYSTEM
"modules/installation/install-on-jboss-5.xml">
-<!ENTITY ch-getting-started SYSTEM
"modules/getting-started/getting-started.xml">
-<!ENTITY s-rpc-endpoints SYSTEM
"modules/getting-started/rpc-endpoints.xml">
-<!ENTITY s-doc-endpoints SYSTEM
"modules/getting-started/doc-endpoints.xml">
-<!ENTITY s-message-style SYSTEM
"modules/getting-started/message-endpoints.xml">
+<!ENTITY ch-tutorial-1 SYSTEM
"modules/tutorial-1/tutorial-1.xml">
]>
@@ -48,6 +45,8 @@
&ch-introduction;
&ch-installation;
+ &ch-tutorial-1;
+
<!-- &ch-getting-started; -->
</book>
Modified: trunk/jbossws-docs/online/tutorial-doc/en/master.xml
===================================================================
--- trunk/jbossws-docs/online/tutorial-doc/en/master.xml 2007-01-05 10:26:27 UTC (rev
1801)
+++ trunk/jbossws-docs/online/tutorial-doc/en/master.xml 2007-01-05 10:36:17 UTC (rev
1802)
@@ -11,10 +11,7 @@
<!ENTITY ch-installation SYSTEM
"modules/installation/installation.xml">
<!ENTITY s-install-jboss SYSTEM
"modules/installation/install-jboss.xml">
<!ENTITY s-install-on-jboss-5 SYSTEM
"modules/installation/install-on-jboss-5.xml">
-<!ENTITY ch-getting-started SYSTEM
"modules/getting-started/getting-started.xml">
-<!ENTITY s-rpc-endpoints SYSTEM
"modules/getting-started/rpc-endpoints.xml">
-<!ENTITY s-doc-endpoints SYSTEM
"modules/getting-started/doc-endpoints.xml">
-<!ENTITY s-message-style SYSTEM
"modules/getting-started/message-endpoints.xml">
+<!ENTITY ch-tutorial-1 SYSTEM
"modules/tutorial-1/tutorial-1.xml">
]>
@@ -23,7 +20,7 @@
<bookinfo>
<title>JBossWS Tutorials</title>
<subtitle>jbossws-2.0.0.CR3.DEV</subtitle>
- <releaseinfo>06-Dec-2006</releaseinfo>
+ <releaseinfo>10-Dec-2006</releaseinfo>
<releaseinfo>
<ulink
url="http://labs.jboss.com/jbossws/tutorials/en/html/index.html"...
Pages]</ulink>,
<ulink
url="http://labs.jboss.com/jbossws/tutorials/en/html_single/index.ht...
Page]</ulink>,
@@ -48,6 +45,8 @@
&ch-introduction;
&ch-installation;
+ &ch-tutorial-1;
+
<!-- &ch-getting-started; -->
</book>
Modified: trunk/jbossws-docs/online/tutorial-doc/en/modules/introduction.xml
===================================================================
--- trunk/jbossws-docs/online/tutorial-doc/en/modules/introduction.xml 2007-01-05 10:26:27
UTC (rev 1801)
+++ trunk/jbossws-docs/online/tutorial-doc/en/modules/introduction.xml 2007-01-05 10:36:17
UTC (rev 1802)
@@ -16,8 +16,15 @@
downloaded a version of AS 5 yet, you can get it here:
<ulink
url="http://labs.jboss.com/portal/jbossas/download/index.html"/...
</para>
-
+
&s-what-is-a-web-service;
+
+<!--
+ <para>
+ The J2EE 5 is descibed more here at the
+ <ulink url="http://java.sun.com/javaee/5/docs/tutorial/doc/">J2EE
5 Tutorial</ulink>.
+ </para>
+-->
</chapter>
Added: trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/doc-endpoints.xml
===================================================================
---
trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/doc-endpoints.xml 2007-01-05
10:26:27 UTC (rev 1801)
+++
trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/doc-endpoints.xml 2007-01-05
10:36:17 UTC (rev 1802)
@@ -0,0 +1,216 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- $Id: doc-endpoints.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $
-->
+
+<sect1 id="doc-endpoints">
+ <title>Document Style Endpoints</title>
+
+ <para> With document style web services two business partners agree on the
exchange of complex business documents
+ that are well defined in XML schema. For example, one party sends a document
describing a
+ purchase order, the other responds (immediately or later) with a document that
describes
+ the status of the purchase order. No need to agree on such low level details as
operation names and their
+ associated parameters.</para>
+
+ <para> The payload of the SOAP message is an XML document that can be validated
against XML schema. No wrapping RPC element, no individual parameters. </para>
+
+ <para>
+ In chapter we develop a document/literal wrapped service endpoint that uses the same
service endpoint interface (SEI) as for
+ <link linkend="rpc-endpoints">RPC Style Endpoints</link>
example.
+
+ <programlisting><![CDATA[
+ public interface TrivialService extends Remote
+ {
+ String purchase (String person, String product) throws RemoteException;
+ }
+ ]]></programlisting>
+ </para>
+
+ <para><command>Generating required deployment
artifacts</command></para>
+
+ <para>
+ Run wstools on a document/literal configuration:
+ <orderedlist>
+ <listitem><para>The wsdlStyle attribute is set to
'document'</para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ <programlisting><![CDATA[
+ <configuration ...>
+ <java-wsdl>
+ <service name="SampleService" style="document"
+
endpoint="org.jboss.test.ws.jaxrpc.samples.docstyle.wrapped.TrivialService"
/>
+
+ <namespaces
target-namespace="http://org.jboss.ws/samples/docstyle/wrapped"
+
type-namespace="http://org.jboss.ws/samples/docstyle/wrapped/types"/>
+
+ <mapping file="jaxrpc-mapping.xml"/>
+ <webservices servlet-link="TrivialEndpoint"/>
+ </java-wsdl>
+ </configuration>
+ ]]></programlisting></para>
+
+ <para>The generated WSDL contains complex type definitions for the
request/response payloads,
+ which are referenced from the WSDL messages</para>
+
+ <para>
+ <programlisting><![CDATA[
+ <complexType name="purchase">
+ <sequence>
+ <element name="String_1" type="string"
nillable="true"/>
+ <element name="String_2" type="string"
nillable="true"/>
+ </sequence>
+ </complexType>
+
+ <complexType name="purchaseResponse">
+ <sequence>
+ <element name="result" type="string"
nillable="true"/>
+ </sequence>
+ </complexType>
+ ]]></programlisting></para>
+
+ <para>WSTools also generates request/response java objects that correspond to
these schema types.
+ These java wrapper beans are mapped in jaxrpc-mapping.xml</para>
+
+ <para>
+ <programlisting><![CDATA[
+ <java-xml-type-mapping>
+ <java-type>
+
org.jboss.test.ws.jaxrpc.samples.docstyle.wrapped.TrivialService_purchase_RequestStruct
+ </java-type>
+ <root-type-qname
xmlns:typeNS="http://org.jboss.ws/samples/docstyle/wrapped/types">
+ typeNS:purchase
+ </root-type-qname>
+ <qname-scope>complexType</qname-scope>
+ <variable-mapping>
+ <java-variable-name>String_1</java-variable-name>
+ <xml-element-name>String_1</xml-element-name>
+ </variable-mapping>
+ <variable-mapping>
+ <java-variable-name>String_2</java-variable-name>
+ <xml-element-name>String_2</xml-element-name>
+ </variable-mapping>
+ </java-xml-type-mapping>
+
+ <java-xml-type-mapping>
+ <java-type>
+
org.jboss.test.ws.jaxrpc.samples.docstyle.wrapped.TrivialService_purchase_ResponseStruct
+ </java-type>
+ <root-type-qname
xmlns:typeNS="http://org.jboss.ws/samples/docstyle/wrapped/types">
+ typeNS:purchaseResponse
+ </root-type-qname>
+ <qname-scope>complexType</qname-scope>
+ <variable-mapping>
+ <java-variable-name>result</java-variable-name>
+ <xml-element-name>result</xml-element-name>
+ </variable-mapping>
+ </java-xml-type-mapping>
+ ]]></programlisting></para>
+
+ <para><command>SOAP message exchange</command></para>
+
+ <para>Below you see the SOAP messages that are beeing exchanged. </para>
+
+ <para>
+ <programlisting><![CDATA[
+ Incomming SOAPMessage
+
+ <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
+ <env:Header/>
+ <env:Body>
+ <ns1:purchase
xmlns:ns1='http://org.jboss.ws/samples/docstyle/wrapped/types'>
+ <String_1>Kermit</String_1>
+ <String_2>Ferrari</String_2>
+ </ns1:purchase>
+ </env:Body>
+ </env:Envelope>
+ ]]></programlisting></para>
+
+ <para>
+ <programlisting><![CDATA[
+ Outgoing SOAPMessage
+
+ <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
+ <env:Header/>
+ <env:Body>
+ <ns1:purchaseResponse
xmlns:ns1='http://org.jboss.ws/samples/docstyle/wrapped/types'>
+ <result>okKermitFerrari</result>
+ </ns1:purchaseResponse>
+ </env:Body>
+ </env:Envelope>
+ ]]></programlisting></para>
+
+ <para>On the wire the message structure is no different to
rpc/literal.</para>
+
+ <para><command>Document Bare Endpoints</command></para>
+
+ <para>What we have seen above is a document/literal (wrapped) endpoint. The
endpoint operation paramters and return are automatically wrapped in request/response
structures. The SEI methods
+ deal with the individual properties from these request/response
structures.</para>
+
+ <para>Whith document/literal (bare), the SEI methods deal directly with the
request/response structures.</para>
+
+ <para>
+ <programlisting><![CDATA[
+ public interface TrivialService extends Remote
+ {
+ TrivialOrderResponse purchase(TrivialOrder order) throws RemoteException;
+ }
+ ]]></programlisting></para>
+
+ <para>Run wstools with the following configuration</para>
+
+ <para>
+ <programlisting><![CDATA[
+ <configuration ...>
+ <java-wsdl>
+ <service name="SampleService" style="document"
parameter-style="bare"
+ endpoint="org.jboss.test.ws.samples.docstyle.bare.TrivialService"
/>
+
+ <namespaces
target-namespace="http://org.jboss.ws/samples/docstyle/bare"
+ type-namespace="http://org.jboss.ws/samples/docstyle/bare/types"/>
+
+ <mapping file="jaxrpc-mapping.xml"/>
+ <webservices servlet-link="TrivialEndpoint"/>
+ </java-wsdl>
+ </configuration>
+ ]]></programlisting>
+ </para>
+
+ <para><command>SOAP message exchange</command></para>
+
+ <para>Below you see the SOAP messages that are beeing exchanged. </para>
+
+ <para>
+ <programlisting><![CDATA[
+ Incomming SOAPMessage
+
+ <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
+ <env:Header/>
+ <env:Body>
+ <ns1:purchase
xmlns:ns1='http://org.jboss.ws/samples/docstyle/bare/types'>
+ <person>Kermit</person>
+ <product>Ferrari</product>
+ </ns1:purchase>
+ </env:Body>
+ </env:Envelope>
+ ]]></programlisting>
+ </para>
+
+ <para>
+ <programlisting><![CDATA[
+ Outgoing SOAPMessage
+
+ <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
+ <env:Header/>
+ <env:Body>
+ <ns1:purchaseResponse
xmlns:ns1='http://org.jboss.ws/samples/docstyle/bare/types'>
+ <result>okKermitFerrari</result>
+ </ns1:purchaseResponse>
+ </env:Body>
+ </env:Envelope>
+ ]]></programlisting></para>
+
+ <para>On the wire the message structure is no different to document/literal
wrapped. That the implementation
+ deals with the wrapper beans directly is an implementation detail.</para>
+
+</sect1>
Added: trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/getting-started.xml
===================================================================
---
trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/getting-started.xml 2007-01-05
10:26:27 UTC (rev 1801)
+++
trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/getting-started.xml 2007-01-05
10:36:17 UTC (rev 1802)
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<chapter id="getting-started">
+ <title>Getting started</title>
+ <para>
+ In order to get started we will begin with some simple endpoint
implementations.
+ This chapter will walk you through the standard J2EE 1.4 development model and
explore the different style/use models
+ to bind your endpoint implementations.
+ A WSDL binding describes how the service is bound to a messaging protocol,
particularly the SOAP messaging protocol.
+ JBossWS conforms to the WS-I basic profile, which eliminates the encoded use.
This leaves you with the following style/use models:
+
+ <itemizedlist>
+ <listitem>
+ <para>RPC/literal</para>
+ </listitem>
+ <listitem>
+ <para>Document/literal</para>
+ </listitem>
+ <listitem>
+ <para>Message style</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Let's begin with a simple RPC web service endpoint implementation.
+ </para>
+
+ &s-rpc-endpoints;
+ &s-doc-endpoints;
+ &s-message-style;
+</chapter>
+
Added: trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/message-endpoints.xml
===================================================================
---
trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/message-endpoints.xml 2007-01-05
10:26:27 UTC (rev 1801)
+++
trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/message-endpoints.xml 2007-01-05
10:36:17 UTC (rev 1802)
@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- $Id: message-endpoints.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $
-->
+
+<sect1 id="message-endpoints">
+
+ <title>Message Style Endpoints</title>
+
+ <para>
+ You may come to the point where RPC/literal or Document/literal is not what you are
looking for.
+ This may be the case for instance, when you want to do the XML processing yourself
instead of deferring
+ it to the SOAP stack. JBossWS offers the possiblity to setup message style endpoints
that do exchange
+ raw XML documents mapped to DOM elements or SOAPElements,
+ </para>
+
+ <para>
+ This chapter describes a generic endpoint that can process arbitrary DOM elements.
+ </para>
+
+ <note>
+ <para>In the JAX-RPC specification this is not a permitted java type.
+ JBossWS extends the standard type support by DOM Element and SOAPElement.
+ </para>
+ </note>
+
+ <para>
+ <programlisting><![CDATA[
+ public interface MessageTestService extends Remote
+ {
+ public Element processElement(Element msg) throws RemoteException;
+ }
+ ]]></programlisting></para>
+
+ <para><command>Generating required deployment
artifacts</command></para>
+
+ <para>Run wstools with the following configuration</para>
+
+ <para>
+ <programlisting><![CDATA[
+ <configuration ...>
+ <java-wsdl>
+ <service name="MessageService" style="document"
parameter-style="bare"
+
endpoint="org.jboss.test.ws.jaxrpc.samples.message.MessageTestService">
+
+ <operation name="processElement"
return-xml-name="Response">
+ <parameter type="javax.xml.soap.SOAPElement"
xml-name="Order"/>
+ </operation>
+ </service>
+
+ <namespaces target-namespace="http://org.jboss.ws/samples/message"
+ type-namespace="http://org.jboss.ws/samples/message/types"/>
+
+ <mapping file="jaxrpc-mapping.xml"/>
+ <webservices servlet-link="TestService"/>
+ </java-wsdl>
+ </configuration>
+ ]]>
+ </programlisting></para>
+
+ <para>WSTools generates schema elements with xsd:anyType</para>
+
+ <para>
+ <programlisting><![CDATA[
+ <schema targetNamespace="http://org.jboss.ws/samples/message" ...>
+ <element name="Order" type="anyType"/>
+ <element name="Response" type="anyType"/>
+ </schema>
+
+ <message name="Message_processElement">
+ <part name="order" element="tns:Order"/>
+ </message>
+
+ <message name="Message_processElementResponse">
+ <part name="result" element="tns:Response"/>
+ </message>
+ ]]></programlisting></para>
+
+ <sect2>
+ <title>SOAPConnection for raw message dispatch</title>
+
+ <para>It is possible to use the standard javax.xml.soap.SOAPConnection to
dispatch a precreated SOAP message to a given endpoint</para>
+
+ <para>
+ <programlisting><![CDATA[
+ public void testSAAJClientFromEnvelope() throws Exception
+ {
+ MessageFactory mf = MessageFactory.newInstance();
+ SOAPMessage reqMsg = mf.createMessage();
+
+ String request =
+ "<ns1:Order xmlns:ns1='" + TARGET_NAMESPACE +
+ "' xmlns:ns2='http://somens'
attrval='somevalue'>" +
+ " <ns2:Customer>Kermit</ns2:Customer>" +
+ " <Item>Ferrari</Item>" +
+ "</ns1:Order>";
+
+ DocumentBuilder builder = getDocumentBuilder();
+ Document doc = builder.parse(new ByteArrayInputStream(request.getBytes()));
+ reqMsg.getSOAPBody().addDocument(doc);
+
+ SOAPConnectionFactory conFactory = SOAPConnectionFactory.newInstance();
+ SOAPConnection con = conFactory.createConnection();
+ SOAPMessage resMsg = con.call(reqMsg, new URL(TARGET_ENDPOINT));
+
+ SOAPBody soapBody = resMsg.getSOAPBody();
+ SOAPElement soapElement = (SOAPElement)soapBody.getChildElements().next();
+
+ validateResponse(soapElement);
+ }
+ ]]></programlisting></para>
+
+ <para><command>SOAP message exchange</command></para>
+
+ <para>Below you see the incomming SOAP messages.</para>
+
+ <para>
+ <programlisting><![CDATA[
+ Incomming SOAPMessage
+
+ <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
+ <env:Header/>
+ <env:Body>
+ <ns1:Order attrval='somevalue'
+ xmlns:ns1='http://org.jboss.ws/samples/message'
xmlns:ns2='http://somens'>
+ <ns2:Customer>Kermit</ns2:Customer>
+ <Item>Ferrari</Item>
+ </ns1:Order>
+ </env:Body>
+ </env:Envelope>
+ ]]></programlisting>
+ </para>
+ </sect2>
+</sect1>
\ No newline at end of file
Added: trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/rpc-endpoints.xml
===================================================================
---
trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/rpc-endpoints.xml 2007-01-05
10:26:27 UTC (rev 1801)
+++
trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/rpc-endpoints.xml 2007-01-05
10:36:17 UTC (rev 1802)
@@ -0,0 +1,224 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- $Id: rpc-endpoints.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $
-->
+
+<sect1 id="rpc-endpoints">
+
+ <title>A simple RPC Style Endpoint</title>
+ <para>
+ With RPC there is a wrapper element that names the endpoint operation. Child elements
of the RPC parent are the individual parameters.
+
+ The SOAP body is constructed based on some simple rules:
+
+ <itemizedlist>
+ <listitem>
+ <para>The port type operation name defines the endpoint method
name</para>
+ </listitem>
+ <listitem>
+ <para>Message parts are are endpoint method parameters</para>
+ </listitem>
+ </itemizedlist>
+
+ </para>
+
+ <para>
+ This chapter describes portable <link
linkend="jsr109-endpoints">J2EE-1.4 web service endpoint development
model</link> for plain java endpoints.
+ </para>
+
+ <tip><para>The more appropriate method using JSR-181 annotations is
described in chapter <link linkend="jsr181-pojo-endpoint">JSR-181 POJO
Endpoints</link>.</para></tip>
+
+ <para>
+ Let's start with a trivial service endpoint interface (SEI) that has a single
operation, which takes two string parameters and returns a string.
+
+ <programlisting><![CDATA[
+ public interface TrivialService extends Remote
+ {
+ String purchase (String person, String product) throws RemoteException;
+ }
+ ]]></programlisting>
+ </para>
+
+ <para>There are certain rules you have to follow for a valid SEI.
+ <itemizedlist>
+ <listitem>
+ <para>The SEI must extend java.rmi.Remote</para>
+ </listitem>
+
+ <listitem>
+ <para>All methods must include java.rmi.RemoteException in their throws
clause</para>
+ </listitem>
+
+ <listitem>
+ <para>Method parameter types are limited to the ones specified by the
JAXRPC-1.1 specification</para>
+ </listitem>
+ </itemizedlist> </para>
+
+ <para><command>The endpoint implementation
bean</command></para>
+
+ <para>The SEI defines the java contract of the web service. You will also need to
provide an implementation bean. Here it is</para>
+
+ <para>
+ <programlisting><![CDATA[
+ public class TrivialEndpointJSE implements TrivialService
+ {
+ public String purchase (String person, String product)
+ {
+ log.info("purchase: " + person + "," + product);
+ return "ok" + person + product;
+ }
+ }
+ ]]></programlisting></para>
+
+ <para><command>Generating required deployment
artifacts</command></para>
+
+ <para>JSR-109 requires a number of deployment artifacts, which are:
+ <itemizedlist>
+ <listitem>
+ <para>webservices.xml, the descriptor that identifies a deployment a web
service endpoint </para>
+ </listitem>
+
+ <listitem>
+ <para>wsdl, the abstract webservice contract</para>
+ </listitem>
+
+ <listitem>
+ <para>jaxrpc-mapping.xml, the mapping desriptor that bridges WSDL to
java</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>JBossWS comes with a tool collection called WSTools. WSTools that can
generate these artifacts from the given SEI. There is a command line version and an Apache
Ant task available. Both take a configuration file
+ as input. For details of the wstools configuration, see <link
linkend="appendix-a">Apendix A</link></para>
+
+ <para>
+
+
+ <programlisting><![CDATA[
+ <configuration ...>
+ <java-wsdl>
+ <service name="SampleService" style="rpc"
+
endpoint="org.jboss.test.ws.jaxrpc.samples.rpcstyle.TrivialService"/>
+
+ <namespaces target-namespace="http://org.jboss.ws/samples/rpcstyle"
+ type-namespace="http://org.jboss.ws/samples/rpcstyle/types"/>
+
+ <mapping file="jaxrpc-mapping.xml"/>
+ <webservices servlet-link="TrivialEndpoint"/>
+ </java-wsdl>
+ </configuration>
+ ]]></programlisting></para>
+
+ <para>You can run WSTools from the command line</para>
+
+ <para>
+ <programlisting><![CDATA[
+ > jboss-inst/bin/wstools.sh -cp {path to TrivialService.class} -config
wstools-config.xml
+ ]]></programlisting>
+ </para>
+
+ <para>or from an ant task</para>
+
+ <para>
+ <programlisting><![CDATA[
+ <!-- Define a taskdef for the wstools ant task -->
+ <taskdef name="wstools"
classname="org.jboss.ws.tools.ant.wstools">
+ <classpath refid="library.classpath"/>
+ <classpath refid="test.client.classpath"/>
+ <classpath path="${build.test.classes.dir}"/>
+ </taskdef>
+
+ <!-- samples/rpcstyle -->
+ <wstools dest="${build.wstools.resources.dir}/samples/rpcstyle/WEB-INF"
+ config="${test.resources.dir}/samples/rpcstyle/wstools-config.xml"/>
+ ]]></programlisting>
+ </para>
+
+ <para><command> The endpoint as a web
application</command></para>
+
+ <para>
+ A java service endpoint is deployed as a web application:
+ <orderedlist>
+ <listitem><para>Your service endpoint configured as a
servlet</para></listitem>
+ </orderedlist>
+
+ <programlisting><![CDATA[
+ <web-app xmlns="http://java.sun.com/xml/ns/j2ee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
+ http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
+ version="2.4">
+
+ <servlet>
+ <servlet-name>TrivialEndpoint</servlet-name>
+ (1)
<servlet-class>org.jboss.test.ws.jaxrpc.samples.rpcstyle.TrivialEndpointJSE</servlet-class>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>TrivialEndpoint</servlet-name>
+ <url-pattern>/*</url-pattern>
+ </servlet-mapping>
+
+ </web-app>
+ ]]></programlisting>
+
+ <note><para>The content of <servlet-class> element is not
at all a servlet as required by the servlet spec.
+ It is the endpoint implementation bean that is shown
above.</para></note>
+
+ </para>
+
+ <para><command>Packaging the endpoint</command></para>
+
+ <para>A JSR-109 java service endpoint (JSE) is packaged as a web application in a
*.war file. Note, that all descriptors are located in the WEB-INF directory with the WSDL
in a predefined
+ subdirectory. </para>
+
+ <para>
+ <programlisting><![CDATA[
+ <war warfile="${build.dir}/libs/jbossws-samples-rpcstyle.war"
+ webxml="${build.resources.dir}/samples/rpcstyle/WEB-INF/web.xml">
+ <classes dir="${build.dir}/classes">
+ <include
name="org/jboss/test/ws/samples/rpcstyle/TrivialEndpointJSE.class"/>
+ <include
name="org/jboss/test/ws/samples/rpcstyle/TrivialService.class"/>
+ </classes>
+ <webinf dir="${build.resources.dir}/samples/rpcstyle/WEB-INF">
+ <include name="jaxrpc-mapping.xml"/>
+ <include name="webservices.xml"/>
+ <include name="wsdl/**"/>
+ </webinf>
+ </war>
+ ]]></programlisting></para>
+
+ <para>How a J2EE-1.4 portable web service client connects to the endpoint is
described in <link linkend="jsr109-clients">JSR-109
Clients</link></para>
+
+ <para><command>SOAP message exchange</command></para>
+
+ <para>Below you see the SOAP messages that are beeing exchanged. </para>
+
+ <para>
+ <programlisting><![CDATA[
+ Incomming SOAPMessage
+
+ <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
+ <env:Header/>
+ <env:Body>
+ <ns1:purchase xmlns:ns1='http://org.jboss.ws/samples/rpcstyle'>
+ <String_1>Kermit</String_1>
+ <String_2>Ferrari</String_2>
+ </ns1:purchase>
+ </env:Body>
+ </env:Envelope>
+ ]]></programlisting>
+
+ <programlisting><![CDATA[
+ Outgoing SOAPMessage
+
+ <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
+ <env:Header/>
+ <env:Body>
+ <ns1:purchaseResponse
xmlns:ns1='http://org.jboss.ws/samples/rpcstyle'>
+ <result>okKermitFerrari</result>
+ </ns1:purchaseResponse>
+ </env:Body>
+ </env:Envelope>
+ ]]></programlisting></para>
+
+</sect1>
\ No newline at end of file
Added: trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/tutorial-1.xml
===================================================================
--- trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/tutorial-1.xml 2007-01-05
10:26:27 UTC (rev 1801)
+++ trunk/jbossws-docs/online/tutorial-doc/en/modules/tutorial-1/tutorial-1.xml 2007-01-05
10:36:17 UTC (rev 1802)
@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<chapter id="tutorial-1">
+
+ <title>Tutorial 1</title>
+ <para> In this tutorial we will see the basic structure of a JAX-WS 2.0 web
service and the Ant
+ file to build it. There are a few things to learn, so lets get to it.
</para>
+
+ <section>
+ <title>Endpiont Interface Definition</title>
+
+ <para>
+ We start out with a definition of our web services endpoint. Endpoints define
the interface
+ that we are going to export to the world thru WSDL for our web service. You
can see that
+ it is also much like a RMI object in that it is declared remote as well. The
methods in our
+ EndpointInterface definition must all be public as well.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+package org.jboss.samples.helloworld;
+
+import java.rmi.Remote;
+import java.rmi.RemoteException;
+
+public interface EndpointInterface extends Remote
+{
+ String sayHello(String toWhom) throws RemoteException;
+}
+ ]]>
+ </programlisting>
+ <para>
+ Our interface is about as simple as it gets. We take a String instance input
and return
+ a String as an output.
+ </para>
+ </section>
+
+ <section>
+ <title>Endpoint Class</title>
+ <para>Now we create the implementation of our Endpoint. Our example pays
homage to the
+ venerable "HelloWorld" known world over.
+ </para>
+ <programlisting>
+package org.jboss.samples.helloworld;
+
+import javax.jws.WebService;
+import javax.jws.WebMethod;
+
+@WebService(endpointinterface=")
+public class HelloWorldWS
+{
+ @WebMethod
+ public String sayHello(String toWhom)
+ {
+ return "Hello " + toWhom + "!" + " The date and time is:
" + new java.util.Date();
+ }
+}
+ </programlisting>
+
+ <para>
+ Here we see that we need our web service to import both the WebService and
WebMethod classes
+ from the javax.jws package for use in the annotations on our web service. We
are using the
+ simplest forms of both of those annotations. Doing so takes all the default
settings that the
+ annotation would define. We will go into that more in later tutorials.
+ </para>
+ <para>
+ Our class is flagged as a web service by the annotaion before the class
declaration. The class
+ must be public.
+ We have our "sayHello" method implementation which takes in a
string (someone's name) and
+ then returns a appropriate greeting string. That's it.
+ </para>
+
+ </section>
+
+ <section>
+ <title>ANT Build File</title>
+ <para>We'll see these main things in this build file:</para>
+ <itemizedlist>
+ <listitem>Libs needed</listitem>
+ <listitem>WSTool call to get WSDL</listitem>
+ <listitem>Packaging it up</listitem>
+ </itemizedlist>
+
+
+ </section>
+
+
+</chapter>