com.sun.xml.ws.api.wsdl.parser
Class WSDLParserExtension

java.lang.Object
  extended by com.sun.xml.ws.api.wsdl.parser.WSDLParserExtension
Direct Known Subclasses:
DelegatingParserExtension, W3CAddressingWSDLParserExtension, WSDLParserExtensionFacade

public abstract class WSDLParserExtension
extends Object

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 Tubes.

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 WSDLParserExtensions, 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:

  1. Return false without moving XMLStreamReader, to indicate that the extension element isn't recognized. This allows the next WSDLParserExtension to see this extension element.
  2. 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 WSDLParserExtensions 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 finished(WSDLParserExtensionContext), when it's safe to use WSDLModel can be used safely.

Also note that WSDLParserExtensions are called in no particular order. This interface is not designed for having multiple WSDLParserExtensions parse the same extension element.

Error Handling

For usability, WSDLParserExtensions 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 WSDLParserExtensions 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.


Constructor Summary
WSDLParserExtension()
           
 
Method Summary
 void bindingAttributes(WSDLBoundPortType binding, javax.xml.stream.XMLStreamReader reader)
           
 boolean bindingElements(WSDLBoundPortType binding, javax.xml.stream.XMLStreamReader reader)
           
 void bindingOperationAttributes(WSDLBoundOperation operation, javax.xml.stream.XMLStreamReader reader)
           
 boolean bindingOperationElements(WSDLBoundOperation operation, javax.xml.stream.XMLStreamReader reader)
           
 void bindingOperationFaultAttributes(WSDLBoundFault fault, javax.xml.stream.XMLStreamReader reader)
           
 boolean bindingOperationFaultElements(WSDLBoundFault fault, javax.xml.stream.XMLStreamReader reader)
           
 void bindingOperationInputAttributes(WSDLBoundOperation operation, javax.xml.stream.XMLStreamReader reader)
           
 boolean bindingOperationInputElements(WSDLBoundOperation operation, javax.xml.stream.XMLStreamReader reader)
           
 void bindingOperationOutputAttributes(WSDLBoundOperation operation, javax.xml.stream.XMLStreamReader reader)
           
 boolean bindingOperationOutputElements(WSDLBoundOperation operation, javax.xml.stream.XMLStreamReader reader)
           
 boolean definitionsElements(javax.xml.stream.XMLStreamReader reader)
           
 void finished(WSDLParserExtensionContext context)
          Called when the parsing of a set of WSDL documents are all done.
 void messageAttributes(WSDLMessage msg, javax.xml.stream.XMLStreamReader reader)
           
 boolean messageElements(WSDLMessage msg, javax.xml.stream.XMLStreamReader reader)
           
 void portAttributes(WSDLPort port, javax.xml.stream.XMLStreamReader reader)
           
 boolean portElements(WSDLPort port, javax.xml.stream.XMLStreamReader reader)
           
 void portTypeAttributes(WSDLPortType portType, javax.xml.stream.XMLStreamReader reader)
           
 boolean portTypeElements(WSDLPortType portType, javax.xml.stream.XMLStreamReader reader)
           
 void portTypeOperationAttributes(WSDLOperation operation, javax.xml.stream.XMLStreamReader reader)
           
 boolean portTypeOperationElements(WSDLOperation operation, javax.xml.stream.XMLStreamReader reader)
           
 boolean portTypeOperationFault(WSDLOperation op, javax.xml.stream.XMLStreamReader reader)
           
 void portTypeOperationFaultAttributes(WSDLFault fault, javax.xml.stream.XMLStreamReader reader)
           
 boolean portTypeOperationFaultElements(WSDLFault fault, javax.xml.stream.XMLStreamReader reader)
           
 boolean portTypeOperationInput(WSDLOperation op, javax.xml.stream.XMLStreamReader reader)
           
 void portTypeOperationInputAttributes(WSDLInput input, javax.xml.stream.XMLStreamReader reader)
           
 boolean portTypeOperationInputElements(WSDLInput input, javax.xml.stream.XMLStreamReader reader)
           
 boolean portTypeOperationOutput(WSDLOperation op, javax.xml.stream.XMLStreamReader reader)
           
 void portTypeOperationOutputAttributes(WSDLOutput output, javax.xml.stream.XMLStreamReader reader)
           
 boolean portTypeOperationOutputElements(WSDLOutput output, javax.xml.stream.XMLStreamReader reader)
           
 void postFinished(WSDLParserExtensionContext context)
           
 void serviceAttributes(WSDLService service, javax.xml.stream.XMLStreamReader reader)
           
 boolean serviceElements(WSDLService service, javax.xml.stream.XMLStreamReader reader)
           
 void start(WSDLParserExtensionContext context)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WSDLParserExtension

public WSDLParserExtension()
Method Detail

start

public void start(WSDLParserExtensionContext context)

serviceAttributes

public void serviceAttributes(WSDLService service,
                              javax.xml.stream.XMLStreamReader reader)

serviceElements

public boolean serviceElements(WSDLService service,
                               javax.xml.stream.XMLStreamReader reader)

portAttributes

public void portAttributes(WSDLPort port,
                           javax.xml.stream.XMLStreamReader reader)

portElements

public boolean portElements(WSDLPort port,
                            javax.xml.stream.XMLStreamReader reader)

portTypeOperationInput

public boolean portTypeOperationInput(WSDLOperation op,
                                      javax.xml.stream.XMLStreamReader reader)

portTypeOperationOutput

public boolean portTypeOperationOutput(WSDLOperation op,
                                       javax.xml.stream.XMLStreamReader reader)

portTypeOperationFault

public boolean portTypeOperationFault(WSDLOperation op,
                                      javax.xml.stream.XMLStreamReader reader)

definitionsElements

public boolean definitionsElements(javax.xml.stream.XMLStreamReader reader)

bindingElements

public boolean bindingElements(WSDLBoundPortType binding,
                               javax.xml.stream.XMLStreamReader reader)

bindingAttributes

public void bindingAttributes(WSDLBoundPortType binding,
                              javax.xml.stream.XMLStreamReader reader)

portTypeElements

public boolean portTypeElements(WSDLPortType portType,
                                javax.xml.stream.XMLStreamReader reader)

portTypeAttributes

public void portTypeAttributes(WSDLPortType portType,
                               javax.xml.stream.XMLStreamReader reader)

portTypeOperationElements

public boolean portTypeOperationElements(WSDLOperation operation,
                                         javax.xml.stream.XMLStreamReader reader)

portTypeOperationAttributes

public void portTypeOperationAttributes(WSDLOperation operation,
                                        javax.xml.stream.XMLStreamReader reader)

bindingOperationElements

public boolean bindingOperationElements(WSDLBoundOperation operation,
                                        javax.xml.stream.XMLStreamReader reader)

bindingOperationAttributes

public void bindingOperationAttributes(WSDLBoundOperation operation,
                                       javax.xml.stream.XMLStreamReader reader)

messageElements

public boolean messageElements(WSDLMessage msg,
                               javax.xml.stream.XMLStreamReader reader)

messageAttributes

public void messageAttributes(WSDLMessage msg,
                              javax.xml.stream.XMLStreamReader reader)

portTypeOperationInputElements

public boolean portTypeOperationInputElements(WSDLInput input,
                                              javax.xml.stream.XMLStreamReader reader)

portTypeOperationInputAttributes

public void portTypeOperationInputAttributes(WSDLInput input,
                                             javax.xml.stream.XMLStreamReader reader)

portTypeOperationOutputElements

public boolean portTypeOperationOutputElements(WSDLOutput output,
                                               javax.xml.stream.XMLStreamReader reader)

portTypeOperationOutputAttributes

public void portTypeOperationOutputAttributes(WSDLOutput output,
                                              javax.xml.stream.XMLStreamReader reader)

portTypeOperationFaultElements

public boolean portTypeOperationFaultElements(WSDLFault fault,
                                              javax.xml.stream.XMLStreamReader reader)

portTypeOperationFaultAttributes

public void portTypeOperationFaultAttributes(WSDLFault fault,
                                             javax.xml.stream.XMLStreamReader reader)

bindingOperationInputElements

public boolean bindingOperationInputElements(WSDLBoundOperation operation,
                                             javax.xml.stream.XMLStreamReader reader)

bindingOperationInputAttributes

public void bindingOperationInputAttributes(WSDLBoundOperation operation,
                                            javax.xml.stream.XMLStreamReader reader)

bindingOperationOutputElements

public boolean bindingOperationOutputElements(WSDLBoundOperation operation,
                                              javax.xml.stream.XMLStreamReader reader)

bindingOperationOutputAttributes

public void bindingOperationOutputAttributes(WSDLBoundOperation operation,
                                             javax.xml.stream.XMLStreamReader reader)

bindingOperationFaultElements

public boolean bindingOperationFaultElements(WSDLBoundFault fault,
                                             javax.xml.stream.XMLStreamReader reader)

bindingOperationFaultAttributes

public void bindingOperationFaultAttributes(WSDLBoundFault fault,
                                            javax.xml.stream.XMLStreamReader reader)

finished

public void finished(WSDLParserExtensionContext context)
Called when the parsing of a set of WSDL documents are all done.

This is the opportunity to do any post-processing of the parsing you've done.

Parameters:
context - WSDLParserExtensionContext gives fully parsed WSDLModel.

postFinished

public void postFinished(WSDLParserExtensionContext context)