This chapter describes how to declare and customize standardized binding.
As stated in the previous chapter, JAX-WS web services can be implemented from Java class or WSDL document.
Various functions can be added to implement more extensible web services. They can be added through wsgen by embedding annotations in Java class files, or through wsimport by adding the functions to WSDL documents.
This section introduces binding customization used to configure a client or web service through the wsimport tool by using WSDL document. The next section will provide the function details, and how to configure and implement a Web service with Java classes by using the wsgen tool.
JEUS Web service supports the binding declaration and customization of Java classes in WSDL file (if mainly using the wsimport tool) through a standardized method as requested by JAX-WS. In the existing JAX-RPC web services, this standard is not specified and web services are not portable across vendors.
The following are the roles that the standardized binding declaration and customization plays in implementing web services.
Customize mapping from almost all WSDL components to the Java language including service endpoint interface class, method name, parameter name, and exception class.
Customize functions like asynchronization, provider, wrapper, and additional headers.
Elements related to all bindings belong to the namespace, http://java.sun.com/xml/ns/jaxws, and bindings are declared as the 'jaxws:bindings' element by adding 'jaxws' to the prefix of the namespace.
A binding can be declared in either of the following.
External document.
WSDL document.
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.
[Example 6.1] << custom-client.xml >>
<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.
[Example 6.2] << custom-client.xml >>
<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.
The <jaxws:bindings> element is used as an extension element in the WSDL document.
The node attribute is not used.
The <jaxws:bindings> element is not used as a child element of the <jaxws:bindings> element.
The <jaxws:bindings> element only affects the WSDL component which is wrapping it.
[Example 6.3] << AddNumbers.wsdl >>
<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'.
This section describes the customization of the declared bindings with the following details.
Overall binding
Customizing a package name
Wrapper style
Asynchronization
Provider interface
Customizing a class name
Customizing Java methods
Customizing Java parameters
Customizing XML schema
Customizing handler chains
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.
[Example 6.4] << custom-client.xml >>
<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.
[Example 6.5] << custom-client.xml >>
<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.
[Example 6.6] << custom-client.xml >>
<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.
[Example 6.7] << custom-client.xml >>
<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.
If used inside the wsdl:definitions, it is applied to all wsdl:operations elements of all wsdl:portType attributes.
If used inside the wsdl:portType, it is applied to all wsdl:operations elements of the portType.
If used Inside the wsdl:operation element, it is applied only to the operation.
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.
[Example 6.8] << custom-client.xml >>
<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.
Service Endpoint Interface Class
The following is an example of binding customization for a service endpoint interface class name.
[Example 6.9] << custom-client.xml >>
<jaxws:bindings node="wsdl:definitions/wsdl:portType[@name='AddNumbersImpl']">
<jaxws:class name="TmaxUtil" />
</jaxws:bindings>
In the previous example, the service endpoint interface class name is TmaxUtil, instead of the default name, AddNumbersImpl.
Exception Class
The following is an example of binding customization for an exception class name.
[Example 6.10] << custom-client.xml >>
<jaxws:bindings node="wsdl:definitions/
wsdl:portType[@name='AddNumbersImpl']/
wsdl:operation[@name='addNumbers']/
wsdl:fault[@name='AddNumbersException']">
<jaxws:class name="TmaxException" />
</jaxws:bindings>
In this example, the exception class name is TmaxException, instead of the default name, AddNumbersException.
Service Class
The following is an example of binding customization for a service class name.
[Example 6.11] << custom-client.xml >>
<jaxws:bindings node="wsdl:definitions/
wsdl:service[@name='AddNumbersService']">
<jaxws:class name="TmaxService" />
</jaxws:bindings>
In the example, the service class name is TmaxService, instead of the default name, AddNumbersService.
Use the jaxws:method binding declaration to customize a method name for obtaining the service endpoint method name or service class port.
Service Endpoint Interface Method
The following is an example of binding declaration for modifying the service endpoint interface method name.
[Example 6.12] << custom-client.xml >>
<jaxws:bindings node="wsdl:definitions/
wsdl:portType[@name='AddNumbersImpl']/
wsdl:operation[@name='addNumbers']">
<jaxws:method name="add" />
</jaxws:bindings>
The wsimport tool will use 'add', not the default value 'addNumbers', as the method name of the service endpoint interface.
Service Class Methods to Access the Port
The following is an example of binding declaration for modifying the name of the service class method for port access.
[Example 6.13] << custom-client.xml >>
<jaxws:bindings node="wsdl:definitions/
wsdl:service[@name='AddNumbersService']/
wsdl:port[@name='AddNumbersImplPort']">
<jaxws:method name="getTmaxUtil" />
</jaxws:bindings>
The wsimport tool will use 'getTmaxUtil', not the default value 'getAddNumbersImplPort', as the service class method name for port access.
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.
[Example 6.14] << custom-client.xml >>
<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.
[Example 6.15] << custom-client.xml >>
<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.
[Example 6.16] << custom-client.xml >>
<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.
[Example 6.17] << custom-client.xml >>
<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.