| Extends the WSDL parsing process.
This interface is implemented by components that build on top of the JAX-WS RI,
to participate in the WSDL parsing process that happens in the runtime.
This allows such components to retrieve information from WSDL extension elements,
and use that later to, for example, configure
Tube s.
How it works?
Each method on this interface denotes one extension point in WSDL
(the place where foreign elements/attributes can be added.) A
RuntimeWSDLParser starts parsing WSDL with a fixed set of
WSDLParserExtension s, and
as it finds extension elements/attributes, it calls appropriate callback methods
to provide a chance for
WSDLParserExtension to parse such
an extension element.
There are two kinds of callbacks.
Attribute callbacks
One is for attributes, which ends with the name
Attributes .
This callback is invoked with
XMLStreamReader that points
to the start tag of the WSDL element.
The callback method can read interesting attributes on it.
The method must return without advancing the parser to the next token.
Element callbacks
The other callback is for extension elements, which ends with the name
Elements .
When a callback is invoked,
XMLStreamReader points to the
start tag of the extension element. The callback method can do
one of the following:
- Return
false without moving
XMLStreamReader ,
to indicate that the extension element isn't recognized.
This allows the next
WSDLParserExtension to see this
extension element.
- Parse the whole subtree rooted at the element,
move the cursor to the
XMLStreamConstants.END_ELEMENT state,
and return
true , indicating that the extension
element is consumed.
No other
WSDLParserExtension s are notified of this extension.
Parsing in callback
For each callback, the corresponding WSDL model object is passed in,
so that
WSDLParserExtension can relate what it's parsing
to the
WSDLModel . Most likely, extensions can parse
their data into an
WSDLExtension -derived classes, then
use
WSDLExtensible interface to hook them into
WSDLModel .
Note that since the
WSDLModel itself
is being built,
WSDLParserExtension may not invoke any of
the query methods on the WSDL model. Those references are passed just so that
WSDLParserExtension can hold on to those references, or put
WSDLExtensible objects into the model, not to query it.
If
WSDLParserExtension needs to query
WSDLModel ,
defer that processing until
WSDLParserExtension.finished(WSDLParserExtensionContext) , when it's
safe to use
WSDLModel can be used safely.
Also note that
WSDLParserExtension s are called in no particular order.
This interface is not designed for having multiple
WSDLParserExtension s
parse the same extension element.
Error Handling
For usability,
WSDLParserExtension s are expected to check possible
errors in the extension elements that it parses. When an error is found,
it may throw a
WebServiceException to abort the parsing of the WSDL.
This exception will be propagated to the user, so it should have
detailed error messages pointing at the problem.
Discovery
The JAX-WS RI locates the implementation of
WSDLParserExtension s
by using the standard service look up mechanism, in particular looking for
META-INF/services/com.sun.xml.ws.api.wsdl.parser.WSDLParserExtension
TODO
As it's designed today, extensions cannot access to any of the environmental
information before the parsing begins (such as what
WSService this
WSDL is being parsed for, etc.) We might need to reconsider this aspect.
The JAX-WS team waits for feedback on this topic.
author:
Kohsuke Kawaguchi | 