ohair@286: /*
alanb@368:  * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
ohair@286:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
ohair@286:  *
ohair@286:  * This code is free software; you can redistribute it and/or modify it
ohair@286:  * under the terms of the GNU General Public License version 2 only, as
ohair@286:  * published by the Free Software Foundation.  Oracle designates this
ohair@286:  * particular file as subject to the "Classpath" exception as provided
ohair@286:  * by Oracle in the LICENSE file that accompanied this code.
ohair@286:  *
ohair@286:  * This code is distributed in the hope that it will be useful, but WITHOUT
ohair@286:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
ohair@286:  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
ohair@286:  * version 2 for more details (a copy is included in the LICENSE file that
ohair@286:  * accompanied this code).
ohair@286:  *
ohair@286:  * You should have received a copy of the GNU General Public License version
ohair@286:  * 2 along with this work; if not, write to the Free Software Foundation,
ohair@286:  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
ohair@286:  *
ohair@286:  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
ohair@286:  * or visit www.oracle.com if you need additional information or have any
ohair@286:  * questions.
ohair@286:  */
ohair@286: 
ohair@286: package com.sun.xml.internal.ws.api.wsdl.parser;
ohair@286: 
ohair@286: import com.sun.xml.internal.ws.api.WSService;
ohair@286: import com.sun.xml.internal.ws.api.model.wsdl.*;
ohair@286: import com.sun.xml.internal.ws.api.pipe.Tube;
ohair@286: import com.sun.xml.internal.ws.wsdl.parser.RuntimeWSDLParser;
ohair@286: 
ohair@286: import javax.xml.stream.XMLStreamConstants;
ohair@286: import javax.xml.stream.XMLStreamReader;
ohair@286: import javax.xml.ws.WebServiceException;
ohair@286: 
ohair@286: /**
ohair@286:  * Extends the WSDL parsing process.
ohair@286:  *
ohair@286:  * <p>
ohair@286:  * This interface is implemented by components that build on top of the JAX-WS RI,
ohair@286:  * to participate in the WSDL parsing process that happens in the runtime.
ohair@286:  * This allows such components to retrieve information from WSDL extension elements,
ohair@286:  * and use that later to, for example, configure {@link Tube}s.
ohair@286:  *
ohair@286:  *
ohair@286:  *
ohair@286:  * <h2>How it works?</h2>
ohair@286:  * <p>
ohair@286:  * Each method on this interface denotes one extension point in WSDL
ohair@286:  * (the place where foreign elements/attributes can be added.) A {@link RuntimeWSDLParser}
ohair@286:  * starts parsing WSDL with a fixed set of {@link WSDLParserExtension}s, and
ohair@286:  * as it finds extension elements/attributes, it calls appropriate callback methods
ohair@286:  * to provide a chance for {@link WSDLParserExtension} to parse such
ohair@286:  * an extension element.
ohair@286:  *
ohair@286:  * <p>
ohair@286:  * There are two kinds of callbacks.
ohair@286:  *
ohair@286:  * <h3>Attribute callbacks</h3>
ohair@286:  * <p>
ohair@286:  * One is for attributes, which ends with the name {@code Attributes}.
ohair@286:  * This callback is invoked with {@link XMLStreamReader} that points
ohair@286:  * to the start tag of the WSDL element.
ohair@286:  *
ohair@286:  * <p>
ohair@286:  * The callback method can read interesting attributes on it.
ohair@286:  * The method must return without advancing the parser to the next token.
ohair@286:  *
ohair@286:  * <h3>Element callbacks</h3>
ohair@286:  * <p>
ohair@286:  * The other callback is for extension elements, which ends with the name
ohair@286:  * {@code Elements}.
ohair@286:  * When a callback is invoked, {@link XMLStreamReader} points to the
ohair@286:  * start tag of the extension element. The callback method can do
ohair@286:  * one of the following:
ohair@286:  *
ohair@286:  * <ol>
ohair@286:  *  <li>Return {@code false} without moving {@link XMLStreamReader},
ohair@286:  *      to indicate that the extension element isn't recognized.
ohair@286:  *      This allows the next {@link WSDLParserExtension} to see this
ohair@286:  *      extension element.
ohair@286:  *  <li>Parse the whole subtree rooted at the element,
ohair@286:  *      move the cursor to the {@link XMLStreamConstants#END_ELEMENT} state,
ohair@286:  *      and return {@code true}, indicating that the extension
ohair@286:  *      element is consumed.
ohair@286:  *      No other {@link WSDLParserExtension}s are notified of this extension.
ohair@286:  * </ol>
ohair@286:  *
ohair@286:  * <h3>Parsing in callback</h3>
ohair@286:  * <p>
ohair@286:  * For each callback, the corresponding WSDL model object is passed in,
ohair@286:  * so that {@link WSDLParserExtension} can relate what it's parsing
ohair@286:  * to the {@link WSDLModel}. Most likely, extensions can parse
ohair@286:  * their data into an {@link WSDLExtension}-derived classes, then
ohair@286:  * use {@link WSDLExtensible} interface to hook them into {@link WSDLModel}.
ohair@286:  *
ohair@286:  * <p>
ohair@286:  * Note that since the {@link WSDLModel} itself
ohair@286:  * is being built, {@link WSDLParserExtension} may not invoke any of
ohair@286:  * the query methods on the WSDL model. Those references are passed just so that
ohair@286:  * {@link WSDLParserExtension} can hold on to those references, or put
ohair@286:  * {@link WSDLExtensible} objects into the model, not to query it.
ohair@286:  *
ohair@286:  * <p>
ohair@286:  * If {@link WSDLParserExtension} needs to query {@link WSDLModel},
ohair@286:  * defer that processing until {@link #finished(WSDLParserExtensionContext)}, when it's
ohair@286:  * safe to use {@link WSDLModel} can be used safely.
ohair@286:  *
ohair@286:  * <p>
ohair@286:  * Also note that {@link WSDLParserExtension}s are called in no particular order.
ohair@286:  * This interface is not designed for having multiple {@link WSDLParserExtension}s
ohair@286:  * parse the same extension element.
ohair@286:  *
ohair@286:  *
ohair@286:  * <h2>Error Handling</h2>
ohair@286:  * <p>
ohair@286:  * For usability, {@link WSDLParserExtension}s are expected to check possible
ohair@286:  * errors in the extension elements that it parses. When an error is found,
ohair@286:  * it may throw a {@link WebServiceException} to abort the parsing of the WSDL.
ohair@286:  * This exception will be propagated to the user, so it should have
ohair@286:  * detailed error messages pointing at the problem.
ohair@286:  *
ohair@286:  * <h2>Discovery</h2>
ohair@286:  * <p>
ohair@286:  * The JAX-WS RI locates the implementation of {@link WSDLParserExtension}s
ohair@286:  * by using the standard service look up mechanism, in particular looking for
ohair@286:  * <tt>META-INF/services/com.sun.xml.internal.ws.api.wsdl.parser.WSDLParserExtension</tt>
ohair@286:  *
ohair@286:  *
ohair@286:  * <h2>TODO</h2>
ohair@286:  * <p>
ohair@286:  * As it's designed today, extensions cannot access to any of the environmental
ohair@286:  * information before the parsing begins (such as what {@link WSService} this
ohair@286:  * WSDL is being parsed for, etc.) We might need to reconsider this aspect.
ohair@286:  * The JAX-WS team waits for feedback on this topic.
ohair@286:  *
ohair@286:  * @author Kohsuke Kawaguchi
ohair@286:  */
ohair@286: public abstract class WSDLParserExtension {
ohair@286:     public void start(WSDLParserExtensionContext context){
ohair@286:         // noop
ohair@286:     }
ohair@286:     public void serviceAttributes(WSDLService service, XMLStreamReader reader) {
ohair@286:         // noop
ohair@286:     }
ohair@286: 
ohair@286:     public boolean serviceElements(WSDLService service, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public void portAttributes(WSDLPort port, XMLStreamReader reader) {
ohair@286:         // noop
ohair@286:     }
ohair@286: 
ohair@286:     public boolean portElements(WSDLPort port, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public boolean portTypeOperationInput(WSDLOperation op, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public boolean portTypeOperationOutput(WSDLOperation op, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public boolean portTypeOperationFault(WSDLOperation op, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public boolean definitionsElements(XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public boolean bindingElements(WSDLBoundPortType binding, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public void bindingAttributes(WSDLBoundPortType binding, XMLStreamReader reader) {
ohair@286:     }
ohair@286: 
ohair@286:     public boolean portTypeElements(WSDLPortType portType, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public void portTypeAttributes(WSDLPortType portType, XMLStreamReader reader) {
ohair@286:     }
ohair@286: 
ohair@286:     public boolean portTypeOperationElements(WSDLOperation operation, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public void portTypeOperationAttributes(WSDLOperation operation, XMLStreamReader reader) {
ohair@286:     }
ohair@286: 
ohair@286:     public boolean bindingOperationElements(WSDLBoundOperation operation, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public void bindingOperationAttributes(WSDLBoundOperation operation, XMLStreamReader reader) {
ohair@286:     }
ohair@286: 
ohair@286:     public boolean messageElements(WSDLMessage msg, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public void messageAttributes(WSDLMessage msg, XMLStreamReader reader) {
ohair@286:     }
ohair@286: 
ohair@286:     public boolean portTypeOperationInputElements(WSDLInput input, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public void portTypeOperationInputAttributes(WSDLInput input, XMLStreamReader reader) {
ohair@286:     }
ohair@286: 
ohair@286:     public boolean portTypeOperationOutputElements(WSDLOutput output, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public void portTypeOperationOutputAttributes(WSDLOutput output, XMLStreamReader reader) {
ohair@286:     }
ohair@286: 
ohair@286:     public boolean portTypeOperationFaultElements(WSDLFault fault, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public void portTypeOperationFaultAttributes(WSDLFault fault, XMLStreamReader reader) {
ohair@286:     }
ohair@286: 
ohair@286:     public boolean bindingOperationInputElements(WSDLBoundOperation operation, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public void bindingOperationInputAttributes(WSDLBoundOperation operation, XMLStreamReader reader) {
ohair@286:     }
ohair@286: 
ohair@286:     public boolean bindingOperationOutputElements(WSDLBoundOperation operation, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public void bindingOperationOutputAttributes(WSDLBoundOperation operation, XMLStreamReader reader) {
ohair@286:     }
ohair@286: 
ohair@286:     public boolean bindingOperationFaultElements(WSDLBoundFault fault, XMLStreamReader reader) {
ohair@286:         return false;
ohair@286:     }
ohair@286: 
ohair@286:     public void bindingOperationFaultAttributes(WSDLBoundFault fault, XMLStreamReader reader) {
ohair@286:     }
ohair@286: 
ohair@286:     // TODO: complete the rest of the callback
ohair@286: 
ohair@286:     /**
ohair@286:      * Called when the parsing of a set of WSDL documents are all done.
ohair@286:      * <p>
ohair@286:      * This is the opportunity to do any post-processing of the parsing
ohair@286:      * you've done.
ohair@286:      *
ohair@286:      * @param context  {@link WSDLParserExtensionContext} gives fully parsed {@link WSDLModel}.
ohair@286:      */
ohair@286:     public void finished(WSDLParserExtensionContext context) {
ohair@286:         // noop
ohair@286:     }
ohair@286: 
ohair@286:     public void postFinished(WSDLParserExtensionContext context) {
ohair@286:         // noop
ohair@286:     }
ohair@286: }