84 // has appropriate role for us.)
85 // if that's the case, it might be better if we define this whole operation
86 // as one method, instead of exposing two properties.
87
88 /**
89 * Checks if this header is ignorable for us (IOW, make sure
90 * that this header has a problematic "mustUnderstand" header value
91 * that we have to reject.)
92 *
93 * <p>
94 * This method is used as a part of the
95 * <a href="HeaderList.html#MU">mustUnderstanx processing</a>.
96 * At the end of the processing, the JAX-WS identifies a list of {@link Header}s
97 * that were not understood. This method is invoked on those {@link Header}s,
98 * to verify that we don't need to report an error for it.
99 *
100 * <p>
101 * specifically, this method has to perform the following tasks:
102 *
103 * <ul>
104 * <li>If this header does not have <tt>mustUnderstand</tt> as "1" nor "true",
105 * then this method must return true.
106 * <li>Otherwise, check the role attribute (for SOAP 1.2) or the actor attribute (for SOAP 1.1).
107 * When those attributes are absent, the default values have to be assumed.
108 * See {@link #getRole(SOAPVersion)} for how the values are defaulted.
109 * Now, see if the {@code roles} set contains the value.
110 * If so, this method must return false (indicating that an error is in order.)
111 * <li>Otherwise return true (since we don't play the role this header is intended for.)
112 * </ul>
113 *
114 * @param soapVersion
115 * The caller specifies the SOAP version that the pipeline is working against.
116 * Often each {@link Header} implementation already knows the SOAP version
117 * anyway, but this allows some {@link Header}s to avoid keeping it.
118 * That's why this redundant parameter is passed in.
119 * @param roles
120 * The set of role values that the current JAX-WS pipeline is assuming.
121 * Note that SOAP 1.1 and SOAP 1.2 use different strings for the same role,
122 * and the caller is responsible for supplying a proper value depending on the
123 * active SOAP version in use.
124 *
283 * <p>
284 * Sometimes a {@link Message} needs to produce itself
285 * as {@link SOAPMessage}, in which case each header needs
286 * to turn itself into a header.
287 *
288 * @throws SOAPException
289 * if the operation fails for some reason. This leaves the
290 * writer to an undefined state.
291 */
292 public void writeTo(SOAPMessage saaj) throws SOAPException;
293
294 /**
295 * Writes out the header as SAX events.
296 *
297 * <p>
298 * Sometimes a {@link Message} needs to produce SAX events,
299 * and this method is necessary for headers to participate to it.
300 *
301 * <p>
302 * A header is responsible for producing the SAX events for its part,
303 * including <tt>startPrefixMapping</tt> and <tt>endPrefixMapping</tt>,
304 * but not startDocument/endDocument.
305 *
306 * <p>
307 * Note that SAX contract requires that any error that does NOT originate
308 * from {@link ContentHandler} (meaning any parsing error and etc) must
309 * be first reported to {@link ErrorHandler}. If the SAX event production
310 * cannot be continued and the processing needs to abort, the code may
311 * then throw the same {@link SAXParseException} reported to {@link ErrorHandler}.
312 *
313 * @param contentHandler
314 * The {@link ContentHandler} that receives SAX events.
315 *
316 * @param errorHandler
317 * The {@link ErrorHandler} that receives parsing errors.
318 */
319 public void writeTo(ContentHandler contentHandler, ErrorHandler errorHandler) throws SAXException;
320
321 /**
322 * Used to obtain value XYZ from a header that looks like
323 * "<header>XYZ</header>". The primary use of this header
|
84 // has appropriate role for us.)
85 // if that's the case, it might be better if we define this whole operation
86 // as one method, instead of exposing two properties.
87
88 /**
89 * Checks if this header is ignorable for us (IOW, make sure
90 * that this header has a problematic "mustUnderstand" header value
91 * that we have to reject.)
92 *
93 * <p>
94 * This method is used as a part of the
95 * <a href="HeaderList.html#MU">mustUnderstanx processing</a>.
96 * At the end of the processing, the JAX-WS identifies a list of {@link Header}s
97 * that were not understood. This method is invoked on those {@link Header}s,
98 * to verify that we don't need to report an error for it.
99 *
100 * <p>
101 * specifically, this method has to perform the following tasks:
102 *
103 * <ul>
104 * <li>If this header does not have {@code mustUnderstand} as "1" nor "true",
105 * then this method must return true.
106 * <li>Otherwise, check the role attribute (for SOAP 1.2) or the actor attribute (for SOAP 1.1).
107 * When those attributes are absent, the default values have to be assumed.
108 * See {@link #getRole(SOAPVersion)} for how the values are defaulted.
109 * Now, see if the {@code roles} set contains the value.
110 * If so, this method must return false (indicating that an error is in order.)
111 * <li>Otherwise return true (since we don't play the role this header is intended for.)
112 * </ul>
113 *
114 * @param soapVersion
115 * The caller specifies the SOAP version that the pipeline is working against.
116 * Often each {@link Header} implementation already knows the SOAP version
117 * anyway, but this allows some {@link Header}s to avoid keeping it.
118 * That's why this redundant parameter is passed in.
119 * @param roles
120 * The set of role values that the current JAX-WS pipeline is assuming.
121 * Note that SOAP 1.1 and SOAP 1.2 use different strings for the same role,
122 * and the caller is responsible for supplying a proper value depending on the
123 * active SOAP version in use.
124 *
283 * <p>
284 * Sometimes a {@link Message} needs to produce itself
285 * as {@link SOAPMessage}, in which case each header needs
286 * to turn itself into a header.
287 *
288 * @throws SOAPException
289 * if the operation fails for some reason. This leaves the
290 * writer to an undefined state.
291 */
292 public void writeTo(SOAPMessage saaj) throws SOAPException;
293
294 /**
295 * Writes out the header as SAX events.
296 *
297 * <p>
298 * Sometimes a {@link Message} needs to produce SAX events,
299 * and this method is necessary for headers to participate to it.
300 *
301 * <p>
302 * A header is responsible for producing the SAX events for its part,
303 * including {@code startPrefixMapping} and {@code endPrefixMapping},
304 * but not startDocument/endDocument.
305 *
306 * <p>
307 * Note that SAX contract requires that any error that does NOT originate
308 * from {@link ContentHandler} (meaning any parsing error and etc) must
309 * be first reported to {@link ErrorHandler}. If the SAX event production
310 * cannot be continued and the processing needs to abort, the code may
311 * then throw the same {@link SAXParseException} reported to {@link ErrorHandler}.
312 *
313 * @param contentHandler
314 * The {@link ContentHandler} that receives SAX events.
315 *
316 * @param errorHandler
317 * The {@link ErrorHandler} that receives parsing errors.
318 */
319 public void writeTo(ContentHandler contentHandler, ErrorHandler errorHandler) throws SAXException;
320
321 /**
322 * Used to obtain value XYZ from a header that looks like
323 * "<header>XYZ</header>". The primary use of this header
|