+ * 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 {@link Tube}s. + * + * + * + *
+ * Each method on this interface denotes one extension point in WSDL + * (the place where foreign elements/attributes can be added.) A {@link RuntimeWSDLParser} + * starts parsing WSDL with a fixed set of {@link WSDLParserExtension}s, and + * as it finds extension elements/attributes, it calls appropriate callback methods + * to provide a chance for {@link WSDLParserExtension} to parse such + * an extension element. + * + *
+ * There are two kinds of callbacks. + * + *
+ * One is for attributes, which ends with the name {@code Attributes}. + * This callback is invoked with {@link 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. + * + *
+ * The other callback is for extension elements, which ends with the name + * {@code Elements}. + * When a callback is invoked, {@link XMLStreamReader} points to the + * start tag of the extension element. The callback method can do + * one of the following: + * + *
+ * For each callback, the corresponding WSDL model object is passed in, + * so that {@link WSDLParserExtension} can relate what it's parsing + * to the {@link WSDLModel}. Most likely, extensions can parse + * their data into an {@link WSDLExtension}-derived classes, then + * use {@link WSDLExtensible} interface to hook them into {@link WSDLModel}. + * + *
+ * Note that since the {@link WSDLModel} itself + * is being built, {@link WSDLParserExtension} may not invoke any of + * the query methods on the WSDL model. Those references are passed just so that + * {@link WSDLParserExtension} can hold on to those references, or put + * {@link WSDLExtensible} objects into the model, not to query it. + * + *
+ * If {@link WSDLParserExtension} needs to query {@link WSDLModel}, + * defer that processing until {@link #finished(WSDLParserExtensionContext)}, when it's + * safe to use {@link WSDLModel} can be used safely. + * + *
+ * Also note that {@link WSDLParserExtension}s are called in no particular order. + * This interface is not designed for having multiple {@link WSDLParserExtension}s + * parse the same extension element. + * + * + *
+ * For usability, {@link WSDLParserExtension}s are expected to check possible + * errors in the extension elements that it parses. When an error is found, + * it may throw a {@link 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. + * + *
+ * The JAX-WS RI locates the implementation of {@link WSDLParserExtension}s + * by using the standard service look up mechanism, in particular looking for + * META-INF/services/com.sun.xml.internal.ws.api.wsdl.parser.WSDLParserExtension + * + * + *
+ * As it's designed today, extensions cannot access to any of the environmental + * information before the parsing begins (such as what {@link 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 + */ +public abstract class WSDLParserExtension { + public void start(WSDLParserExtensionContext context){ + // noop + } + public void serviceAttributes(WSDLService service, XMLStreamReader reader) { + // noop + } + + public boolean serviceElements(WSDLService service, XMLStreamReader reader) { + return false; + } + + public void portAttributes(WSDLPort port, XMLStreamReader reader) { + // noop + } + + public boolean portElements(WSDLPort port, XMLStreamReader reader) { + return false; + } + + public boolean portTypeOperationInput(WSDLOperation op, XMLStreamReader reader) { + return false; + } + + public boolean portTypeOperationOutput(WSDLOperation op, XMLStreamReader reader) { + return false; + } + + public boolean portTypeOperationFault(WSDLOperation op, XMLStreamReader reader) { + return false; + } + + public boolean definitionsElements(XMLStreamReader reader) { + return false; + } + + public boolean bindingElements(WSDLBoundPortType binding, XMLStreamReader reader) { + return false; + } + + public void bindingAttributes(WSDLBoundPortType binding, XMLStreamReader reader) { + } + + public boolean portTypeElements(WSDLPortType portType, XMLStreamReader reader) { + return false; + } + + public void portTypeAttributes(WSDLPortType portType, XMLStreamReader reader) { + } + + public boolean portTypeOperationElements(WSDLOperation operation, XMLStreamReader reader) { + return false; + } + + public void portTypeOperationAttributes(WSDLOperation operation, XMLStreamReader reader) { + } + + public boolean bindingOperationElements(WSDLBoundOperation operation, XMLStreamReader reader) { + return false; + } + + public void bindingOperationAttributes(WSDLBoundOperation operation, XMLStreamReader reader) { + } + + public boolean messageElements(WSDLMessage msg, XMLStreamReader reader) { + return false; + } + + public void messageAttributes(WSDLMessage msg, XMLStreamReader reader) { + } + + public boolean portTypeOperationInputElements(WSDLInput input, XMLStreamReader reader) { + return false; + } + + public void portTypeOperationInputAttributes(WSDLInput input, XMLStreamReader reader) { + } + + public boolean portTypeOperationOutputElements(WSDLOutput output, XMLStreamReader reader) { + return false; + } + + public void portTypeOperationOutputAttributes(WSDLOutput output, XMLStreamReader reader) { + } + + public boolean portTypeOperationFaultElements(WSDLFault fault, XMLStreamReader reader) { + return false; + } + + public void portTypeOperationFaultAttributes(WSDLFault fault, XMLStreamReader reader) { + } + + public boolean bindingOperationInputElements(WSDLBoundOperation operation, XMLStreamReader reader) { + return false; + } + + public void bindingOperationInputAttributes(WSDLBoundOperation operation, XMLStreamReader reader) { + } + + public boolean bindingOperationOutputElements(WSDLBoundOperation operation, XMLStreamReader reader) { + return false; + } + + public void bindingOperationOutputAttributes(WSDLBoundOperation operation, XMLStreamReader reader) { + } + + public boolean bindingOperationFaultElements(WSDLBoundFault fault, XMLStreamReader reader) { + return false; + } + + public void bindingOperationFaultAttributes(WSDLBoundFault fault, XMLStreamReader reader) { + } + + // TODO: complete the rest of the callback + + /** + * 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. + * + * @param context {@link WSDLParserExtensionContext} gives fully parsed {@link WSDLModel}. + */ + public void finished(WSDLParserExtensionContext context) { + // noop + } + + public void postFinished(WSDLParserExtensionContext context) { + // noop + } +}