Skip to main content

JAX-WS SEI/WSDL Processing Extension Hooks

Posted by arungupta on February 9, 2007 at 7:59 AM PST

One of the key advantages of JAX-WS
Reference Implementation ([1],
[2],
[3],
[4],
[5])
is it's extensible nature. Several extensibility hooks, defined as
abstract classes, are enabled
through out the JAX-WS RI that allow to extend the core JAX-WS functionality for
WSDL/Service Endpoint Interface processing.
This document explains these hooks and their intended purpose. 

An implementation of extensibility hook is discovered using the Service
Provider
mechanism. If the service provider file required by the extension
hook is present in the classpath in META-INF/services directory,
then JAX-WS tool time or runtime (whatever is appropriate) picks up the
implementation advertised by the service provider and invokes the relevant
methods. The implementation of these methods is provided with the information
required to perform the intended functionality. 

The different extensibility points, to impact the WSDL/Service Endpoint
Interface generation and consumption, enabled by JAX-WS RI are explained next.

1.0 Tool time WSDL Parsing

This extension hook, defined by com.sun.tools.ws.api.wsdl.TWSDLExtensionHandler
service provider, allows participation in the tool time WSDL parsing for the extensibility
elements
in a WSDL. This enables an extension handler to be registered with
the JAX-WS WSDL importing tool, wsimport, for a namespace different
from that of WSDL 1.1. This allows such handlers to retrieve information from
WSDL elements, and use that later to, for example, generating annotations. The
appropriate method in the registered extension handler is invoked if an
extensibility element in that namespace is encountered during tool time WSDL
parsing. 



For example, JAX-WS RI registers a tool time WSDL parsing extension handler, com.sun.tools.ws.wsdl.parser.W3CAddressingExtensionHandler,
for
the http://www.w3.org/2005/08/addressing/wsdl
(W3C WS-Addressing namespace and bound to wsaw prefix) namespace. The handleInputExtension
method is invoked if wsdl:portType/wsdl:operation/wsdl:input
contains wsaw:Action attribute. Similarly other methods from TWSDLExtensionHandler,
where WS-Addressing elements can occur and need to be handled, are overridden as
well. 

Any data accessed from the extension element in WSDL may be stored in a data
structure internal to JAX-WS RI. Alternatively if an extension handler, living
outside JAX-WS RI, is registered then it is recommended that an extension element, of type com.sun.tools.ws.api.wsdl.TWSDLExtension,
be created and added as an extension to com.sun.tools.ws.api.wsdl.TWSDLExtensible
(for example

com.sun.tools.ws.api.wsdl.TWSDLOperation)
to store any information required later.

The tool time WSDL parsing creates a complete DOM tree of the WSDL and thus indexing
by the namespace URI works efficiently.

Table 1 gives the service provider file name and the
corresponding JAX-WS implementation class name.

2.0 Tool time Java SEI Code Generation

This extension hook, defined by com.sun.tools.ws.api.TJavaGeneratorExtension
service provider, allows additional annotations to be generated on a Java
method during the WSDL-to-Java mapping. It may use the information stored in an
internal data structure or com.sun.tools.ws.api.wsdl.TWSDLExtension
element stored during the tool time WSDL parsing stage.

For example, JAX-WS RI uses com.sun.tools.ws.processor.generator.W3CAddressingJavaGeneratorExtension
to generate @javax.xml.ws.Action
annotation on a generated Java method, using information stored in an internal
structure.

Table 1 gives the service provider file name and the
corresponding JAX-WS implementation class name.

3.0 Runtime WSDL Parsing

This extension hook, defined by com.sun.xml.ws.api.wsdl.parser.WSDLParserExtension
service provider, allows participation in runtime WSDL parsing for the
extensibility elements in the WSDL. This allows the registered handlers to
retrieve information from WSDL elements, and use that later to, for example,
generate wsa:Action in the SOAP message. At runtime, all registered
handlers are invoked for an extension element. The handler then makes a decision
about whether it is interested in processing the current element, by peeking at
the QName of the element, or ignore it. This is different from tool-time parsing
where a complete DOM tree of the WSDL allows namespace indexing and thus calls
the correct extension handler.

For example, JAX-WS RI registers a runtime WSDL parsing extension handler, com.sun.xml.ws.wsdl.parser.W3CAddressingWSDLParserExtension,
for processing WS-Addressing extension elements in the WSDL. As mentioned
earlier, any data accessed from the extension element in WSDL may be stored in a
data structure internal to JAX-WS RI. Alternatively if an extension handler,
living outside JAX-WS RI, is registered then it is recommended that an extension element, of type
com.sun.tools.ws.api.wsdl.WSDLExtension,
be created and added as an extension to

com.sun.xml.ws.api.model.wsdl.WSDLOperation

to store any information required later.

To illustrate further, if there is an extension element in the WSDL in wsdl:portType/wsdl:operation/wsdl:input,
then portTypeOperationInput
method is invoked for all the registered extension handlers. If wsdl:input
contains wsaw:Action attribute then it's value is stored in an
internal data structure and later used for generating

wsa:Action
on the SOAP message. Otherwise default
Action
is generated, as defined by WS-Addressing
1.0 - WSDL Binding
, by querying other data from the WSDL.

Another example is where WSIT defines com.sun.xml.ws.policy.jaxws.PolicyWSDLParserExtension
to process all WS-Policy related extension elements in the WSDL.

Table 1 gives the service provider file name and the
corresponding WSIT implementation class name.

4.0 Runtime WSDL Generation

This extension hook, defined by com.sun.xml.ws.api.wsdl.writer.WSDLGeneratorExtension
service provider, allows participation in runtime generation of extensibility elements
in the WSDL. This allows the registered handlers to
generate their own extensibility elements on various WSDL elements. Each method
is invoked with a com.sun.xml.txw2.TypedXmlWriter
parameter with an underlying WSDL element. This allows to add an attribute, declare a new
namespace URI or append a new child element to the underlying WSDL element. Each
method is passed the information required to generate the extensibility element.

For example, JAX-WS RI registers a runtime WSDL generation handler, com.sun.xml.ws.wsdl.writer.W3CAddressingWSDLGeneratorExtension
for generating WS-Addressing extension elements in the WSDL. The addOperationInputExtension
method is invoked when wsdl:portType/wsdl:operation/wsdl:input is
generated. The JAX-WS RI handler obtains the value of  @javax.xml.ws.Action
annotation from the java.lang.reflect.Method and generates the
appropriate wsaw:Action attribute.

Another example is where WSIT defines com.sun.xml.ws.policy.jaxws.PolicyWSDLGeneratorExtension
to generate all WS-Policy related extension elements in the WSDL.

Table 1 gives the service provider file name and the
corresponding WSIT implementation class name.

  Service Provider File Name Sample Implementation
Tool time WSDL Parsing com.sun.tools.ws.api.wsdl.TWSDLExtensionHandler com.sun.tools.ws.wsdl.parser.W3CAddressingExtensionHandler
Tool time Java Generation com.sun.tools.ws.api.TJavaGeneratorExtension com.sun.tools.ws.processor.generator.W3CAddressingJavaGeneratorExtension
Runtime WSDL Parsing com.sun.xml.ws.api.wsdl.parser.WSDLParserExtension com.sun.xml.ws.policy.jaxws.PolicyWSDLParserExtension
Runtime WSDL Generation com.sun.xml.ws.api.wsdl.writer.WSDLGeneratorExtension com.sun.xml.ws.policy.jaxws.PolicyWSDLGeneratorExtension

Table 1: Service Provider file name and
Sample Implementations 

In summary, the JAX-WS Reference Implementation provides a
feature-rich platform for middleware developers that allows them to extend the
capabilities of core functionality. The stand-alone JAX-WS implementation can be
downloaded from here. It is also
integrated in GlassFish v2 which can be downloaded from here.

Technorati: JAX-WS
Web services GlassFish
WSIT Extensiblity

Related Topics >>