1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/src/share/jaxws_classes/javax/xml/soap/SOAPMessage.java Wed Apr 27 01:27:09 2016 +0800 1.3 @@ -0,0 +1,456 @@ 1.4 +/* 1.5 + * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved. 1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 1.7 + * 1.8 + * This code is free software; you can redistribute it and/or modify it 1.9 + * under the terms of the GNU General Public License version 2 only, as 1.10 + * published by the Free Software Foundation. Oracle designates this 1.11 + * particular file as subject to the "Classpath" exception as provided 1.12 + * by Oracle in the LICENSE file that accompanied this code. 1.13 + * 1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT 1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1.17 + * version 2 for more details (a copy is included in the LICENSE file that 1.18 + * accompanied this code). 1.19 + * 1.20 + * You should have received a copy of the GNU General Public License version 1.21 + * 2 along with this work; if not, write to the Free Software Foundation, 1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1.23 + * 1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 1.25 + * or visit www.oracle.com if you need additional information or have any 1.26 + * questions. 1.27 + */ 1.28 + 1.29 +package javax.xml.soap; 1.30 +import java.io.OutputStream; 1.31 +import java.io.IOException; 1.32 + 1.33 +import java.util.Iterator; 1.34 + 1.35 +import javax.activation.DataHandler; 1.36 + 1.37 +/** 1.38 + * The root class for all SOAP messages. As transmitted on the "wire", a SOAP 1.39 + * message is an XML document or a MIME message whose first body part is an 1.40 + * XML/SOAP document. 1.41 + * <P> 1.42 + * A <code>SOAPMessage</code> object consists of a SOAP part and optionally 1.43 + * one or more attachment parts. The SOAP part for a <code>SOAPMessage</code> 1.44 + * object is a <code>SOAPPart</code> object, which contains information used 1.45 + * for message routing and identification, and which can contain 1.46 + * application-specific content. All data in the SOAP Part of a message must be 1.47 + * in XML format. 1.48 + * <P> 1.49 + * A new <code>SOAPMessage</code> object contains the following by default: 1.50 + * <UL> 1.51 + * <LI>A <code>SOAPPart</code> object 1.52 + * <LI>A <code>SOAPEnvelope</code> object 1.53 + * <LI>A <code>SOAPBody</code> object 1.54 + * <LI>A <code>SOAPHeader</code> object 1.55 + * </UL> 1.56 + * The SOAP part of a message can be retrieved by calling the method <code>SOAPMessage.getSOAPPart()</code>. 1.57 + * The <code>SOAPEnvelope</code> object is retrieved from the <code>SOAPPart</code> 1.58 + * object, and the <code>SOAPEnvelope</code> object is used to retrieve the 1.59 + * <code>SOAPBody</code> and <code>SOAPHeader</code> objects. 1.60 + * 1.61 + * <PRE> 1.62 + * SOAPPart sp = message.getSOAPPart(); 1.63 + * SOAPEnvelope se = sp.getEnvelope(); 1.64 + * SOAPBody sb = se.getBody(); 1.65 + * SOAPHeader sh = se.getHeader(); 1.66 + * </PRE> 1.67 + * 1.68 + * <P> 1.69 + * In addition to the mandatory <code>SOAPPart</code> object, a <code>SOAPMessage</code> 1.70 + * object may contain zero or more <code>AttachmentPart</code> objects, each 1.71 + * of which contains application-specific data. The <code>SOAPMessage</code> 1.72 + * interface provides methods for creating <code>AttachmentPart</code> 1.73 + * objects and also for adding them to a <code>SOAPMessage</code> object. A 1.74 + * party that has received a <code>SOAPMessage</code> object can examine its 1.75 + * contents by retrieving individual attachment parts. 1.76 + * <P> 1.77 + * Unlike the rest of a SOAP message, an attachment is not required to be in 1.78 + * XML format and can therefore be anything from simple text to an image file. 1.79 + * Consequently, any message content that is not in XML format must be in an 1.80 + * <code>AttachmentPart</code> object. 1.81 + * <P> 1.82 + * A <code>MessageFactory</code> object may create <code>SOAPMessage</code> 1.83 + * objects with behavior that is specialized to a particular implementation or 1.84 + * application of SAAJ. For instance, a <code>MessageFactory</code> object 1.85 + * may produce <code>SOAPMessage</code> objects that conform to a particular 1.86 + * Profile such as ebXML. In this case a <code>MessageFactory</code> object 1.87 + * might produce <code>SOAPMessage</code> objects that are initialized with 1.88 + * ebXML headers. 1.89 + * <P> 1.90 + * In order to ensure backward source compatibility, methods that are added to 1.91 + * this class after version 1.1 of the SAAJ specification are all concrete 1.92 + * instead of abstract and they all have default implementations. Unless 1.93 + * otherwise noted in the JavaDocs for those methods the default 1.94 + * implementations simply throw an <code>UnsupportedOperationException</code> 1.95 + * and the SAAJ implementation code must override them with methods that 1.96 + * provide the specified behavior. Legacy client code does not have this 1.97 + * restriction, however, so long as there is no claim made that it conforms to 1.98 + * some later version of the specification than it was originally written for. 1.99 + * A legacy class that extends the SOAPMessage class can be compiled and/or run 1.100 + * against succeeding versions of the SAAJ API without modification. If such a 1.101 + * class was correctly implemented then it will continue to behave correctly 1.102 + * relative to the version of the specification against which it was written. 1.103 + * 1.104 + * @see MessageFactory 1.105 + * @see AttachmentPart 1.106 + */ 1.107 +public abstract class SOAPMessage { 1.108 + /** 1.109 + * Specifies the character type encoding for the SOAP Message. Valid values 1.110 + * include "utf-8" and "utf-16". See vendor documentation for additional 1.111 + * supported values. The default is "utf-8". 1.112 + * 1.113 + * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty 1.114 + * @since SAAJ 1.2 1.115 + */ 1.116 + public static final String CHARACTER_SET_ENCODING = 1.117 + "javax.xml.soap.character-set-encoding"; 1.118 + 1.119 + /** 1.120 + * Specifies whether the SOAP Message will contain an XML declaration when 1.121 + * it is sent. The only valid values are "true" and "false". The default is 1.122 + * "false". 1.123 + * 1.124 + * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty 1.125 + * @since SAAJ 1.2 1.126 + */ 1.127 + public static final String WRITE_XML_DECLARATION = 1.128 + "javax.xml.soap.write-xml-declaration"; 1.129 + 1.130 + /** 1.131 + * Sets the description of this <code>SOAPMessage</code> object's 1.132 + * content with the given description. 1.133 + * 1.134 + * @param description a <code>String</code> describing the content of this 1.135 + * message 1.136 + * @see #getContentDescription 1.137 + */ 1.138 + public abstract void setContentDescription(String description); 1.139 + 1.140 + /** 1.141 + * Retrieves a description of this <code>SOAPMessage</code> object's 1.142 + * content. 1.143 + * 1.144 + * @return a <code>String</code> describing the content of this 1.145 + * message or <code>null</code> if no description has been set 1.146 + * @see #setContentDescription 1.147 + */ 1.148 + public abstract String getContentDescription(); 1.149 + 1.150 + /** 1.151 + * Gets the SOAP part of this <code>SOAPMessage</code> object. 1.152 + * <P> 1.153 + * <code>SOAPMessage</code> object contains one or more attachments, the 1.154 + * SOAP Part must be the first MIME body part in the message. 1.155 + * 1.156 + * @return the <code>SOAPPart</code> object for this <code>SOAPMessage</code> 1.157 + * object 1.158 + */ 1.159 + public abstract SOAPPart getSOAPPart(); 1.160 + 1.161 + /** 1.162 + * Gets the SOAP Body contained in this <code>SOAPMessage</code> object. 1.163 + * <p> 1.164 + * 1.165 + * @return the <code>SOAPBody</code> object contained by this <code>SOAPMessage</code> 1.166 + * object 1.167 + * @exception SOAPException 1.168 + * if the SOAP Body does not exist or cannot be retrieved 1.169 + * @since SAAJ 1.2 1.170 + */ 1.171 + public SOAPBody getSOAPBody() throws SOAPException { 1.172 + throw new UnsupportedOperationException("getSOAPBody must be overridden by all subclasses of SOAPMessage"); 1.173 + } 1.174 + 1.175 + /** 1.176 + * Gets the SOAP Header contained in this <code>SOAPMessage</code> 1.177 + * object. 1.178 + * <p> 1.179 + * 1.180 + * @return the <code>SOAPHeader</code> object contained by this <code>SOAPMessage</code> 1.181 + * object 1.182 + * @exception SOAPException 1.183 + * if the SOAP Header does not exist or cannot be retrieved 1.184 + * @since SAAJ 1.2 1.185 + */ 1.186 + public SOAPHeader getSOAPHeader() throws SOAPException { 1.187 + throw new UnsupportedOperationException("getSOAPHeader must be overridden by all subclasses of SOAPMessage"); 1.188 + } 1.189 + 1.190 + /** 1.191 + * Removes all <code>AttachmentPart</code> objects that have been added 1.192 + * to this <code>SOAPMessage</code> object. 1.193 + * <P> 1.194 + * This method does not touch the SOAP part. 1.195 + */ 1.196 + public abstract void removeAllAttachments(); 1.197 + 1.198 + /** 1.199 + * Gets a count of the number of attachments in this message. This count 1.200 + * does not include the SOAP part. 1.201 + * 1.202 + * @return the number of <code>AttachmentPart</code> objects that are 1.203 + * part of this <code>SOAPMessage</code> object 1.204 + */ 1.205 + public abstract int countAttachments(); 1.206 + 1.207 + /** 1.208 + * Retrieves all the <code>AttachmentPart</code> objects that are part of 1.209 + * this <code>SOAPMessage</code> object. 1.210 + * 1.211 + * @return an iterator over all the attachments in this message 1.212 + */ 1.213 + public abstract Iterator getAttachments(); 1.214 + 1.215 + /** 1.216 + * Retrieves all the <code>AttachmentPart</code> objects that have header 1.217 + * entries that match the specified headers. Note that a returned 1.218 + * attachment could have headers in addition to those specified. 1.219 + * 1.220 + * @param headers 1.221 + * a <code>MimeHeaders</code> object containing the MIME 1.222 + * headers for which to search 1.223 + * @return an iterator over all attachments that have a header that matches 1.224 + * one of the given headers 1.225 + */ 1.226 + public abstract Iterator getAttachments(MimeHeaders headers); 1.227 + 1.228 + /** 1.229 + * Removes all the <code>AttachmentPart</code> objects that have header 1.230 + * entries that match the specified headers. Note that the removed 1.231 + * attachment could have headers in addition to those specified. 1.232 + * 1.233 + * @param headers 1.234 + * a <code>MimeHeaders</code> object containing the MIME 1.235 + * headers for which to search 1.236 + * @since SAAJ 1.3 1.237 + */ 1.238 + public abstract void removeAttachments(MimeHeaders headers); 1.239 + 1.240 + 1.241 + /** 1.242 + * Returns an <code>AttachmentPart</code> object that is associated with an 1.243 + * attachment that is referenced by this <code>SOAPElement</code> or 1.244 + * <code>null</code> if no such attachment exists. References can be made 1.245 + * via an <code>href</code> attribute as described in 1.246 + * {@link <a href="http://www.w3.org/TR/SOAP-attachments#SOAPReferenceToAttachements">SOAP Messages with Attachments</a>}, 1.247 + * or via a single <code>Text</code> child node containing a URI as 1.248 + * described in the WS-I Attachments Profile 1.0 for elements of schema 1.249 + * type {@link <a href="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html">ref:swaRef</a>}. These two mechanisms must be supported. 1.250 + * The support for references via <code>href</code> attribute also implies that 1.251 + * this method should also be supported on an element that is an 1.252 + * <i>xop:Include</i> element ( 1.253 + * {@link <a href="http://www.w3.org/2000/xp/Group/3/06/Attachments/XOP.html">XOP</a>}). 1.254 + * other reference mechanisms may be supported by individual 1.255 + * implementations of this standard. Contact your vendor for details. 1.256 + * 1.257 + * @param element The <code>SOAPElement</code> containing the reference to an Attachment 1.258 + * @return the referenced <code>AttachmentPart</code> or null if no such 1.259 + * <code>AttachmentPart</code> exists or no reference can be 1.260 + * found in this <code>SOAPElement</code>. 1.261 + * @throws SOAPException if there is an error in the attempt to access the 1.262 + * attachment 1.263 + * 1.264 + * @since SAAJ 1.3 1.265 + */ 1.266 + public abstract AttachmentPart getAttachment(SOAPElement element) throws SOAPException; 1.267 + 1.268 + 1.269 + /** 1.270 + * Adds the given <code>AttachmentPart</code> object to this <code>SOAPMessage</code> 1.271 + * object. An <code>AttachmentPart</code> object must be created before 1.272 + * it can be added to a message. 1.273 + * 1.274 + * @param AttachmentPart 1.275 + * an <code>AttachmentPart</code> object that is to become part 1.276 + * of this <code>SOAPMessage</code> object 1.277 + * @exception IllegalArgumentException 1.278 + */ 1.279 + public abstract void addAttachmentPart(AttachmentPart AttachmentPart); 1.280 + 1.281 + /** 1.282 + * Creates a new empty <code>AttachmentPart</code> object. Note that the 1.283 + * method <code>addAttachmentPart</code> must be called with this new 1.284 + * <code>AttachmentPart</code> object as the parameter in order for it to 1.285 + * become an attachment to this <code>SOAPMessage</code> object. 1.286 + * 1.287 + * @return a new <code>AttachmentPart</code> object that can be populated 1.288 + * and added to this <code>SOAPMessage</code> object 1.289 + */ 1.290 + public abstract AttachmentPart createAttachmentPart(); 1.291 + 1.292 + /** 1.293 + * Creates an <code>AttachmentPart</code> object and populates it using 1.294 + * the given <code>DataHandler</code> object. 1.295 + * 1.296 + * @param dataHandler 1.297 + * the <code>javax.activation.DataHandler</code> object that 1.298 + * will generate the content for this <code>SOAPMessage</code> 1.299 + * object 1.300 + * @return a new <code>AttachmentPart</code> object that contains data 1.301 + * generated by the given <code>DataHandler</code> object 1.302 + * @exception IllegalArgumentException 1.303 + * if there was a problem with the specified <code>DataHandler</code> 1.304 + * object 1.305 + * @see javax.activation.DataHandler 1.306 + * @see javax.activation.DataContentHandler 1.307 + */ 1.308 + public AttachmentPart createAttachmentPart(DataHandler dataHandler) { 1.309 + AttachmentPart attachment = createAttachmentPart(); 1.310 + attachment.setDataHandler(dataHandler); 1.311 + return attachment; 1.312 + } 1.313 + 1.314 + /** 1.315 + * Returns all the transport-specific MIME headers for this <code>SOAPMessage</code> 1.316 + * object in a transport-independent fashion. 1.317 + * 1.318 + * @return a <code>MimeHeaders</code> object containing the <code>MimeHeader</code> 1.319 + * objects 1.320 + */ 1.321 + public abstract MimeHeaders getMimeHeaders(); 1.322 + 1.323 + /** 1.324 + * Creates an <code>AttachmentPart</code> object and populates it with 1.325 + * the specified data of the specified content type. The type of the 1.326 + * <code>Object</code> should correspond to the value given for the 1.327 + * <code>Content-Type</code>. 1.328 + * 1.329 + * @param content 1.330 + * an <code>Object</code> containing the content for the 1.331 + * <code>AttachmentPart</code> object to be created 1.332 + * @param contentType 1.333 + * a <code>String</code> object giving the type of content; 1.334 + * examples are "text/xml", "text/plain", and "image/jpeg" 1.335 + * @return a new <code>AttachmentPart</code> object that contains the 1.336 + * given data 1.337 + * @exception IllegalArgumentException 1.338 + * may be thrown if the contentType does not match the type 1.339 + * of the content object, or if there was no 1.340 + * <code>DataContentHandler</code> object for the given 1.341 + * content object 1.342 + * @see javax.activation.DataHandler 1.343 + * @see javax.activation.DataContentHandler 1.344 + */ 1.345 + public AttachmentPart createAttachmentPart( 1.346 + Object content, 1.347 + String contentType) { 1.348 + AttachmentPart attachment = createAttachmentPart(); 1.349 + attachment.setContent(content, contentType); 1.350 + return attachment; 1.351 + } 1.352 + 1.353 + /** 1.354 + * Updates this <code>SOAPMessage</code> object with all the changes that 1.355 + * have been made to it. This method is called automatically when 1.356 + * {@link SOAPMessage#writeTo(OutputStream)} is called. However, if 1.357 + * changes are made to a message that was received or to one that has 1.358 + * already been sent, the method <code>saveChanges</code> needs to be 1.359 + * called explicitly in order to save the changes. The method <code>saveChanges</code> 1.360 + * also generates any changes that can be read back (for example, a 1.361 + * MessageId in profiles that support a message id). All MIME headers in a 1.362 + * message that is created for sending purposes are guaranteed to have 1.363 + * valid values only after <code>saveChanges</code> has been called. 1.364 + * <P> 1.365 + * In addition, this method marks the point at which the data from all 1.366 + * constituent <code>AttachmentPart</code> objects are pulled into the 1.367 + * message. 1.368 + * <P> 1.369 + * 1.370 + * @exception <code>SOAPException</code> if there was a problem saving 1.371 + * changes to this message. 1.372 + */ 1.373 + public abstract void saveChanges() throws SOAPException; 1.374 + 1.375 + /** 1.376 + * Indicates whether this <code>SOAPMessage</code> object needs to have 1.377 + * the method <code>saveChanges</code> called on it. 1.378 + * 1.379 + * @return <code>true</code> if <code>saveChanges</code> needs to be 1.380 + * called; <code>false</code> otherwise. 1.381 + */ 1.382 + public abstract boolean saveRequired(); 1.383 + 1.384 + /** 1.385 + * Writes this <code>SOAPMessage</code> object to the given output 1.386 + * stream. The externalization format is as defined by the SOAP 1.1 with 1.387 + * Attachments specification. 1.388 + * <P> 1.389 + * If there are no attachments, just an XML stream is written out. For 1.390 + * those messages that have attachments, <code>writeTo</code> writes a 1.391 + * MIME-encoded byte stream. 1.392 + * <P> 1.393 + * Note that this method does not write the transport-specific MIME Headers 1.394 + * of the Message 1.395 + * 1.396 + * @param out 1.397 + * the <code>OutputStream</code> object to which this <code>SOAPMessage</code> 1.398 + * object will be written 1.399 + * @exception IOException 1.400 + * if an I/O error occurs 1.401 + * @exception SOAPException 1.402 + * if there was a problem in externalizing this SOAP message 1.403 + */ 1.404 + public abstract void writeTo(OutputStream out) 1.405 + throws SOAPException, IOException; 1.406 + 1.407 + /** 1.408 + * Associates the specified value with the specified property. If there was 1.409 + * already a value associated with this property, the old value is 1.410 + * replaced. 1.411 + * <p> 1.412 + * The valid property names include 1.413 + * {@link SOAPMessage#WRITE_XML_DECLARATION} and 1.414 + * {@link SOAPMessage#CHARACTER_SET_ENCODING}. All of these standard SAAJ 1.415 + * properties are prefixed by "javax.xml.soap". Vendors may also add 1.416 + * implementation specific properties. These properties must be prefixed 1.417 + * with package names that are unique to the vendor. 1.418 + * <p> 1.419 + * Setting the property <code>WRITE_XML_DECLARATION</code> to <code>"true"</code> 1.420 + * will cause an XML Declaration to be written out at the start of the SOAP 1.421 + * message. The default value of "false" suppresses this declaration. 1.422 + * <p> 1.423 + * The property <code>CHARACTER_SET_ENCODING</code> defaults to the value 1.424 + * <code>"utf-8"</code> which causes the SOAP message to be encoded using 1.425 + * UTF-8. Setting <code>CHARACTER_SET_ENCODING</code> to <code>"utf-16"</code> 1.426 + * causes the SOAP message to be encoded using UTF-16. 1.427 + * <p> 1.428 + * Some implementations may allow encodings in addition to UTF-8 and 1.429 + * UTF-16. Refer to your vendor's documentation for details. 1.430 + * 1.431 + * @param property 1.432 + * the property with which the specified value is to be 1.433 + * associated. 1.434 + * @param value 1.435 + * the value to be associated with the specified property 1.436 + * @exception SOAPException 1.437 + * if the property name is not recognized. 1.438 + * @since SAAJ 1.2 1.439 + */ 1.440 + public void setProperty(String property, Object value) 1.441 + throws SOAPException { 1.442 + throw new UnsupportedOperationException("setProperty must be overridden by all subclasses of SOAPMessage"); 1.443 + } 1.444 + 1.445 + /** 1.446 + * Retrieves value of the specified property. 1.447 + * 1.448 + * @param property 1.449 + * the name of the property to retrieve 1.450 + * @return the value associated with the named property or <code>null</code> 1.451 + * if no such property exists. 1.452 + * @exception SOAPException 1.453 + * if the property name is not recognized. 1.454 + * @since SAAJ 1.2 1.455 + */ 1.456 + public Object getProperty(String property) throws SOAPException { 1.457 + throw new UnsupportedOperationException("getProperty must be overridden by all subclasses of SOAPMessage"); 1.458 + } 1.459 +}