Arun Gupta's Blog

JAX-WS SEI/WSDL Processing Extension Hooks

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.

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}

Comments

• Arun,
  These capabilities are very useful.
  I've been trying to add a WSDLGenerationExtension without success. I added the com.sun.xml.ws.api.wsdl.writer.WSDLGeneratorExtension to one of my app jar files in META-INF/services but the extension doesn't seem to be loaded.
  I'm working with Tomcat 5.X and JAX-WS RI 2.1
  Are there any known issues with SPI in JAX-WS 2 or any problem with any container?

  Posted by: pablius on April 04, 2007 at 06:48 AM

• Hi pablius,

  I posted your question at:

  http://forums.java.net/jive/thread.jspa?threadID=25051

  Please follow it there.

  Posted by: arungupta on April 09, 2007 at 04:56 PM

This work is licensed under a Creative Commons License.