Wed, 12 Jun 2013 14:47:09 +0100
8013021: Rebase 8005432 & 8003542 against the latest jdk8/jaxws
8003542: Improve processing of MTOM attachments
8005432: Update access to JAX-WS
Reviewed-by: mullan
1 /*
2 * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
26 package com.sun.xml.internal.ws.api.wsdl.parser;
28 import com.sun.xml.internal.ws.api.WSService;
29 import com.sun.xml.internal.ws.api.model.wsdl.*;
30 import com.sun.xml.internal.ws.api.pipe.Tube;
31 import com.sun.xml.internal.ws.wsdl.parser.RuntimeWSDLParser;
33 import javax.xml.stream.XMLStreamConstants;
34 import javax.xml.stream.XMLStreamReader;
35 import javax.xml.ws.WebServiceException;
37 /**
38 * Extends the WSDL parsing process.
39 *
40 * <p>
41 * This interface is implemented by components that build on top of the JAX-WS RI,
42 * to participate in the WSDL parsing process that happens in the runtime.
43 * This allows such components to retrieve information from WSDL extension elements,
44 * and use that later to, for example, configure {@link Tube}s.
45 *
46 *
47 *
48 * <h2>How it works?</h2>
49 * <p>
50 * Each method on this interface denotes one extension point in WSDL
51 * (the place where foreign elements/attributes can be added.) A {@link RuntimeWSDLParser}
52 * starts parsing WSDL with a fixed set of {@link WSDLParserExtension}s, and
53 * as it finds extension elements/attributes, it calls appropriate callback methods
54 * to provide a chance for {@link WSDLParserExtension} to parse such
55 * an extension element.
56 *
57 * <p>
58 * There are two kinds of callbacks.
59 *
60 * <h3>Attribute callbacks</h3>
61 * <p>
62 * One is for attributes, which ends with the name {@code Attributes}.
63 * This callback is invoked with {@link XMLStreamReader} that points
64 * to the start tag of the WSDL element.
65 *
66 * <p>
67 * The callback method can read interesting attributes on it.
68 * The method must return without advancing the parser to the next token.
69 *
70 * <h3>Element callbacks</h3>
71 * <p>
72 * The other callback is for extension elements, which ends with the name
73 * {@code Elements}.
74 * When a callback is invoked, {@link XMLStreamReader} points to the
75 * start tag of the extension element. The callback method can do
76 * one of the following:
77 *
78 * <ol>
79 * <li>Return {@code false} without moving {@link XMLStreamReader},
80 * to indicate that the extension element isn't recognized.
81 * This allows the next {@link WSDLParserExtension} to see this
82 * extension element.
83 * <li>Parse the whole subtree rooted at the element,
84 * move the cursor to the {@link XMLStreamConstants#END_ELEMENT} state,
85 * and return {@code true}, indicating that the extension
86 * element is consumed.
87 * No other {@link WSDLParserExtension}s are notified of this extension.
88 * </ol>
89 *
90 * <h3>Parsing in callback</h3>
91 * <p>
92 * For each callback, the corresponding WSDL model object is passed in,
93 * so that {@link WSDLParserExtension} can relate what it's parsing
94 * to the {@link WSDLModel}. Most likely, extensions can parse
95 * their data into an {@link WSDLExtension}-derived classes, then
96 * use {@link WSDLExtensible} interface to hook them into {@link WSDLModel}.
97 *
98 * <p>
99 * Note that since the {@link WSDLModel} itself
100 * is being built, {@link WSDLParserExtension} may not invoke any of
101 * the query methods on the WSDL model. Those references are passed just so that
102 * {@link WSDLParserExtension} can hold on to those references, or put
103 * {@link WSDLExtensible} objects into the model, not to query it.
104 *
105 * <p>
106 * If {@link WSDLParserExtension} needs to query {@link WSDLModel},
107 * defer that processing until {@link #finished(WSDLParserExtensionContext)}, when it's
108 * safe to use {@link WSDLModel} can be used safely.
109 *
110 * <p>
111 * Also note that {@link WSDLParserExtension}s are called in no particular order.
112 * This interface is not designed for having multiple {@link WSDLParserExtension}s
113 * parse the same extension element.
114 *
115 *
116 * <h2>Error Handling</h2>
117 * <p>
118 * For usability, {@link WSDLParserExtension}s are expected to check possible
119 * errors in the extension elements that it parses. When an error is found,
120 * it may throw a {@link WebServiceException} to abort the parsing of the WSDL.
121 * This exception will be propagated to the user, so it should have
122 * detailed error messages pointing at the problem.
123 *
124 * <h2>Discovery</h2>
125 * <p>
126 * The JAX-WS RI locates the implementation of {@link WSDLParserExtension}s
127 * by using the standard service look up mechanism, in particular looking for
128 * <tt>META-INF/services/com.sun.xml.internal.ws.api.wsdl.parser.WSDLParserExtension</tt>
129 *
130 *
131 * <h2>TODO</h2>
132 * <p>
133 * As it's designed today, extensions cannot access to any of the environmental
134 * information before the parsing begins (such as what {@link WSService} this
135 * WSDL is being parsed for, etc.) We might need to reconsider this aspect.
136 * The JAX-WS team waits for feedback on this topic.
137 *
138 * @author Kohsuke Kawaguchi
139 */
140 public abstract class WSDLParserExtension {
141 public void start(WSDLParserExtensionContext context){
142 // noop
143 }
144 public void serviceAttributes(WSDLService service, XMLStreamReader reader) {
145 // noop
146 }
148 public boolean serviceElements(WSDLService service, XMLStreamReader reader) {
149 return false;
150 }
152 public void portAttributes(WSDLPort port, XMLStreamReader reader) {
153 // noop
154 }
156 public boolean portElements(WSDLPort port, XMLStreamReader reader) {
157 return false;
158 }
160 public boolean portTypeOperationInput(WSDLOperation op, XMLStreamReader reader) {
161 return false;
162 }
164 public boolean portTypeOperationOutput(WSDLOperation op, XMLStreamReader reader) {
165 return false;
166 }
168 public boolean portTypeOperationFault(WSDLOperation op, XMLStreamReader reader) {
169 return false;
170 }
172 public boolean definitionsElements(XMLStreamReader reader) {
173 return false;
174 }
176 public boolean bindingElements(WSDLBoundPortType binding, XMLStreamReader reader) {
177 return false;
178 }
180 public void bindingAttributes(WSDLBoundPortType binding, XMLStreamReader reader) {
181 }
183 public boolean portTypeElements(WSDLPortType portType, XMLStreamReader reader) {
184 return false;
185 }
187 public void portTypeAttributes(WSDLPortType portType, XMLStreamReader reader) {
188 }
190 public boolean portTypeOperationElements(WSDLOperation operation, XMLStreamReader reader) {
191 return false;
192 }
194 public void portTypeOperationAttributes(WSDLOperation operation, XMLStreamReader reader) {
195 }
197 public boolean bindingOperationElements(WSDLBoundOperation operation, XMLStreamReader reader) {
198 return false;
199 }
201 public void bindingOperationAttributes(WSDLBoundOperation operation, XMLStreamReader reader) {
202 }
204 public boolean messageElements(WSDLMessage msg, XMLStreamReader reader) {
205 return false;
206 }
208 public void messageAttributes(WSDLMessage msg, XMLStreamReader reader) {
209 }
211 public boolean portTypeOperationInputElements(WSDLInput input, XMLStreamReader reader) {
212 return false;
213 }
215 public void portTypeOperationInputAttributes(WSDLInput input, XMLStreamReader reader) {
216 }
218 public boolean portTypeOperationOutputElements(WSDLOutput output, XMLStreamReader reader) {
219 return false;
220 }
222 public void portTypeOperationOutputAttributes(WSDLOutput output, XMLStreamReader reader) {
223 }
225 public boolean portTypeOperationFaultElements(WSDLFault fault, XMLStreamReader reader) {
226 return false;
227 }
229 public void portTypeOperationFaultAttributes(WSDLFault fault, XMLStreamReader reader) {
230 }
232 public boolean bindingOperationInputElements(WSDLBoundOperation operation, XMLStreamReader reader) {
233 return false;
234 }
236 public void bindingOperationInputAttributes(WSDLBoundOperation operation, XMLStreamReader reader) {
237 }
239 public boolean bindingOperationOutputElements(WSDLBoundOperation operation, XMLStreamReader reader) {
240 return false;
241 }
243 public void bindingOperationOutputAttributes(WSDLBoundOperation operation, XMLStreamReader reader) {
244 }
246 public boolean bindingOperationFaultElements(WSDLBoundFault fault, XMLStreamReader reader) {
247 return false;
248 }
250 public void bindingOperationFaultAttributes(WSDLBoundFault fault, XMLStreamReader reader) {
251 }
253 // TODO: complete the rest of the callback
255 /**
256 * Called when the parsing of a set of WSDL documents are all done.
257 * <p>
258 * This is the opportunity to do any post-processing of the parsing
259 * you've done.
260 *
261 * @param context {@link WSDLParserExtensionContext} gives fully parsed {@link WSDLModel}.
262 */
263 public void finished(WSDLParserExtensionContext context) {
264 // noop
265 }
267 public void postFinished(WSDLParserExtensionContext context) {
268 // noop
269 }
270 }