Last Modified: 04/04/2005
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 Package Customization
2.2 Wrapper Style
2.3 Asynchrony
2.4 Additional Header Mapping
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 XML Schema Customization
2.10 Handler Chain Customization
The JAX-RPC 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 archictecture. 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 implementions. JAX-RPC 2.0 SI provides complete support for all the binding declarations defined by the specification.
All the binding declaration elements live in http://java.sun.com/xml/ns/jaxrpc
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 jaxrpc:bindings
element is used as a container for JAX-RPC binding declarations. The jaxrpc
prefix maps to the http://java.sun.com/xml/ns/jaxrpc
namespace.
External binding files are semantically equivalent to embedded binding declarations. When wscompile
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 wscompile
may give an error if, upon embedding the binding declarations defined in the external binding files, the resulting WSDL document contains conflicting binding declarations.
The jaxrpc:bindings
declaration appears as the root of all other binding declarations. This top-level jaxrpc: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 jaxrpc:bindings
declaration is same as the WSDL location URI given to wscompile
.
<jaxrpc:bindings wsdlLocation="http://localhost:8080/jaxrpc-external-customize/addnumbers?WSDL" jaxrpc:xmlns="http://java.sun.com/xml/ns/jaxrpc"> ... </jaxrpc:bindings>
The root jaxrpc:bindings
element may contain child jaxrpc:bindings
elements. In this case the child jaxrpc: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:
<jaxrpc:bindings wsdlLocation="http://localhost:8080/jaxrpc-external-customize/addnumbers?WSDL" jaxrpc:xmlns="http://java.sun.com/xml/ns/jaxrpc"> <jaxrpc:bindings node="wsdl:definitions" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"> <jaxrpc:package name="external_customize.client"/> ... </jaxrpc:bindings>
In this example the child jaxrpc: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.
Embedded binding declarations 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-RPC 2.0 specification:
jaxrpc:bindings
element as a WSDL extension.jaxrpc:bindings
element is used as a WSDL extension, it must not have a node attribute.jaxrpc:bindings
.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 --> <jaxrpc:bindings xmlns:jaxrpc="http://java.sun.com/xml/ns/jaxrpc"> <!-- rename the generated SEI from AddNumbersImpl to MathUtil --> <jaxrpc:class name="MathUtil"/> ... </jaxrpc:bindings> <wsdl:operation name="addNumber"> ... </wsdl:portType>
The above WSDL file excerpt shows the wsdl:portType
customization. jaxrpc: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 jaxrpc:class
customizes the generated class to be named MathUtil
instead of AddNumberImpl
.
This section provides the details of all the possible WSDL binding declarations.
By default wscompile
generates WSDL artifacts in a package computed from the WSDL targetNamespace
. For example, a WSDL file with the targetNamespace
http://duke.org
without any package customization will be mapped to the org.duke
package. To customize the default package mapping you would use a jaxrpc:package
customization on the wsdl:definitions
node.
For example:
<bindings xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" wsdlLocation="http://localhost:8080/jaxrpc-external-customize/addnumbers?WSDL" xmlns="http://java.sun.com/xml/ns/jaxrpc"> <bindings node="wsdl:definitions"> <package name="external_customize.client"/> ...
wscompile
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 jaxrpc:enableWrapperStyle
.
jaxrpc:enableWrapperStyle
can have following target nodes:
wsdl:definitions
: global scope, applies to all the wsdl:operations
of all wsdl:portType
attributeswsdl: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/jaxrpc-external-customize/addnumbers?WSDL" xmlns="http://java.sun.com/xml/ns/jaxrpc"> <bindings node="wsdl:definitions"> <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 wscompile
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 wscompile
to generate a bare Java method signature.
A client application can use the jaxrpc:enableAsyncMapping
binding declaration so that wscompile
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
: 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/jaxrpc-external-customize/addnumbers?WSDL" xmlns="http://java.sun.com/xml/ns/jaxrpc"> <bindings node="wsdl:definitions"> <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 wscompile
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 wscompile
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>);
As described in the JAX-RPC 2.0 specification additional headers are the WSDL parts referenced from soap:header
in wsdl:binding
that don't belong to the input or output message. By default these additional headers are not mapped to Java parameters. To map these headers to the parameter jaxrpc:enableAdditionalSOAPHeaderMapping
the binding declaration should be set to true. Its default value is false.
jaxrpc:enableAdditionalSOAPHeaderMapping
can be applied to the following target nodes:
wsdl:definitions
: global scope, applies to all wsdl:operations
of all wsdl:binding
elementswsdl:binding
: applies to all wsdl:operations
in this wsdl:binding
elementwsdl:operation
: applies to only this wsdl:operation
inside the wsdl:binding
elementThis binding declaration looks like:
<bindings xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" wsdlLocation="http://localhost:8080/jaxrpc-external-customize/addnumbers?WSDL" xmlns="http://java.sun.com/xml/ns/jaxrpc"> <bindings node="wsdl:definitions"> <enableAdditionalSOAPHeaderMapping>false</enableAdditionalSOAPHeaderMapping> ...
By default the value of jaxrpc: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.
The generated class for wsdl:portType
, wsdl:fault
, soap:headerfault
, and wsdl:server
can be customized using the jaxrpc:class
binding declaration. Refer to the external binding declaration file custom-client.xml
in the external-customize
sample.
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"/>
wscompile
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"/> </bindings>
wscompile
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"/> </bindings>
The jaxrpc: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.
wscompile
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"/> ...
wscompile
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"/> </bindings>
The jaxrpc: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
and it can be applied to header parameters defined inside a wsdl:operation
of the wsdl:binding
section. 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
.
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 jaxrpc:bindings
element in an external binding declaration file:
<jaxrpc:bindings node="wsdl:definitions/wsdl:types/xsd:schema[@targetNamespace='http://duke.org']"> <jaxb:schemaBindings> <jaxb:package name="fromwsdl.server"/> </jaxb:schemaBindings> </jaxrpc: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/jaxrpc-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 wscompile
using the -b
switch. See the JAX-RPC tools documentation for details.
Handler chain customization is not yet specified by the 2.0 specification. The JAX-RPC 1.x SI allowed handler chain customization using a configuration file. In JAX-RPC 2.0 SI the same handler chain customizations can be used by wrapping them inside a jaxrpc:bindings
element. Below is a sample JAX-RPC binding declaration file with handler chain configuration:
<jaxrpc: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/jaxrpc-fromwsdlhandler/addnumbers?WSDL" xmlns:jaxrpc="http://java.sun.com/xml/ns/jaxrpc"> <jaxrpc:bindings node="wsdl:definitions"> <handlerChains xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config"> <chain runAt="client"> <handler className="fromwsdlhandler.common.LoggingHandler"/> </chain> </handlerChains> </jaxrpc:bindings> </jaxrpc:bindings>
Copyright © 2005 Sun Microsystems, Inc. All rights reserved.