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 }