1 /*
   2  * Copyright (c) 2005, 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  */
  25 
  26 package javax.xml.ws.handler.soap;
  27 
  28 import javax.xml.soap.SOAPMessage;
  29 import javax.xml.bind.JAXBContext;
  30 import javax.xml.namespace.QName;
  31 import java.util.Set;
  32 
  33 /** The interface <code>SOAPMessageContext</code>
  34  *  provides access to the SOAP message for either RPC request or
  35  *  response. The <code>javax.xml.soap.SOAPMessage</code> specifies
  36  *  the standard Java API for the representation of a SOAP 1.1 message
  37  *  with attachments.
  38  *
  39  *  @see javax.xml.soap.SOAPMessage
  40  *
  41  *  @since 1.6, JAX-WS 2.0
  42 **/
  43 public interface SOAPMessageContext
  44                     extends javax.xml.ws.handler.MessageContext {
  45 
  46   /** Gets the <code>SOAPMessage</code> from this message context. Modifications
  47    *  to the returned <code>SOAPMessage</code> change the message in-place, there
  48    *  is no need to subsequently call <code>setMessage</code>.
  49    *
  50    *  @return Returns the <code>SOAPMessage</code>; returns <code>null</code> if no
  51    *          <code>SOAPMessage</code> is present in this message context
  52   **/
  53   public SOAPMessage getMessage();
  54 
  55   /** Sets the SOAPMessage in this message context
  56    *
  57    *  @param  message SOAP message
  58    *  @throws WebServiceException If any error during the setting
  59    *          of the <code>SOAPMessage</code> in this message context
  60    *  @throws java.lang.UnsupportedOperationException If this
  61    *          operation is not supported
  62   **/
  63   public void setMessage(SOAPMessage message);
  64 
  65   /** Gets headers that have a particular qualified name from the message in the
  66    *  message context. Note that a SOAP message can contain multiple headers
  67    *  with the same qualified name.
  68    *
  69    *  @param  header The XML qualified name of the SOAP header(s).
  70    *  @param  context The JAXBContext that should be used to unmarshall the
  71    *          header
  72    *  @param  allRoles If <code>true</code> then returns headers for all SOAP
  73    *          roles, if <code>false</code> then only returns headers targetted
  74    *          at the roles currently being played by this SOAP node, see
  75    *          <code>getRoles</code>.
  76    *  @return An array of unmarshalled headers; returns an empty array if no
  77    *          message is present in this message context or no headers match
  78    *          the supplied qualified name.
  79    *  @throws WebServiceException If an error occurs when using the supplied
  80    *     <code>JAXBContext</code> to unmarshall. The cause of
  81    *     the <code>WebServiceException</code> is the original <code>JAXBException</code>.
  82   **/
  83   public Object[] getHeaders(QName header, JAXBContext context,
  84     boolean allRoles);
  85 
  86   /** Gets the SOAP actor roles associated with an execution
  87    *  of the handler chain.
  88    *  Note that SOAP actor roles apply to the SOAP node and
  89    *  are managed using {@link javax.xml.ws.soap.SOAPBinding#setRoles} and
  90    *  {@link javax.xml.ws.soap.SOAPBinding#getRoles}. <code>Handler</code> instances in
  91    *  the handler chain use this information about the SOAP actor
  92    *  roles to process the SOAP header blocks. Note that the
  93    *  SOAP actor roles are invariant during the processing of
  94    *  SOAP message through the handler chain.
  95    *
  96    *  @return Array of <code>String</code> for SOAP actor roles
  97   **/
  98   public Set<String> getRoles();
  99 }
--- EOF ---