< prev index next >

src/java.xml.ws/share/classes/com/sun/xml/internal/ws/api/message/Header.java

Print this page




  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      * "&lt;header&gt;XYZ&lt;/header&gt;". 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      * "&lt;header&gt;XYZ&lt;/header&gt;". The primary use of this header
< prev index next >