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: package com.sun.xml.ws.api.message;
037:
038: import com.sun.istack.NotNull;
039: import com.sun.istack.Nullable;
040: import com.sun.xml.bind.api.Bridge;
041: import com.sun.xml.ws.api.SOAPVersion;
042: import com.sun.xml.ws.api.addressing.AddressingVersion;
043: import com.sun.xml.ws.api.addressing.WSEndpointReference;
044: import org.xml.sax.ContentHandler;
045: import org.xml.sax.ErrorHandler;
046: import org.xml.sax.SAXException;
047: import org.xml.sax.SAXParseException;
048:
049: import javax.xml.bind.JAXBException;
050: import javax.xml.bind.Unmarshaller;
051: import javax.xml.namespace.QName;
052: import javax.xml.soap.SOAPException;
053: import javax.xml.soap.SOAPMessage;
054: import javax.xml.stream.XMLStreamException;
055: import javax.xml.stream.XMLStreamReader;
056: import javax.xml.stream.XMLStreamWriter;
057: import javax.xml.ws.WebServiceException;
058: import java.util.Set;
059:
060: /**
061: * A SOAP header.
062: *
063: * <p>
064: * A header is immutable, but unlike body it can be read
065: * multiple times.
066: * The {@link Header} abstraction hides how the header
067: * data is represented in memory; instead, it commits to
068: * the ability to write itself to XML infoset.
069: *
070: * <p>
071: * When a message is received from the transport and
072: * being processed, the processor needs to "peek"
073: * some information of a header, such as the tag name,
074: * the mustUnderstand attribute, and so on. Therefore,
075: * the {@link Header} interface exposes those information
076: * as properties, so that they can be checked without
077: * replaying the infoset, which is efficiently but still
078: * costly.
079: *
080: * <p>
081: * A {@link Header} may belong to more than one {@link HeaderList}
082: * due to wrapping of {@link Message}.
083: *
084: * @see HeaderList
085: * @see Headers
086: */
087: public interface Header {
088: // TODO: Vivek pointed out that the only time we are looking at
089: // mustUnderstand and role are when we do the mustUnderstand error check
090: // (that is, to find out if there's any header with @mustUnderstand that
091: // has appropriate role for us.)
092: // if that's the case, it might be better if we define this whole operation
093: // as one method, instead of exposing two properties.
094:
095: /**
096: * Checks if this header is ignorable for us (IOW, make sure
097: * that this header has a problematic "mustUnderstand" header value
098: * that we have to reject.)
099: *
100: * <p>
101: * This method is used as a part of the
102: * <a href="HeaderList.html#MU">mustUnderstanx processing</a>.
103: * At the end of the processing, the JAX-WS identifies a list of {@link Header}s
104: * that were not understood. This method is invoked on those {@link Header}s,
105: * to verify that we don't need to report an error for it.
106: *
107: * <p>
108: * specifically, this method has to perform the following tasks:
109: *
110: * <ul>
111: * <li>If this header does not have <tt>mustUnderstand</tt> as "1" nor "true",
112: * then this method must return true.
113: * <li>Otherwise, check the role attribute (for SOAP 1.2) or the actor attribute (for SOAP 1.1).
114: * When those attributes are absent, the default values have to be assumed.
115: * See {@link #getRole(SOAPVersion)} for how the values are defaulted.
116: * Now, see if the {@code roles} set contains the value.
117: * If so, this method must return false (indicating that an error is in order.)
118: * <li>Otherwise return true (since we don't play the role this header is intended for.)
119: * </ul>
120: *
121: * @param soapVersion
122: * The caller specifies the SOAP version that the pipeline is working against.
123: * Often each {@link Header} implementation already knows the SOAP version
124: * anyway, but this allows some {@link Header}s to avoid keeping it.
125: * That's why this redundant parameter is passed in.
126: * @param roles
127: * The set of role values that the current JAX-WS pipeline is assuming.
128: * Note that SOAP 1.1 and SOAP 1.2 use different strings for the same role,
129: * and the caller is responsible for supplying a proper value depending on the
130: * active SOAP version in use.
131: *
132: * @return
133: * true if no error needs to be reported. False if an error needs to be raised.
134: * See the method javadoc for more discussion.
135: */
136: public boolean isIgnorable(@NotNull
137: SOAPVersion soapVersion, @NotNull
138: Set<String> roles);
139:
140: /**
141: * Gets the value of the soap:role attribute (or soap:actor for SOAP 1.1).
142: *
143: * <p>
144: * If the attribute is omitted, the value defaults to {@link SOAPVersion#implicitRole}.
145: *
146: * @param soapVersion
147: * The caller specifies the SOAP version that the pipeline is working against.
148: * Often each {@link Header} implementation already knows the SOAP version
149: * anyway, but this allows some {@link Header}s to avoid keeping it.
150: * That's why this redundant parameter is passed in.
151: * @return
152: * never null. This string need not be interned.
153: */
154: public @NotNull
155: String getRole(@NotNull
156: SOAPVersion soapVersion);
157:
158: /**
159: * True if this header is to be relayed if not processed.
160: * For SOAP 1.1 messages, this method always return false.
161: *
162: * <p>
163: * IOW, this method returns true if there's @soap:relay='true'
164: * is present.
165: *
166: * <h3>Implementation Note</h3>
167: * <p>
168: * The implementation needs to check for both "true" and "1",
169: * but because attribute values are normalized, it doesn't have
170: * to consider " true", " 1 ", and so on.
171: *
172: * @return
173: * false.
174: */
175: public boolean isRelay();
176:
177: /**
178: * Gets the namespace URI of this header element.
179: *
180: * @return
181: * this string must be interned.
182: */
183: public @NotNull
184: String getNamespaceURI();
185:
186: /**
187: * Gets the local name of this header element.
188: *
189: * @return
190: * this string must be interned.
191: */
192: public @NotNull
193: String getLocalPart();
194:
195: /**
196: * Gets the attribute value on the header element.
197: *
198: * @param nsUri
199: * The namespace URI of the attribute. Can be empty.
200: * @param localName
201: * The local name of the attribute.
202: *
203: * @return
204: * if the attribute is found, return the whitespace normalized value.
205: * (meaning no leading/trailing space, no consequtive whitespaces in-between.)
206: * Otherwise null. Note that the XML parsers are responsible for
207: * whitespace-normalizing attributes, so {@link Header} implementation
208: * doesn't have to do anything.
209: */
210: @Nullable
211: String getAttribute(@NotNull
212: String nsUri, @NotNull
213: String localName);
214:
215: /**
216: * Gets the attribute value on the header element.
217: *
218: * <p>
219: * This is a convenience method that calls into {@link #getAttribute(String, String)}
220: *
221: * @param name
222: * Never null.
223: *
224: * @see #getAttribute(String, String)
225: */
226: @Nullable
227: String getAttribute(@NotNull
228: QName name);
229:
230: /**
231: * Reads the header as a {@link XMLStreamReader}.
232: *
233: * <p>
234: * The returned parser points at the start element of this header.
235: * (IOW, {@link XMLStreamReader#getEventType()} would return
236: * {@link XMLStreamReader#START_ELEMENT}.
237: *
238: * <h3>Performance Expectation</h3>
239: * <p>
240: * For some {@link Header} implementations, this operation
241: * is a non-trivial operation. Therefore, use of this method
242: * is discouraged unless the caller is interested in reading
243: * the whole header.
244: *
245: * <p>
246: * Similarly, if the caller wants to use this method only to do
247: * the API conversion (such as simply firing SAX events from
248: * {@link XMLStreamReader}), then the JAX-WS team requests
249: * that you talk to us.
250: *
251: * <p>
252: * {@link Message}s that come from tranport usually provides
253: * a reasonably efficient implementation of this method.
254: *
255: * @return
256: * must not null.
257: */
258: public XMLStreamReader readHeader() throws XMLStreamException;
259:
260: /**
261: * Reads the header as a JAXB object by using the given unmarshaller.
262: */
263: public <T> T readAsJAXB(Unmarshaller unmarshaller)
264: throws JAXBException;
265:
266: /**
267: * Reads the header as a JAXB object by using the given unmarshaller.
268: */
269: public <T> T readAsJAXB(Bridge<T> bridge) throws JAXBException;
270:
271: /**
272: * Reads this header as an {@link WSEndpointReference}.
273: *
274: * @param expected
275: * The version of the addressing used to parse the EPR.
276: * If the actual infoset and this doesn't agree, then
277: * you'll get an {@link WebServiceException} stating that fact.
278: *
279: * @return
280: * On a successful return, this method never returns null.
281: */
282: public @NotNull
283: WSEndpointReference readAsEPR(AddressingVersion expected)
284: throws XMLStreamException;
285:
286: /**
287: * Writes out the header as a fragment.
288: *
289: * @throws XMLStreamException
290: * if the operation fails for some reason. This leaves the
291: * writer to an undefined state.
292: */
293: public void writeTo(XMLStreamWriter w) throws XMLStreamException;
294:
295: /**
296: * Writes out the header to the given SOAPMessage.
297: *
298: * <p>
299: * Sometimes a {@link Message} needs to produce itself
300: * as {@link SOAPMessage}, in which case each header needs
301: * to turn itself into a header.
302: *
303: * @throws SOAPException
304: * if the operation fails for some reason. This leaves the
305: * writer to an undefined state.
306: */
307: public void writeTo(SOAPMessage saaj) throws SOAPException;
308:
309: /**
310: * Writes out the header as SAX events.
311: *
312: * <p>
313: * Sometimes a {@link Message} needs to produce SAX events,
314: * and this method is necessary for headers to participate to it.
315: *
316: * <p>
317: * A header is responsible for producing the SAX events for its part,
318: * including <tt>startPrefixMapping</tt> and <tt>endPrefixMapping</tt>,
319: * but not startDocument/endDocument.
320: *
321: * <p>
322: * Note that SAX contract requires that any error that does NOT originate
323: * from {@link ContentHandler} (meaning any parsing error and etc) must
324: * be first reported to {@link ErrorHandler}. If the SAX event production
325: * cannot be continued and the processing needs to abort, the code may
326: * then throw the same {@link SAXParseException} reported to {@link ErrorHandler}.
327: *
328: * @param contentHandler
329: * The {@link ContentHandler} that receives SAX events.
330: *
331: * @param errorHandler
332: * The {@link ErrorHandler} that receives parsing errors.
333: */
334: public void writeTo(ContentHandler contentHandler,
335: ErrorHandler errorHandler) throws SAXException;
336:
337: /**
338: * Used to obtain value XYZ from a header that looks like
339: * "<header>XYZ</header>". The primary use of this header
340: * for now is to access certain Addressing headers quickly.
341: *
342: * @throws WebServiceException
343: * If the structure of the header is more complicated than
344: * a simple string header.
345: *
346: * @return
347: * Can be empty but always non-null.
348: */
349: public @NotNull
350: String getStringContent();
351: }
|