1/*
2 * Copyright (c) 2005, 2015, 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
26package javax.xml.ws.handler.soap;
27
28import javax.xml.soap.SOAPMessage;
29import javax.xml.bind.JAXBContext;
30import javax.xml.namespace.QName;
31import java.util.Set;
32
33/** The interface {@code SOAPMessageContext}
34 *  provides access to the SOAP message for either RPC request or
35 *  response. The {@code javax.xml.soap.SOAPMessage} 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**/
43public interface SOAPMessageContext
44                    extends javax.xml.ws.handler.MessageContext {
45
46  /** Gets the {@code SOAPMessage} from this message context. Modifications
47   *  to the returned {@code SOAPMessage} change the message in-place, there
48   *  is no need to subsequently call {@code setMessage}.
49   *
50   *  @return Returns the {@code SOAPMessage}; returns {@code null} if no
51   *          {@code SOAPMessage} 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 javax.xml.ws.WebServiceException If any error during the setting
59   *          of the {@code SOAPMessage} 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} then returns headers for all SOAP
73   *          roles, if {@code false} then only returns headers targetted
74   *          at the roles currently being played by this SOAP node, see
75   *          {@code getRoles}.
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 javax.xml.ws.WebServiceException If an error occurs when using the supplied
80   *     {@code JAXBContext} to unmarshall. The cause of
81   *     the {@code WebServiceException} is the original {@code JAXBException}.
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} 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} for SOAP actor roles
97  **/
98  public Set<String> getRoles();
99}
100