When declaring binding in an external document (file), the client who is the main user of the web service, passes the WSDL document path as a parameter of the wsimport tool. The path is set in the wsdlLocation element of the binding declaration document.

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

To configure component binding in the WSDL document, add it as the child element of the previously declared root element. Place the components inside the node element by using the XPath syntax. Add the binding as a child element of the node element.

The following is an example of adding an element for the binding configuration in the WSDL document.

<jaxws:bindings
    wsdlLocation="http://localhost:8088/AddNumbers/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="customize.client"/>
        ...
</jaxws:bindings>

As shown in the previous example, the binding declaration means that the package name of Java classes created for wsdl:definitions in the WSDL document will be customized to 'customize.client'.

The created external binding declaration document can be executed using the wsimport tool as in the following.

$ wsimport -b custom-client.xml http://localhost:8088/AddNumbers/addnumbers?WSDL

The following are the differences in declaring binding directly in the WSDL document instead of in an external document.

<wsdl:portType name="AddNumbersImpl">
    <jaxws:bindings xmlns:jaxws="http://java.sun.com/xml/ns/jaxws">
        <jaxws:class name="MathUtil"/>
        ...
    </jaxws:bindings>
    <wsdl:operation name="addNumber">
    ...
</wsdl:portType>

The previous example shows how to customize the <wsdl:portType> element in the WSDL document.

The extension element, <jaxws:bindings>, is the customization of a service endpoint interface class name, which is generated from wsdl:portType. The example shows that the class name, AddNumbersImpl, which is generated with the default value, is customized to 'MathUtil'.

The global bindings are valid from the binding declarations defined in an external document file, and they apply to the entire scope of wsdl:definition in the WSDL document referenced by the jaxws:bindings@wsdlLocation.

<jaxws:package name="..."/> 
<jaxws:enableWrapperStyle/> 
<jaxws:enableAsyncMapping/>

These elements have global scope.

They are used as in the following.

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

When creating a Java class from WSDL document by using the wsimport tool, the class package name is determined by the namespace of the WSDL file.

To customize the class package name, declare the binding customization with the jaxws:package element. The package name can be modified with the '-p' option when created through the wsimport command line, and the modified name overwrites what was previously customized by the jaxws:package element.

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

The declaration can be shortened as in the following.

<jaxws: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="customize.client" />
...
</jaxws:bindings>

By default, the wsimport tool applies the wrapper style rule to an abstract operation set to the wsdl:portType element in WSDL document. A user can disable the wrapper style through binding customization.

<jaxws:bindings
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    wsdlLocation="http://localhost:8080/AddNumbers/addnumbers?WSDL"
    xmlns="http://java.sun.com/xml/ns/jaxws">
        <enableWrapperStyle>true</enableWrapperStyle>
    <bindings node="wsdl:definitions/
        wsdl:portType[@name='AddNumbersImpl']/
        wsdl:operation[@name='addNumbers']">
        <enableWrapperStyle>false</enableWrapperStyle>
    ...
</jaxws:bindings>

The wrapper style can be set through the jaxws:enableWrapperStyle element, and can be used inside the wsdl:definitions, wsdl:portType and wsdl:operation elements.

The client application generates asynchronous polling or callback operations when executing wsimport by declaring the jaxws:enableAsyncMappingbinding element. For more information about asynchronous client applications, refer to "Chapter 9. Asynchronous Web Services".

The same rules for the wrapper style apply to the components and application scope within the WSDL document.

<jaxws:bindings
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    wsdlLocation="http://localhost:8080/AddNumbers/addnumbers?WSDL"
    xmlns="http://java.sun.com/xml/ns/jaxws">
        <enableAsyncMapping>false</enableAsyncMapping>
    <bindings node="wsdl:definitions/
        wsdl:portType[@name='AddNumbersImpl']/
        wsdl:operation[@name='addNumbers']">
        <enableAsyncMapping>true</enableAsyncMapping>
    ...
</jaxws:bindings>

This section describes how to declare a provider interface through binding declaration. For more information, refer to "Chapter 8. Provider and Dispatch Interfaces".

To declare a port as a provider interface in the WSDL document, use the XPath syntax to configure the wsdl:port node, and then declare the jaxws:provider binding. By default, the provider interface is not declared and is only available when creating a web service from WSDL.

In a WSDL document, wsdl:portType, wsdl:fault, soap:headerfault, and wsdl:server elements are created as Java classes, and the class names can be modified through jaxws:class binding declaration. The following describes each of the Java component classes in the WSDL document.

Use the jaxws:method binding declaration to customize a method name for obtaining the service endpoint method name or service class port.

The jaxws:parameter binding declaration is used to change the parameter name of the implemented Java method into a preferred one. A user can modify the method parameter name of wsdl:operation or wsdl:portType.

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

As shown in the previous example, the java parameter customization declaration changes the method parameter name of wsdl:operation, from 'number1' to 'num1'.

XML schema declared in the WSDL document can be modified by using the standard JAXB binding element inside the jaxws:bindings element.

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

In addition, a user can apply binding customization to XML schema files imported by the WSDL document. In such a case, use the JAXB standard extension 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:8088/AddNumbers/schema1.xsd"
        node="/xsd:schema">
        <jxb:schemaBindings>
            <jxb:package name="fromjava.client"/>
        </jxb:schemaBindings>
    </jxb:bindings>
...

The external standard JAXB binding declaration file is transmitted by using the '-b' option of the wsimport tool.

The jaxws:bindings binding declaration is also used to add or customize a handler. For more information about handlers, refer to "Chapter 7. Handler Framework".

To add or modify handler information to a binding customization declaration, configure the handler chain in jaxws:bindings element, as stated in the schema(JAR 181) for handler chain settings.

<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 portable artifacts are created by using the wsimport tool with an external binding declaration document or WSDL document, a handler configuration file is also created. When a service endpoint interface class is created, the @javax.jws.HandlerChain annotation that is used by JAX-WS runtime to search for handlers is added to the class.