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 &lt;servlet-class&gt; 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>