01 /*
02 * Copyright 2005 Sun Microsystems, Inc. All Rights Reserved.
03 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
04 *
05 * This code is free software; you can redistribute it and/or modify it
06 * under the terms of the GNU General Public License version 2 only, as
07 * published by the Free Software Foundation. Sun designates this
08 * particular file as subject to the "Classpath" exception as provided
09 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 JAX-WS 2.0
42 **/
43 public interface SOAPMessageContext extends
44 javax.xml.ws.handler.MessageContext {
45
46 /** Gets the SOAPMessage from this message context. Modifications
47 * to the returned SOAPMessage change the message in-place, there
48 * is no need to susequently call <code>setMessage</code>.
49 *
50 * @return Returns the SOAPMessage; returns null if no
51 * 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 WebServiceException If any error during the setting
59 * of the 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</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 * JAXBContext to unmarshall. The cause of
81 * the WebServiceException is the original 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 <code>SOAPBinding.setRoles</code> and
90 * <code>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 String for SOAP actor roles
97 **/
98 public Set<String> getRoles();
99 }
|