# Java TM API for XML Web Services
(JAX-WS)
WSDL Customization

Specification Version: 2.2
Implementation Version: 2.2.5

- Overview
- Provider
- AsyncProvider
- Dispatch
- Asynchronous Client
- Handler
- MTOM and Swaref
- SOAP 1.2
- WSDL Customization
- Annotations
- WS-Addressing
- Stateful Webservice
- Catalog
- Interoperability

## Contents

1. Declaring Customizations
1.1 External Binding Declaration
1.1.1 Root Binding Element
1.1.2 Child Binding Elements
1.2 Embedded Binding Declarations
2. Standard Customizations
2.1 Global Customizations
2.2 Package Customization
2.3 Wrapper Style
2.4 Asynchrony
2.5 The Provider Interface
2.6 Class Customization
2.6.1 The Service Endpoint Interface Class
2.6.2 The Exception Class
2.6.3 The Service Class
2.7 Java Method Customization
2.7.1 Service Endpoint Interface Methods
2.7.2 Port Accessor Methods in the Service Class
2.8 Java Parameter Customization
2.9 Javadoc Customization
2.10 XML Schema Customization
2.11 Handler Chain Customization

The JAX-WS 2.0 specification defines standard XML-based customization for WSDL 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 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` or all operations in a `portType` or all `portType` operations defined in the WSDL file.

The JAX-RPC 1.1 specification did not define a standard customization architecture. However JAX-RPC 1.x SI had limited WSDL to Java customization support. It allowed a JAX-RPC 1.x application to:

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

- Customize the package for the value classes mapped from the imported XML schema by the WSDL document.

- Customize handler chains.

But these customizations were not portable and could not be used across other JAX-RPC implementations. JAX-WS RI 2.2.5 provides complete support for all the binding declarations defined by the specification.

## 1. Declaring Customizations

All the binding declaration elements live in `http://java.sun.com/xml/ns/jaxws` namespace. There are two ways to specify binding declarations. In the first approach, all binding declarations pertaining to a given WSDL document are grouped together in a standalone document, called an external binding file. The second approach consists of embedding binding declarations directly inside a WSDL document. In either case, the `jaxws:bindings` element is used as a container for JAX-WS binding declarations. The `jaxws` prefix maps to the `http://java.sun.com/xml/ns/jaxws` namespace.

### 1.1 External Binding Declaration

External binding files are semantically equivalent to embedded binding declarations. When `wsimport` processes the WSDL document for which there is an external binding file, it internalizes the binding declarations defined in the external binding file on the nodes in the WSDL document they target using the `wsdlLocation` attribute. The embedded binding declarations can exist in a WSDL file and an external binding file targeting that WSDL, but `wsimport` may give an error if, upon embedding the binding declarations defined in the external binding files, the resulting WSDL document contains conflicting binding declarations.

#### 1.1.1 Root Binding Element

The `jaxws:bindings` declaration appears as the root of all other binding declarations. This top-level `jaxws:bindings` element must specify the location of the WSDL file as a URI in the value of `wsdlLocation` attribute.

Its important that the `wsdlLocation` attribute on the root `jaxws:bindings` declaration is same as the WSDL location URI given to `wsimport`.

    <jaxws:bindings
        wsdlLocation="http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"
        jaxws:xmlns="http://java.sun.com/xml/ns/jaxws">
    ...
    </jaxws:bindings>

#### 1.1.2 Child Binding Elements

The root `jaxws:bindings` element may contain child `jaxws:bindings` elements. In this case the child `jaxws:bindings` element must carry an XPath expression in the node attribute to refer to the WSDL node it customizes.

Here is an excerpt from an external binding file custom-client.xml in the `external-customize` sample:

    <jaxws:bindings
        wsdlLocation="http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"
        jaxws:xmlns="http://java.sun.com/xml/ns/jaxws">
        <jaxws:bindings node="wsdl:definitions" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
            <jaxws:package name="external_customize.client"/>
            ...
    </jaxws:bindings>

In this example the child `jaxws:bindings` applies package customization. An XPath expression in the node attribute refers to the root node of the WSDL document, which is `wsdl:definitions` and declares the package `external_customize.client` for all the generated Java classes mapped from the WSDL file.

### 1.2 Embedded Binding Declarations

Embedded binding declarations directly inside the WSDL follow different rules compared to the binding declarations declared in the external binding file. Here are some important facts and rules as defined in the JAX-WS 2.0 specification:

- An embedded binding declaration is specified by using the `jaxws:bindings` element as a WSDL extension inside the wsdl node that is to be customized.

- When a `jaxws:bindings` element is used as a WSDL extension, the `jaxws:bindings` element should not have node attribute (the node attribute is only used in external customization file to scope the custmization to a wsdl element).

- A binding declaration embedded in a WSDL can only affect the WSDL element it extends.

Here's an example of embedded binding declarations in the WSDL `AddNumbers.wsdl` from the `inline-customize` sample:

    <wsdl:portType name="AddNumbersImpl">
        <!-- wsdl:portType customizations -->
        <jaxws:bindings xmlns:jaxws="http://java.sun.com/xml/ns/jaxws">
            <!-- rename the generated SEI from AddNumbersImpl to MathUtil -->
            <jaxws:class name="MathUtil"/>
            ...
        </jaxws:bindings>
        <wsdl:operation name="addNumber">
        ...
    </wsdl:portType>

The above WSDL file excerpt shows the `wsdl:portType` customization. `jaxws:bindings` appears as extension element of `portType`. It customizes the class name of the generated service endpoint interface. Without this customization, or by default, the service endpoint interface class is named after the `wsdl:portType` name. The binding declaration `jaxws:class` customizes the generated class to be named `MathUtil` instead of `AddNumberImpl`. In the following section, all the possible standard customizations and their scope is described. Global customizations can be specified under <wsdl:definitions> element and other customizations can be specified under the node of its scope.

## 2. Standard Customizations

This section provides the details of all the possible WSDL binding declarations.

### 2.1 Global bindings

The global customizations are the customizations that applies to the entire scope of wsdl:definition in the wsdl referenced by the root jaxws:bindings@wsdlLocation.
Following customizations have the global scopes:
<jaxws:package name="..."/>
<jaxws:enableWrapperStyle/>
<jaxws:enableAsyncMapping/>
These can appear as direct child of the root binding declarations in the external customization file. For example:

    <bindings
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        wsdlLocation="http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"
        xmlns="http://java.sun.com/xml/ns/jaxws">
            <package name="external_customize.client"/>
           <enableWrapperStyle>true</enableWrapperStyle>
            <enableAsyncMapping>false</enableAsyncMapping>
    </bindings>

In embedded usage, the global customization can be specified under <wsdl:definitions> node of the wsdl.

### 2.2 Package Customization

By default `wscompile` generates WSDL artifacts in a package computed from the WSDL `targetNamespace`. For example, a WSDL file with the `targetNamespace` `http://duke.example.org` without any package customization will be mapped to the `org.duke` package. To customize the default package mapping you would use a `jaxws:package` customization on the `wsdl:definitions` node or it can directly appear inside the top level bindings element.

An important thing to note is that -p option on commandline wsimport.sh tool (package attribute on wsimport ant task), overrides the jaxws:package customization,it also overrides the schema package customization specified using jaxb schema customization.

For example:

    <bindings
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        wsdlLocation="http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"
        xmlns="http://java.sun.com/xml/ns/jaxws">
            <package name="external_customize.client">
                <javadoc>Mathutil package</javadoc>
            </package>
    ...
    or
    <bindings
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        wsdlLocation="http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"
        xmlns="http://java.sun.com/xml/ns/jaxws">
        <bindings node="wsdl:definitions">
            <package name="external_customize.client">
                <javadoc>Mathutil package</javadoc>
            </package>
    ...

### 2.3 Wrapper Style

`wsimport` by default applies wrapper style rules to the abstract operation defined in the `wsdl:portType`, and if an operation qualifies the Java method signature is generated accordingly. Wrapper style Java method generation can be disabled by using `jaxws:enableWrapperStyle`.

`jaxws:enableWrapperStyle` can appear on the toplevel bindings element (with @wsdlLocation attribute), it can also appear on the following target nodes:

- `wsdl:definitions`: global scope, applies to all the `wsdl:operations` of all `wsdl:portType` attributes

- `wsdl:portType` applies to all the `wsdl:operations` in the `portType`

- `wsdl:operation` applies to only this `wsdl:operation`

For example:

    <bindings
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        wsdlLocation="http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"
        xmlns="http://java.sun.com/xml/ns/jaxws">
            <!-- applies to wsdl:definitions node, that would mean the entire wsdl -->
            <enableWrapperStyle>true</enableWrapperStyle>
        <!-- wsdl:portType operation customization -->
        <bindings node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']">
            <!-- change java method name from addNumbers() to add() -->
            <enableWrapperStyle>false</enableWrapperStyle>
        ...

In the example above the wrapper style is disabled for the `addNumbers` operation in `AddNumbersImpl` `portType` .This is because `wsimport` processes this binding in the following order: first `wsdl:operation`, then its parent `wsdl:portType`, and finally `wsdl:definitions`. Here `wsdl:operation` `addNumbers` has this customization disabled so this is what is applied by `wsimport` to generate a bare Java method signature.

### 2.4 Asynchrony

A client application can use the `jaxws:enableAsyncMapping`binding declaration so that `wsimport` will generate async polling and callback operations along with the normal synchronous method when it compiles a WSDL file.

It has the same target nodes as the wrapper style binding declaration described above in section 2.2.

- `wsdl:definitions` or toplevel bindings element: global scope, applies to all the `wsdl:operations` of all `wsdl:portType`

- `wsdl:portType`: applies to all the `wsdl:operations` in the `portType`

- `wsdl:operation`: applies to only this `wsdl:operation`

Example :

    <bindings
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        wsdlLocation="http://localhost:8080/jaxws-external-customize/addnumbers?WSDL"
        xmlns="http://java.sun.com/xml/ns/jaxws">
            <!-- applies to wsdl:definitions node, that would mean the entire wsdl -->
            <enableAsyncMapping>false</enableAsyncMapping>
        <!-- wsdl:portType operation customization -->
        <bindings node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']">
            <!-- change java method name from addNumbers() to add() -->
            <enableAsyncMapping>true</enableAsyncMapping>
        ...

In the above example `wsimport` will generate async polling and callback methods for the `addNumbers` operation. In the `wsdl:definition` node, the async customization is disabled or false but the `wsdl:operation` node has it enabled or true, and so `wsimport` generates the async methods of the `wsdl:operation` `addNumbers`.

This is how the generated signatures look (annotations are removed from synchronous method for reading simplicity):

        //synchronous method
        public int addNumbers(int number1, int number2) throws
            org.duke.AddNumbersFault_Exception,  java.rmi.RemoteException;
        //async polling Method
        public Response<AddNumbersResponse> addNumbers(int number1, int number2);
        //async callback Method
        public Future<?> addNumbers(int number1, int number2, AsyncHandler<AddNumbersResponse>);
    ...

### 2.5 The Provider Interface

By default the value of `jaxws:provider` binding is false. That is, provider interface generation is disabled. In order to mark a port as provider interface this binding declaration should refer to the `wsdl:port` node using an XPath expression. Please note that provider binding declaration applies only when developing a server starting from a WSDL file.

### 2.6 Class Customization

The generated class for `wsdl:portType`, `wsdl:fault`, `soap:headerfault`, and `wsdl:server` can be customized using the `jaxws:class` binding declaration. Refer to the external binding declaration file `custom-client.xml` in the `external-customize` sample.

#### 2.6.1 The Service Endpoint Interface Class

`wscompile` will generate the service endpoint interface class `MathUtil` instead of the default `AddNumbersImpl` in this example:

        <!-- wsdl:portType customization -->
        <bindings node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']">
            <!-- change the generated SEI class -->
            <class name="MathUtil">
                <javadoc>Perform mathematical computations</javadoc>
            </class>

#### 2.6.2 The Exception Class

`wsimport` will generate the `MathUtilException`class instead of the default `AddNumbersExeption` in this example:

        <!-- change the generated exception class name -->
        <bindings node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']/wsdl:fault[@name='AddNumbersException']">
            <class name="MathUtilException">
                <javadoc>Exception generated during computation</javadoc>
            </class>
        </bindings>

#### 2.6.3 The Service Class

`wsimport` will generate `MathUtilService`instead of the default `AddNumbersService` in this example:

        <!-- wsdl:service customization -->
        <bindings node="wsdl:definitions/wsdl:service[@name='AddNumbersService']">
            <!-- change the generated service class -->
            <class name="MathUtilService">
                <javadoc>Service to perform mathematical computations</javadoc>
            </class>
        </bindings>

### 2.7 Java Method Customization

The `jaxws:method` binding declaration is used to customize the generated Java method name of a service endpoint interface and to customize the port accessor method in the generated `Service` class. Refer to the external binding declaration file `custom-client.xml` in the `external-customize` sample.

#### 2.7.1 Service Endpoint Interface Methods

`wsimport` will generate a method named `add`instead of the default `addNumbers` in this example:

        <!-- wsdl:portType operation customization -->
        <bindings node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']">
            <!-- change java method name from addNumbers() to add() -->
            <method name="add">
                <javadoc>Adds the numbers</javadoc>
            </method>
            ...

#### 2.7.2 Port Accessor Methods in the Service Class

`wsimport` will generate the `getMathUtil` port accessor method in the generated `Service` class instead of the default `getAddNumbersImplPort` method in this example:

        <!-- change the port accessor method -->
        <bindings node="wsdl:definitions/wsdl:service[@name='AddNumbersService']/wsdl:port[@name='AddNumbersImplPort']">
            <method name="getMathUtil">
                <javadoc>Returns MathUtil port</javadoc>
            </method>
        </bindings>

### 2.8 Java Parameter Customization

The `jaxws:parameter` binding declaration is used to change the parameter name of generated Java methods. It can be used to change the method parameter of a `wsdl:operation` in a `wsdl:portType.` Refer to the external binding declaration file `custom-client.xml` of the `external-customize` sample.

    <bindings node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']/wsdl:operation[@name='addNumbers']">
            <!-- rename method parameters-->
            <parameter part="definitions/message[@name='addNumbers']/part[@name='parameters']" element="tns:number1" name="num1"/>
    ...

The above sample renames the default parameter name of the Java method `addNumbers` from `number1` to `num1`.

### 2.9 Javadoc customization

jaxws:javadoc customization can be used to specify javadoc text for java package, class(SEI, Service or Exception class) and on the methods in SEI and service class. Inorder to do it,it should appear on the corresponding wsdl nodes.
For package level javadoc:
<jaxws:package name="xs:string">?
<jaxws:javadoc>xs:string</jaxws:javadoc>?
</jaxws:package>
For class level javadoc:
<jaxws:class name="xs:string">?
<jaxws:javadoc>xs:string</jaxws:javadoc>?
</jaxws:class>
For method level javadoc:
<jaxws:method name="xs:string">?
<jaxws:javadoc>xs:string</jaxws:javadoc>?
</jaxws:method>
For specific samples on javadoc customization for class, refer SEI, exception and service customization. For javadoc customization on method refer SEI method and service class port accessor method customization and for package level customization refer package customization.

### 2.10 XML Schema Customization

An XML schema inlined inside a compiled WSDL file can be customized by using standard JAXB bindings. These JAXB bindings can live inside the schema or as the child of a `jaxws:bindings` element in an external binding declaration file:

        <jaxws:bindings node="wsdl:definitions/wsdl:types/xsd:schema[@targetNamespace='http://duke.example.org']">
            <jaxb:schemaBindings>
                <jaxb:package name="fromwsdl.server"/>
            </jaxb:schemaBindings>
        </jaxws:bindings>

External XML schema files imported by the WSDL file can be customized using a JAXB external binding declaration file:

    <jxb:bindings
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
        version="1.0">
        <jxb:bindings schemaLocation="http://localhost:8080/jaxws-external-customize/schema1.xsd" node="/xsd:schema">
            <jxb:schemaBindings>
                <jxb:package name="fromjava.client"/>
            </jxb:schemaBindings>
        </jxb:bindings>
    ...

The external JAXB binding declaration file can be passed to `wsimport` using the `-b` switch. See the JAX-WS tools documentation for details.

### 2.11 Handler Chain Customization

`jaxws:bindings` customization can be used to customize or add handlers. All that is needed is to inline a handler chain configuration conforming to JSR 181 Handler Chain configuration schema inside `jaxws:bindings` element.

Below is a sample JAX-WS binding declaration file with JSR 181 handler chain configuration:

    <jaxws:bindings
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        wsdlLocation="http://localhost:8080/jaxws-fromwsdlhandler/addnumbers?WSDL"
        xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
        xmlns:javaee="http://java.sun.com/xml/ns/javaee">
        <jaxws:bindings node="wsdl:definitions">
            <javaee:handler-chain>
                <javaee:handler-chain-name>LoggingHandlers</javaee:handler-chain-name>
                <javaee:handler>
                    <javaee:handler-name>Logger</javaee:handler-name>
                    <javaee:handler-class>fromwsdlhandler.common.LoggingHandler</javaee:handler-class>
                </javaee:handler>
            </javaee:handler-chain>
        </jaxws:bindings>
    </jaxws:bindings>

When this customization file is passed on to wsimport tool using -b switch together with the WSDL, wsimport generates all the artifacts togather with a handler configuration file which has everything inside `jaxws:bindings` element enclosing the `jws:handler-chain` element. It also add @javax.jws.HandlerChain annotation in the generated SEI class. JAXWS runtime uses the @HandlerChain annotation from the SEI to find the handlers that has to be added into the handle chain.