Author: sam.griffith(a)jboss.com Date: 2006-12-04 08:30:29 -0500 (Mon, 04 Dec 2006) New Revision: 1545 Added: trunk/docs/online/tutorial-doc/ trunk/docs/online/tutorial-doc/build-docbook.xml trunk/docs/online/tutorial-doc/build.xml trunk/docs/online/tutorial-doc/en/ trunk/docs/online/tutorial-doc/en/images/ trunk/docs/online/tutorial-doc/en/images/EventingCollaboration.gif trunk/docs/online/tutorial-doc/en/images/readme.txt trunk/docs/online/tutorial-doc/en/images/wstools-components.png trunk/docs/online/tutorial-doc/en/images/wstools-config.png trunk/docs/online/tutorial-doc/en/master.template trunk/docs/online/tutorial-doc/en/modules/ trunk/docs/online/tutorial-doc/en/modules/appendix-a.xml trunk/docs/online/tutorial-doc/en/modules/attachments/ trunk/docs/online/tutorial-doc/en/modules/attachments/attachments.xml trunk/docs/online/tutorial-doc/en/modules/clients/ trunk/docs/online/tutorial-doc/en/modules/clients/clients.xml trunk/docs/online/tutorial-doc/en/modules/clients/dii-clients.xml trunk/docs/online/tutorial-doc/en/modules/clients/jsr109-clients.xml trunk/docs/online/tutorial-doc/en/modules/clients/stub-properties.xml trunk/docs/online/tutorial-doc/en/modules/endpoints/ trunk/docs/online/tutorial-doc/en/modules/endpoints/endpoints.xml trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr109-ejb-endpoint.xml trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr109-endpoints.xml trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr109-pojo-endpoint.xml trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr181-ejb3-endpoint.xml trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr181-endpoints.xml trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr181-pojo-endpoint.xml trunk/docs/online/tutorial-doc/en/modules/endpoints/service-lifecycle.xml trunk/docs/online/tutorial-doc/en/modules/endpoints/template-config.xml trunk/docs/online/tutorial-doc/en/modules/exceptions/ trunk/docs/online/tutorial-doc/en/modules/exceptions/exceptions.xml trunk/docs/online/tutorial-doc/en/modules/getting-started/ trunk/docs/online/tutorial-doc/en/modules/getting-started/doc-endpoints.xml trunk/docs/online/tutorial-doc/en/modules/getting-started/getting-started.xml trunk/docs/online/tutorial-doc/en/modules/getting-started/message-endpoints.xml trunk/docs/online/tutorial-doc/en/modules/getting-started/rpc-endpoints.xml trunk/docs/online/tutorial-doc/en/modules/headers-handlers/ trunk/docs/online/tutorial-doc/en/modules/headers-handlers/dynamic-handlers.xml trunk/docs/online/tutorial-doc/en/modules/headers-handlers/handlers.xml trunk/docs/online/tutorial-doc/en/modules/headers-handlers/headers-handlers.xml trunk/docs/online/tutorial-doc/en/modules/headers-handlers/headers.xml trunk/docs/online/tutorial-doc/en/modules/holders/ trunk/docs/online/tutorial-doc/en/modules/holders/inout-parameters.xml trunk/docs/online/tutorial-doc/en/modules/installation/ trunk/docs/online/tutorial-doc/en/modules/installation/install-jboss.xml trunk/docs/online/tutorial-doc/en/modules/installation/install-tomcat.xml trunk/docs/online/tutorial-doc/en/modules/installation/installation.xml trunk/docs/online/tutorial-doc/en/modules/introduction.xml trunk/docs/online/tutorial-doc/en/modules/jmstransport/ trunk/docs/online/tutorial-doc/en/modules/jmstransport/jms-client.xml trunk/docs/online/tutorial-doc/en/modules/jmstransport/jms-endpoint.xml trunk/docs/online/tutorial-doc/en/modules/jmstransport/jms-transport.xml trunk/docs/online/tutorial-doc/en/modules/mtom-xop/ trunk/docs/online/tutorial-doc/en/modules/mtom-xop/mtom-xop.xml trunk/docs/online/tutorial-doc/en/modules/oneway/ trunk/docs/online/tutorial-doc/en/modules/oneway/oneway.xml trunk/docs/online/tutorial-doc/en/modules/secureejb/ trunk/docs/online/tutorial-doc/en/modules/secureejb/secure-ejb.xml trunk/docs/online/tutorial-doc/en/modules/wsaddressing/ trunk/docs/online/tutorial-doc/en/modules/wsaddressing/wsaddressing.xml trunk/docs/online/tutorial-doc/en/modules/wseventing/ trunk/docs/online/tutorial-doc/en/modules/wseventing/wseventing.xml trunk/docs/online/tutorial-doc/en/modules/wssecurity/ trunk/docs/online/tutorial-doc/en/modules/wssecurity/wssecurity.xml trunk/docs/online/tutorial-doc/en/modules/wstransaction/ trunk/docs/online/tutorial-doc/en/modules/wstransaction/wstransaction.xml trunk/docs/online/tutorial-doc/en/modules/xmlregistry/ trunk/docs/online/tutorial-doc/en/modules/xmlregistry/xmlregistry.xml trunk/docs/online/tutorial-src/ trunk/docs/online/tutorial-src/jax-ws-hello-world/ trunk/docs/online/tutorial-src/jax-ws-hello-world/build.xml trunk/docs/online/tutorial-src/jax-ws-hello-world/classes/ trunk/docs/online/tutorial-src/jax-ws-hello-world/log4j.xml trunk/docs/online/tutorial-src/jax-ws-hello-world/resources/ trunk/docs/online/tutorial-src/jax-ws-hello-world/resources/wstools-config.xml trunk/docs/online/tutorial-src/jax-ws-hello-world/src/ trunk/docs/online/tutorial-src/jax-ws-hello-world/src/java/ trunk/docs/online/tutorial-src/jax-ws-hello-world/src/java/org/ trunk/docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/ trunk/docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/samples/ trunk/docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/samples/helloworld/ trunk/docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/samples/helloworld/EndpointInterface.java trunk/docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/samples/helloworld/HelloWorldWS.java trunk/docs/online/tutorial-src/jax-ws-hello-world/src/metadata/ trunk/docs/online/tutorial-src/jax-ws-hello-world/src/metadata/web.xml Log: Added: trunk/docs/online/tutorial-doc/build-docbook.xml =================================================================== --- trunk/docs/online/tutorial-doc/build-docbook.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/build-docbook.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,14 @@ +<project name="Documentation" default="all.doc" basedir="."> + + <property name="pdf.name" value="jbossws-userguide.pdf"/> + <property name="doc.module.home" value="."/> + + <import file="${docbook-support.home}/support.xml"/> + + <target name="all.doc" depends="clean"> + <antcall target="lang.all"> + <param name="lang" value="en"/> + </antcall> + </target> + +</project> Added: trunk/docs/online/tutorial-doc/build.xml =================================================================== --- trunk/docs/online/tutorial-doc/build.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/build.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,49 @@ +<project name="Documentation" default="all.doc" basedir="."> + + <property name="docbook-support.home" value="../../docbook-support"/> + <property name="doc.module.home" value="."/> + + <available property="docbook-support.available" file="${docbook-support.home}/support.xml"/> + + <!-- Setup the build timestamp & build identifer properties --> + <property file="../../../version.properties"/> + <tstamp> + <format property="build.date" pattern="dd-MMM-yyyy"/> + </tstamp> + <tstamp> + <format property="build.id" pattern="yyyyMMddHHmm"/> + </tstamp> + + <!-- all.doc --> + <target name="all.doc" depends="get-docbook-support, copy-templates"> + <ant antfile="${doc.module.home}/build-docbook.xml" inheritall="false"> + <property name="docbook-support.home" value="${docbook-support.home}"/> + </ant> + <copy todir="build/en" file="../../../src/main/resources/dist/Install.txt" filtering="yes" overwrite="yes"> + <filterset> + <filtersfile file="../../../version.properties"/> + </filterset> + </copy> + </target> + + <!-- get-docbook-support --> + <target name="get-docbook-support" unless="docbook-support.available"> + <echo>Export docbook-support to ${docbook-support.home}/..</echo> + <cvs command="export -r HEAD" + cvsRoot=":pserver:anonymous:@anoncvs.forge.jboss.com:/cvsroot/jboss" + package="docbook-support" + dest="${docbook-support.home}/.." + failonerror="true"/> + </target> + + <!-- copy-templates --> + <target name="copy-templates"> + <copy tofile="en/master.xml" file="en/master.template" filtering="yes" overwrite="yes"> + <filterset> + <filter token="build.date" value="${build.date}"/> + <filtersfile file="../../../version.properties"/> + </filterset> + </copy> + </target> + +</project> Added: trunk/docs/online/tutorial-doc/en/images/EventingCollaboration.gif =================================================================== (Binary files differ) Property changes on: trunk/docs/online/tutorial-doc/en/images/EventingCollaboration.gif ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/docs/online/tutorial-doc/en/images/readme.txt =================================================================== --- trunk/docs/online/tutorial-doc/en/images/readme.txt 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/images/readme.txt 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1 @@ +This is the directory to store images. Added: trunk/docs/online/tutorial-doc/en/images/wstools-components.png =================================================================== (Binary files differ) Property changes on: trunk/docs/online/tutorial-doc/en/images/wstools-components.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/docs/online/tutorial-doc/en/images/wstools-config.png =================================================================== (Binary files differ) Property changes on: trunk/docs/online/tutorial-doc/en/images/wstools-config.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/docs/online/tutorial-doc/en/master.template =================================================================== --- trunk/docs/online/tutorial-doc/en/master.template 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/master.template 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,104 @@ +<?xml version='1.0' encoding="iso-8859-1"?> + +<!-- $Id: master.xml 118 2006-04-06 14:44:24Z thomas.diesler(a)jboss.com $ --> + +<!DOCTYPE book PUBLIC + "-//OASIS//DTD DocBook XML V4.3CR3//EN" + "../../../docbook-support/support/docbook-dtd/docbookx.dtd" +[ +<!ENTITY ch-introduction SYSTEM "modules/introduction.xml"> +<!ENTITY ch-installation SYSTEM "modules/installation/installation.xml"> +<!ENTITY s-install-jboss SYSTEM "modules/installation/install-jboss.xml"> +<!ENTITY s-install-tomcat SYSTEM "modules/installation/install-tomcat.xml"> +<!ENTITY ch-installation SYSTEM "modules/installation/installation.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-endpoints SYSTEM "modules/endpoints/endpoints.xml"> +<!ENTITY s-jsr109-endpoints SYSTEM "modules/endpoints/jsr109-endpoints.xml"> +<!ENTITY s-jsr109-pojo-endpoint SYSTEM "modules/endpoints/jsr109-pojo-endpoint.xml"> +<!ENTITY s-jsr109-ejb-endpoint SYSTEM "modules/endpoints/jsr109-ejb-endpoint.xml"> +<!ENTITY s-jsr181-endpoints SYSTEM "modules/endpoints/jsr181-endpoints.xml"> +<!ENTITY s-jsr181-pojo-endpoint SYSTEM "modules/endpoints/jsr181-pojo-endpoint.xml"> +<!ENTITY s-jsr181-ejb3-endpoint SYSTEM "modules/endpoints/jsr181-ejb3-endpoint.xml"> +<!ENTITY s-service-lifecycle SYSTEM "modules/endpoints/service-lifecycle.xml"> +<!ENTITY s-templates SYSTEM "modules/endpoints/template-config.xml"> +<!ENTITY ch-clients SYSTEM "modules/clients/clients.xml"> +<!ENTITY s-jsr109-clients SYSTEM "modules/clients/jsr109-clients.xml"> +<!ENTITY s-dii-clients SYSTEM "modules/clients/dii-clients.xml"> +<!ENTITY s-stub-properties SYSTEM "modules/clients/stub-properties.xml"> +<!ENTITY ch-headers-handlers SYSTEM "modules/headers-handlers/headers-handlers.xml"> +<!ENTITY s-headers SYSTEM "modules/headers-handlers/headers.xml"> +<!ENTITY s-handlers SYSTEM "modules/headers-handlers/handlers.xml"> +<!ENTITY s-dynamic-handlers SYSTEM "modules/headers-handlers/dynamic-handlers.xml"> +<!ENTITY ch-holders SYSTEM "modules/holders/inout-parameters.xml"> +<!ENTITY ch-exceptions SYSTEM "modules/exceptions/exceptions.xml"> +<!ENTITY ch-oneway SYSTEM "modules/oneway/oneway.xml"> +<!ENTITY ch-attachments SYSTEM "modules/attachments/attachments.xml"> +<!ENTITY ch-mtom-xop SYSTEM "modules/mtom-xop/mtom-xop.xml"> +<!ENTITY ch-jms-transport SYSTEM "modules/jmstransport/jms-transport.xml"> +<!ENTITY s-jms-endpoint SYSTEM "modules/jmstransport/jms-endpoint.xml"> +<!ENTITY s-jms-client SYSTEM "modules/jmstransport/jms-client.xml"> +<!ENTITY ch-secure-ejb SYSTEM "modules/secureejb/secure-ejb.xml"> +<!ENTITY ch-wssecurity SYSTEM "modules/wssecurity/wssecurity.xml"> +<!ENTITY ch-wsaddressing SYSTEM "modules/wsaddressing/wsaddressing.xml"> +<!ENTITY ch-wseventing SYSTEM "modules/wseventing/wseventing.xml"> +<!ENTITY ch-wstransaction SYSTEM "modules/wstransaction/wstransaction.xml"> +<!ENTITY ch-xmlregistry SYSTEM "modules/xmlregistry/xmlregistry.xml"> +<!ENTITY appendix-a SYSTEM "modules/appendix-a.xml"> +]> + + +<book lang="en"> + + <bookinfo> + <title>JBossWS User Guide</title> + <subtitle&gt;jbossws-@version.id(a)&lt;/subtitle&gt; + <releaseinfo&gt;@build.date(a)&lt;/releaseinfo&gt; + <releaseinfo> + <ulink url="http://labs.jboss.com/jbossws/user-guide/en/html/index.html&quo... Pages]</ulink>, + <ulink url="http://labs.jboss.com/jbossws/user-guide/en/html_single/index.h... Page]</ulink>, + <ulink url="http://labs.jboss.com/jbossws/user-guide/en/pdf/jbossws-usergui... + </releaseinfo> + </bookinfo> + + <toc/> + + <preface id="preface" revision="1"> + <title>Preface</title> + <para> After JBoss J2EE-1.4 certification in Jun/2004 we have decided to develop our + own JAXRPC SOAP stack that fits better in the overall JBoss architecture and is + generally more suiteable for the specific J2EE requirements for web services. + JBossWS is our new implementation of J2EE compatible web services. + This document describes the JBossWS feature set and its usage. + </para> + <para> If you have questions regarding JBossWS, please feel to ask the JBossWS team.</para> + + <para>Web Service Lead - Thomas Diesler</para> + <para>WS-Security, WSTools - Jason Greene</para> + <para>WS-Eventing, Standards - Heiko Braun</para> + + </preface> + + &ch-introduction; + &ch-installation; + &ch-getting-started; + &ch-endpoints; + &ch-clients; + &ch-headers-handlers; + &ch-holders; + &ch-exceptions; + &ch-oneway; + &ch-attachments; + &ch-mtom-xop; + &ch-jms-transport; + &ch-secure-ejb; + &ch-wssecurity; + &ch-wsaddressing; + &ch-wseventing; + &ch-wstransaction; + &ch-xmlregistry; + &appendix-a; + +</book> Added: trunk/docs/online/tutorial-doc/en/modules/appendix-a.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/appendix-a.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/appendix-a.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,30 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: appendix-a.xml 284 2006-05-05 23:26:06Z jason.greene(a)jboss.com $ --> + +<chapter id="appendix-a"> + + <title>Appendix A - Useful links</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://fisheye.jboss.com/viewrep/~raw,r=HEAD/JBossWS/trunk/src/... configuration syntax</ulink></para> + </listitem> + <listitem> + <para><ulink url="http://fisheye.jboss.com/viewrep/~raw,r=HEAD/JBossWS/trunk/src/... configuration syntax</ulink></para> + </listitem> + <listitem> + <para><ulink url="http://fisheye.jboss.com/viewrep/~raw,r=HEAD/JBossWS/trunk/src/... configuration syntax</ulink></para> + </listitem> + <listitem> + <para><ulink url="http://java.sun.com/developer/technicalArticles/xml/jaxrpcpatte... and Strategies for Building Document-Based Web Services</ulink></para> + </listitem> + <listitem> + <para><ulink url="http://www-128.ibm.com/developerworks/webservices/library/ws-wh... style of WSDL should I use?</ulink></para> + </listitem> + <listitem> + <para><ulink url="http://www.jcp.org/en/jsr/detail?id=181">Web Service Metadata (JSR-181)</ulink></para> + </listitem> + </itemizedlist> + +</chapter> Added: trunk/docs/online/tutorial-doc/en/modules/attachments/attachments.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/attachments/attachments.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/attachments/attachments.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,242 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: attachments.xml 284 2006-05-05 23:26:06Z jason.greene(a)jboss.com $ --> + +<chapter id="attachments"> + + <title>SOAP with Attachments</title> + + <para>This chapter describes SOAP with Attachments. JBossWS conform to the + <ulink url="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0.html"&... AttachmentsProfile-1.0</ulink> + </para> + + <para> + <table frame="all"> + <title>MIME mapping required by JAXRPC-1.1</title> + <tgroup cols="2"> + <tbody> + <row> + <entry>image/gif</entry> + <entry>java.awt.Image</entry> + </row> + <row> + <entry>image/jpeg</entry> + <entry>java.awt.Image</entry> + </row> + <row> + <entry>text/plain</entry> + <entry>java.lang.String</entry> + </row> + <row> + <entry>multipart/*</entry> + <entry>javax.mail.internet.MimeMultipart</entry> + </row> + <row> + <entry>text/xml</entry> + <entry>javax.xml.transform.Source</entry> + </row> + <row> + <entry>application/xml</entry> + <entry>javax.xml.transform.Source</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + + <para>The sample code uses the following service endpoint interface</para> + + <para> + <programlisting><![CDATA[ + public interface Attachment extends Remote + { + /** Service endpoint method for image/gif */ + String sendMimeImageGIF(String message, Object mimepart) throws RemoteException; + + /** Service endpoint method for image/jpeg */ + String sendMimeImageJPEG(String message, Image mimepart) throws RemoteException; + + /** Service endpoint method for text/plain */ + String sendMimeTextPlain(String message, String mimepart) throws RemoteException; + + /** Service endpoint method for multipart/* */ + String sendMimeMultipart(String message, MimeMultipart mimepart) throws RemoteException; + + /** Service endpoint method for text/xml */ + String sendMimeTextXML(String message, Object mimepart) throws RemoteException; + + /** Service endpoint method for application/xml */ + String sendMimeApplicationXML(String message, Source mimepart) throws RemoteException; + } + ]]></programlisting></para> + + <para><command>Generating required deployment artifacts</command></para> + + <para>Run wstools with the following configuration</para> + + <para> + <programlisting><![CDATA[ + ]]> + + <ulink url="http://jira.jboss.org/jira/browse/JBWS-700">FIXME: JBWS-700</ulink> + </programlisting></para> + + <para>WSTools does generate message parts of type xsd:hexBinary and the associated mime bindings</para> + + <para> + <programlisting><![CDATA[ + <message name="Attachment_sendMimeImageGIF"> + <part name="message" type="xsd:string"/> + <part name="mimepart" type="xsd:hexBinary"/> + </message> + + <binding name="AttachmentBinding" type="tns:Attachment"> + <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"/> + <operation name="sendMimeImageGIF"> + <soap:operation soapAction=""/> + <input> + <mime:multipartRelated> + <mime:part> + <soap:body part="message" use="literal" + namespace="http://org.jboss.ws/samples/swa"/> + </mime:part> + <mime:part> + <mime:content part="mimepart" type="image/gif"/> + </mime:part> + </mime:multipartRelated> + </input> + <output> + <soap:body use="literal" namespace="http://org.jboss.ws/samples/swa"/> + </output> + </operation> + ... + </binding> + ]]></programlisting></para> + + <sect1> + <title>Access attachments on the server side</title> + + <para> + Your endpoint bean may access the attachment parts using the standard SAAJ API: + <programlisting><![CDATA[ + ServletEndpointContext context = + (ServletEndpointContext)ctxWhichIsSetIn_ServiceLifecycle_init; + + SOAPMessageContext msgContext = (SOAPMessageContext)context.getMessageContext(); + SOAPMessage soapMessage = msgContext.getMessage(); + + Iterator attachments = soapMessage.getAttachments(); + if (attachments.hasNext()) + { + AttachmentPart ap = (AttachmentPart)attachments.next(); + String contentType = ap.getContentType(); + + if (expContentType.equals("multipart/*")) + { + MimeMultipart mmp = (MimeMultipart)ap.getContent(); + int mmpCount = mmp.getCount(); + for (int i = 0; i < mmpCount; i++) + { + BodyPart bp = mmp.getBodyPart(i); + String bpct = bp.getContentType(); + Object bpc = bp.getContent(); + ... + } + } + else if (expContentType.equals("image/gif")) + { + Image image = (Image)ap.getContent(); + ... + } + else + { + ... + } + } + ]]></programlisting> + </para> + </sect1> + + <sect1> + <title>Sending an attachment from a DII client</title> + + <para> + To send an image, we can use the standard DII API and make use of the Java activation framework. From the JavaDoc for DataHandler: + </para> + + <para> + <emphasis>The DataHandler class provides a consistent interface to data available in many different sources and formats. + It manages simple stream to string conversions and related operations using DataContentHandlers.</emphasis> + </para> + + <para> + <programlisting><![CDATA[ + ServiceFactory factory = ServiceFactory.newInstance(); + Service service = factory.createService(SERVICE_NAME); + + Call call = service.createCall(PORT_NAME, new QName(NS_URI, rpcMethodName)); + call.addParameter("message", Constants.XSD_STRING, ParameterMode.IN); + call.addParameter("mimepart", Constants.MIME_IMAGE, ParameterMode.IN); + call.setReturnType(Constants.XSD_STRING); + call.setTargetEndpointAddress("http://" + getServerHost() + ":8080/ws4ee-attachment"); + + URL url = new File("resources/webservice/attachment/attach.gif").toURL(); + + String message = "Some text message"; + String value = (String)call.invoke(new Object[]{message, new DataHandler(url)}); + + System.out.println(value); + ]]></programlisting> + </para> + </sect1> + + <sect1> + <title>Building a SOAP multipart message using SAAJ</title> + + <para> + Using the SAAJ API directly, you can also construct a MIME multipart message and send it on the wire without using an JAX-RPC client. + + <programlisting><![CDATA[ + MessageFactory mf = MessageFactory.newInstance(); + + // Create a soap message from the message factory. + SOAPMessage msg = mf.createMessage(); + + // Message creation takes care of creating the SOAPPart + // a required part of the message as per the SOAP 1.1 spec. + SOAPPart sp = msg.getSOAPPart(); + + // Retrieve the envelope from the soap part to start building the soap message. + SOAPEnvelope envelope = sp.getEnvelope(); + + // Create a soap body from the envelope. + SOAPBody bdy = envelope.getBody(); + + // Add a soap body element + SOAPBodyElement sbe = + bdy.addBodyElement(envelope.createName(rpcMethodName, NS_PREFIX, NS_URI)); + + // Add a some child elements + sbe.addChildElement(envelope.createName("message")) + .addTextNode("Some text message"); + sbe.addChildElement(envelope.createName("mimepart")) + .addAttribute(envelope.createName("href"), CID_MIMEPART); + + AttachmentPart ap = msg.createAttachmentPart(new DataHandler(url)); + ap.setContentType("image/gif"); + ap.setContentId(CID_MIMEPART); + + // Add the attachments to the message. + msg.addAttachmentPart(ap); + + SOAPConnectionFactory conFactory = SOAPConnectionFactory.newInstance(); + SOAPConnection con = conFactory.createConnection(); + SOAPMessage resMessage = con.call(msg, new URL("http://" + + getServerHost() + + ":8080/ws4ee-attachment") + ); + ]]></programlisting> + </para> + </sect1> + +</chapter> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/clients/clients.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/clients/clients.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/clients/clients.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,10 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<chapter id="clients"> + <title>Consuming web services</title> + + &s-jsr109-clients; + &s-dii-clients; + &s-stub-properties; +</chapter> + Added: trunk/docs/online/tutorial-doc/en/modules/clients/dii-clients.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/clients/dii-clients.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/clients/dii-clients.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,105 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: dii-clients.xml 506 2006-06-28 14:07:03Z thomas.diesler(a)jboss.com $ --> + +<sect1 id="dii-clients"> + + <title>Dynamic Invocation Interface</title> + + <para><command>An unconfigured DII client</command></para> + + <para>In the case of DII the client sets up the call object manually. This involves setting + the operation name and in/out parameters explicitly. There is no WSDL as abstract + contract for the web service communication involved. Of all the web service client + technologies, this is the least favorable.</para> + + <para> + <programlisting><![CDATA[ + public void testEchoString() throws Exception + { + ServiceFactory factory = ServiceFactory.newInstance(); + Service service = factory.createService(new QName("ANY_SERVICE_NAME")); + + Call call = service.createCall(); + call.setOperationName(new QName(TARGET_NAMESPACE, "echoString")); + call.addParameter("String_1", Constants.TYPE_LITERAL_STRING, ParameterMode.IN); + call.addParameter("String_2", Constants.TYPE_LITERAL_STRING, ParameterMode.IN); + call.setReturnType(Constants.TYPE_LITERAL_STRING); + + call.setTargetEndpointAddress(TARGET_ENDPOINT_ADDRESS); + + String hello = "Hello"; + String world = "world!"; + Object retObj = call.invoke(new Object[]{hello, world}); + assertEquals(hello + world, retObj); + } + ]]></programlisting></para> + + <para><command>A configured DII client</command></para> + + <para>A DII client can be configured from WSDL</para> + + <para> + <programlisting><![CDATA[ + public void testEchoString() throws Exception + { + ServiceFactory factory = ServiceFactory.newInstance(); + URL wsdlLocation = new URL(TARGET_ENDPOINT_ADDRESS + "?wsdl"); + QName serviceName = new QName(TARGET_NAMESPACE, "TestService"); + ServiceImpl service = (ServiceImpl)factory.createService(wsdlLocation, serviceName); + call = service.createCall(); + + QName operationName = new QName(TARGET_NAMESPACE, "echoString"); + call.setOperationName(operationName); + assertFalse(call.isParameterAndReturnSpecRequired(operationName)); + + String hello = "Hello"; + String world = "world!"; + Object retObj = call.invoke(new Object[]{hello, world}); + assertEquals(hello + world, retObj); + } + ]]></programlisting></para> + + <para>Note however, that the above example does not have a notion of JAXRPC mapping. The abstract contract is given as an + URL to the WSDL, but it is not expicitly said how the various types in XML schema map to Java types. It works, because + above we only use strings. It would not work if complex user types were involved. Prior to standard J2EE-1.4 web services + frameworks fell back to Java reflection to provide the mapping meta data. + </para> + + <para>With JSR109 we have a standard mapping metadata format usually provided through jaxrpc-mapping.xml. The name of the + file is however not standardized. Unfortunately the standard JAXRPC API does not accommodate this mapping information because + it predates JSR109. In JBossWS you have the option to use a propriatary API method or rely on autodiscovery of META-INF/jaxrpc-mapping.xml. + </para> + + <para>Here the propriatary API methods that we provide in org.jboss.ws.jaxrpc.ServiceFactoryImpl + </para> + + <para> + <programlisting><![CDATA[ + /** + * Create a <code>Service</code> instance. + * + * @param wsdlURL URL for the WSDL document location + * @param serviceName QName for the service. + * @param mappingURL URL for the jaxrpc-mapping.xml document location + */ + public Service createService(URL wsdlURL, QName serviceName, URL mappingURL) throws ServiceException + { + ... + } + + /** + * Create a <code>Service</code> instance. + * + * @param wsdlURL URL for the WSDL document location + * @param serviceName QName for the service. + * @param mappingURL URL for the jaxrpc-mapping.xml document location + * @param securityURL URL for the jbossws-security.xml file + */ + public Service createService(URL wsdlURL, QName serviceName, URL mappingURL, URL securityURL) throws ServiceException + { + ... + } + ]]></programlisting></para> + +</sect1> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/clients/jsr109-clients.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/clients/jsr109-clients.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/clients/jsr109-clients.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,120 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: jsr109-clients.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $ --> + +<sect1 id="jsr109-clients"> + + <title>JSR-109 Clients</title> + + <para><command>A web service client connecting to an endpoint</command></para> + + <para>The web service client programming model for J2EE is about accessing a remote web service from a J2EE component. + Please remember that with web services the client and the server are fundamentally disconnected. There are server side issues + and client side issues. In other words, if you setup a web service endpoint any client that adhers to the abstract contract + in WSDL can talk to that endpoint. + </para> + <para> + If you want to implement a WS client using JBossWS (to what server impl it talks to does not matter) you use wstools to generate the + WS4EE required artifacts from WSDL. The artifacts are + </para> + + <para> + <itemizedlist> + <listitem> + Required Service Endpoint Interface (SEI) + </listitem> + <listitem> + Optional User Types + </listitem> + <listitem> + Optional User Exceptions + </listitem> + <listitem> + Required WSDL/Java mapping meta data (jaxrpc-mapping.xml) + </listitem> + </itemizedlist> + </para> + + <para>Here a wstools config file that generates the client side artifacts from WSDL</para> + + <para> + <programlisting><![CDATA[ + <configuration ...> + <wsdl-java file="resources/samples/jsr181pojo/META-INF/wsdl/TestService.wsdl"> + <mapping file="jaxrpc-mapping.xml" /> + </wsdl-java> + </configuration> + ]]></programlisting></para> + + <para> + This chapter uses a J2EE-1.4 client, but for all intents and purposes, this could also be + a Servlet, JSP, or EJB component. All of these J2EE components support &lt;service-ref&gt; + elements in their respective deployment descriptor. </para> + + <para> The J2EE client deployment model has many advantages over dynamic invocation (DII). + Most Java applications (except the most trivial ones) have a need for registry lookup (JNDI) and + management (JMX). A very minimal jboss configuration has a tiny footprint and provides just that. + Therefore, running your client app on jboss and mangage it through JMX and have a layer of + indirection for resource lookup through JNDI is recommended pratice. + Additionally, you can leverage the J2EE 1.4 client programming model and obtain preconfigured + web service clients fromJNDI.</para> + + <para> + <programlisting><![CDATA[ + <service-ref> + <service-ref-name>service/TrivialService</service-ref-name> + <service-interface>javax.xml.rpc.Service</service-interface> + <wsdl-file>META-INF/wsdl/SampleService.wsdl</wsdl-file> + <jaxrpc-mapping-file>META-INF/jaxrpc-mapping.xml</jaxrpc-mapping-file> + <port-component-ref> + <service-endpoint-interface> + org.jboss.test.ws.jaxrpc.samples.rpcstyle.TrivialService + </service-endpoint-interface> + </port-component-ref> + </service-ref> + ]]></programlisting></para> + + <para> With the configuration given above, the SampleService.wsdl must contain the correct SOAP target address. + JBoss provides an override mechanism for the WSDL in jboss-client.xml.</para> + + <para> + <programlisting><![CDATA[ + <jboss-client> + <jndi-name>jbossws-client</jndi-name> + <service-ref> + <service-ref-name>service/TrivialService</service-ref-name> + <wsdl-override> + http://jbosstesthost:8080/jbossws-samples-rpcstyle?wsdl + </wsdl-override> + </service-ref> + </jboss-client> + ]]></programlisting></para> + + <para>When the WSDL is obtained from the server, the server has already performed all the necessary address rewrites</para> + + <para> Once the J2EE application client jar is deployed on a JBoss instance, it can be accessed by a separate standalone Java process.</para> + + <para> + <programlisting><![CDATA[ + public void testTrivialAccess() throws Exception + { + InitialContext iniCtx = getInitialContext(); + Service service = (Service)iniCtx.lookup("java:comp/env/service/TrivialService"); + TrivialService port = (TrivialService)service.getPort(TrivialService.class); + String person = "Kermit"; + String product = "Ferrari"; + String status = port.purchase(person, product); + assertEquals("ok" + person + product, status); + } + + protected InitialContext getInitialContext() throws NamingException + { + InitialContext iniCtx = new InitialContext(); + Hashtable env = iniCtx.getEnvironment(); + env.put(Context.URL_PKG_PREFIXES, "org.jboss.naming.client"); + env.put("j2ee.clientName", "jbossws-client"); + return new InitialContext(env); + } + ]]></programlisting></para> + +</sect1> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/clients/stub-properties.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/clients/stub-properties.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/clients/stub-properties.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,64 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<sect1 id="stub-properties"> + <title>Stub properties</title> + + <para><command>Standard JAXRPC Stub properties</command></para> + + <para> + <programlisting><![CDATA[ + /** User name for authentication. */ + public static final String USERNAME_PROPERTY = "javax.xml.rpc.security.auth.username"; + + /** Password for authentication. */ + public static final String PASSWORD_PROPERTY = "javax.xml.rpc.security.auth.password"; + + /** Target service endpoint address. */ + public static final String ENDPOINT_ADDRESS_PROPERTY = "javax.xml.rpc.service.endpoint.address"; + + /** + This boolean property is used by a service client to indicate + whether or not it wants to participate in a session with a service endpoint. + */ + public static final String SESSION_MAINTAIN_PROPERTY = "javax.xml.rpc.session.maintain"; + ]]></programlisting></para> + + <para><command>JBossWS propriatary Stub properties</command></para> + + <para>The propriatary properties are defined in org.jboss.ws.jaxrpc.StubExt</para> + + <para> + <programlisting><![CDATA[ + /** ClientTimeout property: org.jboss.ws.timeout */ + static final String PROPERTY_CLIENT_TIMEOUT = "org.jboss.ws.timeout"; + + /** KeyStore property: org.jboss.ws.keyStore */ + static final String PROPERTY_KEY_STORE = "org.jboss.ws.keyStore"; + + /** KeyStorePassword property: org.jboss.ws.keyStorePassword */ + static final String PROPERTY_KEY_STORE_PASSWORD = "org.jboss.ws.keyStorePassword"; + + /** KeyStoreType property: org.jboss.ws.keyStoreType */ + static final String PROPERTY_KEY_STORE_TYPE = "org.jboss.ws.keyStoreType"; + + /** TrustStore property: org.jboss.ws.trustStore */ + static final String PROPERTY_TRUST_STORE = "org.jboss.ws.trustStore"; + + /** TrustStorePassword property: org.jboss.ws.trustStorePassword */ + static final String PROPERTY_TRUST_STORE_PASSWORD = "org.jboss.ws.trustStorePassword"; + + /** TrustStoreType property: org.jboss.ws.trustStoreType */ + static final String PROPERTY_TRUST_STORE_TYPE = "org.jboss.ws.trustStoreType"; + + /** Authentication type, used to specify basic, etc) */ + static final String PROPERTY_AUTH_TYPE = "org.jboss.ws.authType"; + + /** Authentication type, BASIC */ + static final String PROPERTY_AUTH_TYPE_BASIC = "org.jboss.ws.authType.basic"; + + /** Authentication type, WSEE */ + static final String PROPERTY_AUTH_TYPE_WSSE = "org.jboss.ws.authType.wsse"; + ]]></programlisting></para> + +</sect1> + Added: trunk/docs/online/tutorial-doc/en/modules/endpoints/endpoints.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/endpoints/endpoints.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/endpoints/endpoints.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<chapter id="endpoints"> + <title>Developing web service endpoints</title> + <para> + In the previous chapter we have seen how to package and deploy simple endpoints + that were all based on POJO implementations. If you really want to leverage J2EE technologies + it might be more appropriate to use EJB endpoint implementations. In this chapter we will use EJB-2.1 + and EJB-3.0 stateless session beans and explore the + <ulink url="http://www.jcp.org/en/jsr/detail?id=181">Web Services Metadata specification</ulink>, + which allows you to expose classes as a webservice through the use of JDK 5 annotations. + + </para> + &s-jsr109-endpoints; + &s-jsr181-endpoints; + &s-service-lifecycle; + &s-templates; +</chapter> + Added: trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr109-ejb-endpoint.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr109-ejb-endpoint.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr109-ejb-endpoint.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,69 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: jsr109-ejb-endpoint.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $ --> + +<sect2 id="jsr109-ejb-endpoint"> + + <title>JSR-109 EJB Endpoint</title> + + <para>This chapter uses the same service endpoint interface (SEI) as in + <link linkend="jsr109-pojo-endpoint">JSR-109 POJO Endpoint</link>. + </para> + + <para> + <programlisting><![CDATA[ + public interface JaxRpcTestService extends Remote + { + String echoString(String str1, String str2) throws RemoteException; + + SimpleUserType echoSimpleUserType(String str1, SimpleUserType 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="TestService" style="rpc" + endpoint="org.jboss.test.ws.jaxrpc.samples.jsr109ejb.JaxRpcTestService"/> + + <namespaces target-namespace="http://org.jboss.ws/samples/jsr109ejb" + type-namespace="http://org.jboss.ws/samples/jsr109ejb/types"/> + + <mapping file="jaxrpc-mapping.xml"/> + <webservices ejb-link="TestService"/> + </java-wsdl> + </configuration> + ]]></programlisting></para> + + <para><command>The EJB deployment descriptor</command></para> + <para>The attribute value for ejbLink element corresponds to ejb-name given in ejb-jar.xml. + In this example, the stateless session bean (SLSB) is only exposed as a service endpoint, + it does not have a Home nor Remote interface + <orderedlist> + <listitem><para>Exposing an SEI as a webservice endpoint</para></listitem> + <listitem><para>The SLSB endpoint implementation</para></listitem> + </orderedlist> + </para> + + <para> + <programlisting><![CDATA[ + <enterprise-beans> + <session> + <ejb-name>TestService</ejb-name> + (1) <service-endpoint> + org.jboss.test.ws.jaxrpc.samples.jsr109ejb.JaxRpcTestService + </service-endpoint> + (2) <ejb-class>org.jboss.test.ws.jaxrpc.samples.jsr109ejb.JaxRpcEJBEndpoint</ejb-class> + <session-type>Stateless</session-type> + <transaction-type>Container</transaction-type> + </session> + </enterprise-beans> + ]]></programlisting></para> + +</sect2> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr109-endpoints.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr109-endpoints.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr109-endpoints.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,15 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<sect1 id="jsr109-endpoints"> + <title>JSR-109 Endpoints</title> + <para> + JSR-109 promotes building portable web services in the J2EE 1.4 environment. + It leverages J2EE technologies to provide a standard for developing and deploying web + services on the J2EE platform. + If you already have followed the <link linkend="getting-started">Getting Started Chapter</link> + you can proceed with <link linkend="jsr109-ejb-endpoint">EJB endpoints</link> right away. + </para> + &s-jsr109-pojo-endpoint; + &s-jsr109-ejb-endpoint; +</sect1> + Added: trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr109-pojo-endpoint.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr109-pojo-endpoint.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr109-pojo-endpoint.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,87 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: jsr109-pojo-endpoint.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $ --> + +<sect2 id="jsr109-pojo-endpoint"> + + <title>JSR-109 POJO Endpoint</title> + + <para>This chapter uses a more complex service endpoint interface (SEI) as in <link linkend="doc-endpoints">Document Style Endpoints</link>. + It contains a user defined type as one of the opertion parameters. + </para> + + <para> + <programlisting><![CDATA[ + public interface JaxRpcTestService extends Remote + { + String echoString(String str1, String str2) throws RemoteException; + + SimpleUserType echoSimpleUserType(String str1, SimpleUserType 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="TestService" style="rpc" + endpoint="org.jboss.test.ws.jaxrpc.samples.jsr109pojo.JaxRpcTestService"/> + + <namespaces target-namespace="http://org.jboss.ws/samples/jsr109pojo" + type-namespace="http://org.jboss.ws/samples/jsr109pojo/types"/> + + <mapping file="jaxrpc-mapping.xml"/> + <webservices servlet-link="TestService"/> + </java-wsdl> + </configuration> + ]]></programlisting></para> + + <para>WSTools generates request/response java objects that correspond to these schema + types and that are mapped in jaxrpc-mapping.xml.</para> + + <para><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:echoSimpleUserType xmlns:ns1='http://org.jboss.ws/samples/jsr109pojo'> + <String_1>Hello</String_1> + <SimpleUserType_2> + <a>1</a> + <b>2</b> + </SimpleUserType_2> + </ns1:echoSimpleUserType> + </env:Body> + </env:Envelope> + ]]></programlisting></para> + + <para> + <programlisting><![CDATA[ + Outgoing SOAPMessage + + <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'> + <env:Header/> + <env:Body> + <ns1:echoSimpleUserTypeResponse xmlns:ns1='http://org.jboss.ws/samples/jsr109pojo'> + <result> + <a>1</a> + <b>2</b> + </result> + </ns1:echoSimpleUserTypeResponse> + </env:Body> + </env:Envelope> + ]]></programlisting></para> + + +</sect2> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr181-ejb3-endpoint.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr181-ejb3-endpoint.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr181-ejb3-endpoint.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: jsr181-ejb3-endpoint.xml 284 2006-05-05 23:26:06Z jason.greene(a)jboss.com $ --> + +<sect2 id="jsr181-ejb3-endpoint"> + + <title>JSR-181 EJB Endpoint</title> + + <para>EJB endpoints that use the <ulink url="http://www.jcp.org/en/jsr/detail?id=181">JSR-181 Web Services Metadata</ulink> + programming model support the same set of JSR-181 annotations as <link linkend="jsr181-pojo-endpoint">JSR-181 POJO Endpoint</link>. + JBossWS supports JSR-181 annotations on EJB-2.1 and EJB-3.0 stateless session beans. + </para> + + <para> + <programlisting><![CDATA[ + @WebService(name = "EndpointInterface", + targetNamespace = "http://org.jboss.ws/samples/jsr181ejb", + serviceName = "TestService") + + @SOAPBinding(style = SOAPBinding.Style.RPC) + + @Stateless + @Remote(EJB3RemoteInterface.class) + @RemoteBinding(jndiBinding = "/ejb3/EJB3EndpointInterface") + public class EJB3Bean01 implements EJB3RemoteInterface + { + @WebMethod + public String echo(String input) + { + return input; + } + } + ]]></programlisting></para> + + <para>Above you see an EJB-3.0 stateless session bean that exposes one method both on the remote + interface and on and as an endpoint operation. + </para> + + <para><command>Packaging the endpoint</command></para> + + <para>A JSR-181 EJB service endpoint is packaged as an ordinary ejb deployment. </para> + + <para> + <programlisting><![CDATA[ + <jar jarfile="${build.dir}/libs/jbossws-samples-jsr181ejb.ejb3"> + <fileset dir="${build.dir}/classes"> + <include name="org/jboss/test/ws/samples/jsr181ejb/EJB3Bean01.class"/> + <include name="org/jboss/test/ws/samples/jsr181ejb/EJB3RemoteInterface.class"/> + </fileset> + </jar> + ]]></programlisting></para> + + <para>Generating the client side artifacts and the SOAP message exchange are equivalent to <link linkend="jsr181-pojo-endpoint">JSR-181 POJO Endpoints</link></para> + +</sect2> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr181-endpoints.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr181-endpoints.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr181-endpoints.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,18 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<sect1 id="jsr181-endpoints"> + + <title>JSR-181 Endpoints</title> + + <para> The web service metadata specification reduces the amount of information required to setup a web service a great deal. + Service operations and attributes are specified declaratively by + annotating java source files that implement your web service. </para> + + <tip> + <para> Please consult the + <ulink url="http://www.jcp.org/en/jsr/detail?id=181">JSR-181 specification</ulink> for a complete list of all supported annotations. </para> + </tip> + + &s-jsr181-pojo-endpoint; + &s-jsr181-ejb3-endpoint; +</sect1> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr181-pojo-endpoint.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr181-pojo-endpoint.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/endpoints/jsr181-pojo-endpoint.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,130 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: jsr181-pojo-endpoint.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $ --> + +<sect2 id="jsr181-pojo-endpoint"> + + <title>JSR-181 POJO Endpoint</title> + + <para> + Let's take alook at simple POJO endpoint implementation. + All endpoint associated metadata is provided via JSR-181 annotations: + </para> + + <para> + <programlisting><![CDATA[ + @WebService( + name = "EndpointInterface", + targetNamespace = "http://org.jboss.ws/samples/jsr181pojo", + serviceName = "TestService") + @SOAPBinding(style = SOAPBinding.Style.RPC) + public class JSEBean01 + { + @WebMethod + public String echo(String input) + { + return input; + } + } + ]]></programlisting></para> + + <para>Strictly speaking you only need the @WebService and @WebMethod annotations without any parameters. + Everything else has sensible defaults and is provided here mainly for more control over WSDL generation. + The service endpoint interface is optional. If given, the JSR-181 annotations must be set on the service endpoint interface. + </para> + + <para><command> The endpoint as a web application</command></para> + + <para>A JSR-181 java service endpoint is deployed as a web application. This is equivalent to <link linkend="rpc-endpoints">JSR-109 Style Endpoints</link>. + + </para> + + <para> + <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>TestService</servlet-name> + <servlet-class>org.jboss.test.ws.jaxws.samples.jsr181pojo.JSEBean01</servlet-class> + </servlet> + + <servlet-mapping> + <servlet-name>TestService</servlet-name> + <url-pattern>/*</url-pattern> + </servlet-mapping> + + </web-app> + ]]></programlisting></para> + + <para><command>Packaging the endpoint</command></para> + + <para>A JSR-181 java service endpoint (JSE) is packaged as a web application in a *.war file. </para> + + <para> + <programlisting><![CDATA[ + <war warfile="${build.dir}/libs/jbossws-samples-jsr181pojo.war" + webxml="${build.resources.dir}/samples/jsr181pojo/WEB-INF/web.xml"> + <classes dir="${build.dir}/classes"> + <include name="org/jboss/test/ws/samples/jsr181pojo/JSEBean01.class"/> + </classes> + </war> + ]]></programlisting></para> + + <para>Note, only the endpoint implementation bean and web.xml are required.</para> + + <para><command>Generating the client side artifacts</command></para> + + <para>Run wstools with the following configuration</para> + + <para> + <programlisting><![CDATA[ + <configuration ...> + <wsdl-java file="resources/samples/jsr181pojo/META-INF/wsdl/TestService.wsdl"> + <mapping file="jaxrpc-mapping.xml" /> + </wsdl-java> + </configuration> + ]]> + <ulink url="http://jira.jboss.org/jira/browse/JBWS-701">FIXME: JBWS-701</ulink> + </programlisting></para> + + <para>WSTools generates the service endpoint interface and the mapping file</para> + + <para>How a J2EE-1.4 protable 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:echo xmlns:ns1='http://org.jboss.ws/samples/jsr181pojo'> + <String_1>Hello world!</String_1> + </ns1:echo> + </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:echoResponse xmlns:ns1='http://org.jboss.ws/samples/jsr181pojo'> + <result>Hello world!</result> + </ns1:echoResponse> + </env:Body> + </env:Envelope> + ]]></programlisting></para> + +</sect2> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/endpoints/service-lifecycle.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/endpoints/service-lifecycle.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/endpoints/service-lifecycle.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,54 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<sect1 id="service-lifecycle"> + + <title>Service Lifecycle and MessageContext</title> + + <para><command>Adding Service Lifecycle</command></para> + + <para>Your POJO endpoint may implement javax.xml.rpc.server.ServiceLifecycle to + obtain access to the javax.xml.rpc.server.ServletEndpointContext int the init() method.</para> + + <para>The ServletEndpointContext provides an endpoint context maintained by the underlying + servlet container based JAX-RPC runtime system. For service endpoints + deployed on a servlet container based JAX-RPC runtime system, the context + parameter in the ServiceLifecycle.init method is required to be of the Java + type javax.xml.rpc.server.ServletEndpointContext.</para> + + <para>A servlet container based JAX-RPC runtime system implements the + ServletEndpointContext interface. The JAX-RPC runtime system is required to + provide appropriate session, message context, servlet context and user + principal information per method invocation on the endpoint class.</para> + + <para> + <programlisting><![CDATA[ + public class JaxRpcJSEEndpoint implements JaxRpcTestService, ServiceLifecycle + { + ... + + private ServletEndpointContext context; + + public String echoString(String str1, String str2) + { + log.info("echoString: " + str1 + "," + str2); + log.info("userPricipal: " + context.getUserPrincipal()); + return str1 + str2; + } + + public void init(Object context) throws ServiceException + { + this.context = (ServletEndpointContext)context; + } + + public void destroy() + { + } + } + ]]></programlisting></para> + + <para>Currently, POJO endpoints are not pooled like their EJB counterparts. As a consequence + and because WS4EE endpoints are essentially stateless, you will get a new instance of the endpoint + implementation bean for every request. For stateful behaviour see <link linkend="wsaddressing">WS-Addressing</link>. + </para> +</sect1> + Added: trunk/docs/online/tutorial-doc/en/modules/endpoints/template-config.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/endpoints/template-config.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/endpoints/template-config.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,101 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<sect1 id="template-config"> + + <title>Endpoint configuration templates</title> + <para> + + Configuration templates provide a convenient way to setup a handler configuration for JBossWS endpoints. + A configuration basically includes a list of <link linkend="handlers">JAXRPC handlers</link> that are + registered with a web service endpoint upon deployment. + + <programlisting><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> + +<jbossws-config xmlns="urn:jboss:jbossws-config:5.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:j2ee="http://java.sun.com/xml/ns/j2ee" + xsi:schemaLocation="urn:jboss:jbossws-config:5.0 http://www.jboss.com/xml/jbossws-config_1_0.xsd"> + + <endpoint-config> + <config-name>Standard Endpoint</config-name> + </endpoint-config> + + <endpoint-config> + <config-name>Standard Secure Endpoint</config-name> + <pre-handler-chain> + <handler-chain-name>PreHandlerChain</handler-chain-name> + <handler> + <j2ee:handler-name>WSSecurityHandlerInbound</j2ee:handler-name> + <j2ee:handler-class>org.jboss.ws.wsse.WSSecurityHandlerInbound</j2ee:handler-class> + </handler> + </pre-handler-chain> + </endpoint-config> + +</jbossws-config> + ]]></programlisting> + + </para> + + <para> + These template configurations can be referenced from any jboss specific deplyoment descriptor, i.e: + + <programlisting><![CDATA[ + <jboss-client> + <jndi-name>jbossws-client</jndi-name> + + <service-ref> + <service-ref-name>service/HelloService</service-ref-name> + (1) <config-name>Standard Secure Client</config-name> + <wsdl-override>http://@jbosstest.host.name@:8080/jbossws-samples-wssecurity-encrypt?wsdl</wsdl-override> + </service-ref> + + </jboss-client> + ]]></programlisting> + + <orderedlist> + <listitem> + <para> + An example configuration reference from a client deployment descriptor. + </para> + </listitem> + </orderedlist> + + + <note> + <para>This is a proprietary configuration mechanism. + In order to stay portable it's recommended to use the default JAXRPC handler configuration.</para> + </note> + + </para> + + <para> + <command>Configuration reference from web.xml</command> + <para> + Within web.xml the same approach can be taken, with the difference that it uses a predefined servlet context + parameter (1) to specfiy the chosen endpoint config (2): + + <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"> + + <context-param> + (1) <param-name>jbossws-config-name</param-name>> + (2) <param-value>Standard Secure Endpoint</param-value> + </context-param> + + <servlet> + <servlet-name>HelloService</servlet-name> + <servlet-class>org.jboss.test.ws.jaxrpc.samples.wssecurity.HelloJavaBean</servlet-class> + </servlet> + <servlet-mapping> + <servlet-name>HelloService</servlet-name> + <url-pattern>/*</url-pattern> + </servlet-mapping> +</web-app> ]]></programlisting> + </para> + </para> + +</sect1> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/exceptions/exceptions.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/exceptions/exceptions.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/exceptions/exceptions.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,193 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: exceptions.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $ --> + +<chapter id="exceptions"> + + <title>Custom Exceptions</title> + + <para> Custom exceptions in JAXRPC are about definig SOAP faults in your abstract + contract and mapping them to java exceptions. The SOAP message contains a + &lt;soap:fault&gt; element that contains information about the cause of the fault. + Java specifics like stack traces, exception class names, etc. are usually not + transported because they maybe meaningless to the non-java receiver. </para> + + <para> A good article about + <ulink url="http://www-128.ibm.com/developerworks/xml/library/ws-tip-jaxrpc... + Exception Handling with JAX-RPC</ulink> can be found at IBM's developerworks. + </para> + + <para> + Lets use a service endpoint interface (SEI) that throws various user exception + </para> + + <para> + <programlisting><![CDATA[ + public interface ExceptionServiceInterface extends Remote + { + void throwException() + throws UserException, RemoteException; + + void throwExceptionWithMessage(String message) + throws UserMessageException, RemoteException; + + void throwComplexUserException(String message, int code) + throws ComplexUserException, RemoteException; + + void throwComplexUserArrayException(String message, int[] code) + throws ComplexUserArrayException, RemoteException; + } + ]]></programlisting></para> + + <para><command>Generating required deployment artifacts</command></para> + + <para>Run wstools with the following configuration</para> + + <para> + <programlisting><![CDATA[ + <configuration ...> + <java-wsdl> + <service name="ExceptionService" style="rpc" + endpoint="org.jboss.test.ws.jaxrpc.samples.exception.ExceptionServiceInterface"/> + + <namespaces target-namespace="http://org.jboss.ws/samples/exception" + type-namespace="http://org.jboss.ws/samples/exception/types"/> + + <mapping file="jaxrpc-mapping.xml"/> + <webservices ejb-link="ExceptionBean"/> + </java-wsdl> + </configuration> + ]]></programlisting></para> + + <para>wstools produces the following abstract contract (WSDL)</para> + + <para> + <programlisting><![CDATA[ + <definitions targetNamespace='http://org.jboss.ws/samples/exception' ...> + ... + <portType name='ExceptionServiceInterface'> + <operation name='throwComplexUserArrayException'> + ... + <fault message='tns:ComplexUserArrayException'/> + </operation> + <operation name='throwComplexUserException'> + ... + <fault message='tns:ComplexUserException' name='ComplexUserException'/> + </operation> + <operation name='throwException'> + ... + <fault message='tns:UserException' name='UserException'/> + </operation> + <operation name='throwExceptionWithMessage'> + ... + <fault message='tns:UserMessageException' name='UserMessageException'/> + </operation> + </portType> + ... + </definitions> + ]]></programlisting></para> + + <para> + Note the various fault elements and how they are linked to XML schema complex + types. The WSDL does not contain any information about the java mapping. This is + defined in jaxrpc-maping.xml, for which I will only show the exception relevant + parts. </para> + + <para> + <programlisting><![CDATA[ + <exception-mapping> + <exception-type>org.jboss.test.ws.jaxrpc.samples.exception.UserException</exception-type> + <wsdl-message>exMsgNS:UserException</wsdl-message> + </exception-mapping> + <exception-mapping> + <exception-type>org.jboss.test.ws.jaxrpc.samples.exception.UserMessageException</exception-type> + <wsdl-message>exMsgNS:UserMessageException</wsdl-message> + <constructor-parameter-order> + <element-name>message</element-name> + </constructor-parameter-order> + </exception-mapping> + <exception-mapping> + <exception-type>org.jboss.test.ws.jaxrpc.samples.exception.ComplexUserException</exception-type> + <wsdl-message>exMsgNS:ComplexUserException</wsdl-message> + <constructor-parameter-order> + <element-name>message</element-name> + <element-name>errorCode</element-name> + </constructor-parameter-order> + </exception-mapping> + <exception-mapping> + <exception-type>org.jboss.test.ws.jaxrpc.samples.exception.ComplexUserArrayException</exception-type> + <wsdl-message>exMsgNS:ComplexUserArrayException</wsdl-message> + <constructor-parameter-order> + <element-name>message</element-name> + <element-name>errorCodes</element-name> + </constructor-parameter-order> + </exception-mapping> + ]]></programlisting></para> + + <para><command>SOAP message exchange</command></para> + + <para> Here some SOAP messages as they would appear on the wire </para> + + <para> + <programlisting><![CDATA[ + <soapenv:Envelope ...> + <soapenv:Body> + <soapenv:Fault> + <faultcode>soapenv:Client</faultcode> + <faultstring>org.jboss.test.webservice.exception.UserException</faultstring> + <detail> + <ns1:UserException xmlns:ns1="http://org.jboss.webservice/exception/types"> + <message xsi:nil="1"/> + </ns1:UserException> + </detail> + </soapenv:Fault> + </soapenv:Body> + </soapenv:Envelope> + + <soapenv:Envelope ...> + <soapenv:Body> + <soapenv:Fault> + <faultcode>soapenv:Client</faultcode> + <faultstring>Don't worry it's just a test</faultstring> + <detail> + <ns1:UserMessageException xmlns:ns1="http://org.jboss.webservice/exception/types"> + <message>Don't worry it's just a test</message> + </ns1:UserMessageException> + </detail> + </soapenv:Fault> + </soapenv:Body> + </soapenv:Envelope> + + <soapenv:Envelope ...> + <soapenv:Body> + <soapenv:Fault> + <faultcode>soapenv:Client</faultcode> + <faultstring>Don't worry it's just a test</faultstring> + <detail> + <ns1:ComplexUserException xmlns:ns1="http://org.jboss.webservice/exception/types"> + <message>Don't worry it's just a test</message> + <errorCode>200</errorCode> + </ns1:ComplexUserException> + </detail> + </soapenv:Fault> + </soapenv:Body> + </soapenv:Envelope> + + <soapenv:Envelope ...> + <soapenv:Body> + <soapenv:Fault> + <faultcode>soapenv:Client</faultcode> + <faultstring>Don't worry it's just a test</faultstring> + <detail> + <ns1:ComplexUserArrayException xmlns:ns1="http://org.jboss.webservice/exception/types"> + <message>Don't worry it's just a test</message> + <errorCodes>100</errorCodes> + <errorCodes>200</errorCodes> + </ns1:ComplexUserArrayException> + </detail> + </soapenv:Fault> + </soapenv:Body> + </soapenv:Envelope> + ]]></programlisting></para> + +</chapter> \ No newline at end of file Property changes on: trunk/docs/online/tutorial-doc/en/modules/exceptions/exceptions.xml ___________________________________________________________________ Name: svn:executable + * Added: trunk/docs/online/tutorial-doc/en/modules/getting-started/doc-endpoints.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/getting-started/doc-endpoints.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/getting-started/doc-endpoints.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -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/docs/online/tutorial-doc/en/modules/getting-started/getting-started.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/getting-started/getting-started.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/getting-started/getting-started.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -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/docs/online/tutorial-doc/en/modules/getting-started/message-endpoints.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/getting-started/message-endpoints.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/getting-started/message-endpoints.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -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/docs/online/tutorial-doc/en/modules/getting-started/rpc-endpoints.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/getting-started/rpc-endpoints.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/getting-started/rpc-endpoints.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -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/docs/online/tutorial-doc/en/modules/headers-handlers/dynamic-handlers.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/headers-handlers/dynamic-handlers.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/headers-handlers/dynamic-handlers.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,90 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: dynamic-handlers.xml 284 2006-05-05 23:26:06Z jason.greene(a)jboss.com $ --> + +<sect1 id="dynamic-handlers"> + + <title>Dynamic JAXRPC Handlers</title> + + <para><command>Modifying the client side handler chain dynamically</command></para> + + <para>The JSR-109 specification does not allow access to the HandlerRegistry that is associated with the + Service object. JBossWS extends the Service interface to provide full access to the handler chains. + There can be one handler chain per service port.</para> + + <para> + <programlisting><![CDATA[ + public void testRemoveServerHandlers() throws Exception + { + MBeanServerConnection server = getServer(); + ObjectName oname = ObjectNameFactory.create("jboss.ws:service=ServiceEndpointManager"); + ObjectName serviceID = new ObjectName("jboss.ws:di=jbossws-samples-dynamichandler.war," + + "service=TestService,port=HandlerTestServicePort"); + + List<HandlerInfo> infos = (List<HandlerInfo>) + server.invoke(oname, "getHandlerInfos", + new Object[]{serviceID}, new String[]{"javax.management.ObjectName"}); + + Iterator<HandlerInfo> it = infos.iterator(); + while (it.hasNext()) + { + HandlerInfo info = it.next(); + if (info.getHandlerClass() == ServerSideHandler.class) + it.remove(); + } + + server.invoke(oname, "stopServiceEndpoint", new Object[]{serviceID}, + new String[]{"javax.management.ObjectName"}); + + server.invoke(oname, "setHandlerInfos", new Object[]{serviceID, infos}, + new String[]{"javax.management.ObjectName", "java.util.List"}); + + server.invoke(oname, "startServiceEndpoint", new Object[]{serviceID}, + new String[]{"javax.management.ObjectName"}); + + String res = endpoint.testHandlers("InitalMessage"); + assertEquals("InitalMessage", res); + } + ]]></programlisting></para> + + <para><command>Modifying the server side handler chain dynamically</command></para> + + <para>JAXRPC-1.1 does not provide access to the service endpoint handler chain. + JBossWS provides full access to the handler chains through the ServiceEndpointManager. + The ServiceEndpointManager is an MBean that manages all service endpoints deployed to the server.</para> + + <para> + <programlisting><![CDATA[ + public void testRemoveServerHandlers() throws Exception + { + MBeanServerConnection server = getServer(); + ObjectName oname = ObjectNameFactory.create("jboss.ws:service=ServiceEndpointManager"); + String serviceID = + "jbossws-samples-dynamichandler.war#TestService/HandlerTestServicePort"; + + List<HandlerInfo> infos = (List<HandlerInfo>) + server.invoke(oname, "getHandlerInfos", + new Object[]{serviceID}, new String[]{"java.lang.String"} + ); + Iterator<HandlerInfo> it = infos.iterator(); + while (it.hasNext()) + { + HandlerInfo info = it.next(); + if (info.getHandlerClass() == ServerSideHandler.class) + it.remove(); + } + server.invoke(oname, "stopServiceEndpoint", + new Object[]{serviceID}, new String[]{"java.lang.String"}); + + server.invoke(oname, "setHandlerInfos", new Object[]{serviceID, infos}, + new String[]{"java.lang.String", "java.util.List"}); + + server.invoke(oname, "startServiceEndpoint", + new Object[]{serviceID}, new String[]{"java.lang.String"}); + + String res = endpoint.testHandlers("InitalMessage"); + assertEquals("InitalMessage", res); + } + ]]></programlisting></para> + +</sect1> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/headers-handlers/handlers.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/headers-handlers/handlers.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/headers-handlers/handlers.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,153 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: handlers.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $ --> + +<sect1 id="handlers"> + + <title>Message handler</title> + + <para> + JAX-RPC handler provide a convinient solution to intercept SOAP message processing + both inbound and outbound on the client and the server side: + </para> + + <para> + <programlisting><![CDATA[ + package javax.xml.rpc.handler; + public interface Handler + { + boolean handleRequest(MessageContext context); + + boolean handleResponse(MessageContext context); + + boolean handleFault(MessageContext context); + } + ]]></programlisting></para> + + <para>A Handler implementation class is required to provide a default constructor. The methods handleRequest and handleResponse perform the actual processing work for a handler. The method handleRequest processes the request SOAP message, while the method handleResponse processes the response SOAP message. The method handleFault performs the SOAP fault processing. + The MessageContext parameter provides access to the message context (for example: a SOAP message that carries an RPC request or response) that is processed by a handler.</para> + + <para> + In the following chapter we will implement a simple JAX-RPC handler and see how to configure the + handler chain for JSR-109 clients and web service endpoints. + </para> + + <para>Run wstools with the following configuration</para> + + <para> + <programlisting><![CDATA[ + <configuration ...> + <java-wsdl> + <service name="TestService" style="rpc" + endpoint="org.jboss.test.ws.jaxrpc.samples.handler.HeaderTestService"> + <operation name="testInHeader"> + <parameter type="java.lang.String"/> + <parameter type="java.lang.String" xml-name="headerMsg" header="true"/> + </operation> + <operation name="testInOutHeader"> + <parameter type="java.lang.String"/> + <parameter type="javax.xml.rpc.holders.StringHolder" + xml-name="headerMsg" header="true" mode="INOUT"/> + </operation> + <operation name="testOutHeader"> + <parameter type="java.lang.String"/> + <parameter type="javax.xml.rpc.holders.StringHolder" + xml-name="headerMsg" header="true" mode="OUT"/> + </operation> + </service> + + <namespaces target-namespace="http://org.jboss.ws/samples/handler" + type-namespace="http://org.jboss.ws/samples/handler/types"/> + + <mapping file="jaxrpc-mapping.xml"/> + <webservices servlet-link="TestService"/> + </java-wsdl> + </configuration> + ]]></programlisting></para> + + <para>The handlers must be defined manualy in webservices.xml. WSTools does not generate client/server side handler configurations.</para> + + <para> + <programlisting><![CDATA[ + <webservices ...> + <webservice-description> + ... + <port-component> + ... + <handler> + <handler-name>HeaderTestHandler</handler-name> + <handler-class>org.jboss.test.ws.jaxrpc.samples.handler.ServerSideHandler</handler-class> + </handler> + </port-component> + </webservice-description> + </webservices> + ]]></programlisting></para> + + <para><command>Generic Handler</command></para> + + <para> + The javax.xml.rpc.handler.GenericHandler class is an abstract class that implements the Handler interface. + Developers typically subclass the GenericHandler class unless the Handler implementation class needs another class as its superclass. + </para> + + <para> + The GenericHandler class is a convenience abstract class that makes writing handlers easy. + This class provides default implementations of the lifecycle methods init and destroy and also different handle methods. + A handler developer should only override methods that it needs to specialize as part of the derived Handler implementation class. + </para> + + <title>Handler message processing</title> + + <para> + <itemizedlist> + <listitem> + <para>On the client side, a request handler is invoked before an RPC request is communicated to the target service endpoint.</para> + </listitem> + + <listitem> + <para>On the client side, a response or fault handler is invoked before an RPC response is returned to the service client from the target service endpoint.</para> + </listitem> + </itemizedlist> </para> + + + + <para>On the endpoint a JAX-RPC handler may be configured and used as follows:</para> + + <para> + <itemizedlist> + <listitem> + <para>On the service endpoint side, a request handler is invoked before an RPC request is dispatched to the target service endpoint.</para> + </listitem> + + <listitem> + <para>On the service endpoint side, a response or fault handler is invoked before communication back to the service client from the target service endpoint.</para> + </listitem> + </itemizedlist> </para> + + <para><command>Configuring a client side handler</command></para> + + <para>Client side JAXRPC handlers are configured as part of the &lt;service-ref&gt; element + that is available in application-client.xml, ejb-jar.xml and web.xml. + </para> + + <para> + <programlisting><![CDATA[ + <service-ref> + <service-ref-name>service/TestService</service-ref-name> + <service-interface>javax.xml.rpc.Service</service-interface> + <wsdl-file>META-INF/wsdl/TestService.wsdl</wsdl-file> + <jaxrpc-mapping-file>META-INF/jaxrpc-mapping.xml</jaxrpc-mapping-file> + <port-component-ref> + <service-endpoint-interface> + org.jboss.test.ws.jaxrpc.samples.handler.HeaderTestService + </service-endpoint-interface> + </port-component-ref> + <handler> + <handler-name>HeaderTestHandler</handler-name> + <handler-class>org.jboss.test.ws.jaxrpc.samples.handler.ClientSideHandler</handler-class> + </handler> + </service-ref> + ]]></programlisting></para> + + </sect1> + Added: trunk/docs/online/tutorial-doc/en/modules/headers-handlers/headers-handlers.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/headers-handlers/headers-handlers.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/headers-handlers/headers-handlers.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,12 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: headers-handlers.xml 284 2006-05-05 23:26:06Z jason.greene(a)jboss.com $ --> + +<chapter id="headers-handlers"> + + <title>Headers &amp; Handlers</title> + + &s-headers; + &s-handlers; + &s-dynamic-handlers; +</chapter> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/headers-handlers/headers.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/headers-handlers/headers.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/headers-handlers/headers.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,197 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: headers.xml 506 2006-06-28 14:07:03Z thomas.diesler(a)jboss.com $ --> + +<sect1 id="headers"> + + <title>Bound and unbound SOAP Headers</title> + + <para><command>Bound SOAP Headers </command></para> + + <para>Bound SOAP header elements are visible on the SEI as operation parameters, unbound SOAP headers + are not. Both, bound and unbound headers are visible to JAXRPC handlers. Here is an example that uses bound + headers on three SEI methods.</para> + + <para> + <programlisting><![CDATA[ + public interface HeaderTestService extends Remote + { + void testInHeader(String bodyMsg, String headerMsg) throws RemoteException; + + void testInOutHeader(String bodyMsg, StringHolder headerMsg) throws RemoteException; + + void testOutHeader(String bodyMsg, StringHolder headerMsg) throws RemoteException; + } + ]]></programlisting></para> + + <para>A bound header is a message part that is explicitly bound with the &lt;soap:header&gt; element + in the WSDL binding.</para> + + <para> + <programlisting><![CDATA[ + <message name="HeaderTestService_testInHeader"> + <part name="String_1" type="xsd:string"/> + <part name="String_2" type="xsd:string"/> + </message> + + <portType name="HeaderTestService"> + <operation name="testInHeader" parameterOrder="String_1 String_2"> + <input message="tns:HeaderTestService_testInHeader"/> + <output message="tns:HeaderTestService_testInHeaderResponse"/> + </operation> + ... + </portType> + + <binding name="HeaderTestServiceBinding" type="tns:HeaderTestService"> + <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"/> + <operation name="testInHeader"> + <soap:operation soapAction=""/> + <input> + <soap:body use="literal" namespace="http://org.jboss.ws/samples/handler"/> + <soap:header message="tns:HeaderTestService_testInHeader" + part="String_2" use="literal" namespace="http://somens"/> + </input> + <output> + <soap:body use="literal" namespace="http://org.jboss.ws/samples/handler"/> + </output> + </operation> + ... + </binding> + ]]></programlisting></para> + + <para><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> + <ns2:String_2 xmlns:ns2='http://somens'>IN header message</ns2:String_2> + </env:Header> + <env:Body> + <ns1:testInHeader xmlns:ns1='http://org.jboss.ws/samples/handler'> + <String_1>Hello world!</String_1> + </ns1:testInHeader> + </env:Body> + </env:Envelope> + ]]></programlisting></para> + + <para> + <programlisting><![CDATA[ + Outgoing SOAPMessage + + <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'> + <env:Header/> + <env:Body> + <ns1:testInHeaderResponse xmlns:ns1='http://org.jboss.ws/samples/handler'/> + </env:Body> + </env:Envelope> + ]]></programlisting></para> + + <para><command>Unbound SOAP Headers</command></para> + + <para>Unbound SOAP header elements are not visible on SEI methods, but in JAXRPC handlers through the SAAJ API.</para> + + <para> + <programlisting><![CDATA[ + public class ServerSideHandler extends GenericHandler + { + ... + + public boolean handleResponse(MessageContext msgContext) + { + log.info("handleResponse"); + + try + { + SOAPMessage soapMessage = ((SOAPMessageContext)msgContext).getMessage(); + SOAPHeader soapHeader = soapMessage.getSOAPHeader(); + + SOAPBody soapBody = soapMessage.getSOAPBody(); + SOAPBodyElement soapBodyElement = + (SOAPBodyElement)soapBody.getChildElements().next(); + String rpcName = soapBodyElement.getElementName().getLocalName(); + + SOAPFactory soapFactory = SOAPFactory.newInstance(); + Name headerName = + soapFactory.createName("HeaderValue", "ns2", "http://otherns"); + SOAPHeaderElement she = soapHeader.addHeaderElement(headerName); + she.setValue("Unbound OUT header message"); + } + catch (SOAPException e) + { + throw new JAXRPCException(e); + } + + return true; + } + } + ]]></programlisting></para> + + <para><command>Unbound SOAP Headers on the client proxy</command></para> + + <para>The web service client has access to unbound headers through the proxy</para> + + <para> + <programlisting><![CDATA[ + public void testUnboundInHeader() throws Exception + { + // Add a header to the stub + StubExt stub = (StubExt)endpoint; + QName xmlName = new QName("http://otherns", "HeaderValue"); + stub.addUnboundHeader( + xmlName, Constants.TYPE_LITERAL_STRING, + String.class, ParameterMode.IN + ); + stub.setUnboundHeaderValue(xmlName, "Unbound IN header message"); + + endpoint.testInHeader("Hello world!", "IN header message"); + + String unboundRet = (String)stub.getUnboundHeaderValue(xmlName); + assertEquals("Unbound OUT header message", unboundRet); + } + ]]></programlisting></para> + + <para><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> + <ns2:String_2 xmlns:ns2='http://somens'>INOUT header message</ns2:String_2> + <ns3:HeaderValue + xmlns:ns3='http://otherns'>Unbound INOUT header message</ns3:HeaderValue> + </env:Header> + <env:Body> + <ns1:testInOutHeader xmlns:ns1='http://org.jboss.ws/samples/handler'> + <String_1>Hello world!</String_1> + </ns1:testInOutHeader> + </env:Body> + </env:Envelope> + ]]></programlisting></para> + + <para> + <programlisting><![CDATA[ + Outgoing SOAPMessage + + <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'> + <env:Header> + <ns2:String_2 + xmlns:ns2='http://somens'>INOUT header message - response</ns2:String_2> + <ns2:HeaderValue + xmlns:ns2='http://otherns'>Unbound OUT header message</ns2:HeaderValue> + </env:Header> + <env:Body> + <ns1:testInOutHeaderResponse xmlns:ns1='http://org.jboss.ws/samples/handler'/> + </env:Body> + </env:Envelope> + ]]></programlisting></para> + + </sect1> Added: trunk/docs/online/tutorial-doc/en/modules/holders/inout-parameters.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/holders/inout-parameters.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/holders/inout-parameters.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,112 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: inout-parameters.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $ --> + +<chapter id="inout-parameters"> + + <title>Holders for INOUT parameters</title> + + <para>This chapter describes how a BigDecimalHolder can be used as an in/out parameter.</para> + + <para> + <programlisting><![CDATA[ + public interface HolderTestService extends Remote + { + void echoBigDecimal(BigDecimalHolder val) throws RemoteException; + ... + } + ]]></programlisting></para> + + <para><command>Generating required deployment artifacts</command></para> + + <para>Run wstools with the following configuration</para> + + <para> + <programlisting><![CDATA[ + <configuration xmlns="http://www.jboss.org/jbossws-tools"> + <javaToWSDL> + <service name="TestService" wsdlStyle="rpc" + endpoint="org.jboss.test.ws.jaxrpc.samples.holder.HolderTestService"/> + <namespaces targetNamespace="http://org.jboss.ws/samples/holder" + typeNamespace="http://org.jboss.ws/samples/holder/types"/> + <mapping fileName="jaxrpc-mapping.xml"/> + <wsxml servletLink="TestService"/> + </javaToWSDL> + </configuration> + ]]></programlisting></para> + + <para>WSTools generates WSDL messages with identical part names.</para> + + <para> + <programlisting><![CDATA[ + <message name='HolderTestService_echoBigDecimal'> + <part name='BigDecimal_1' type='xsd:decimal'/> + </message> + + <message name='HolderTestService_echoBigDecimalResponse'> + <part name='BigDecimal_1' type='xsd:decimal'/> + </message> + + <portType name='HolderTestService'> + <operation name='echoBigDecimal' parameterOrder='BigDecimal_1'> + <input message='tns:HolderTestService_echoBigDecimal'/> + <output message='tns:HolderTestService_echoBigDecimalResponse'/> + </operation> + ... + </portType> + ]]></programlisting></para> + + <para>The &lt;service-endpoint-method-mapping&gt; declares the parameter mode as INOUT.</para> + + <para> + <programlisting><![CDATA[ + <service-endpoint-method-mapping> + <java-method-name>echoBigDecimal</java-method-name> + <wsdl-operation>echoBigDecimal</wsdl-operation> + <method-param-parts-mapping> + <param-position>0</param-position> + <param-type>java.math.BigDecimal</param-type> + <wsdl-message-mapping> + <wsdl-message xmlns:wsdlMsgNS='http://org.jboss.ws/samples/holder'> + wsdlMsgNS:HolderTestService_echoBigDecimal + </wsdl-message> + <wsdl-message-part-name>BigDecimal_1</wsdl-message-part-name> + <parameter-mode>INOUT</parameter-mode> + </wsdl-message-mapping> + </method-param-parts-mapping> + </service-endpoint-method-mapping> + ]]></programlisting></para> + + <para><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:echoBigDecimal xmlns:ns1='http://org.jboss.ws/samples/holder'> + <BigDecimal_1>1000</BigDecimal_1> + </ns1:echoBigDecimal> + </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:echoBigDecimalResponse xmlns:ns1='http://org.jboss.ws/samples/holder'> + <BigDecimal_1>1001</BigDecimal_1> + </ns1:echoBigDecimalResponse> + </env:Body> + </env:Envelope> + ]]></programlisting></para> + +</chapter> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/installation/install-jboss.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/installation/install-jboss.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/installation/install-jboss.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,40 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: install-jboss.xml 1495 2006-11-21 20:29:19Z thomas.diesler(a)jboss.com $ --> + +<sect1 id="install-jboss"> + + <title>Install on JBoss Application Server</title> + + <para>To take advantage of optimum integration it is best to install JBossWS on the appserver with embedded Tomcat. + In this way you get access to the full set of advanced J2EE features (JMS, JAAS, EJB, etc.) advanced class loading, + better integration with managment and security. Contrary to common believe JBossAS with embedded Tomcat is + as lightweight and easy to administer as standalone Tomcat.</para> + + <para>For additional information, see <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=TomcatStandalonevsEmbe... Standalone vs Embedded</ulink>.</para> + + <para>Installing JBossWS on JBoss is a matter of two simple steps.</para> + + <itemizedlist> + <listitem> + <para> + Deploy jbossws.sar to ${jboss.home}/server/default/deploy. + Recommended is an expanded deployment for easy access to JBossWS configuration files. + </para> + </listitem> + <listitem> + <para> + Copy jbossws-client.jar to ${jboss.home}/client. + </para> + </listitem> + </itemizedlist> + + <para>If you are running JBoss on jdk1.4, you need to deploy jbossws14.sar and jbossws14-client.jar respectivly.</para> + + <para>The integration layer hooks into the JBoss deployer architecture and allows you to hot-deploy POJO and EJB endpoints. The + packaging of a standard portable J2EE-1.4 web service endpoints is defined by the JSR109 specification. JBossWS also supports + JSR181 endpoints, which are significantly easier to develop and maintain.</para> + + <para>Additionally, please have a look at the <ulink url="http://labs.jboss.com/jbossws/user-guide/en/Install.txt"&g... specific install instructions</ulink>.</para> + +</sect1> Added: trunk/docs/online/tutorial-doc/en/modules/installation/install-tomcat.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/installation/install-tomcat.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/installation/install-tomcat.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,69 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: install-tomcat.xml 1495 2006-11-21 20:29:19Z thomas.diesler(a)jboss.com $ --> + +<sect1 id="install-tomcat"> + + <title>Install on Apache Tomcat</title> + + <para>If you have an existing application on Tomcat that has a need for web service support, you can still use JBossWS. This + allows you to develop standard portable J2EE-1.4 web service endpoints in Tomcat that can be moved unmodified to JBossAS when needed. + New applications should consider JBoss with ebedded Tomcat for a number of good reasons. </para> + + <para>For additional information, see <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=TomcatStandalonevsEmbe... Standalone vs Embedded</ulink>.</para> + + <para>JBoss Inc. provides subscription support contracts for both Tomcat Standalone and JBoss embedded Tomcat.</para> + + <para>To install JBossWS on Tomcat you need to</para> + + <itemizedlist> + <listitem> + <para> + Copy serializer.jar, xalan.jar, xercesImpl.jar to ${tomcat.home}/common/endorsed. This overrides the XML parser that comes with + the JDK with a more recent version that is compatible with JBossWS. + </para> + </listitem> + <listitem> + <para> + Copy activation.jar, mailapi.jar, log4j.jar to ${tomcat.home}/common/lib. + </para> + </listitem> + <listitem> + <para> + Copy jbossws-core.jar, jbossws-tomcat-integration.jar, jbossws-thirdparty.jar to ${tomcat.home}/common/lib. + </para> + </listitem> + <listitem> + <para> + Copy jbossws.war to ${tomcat.home}/webapps. + </para> + </listitem> + </itemizedlist> + + <para>There is no jdk1.4 version available for Tomcat.</para> + + <para>When the jbossws web application context stats up, it creates a ${tomcat.home}/jbossws-deploy directory next to ${tomcat.home}/webapps. + This is the hot deployment directory equivalent to ${jboss.home}/server/default/deploy. Web service endpoints that you drop in ${tomcat.home}/jbossws-deploy + are converted into valid web applications and copied over to ${tomcat.home}/webapps</para> + + <para>Only POJO endpoints are supported. EJB endpoints are not supported in Tomcat standalone for obvious resons. Also note, that POJO endpoints + are currently not pooled, hence you get a new instance for ever invocation. The packaging of a standard portable J2EE-1.4 web service endpoints + is defined by the JSR109 specification. JBossWS also supports JSR181 endpoints, which are significantly easier to develop and maintain.</para> + + <para>To run the samples that come with this JBossWS release against Tomcat, you must enable access to the Tomcat Manager in ${tomcat.home}/conf/tomcat-users.xml + For details of this see <ulink url="http://tomcat.apache.org/tomcat-5.5-doc/manager-howto.html#Conf... Manager Application Access</ulink> + in the Tomcat documentation.</para> + + <para>Here is a example</para> + + <para> + <programlisting><![CDATA[ + <tomcat-users> + <role rolename="manager"/> + <user username="manager" password="manager" roles="manager"/> + </tomcat-users> + ]]></programlisting></para> + + <para>Additionally, please have a look at the <ulink url="http://labs.jboss.com/jbossws/user-guide/en/Install.txt"&g... specific install instructions</ulink>.</para> + +</sect1> Added: trunk/docs/online/tutorial-doc/en/modules/installation/installation.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/installation/installation.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/installation/installation.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,17 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<chapter id="installation"> + + <title>Installation</title> + + <para> + JBossWS is based on the <ulink url="http://labs.jboss.com/portal/jbossmc">JBoss Microcontainer</ulink>, which + supports direct POJO deployment and standalone use outside the JBoss application server. Currently, we have integration + layers for the JBoss application server and Apache Tomcat. + </para> + + &s-install-jboss; + &s-install-tomcat; + +</chapter> + Added: trunk/docs/online/tutorial-doc/en/modules/introduction.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/introduction.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/introduction.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,64 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<chapter id="introduction"> + <title>Introduction</title> + + <sect1 id="features"> + <title>Features</title> + <itemizedlist> + <listitem> + <para>RPC style and Document style endpoints (wrapped and bare)</para> + </listitem> + <listitem> + <para>SOAP header values bound/unbound to endpoint parameters</para> + </listitem> + <listitem> + <para>J2EE endpoint development model for EJB and Java (JSR-109)</para> + </listitem> + <listitem> + <para>J2EE client development model (JSR-109)</para> + </listitem> + <listitem> + <para>Dynamic Invocation Interface (DII)</para> + </listitem> + <listitem> + <para>JAX-RPC client/server side handlers</para> + </listitem> + <listitem> + <para>Holders for INOUT/OUT parameters</para> + </listitem> + <listitem> + <para>Message style endpoints</para> + </listitem> + <listitem> + <para>Attachments Profile Version 1.0</para> + </listitem> + <listitem> + <para>Dynamic client/server side handler injection</para> + </listitem> + <listitem> + <para>Web Service Metadata (JSR-181)</para> + </listitem> + <listitem> + <para>EJB3 Stateless Session endpoints</para> + </listitem> + <listitem> + <para>WS-Security1.0 for XML Encryption/Signature of the SOAP message</para> + </listitem> + <listitem> + <para>WS-Addressing (W3C candidate release) and JSR-261</para> + </listitem> + <listitem> + <para>WS-Eventing</para> + </listitem> + <listitem> + <para>WS-Policy</para> + </listitem> + <listitem> + <para>MTOM/XOP</para> + </listitem> + </itemizedlist> + </sect1> + +</chapter> + Added: trunk/docs/online/tutorial-doc/en/modules/jmstransport/jms-client.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/jmstransport/jms-client.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/jmstransport/jms-client.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,47 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: jms-client.xml 284 2006-05-05 23:26:06Z jason.greene(a)jboss.com $ --> + +<sect1 id="jms-client"> + + <title>JMS Client</title> + + <para>To send a SOAP message to a JMS endpoint you use the normal JMS message producer metodology. Here is an example:</para> + + <para>There is not yet transparent JMS transport available for web service clients. + Please monitor <ulink url="http://jira.jboss.com/jira/browse/JBWS-670">JBWS-670<... for progress on this.</para> + + <para> + <programlisting><![CDATA[ + InitialContext context = new InitialContext(); + QueueConnectionFactory connectionFactory = + (QueueConnectionFactory)context.lookup("ConnectionFactory"); + + Queue reqQueue = (Queue)context.lookup("queue/RequestQueue"); + Queue resQueue = (Queue)context.lookup("queue/ResponseQueue"); + + QueueConnection con = connectionFactory.createQueueConnection(); + QueueSession session = con.createQueueSession(false, Session.AUTO_ACKNOWLEDGE); + QueueReceiver receiver = session.createReceiver(resQueue); + ResponseListener responseListener = new ResponseListener(); + receiver.setMessageListener(responseListener); + con.start(); + + TextMessage message = session.createTextMessage(reqMessage); + message.setJMSReplyTo(resQueue); + + QueueSender sender = session.createSender(reqQueue); + sender.send(message); + sender.close(); + + done.acquire(); + + assertNotNull("Expected response message", responseListener.resMessage); + assertEquals(DOMUtils.parse(resMessage), DOMUtils.parse(responseListener.resMessage)); + + con.stop(); + session.close(); + con.close(); + ]]></programlisting></para> + +</sect1> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/jmstransport/jms-endpoint.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/jmstransport/jms-endpoint.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/jmstransport/jms-endpoint.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,92 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: jms-endpoint.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $ --> + +<sect1 id="jms-endpoint"> + + <title>JMS Endpoint</title> + + <para>In this section we describe how to expose an EJB Message Driven Bean as service endpoint.</para> + + <para><command>The Message Driven Bean</command></para> + + <para>First you setup an ordinary message driven bean in ejb-jar.xml and jboss.xml</para> + + <para> + <programlisting><![CDATA[ + <ejb-jar> + <enterprise-beans> + <message-driven> + <ejb-name>OrganizationMDB</ejb-name> + <ejb-class>org.jboss.test.ws.jaxrpc.samples.jmstransport.OrganizationJMSEndpoint</ejb-class> + <message-selector></message-selector> + <transaction-type>Container</transaction-type> + <acknowledge-mode>AUTO_ACKNOWLEDGE</acknowledge-mode> + <message-driven-destination> + <destination-type>javax.jms.Queue</destination-type> + <subscription-durability>NonDurable</subscription-durability> + </message-driven-destination> + </message-driven> + </enterprise-beans> + </ejb-jar> + + <jboss> + <enterprise-beans> + <message-driven> + <ejb-name>OrganizationMDB</ejb-name> + <destination-jndi-name>queue/RequestQueue</destination-jndi-name> + <depends>jboss.mq.destination:service=Queue,name=RequestQueue</depends> + </message-driven> + </enterprise-beans> + </jboss> + ]]></programlisting></para> + + <para>The implementation extends + <ulink url="http://fisheye.jboss.com/viewrep/JBoss/jboss/src/main/org/jboss... + org.jboss.webservice.transport.jms.JMSTransportSupport</ulink>, which is the actual MDB and takes care of decoding the incomming JMS + message and dispatching it to the target endpoint bean.</para> + + <para> + <programlisting><![CDATA[ + public class OrganizationJMSEndpoint extends JMSTransportSupport + { + // provide logging + private static final Logger log = Logger.getLogger(OrganizationJMSEndpoint.class); + + /** Get the contact info */ + public String getContactInfo(String organization) throws RemoteException + { + log.info("getContactInfo: " + organization); + return "The '" + organization + "' boss is currently out of office, please call again."; + } + } + ]]></programlisting></para> + + <para><command>Packaging the JMS Endpoint</command></para> + + <para>A JMS endpoint is packaged like an <link linkend="jsr109-ejb-endpoint">JSR-109 EJB Endpoint</link> and uses the standard webservices.xml + descriptor</para> + + <para> + <programlisting><![CDATA[ + <webservices ...> + <webservice-description> + <webservice-description-name>OrganizationService</webservice-description-name> + <wsdl-file>META-INF/wsdl/OrganizationService.wsdl</wsdl-file> + <jaxrpc-mapping-file>META-INF/jaxrpc-mapping.xml</jaxrpc-mapping-file> + <port-component> + <port-component-name>OrganizationPort</port-component-name> + <wsdl-port>impl:OrganizationPort</wsdl-port> + <service-endpoint-interface> + org.jboss.test.ws.jaxrpc.samples.jmstransport.Organization + </service-endpoint-interface> + <service-impl-bean> + <ejb-link>OrganizationMDB</ejb-link> + </service-impl-bean> + </port-component> + </webservice-description> + </webservices> + ]]></programlisting></para> + + +</sect1> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/jmstransport/jms-transport.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/jmstransport/jms-transport.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/jmstransport/jms-transport.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,17 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: jms-transport.xml 284 2006-05-05 23:26:06Z jason.greene(a)jboss.com $ --> + +<chapter id="jms-transport"> + + <title>JMS Transport</title> + + <para>JBossWS supports J2EE-1.4 message driven beans (MDB) as service endpoints. + A JMS message that is targeted to MDB may contain a SOAP envelope that is then dispatched to the same MDB. + The MDB implements the methods on the Service Endpoint Interface (SEI), onMessage() is implemented + by a base class that we provide. + </para> + + &s-jms-endpoint; + &s-jms-client; +</chapter> Property changes on: trunk/docs/online/tutorial-doc/en/modules/jmstransport/jms-transport.xml ___________________________________________________________________ Name: svn:executable + * Added: trunk/docs/online/tutorial-doc/en/modules/mtom-xop/mtom-xop.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/mtom-xop/mtom-xop.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/mtom-xop/mtom-xop.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,144 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: mtom-xop.xml 865 2006-08-30 22:32:11Z thomas.diesler(a)jboss.com $ --> + +<chapter id="mtom-xop"> + + <title>MTOM/XOP</title> + + <para>This chapter describes Message Transmission Optimization Mechanism (MTOM) and XML-binary Optimized Packaging (XOP), + a means of more efficiently serializing XML Infosets that have certain types of content. + The related specifications are <ulink url=" http://www.w3.org/TR/soap12-mtom/">SOAP Message Transmission Optimization Mechanism (MTOM)</ulink> + and <ulink url="http://www.w3.org/TR/xop10/">XML-binary Optimized Packaging (XOP)</ulink> + </para> + + <para>The MTOM/XOP example uses a service endpoint interface with the same operations as in <link linkend="attachments">SOAP with Attachments</link> + </para> + + <sect1 id="mtom-schema-elements"> + <title>MTOM schema elements</title> + + + <para>Currently neither wstools nor wscompile has support for MTOM. + Fortunatly a MTOM optimizable element decalaration isn't that difficult to understand + and can easily be created manually:</para> + + <para> + <programlisting><![CDATA[ + <schema xmlns="http://www.w3.org/2001/XMLSchema" + targetNamespace="http://org.jboss.ws/samples/mtom" + xmlns:xmime="http://www.w3.org/2005/05/xmlmime"> + + (1) <import schemaLocation="http://www.w3.org/2005/05/xmlmime" namespace="http://www.w3.org/2005/05/xmlmime"/> + + (2) <element name="imagejpeg" xmime:contentType="image/jpeg" type="xmime:base64Binary"/> + </schema> + ]]></programlisting> + + <orderedlist> + <listitem> + <para> + Import the xmime schema declarations + </para> + </listitem> + <listitem> + <para> + Derive your element declaration from xmime:base64Binary + </para> + </listitem> + </orderedlist> + + The JBossWS MTOM implementation scans the associated schema + and will treat any xmime:base64Binary occurance as a MTOM optimizable parameter. + </para> + + </sect1> + + <sect1 id="mtom-schema-elements"> + <title>Supported MTOM parameter types</title> + <para> + <table frame="all"> + <title>Java to Mime mapping</title> + <tgroup cols="2"> + <tbody> + <row> + <entry>image/jpeg</entry> + <entry>java.awt.Image</entry> + </row> + <row> + <entry>text/xml</entry> + <entry>javax.xml.transform.Source</entry> + </row> + <row> + <entry>application/xml</entry> + <entry>javax.xml.transform.Source</entry> + </row> + <row> + <entry>*/*</entry> + <entry>javax.activation.DataHandler</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + + The above table shows a list of supported endpoint parameter types. The recommended approach is to use + the <ulink url="http://java.sun.com/j2ee/1.4/docs/api/javax/activation/DataHand... + javax.activation.DataHandler</ulink> classes to represent binary data as service endpoint parameters. + + </sect1> + + <sect1> + <title>An example MTOM request</title> + + <para>The incomming message is multipart/related. The first part is the SOAP Envelope.</para> + + <para> + <programlisting><![CDATA[ +POST /jbossws-samples-mtom HTTP/1.1 +SOAPAction: "" +Content-Type: multipart/related; start-info="text/xml"; + type="application/xop+xml"; + start=&quot;&lt;rootpart(a)ws.jboss.org&gt;&quot;; + boundary="----=_Part_2_29441291.1153833579421" +User-Agent: Java/1.5.0_07 +Host: localhost:8081 +Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 +Connection: keep-alive +Content-Length: 915 + + +------=_Part_2_29441291.1153833579421 +Content-Type: application/xop+xml; type="text/xml" +Content-Transfer-Encoding: 8bit +Content-ID: <rootpart(a)ws.jboss.org&gt; + +<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'> + <env:Header/> + <env:Body> + <ns1:sendMimeTextXML xmlns:ns1='http://org.jboss.ws/samples/mtom'> + <message>Some text message</message> + <ns1:textxml> + <xop:Include + href='cid:textxml-590c9216-9871-48a8-9239-f73831644442@ws.jboss.org' + xmlns:xop='http://www.w3.org/2004/08/xop/include'/> + </ns1:textxml> + </ns1:sendMimeTextXML> + </env:Body> +</env:Envelope> +------=_Part_2_29441291.1153833579421 +Content-Type: text/xml +Content-Transfer-Encoding: binary +Content-Id: <textxml-590c9216-9871-48a8-9239-f73831644442(a)ws.jboss.org&gt; + +<?xml version="1.0" encoding="ISO-8859-1"?> + +<mime-message>This is an xml attachment.</mime-message> + +------=_Part_2_29441291.1153833579421-- + + ]]></programlisting></para> + + </sect1> + +</chapter> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/oneway/oneway.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/oneway/oneway.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/oneway/oneway.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,82 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: oneway.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $ --> + +<chapter id="oneway"> + + <title>OneWay Invocations</title> + + <para>This chapter describes an asynchronous one way endpoint invocation</para> + + <para> + <programlisting><![CDATA[ + public interface OneWayTestService extends Remote + { + void oneWay(String str1) 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="TestService" style="rpc" + endpoint="org.jboss.test.ws.jaxrpc.samples.oneway.OneWayTestService"> + <operation name="oneWay" one-way="true"> + <parameter type="java.lang.String"/> + </operation> + </service> + + <namespaces target-namespace="http://org.jboss.ws/samples/oneway" + type-namespace="http://org.jboss.ws/samples/one-way=/types"/> + + <mapping file="jaxrpc-mapping.xml"/> + <webservices servlet-link="TestService"/> + </java-wsdl> + </configuration> + ]]></programlisting></para> + + <para>WSTools does not generate output elements in the WSDL portType nor in the binding</para> + + <para> + <programlisting><![CDATA[ + <portType name='OneWayTestService'> + <operation name='oneWay' parameterOrder='String_1'> + <input message='tns:OneWayTestService_oneWay'/> + </operation> + </portType> + + <binding name='OneWayTestServiceBinding' type='tns:OneWayTestService'> + <soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http'/> + <operation name='oneWay'> + <soap:operation soapAction=''/> + <input> + <soap:body namespace='http://org.jboss.ws/samples/oneway' use='literal'/> + </input> + </operation> + </binding> + ]]></programlisting></para> + + <para><command>SOAP message exchange</command></para> + + <para>Below you see the incomming SOAP message. There is no outgoing message.</para> + + <para> + <programlisting><![CDATA[ + Incomming SOAPMessage + + <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'> + <env:Header/> + <env:Body> + <ns1:oneWay xmlns:ns1='http://org.jboss.ws/samples/oneway'> + <String_1>Hello</String_1> + </ns1:oneWay> + </env:Body> + </env:Envelope> + ]]></programlisting></para> + +</chapter> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/secureejb/secure-ejb.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/secureejb/secure-ejb.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/secureejb/secure-ejb.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,262 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: secure-ejb.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $ --> + +<chapter id="secure-ejb"> + + <title>Secure Endpoints</title> + + <para><command>Secure the access to the SLSB</command></para> + + <para>First we secure the access to the SLSB as we would do for normal (non web service) invocations.</para> + + <para>In ejb-jar.xml, we setup the method permissions for the SLSB endpoint. + Note, that it is not necessarily required for the endpoint to have home/remote interfaces.</para> + + <para> + <programlisting><![CDATA[ + <enterprise-beans> + <session> + <ejb-name>RoleSecuredSLSB</ejb-name> + <remote>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationRemote</remote> + <home>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationHome</home> + <service-endpoint>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationService</service-endpoint> + <ejb-class>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationImpl</ejb-class> + <session-type>Stateless</session-type> + <transaction-type>Container</transaction-type> + <security-role-ref> + <role-name>friend</role-name> + </security-role-ref> + </session> + <session> + <ejb-name>BasicSecuredSLSB</ejb-name> + <remote>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationRemote</remote> + <home>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationHome</home> + <service-endpoint>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationService</service-endpoint> + <ejb-class>org.jboss.test.ws.jaxrpc.samples.secureejb.OrganizationImpl</ejb-class> + <session-type>Stateless</session-type> + <transaction-type>Container</transaction-type> + </session> + </enterprise-beans> + + <assembly-descriptor> + <security-role> + <role-name>friend</role-name> + </security-role> + <method-permission> + <role-name>friend</role-name> + <method> + <ejb-name>RoleSecuredSLSB</ejb-name> + <method-name>*</method-name> + </method> + </method-permission> + <method-permission> + <unchecked/> + <method> + <ejb-name>BasicSecuredSLSB</ejb-name> + <method-name>*</method-name> + </method> + </method-permission> + </assembly-descriptor> + ]]></programlisting></para> + + <para><command>Define the security domain</command></para> + + <para>Next, define the security domain for this deployment in jboss.xml. + The JBossWS security context is configured in login-config.xml and uses the + <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=UsersRolesLoginModule&... + + <para> + <programlisting><![CDATA[ + <jboss> + <security-domain>java:/jaas/JBossWS</security-domain> + <enterprise-beans> + <session> + <ejb-name>RoleSecuredSLSB</ejb-name> + <jndi-name>ejb/RoleSecuredSLSB</jndi-name> + <port-component> + <port-component-name>RoleSecured</port-component-name> + <port-component-uri>/ws4ee-samples-ejb/RoleSecured</port-component-uri> + </port-component> + </session> + <session> + <ejb-name>BasicSecuredSLSB</ejb-name> + <jndi-name>ejb/BasicSecuredSLSB</jndi-name> + <port-component> + <port-component-name>BasicSecured</port-component-name> + <port-component-uri>/ws4ee-samples-ejb/BasicSecured</port-component-uri> + </port-component> + </session> + </enterprise-beans> + </jboss> + ]]></programlisting></para> + + <para>In login-config.xml, that lives in the server config dir, you will find the definition of the JBossWS security domain.</para> + + <para> + <programlisting><![CDATA[ + <!-- + 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> + ]]></programlisting></para> + + <para><command> Use the JAXRPC Stub to set principal/credential</command></para> + + <para>A web service client may use the javax.xml.rpc.Stub object to set the username/password combination</para> + + <para> + <programlisting><![CDATA[ + public void testWebServiceAccess() throws Exception + { + OrganizationEndpoint endpoint = service.getPort(OrganizationEndpoint.class); + + Stub stub = (Stub)endpoint; + stub._setProperty(Stub.USERNAME_PROPERTY, "kermit"); + stub._setProperty(Stub.PASSWORD_PROPERTY, "thefrog"); + + String info = endpoint.getContactInfo("mafia"); + assertEquals("The 'mafia' boss is currently out of office, please call again.", info); + } + ]]></programlisting></para> + + <para><command> Using HTTP Basic Auth for security</command></para> + + <para>To enable HTTP Basic authentication you need to add a port-component descriptor to your jboss.xml file, which contains an auth-method tag. + We just modify the jboss.xml from above.</para> + + <para> + <programlisting><![CDATA[ + <jboss> + <security-domain>java:/jaas/JBossWS</security-domain> + <enterprise-beans> + <session> + <ejb-name>RoleSecuredSLSB</ejb-name> + <jndi-name>ejb/RoleSecuredSLSB</jndi-name> + <port-component> + <port-component-name>RoleSecured</port-component-name> + <port-component-uri>/ws4ee-samples-ejb/RoleSecured</port-component-uri> + <auth-method>BASIC</auth-method> + </port-component> + </session> + <session> + <ejb-name>BasicSecuredSLSB</ejb-name> + <jndi-name>ejb/BasicSecuredSLSB</jndi-name> + <port-component> + <port-component-name>BasicSecured</port-component-name> + <port-component-uri>/ws4ee-samples-ejb/BasicSecured</port-component-uri> + <auth-method>BASIC</auth-method> + </port-component> + </session> + </enterprise-beans> + </jboss> + ]]></programlisting></para> + + <para><command>Secure HTTP transport</command></para> + + <para>You can also require that all webservice requests use SSL by adding the transport-guarantee tag in your jboss.xml file. + Modify jboss.xml file to also require the transport guarantee CONFIDENTIAL. + </para> + + <para> + <programlisting><![CDATA[ + <jboss> + <security-domain>java:/jaas/JBossWS</security-domain> + <enterprise-beans> + <session> + <ejb-name>RoleSecuredSLSB</ejb-name> + <jndi-name>ejb/RoleSecuredSLSB</jndi-name> + <port-component> + <port-component-name>RoleSecured</port-component-name> + <port-component-uri>/ws4ee-samples-ejb/RoleSecured</port-component-uri> + <auth-method>BASIC</auth-method> + <transport-guarantee>CONFIDENTIAL</transport-guarantee> + </port-component> + </session> + <session> + <ejb-name>BasicSecuredSLSB</ejb-name> + <jndi-name>ejb/BasicSecuredSLSB</jndi-name> + <port-component> + <port-component-name>BasicSecured</port-component-name> + <port-component-uri>/ws4ee-samples-ejb/BasicSecured</port-component-uri> + <auth-method>BASIC</auth-method> + <transport-guarantee>CONFIDENTIAL</transport-guarantee> + </port-component> + </session> + </enterprise-beans> + </jboss> + ]]></programlisting></para> + + <para>At last, make sure that the endpoint address in your WSDL file uses a secure protocol. + The easiest way is to add "https://" to the SOAP Address entry:</para> + + <para> + <programlisting><![CDATA[ + <service name="OrganizationService"> + <port name="BasicSecuredPort" binding="tns:OrganizationServiceBinding"> + <soap:address location="https://localhost:8443/ws4ee-samples-ejb/BasicSecured"/> + </port> + <port name="RoleSecuredPort" binding="tns:OrganizationServiceBinding"> + <soap:address location="https://localhost:8443/ws4ee-samples-ejb/RoleSecured"/> + </port> + </service> + ]]></programlisting></para> + + <para>For this to work the Tomcat+SSL connector must be enabled. + </para> + + <para> + <programlisting><![CDATA[ + <Connector port="8443" address="${jboss.bind.address}" + maxThreads="100" minSpareThreads="5" maxSpareThreads="15" + scheme="https" secure="true" clientAuth="want" + keystoreFile="${jboss.server.home.dir}/conf/keystores/wsse.keystore" + keystorePass="jbossws" + truststoreFile="${jboss.server.home.dir}/conf/keystores/wsse.keystore" + truststorePass="jbossws" + sslProtocol = "TLS" /> + ]]></programlisting></para> + + <para>For details see: <ulink url="http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html"/> + </para> + + <para>On the client side the truststore must be installed + </para> + + <para> + <programlisting><![CDATA[ + <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"/> + ]]></programlisting></para> + + <para>In case you see the following exception, you should disable URL checking on the client side + </para> + + <para> + <programlisting><![CDATA[ + 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) + ]]></programlisting></para> + + <para> + <programlisting><![CDATA[ + <sysproperty key="org.jboss.security.ignoreHttpsHost" value="true"/> + ]]></programlisting></para> + +</chapter> \ No newline at end of file Property changes on: trunk/docs/online/tutorial-doc/en/modules/secureejb/secure-ejb.xml ___________________________________________________________________ Name: svn:executable + * Added: trunk/docs/online/tutorial-doc/en/modules/wsaddressing/wsaddressing.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/wsaddressing/wsaddressing.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/wsaddressing/wsaddressing.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,231 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: wsaddressing.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $ --> + +<chapter id="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 staful service endpoint.</para> + + <para><command>Specifications</command></para> + + <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/aboutJava/communityprocess/edr/jsr261/"... + + <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> + <listitem> + <para><ulink url="http://www.jcp.org/aboutJava/communityprocess/edr/jsr261/"... - Java API for XML Web Services Addressing 1.0</ulink></para> + </listitem> + </itemizedlist> </para> + + <para>The following service endpoint interface (SEI) has a set of operation for a typical stateful shopping chart application.</para> + + <para> + <programlisting><![CDATA[ + public interface StatefulEndpoint extends Remote + { + public void addItem(String item) throws RemoteException; + + public void checkout() throws RemoteException; + + public String getItems() throws RemoteException; + } + ]]></programlisting></para> + + <para><command>The endpoint implementation bean</command></para> + + <para>We use JSR-181 annotations for the endpoint implementation bean. The endpoint handler chain is comprised of two + handlers. The first handler (org.jboss.ws.addressing.soap.SOAPServerHandler) processes the incomming WS-Addressing header elements + and provides access to them through the JSR-261 API. + The second handler (org.jboss.test.ws.samples.wsaddr.ServerHandler) is application specific and assignes/processes stateful client ids.</para> + + <para> + <programlisting><![CDATA[ + @WebService(name = "StatefulEndpoint", + targetNamespace = "http://org.jboss.ws/samples/wsaddr", serviceName = "TestService") + @SOAPBinding(style = SOAPBinding.Style.RPC) + @SOAPMessageHandlers( { + @SOAPMessageHandler(className = "org.jboss.ws.addressing.soap.SOAPServerHandler"), + @SOAPMessageHandler(className = "org.jboss.test.ws.samples.wsaddr.ServerHandler") + }) + public class StatefulEndpointImpl implements StatefulEndpoint, ServiceLifecycle + { + @WebMethod + public void addItem(String item) + { ... } + + @WebMethod + public void checkout() + { ... } + + @WebMethod + public String getItems() + { ... } + } + ]]></programlisting></para> + + <para>On the client side there is a simmilar handler that does the reverse. + It uses the <ulink url="http://www.jcp.org/en/jsr/detail?id=261">JavaTM API for XML Web Services Addressing (JSR-261)</ulink> to add WS-Addressing header elements including the clientid association.</para> + + <para>Generating the client side artifacts is equivalent to <link linkend="jsr181-pojo-endpoint">JSR-181 POJO Endpoints</link></para> + + <para><command>Server side handler configuration</command></para> + + <para>The stateful addressing example uses an JSR-181 endpoinhttp://www.jcp.org/en/jsr/detail?id=261t with the following handler configuration.</para> + + <para> + <programlisting><![CDATA[ + @WebService + @SOAPBinding(style = SOAPBinding.Style.RPC) + @SOAPMessageHandlers( { + @SOAPMessageHandler(className = "org.jboss.ws.addressing.soap.SOAPServerHandler"), + @SOAPMessageHandler(className = "org.jboss.test.ws.jaxrpc.samples.wsaddressing.ServerHandler") + }) + public class StatefulEndpointImpl implements StatefulEndpoint, ServiceLifecycle + { + ... + } + ]]></programlisting></para> + + <para>The <ulink url="http://fisheye.jboss.com/viewrep/JBossWS/trunk/src/main/java/or... + is provided by JBossWS and <emphasis>reads/writes the addressing properties and puts then into the message context</emphasis>. + </para> + + <para>The <ulink url="http://fisheye.jboss.com/viewrep/JBossWS/trunk/src/test/java/or... + is implementation specific.</para> + + <para><command>Client side handler configuration</command></para> + + <para>The client uses a predifined handler configuration in jboss-client.xml</para> + + <para> + <programlisting><![CDATA[ + <jboss-client> + <jndi-name>jbossws-client</jndi-name> + <service-ref> + <service-ref-name>service/TestService</service-ref-name> + <config-name>Standard Addressing Client</config-name> + </service-ref> + </jboss-client> + ]]></programlisting></para> + + <para>The standard client configurations are defined in standard-jbossws-client-config.xml</para> + + <para> + <programlisting><![CDATA[ + <jboss-client> + <jndi-name>jbossws-client</jndi-name> + <service-ref> + <service-ref-name>service/TestService</service-ref-name> + <config-name>Standard Addressing Client</config-name> + </service-ref> + </jboss-client> + ]]></programlisting></para> + + <para>The <ulink url="http://fisheye.jboss.com/viewrep/JBossWS/trunk/src/main/java/or... + is provided by JBossWS and <emphasis>reads/writes the addressing properties and puts then into the message context</emphasis>. + </para> + + <para>The <ulink url="http://fisheye.jboss.com/viewrep/JBossWS/trunk/src/test/java/or... + is implementation specific.</para> + + <para><command>A client connecting to the stateful endpoint</command></para> + + <para> + <programlisting><![CDATA[ + public class AddressingStatefulTestCase extends JBossWSTest + { + ... + + public void testAddItem() throws Exception + { + client1.addItem("Ice Cream"); + client1.addItem("Ferrari"); + + client2.addItem("Mars Bar"); + client2.addItem("Porsche"); + } + + public void testGetItems() throws Exception + { + String items1 = client1.getItems(); + assertEquals("[Ice Cream, Ferrari]", items1); + + String items2 = client2.getItems(); + assertEquals("[Mars Bar, Porsche]", items2); + } + } + ]]></programlisting></para> + + <para><command>SOAP message exchange</command></para> + + <para>Below you see the SOAP messages that are beeing exchanged. </para> + + <para> + <programlisting><![CDATA[ + + <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'> + <env:Header xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'> + <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='http://somens'>clientid-1</ns1:clientid> + </wsa:ReferenceParameters> + </env:Header> + <env:Body> + <ns1:addItem xmlns:ns1='http://org.jboss.ws/samples/wsaddr'> + <String_1>Ice Cream</String_1> + </ns1:addItem> + </env:Body> + </env:Envelope> + + <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'> + <env:Header xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'> + <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='http://somens'>clientid-1</ns1:clientid> + </env:Header> + <env:Body> + <ns1:addItemResponse xmlns:ns1='http://org.jboss.ws/samples/wsaddr'/> + </env:Body> + </env:Envelope> + + ... + + <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'> + <env:Header xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'> + <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='http://somens'>clientid-1</ns1:clientid> + </wsa:ReferenceParameters> + </env:Header> + <env:Body> + <ns1:getItems xmlns:ns1='http://org.jboss.ws/samples/wsaddr'/> + </env:Body> + </env:Envelope> + + <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'> + <env:Header xmlns:wsa='http://schemas.xmlsoap.org/ws/2004/08/addressing'> + <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='http://somens'>clientid-1</ns1:clientid> + </env:Header> + <env:Body> + <ns1:getItemsResponse xmlns:ns1='http://org.jboss.ws/samples/wsaddr'> + <result>[Ice Cream, Ferrari]</result> + </ns1:getItemsResponse> + </env:Body> + </env:Envelope> + + ]]></programlisting></para> + +</chapter> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/wseventing/wseventing.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/wseventing/wseventing.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/wseventing/wseventing.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,383 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: wseventing.xml 284 2006-05-05 23:26:06Z jason.greene(a)jboss.com $ --> + +<chapter id="wseventing"> + <title>WS-Eventing</title> + + <sect1 id="eventing-welcome"> + <title>Introduction</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> + + <para><command>Specifications</command></para> + + <para>WS-Eventing is defined by the combination of the following specifications:</para> + + <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> + <emphasis role="bold">NOTE:</emphasis>The original eventing specification builds upon WS-Addressing 2004/08. + JBossWS however decided to stick to the latest version, which is the W3C candidate release. + Eventing was submitted to the W3C in March 2006 and it's expected that the TC will follow this path as well. + </para> + </para> + </listitem> + </itemizedlist> + </para> + </sect1> + + <sect1 id="eventing-introduction"> + <title>Eventing collaboration</title> + + <para> + The following section will introduce the main eventing actors and their responsiblities. + </para> + + <para> + <figure id="EventingCollaboration.fig"> + <title>Eventing collaboration</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/EventingCollaboration.gif"/> + </imageobject> + </mediaobject> + </figure> + + <para> + <orderedlist> + <listitem> + <para> + An event sink (web service client) sends a subscribtion request to the event source endpoint. + This includes the event sink endpoint address where notifications should delivered. + Upon successful subscription the sink receives a leased subscription ID that can be used to identify the client + in subsequent requests. + </para> + </listitem> + <listitem> + <para> + A successfully registered event sink directs management requests (Renew, GetStatus, Unsubscribe) + to the subscription manager endpoint using the previously received subscription ID. + The subscription manager endpoint address was returned as part of the subscription response + in the first place. + </para> + </listitem> + <listitem> + <para> + The actual event sink (application) emits notification messages through the JBossWS-Eventing module. + JBossWS-Eventing dispatches the notification to any subscriber endpoint + that is registered with a particular event source.s + </para> + </listitem> + <listitem> + <para> + Besides notifications JBossWS-Eventing may emit lifecycle events at any time, + i.e. to inform an event sink that a subscription was canceled. + This can be the case when the subscription expired or the event source was undeployed. + </para> + </listitem> + </orderedlist> + </para> + </para> + + </sect1> + + <sect1 id="eventing-deployment"> + <title>Event source deployment</title> + + <para> + It is the users responsibilty to supply the web service endpoints (EventSourceEndpoint, SubscriptionManagerEndpoint) + that are required for a complete event source deployment. + Fortunatly JBossWS-Eventing already ships with a implementation that can be used right away. + All that's left todo is packaging of standard JSR-109 deployment archive that includes + the event source specific WSDL and points to the JBossWS-Eventing endpoint implementations. + </para> + + <para> + The relevant steps are: + + <itemizedlist> + <listitem> + <para> + Create a custom WSDL that describes your event source, in respect to the notification schema (1) + and the fact that is actually contains an event source port (2)</para> + </listitem> + <listitem> + <para>Use the JBossWS SEI (3) and endpoint (4) implementations (webservices.xml, web.xml).</para> + </listitem> + </itemizedlist> + </para> + + <para><command>The WSDL that describes an event source</command></para> + + <para> + + The following excerpt shows the relevant WSDL details that describe an event source. + + <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> + + <programlisting><![CDATA[ + + <?xml version="1.0" encoding="UTF-8"?> + + <wsdl:definitions + targetNamespace="http://www.jboss.org/sysmon" + xmlns:tns="http://www.jboss.org/sysmon" + xmlns:wse='http://schemas.xmlsoap.org/ws/2004/08/eventing' + xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/' + xmlns:wsa10='http://www.w3.org/2005/08/addressing' + xmlns:xs='http://www.w3.org/2001/XMLSchema' + xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"> + + <wsdl:import +(1) namespace='http://schemas.xmlsoap.org/ws/2004/08/eventing' + location='jbwse.wsdl' /> + + <wsdl:types> + + <xs:schema targetNamespace='http://schemas.xmlsoap.org/ws/2004/08/eventing'> +(2) <xs:include schemaLocation='jbwse.xsd'/> + </xs:schema> + +(3) <xs:schema + targetNamespace="http://www.jboss.org/sysmon" + elementFormDefault="qualified" + blockDefault="#all"> + <xs:element name="SystemStatus"> + <xs:complexType> + <xs:sequence> + <xs:element name="Time " type="xs:dateTime"/> + <xs:element name="HostName" type="xs:string"/> + <xs:element name="HostAddress" type="xs:string"/> + <xs:element name="ActiveThreadCount" type="xs:int"/> + <xs:element name="FreeMemory" type="xs:string"/> + <xs:element name="MaxMemory" type="xs:string"/> + </xs:sequence> + </xs:complexType> + </xs:element> + </xs:schema> + + </wsdl:types> + + <wsdl:message name='SystemInfoMsg'> + <wsdl:part name='body' element='tns:SystemStatus'/> + </wsdl:message> + +(4) <wsdl:portType name='SystemInfo' wse:EventSource='true'> + <wsdl:operation name='SysmonOp'> + <wsdl:output message='tns:SystemInfoMsg'/> + </wsdl:operation> + </wsdl:portType> + + <wsdl:binding name="SystemInfoBinding" type="tns:SystemInfo"> + <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> + <wsdl:operation name="SysmonOp"> + <soap:operation soapAction=""/> + <wsdl:output> + <soap:body use="literal"/> + </wsdl:output> + </wsdl:operation> + </wsdl:binding> + +</wsdl:definitions> + ]]></programlisting> + + </para> + + + <para><command>The JBossWS service endpoint interface</command></para> + <para> + Within webservices.xml simply refer to the JBossWS-Eventing SEI that ships with JBossWS. + + <programlisting><![CDATA[ + <port-component> + <port-component-name>SubscriptionManagerPort</port-component-name> + <wsdl-port>wsdl:SubscriptionManagerPort</wsdl-port> +(3) <service-endpoint-interface> + org.jboss.ws.eventing.SubscriptionManagerEndpoint + </service-endpoint-interface> + <service-impl-bean> + <servlet-link>SubscriptionManagerServlet</servlet-link> + </service-impl-bean> + + <handler> + <handler-name> + org.jboss.ws.addressing.soap.SOAPServerHandler + </handler-name> + <handler-class> + org.jboss.ws.addressing.soap.SOAPServerHandler + </handler-class> + </handler> + + </port-component> + + <port-component> + <port-component-name>EventSourcePort</port-component-name> + <wsdl-port>wsdl:EventSourcePort</wsdl-port> +(3) <service-endpoint-interface> + org.jboss.ws.eventing.EventSourceEndpoint + </service-endpoint-interface> + <service-impl-bean> + <servlet-link>EventSourceServlet</servlet-link> + </service-impl-bean> + + <handler> + <handler-name> + org.jboss.ws.addressing.soap.SOAPServerHandler + </handler-name> + <handler-class> + org.jboss.ws.addressing.soap.SOAPServerHandler + </handler-class> + </handler> + + </port-component> + ]]></programlisting> + </para> + + <para><command>The JBossWS service endpoint implementation</command></para> + <para> + Within web.xml use the endpoint implementations that ship with JBossWS. + + <programlisting><![CDATA[ + <servlet> + <servlet-name>EventSourceServlet</servlet-name> +(4) <servlet-class> + org.jboss.ws.eventing.EventSourceEndpointImpl + </servlet-class> + <load-on-startup>0</load-on-startup> + </servlet> + <servlet-mapping> + <servlet-name>EventSourceServlet</servlet-name> + <url-pattern>/subscribe</url-pattern> + </servlet-mapping> + + <servlet> + <servlet-name>SubscriptionManagerServlet</servlet-name> +(4) <servlet-class> + org.jboss.ws.eventing.SubscriptionManagerEndpointImpl + </servlet-class> + <load-on-startup>0</load-on-startup> + </servlet> + <servlet-mapping> + <servlet-name>SubscriptionManagerServlet</servlet-name> + <url-pattern>/manage</url-pattern> + </servlet-mapping> + ]]></programlisting> + </para> + + </sect1> + + <sect1 id="eventing-notification"> + <title>Sending notifications from applications</title> + <para> + JBossWS-Eventing registeres a event dispatcher within local JNDI tree + that can be used to emit notifications from applications. + <programlisting><![CDATA[ + java:/EventDispatcher + ]]></programlisting> + </para> + + <para> + The event dispatcher interface: + <programlisting><![CDATA[ + public interface EventDispatcher + { + void dispatch(URI eventSourceNS, Element payload); + } + ]]></programlisting> + </para> + + <para> + <command>Example notification</command>: + <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> + + + <programlisting><![CDATA[ + +(1) URI eventSourceURI = new URI("http://http://www.jboss.org/sysmon/SystemInfo"); +(2) Element payload = DOMUtils.parse("SOME XML STRING"); + try + { + InitialContext iniCtx = getInitialContext(); +(3) EventDispatcher delegate = (EventDispatcher) + iniCtx.lookup(EventingConstants.DISPATCHER_JNDI_NAME); +(4) delegate.dispatch(eventSourceURI, payload); + } + catch (Exception e) + { + // + } + + ]]></programlisting> + </para> + + </sect1> + + <sect1 id="eventing-manager"> + <title>The SubscriptionManager MBean</title> + <para> + The SubscriptionManager MBean is the actual core component that drives the JBossWS-Eventing implementation. + It can be accessed through the jmx-console. + <programlisting><![CDATA[ + jboss.ws.eventing:service=SubscriptionManager + ]]></programlisting> + + </para> + + <para> + Management operations exist to monitor and maintain active subscritions and deployed event sources. + The current implementation is backed by a ThreadPoolExecutor, that asynchronously delivers messages to event sink endpoints. + It can be configured through the following attributes: + + <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> + </sect1> +</chapter> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/wssecurity/wssecurity.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/wssecurity/wssecurity.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/wssecurity/wssecurity.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,358 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: wssecurity.xml 938 2006-09-11 15:17:07Z thomas.diesler(a)jboss.com $ --> + +<chapter id="wssecurity"> + + <title>WS-Security</title> + + <para>WS-Security 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><command>Specifications</command></para> + + <para>WS-Security is defined by the combination of the following specifications:</para> + + <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/oasis-200401-wss-usernam... 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> </para> + + <sect1> + <title>Generating required deployment artifacts</title> + + <para> Lets start with a trivial service endpoint interface (SEI) that echos a user defined type.</para> + + <para> + <programlisting><![CDATA[ + public interface Hello extends Remote + { + public UserType echoUserType(UserType in0) throws RemoteException; + } + ]]></programlisting></para> + + + <para>Run wstools with the following configuration</para> + + <para> + <programlisting><![CDATA[ + <configuration ...> + <java-wsdl> + <service name="HelloService" style="rpc" + endpoint="org.jboss.test.ws.jaxrpc.samples.wssecurity.Hello"/> + + <namespaces target-namespace="http://org.jboss.ws/samples/wssecurity" + type-namespace="http://org.jboss.ws/samples/wssecurity/types"/> + + <mapping file="jaxrpc-mapping.xml"/> + <webservices servlet-link="HelloService"/> + </java-wsdl> + </configuration> + ]]></programlisting></para> + </sect1> + + <sect1> + <title>Configuration and setup</title> + + <sect2> + <title>Enable security processing</title> + <para> + JBossWS uses generic <link linkend="handlers">JAXRPC handlers</link> to identify ws-security encoded requests + and invoke the security components to sign and encrypt messages. In order to enable security processing, + the client and server side need to include a corressponding handler configuration. The preferred way is to reference + a <link linkend="template-config">predefined endpoint configuration</link> (excerpt from WEB-INF/web.xml): + + <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"> + + <context-param> + (1) <param-name>jbossws-config-name</param-name>> + (2) <param-value>Standard Secure Endpoint</param-value> + </context-param> + + <servlet> + <servlet-name>HelloService</servlet-name> + <servlet-class>org.jboss.test.ws.jaxrpc.samples.wssecurity.HelloJavaBean</servlet-class> + </servlet> + <servlet-mapping> + <servlet-name>HelloService</servlet-name> + <url-pattern>/*</url-pattern> + </servlet-mapping> +</web-app> ]]></programlisting> + + <orderedlist> + <listitem> + <para> + JBossWS specific context param + </para> + </listitem> + <listitem> + <para> + Point it to 'Standard Secure Endpoint' + </para> + </listitem> + </orderedlist> + </para> + + <para> + Or the equivalent on the client side (excerpt from META-INF/jboss-client.xml): + <programlisting><![CDATA[ +<jboss-client> + <jndi-name>jbossws-client</jndi-name> + + <service-ref> + <service-ref-name>service/HelloService</service-ref-name> + (1) <config-name>Standard Secure Client</config-name> + <wsdl-override>http://@jbosstest.host.name@:8080/jbossws-samples-wssecurity-encrypt?wsdl</wsdl-override> + </service-ref> + +</jboss-client> + ]]></programlisting> + + <orderedlist> + <listitem> + <para> + JBossWS configuration. Point it to 'Standard Secure Client' + </para> + </listitem> + </orderedlist> + </para> + + <sect3> + <title>Security processing with JSR-181 endpoints</title> + <para> + With JSR-181 endpoints we can't directly reference a predefined endpoint configuration, + therefore we have to reference the necessary handlers directly to be able to process WSSE messages: + + <programlisting><![CDATA[ +[...] +(1) @HandlerChain(file = "resource://config/ServerHandlers.xml", name = "SecureHandlerChain") +public class EJB3Bean01 implements EJB3RemoteInterface +{ + @WebMethod + public String echo(String input) + { + return input; + } +} + ]]></programlisting> + + <orderedlist> + <listitem> + <para> + Reference to handler configuration file that specifies the WSSE handlers needed + </para> + </listitem> + </orderedlist> + + <note><para>These excerpts are taken from the JSR181 ejb endpoint examples shipped with the distribution</para></note> + + Contents of the ServerHandler.xml file referenced above: + <programlisting><![CDATA[ +<?xml version="1.0" encoding="UTF-8"?> + +<handler-config> + <handler-chain> + <handler-chain-name>SecureHandlerChain</handler-chain-name> + <handler> + <handler-name>WSSecurityHandlerInbound</handler-name> + <handler-class>org.jboss.ws.wsse.WSSecurityHandlerInbound</handler-class> + </handler> + </handler-chain> +</handler-config> + ]]></programlisting> + + </para> + </sect3> + </sect2> + + <sect2> + <title>Configure the WS-Security implementation</title> + Once you enabled security processing, it's time configure the ws-security implementation. + Both client and server require configuration files that specify key-store, trust-store + and various other ws-security specific options. + + <para><command>Server side configuration (jboss-wsse-server.xml)</command></para> + + <para>In this example we configure both the client and the server to sign the message body. + Both also require this from each other. So, if you remove either the client or the server security deployment descriptor, + you will notice that the other party will throw a fault explaining that the message did not conform to the proper security requirements.</para> + + <para> + <programlisting><![CDATA[ + <jboss-ws-security xmlns="http://www.jboss.com/ws-security/config" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.jboss.com/ws-security/config + http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd"> + (1) <key-store-file>WEB-INF/wsse.keystore</key-store-file> + (2) <key-store-password>jbossws</key-store-password> + (3) <trust-store-file>WEB-INF/wsse.truststore</trust-store-file> + (4) <trust-store-password>jbossws</trust-store-password> + (5) <config> + (6) <sign type="x509v3" alias="wsse"/> + (7) <requires> + (8) <signature/> + </requires> + </config> + </jboss-ws-security> + ]]></programlisting></para> + + <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 encypted using the {EXT} and {CLASS} commands. Please see samples for their usage.</para> + </listitem> + <listitem> + <para>Here we start our root config block. The root config block is the default configuration for all services in this war file.</para> + </listitem> + <listitem> + <para>This means that the server must sign the message body of all responses. Type means that we are to use a X.509v3 certificate (a standard certificate). The alias option says that the certificate/key pair to use for signing is in the key store under the "wsse" alias</para> + </listitem> + <listitem> + <para>Here we start our optional requires block. This block specifies all security requirements that must be met when the server receives a message.</para> + </listitem> + <listitem> + <para> This means that all web services in this war file require the message body to be siged.</para> + </listitem> + </orderedlist> + </para> + </sect2> + + + <para><command>Client configuration (jboss-wsse-client.xml)</command></para> + + <para> + <programlisting><![CDATA[ + <jboss-ws-security xmlns="http://www.jboss.com/ws-security/config" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.jboss.com/ws-security/config + http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd"> + (1) <config> + (2) <sign type="x509v3" alias="wsse"/> + (3) <requires> + (4) <signature/> + </requires> + </config> + </jboss-ws-security> + ]]></programlisting></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>We did not specify a key store or trust store, because client apps instead use the wsse System properties instead. If this was a web or ejb client (meaning a webservice client in a war or ejb jar file), then we would have specified them in the client descriptor.</para> + + </sect1> + + <sect1> + <title>SOAP message exchange</title> + + <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> + <programlisting><![CDATA[ + Incomming SOAPMessage + + <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> + <env:Header> + <wsse:Security env:mustUnderstand="1" ...> + <wsu:Timestamp wsu:Id="timestamp">...</wsu:Timestamp> + <wsse:BinarySecurityToken ...> + ... + </wsse:BinarySecurityToken> + <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> + ... + </ds:Signature> + </wsse:Security> + </env:Header> + <env:Body wsu:Id="element-1-1140197309843-12388840" ...> + <ns1:echoUserType xmlns:ns1="http://org.jboss.ws/samples/wssecurity"> + <UserType_1 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> + <msg>Kermit</msg> + </UserType_1> + </ns1:echoUserType> + </env:Body> + </env:Envelope> + ]]></programlisting></para> + + </sect1> + + <sect1> + <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> + + <para> + <programlisting><![CDATA[ + security.provider.<n>=org.bouncycastle.jce.provider.BouncyCastleProvider + ]]></programlisting></para> + + <para> + Where &lt;n&gt; is the preference you want the provider at. + <note><para>Issues may arise if the Sun provided providers are not first.</para></note> + </para> + + <para> + Where you put the jar is up to mostly up to you, although with jdk1.4 the best + (and in some cases only) place to have it is in $JAVA_HOME/jre/lib/ext. + Under Windows there will normally be a JRE and a JDK install of Java if you think you have installed it + correctly and it still doesn't work chances are you have added the provider to the installation not being used. + </para> + </sect1> +</chapter> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/wstransaction/wstransaction.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/wstransaction/wstransaction.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/wstransaction/wstransaction.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,15 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- $Id: wstransaction.xml 284 2006-05-05 23:26:06Z jason.greene(a)jboss.com $ --> + +<chapter id="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> + +</chapter> \ No newline at end of file Added: trunk/docs/online/tutorial-doc/en/modules/xmlregistry/xmlregistry.xml =================================================================== --- trunk/docs/online/tutorial-doc/en/modules/xmlregistry/xmlregistry.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-doc/en/modules/xmlregistry/xmlregistry.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,416 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- $Id: xmlregistry.xml 284 2006-05-05 23:26:06Z jason.greene(a)jboss.com $ --> +<chapter id="xmlregistry"> + <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> + + <para><command>Apache jUDDI Configuration</command></para> + + <para>Configuration of the jUDDI registry happens via an MBean Service that + is deployed in the juddi-service.sar archive in the "all" configuration. The + configuration of this service can be done in the jboss-service.xml of the + META-INF directory in the juddi-service.sar</para> + + <para>Let us look at the individual configuration items that can be + changed.</para> + + <itemizedlist> + <listitem> + <para>DataSources configuration</para> + + <programlisting>&lt;!-- Datasource to Database--&gt; +&lt;attribute name="DataSourceUrl"&gt;java:/DefaultDS&lt;/attribute&gt;</programlisting> + </listitem> + + <listitem> + <para>Database Tables (Should they be created on start, Should they be + dropped on stop, Should they be dropped on start etc)</para> + + <programlisting>&lt;!-- Should all tables be created on Start--&gt; +&lt;attribute name="CreateOnStart"&gt;false&lt;/attribute&gt; +&lt;!-- Should all tables be dropped on Stop--&gt; +&lt;attribute name="DropOnStop"&gt;true&lt;/attribute&gt; +&lt;!-- Should all tables be dropped on Start--&gt; +&lt;attribute name="DropOnStart"&gt;false&lt;/attribute&gt;</programlisting> + </listitem> + + <listitem> + <para>JAXR Connection Factory to be bound in JNDI. (Should it be bound? + and under what name?)</para> + + <programlisting>&lt;!-- Should I bind a Context to which JaxrConnectionFactory bound--&gt; +&lt;attribute name="ShouldBindJaxr"&gt;true&lt;/attribute&gt; + +&lt;!-- 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 --&gt; +&lt;attribute name="BindJaxr"&gt;JAXR&lt;/attribute&gt;</programlisting> + </listitem> + </itemizedlist> + + <para>Other common configuration:</para> + + <itemizedlist> + <listitem> + <para>Add authorized users to access the jUDDI registry. (Add a sql + insert statement in a single line)</para> + + <programlisting>Look at the script META-INF/ddl/juddi_data.ddl for more details. Example for a user 'jboss' + +INSERT INTO PUBLISHER (PUBLISHER_ID,PUBLISHER_NAME, +EMAIL_ADDRESS,IS_ENABLED,IS_ADMIN) +VALUES ('jboss','JBoss User','jboss@xxx','true','true');</programlisting> + </listitem> + </itemizedlist> + + <para><command>JBoss JAXR Configuration</command></para> + + <para>In this section, we will discuss the configuration needed to run the + JAXR API. The JAXR configuration relies on System properties passed to the + JVM. The System properties that are needed are:</para> + + <para><programlisting>javax.xml.registry.ConnectionFactoryClass=org.apache.ws.scout.registry.ConnectionFactoryImpl +jaxr.query.url=http://localhost:8080/juddi/inquiry +jaxr.publish.url=http://localhost:8080/juddi/publish +juddi.proxy.transportClass=org.jboss.jaxr.juddi.transport.SaajTransport</programlisting></para> + + <para>Please remember to change the hostname from "localhost" to the + hostname of the UDDI service/JBoss Server.</para> + + <para>You can pass the System Properties to the JVM in the following + ways:</para> + + <itemizedlist> + <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> + + <programlisting>System.setProperty(propertyname, propertyvalue);</programlisting> + </listitem> + </itemizedlist> + + <para><command>JAXR Sample Code</command></para> + + <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... + + <para>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... + + <para>From J2EE 1.4 JavaDoc: "The BusinessLifeCycleManager interface, + which is exposed by the Registry Service, implements the life cycle + management functionality of the Registry as part of a business level + API. Note that there is no authentication information provided, because + the Connection interface keeps that state and context on behalf of the + client."</para> + </listitem> + + <listitem> + <para><ulink + url="http://java.sun.com/j2ee/1.4/docs/api/javax/xml/registry/Busine... + + <para>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> + + <itemizedlist> + <listitem> + <para>Getting a JAXR Connection to the registry.</para> + + <programlisting>String queryurl = System.getProperty("jaxr.query.url"); +String puburl = System.getProperty("jaxr.publish.url"); + +//Standard JAXR ConnectionFactory properties +Properties props = new Properties(); +props.setProperty("javax.xml.registry.queryManagerURL", + queryurl); +props.setProperty("javax.xml.registry.lifeCycleManagerURL", + puburl); + +//JBoss JAXR property +String transportClass = System.getProperty("juddi.proxy.transportClass", + "org.jboss.jaxr.juddi.transport.SaajTransport"); +System.setProperty("juddi.proxy.transportClass", transportClass); + +ConnectionFactory factory = null; + +try +{ + // Create the connection, passing it the configuration properties + factory = ConnectionFactory.newInstance(); + factory.setProperties(props); + connection = factory.createConnection(); +}catch(JAXRException je){}</programlisting> + </listitem> + + <listitem> + <para>Authentication with the registry.</para> + + <programlisting>/** + * Does authentication with the uddi registry + */ + protected void login() + { + PasswordAuthentication passwdAuth = new PasswordAuthentication(userid, + passwd.toCharArray()); + Set creds = new HashSet(); + creds.add(passwdAuth); + + try + { + //Set the credentials on the connection + connection.setCredentials(creds); + } catch (JAXRException e) + { + } + }</programlisting> + </listitem> + + <listitem> + <para>Save a Business</para> + + <programlisting>//Method that creates a Test JAXR Organization +protected Organization createOrganization(String orgname) +throws JAXRException +{ + Organization org = blm.createOrganization(getIString(orgname)); + org.setDescription(getIString("JBoss Inc")); + Service service = blm.createService(getIString("JBOSS JAXR Service")); + service.setDescription(getIString("Services of XML Registry")); + //Create serviceBinding + ServiceBinding serviceBinding = blm.createServiceBinding(); + serviceBinding.setDescription(blm. + createInternationalString("Test Service Binding")); + + //Turn validation of URI off + serviceBinding.setValidateURI(false); + serviceBinding.setAccessURI("http://testjboss.org"); + + // Add the serviceBinding to the service + service.addServiceBinding(serviceBinding); + + User user = blm.createUser(); + org.setPrimaryContact(user); + PersonName personName = blm.createPersonName("Anil S"); + TelephoneNumber telephoneNumber = blm.createTelephoneNumber(); + telephoneNumber.setNumber("111-111-7777"); + telephoneNumber.setType(null); + PostalAddress address + = blm.createPostalAddress("111", + "My Drive", "BuckHead", + "GA", "USA", "1111-111", ""); + Collection postalAddresses = new ArrayList(); + postalAddresses.add(address); + Collection emailAddresses = new ArrayList(); + EmailAddress emailAddress = blm.createEmailAddress(&quot;anil(a)jboss.com&quot;); + emailAddresses.add(emailAddress); + + Collection numbers = new ArrayList(); + numbers.add(telephoneNumber); + user.setPersonName(personName); + user.setPostalAddresses(postalAddresses); + user.setEmailAddresses(emailAddresses); + user.setTelephoneNumbers(numbers); + + ClassificationScheme cScheme = getClassificationScheme("ntis-gov:naics", ""); + Key cKey = blm.createKey("uuid:C0B9FE13-324F-413D-5A5B-2004DB8E5CC2"); + cScheme.setKey(cKey); + Classification classification = blm.createClassification(cScheme, + "Computer Systems Design and Related Services", + "5415"); + org.addClassification(classification); + ClassificationScheme cScheme1 = getClassificationScheme("D-U-N-S", ""); + Key cKey1 = blm.createKey("uuid:3367C81E-FF1F-4D5A-B202-3EB13AD02423"); + cScheme1.setKey(cKey1); + ExternalIdentifier ei = + blm.createExternalIdentifier(cScheme1, "D-U-N-S number", + "08-146-6849"); + org.addExternalIdentifier(ei); + org.addService(service); + return org; +} + +/**Method that saves the JAXR Organization in the UDDI registry */ +protected void saveTestBusiness() throws Exception +{ + String keyid = ""; + login(); + try + { + //Obtain the BusinessLifeCycleManager + getJAXREssentials(); + Collection orgs = new ArrayList(); + Organization org = createOrganization("JBOSS"); + + orgs.add(org); + BulkResponse br = blm.saveOrganizations(orgs); + if (br.getStatus() == JAXRResponse.STATUS_SUCCESS) + { + Collection coll = br.getCollection(); + Iterator iter = coll.iterator(); + while (iter.hasNext()) + { + Key key = (Key) iter.next(); + keyid = key.getId(); + assertNotNull(keyid); + orgKey = key; + }//end while + } else + { + Collection exceptions = br.getExceptions(); + Iterator iter = exceptions.iterator(); + while (iter.hasNext()) + { + Exception e = (Exception) iter.next(); + fail(e.toString()); + } + } + } catch (JAXRException e) + { + } +}</programlisting> + </listitem> + + <listitem> + <para>Query a Business</para> + + <programlisting>public void searchBusiness(String bizname) +throws JAXRException +{ + try + { + // Get registry service and business query manager + rs = connection.getRegistryService(); + bqm = rs.getBusinessQueryManager(); + + // Define find qualifiers and name patterns + Collection findQualifiers = new ArrayList(); + findQualifiers.add(FindQualifier.SORT_BY_NAME_ASC); + Collection namePatterns = new ArrayList(); + namePatterns.add("%" + bizname + "%"); + + // Find based upon qualifier type and values + BulkResponse response = + bqm.findOrganizations(findQualifiers, + namePatterns, + null, + null, + null, + null); + + // check how many organisation we have matched + Collection orgs = response.getCollection(); + if (orgs == null) + { + if ("true".equalsIgnoreCase(debugProp)) + System.out.println(" -- Matched 0 orgs"); + } else + { + if ("true".equalsIgnoreCase(debugProp)) + System.out.println(" -- Matched " + orgs.size() + " organizations -- "); + // then step through them + for (Iterator orgIter = orgs.iterator(); orgIter.hasNext();) + { + Organization org = (Organization) orgIter.next(); + if ("true".equalsIgnoreCase(debugProp)) + { + System.out.println("Org name: " + getName(org)); + System.out.println("Org description: " + getDescription(org)); + System.out.println("Org key id: " + getKey(org)); + } .....</programlisting> + </listitem> + </itemizedlist> + + <para>For more examples of code using the JAXR API, please refer to the + resources in the Resources Section.</para> + + <para><command>Trouble Shooting</command></para> + + <itemizedlist> + <listitem> + <para>I cannot connect to the registry from JAXR.</para> + + <para>Please check the inquiry and publish url passed to the JAXR + ConnectionFactory.</para> + </listitem> + + <listitem> + <para>I cannot connect to the jUDDI registry.</para> + + <para>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.</para> + + <para>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.</para> + + <para>Please use the tcpmon tool to view the messages in transit. <ulink + url="https://tcpmon.dev.java.net/">TCPMon</ulink></... + </listitem> + </itemizedlist> + + <para><command>Resources</command></para> + + <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>J2EE Web Services by Richard Monson-Haefel</para> + </listitem> + </itemizedlist> +</chapter> Added: trunk/docs/online/tutorial-src/jax-ws-hello-world/build.xml =================================================================== --- trunk/docs/online/tutorial-src/jax-ws-hello-world/build.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-src/jax-ws-hello-world/build.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,98 @@ +<?xml version="1.0"?> +<!-- Build file for JSR 181 POJO Hello World Web Service Example using new WS Stack --> +<project name="JSR 181 POJO Hello World Web Service Buildfile" default="main" basedir="."> +<!-- Standard Properties --> + <property name="top.dir" value="${basedir}"/> + <property name="user.home.dir" value="/Users/sgriffith/"/> + <property name="server.config" value="default"/> + <property name="top.dir" value="."/> + <property name="src.dir" value="${top.dir}/src"/> + <property name="build.classes" value="${top.dir}/classes"/> + <property name="java.dir" value="${top.dir}/src/java"/> + <property name="resources.dir" value="${top.dir}/resources"/> + <property name="jboss.dir" value="${user.home.dir}/jboss-4.0.4.GA-ejb3"/> + <property name="jboss.client" value="${jboss.dir}/client"/> + <property name="jboss.lib" value="${jboss.dir}/lib"/> + <property name="jboss.server" value="${jboss.dir}/server/${server.config}"/> + <property name="jboss.server.lib" value="${jboss.server}/lib"/> + <property name="jboss.server.deploy" value="${jboss.server}/deploy"/> + +<!-- JDK Detection --> + <available classname="java.lang.Enum" property="HAVE_JDK_1.5"/> + +<!-- Check for new WS jar file --> + <available file="${jboss.client}/jbossws-client.jar" value="jbossws-client.jar" property="jbossws.client.jar"/> + +<!-- Mapper definitions --> +<!-- <mapper id="deployedFileMapper" type="regexp" from="*hello*.war"/> --> + <available property="jbossws.client.jar" value="jbossws-client.jar" file="${jboss.client}/jbossws-client.jar"/> + +<!-- Path Definitions --> + <path id="client.classpath"> + <fileset dir="${jboss.client}"> + <include name="*.jar"/> + </fileset> + </path> + <path id="compile.classpath"> + <path refid="client.classpath"/> + <pathelement location="${jboss.server.lib}/jboss.jar"/> + </path> + +<!-- Targets --> + <target name="generate-sources" depends="" description="Generate the deployment resources." if="HAVE_JDK_1.5"> +<!-- Define a taskdef for the wstools ant task --> + <echo message="Inside generate-sources"/> + <taskdef name="wstools" classname="org.jboss.ws.tools.ant.wstools"> + <classpath refid="client.classpath"/> + <classpath path="${top.dir}/classes"/> + <classpath path="${top.dir}"/> + </taskdef> + <echo message="wstools about to run"/> + <wstools dest="${top.dir}/META-INF" config="${resources.dir}/wstools-config.xml"/> + </target> + + <target name="clean"> + <echo message="In clean"/> + <delete file="${top.dir}/helloworldws.war"/> + <delete dir="${build.classes}"/> + <delete dir="${top.dir}/META-INF"/> + <mkdir dir="${build.classes}"/> + </target> +<!-- + Compile the java sources + --> +<!-- + Compile the java sources with jdk-1.5 + --> + <target name="compile15" depends="" description="compile the sources" if="HAVE_JDK_1.5"> + <javac destdir="${build.classes}" classpathref="compile.classpath" debug="on"> + <src path="${java.dir}"/> + </javac> + </target> + + + <target name="main" depends="compile15, generate-sources" if="jbossws.client.jar"> + <echo message="In main"/> + <war warfile="helloworldws.war" webxml="${src.dir}/metadata/web.xml"> +<!-- <webinf dir="${src.dir}/metadata" /> + --> + <classes dir="${top.dir}/classes"> + <include name="org/jboss/samples/HelloWorldWS.class"/> + </classes> + </war> + <antcall target="deploy"/> + </target> + + <target name="deploy"> + <echo message="In deploy"/> + <copy file="${top.dir}/helloworldws.war" todir="${jboss.server.deploy}"/> + <delete file="${top.dir}/helloworldws.war"/> + </target> + + <target name="undeploy"> + <echo message="In undeploy"/> + <delete> + <fileset id="web_service_wars" dir="${jboss.server.deploy}" includes="*hello*.war"/> + </delete> + </target> +</project> Added: trunk/docs/online/tutorial-src/jax-ws-hello-world/log4j.xml =================================================================== --- trunk/docs/online/tutorial-src/jax-ws-hello-world/log4j.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-src/jax-ws-hello-world/log4j.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd"> +<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" debug="false"> + +<appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender"> +<errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/> +<param name="Target" value="System.out"/> +<param name="Threshold" value="INFO"/> + +<layout class="org.apache.log4j.PatternLayout"> +<!-- The default pattern: Date Priority [Category] Message\n --> +<param name="ConversionPattern" value="%d{ABSOLUTE} %-5p [%c{1}] %m%n"/> +</layout> +</appender> + + +<root> +<appender-ref ref="CONSOLE"/> +</root> + + +</log4j:configuration> Added: trunk/docs/online/tutorial-src/jax-ws-hello-world/resources/wstools-config.xml =================================================================== --- trunk/docs/online/tutorial-src/jax-ws-hello-world/resources/wstools-config.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-src/jax-ws-hello-world/resources/wstools-config.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,13 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + wstools -config wstools-config.xml +--> +<configuration xmlns="http://www.jboss.org/jbossws-tools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.jboss.org/jbossws-tools http://www.jboss.org/jbossws-tools/schema/jbossws-tool_1_0.xsd"> + <global> + <package-namespace package="org.jboss.samples.helloworld" namespace="http://org.jboss.ws/samples/helloworld"/> + </global> + <java-wsdl> + <service name="HelloWorldWS" endpoint="org.jboss.samples.helloworld.EndpointInterface" style="rpc"/> + <namespaces target-namespace="http://org.jboss.ws/samples/helloworld" type-namespace="http://org.jboss.ws/samples/helloworld/types"/> + </java-wsdl> +</configuration> Added: trunk/docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/samples/helloworld/EndpointInterface.java =================================================================== --- trunk/docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/samples/helloworld/EndpointInterface.java 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/samples/helloworld/EndpointInterface.java 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,9 @@ +package org.jboss.samples.helloworld; + +import java.rmi.Remote; +import java.rmi.RemoteException; + +public interface EndpointInterface extends Remote +{ + String sayHello(String toWhom) throws RemoteException; +} \ No newline at end of file Added: trunk/docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/samples/helloworld/HelloWorldWS.java =================================================================== --- trunk/docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/samples/helloworld/HelloWorldWS.java 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-src/jax-ws-hello-world/src/java/org/jboss/samples/helloworld/HelloWorldWS.java 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,20 @@ +package org.jboss.samples.helloworld; + +import javax.jws.WebService; +import javax.jws.WebMethod; + +/* @WebService(name = "HelloWorld", + targetNamespace="http://org.jboss.ws/helloworld", + serviceName = "HelloWorldWS") +*/ + +@WebService() +public class HelloWorldWS +{ + @WebMethod + public String sayHello(String toWhom) + { + // System.out.println("I'm Hit! " + toWhom); + return "Hello " + toWhom + "!" + " The date and time is: " + new java.util.Date(); + } +} Added: trunk/docs/online/tutorial-src/jax-ws-hello-world/src/metadata/web.xml =================================================================== --- trunk/docs/online/tutorial-src/jax-ws-hello-world/src/metadata/web.xml 2006-12-04 13:30:05 UTC (rev 1544) +++ trunk/docs/online/tutorial-src/jax-ws-hello-world/src/metadata/web.xml 2006-12-04 13:30:29 UTC (rev 1545) @@ -0,0 +1,18 @@ +<?xml version="1.0" ?> + +<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>HelloWorldWS</servlet-name> + <servlet-class>org.jboss.samples.HelloWorldWS</servlet-class> + </servlet> + + <servlet-mapping> + <servlet-name>HelloWorldWS</servlet-name> + <url-pattern>/*</url-pattern> + </servlet-mapping> + +</web-app> +