001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036:
037: package com.sun.xml.ws.api.wsdl.parser;
038:
039: import com.sun.xml.ws.api.WSService;
040: import com.sun.xml.ws.api.model.wsdl.*;
041: import com.sun.xml.ws.api.pipe.Tube;
042: import com.sun.xml.ws.wsdl.parser.RuntimeWSDLParser;
043:
044: import javax.xml.stream.XMLStreamConstants;
045: import javax.xml.stream.XMLStreamReader;
046: import javax.xml.ws.WebServiceException;
047:
048: /**
049: * Extends the WSDL parsing process.
050: *
051: * <p>
052: * This interface is implemented by components that build on top of the JAX-WS RI,
053: * to participate in the WSDL parsing process that happens in the runtime.
054: * This allows such components to retrieve information from WSDL extension elements,
055: * and use that later to, for example, configure {@link Tube}s.
056: *
057: *
058: *
059: * <h2>How it works?</h2>
060: * <p>
061: * Each method on this interface denotes one extension point in WSDL
062: * (the place where foreign elements/attributes can be added.) A {@link RuntimeWSDLParser}
063: * starts parsing WSDL with a fixed set of {@link WSDLParserExtension}s, and
064: * as it finds extension elements/attributes, it calls appropriate callback methods
065: * to provide a chance for {@link WSDLParserExtension} to parse such
066: * an extension element.
067: *
068: * <p>
069: * There are two kinds of callbacks.
070: *
071: * <h3>Attribute callbacks</h3>
072: * <p>
073: * One is for attributes, which ends with the name {@code Attributes}.
074: * This callback is invoked with {@link XMLStreamReader} that points
075: * to the start tag of the WSDL element.
076: *
077: * <p>
078: * The callback method can read interesting attributes on it.
079: * The method must return without advancing the parser to the next token.
080: *
081: * <h3>Element callbacks</h3>
082: * <p>
083: * The other callback is for extension elements, which ends with the name
084: * {@code Elements}.
085: * When a callback is invoked, {@link XMLStreamReader} points to the
086: * start tag of the extension element. The callback method can do
087: * one of the following:
088: *
089: * <ol>
090: * <li>Return {@code false} without moving {@link XMLStreamReader},
091: * to indicate that the extension element isn't recognized.
092: * This allows the next {@link WSDLParserExtension} to see this
093: * extension element.
094: * <li>Parse the whole subtree rooted at the element,
095: * move the cursor to the {@link XMLStreamConstants#END_ELEMENT} state,
096: * and return {@code true}, indicating that the extension
097: * element is consumed.
098: * No other {@link WSDLParserExtension}s are notified of this extension.
099: * </ol>
100: *
101: * <h3>Parsing in callback</h3>
102: * <p>
103: * For each callback, the corresponding WSDL model object is passed in,
104: * so that {@link WSDLParserExtension} can relate what it's parsing
105: * to the {@link WSDLModel}. Most likely, extensions can parse
106: * their data into an {@link WSDLExtension}-derived classes, then
107: * use {@link WSDLExtensible} interface to hook them into {@link WSDLModel}.
108: *
109: * <p>
110: * Note that since the {@link WSDLModel} itself
111: * is being built, {@link WSDLParserExtension} may not invoke any of
112: * the query methods on the WSDL model. Those references are passed just so that
113: * {@link WSDLParserExtension} can hold on to those references, or put
114: * {@link WSDLExtensible} objects into the model, not to query it.
115: *
116: * <p>
117: * If {@link WSDLParserExtension} needs to query {@link WSDLModel},
118: * defer that processing until {@link #finished(WSDLParserExtensionContext)}, when it's
119: * safe to use {@link WSDLModel} can be used safely.
120: *
121: * <p>
122: * Also note that {@link WSDLParserExtension}s are called in no particular order.
123: * This interface is not designed for having multiple {@link WSDLParserExtension}s
124: * parse the same extension element.
125: *
126: *
127: * <h2>Error Handling</h2>
128: * <p>
129: * For usability, {@link WSDLParserExtension}s are expected to check possible
130: * errors in the extension elements that it parses. When an error is found,
131: * it may throw a {@link WebServiceException} to abort the parsing of the WSDL.
132: * This exception will be propagated to the user, so it should have
133: * detailed error messages pointing at the problem.
134: *
135: * <h2>Discovery</h2>
136: * <p>
137: * The JAX-WS RI locates the implementation of {@link WSDLParserExtension}s
138: * by using the standard service look up mechanism, in particular looking for
139: * <tt>META-INF/services/com.sun.xml.ws.api.wsdl.parser.WSDLParserExtension</tt>
140: *
141: *
142: * <h2>TODO</h2>
143: * <p>
144: * As it's designed today, extensions cannot access to any of the environmental
145: * information before the parsing begins (such as what {@link WSService} this
146: * WSDL is being parsed for, etc.) We might need to reconsider this aspect.
147: * The JAX-WS team waits for feedback on this topic.
148: *
149: * @author Kohsuke Kawaguchi
150: */
151: public abstract class WSDLParserExtension {
152: public void start(WSDLParserExtensionContext context) {
153: // noop
154: }
155:
156: public void serviceAttributes(WSDLService service,
157: XMLStreamReader reader) {
158: // noop
159: }
160:
161: public boolean serviceElements(WSDLService service,
162: XMLStreamReader reader) {
163: return false;
164: }
165:
166: public void portAttributes(WSDLPort port, XMLStreamReader reader) {
167: // noop
168: }
169:
170: public boolean portElements(WSDLPort port, XMLStreamReader reader) {
171: return false;
172: }
173:
174: public boolean portTypeOperationInput(WSDLOperation op,
175: XMLStreamReader reader) {
176: return false;
177: }
178:
179: public boolean portTypeOperationOutput(WSDLOperation op,
180: XMLStreamReader reader) {
181: return false;
182: }
183:
184: public boolean portTypeOperationFault(WSDLOperation op,
185: XMLStreamReader reader) {
186: return false;
187: }
188:
189: public boolean definitionsElements(XMLStreamReader reader) {
190: return false;
191: }
192:
193: public boolean bindingElements(WSDLBoundPortType binding,
194: XMLStreamReader reader) {
195: return false;
196: }
197:
198: public void bindingAttributes(WSDLBoundPortType binding,
199: XMLStreamReader reader) {
200: }
201:
202: public boolean portTypeElements(WSDLPortType portType,
203: XMLStreamReader reader) {
204: return false;
205: }
206:
207: public void portTypeAttributes(WSDLPortType portType,
208: XMLStreamReader reader) {
209: }
210:
211: public boolean portTypeOperationElements(WSDLOperation operation,
212: XMLStreamReader reader) {
213: return false;
214: }
215:
216: public void portTypeOperationAttributes(WSDLOperation operation,
217: XMLStreamReader reader) {
218: }
219:
220: public boolean bindingOperationElements(
221: WSDLBoundOperation operation, XMLStreamReader reader) {
222: return false;
223: }
224:
225: public void bindingOperationAttributes(
226: WSDLBoundOperation operation, XMLStreamReader reader) {
227: }
228:
229: public boolean messageElements(WSDLMessage msg,
230: XMLStreamReader reader) {
231: return false;
232: }
233:
234: public void messageAttributes(WSDLMessage msg,
235: XMLStreamReader reader) {
236: }
237:
238: public boolean portTypeOperationInputElements(WSDLInput input,
239: XMLStreamReader reader) {
240: return false;
241: }
242:
243: public void portTypeOperationInputAttributes(WSDLInput input,
244: XMLStreamReader reader) {
245: }
246:
247: public boolean portTypeOperationOutputElements(WSDLOutput output,
248: XMLStreamReader reader) {
249: return false;
250: }
251:
252: public void portTypeOperationOutputAttributes(WSDLOutput output,
253: XMLStreamReader reader) {
254: }
255:
256: public boolean portTypeOperationFaultElements(WSDLFault fault,
257: XMLStreamReader reader) {
258: return false;
259: }
260:
261: public void portTypeOperationFaultAttributes(WSDLFault fault,
262: XMLStreamReader reader) {
263: }
264:
265: public boolean bindingOperationInputElements(
266: WSDLBoundOperation operation, XMLStreamReader reader) {
267: return false;
268: }
269:
270: public void bindingOperationInputAttributes(
271: WSDLBoundOperation operation, XMLStreamReader reader) {
272: }
273:
274: public boolean bindingOperationOutputElements(
275: WSDLBoundOperation operation, XMLStreamReader reader) {
276: return false;
277: }
278:
279: public void bindingOperationOutputAttributes(
280: WSDLBoundOperation operation, XMLStreamReader reader) {
281: }
282:
283: public boolean bindingOperationFaultElements(WSDLBoundFault fault,
284: XMLStreamReader reader) {
285: return false;
286: }
287:
288: public void bindingOperationFaultAttributes(WSDLBoundFault fault,
289: XMLStreamReader reader) {
290: }
291:
292: // TODO: complete the rest of the callback
293:
294: /**
295: * Called when the parsing of a set of WSDL documents are all done.
296: * <p>
297: * This is the opportunity to do any post-processing of the parsing
298: * you've done.
299: *
300: * @param context {@link WSDLParserExtensionContext} gives fully parsed {@link WSDLModel}.
301: */
302: public void finished(WSDLParserExtensionContext context) {
303: // noop
304: }
305:
306: public void postFinished(WSDLParserExtensionContext context) {
307: // noop
308: }
309: }
|