com.sun.xml.ws.api.wsdl.parser.WSDLParserExtension Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package com.sun.xml.ws.api.wsdl.parser;
import com.sun.xml.ws.api.WSService;
import com.sun.xml.ws.api.model.wsdl.editable.EditableWSDLBoundFault;
import com.sun.xml.ws.api.model.wsdl.editable.EditableWSDLBoundOperation;
import com.sun.xml.ws.api.model.wsdl.editable.EditableWSDLBoundPortType;
import com.sun.xml.ws.api.model.wsdl.editable.EditableWSDLFault;
import com.sun.xml.ws.api.model.wsdl.editable.EditableWSDLInput;
import com.sun.xml.ws.api.model.wsdl.editable.EditableWSDLMessage;
import com.sun.xml.ws.api.model.wsdl.editable.EditableWSDLOperation;
import com.sun.xml.ws.api.model.wsdl.editable.EditableWSDLOutput;
import com.sun.xml.ws.api.model.wsdl.editable.EditableWSDLPort;
import com.sun.xml.ws.api.model.wsdl.editable.EditableWSDLPortType;
import com.sun.xml.ws.api.model.wsdl.editable.EditableWSDLService;
import com.sun.xml.ws.api.pipe.Tube;
import com.sun.xml.ws.wsdl.parser.RuntimeWSDLParser;
import javax.xml.stream.XMLStreamConstants;
import javax.xml.stream.XMLStreamReader;
import javax.xml.ws.WebServiceException;
/**
* 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 {@link 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 {@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.
*
*
Attribute 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.
*
*
Element callbacks
*
* 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:
*
*
* - Return {@code false} without moving {@link XMLStreamReader},
* to indicate that the extension element isn't recognized.
* This allows the next {@link WSDLParserExtension} to see this
* extension element.
*
- Parse the whole subtree rooted at the element,
* move the cursor to the {@link XMLStreamConstants#END_ELEMENT} state,
* and return {@code true}, indicating that the extension
* element is consumed.
* No other {@link WSDLParserExtension}s are notified of this extension.
*
*
* Parsing in callback
*
* 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.
*
*
*
Error Handling
*
* 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.
*
*
Discovery
*
* The JAX-WS RI locates the implementation of {@link WSDLParserExtension}s
* by using the standard service look up mechanism, in particular looking for
* {@code 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 {@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(EditableWSDLService service, XMLStreamReader reader) {
// noop
}
public boolean serviceElements(EditableWSDLService service, XMLStreamReader reader) {
return false;
}
public void portAttributes(EditableWSDLPort port, XMLStreamReader reader) {
// noop
}
public boolean portElements(EditableWSDLPort port, XMLStreamReader reader) {
return false;
}
public boolean portTypeOperationInput(EditableWSDLOperation op, XMLStreamReader reader) {
return false;
}
public boolean portTypeOperationOutput(EditableWSDLOperation op, XMLStreamReader reader) {
return false;
}
public boolean portTypeOperationFault(EditableWSDLOperation op, XMLStreamReader reader) {
return false;
}
public boolean definitionsElements(XMLStreamReader reader) {
return false;
}
public boolean bindingElements(EditableWSDLBoundPortType binding, XMLStreamReader reader) {
return false;
}
public void bindingAttributes(EditableWSDLBoundPortType binding, XMLStreamReader reader) {
}
public boolean portTypeElements(EditableWSDLPortType portType, XMLStreamReader reader) {
return false;
}
public void portTypeAttributes(EditableWSDLPortType portType, XMLStreamReader reader) {
}
public boolean portTypeOperationElements(EditableWSDLOperation operation, XMLStreamReader reader) {
return false;
}
public void portTypeOperationAttributes(EditableWSDLOperation operation, XMLStreamReader reader) {
}
public boolean bindingOperationElements(EditableWSDLBoundOperation operation, XMLStreamReader reader) {
return false;
}
public void bindingOperationAttributes(EditableWSDLBoundOperation operation, XMLStreamReader reader) {
}
public boolean messageElements(EditableWSDLMessage msg, XMLStreamReader reader) {
return false;
}
public void messageAttributes(EditableWSDLMessage msg, XMLStreamReader reader) {
}
public boolean portTypeOperationInputElements(EditableWSDLInput input, XMLStreamReader reader) {
return false;
}
public void portTypeOperationInputAttributes(EditableWSDLInput input, XMLStreamReader reader) {
}
public boolean portTypeOperationOutputElements(EditableWSDLOutput output, XMLStreamReader reader) {
return false;
}
public void portTypeOperationOutputAttributes(EditableWSDLOutput output, XMLStreamReader reader) {
}
public boolean portTypeOperationFaultElements(EditableWSDLFault fault, XMLStreamReader reader) {
return false;
}
public void portTypeOperationFaultAttributes(EditableWSDLFault fault, XMLStreamReader reader) {
}
public boolean bindingOperationInputElements(EditableWSDLBoundOperation operation, XMLStreamReader reader) {
return false;
}
public void bindingOperationInputAttributes(EditableWSDLBoundOperation operation, XMLStreamReader reader) {
}
public boolean bindingOperationOutputElements(EditableWSDLBoundOperation operation, XMLStreamReader reader) {
return false;
}
public void bindingOperationOutputAttributes(EditableWSDLBoundOperation operation, XMLStreamReader reader) {
}
public boolean bindingOperationFaultElements(EditableWSDLBoundFault fault, XMLStreamReader reader) {
return false;
}
public void bindingOperationFaultAttributes(EditableWSDLBoundFault 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
}
}