# Overview

## Introduction

This document describes the new features available in this release of the &jax-ws.product.name.short;. The main focus of this document is to describe the tools used to develop &jax-ws.product.name; web service endpoints and clients. Readers of this document should be familiar with web services XML, XML Schema and WSDL. Familiarity with JAX-RPC 1.1 may also be beneficial but is not necessary.

The documentation/samples discusses how to use JAX-WS in a non-Java EE 5 servlet container using a proprietary deployment descriptor `sun-jaxws.xml` and servlet `com.sun.xml.ws.transport.http.servlet.WSServlet`. This means that you can run &jax-ws.product.name.short; applications in any servlet container that has been enabled with the &jax-ws.product.name.short;. Applications that use the proprietary DD and servlet will run in a &jax-ws.product.name.short; enabled Java EE 5 servlet container, but they will be non-portable. If you wish to use JAX-WS in a Java EE container in a Java EE portable manner you need to use the standard Java EE 5 deployment descriptor; please refer to the Java EE 5 or Glassfish documentation/samples. The majority of the documentation included with JAX-WS is valid with Java EE 5 as well.

## Features

### JAX-WS &jax-ws.release.spec.version; API

JAX-WS &jax-ws.release.spec.version; is a Maintainence Release of JAXWS 2.0 API.

JAX-WS &jax-ws.release.spec.version; has the following new features from JAX-WS 2.1 specification:

- Support for JAXB 2.2 APIs (JSR 222)

- Support for WS-Addressing 1.0 - Metadata specification

- Support for `@XmlElement` on SEI's wrapper parameter

- Support for `@XmlType` on exception classes

- HTTP SPI

- Provide API to create Endpoint with features

JAX-WS 2.1 has the following new features from JAX-WS 2.0 specification:

- WS-Addressing support

- APIs for EndpointReference

  - Creation

    - `BindingProvider.getEndpointReference()`

    - `Endpoint.getEndpointReference()`

    - `MessageContext.getEndpointReference()`

  - EPR Propagation

    - Using JAXB 2.1 bind W3C EPR to `W3CEndpointReference` class

    - Marshall/Unmarshall `W3CEndpointReference` class using JAXB

- User friendly APIs to enable/disable features, such as MTOM and Addressing

JAX-RPC users should note that JAX-WS is a completely different technology than JAX-RPC and thus cannot run JAX-RPC applications on top of JAX-WS. If you have an existing JAX-RPC application it must be converted to work with JAX-WS.

### Fully Dynamic Runtime

In JAX-WS, all artifacts generated by `annotationProcessing`, `wsimport` and `wsgen` are portable. JAX-WS uses the annotations within the SEI to aid in marshalling/unmarshalling messages. Because we no longer generated non-portable artifacts, we were able to get rid of tools like JAX-RPC's `wsdeploy`. The user now can create their own deployable WAR file. To learn more about creating a WAR file and the deployment descriptor, see . It should also be noted that JAX-RPC's `wscompile` tool has been replaced by two new tools: `wsimport` and `wsgen`. `wsimport` is used for importing WSDLs and generating the portable artifacts. `wsgen` processes a compiled SEI and generates the portable artifacts. Unlike JAX-RPC's `wscompile` JAX-WS's `wsgen` does not generate WSDL at tool-time, the WSDL is now generated when the endpoint is deployed. There however is an option on `wsgen` to generate the WSDL for developement purposes.

### MTOM & swaRef

MTOM and swaRef support was added in JAX-WS 2.0 RI FCS release. MTOM and swaref support is required by the JAX-WS 2.0 specification. This means that the MTOM or swaref solution developed with &jax-ws.product.name.short; will be fully portable with any JAX-WS 2.0 compliant implementation.

MTOM implementation was completely re-written to allow streaming attachment support and just like rest of the &jax-ws.product.name.short; runtime its written for better performance. This implementation was released as part of JAX-WS 2.0.1 M1 release.

JAX-WS &jax-ws.release.spec.version; brings in support for optimized transmission of binary data as specified by MTOM (SOAP Message Transmission Optimization Mechanism)/ XOP (XML Binary Optimized Packaing) and swaRef (SOAP Attachment References specified by WS-I Attachment Profile 1.0).

- MTOM allows optimized transmission of binary data - any `xs:base64Binary` or `xs:hexBinary` schema type can be send as attachment following rules defined by XOP encoding and MTOM specification.

- In swaRef, an XML element of `wsi:swaRef` type (defined by WS-I Attachment Profile 1.0) is send as attachment and a referenced based on CID URL schema is put in place of the content of the element.

For details on MTOM and swaRef features refer to .

### SOAP 1.2

SOAP 1.2 support is added to JAX-WS &jax-ws.release.spec.version;. For details refer to .

### XML/HTTP Binding

Support for XML/HTTP binding is added to JAX-WS 2.0. One can directly send XML over HTTP using and implementations. This enables support for REST style Web Services in JAX-WS. For details refer to restful sample.

### JAXB 2.2

&jax-ws.product.name; uses JAXB 2.2 for data-binding between Java and XML which enables features such as separate compilation, type substitution and other improvements.

#### Type Substitution using `@XmlSeeAlso`

JAXB 2.1 defines `@XmlSeeAlso` annotation which can be used to tell JAXB to use the classes mentioned with this annotation. This allows type substitution to takes place. See the `samples/type_substitution/src/type_substitution/server/CarDealer.java` sample that demonstrates it.

`wsimport` tool, generates `@XmlSeeAlso` with all the classes that are not directly referenced by the WSDL operations. To capture all such classes `wsimport` generates `@XmlSeeAlso(ObjectFactory.class)` on the generated Service Endpoint Interface.

#### `@XmlElement` on web service SEI parameters

JAX-WS 2.2 spec allows `@XmlElement` on web service SEI parameters, which enables better control of XML representation. For this support, JAX-WS relies on JAXB 2.2 API which allows the `@XmlElement` annotation on parameters.

### WS-Addressing

&jax-ws.product.name; supports for W3C Core, SOAP Binding and Addressing 1.0 - Metadata specifications and defines standard API and annotations to enable/disable W3C WS-Addressing on the client and service endpoint. In addition to that, JAX-WS RI also supports Member Submission version of WS-Addressing. The member submission version is supported in an implementation specific way. For compatility with JAX-WS 2.1 behavior, JAX-WS RI 2.2 also supports wsdls conforming to WSDL Binding specification.

Refer to for more details. See WS-Addressing samples fromjava-wsaddressing, fromwsdl-wsaddressing-policy and fromwsdl-wsaddressing with the &jax-ws.product.name; for details on the WS-Addressing programming model.

### Annotations

JAX-WS &jax-ws.release.spec.version; relies heavily on the use of annotations as provided by A Metadata Facility for the Java Programming Language (JSR 175) and and Web Services Metadata for the Java Platform (JSR 181) as well as additional annotations defined by JAX-WS &jax-ws.release.spec.version;. These annotations are used to customize the mapping from Java to XML schema/WSDL and are used at runtime to alleviate the need for non-portable serializers/deserializers that were generated in JAX-RPC 1.x. (JSR 269) Pluggable Annotation Processing API comes as replacement of apt

The &jax-ws.product.name.short; utilizes an `javac` Pluggable Annotation Processing API functionality that was introduced in Java SE 6. `javac` allows the SI to process Java source files directly to generate the portable artifacts specified by the JAX-WS 2.0 specification. `javac` comes as replacement of deprecated `apt`. More documentation about `javac` can be found in section Deprecated `apt` will be covered in more detail in section .

For more information on the annotations used by JAX-WS 2.0 please refer to .

### Customizations

&jax-ws.product.name; carries forward customization support introduced in JAX-WS 2.0 RI.

- Define a package where Java artifacts mapped from a WSDL file will be generated

- Package customization for value classes mapped from the imported XML schemas by the WSDL document

- Handler chain customization

JAX-WS 2.0 specification defines standard XML based customization for a WSDL file to Java mapping and to control certain features. These customizations, or binding declarations, can customize almost all WSDL components that can be mapped to Java, such as the service endpoint interface class, method name, parameter name, exception class, etc. The other important thing you can do with these binding declarations is to control certain features, such as asynchrony, provider, wrapper style, and additional headers. For example, a client application can enable asynchrony for a particular operation in a portType, all operations in a `portType`, or all `portType` operations defined in the WSDL file.

These binding declarations can be inlined in a WSDL file or can live outside as an external file. The binding declarations closely align with the JAXB binding declarations. An application importing a WSDL file can inline JAXB bindings inside JAX-WS binding declarations to customize the inlined schema declared in the WSDL file. Schema files that are imported from a WSDL file can be customized using JAXB binding files and can be passed to `wscompile` using the `-b` option switch.

These are the main customization features:

- Scoped binding declarations. An XPath expression is used to specify the target node of the WSDL file on which customization should be applied.

- Close alignment with JAXB bindings. JAXB binding declarations can be inlined in an external JAX-WS binding file.

- Feature Control. Features such as asynchrony, wrapper style, additional header mapping, and provider interfaces can be enabled or disabled.

- Handler chain customization (not yet specified by the 2.0 specification)

The following WSDL component's mapped Java names can be modified:

- generated service endpoint interface class

- method

- method parameter

- generated exception class (for WSDL fault and header fault exceptions)

- header parameter

- generated service class

- port accessor methods in the generated service class

XML Schema Java mapping can be customized using standard JAXB customizations.

For more information on the customizations used by JAX-WS 2.0 please refer to .

### Improved Handler Framework

JAX-WS 2.0 specification defines two types of handlers: logical and protocol handlers. While protocol handlers have access to an entire message such as a SOAP message, logical handlers deal only with the payload of a message and are independent of the protocol being used. Handler chains can now be configured on a per-port, per-protocol, or per-service basis. A new framework of context objects has been added to allow client code to share information easily with handlers.

For more information on the handler framework in &jax-ws.product.name; please refer to .

### Provider

Web service endpoints may choose to work at the XML message level by implementing the `Provider` interface. Here the endpoints access messages or message payloads using this low level, generic API.

For more information on providers in &jax-ws.product.name; please refer to .

### Dispatch

The Dispatch API is intended for advanced XML developers who prefer to use XML constructs at the `java.lang.transform.Source` or `javax.xml.soap.SOAPMessage` level. For added convenience use of the `Dispatch` API with JAXB data-bound objects is supported. The `Dispatch` API can be used in both `Message` and `Payload` modes.

For more information on the `Dispatch` please refer to .

### Asynchronous Client Operations

For more information on asynchronous clients in &jax-ws.product.name; please refer to .

## Programming Model

This section of the documentation will focus on the programming model for both developing and publishing a web service endpoint, and writing a web service client. A web service endpoint is the implementation of a web service. A web service client is an application that accesses a web service.

### Server

When developing a web service endpoint, a developer may either start from a Java endpoint implementation class or from a WSDL file. A WSDL (Web Services Description Language) document describes the contract between the web service endpoint and the client. A WSDL document may include and/or import XML schema files used to describe the data types used by the web service. When starting from a Java class, the tools generate any portable artifacts as mandated by the spec. When starting from a WSDL file and schemas, the tools generate a service endpoint interface.

There is a trade-off when starting from a Java class or from a WSDL file. If you start from a Java class, you can make sure that the endpoint implementation class has the desirable Java data types, but the developer has less control of the generated XML schema. When starting from a WSDL file and schema, the developer has total control over what XML schema is used, but has less control over what the generated service endpoint and the classes it uses will contain.

#### Starting from Java

The basic process for deploying a web service from a Java class consists of two steps.

1. Generate portable artifacts.

2. Create a WAR file to deploy

#### Generate Portable Artifacts

Portable artifacts generated by &jax-ws.product.name; include zero or more JavaBean classes to aide in the marshaling of method invocations and responses, as well as service-specific exceptions.

In document/literal wrapped mode, two JavaBeans are generated for each operation in the web service. One bean is for invoking the other for the response. In all modes (rpc/literal and both document/literal modes), one JavaBean is generated for each service-specific exception.

When starting from Java the developer must provide the JAX-WS tools with a valid endpoint implementation class. This implementation class is the class that implements the desired web service. JAX-WS has a number of restrictions on endpoint implementation classes. A valid endpoint implementation class must meet the following requirements:

- It must carry a javax.jws.WebService annotation (see JSR 181).

- Any of its methods may carry a javax.jws.WebMethod annotation (see 7.5.2).

- All of its methods may throw java.rmi.RemoteException in addition to any service-specific exceptions.

- All method parameters and return types must be compatible with the JAXB 2.0 Java to XML Schema mapping definition.

- A method parameter or return value type must not implement the java.rmi.Remote interface either directly or indirectly.

Here is an example of a a simple endpoint implementation class ``samples/fromjava/src/fromjava/server/AddNumbersImpl.java`` from the fromjava sample:

    package fromjava.server;

    import javax.jws.WebService;

    @WebService
    public class AddNumbersImpl {
        /**
         * @param number1
         * @param number2
         * @return The sum
         * @throws AddNumbersException if any of the numbers to be added is
         * negative.
         */
        public int addNumbers(int number1, int number2) throws
                AddNumbersException {
            if (number1 < 0 || number2 < 0) {
                throw new AddNumbersException("Negative number cant be " +
                        "added!", "Numbers: " + number1 + ", " + number2);
            }
            return number1 + number2;
        }
    }

If you are familiar with JAX-RPC 1.1, you will notice that this implementation class does not implement a service endpoint interface. In &jax-ws.product.name; a service endpoint interface is no longer required.

When starting from a Java endpoint implementation class, it is recommended that the portable artifacts be generated from source using `annotationProcessing`. This because the JAX-WS tools will then have full access to the source code and will be able to utilize parameter names that are otherwise not available through the Java reflection APIs. If the source for the endpoint implementation class is not available, the portable artifacts can be generated using `wscompile`. Here is a sample `annotationProcessing` Ant task from the samples:

    <annotationProcessing
            debug="${debug}"
            verbose="${verbose}"
            destdir="${build.classes.home}"
            sourceDestDir="${build.classes.home}"
            srcdir="${basedir}/src"
            includes="**/server/*.java"
            sourcepath="${basedir}/src">

        <classpath refid="jax-ws.classpath"/>
    </annotationProcessing>

More information about the `annotationProcessing` Ant task can be found . If this task is run on the fromjava sample, the output would include:

    AddNumbers.class
    AddNumbers.java
    AddNumbersExceptionBean.class
    AddNumbersExceptionBean.java
    AddNumbersResponse.class
    AddNumbersResponse.java

The `AddNumbersImplService.wsdl` file describes the web service. The `schema1.xsd` file is imported by the `AddNumbersImplService.wsdl` and contains the datatypes used by the web service. The `AddNumbers.class`/`AddNumbers.java` files contain the a bean used by a JAXB to marshall/unmarshall the `addNumbers` request. The `AddNumbersExceptionBean.class`/`AddNumbersExceptionBean.java` file is a bean used by JAXB to marshall the contents of the `AddNumbersException` class. The `AddNumbersResponse.class`/`AddNumbersResponse.java` files represent the response bean used by JAXB to marshall/unmarshall the `addNumbers` response.

#### Create a WAR file to deploy

Creating a WAR file is nothing more than packaging the service endpoint interface (if there is one), service endpoint implementation, Java classes used by the endpoint implementation and a deployment descriptor in WAR format. For the fromjava sample the `AddNumbersImpl` and `AddNumbersException` classes in the fromjava.server package, and the deployment descriptor are bundled together to make a raw WAR file. To learn more about creating a WAR file and the deployment descriptor, see . The deployment descriptor used in fromjava sample is given below and can be found `samples/fromjava/etc/sun-jaxws.xml`:

    <?xml version="1.0" encoding="UTF-8"?>
    <endpoints xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime'
            version='2.0'>
        <endpoint name='fromjava'
                implementation='fromjava.server.AddNumbersImpl'
                url-pattern='/addnumbers'/>
    </endpoints>

The attributes of the `<endpoint>` element are described below:

- name is simply an identifier for this endpoint

- implementation is used to specify the endpoint implementation class

- urlpattern is used to URL pattern used to access this endpoint.

The structure of the raw WAR file is shown below:

    META-INF/MANIFEST.MF
    WEB-INF/sun-jaxws.xml
    WEB-INF/web.xml
    WEB-INF/classes/fromjava/server/AddNumbersException.class
    WEB-INF/classes/fromjava/server/AddNumbersImpl.class
    WEB-INF/classes/fromjava/server/jaxws/AddNumbers.class
    WEB-INF/classes/fromjava/server/jaxws/AddNumbersExceptionBean.class
    WEB-INF/classes/fromjava/server/jaxws/AddNumbersResponse.class

The WAR file created can now be published on a &jax-ws.product.name.short; enabled servlet container such as the Sun Java System Application Server Platform Edition 8.2

#### Starting from a WSDL File

The basic process for deploying a web service when starting from a WSDL document consists of the following four steps:

1. Generate a service endpoint interface.

2. Implement the service endpoint interface.

3. Create a WAR file to deploy.

#### Generate a Service Endpoint Interface

This step involves compiling or importing the WSDL file to generate a service endpoint interface and value classes mapped from imported XML schemas.

Below is a sample `wsimport` Ant target:

    <wsimport
            debug="${debug}"
            verbose="${verbose}"
            keep="${keep}"
            destdir="${build.classes.home}"
            wsdl="${server.wsdl}">

        <binding dir="${basedir}/etc"
                includes="${server.binding}"/>
    </wsimport>

Its commandline equivalent is:

    wsimport.sh etc/AddNumbers.wsdl -b custom-server.xml

Lets look at the excerpt of `samples/fromwsdl/etc/AddNumbers.wsdl` from the sample fromwsdl:

The generated service endpoint interface looks as follows:

    package fromwsdl.server;

    @javax.jws.WebService(
            name = "AddNumbersPortType",
            serviceName = "AddNumbersService",
            targetNamespace = "http://duke.example.org")
    @javax.jws.soap.SOAPBinding(
            style = javax.jws.soap.SOAPBinding.Style.DOCUMENT,
            use = javax.jws.soap.SOAPBinding.Use.LITERAL,
            parameterStyle = javax.jws.soap.SOAPBinding.ParameterStyle.WRAPPED)
    public interface AddNumbersPortType extends java.rmi.Remote {
        @javax.jws.WebMethod(operationName = "addNumbers")
        @javax.jws.WebResult(name = "return")
        public int addNumbers(@javax.jws.WebParam(name = "arg0") int arg0,
                              @javax.jws.WebParam(name = "arg1") int arg1)
                throws fromwsdl.server.AddNumbersFault_Exception, java.rmi.RemoteException;
    }

The generated service endpoint interface has annotations that can be used by the future versions of JAX-WS 2.0 to do dynamic binding and serialization/deserialization at runtime. Alternatively this service endpoint interface can be used to generate a WSDL and schema file. Please note that round-tripping is not guaranteed in this case. So the generated WSDL file and schema may not be the same as the one the service endpoint interface was generated from.

#### Implement the Service Endpoint Interface

The next thing to do will be to provide the implementation of the service endpoint interface generated in the previous step. When you implement the service endpoint interface it is necessary to provide a `@WebService` annotation on the implementation class with a endpointInteface element specifying the qualified name of the endpoint interface class. Let's look at the implementation class `samples/fromwsdl/src/fromwsdl/server/AddNumbersImpl.java` from the sample application fromwsdl:

    package fromwsdl.server;

    @WebService(endpointInterface = "fromwsdl.server.AddNumbersPortType")
    public class AddNumbersImpl implements AddNumbersPortType {
        /**
         * @param number1
         * @param number2
         * @return The sum
         * @throws AddNumbersException if any of the numbers to be added is
         * negative.
         */
        public int addNumbers(int number1, int number2) throws
                AddNumbersFault_Exception {
            ...
        }
    }

#### Create a WAR

This step is similar to the one described above in .

Here the service endpoint interface implementation class from previous step, together with a deployment descriptor file sun-jaxws.xml, and `web.xml` should be bundled together with the service endpoint interface, value classes generated in the first step mentioned in .

Let's look at `samples/fromwsdl/etc/sun-jaxws.xml` from the sample application fromwsdl:

    <?xml version="1.0" encoding="UTF-8"?>
    <endpoints xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime"
            version="2.0">
        <endpoint name="fromwsdl"
                interface="fromwsdl.server.AddNumbersPortType"
                implementation="fromwsdl.server.AddNumbersImpl"
                wsdl="WEB-INF/wsdl/AddNumbers.wsdl"
                service="{http://duke.example.org}AddNumbersService"
                port="{http://duke.example.org}AddNumbersPort"
                url-pattern="/addnumbers"/>
    </endpoints>

It defines the deployment-related configuration information for the fromwsdl endpoint. You will notice that this deployment descriptor contains additional attributes than the deployment descriptor described in . The interface attribute references the service endpoint interface generated in step 1. The wsdl attribute also points at the WSDL that was imported by `wsimport`. The service attribute references which service in the WSDL this endpoint is from and the port is the name of the port in that service for this endpoint.

To learn more about creating a WAR file and the deployment descriptor, see .

The WAR file created can now be published on a &jax-ws.product.name.short; enabled servlet container such as the Sun Java System Application Server Platform Edition 8.2

#### J2SE Endpoints

Endpoints can be created and published programmatically using `javax.xml.ws.Endpoint` API in J2SE. To learn more about these endpoints, see .

### Client

A client application can access a remote web service endpoint in one of two ways: port and dispatch.

#### Dynamic Proxy

In this approach client side invokes Web services via a dynamic proxy. The proxies for the Web Service are created from the generated Service and service endpoint interfaces. Once the proxies are created. the client application can invoke methods on those proxies just like a standard implementation of those interfaces. The sections below describe this process more detail.

#### Generate Client Artifacts

The `wsimport` tool is used to generate the service endpoint interface and the service interface classes. Below is the sample `wsimport` Ant target:

    <wsimport
            debug="${debug}"
            verbose="${verbose}"
            keep="${keep}"
            destdir="${build.classes.home}"
            wsdl="${client.wsdl}">
        <classpath>
            <path refid="jax-ws.classpath"/>
            <pathelement location="${build.classes.home}"/>
        </classpath>
        <binding dir="${basedir}/etc" includes="${client.binding}"/>
    </wsimport>

The command line equivalent of this Ant target is:

    wsimport.sh -classpath client_classpath -d dest_dir -s src_dir \
        -b custom-client.xml http://localhost:8080/jax-ws-fromwsdl/addnumbers?WSDL

For more details see the documentation.

Here is the excerpt from `samples/fromwsdl/src/fromwsdl/client/AddNumbersClient.java` in the fromjava sample application:

    //get the port
    AddNumbersPortType port = new AddNumbersService().getAddNumbersPort();

    //invoke the remote method
    int result = port.addNumbers(10, 20);

#### Dispatch

The `Dispatch` API is intended for advanced XML developers who prefer using XML constructs at the `java.lang.transform.Source` or `javax.xml.soap.SOAPMessage` level. For added convenience use of `Dispatch` with JAXB data binding object is supported. With the `XML/HTTP` binding a `javax.activation.DataSource` can also be used. The `Dispatch` APIs can be used in both `Message` and `Payload` modes. The `Dispatch` API client with an `XML/HTTP` binding can be used with REST Web Services. Please see the restful sample program for more information.

For more information on `Dispatch` in &jax-ws.product.name; please refer to .

## Useful Information

Pluggable Annotation Processing API – http://jcp.org/aboutJava/communityprocess/final/jsr269/

Annotation Processing Tool (apt) – http://docs.oracle.com/javase/6/docs/technotes/guides/apt/index.html.

Please use the METRO forum for feedback.

The JAX-WS project on GitHub is: https://github.com/javaee/metro-jax-ws.