<?xml version="1.0" encoding="UTF-8"?>
<book version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:svg="http://www.w3.org/2000/svg"
      xmlns:mml="http://www.w3.org/1998/Math/MathML"
      xmlns:html="http://www.w3.org/1999/xhtml"
      xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>JAX-WS Developer's Guide</title>

    <authorgroup>
      <author>
        <orgname>JOnAS Team</orgname>
      </author>
    </authorgroup>

    <legalnotice>
      <para>This work is licensed under the Creative Commons
      Attribution-ShareAlike License. To view a copy of this license,visit
      <link
      xlink:href="http://creativecommons.org/licenses/by-sa/2.0/deed.en">http://creativecommons.org/licenses/by-sa/2.0/deed.en</link>
      or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford,
      California 94305, USA.</para>
    </legalnotice>

    <copyright>
      <year>2009</year>

      <holder>OW2 Consortium</holder>
    </copyright>

    <date>March 2009</date>
  </info>

  <preface>
    <title>Preface</title>

    <para>JAX-WS stands for <emphasis>J</emphasis>ava <emphasis>A</emphasis>PI
    for <emphasis>X</emphasis>ML
    <emphasis>W</emphasis>eb<emphasis>S</emphasis>ervices. It's a technology
    used to implement webservices endpoints and webservices clients
    communicating using XML.</para>

    <para>SOAP and XML messaging is a complex domain, but JAX-WS aims to hide
    the complexity of that domain. Endpoint development is an easy task: the
    developer writes a Java interface that will defines the available
    webservices operations, writes a concrete class (can be multiple class in
    case of inheritance) that will implement the Java interface. A minimal set
    of annotations is required to declares the class and interface as
    webservices. Writing webservices client is also an easy task: using
    generated classes from a given WSDL, the client can access the webservice
    without knowing any technical details. This is the role of the JAX-WS
    engine to do all the XML marshalling/unmarshalling, SOAP processing,
    ...</para>

    <para>With JAX-WS, developers takes both advantages of a standard Java
    webservices specification (portability) and of the Java platform
    independence (OS/hardware neutral). Moreover, with JAX-WS (and webservices
    in general), a client can access a webservice not implemented with Java
    and vice versa. This is possible because JAX-WS respects the W3C
    recommendations (<emphasis>W</emphasis>orld <emphasis>W</emphasis>ide
    <emphasis>W</emphasis>eb <emphasis>C</emphasis>onsortium) for HTTP, SOAP
    and WSDL (WebServices Description Language).</para>
  </preface>

  <chapter xml:id="developing-a-webservice-endpoint">
    <title>Developing a Webservice Endpoint</title>

    <para>A Webservice endpoint is the implementation of a webservice. It's a
    server side artifact that can answer to webservices requests.</para>

    <para>An endpoint can be implemented using a POJO or using a Stateless
    EJB3.</para>

    <para>Two approaches can be used to develop an endpoint:</para>

    <itemizedlist>
      <listitem>
        <para>Starting from Java</para>
      </listitem>

      <listitem>
        <para>Starting from WSDL</para>
      </listitem>
    </itemizedlist>

    <para>Taking one of theses 2 approaches is the developer's choice.</para>

    <section xml:id="starting-from-java">
      <title>Starting from Java</title>

      <para>Choosing a Java-first approach is typical of a webservices
      development from scratch.</para>

      <section>
        <title>Defining the Service Endpoint Interface</title>

        <para>The service endpoint interface (SEI) is a Java interface that
        specified the methods that will be exposed as webservices operations.
        This interface is required to be annotated with the @WebService
        annotation.</para>

        <para><programlisting>@WebService(name="QuoteReporter",
            targetNamespace="http://jonas.ow2.org/examples/jaxws/quote")
public interface QuoteReporter {
    public Quote getQuote(@WebParam(name="ticker") String ticker);
}</programlisting>The <link
        xlink:href="http://java.sun.com/javaee/5/docs/api/javax/jws/WebService.html">@WebService</link>
        annotation, placed on a SEI, provides the information required to
        generate a valid WSDL:</para>

        <itemizedlist>
          <listitem>
            <para>name: this value will be used as the
            <tag>wsdl:portType</tag> name in the generated WSDL</para>
          </listitem>

          <listitem>
            <para>targetNamespace: this value will be used as the XML
            namespace containing the WSDL.</para>

            <para>It's required that this value is a URI, it's NOT required to
            use an URL or that this URL is accessible.</para>
          </listitem>
        </itemizedlist>

        <note>
          <para>Annotating the SEI will provides all the necessary information
          to build an abstract WSDL (types + messages + portType).</para>
        </note>

        <para>The <classname><link
        xlink:href="http://java.sun.com/javaee/5/docs/api/javax/jws/WebParam.html">@WebParam</link></classname>
        annotation is placed on the method parameter because Java compilation
        do not store the parameter name ('ticker' here) in the byte code.
        Having a @WebParam ensure that the generated WSDL will always have the
        correct operation parameter names.</para>
      </section>

      <section>
        <title>Implementing the Service Endpoint Interface</title>

        <para>Once the SEI has been created, the developer has to implement
        the SEI.</para>

        <para><programlisting>@WebService(portName="QuoteReporterPort",
            serviceName="QuoteReporterService",
            targetNamespace="http://jonas.ow2.org/examples/jaxws/quote",
            endpointInterface="org.ow2.jonas.examples.jaxws.quote.QuoteReporter")
public class QuoteReporterBean implements QuoteReporter {
    public Quote getQuote(final String ticker) {
        return new Quote(ticker, Math.random() * 100);
    }
}</programlisting>Once again, the developer has to annotate its class with the
        @WebService annotation.</para>

        <itemizedlist>
          <listitem>
            <para>portName: this value specifies the <tag>wsdl:port</tag> to
            be used</para>
          </listitem>

          <listitem>
            <para>serviceName: this value specifies the
            <tag>wsdl:service</tag> to be used</para>
          </listitem>

          <listitem>
            <para>targetNamespace: this value specifies the targetNamespace of
            the <tag>wsdl:service</tag></para>
          </listitem>

          <listitem>
            <para>endpointInterface: this value specifies the service endpoint
            interface classname (SEI)</para>
          </listitem>
        </itemizedlist>

        <para>That's it, a first simple webservice endpoint code ! The next
        section will focus on the most important webservices
        annotations.</para>
      </section>

      <section>
        <title>Annotating the code</title>

        <para></para>
      </section>

      <section>
        <title>Generate WSDL</title>

        <para>Once you have a codebase fully annotated, you may choose to
        generate a WSDL contract.</para>

        <para><note>
            <para>With JOnAS 5.1 M4, there is no simple way to perform a
            wsdl2java operation, although the Apache CXF ant tasks are
            available.</para>

            <para>Next releases will provide more examples and documentation
            about the generation process.</para>
          </note></para>
      </section>
    </section>

    <section xml:id="starting-from-wsdl">
      <title>Starting from WSDL</title>

      <para>In the WSDL first approach, the developer is required to implement
      a webservice that is constrained by a WSDL contract.</para>

      <para>In that case, 2 options are available:</para>

      <itemizedlist>
        <listitem>
          <para>Generates, from the WSDL, the SEI interface and an
          implementation skeleton.</para>
        </listitem>

        <listitem>
          <para>Implements a Provider that will allow the developer to work at
          the XML level.</para>
        </listitem>
      </itemizedlist>

      <section>
        <title>Generates skeleton</title>

        <para>JAX-WS tools are provided to help the developers to quickly
        start to implement business code by generating most of the plumbing.
        wsdl2java for a webservice endpoint will generate the following
        artifacts:</para>

        <itemizedlist>
          <listitem>
            <para>{portType}.java: this is the fully annotated SEI interface.
            By default, its name is based on the wsdl:portType name.</para>
          </listitem>

          <listitem>
            <para>{portType}Impl.java: this is an implementation skeleton,
            annotated with @WebService. The developer just have to fill the
            blanks in this class.</para>
          </listitem>

          <listitem>
            <para>{types}.java + ObjectFactory.java: theses JAXB generated
            classes represents the operations parameters and documents.</para>
          </listitem>
        </itemizedlist>

        <note>
          <para>Insert here a picture of generated classes.</para>
        </note>

        <section>
          <title>Generates the Service Endpoint Interface</title>

          <para>A SEI generated by a JAX-WS 2.1 compatible tool look like
          this:</para>

          <para></para>
        </section>

        <section>
          <title>Implements the Service Endpoint Interface</title>

          <para>Implementing the SEI simply means that the developer has to
          fill in the blanks of the generated skeleton. This part focus on
          business code.</para>
        </section>
      </section>
    </section>

    <section xml:id="writing-a-provider">
      <title xml:base="">Writing a Provider</title>

      <para>JAX-WS allows developers to write endpoints dealing directly with
      XML messages using the Provider interface. This can be done by
      implementing Provider&lt;Source&gt; or Provider&lt;SOAPMessage&gt; or
      Provider&lt;DataSource&gt;.</para>

      <para><programlisting>T invoke(T request) throws WebServiceException;</programlisting></para>

      <para>Supported parameter's types are: <link
      xlink:href="http://java.sun.com/j2se/1.5/docs/api/javax/xml/transform/Source.html">Source</link>,
      <link
      xlink:href="http://java.sun.com/javaee/5/docs/api/javax/xml/soap/SOAPMessage.html">SOAPMessage</link>,
      <link
      xlink:href="http://java.sun.com/javaee/5/docs/api/javax/activation/DataSource.html">DataSource</link>.
      They define the format of the data that will be manipulated inside the
      invoke method. What will be available in theses data structures depends
      on the ServiceMode specified. ServiceMode can be either MESSAGE or
      PAYLOAD (PAYLOAD being the default when no mode is specified):</para>

      <itemizedlist>
        <listitem>
          <para>ServiceMode.MESSAGE: The structure will represent the whole
          request message (allowing access to the SOAP envelop and SOAP
          headers for example)</para>
        </listitem>

        <listitem>
          <para>ServiceMode.PAYLOAD: The structure will represent only the
          body of the request (restricting access to business data located
          inside the SOAP Body element)</para>
        </listitem>
      </itemizedlist>

      <para>When writing a Provider, the webservice developer MUST starts with
      a WSDL, because the Provider implementation do not provide any
      exploitable information about the XML data structures expected (such as
      bean class parameters and such).</para>

      <note>
        <para>Providers cannot be implemented using Stateless EJB.</para>
      </note>

      <para>Providers implementation supports the one way MEP (Message
      Exchange Pattern) simply by returning null.</para>

      <section>
        <title>Supported modes</title>

        <para>Although many modes and types combinations are possibles, there
        are some logical restrictions given the Binding type (HTTP, SOAP) in
        use.</para>

        <para>Supported combinations are described below.</para>

        <section>
          <title>Using SOAP Binding (1.1 or 1.2)</title>

          <para>In the absence of any customization (like applying a
          @BindingType annotation on the Provider), the binding is assumed to
          be SOAP 1.1.</para>

          <caution>
            <para>Provider&lt;SOAPMessage&gt; used in conjunction with a
            ServiceMode set to PAYLOAD is invalid.</para>

            <para>Indeed the SOAPMessage type represents the whole message,
            not just the SOAP Body element.</para>
          </caution>

          <caution>
            <para>Provider&lt;DataSource&gt; is <emphasis>always
            invalid</emphasis> when used with a SOAP Binding.</para>
          </caution>

          <section>
            <title>Provider&lt;Source&gt; and MESSAGE mode</title>

            <para>Using a Provider&lt;Source&gt; with the MESSAGE mode is used
            to change the message's content (provided as a
            javax.xml.transform.Source object) using XSLT Transformers.</para>

            <para><programlisting>@WebServiceProvider
@ServiceMode(Service.Mode.MESSAGE)
public class ProviderImpl implements Provider&lt;Source&gt; {
    public Source invoke(Source message) {
        // Process the request
        ...
        // Prepare the response Source
        Source response = ...;
        return response;
    }
}</programlisting></para>
          </section>

          <section>
            <title>Provider&lt;Source&gt; and PAYLOAD mode</title>

            <para>Using a Provider&lt;Source&gt; with the PAYLOAD mode is used
            to change the message's payload (provided as a
            javax.xml.transform.Source object) using XSLT Transformers.</para>

            <programlisting>@WebServiceProvider
public class ProviderImpl implements Provider&lt;Source&gt; {
    public Source invoke(Source source) {
        // Process the request
        ...
        // Prepare the response Source
        Source response = ...;
        return response;
    }
}</programlisting>
          </section>

          <section>
            <title>Provider&lt;SOAPMessage&gt; and MESSAGE mode</title>

            <para>Using a Provider&lt;SOAPMessage&gt; with the MESSAGE mode is
            used to change the message's content (provided as a
            javax.xml.soap.SOAPMessage object) with a DOM-like API.</para>

            <programlisting>@WebServiceProvider
@ServiceMode(Service.Mode.MESSAGE)
public class ProviderImpl implements Provider&lt;SOAPMessage&gt; {
    public SOAPMessage invoke(SOAPMessage message) {
        // Process the request
        ...
        // Prepare the response SOAPMessage
        SOAPMessage response = ...;
        return response;
    }
}</programlisting>

            <caution>
              <para>Provider&lt;SOAPMessage&gt; used in conjunction with a
              ServiceMode set to PAYLOAD is
              <emphasis>invalid</emphasis>.</para>

              <para>Indeed the <classname>SOAPMessage</classname> type
              represents the whole message, not just the SOAP Body
              element.</para>
            </caution>
          </section>
        </section>

        <section>
          <title>Using HTTP Binding</title>

          <para>Providers can also be implemented using the HTTP binding. That
          means that no SOAP messages are involved and that the interaction
          will only be based on XML/HTTP.</para>

          <caution>
            <para>Provider&lt;DataSource&gt; used in conjunction with a
            ServiceMode set to PAYLOAD is invalid.</para>
          </caution>

          <caution>
            <para>Provider&lt;SOAPMessage&gt; is <emphasis>always
            invalid</emphasis> when used with an HTTP Binding.</para>

            <para>Indeed, using the HTTP binding assume that the messages are
            not SOAP messages.</para>
          </caution>

          <section>
            <title>Provider&lt;Source&gt; and MESSAGE mode</title>

            <para>Using a Provider&lt;Source&gt; with the MESSAGE mode and the
            HTTP binding is used to change the message's content (provided as
            a javax.xml.transform.Source object) using XSLT
            Transformers.</para>

            <programlisting>@WebServiceProvider
@ServiceMode(Service.Mode.MESSAGE)
@BindingType(HTTPBinding.HTTP_BINDING)
public class ProviderImpl implements Provider&lt;Source&gt; {
    public Source invoke(Source message) {
        // Process the request
        ...
        // Prepare the response Source
        Source response = ...;
        return response;
    }
}</programlisting>
          </section>

          <section>
            <title>Provider&lt;Source&gt; and PAYLOAD mode</title>

            <para>Using a Provider&lt;Source&gt; with the PAYLOAD mode and the
            HTTP binding is used to change the message's body (provided as a
            javax.xml.transform.Source object) using XSLT Transformers.</para>

            <programlisting>@WebServiceProvider
@BindingType(HTTPBinding.HTTP_BINDING)
public class ProviderImpl implements Provider&lt;Source&gt; {
    public Source invoke(Source message) {
        // Process the request
        ...
        // Prepare the response Source
        Source response = ...;
        return response;
    }
}</programlisting>
          </section>

          <section>
            <title>Provider&lt;DataSource&gt; and MESSAGE mode</title>

            <para>Using a Provider&lt;DataSource&gt; with the MESSAGE mode and
            the HTTP binding is used to process the message attachment
            (provided as a javax.xml.transform.Source object). This style of
            provider is useful when dealing <emphasis>only</emphasis> with
            message's attachments (no XML changes).</para>

            <programlisting>@WebServiceProvider
@ServiceMode(Service.Mode.MESSAGE)
@BindingType(HTTPBinding.HTTP_BINDING)
public class ProviderImpl implements Provider&lt;DataSource&gt; {
    public DataSource invoke(DataSource message) {
        // Process the request
        ...
        // Prepare the response DataSource
        DataSource response = ...;
        return response;
    }
}</programlisting>
          </section>
        </section>
      </section>

      <section>
        <title>Wrap up</title>

        <para>The table below summarizes the requirement with all the possible
        combinations (<footnoteref
        linkend="jaxws.provider.table.source" />).</para>

        <informaltable border="0">
          <tr>
            <td></td>

            <th>XML/HTTP Binding</th>

            <th>SOAP/HTTP Binding</th>
          </tr>

          <tr>
            <th align="center" colspan="3">Provider&lt;Source&gt;</th>
          </tr>

          <tr>
            <th>Payload</th>

            <td>Primary part or content as Source</td>

            <td>SOAP Body from the primary part or SOAP Body as Source</td>
          </tr>

          <tr>
            <th>Message</th>

            <td>Primary part or content as Source</td>

            <td>SOAP Envelope from the primary part or SOAP Envelope as
            Source</td>
          </tr>

          <tr>
            <th colspan="3">Provider&lt;DataSource&gt;</th>
          </tr>

          <tr>
            <th>Payload</th>

            <td>Not Valid <link linkend="jaxws.provider.ref.1">[1]</link></td>

            <td>Not Valid <link linkend="jaxws.provider.ref.1">[1]</link></td>
          </tr>

          <tr>
            <th>Message</th>

            <td>DataSource as an object</td>

            <td>Not Valid <link linkend="jaxws.provider.ref.2">[2]</link></td>
          </tr>

          <tr>
            <th colspan="3">Provider&lt;SOAPMessage&gt;</th>
          </tr>

          <tr>
            <th>Payload</th>

            <td>Not Valid <link linkend="jaxws.provider.ref.3">[3]</link></td>

            <td>Not Valid <link linkend="jaxws.provider.ref.3">[3]</link></td>
          </tr>

          <tr>
            <th>Message</th>

            <td>Not Valid <link linkend="jaxws.provider.ref.4">[4]</link></td>

            <td>SOAPMessage as an object</td>
          </tr>
        </informaltable>

        <para><footnote xml:id="jaxws.provider.table.source">
            <para>Source Arun Gupta (<link
            xlink:href="http://weblogs.java.net/blog/arungupta/archive/2006/03/jaxws_20_provid_1.html">http://weblogs.java.net/blog/arungupta/archive/2006/03/jaxws_20_provid_1.html)</link></para>
          </footnote><note xml:id="jaxws.provider.ref.1">
            <para>Provider&lt;DataSource&gt; is used for sending attachments
            and thus payload mode is not valid.</para>
          </note><note xml:id="jaxws.provider.ref.2">
            <para>Provider&lt;DataSource&gt; in SOAP/HTTP is not valid since
            attachments in SOAP are sent using Provider&lt;SOAPMessage&gt;.
            </para>
          </note><note xml:id="jaxws.provider.ref.3">
            <para>Provider&lt;SOAPMessage&gt; in payload mode is not valid
            because the entire SOAPMessage is received, not just the payload
            which corresponds to the body of the SOAPMessage. </para>
          </note><note xml:id="jaxws.provider.ref.4">
            <para>Provider&lt;SOAPMessage&gt; in message mode using XML/HTTP
            binding is not valid since the client may have sent an XML message
            that may not be SOAP.</para>
          </note></para>
      </section>

      <section>
        <title>Implementing RESTful services using Providers</title>

        <para></para>

        <note>
          <para>Using HTTP Binding + provider can be used to implement simple
          RESTful services (in the absence of JAX-RS support).</para>

          <para>This topic will be covered in future versions in this
          documentation.</para>
        </note>
      </section>
    </section>

    <section xml:id="overriding-annotations">
      <title>Overriding annotations</title>

      <para>Some annotations values can be overridden in a Java EE application
      server using the webservices.xml (located in WEB-INF/ or META-INF/ given
      the implementor is respectively a POJO or an EJB).</para>

      <para>The link between @WebService (or @WebServiceProvider) and the XML
      &lt;port-component&gt; description is done through the
      &lt;service-impl-bean&gt; element:</para>

      <itemizedlist>
        <listitem>
          <para>&lt;ejb-link&gt; with an ejb-name pointing to a Stateless EJB3
          annotated with @WebService / @WebServiceProvider.</para>
        </listitem>

        <listitem>
          <para>&lt;servlet-link&gt; with a servlet-name pointing to a Servlet
          declaration in the web.xml.</para>
        </listitem>
      </itemizedlist>

      <table>
        <title>Overriding @WebService</title>

        <tgroup cols="3">
          <thead>
            <row>
              <entry align="center"> Annotation</entry>

              <entry align="center">Deployment descriptor element </entry>

              <entry align="center">Comment</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>@WebService</entry>

              <entry>&lt;webservices&gt;/&lt;webservice-description&gt;/&lt;port-component&gt;</entry>

              <entry>One @WebService per &lt;port-component&gt;</entry>
            </row>

            <row>
              <entry>@WebService.wsdlLocation</entry>

              <entry>&lt;webservices&gt;/&lt;webservice-description&gt;/&lt;wsdl-file&gt;</entry>

              <entry>Overrides the WSDL location value for all the
              &lt;port-component&gt; declared in the
              &lt;webservice-description&gt;</entry>
            </row>

            <row>
              <entry>@WebService.name</entry>

              <entry>&lt;webservices&gt;/&lt;webservice-description&gt;/&lt;port-component&gt;/&lt;port-component-name&gt;</entry>

              <entry></entry>
            </row>

            <row>
              <entry>@WebService.serviceName</entry>

              <entry>&lt;webservices&gt;/&lt;webservice-description&gt;/&lt;port-component&gt;/&lt;wsdl-service&gt;</entry>

              <entry></entry>
            </row>

            <row>
              <entry>@WebService.portName</entry>

              <entry>&lt;webservices&gt;/&lt;webservice-description&gt;/&lt;port-component&gt;/&lt;wsdl-port&gt;</entry>

              <entry></entry>
            </row>

            <row>
              <entry>@WebService.endpointInterface</entry>

              <entry>&lt;webservices&gt;/&lt;webservice-description&gt;/&lt;port-component&gt;/&lt;service-endpoint-interface&gt;</entry>

              <entry></entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <para></para>

      <table>
        <title>Overriding @WebServiceProvider</title>

        <tgroup cols="3">
          <thead>
            <row>
              <entry align="center">Annotation </entry>

              <entry align="center">Deployment descriptor element </entry>

              <entry align="center">Comment</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>@WebServiceProvider</entry>

              <entry>&lt;webservices&gt;/&lt;webservice-description&gt;/&lt;port-component&gt;</entry>

              <entry>One @WebServiceProvider per
              &lt;port-component&gt;</entry>
            </row>

            <row>
              <entry>@WebServiceProvider.wsdlLocation</entry>

              <entry>&lt;webservices&gt;/&lt;webservice-description&gt;/&lt;wsdl-file&gt;</entry>

              <entry>Overrides the WSDL location value for all the
              &lt;port-component&gt; declared in the
              &lt;webservice-description&gt;</entry>
            </row>

            <row>
              <entry>@WebService.serviceName</entry>

              <entry>&lt;webservices&gt;/&lt;webservice-description&gt;/&lt;port-component&gt;/&lt;wsdl-service&gt;</entry>

              <entry></entry>
            </row>

            <row>
              <entry>@WebService.portName</entry>

              <entry>&lt;webservices&gt;/&lt;webservice-description&gt;/&lt;port-component&gt;/&lt;wsdl-port&gt;</entry>

              <entry></entry>
            </row>

            <row>
              <entry>@WebService.endpointInterface</entry>

              <entry>N/A</entry>

              <entry>It is not required for a Provider to specify a
              SEI</entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <para></para>

      <table>
        <title>Overriding @BindingType</title>

        <tgroup cols="2">
          <thead>
            <row>
              <entry align="center">Deployment descriptor</entry>

              <entry align="center">Possible values </entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>&lt;port-component&gt;/&lt;protocol-binding&gt;</entry>

              <entry><para>Specify the protocol binding used by this
              port-component. The following alias are
              supported:</para><itemizedlist>
                  <listitem>
                    <para><literal>##SOAP11_HTTP</literal>: SOAP 1.1
                    Binding</para>
                  </listitem>

                  <listitem>
                    <para><literal>##SOAP11_HTTP_MTOM</literal>: SOAP 1.1
                    Binding with MTOM enabled</para>
                  </listitem>

                  <listitem>
                    <para><literal>##SOAP12_HTTP</literal>: SOAP 1.2
                    Binding</para>
                  </listitem>

                  <listitem>
                    <para><literal>##SOAP12_HTTP_MTOM</literal>: SOAP 1.2
                    Binding with MTOM enabled</para>
                  </listitem>

                  <listitem>
                    <para><literal>##XML_HTTP</literal>: XML Binding</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>&lt;port-component&gt;/&lt;enable-mtom&gt;</entry>

              <entry>This element permits to enable/disable the SOAP MTOM/XOP
              mechanism for the endpoint. This element has higher priority
              than &lt;protocol-binding&gt;, meaning that if
              <literal>##SOAP11_HTTP_MTOM</literal> is specified as protocol
              binding and &lt;enable-mtom&gt; is false, it will be equivalent
              to a protocol binding set to
              <literal>##SOAP11_HTTP</literal></entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>

    <section xml:id="endpoint-packaging">
      <title>Endpoint packaging</title>

      <para>When the webservices implementation has been finished, code
      compiled, it's time to take care of the application packaging. There are
      some simple packaging rules to follow.</para>

      <section>
        <title>Web Application</title>

        <para>When the endpoint is implemented as a POJO, the implementation
        class may be referenced as a servlet in the WEB-INF/web.xml. If it is
        not declared in the web.xml, it will be auto discovered at deployment
        time. If it is declared in the web.xml, it must be specified as a new
        servlet element and the servlet must have an associated
        servlet-mapping.<programlisting>&lt;web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
                             http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5"&gt;

    &lt;servlet&gt;
        &lt;servlet-name&gt;<emphasis>{servlet-name}</emphasis>&lt;/servlet-name&gt;                             <co
              xml:id="servlet.servlet-name" />
        &lt;servlet-class&gt;<emphasis>{implementor-fully-qualified-classname}</emphasis>&lt;/servlet-class&gt;  <co
              xml:id="servlet.servlet-class" />
    &lt;/servlet&gt;

    &lt;servlet-mapping&gt;
        &lt;servlet-name&gt;<emphasis>{servlet-name}</emphasis>&lt;/servlet-name&gt;                             <co
              xml:id="servlet-mapping.servlet-name" />
        &lt;url-pattern&gt;<emphasis>{webservice-endpoint-url-pattern}</emphasis>&lt;/url-pattern&gt;            <co
              xml:id="servlet-mapping.url-pattern" />
    &lt;/servlet-mapping&gt;

&lt;/web-app&gt;</programlisting><calloutlist>
            <callout arearefs="servlet.servlet-name">
              <para>A usual servlet name: unique among other servlets.</para>
            </callout>

            <callout arearefs="servlet.servlet-class">
              <para>The implementor fully qualified classname (It's not a
              Servlet, but that's OK, it will be changed during
              deployment).</para>
            </callout>

            <callout arearefs="servlet-mapping.servlet-name">
              <para>The same servlet name specified first in the servlet
              element.</para>
            </callout>

            <callout arearefs="servlet-mapping.url-pattern">
              <para>The URL pattern that will point to the webservice
              endpoint.</para>
            </callout>
          </calloutlist></para>

        <para><caution>
            <para>If the endpoint is declared in the
            <filename>WEB-INF/web.xml</filename> but no
            <tag>servlet-mapping</tag> is provided, the endpoint will not be
            accessible (No URLs will point to the servlet).</para>
          </caution>If the WSDL is referenced from the endpoint (using
        @WebService.wsdlLocation(), @WebServiceProvider.wsdlLocation() or
        webservices.xml), it has to be provided in the <filename
        class="directory">WEB-INF/wsdl/</filename> directory of the
        webapp.</para>

        <section>
          <title>Default Web URL Mapping</title>

          <para>The webservice endpoint contained in the webapp will be
          available through an URL.</para>

          <para>If no servlet-mapping was specified in the web.xml a default
          mapping will be automatically introduced.</para>

          <table>
            <title>Automatic Web Endpoints Servlet Mappings Patterns</title>

            <tgroup cols="2">
              <thead>
                <row>
                  <entry align="center"> Condition</entry>

                  <entry align="center">Servlet Mapping Pattern </entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry><methodname>serviceName</methodname> has been
                  provided in the @WebService(s)</entry>

                  <entry>/{service-qname-local-part}</entry>
                </row>

                <row>
                  <entry>no <methodname>serviceName</methodname>
                  provided</entry>

                  <entry>/{simple-implementor-classname}Simple</entry>
                </row>
              </tbody>
            </tgroup>
          </table>
        </section>
      </section>

      <section>
        <title>EjbJar</title>

        <para>When the webservice endpoint is implemented as a Stateless
        EJB</para>

        <section>
          <title>Endpoint URL Mapping</title>

          <para>As an ejbjar is not a webapp, there is no available web
          context, or url-pattern that can be used to access the endpoint
          through HTTP.</para>

          <para>A Web context is created and named after the ejbjar's filename
          (stopping at the first '_' character).</para>

          <table>
            <title>Automatic EJB Endpoints Servlet Mappings Patterns</title>

            <tgroup cols="2">
              <thead>
                <row>
                  <entry align="center"> Condition</entry>

                  <entry align="center">Servlet Mapping Pattern </entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry><markup>&lt;endpoint-address&gt;</markup> provided
                  for the bean in the easybeans.xml</entry>

                  <entry>provided value</entry>
                </row>

                <row>
                  <entry><methodname>serviceName</methodname> has been
                  provided in the @WebService(s)</entry>

                  <entry>/{service-qname-local-part}</entry>
                </row>

                <row>
                  <entry>no <methodname>serviceName</methodname>
                  provided</entry>

                  <entry>/{simple-implementor-classname}Simple</entry>
                </row>
              </tbody>
            </tgroup>
          </table>
        </section>

        <section>
          <title>EasyBeans deployment descriptor customizations</title>

          <para>The EasyBeans deployment descriptor provides a mean for
          customizing some webservices endpoint properties.</para>

          <para><note>
              <para>To be completed with XML references.
              (easybeans/webservices/endpoint and
              easybeans/ejb/session/endpoint-address).</para>
            </note></para>
        </section>
      </section>
    </section>
  </chapter>

  <chapter xml:id="developing-a-webservice-consumer">
    <title>Developing a Webservice Consumer</title>

    <para>A Webservice consumer is a client of a webservice endpoint. It's a
    client side artifact that perform webservices requests.</para>

    <para>With JAX-WS, clients can benefits of asynchronous invocations (more
    on this later).</para>

    <para>A webservice consumer can be any of the following Java EE
    components: EJB (Session/MessageDriven), Servlet (or any web components
    such as JSP, JSF, ...) or Application Client. For any of theses
    components, the creation process is the same.</para>

    <para>A consumer typically starts with a WSDL (describing the endpoint's
    contract), but dynamic invocation (working at the XML level) can also be
    performed.</para>

    <section>
      <title>Port</title>

      <para>A webservice consummer can be implemented using a Port. A Port is
      a Java interface that hides to the client all the WS low level
      mechanisms (masrshalling, unmarshalling, handler chains, ...).</para>

      <para>A Port is usually generated from a WSDL.</para>

      <section>
        <title>Generates portable client artifacts</title>

        <para>When the client's developer starts with a WSDL, it usually
        generates the client artifacts (Java classes) using a wsdl2java
        tool.</para>

        <note>
          <para>With JOnAS 5.1 M4, there is no simple way to perform a
          wsdl2java operation, although the Apache CXF ant tasks are
          available.</para>

          <para>Next releases will provide more examples and documentation
          about the generation process.</para>
        </note>

        <para><informalexample>
            <para></para>
          </informalexample></para>

        <section>
          <title>Example of generated Service</title>

          <para></para>
        </section>

        <section>
          <title>Example of generated Port</title>

          <para></para>
        </section>
      </section>

      <section>
        <title>Synchronous consumer</title>

        <para>Using synchronous consumer is the easiest way of consuming a
        webservice: by default, wsdl2java tools generate classes supporting
        only synchronous operations.</para>

        <para>The following code snippet shows the Port source code that a
        wsdl2java tool generate using an input WSDL file.</para>

        <para><programlisting>@WebService(targetNamespace = "http://jonas.ow2.org/samples/jaxws/calculator",
            name = "Calculator")
public interface Calculator {

    @ResponseWrapper(localName = "addResponse",
                     targetNamespace = "http://jonas.ow2.org/samples/jaxws/calculator",
                     className = "org.ow2.jonas.samples.jaxws.calculator.AddResponse")
    @RequestWrapper(localName = "add",
                    targetNamespace = "http://jonas.ow2.org/samples/jaxws/calculator",
                    className = "org.ow2.jonas.samples.jaxws.calculator.Add")
    @WebResult(name = "return", targetNamespace = "")
    @WebMethod
    public int add(@WebParam(name = "arg0", targetNamespace = "")
                   int arg0,
                   @WebParam(name = "arg1", targetNamespace = "")
                   int arg1);
}</programlisting></para>
      </section>

      <section>
        <title>Asynchronous consumer</title>

        <para>By default, WSDL2Java generation do not generate asynchronous
        methods for each operation of the wsdl:portType.</para>

        <para>To enable the async method generation, a binding customization
        has to be provided during the WSDL2Java execution.</para>

        <para>It can be provided as part of the WSDL file:</para>

        <programlisting>&lt;portType name="CalculatorPort"&gt;
    &lt;operation name="add"&gt;
      &lt;input message="tns:addRequest"/&gt;
      &lt;output message="tns:addResponse"/&gt;
    &lt;/operation&gt;
&lt;/portType&gt;
&lt;binding name="CalculatorBinding" type="tns:CalculatorPort"&gt;
    &lt;soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/&gt;
    &lt;operation name="add"&gt;
      &lt;soap:operation soapAction=""/&gt;
      &lt;input&gt;
        &lt;soap:body use="literal"/&gt;&lt;/input&gt;
      &lt;output&gt;
        &lt;soap:body use="literal"/&gt;
      &lt;/output&gt;
    &lt;/operation&gt;
&lt;/binding&gt;
</programlisting>

        <para>Or as a separate bindings declaration file:</para>

        <programlisting>&lt;bindings xmlns:xsd="http://www.w3.org/2001/XMLSchema"
          xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
          xmlns="http://java.sun.com/xml/ns/jaxws"
          wsdlLocation="..."&gt;

    &lt;bindings node="wsdl:definitions"&gt;
        &lt;package name="org.ow2.jonas.ws.async.client"/&gt;
        <emphasis>&lt;enableAsyncMapping&gt;true&lt;/enableAsyncMapping&gt;</emphasis>
    &lt;/bindings&gt;
&lt;/bindings&gt;
</programlisting>

        <programlisting>// Synchronous method
public int add(int a, int b);

// Asynchronous polling method
public Response&lt;AddResponse&gt; add(int a, int b);

// Asynchronous callback method
public Future&lt;?&gt; add(int a, int b, AsyncHandler&lt;AddResponse&gt;);
</programlisting>

        <section>
          <title>Asynchronous polling</title>

          <para></para>
        </section>

        <section>
          <title>Asynchronous callback</title>

          <para></para>
        </section>
      </section>
    </section>

    <section>
      <title>Dispatch</title>

      <para>A Dispatch&lt;T&gt; is an object that allows the client to perform
      XML level operations. It is the client side equivalent to the
      Provider&lt;T&gt; interface.</para>

      <section>
        <title>Configure dynamic Service</title>

        <para></para>
      </section>

      <section>
        <title>Create a Dispatch</title>

        <para></para>
      </section>

      <section>
        <title>Invoke the Dispatch</title>

        <para>The Dispatch interface provides support for 4 MEP:
        request-response, asynchronous polling, asynchronous callback</para>

        <section>
          <title>Synchronous request response</title>

          <para></para>
        </section>

        <section>
          <title>Asynchronous request response</title>

          <para></para>
        </section>

        <section>
          <title>One way</title>

          <para></para>
        </section>
      </section>
    </section>

    <section>
      <title>Packaging</title>

      <para></para>
    </section>
  </chapter>

  <chapter xml:id="developing-handlers">
    <title>Developing Handlers</title>

    <para></para>

    <section>
      <title>Types</title>

      <para></para>

      <section>
        <title>SOAP handlers</title>

        <para></para>
      </section>

      <section>
        <title>Logical handlers</title>

        <para></para>
      </section>
    </section>

    <section>
      <title>Defining the handler-chains</title>

      <para></para>

      <section>
        <title>Handler chains description file</title>

        <para></para>

        <section>
          <title>HandlerChain annotation</title>

          <para></para>
        </section>
      </section>

      <section>
        <title>Defining handlers on the endpoint</title>

        <para></para>

        <section>
          <title>Using the @HandlerChain annotation</title>

          <para></para>
        </section>

        <section>
          <title>Using the webservices.xml</title>

          <para></para>
        </section>
      </section>

      <section>
        <title>Defining handlers for the consumer</title>

        <para></para>

        <section>
          <title>Using the @HandlerChain annotation</title>

          <para></para>
        </section>

        <section>
          <title>Using the javaee:service-ref element</title>

          <para></para>
        </section>

        <section>
          <title>Using the HandlerResolver</title>

          <para></para>
        </section>
      </section>
    </section>
  </chapter>

  <chapter xml:id="jaxws-annotations-reference">
    <title>Annotations references</title>

    <para></para>

    <section>
      <title>JWS Annotations (javax.jws)</title>

      <para></para>

      <section>
        <title>javax.jws.WebService</title>

        <para></para>
      </section>

      <section>
        <title>javax.jws.WebMethod</title>

        <para></para>
      </section>

      <section>
        <title>javax.jws.WebParam</title>

        <para></para>
      </section>

      <section>
        <title>javax.jws.WebResult</title>

        <para></para>
      </section>

      <section>
        <title>javax.jws.OneWay</title>

        <para></para>
      </section>

      <section>
        <title>javax.jws.HandlerChain</title>

        <para></para>
      </section>

      <section>
        <title>javax.jws.soap.SOAPBinding</title>

        <para></para>
      </section>
    </section>

    <section>
      <title>JAX-WS Annotations (javax.xml.ws)</title>

      <para></para>

      <section>
        <title>javax.xml.ws.WebServiceProvider</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.WebServiceRef</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.WebServiceRefs</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.WebServiceClient</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.BindingType</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.RequestWrapper</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.ResponseWrapper</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.RespectBinding</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.ServiceMode</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.WebEndpoint</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.WebFault</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.Feature</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.FeatureParameter</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.Action</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.FaultAction</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.soap.Addressing</title>

        <para></para>
      </section>

      <section>
        <title>javax.xml.ws.soap.MTOM</title>

        <para></para>
      </section>
    </section>
  </chapter>

  <glossary>
    <glossdiv>
      <title>JAX-WS Terminology</title>

      <glossentry>
        <glossterm>Endpoint</glossterm>

        <glossdef>
          <para>A Webservice endpoint is the web service implementation. It's
          a server side artifact. It can be implemented as a POJO or as a
          Stateless EJB.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>Consumer</glossterm>

        <glossdef>
          <para>Also known as a webservice client. It is a client side
          artifact.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>Portable Artifacts</glossterm>

        <glossdef>
          <para>JAX-WS generated artifacts (classes / WSDL / XSD) that are
          portable across JAX-WS implementation. It means that artifacts
          generated using Sun RI tools will be usable <emphasis>without any
          changes</emphasis> on any Java EE 5 compliant application
          server.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>Provider</glossterm>

        <glossdef>
          <para>Endpoint can be implemented as Providers if they require low
          level XML access.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>Handler</glossterm>

        <glossdef>
          <para>A Handler can be seen like a webservice interceptor. It can be
          used on client and/or server side. Two kinds of handlers exists:
          Logical and SOAP handlers.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>Dispatch</glossterm>

        <glossdef>
          <para>A Dispatch is a webservice client working at the XML level. A
          Dispatch is the client side equivalent to a Provider.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>POJO</glossterm>

        <glossdef>
          <para>Plain Old Java Object. Commonly used word meaning that the
          beans do not have to implement an interface to be usable by the
          container.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>QName</glossterm>

        <glossdef>
          <para>XML Qualified Name. Disambiguate XML names by prefixing the
          names (local-part) with a namespace (URI).</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>MEP</glossterm>

        <glossdef>
          <para>Message Exchange Pattern. This is the pattern of the exchange
          (one-way, request-response, ...).</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>SEI</glossterm>

        <glossdef>
          <para>Service Endpoint Interface. This is an annotated Java
          interface that represents the business object.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>MTOM</glossterm>

        <glossdef>
          <para>Message Transmission Optimization Mechanism. This is a W3C
          recommendation defining a method to efficiently sending binary data
          to and from webservices.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>WSDL</glossterm>

        <glossdef>
          <para>Web Service Description Language. This is the cornerstone of
          the webservices system. It is an XML file that can basically be
          compared to a Java interface: it's the contract defining the wire
          exchange (possible operations, expected types and parameters, ...)
          between a consumer and an endpoint.</para>
        </glossdef>
      </glossentry>
    </glossdiv>
  </glossary>
</book>
