Thu, 31 Aug 2017 15:18:52 +0800
merge
aoqi@0 | 1 | /* |
aoqi@0 | 2 | * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved. |
aoqi@0 | 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
aoqi@0 | 4 | * |
aoqi@0 | 5 | * This code is free software; you can redistribute it and/or modify it |
aoqi@0 | 6 | * under the terms of the GNU General Public License version 2 only, as |
aoqi@0 | 7 | * published by the Free Software Foundation. Oracle designates this |
aoqi@0 | 8 | * particular file as subject to the "Classpath" exception as provided |
aoqi@0 | 9 | * by Oracle in the LICENSE file that accompanied this code. |
aoqi@0 | 10 | * |
aoqi@0 | 11 | * This code is distributed in the hope that it will be useful, but WITHOUT |
aoqi@0 | 12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
aoqi@0 | 13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
aoqi@0 | 14 | * version 2 for more details (a copy is included in the LICENSE file that |
aoqi@0 | 15 | * accompanied this code). |
aoqi@0 | 16 | * |
aoqi@0 | 17 | * You should have received a copy of the GNU General Public License version |
aoqi@0 | 18 | * 2 along with this work; if not, write to the Free Software Foundation, |
aoqi@0 | 19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
aoqi@0 | 20 | * |
aoqi@0 | 21 | * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
aoqi@0 | 22 | * or visit www.oracle.com if you need additional information or have any |
aoqi@0 | 23 | * questions. |
aoqi@0 | 24 | */ |
aoqi@0 | 25 | |
aoqi@0 | 26 | package javax.xml.soap; |
aoqi@0 | 27 | import java.io.OutputStream; |
aoqi@0 | 28 | import java.io.IOException; |
aoqi@0 | 29 | |
aoqi@0 | 30 | import java.util.Iterator; |
aoqi@0 | 31 | |
aoqi@0 | 32 | import javax.activation.DataHandler; |
aoqi@0 | 33 | |
aoqi@0 | 34 | /** |
aoqi@0 | 35 | * The root class for all SOAP messages. As transmitted on the "wire", a SOAP |
aoqi@0 | 36 | * message is an XML document or a MIME message whose first body part is an |
aoqi@0 | 37 | * XML/SOAP document. |
aoqi@0 | 38 | * <P> |
aoqi@0 | 39 | * A <code>SOAPMessage</code> object consists of a SOAP part and optionally |
aoqi@0 | 40 | * one or more attachment parts. The SOAP part for a <code>SOAPMessage</code> |
aoqi@0 | 41 | * object is a <code>SOAPPart</code> object, which contains information used |
aoqi@0 | 42 | * for message routing and identification, and which can contain |
aoqi@0 | 43 | * application-specific content. All data in the SOAP Part of a message must be |
aoqi@0 | 44 | * in XML format. |
aoqi@0 | 45 | * <P> |
aoqi@0 | 46 | * A new <code>SOAPMessage</code> object contains the following by default: |
aoqi@0 | 47 | * <UL> |
aoqi@0 | 48 | * <LI>A <code>SOAPPart</code> object |
aoqi@0 | 49 | * <LI>A <code>SOAPEnvelope</code> object |
aoqi@0 | 50 | * <LI>A <code>SOAPBody</code> object |
aoqi@0 | 51 | * <LI>A <code>SOAPHeader</code> object |
aoqi@0 | 52 | * </UL> |
aoqi@0 | 53 | * The SOAP part of a message can be retrieved by calling the method <code>SOAPMessage.getSOAPPart()</code>. |
aoqi@0 | 54 | * The <code>SOAPEnvelope</code> object is retrieved from the <code>SOAPPart</code> |
aoqi@0 | 55 | * object, and the <code>SOAPEnvelope</code> object is used to retrieve the |
aoqi@0 | 56 | * <code>SOAPBody</code> and <code>SOAPHeader</code> objects. |
aoqi@0 | 57 | * |
aoqi@0 | 58 | * <PRE> |
aoqi@0 | 59 | * SOAPPart sp = message.getSOAPPart(); |
aoqi@0 | 60 | * SOAPEnvelope se = sp.getEnvelope(); |
aoqi@0 | 61 | * SOAPBody sb = se.getBody(); |
aoqi@0 | 62 | * SOAPHeader sh = se.getHeader(); |
aoqi@0 | 63 | * </PRE> |
aoqi@0 | 64 | * |
aoqi@0 | 65 | * <P> |
aoqi@0 | 66 | * In addition to the mandatory <code>SOAPPart</code> object, a <code>SOAPMessage</code> |
aoqi@0 | 67 | * object may contain zero or more <code>AttachmentPart</code> objects, each |
aoqi@0 | 68 | * of which contains application-specific data. The <code>SOAPMessage</code> |
aoqi@0 | 69 | * interface provides methods for creating <code>AttachmentPart</code> |
aoqi@0 | 70 | * objects and also for adding them to a <code>SOAPMessage</code> object. A |
aoqi@0 | 71 | * party that has received a <code>SOAPMessage</code> object can examine its |
aoqi@0 | 72 | * contents by retrieving individual attachment parts. |
aoqi@0 | 73 | * <P> |
aoqi@0 | 74 | * Unlike the rest of a SOAP message, an attachment is not required to be in |
aoqi@0 | 75 | * XML format and can therefore be anything from simple text to an image file. |
aoqi@0 | 76 | * Consequently, any message content that is not in XML format must be in an |
aoqi@0 | 77 | * <code>AttachmentPart</code> object. |
aoqi@0 | 78 | * <P> |
aoqi@0 | 79 | * A <code>MessageFactory</code> object may create <code>SOAPMessage</code> |
aoqi@0 | 80 | * objects with behavior that is specialized to a particular implementation or |
aoqi@0 | 81 | * application of SAAJ. For instance, a <code>MessageFactory</code> object |
aoqi@0 | 82 | * may produce <code>SOAPMessage</code> objects that conform to a particular |
aoqi@0 | 83 | * Profile such as ebXML. In this case a <code>MessageFactory</code> object |
aoqi@0 | 84 | * might produce <code>SOAPMessage</code> objects that are initialized with |
aoqi@0 | 85 | * ebXML headers. |
aoqi@0 | 86 | * <P> |
aoqi@0 | 87 | * In order to ensure backward source compatibility, methods that are added to |
aoqi@0 | 88 | * this class after version 1.1 of the SAAJ specification are all concrete |
aoqi@0 | 89 | * instead of abstract and they all have default implementations. Unless |
aoqi@0 | 90 | * otherwise noted in the JavaDocs for those methods the default |
aoqi@0 | 91 | * implementations simply throw an <code>UnsupportedOperationException</code> |
aoqi@0 | 92 | * and the SAAJ implementation code must override them with methods that |
aoqi@0 | 93 | * provide the specified behavior. Legacy client code does not have this |
aoqi@0 | 94 | * restriction, however, so long as there is no claim made that it conforms to |
aoqi@0 | 95 | * some later version of the specification than it was originally written for. |
aoqi@0 | 96 | * A legacy class that extends the SOAPMessage class can be compiled and/or run |
aoqi@0 | 97 | * against succeeding versions of the SAAJ API without modification. If such a |
aoqi@0 | 98 | * class was correctly implemented then it will continue to behave correctly |
aoqi@0 | 99 | * relative to the version of the specification against which it was written. |
aoqi@0 | 100 | * |
aoqi@0 | 101 | * @see MessageFactory |
aoqi@0 | 102 | * @see AttachmentPart |
aoqi@0 | 103 | */ |
aoqi@0 | 104 | public abstract class SOAPMessage { |
aoqi@0 | 105 | /** |
aoqi@0 | 106 | * Specifies the character type encoding for the SOAP Message. Valid values |
aoqi@0 | 107 | * include "utf-8" and "utf-16". See vendor documentation for additional |
aoqi@0 | 108 | * supported values. The default is "utf-8". |
aoqi@0 | 109 | * |
aoqi@0 | 110 | * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty |
aoqi@0 | 111 | * @since SAAJ 1.2 |
aoqi@0 | 112 | */ |
aoqi@0 | 113 | public static final String CHARACTER_SET_ENCODING = |
aoqi@0 | 114 | "javax.xml.soap.character-set-encoding"; |
aoqi@0 | 115 | |
aoqi@0 | 116 | /** |
aoqi@0 | 117 | * Specifies whether the SOAP Message will contain an XML declaration when |
aoqi@0 | 118 | * it is sent. The only valid values are "true" and "false". The default is |
aoqi@0 | 119 | * "false". |
aoqi@0 | 120 | * |
aoqi@0 | 121 | * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty |
aoqi@0 | 122 | * @since SAAJ 1.2 |
aoqi@0 | 123 | */ |
aoqi@0 | 124 | public static final String WRITE_XML_DECLARATION = |
aoqi@0 | 125 | "javax.xml.soap.write-xml-declaration"; |
aoqi@0 | 126 | |
aoqi@0 | 127 | /** |
aoqi@0 | 128 | * Sets the description of this <code>SOAPMessage</code> object's |
aoqi@0 | 129 | * content with the given description. |
aoqi@0 | 130 | * |
aoqi@0 | 131 | * @param description a <code>String</code> describing the content of this |
aoqi@0 | 132 | * message |
aoqi@0 | 133 | * @see #getContentDescription |
aoqi@0 | 134 | */ |
aoqi@0 | 135 | public abstract void setContentDescription(String description); |
aoqi@0 | 136 | |
aoqi@0 | 137 | /** |
aoqi@0 | 138 | * Retrieves a description of this <code>SOAPMessage</code> object's |
aoqi@0 | 139 | * content. |
aoqi@0 | 140 | * |
aoqi@0 | 141 | * @return a <code>String</code> describing the content of this |
aoqi@0 | 142 | * message or <code>null</code> if no description has been set |
aoqi@0 | 143 | * @see #setContentDescription |
aoqi@0 | 144 | */ |
aoqi@0 | 145 | public abstract String getContentDescription(); |
aoqi@0 | 146 | |
aoqi@0 | 147 | /** |
aoqi@0 | 148 | * Gets the SOAP part of this <code>SOAPMessage</code> object. |
aoqi@0 | 149 | * <P> |
aoqi@0 | 150 | * <code>SOAPMessage</code> object contains one or more attachments, the |
aoqi@0 | 151 | * SOAP Part must be the first MIME body part in the message. |
aoqi@0 | 152 | * |
aoqi@0 | 153 | * @return the <code>SOAPPart</code> object for this <code>SOAPMessage</code> |
aoqi@0 | 154 | * object |
aoqi@0 | 155 | */ |
aoqi@0 | 156 | public abstract SOAPPart getSOAPPart(); |
aoqi@0 | 157 | |
aoqi@0 | 158 | /** |
aoqi@0 | 159 | * Gets the SOAP Body contained in this <code>SOAPMessage</code> object. |
aoqi@0 | 160 | * <p> |
aoqi@0 | 161 | * |
aoqi@0 | 162 | * @return the <code>SOAPBody</code> object contained by this <code>SOAPMessage</code> |
aoqi@0 | 163 | * object |
aoqi@0 | 164 | * @exception SOAPException |
aoqi@0 | 165 | * if the SOAP Body does not exist or cannot be retrieved |
aoqi@0 | 166 | * @since SAAJ 1.2 |
aoqi@0 | 167 | */ |
aoqi@0 | 168 | public SOAPBody getSOAPBody() throws SOAPException { |
aoqi@0 | 169 | throw new UnsupportedOperationException("getSOAPBody must be overridden by all subclasses of SOAPMessage"); |
aoqi@0 | 170 | } |
aoqi@0 | 171 | |
aoqi@0 | 172 | /** |
aoqi@0 | 173 | * Gets the SOAP Header contained in this <code>SOAPMessage</code> |
aoqi@0 | 174 | * object. |
aoqi@0 | 175 | * <p> |
aoqi@0 | 176 | * |
aoqi@0 | 177 | * @return the <code>SOAPHeader</code> object contained by this <code>SOAPMessage</code> |
aoqi@0 | 178 | * object |
aoqi@0 | 179 | * @exception SOAPException |
aoqi@0 | 180 | * if the SOAP Header does not exist or cannot be retrieved |
aoqi@0 | 181 | * @since SAAJ 1.2 |
aoqi@0 | 182 | */ |
aoqi@0 | 183 | public SOAPHeader getSOAPHeader() throws SOAPException { |
aoqi@0 | 184 | throw new UnsupportedOperationException("getSOAPHeader must be overridden by all subclasses of SOAPMessage"); |
aoqi@0 | 185 | } |
aoqi@0 | 186 | |
aoqi@0 | 187 | /** |
aoqi@0 | 188 | * Removes all <code>AttachmentPart</code> objects that have been added |
aoqi@0 | 189 | * to this <code>SOAPMessage</code> object. |
aoqi@0 | 190 | * <P> |
aoqi@0 | 191 | * This method does not touch the SOAP part. |
aoqi@0 | 192 | */ |
aoqi@0 | 193 | public abstract void removeAllAttachments(); |
aoqi@0 | 194 | |
aoqi@0 | 195 | /** |
aoqi@0 | 196 | * Gets a count of the number of attachments in this message. This count |
aoqi@0 | 197 | * does not include the SOAP part. |
aoqi@0 | 198 | * |
aoqi@0 | 199 | * @return the number of <code>AttachmentPart</code> objects that are |
aoqi@0 | 200 | * part of this <code>SOAPMessage</code> object |
aoqi@0 | 201 | */ |
aoqi@0 | 202 | public abstract int countAttachments(); |
aoqi@0 | 203 | |
aoqi@0 | 204 | /** |
aoqi@0 | 205 | * Retrieves all the <code>AttachmentPart</code> objects that are part of |
aoqi@0 | 206 | * this <code>SOAPMessage</code> object. |
aoqi@0 | 207 | * |
aoqi@0 | 208 | * @return an iterator over all the attachments in this message |
aoqi@0 | 209 | */ |
aoqi@0 | 210 | public abstract Iterator getAttachments(); |
aoqi@0 | 211 | |
aoqi@0 | 212 | /** |
aoqi@0 | 213 | * Retrieves all the <code>AttachmentPart</code> objects that have header |
aoqi@0 | 214 | * entries that match the specified headers. Note that a returned |
aoqi@0 | 215 | * attachment could have headers in addition to those specified. |
aoqi@0 | 216 | * |
aoqi@0 | 217 | * @param headers |
aoqi@0 | 218 | * a <code>MimeHeaders</code> object containing the MIME |
aoqi@0 | 219 | * headers for which to search |
aoqi@0 | 220 | * @return an iterator over all attachments that have a header that matches |
aoqi@0 | 221 | * one of the given headers |
aoqi@0 | 222 | */ |
aoqi@0 | 223 | public abstract Iterator getAttachments(MimeHeaders headers); |
aoqi@0 | 224 | |
aoqi@0 | 225 | /** |
aoqi@0 | 226 | * Removes all the <code>AttachmentPart</code> objects that have header |
aoqi@0 | 227 | * entries that match the specified headers. Note that the removed |
aoqi@0 | 228 | * attachment could have headers in addition to those specified. |
aoqi@0 | 229 | * |
aoqi@0 | 230 | * @param headers |
aoqi@0 | 231 | * a <code>MimeHeaders</code> object containing the MIME |
aoqi@0 | 232 | * headers for which to search |
aoqi@0 | 233 | * @since SAAJ 1.3 |
aoqi@0 | 234 | */ |
aoqi@0 | 235 | public abstract void removeAttachments(MimeHeaders headers); |
aoqi@0 | 236 | |
aoqi@0 | 237 | |
aoqi@0 | 238 | /** |
aoqi@0 | 239 | * Returns an <code>AttachmentPart</code> object that is associated with an |
aoqi@0 | 240 | * attachment that is referenced by this <code>SOAPElement</code> or |
aoqi@0 | 241 | * <code>null</code> if no such attachment exists. References can be made |
aoqi@0 | 242 | * via an <code>href</code> attribute as described in |
aoqi@0 | 243 | * {@link <a href="http://www.w3.org/TR/SOAP-attachments#SOAPReferenceToAttachements">SOAP Messages with Attachments</a>}, |
aoqi@0 | 244 | * or via a single <code>Text</code> child node containing a URI as |
aoqi@0 | 245 | * described in the WS-I Attachments Profile 1.0 for elements of schema |
aoqi@0 | 246 | * 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. |
aoqi@0 | 247 | * The support for references via <code>href</code> attribute also implies that |
aoqi@0 | 248 | * this method should also be supported on an element that is an |
aoqi@0 | 249 | * <i>xop:Include</i> element ( |
aoqi@0 | 250 | * {@link <a href="http://www.w3.org/2000/xp/Group/3/06/Attachments/XOP.html">XOP</a>}). |
aoqi@0 | 251 | * other reference mechanisms may be supported by individual |
aoqi@0 | 252 | * implementations of this standard. Contact your vendor for details. |
aoqi@0 | 253 | * |
aoqi@0 | 254 | * @param element The <code>SOAPElement</code> containing the reference to an Attachment |
aoqi@0 | 255 | * @return the referenced <code>AttachmentPart</code> or null if no such |
aoqi@0 | 256 | * <code>AttachmentPart</code> exists or no reference can be |
aoqi@0 | 257 | * found in this <code>SOAPElement</code>. |
aoqi@0 | 258 | * @throws SOAPException if there is an error in the attempt to access the |
aoqi@0 | 259 | * attachment |
aoqi@0 | 260 | * |
aoqi@0 | 261 | * @since SAAJ 1.3 |
aoqi@0 | 262 | */ |
aoqi@0 | 263 | public abstract AttachmentPart getAttachment(SOAPElement element) throws SOAPException; |
aoqi@0 | 264 | |
aoqi@0 | 265 | |
aoqi@0 | 266 | /** |
aoqi@0 | 267 | * Adds the given <code>AttachmentPart</code> object to this <code>SOAPMessage</code> |
aoqi@0 | 268 | * object. An <code>AttachmentPart</code> object must be created before |
aoqi@0 | 269 | * it can be added to a message. |
aoqi@0 | 270 | * |
aoqi@0 | 271 | * @param AttachmentPart |
aoqi@0 | 272 | * an <code>AttachmentPart</code> object that is to become part |
aoqi@0 | 273 | * of this <code>SOAPMessage</code> object |
aoqi@0 | 274 | * @exception IllegalArgumentException |
aoqi@0 | 275 | */ |
aoqi@0 | 276 | public abstract void addAttachmentPart(AttachmentPart AttachmentPart); |
aoqi@0 | 277 | |
aoqi@0 | 278 | /** |
aoqi@0 | 279 | * Creates a new empty <code>AttachmentPart</code> object. Note that the |
aoqi@0 | 280 | * method <code>addAttachmentPart</code> must be called with this new |
aoqi@0 | 281 | * <code>AttachmentPart</code> object as the parameter in order for it to |
aoqi@0 | 282 | * become an attachment to this <code>SOAPMessage</code> object. |
aoqi@0 | 283 | * |
aoqi@0 | 284 | * @return a new <code>AttachmentPart</code> object that can be populated |
aoqi@0 | 285 | * and added to this <code>SOAPMessage</code> object |
aoqi@0 | 286 | */ |
aoqi@0 | 287 | public abstract AttachmentPart createAttachmentPart(); |
aoqi@0 | 288 | |
aoqi@0 | 289 | /** |
aoqi@0 | 290 | * Creates an <code>AttachmentPart</code> object and populates it using |
aoqi@0 | 291 | * the given <code>DataHandler</code> object. |
aoqi@0 | 292 | * |
aoqi@0 | 293 | * @param dataHandler |
aoqi@0 | 294 | * the <code>javax.activation.DataHandler</code> object that |
aoqi@0 | 295 | * will generate the content for this <code>SOAPMessage</code> |
aoqi@0 | 296 | * object |
aoqi@0 | 297 | * @return a new <code>AttachmentPart</code> object that contains data |
aoqi@0 | 298 | * generated by the given <code>DataHandler</code> object |
aoqi@0 | 299 | * @exception IllegalArgumentException |
aoqi@0 | 300 | * if there was a problem with the specified <code>DataHandler</code> |
aoqi@0 | 301 | * object |
aoqi@0 | 302 | * @see javax.activation.DataHandler |
aoqi@0 | 303 | * @see javax.activation.DataContentHandler |
aoqi@0 | 304 | */ |
aoqi@0 | 305 | public AttachmentPart createAttachmentPart(DataHandler dataHandler) { |
aoqi@0 | 306 | AttachmentPart attachment = createAttachmentPart(); |
aoqi@0 | 307 | attachment.setDataHandler(dataHandler); |
aoqi@0 | 308 | return attachment; |
aoqi@0 | 309 | } |
aoqi@0 | 310 | |
aoqi@0 | 311 | /** |
aoqi@0 | 312 | * Returns all the transport-specific MIME headers for this <code>SOAPMessage</code> |
aoqi@0 | 313 | * object in a transport-independent fashion. |
aoqi@0 | 314 | * |
aoqi@0 | 315 | * @return a <code>MimeHeaders</code> object containing the <code>MimeHeader</code> |
aoqi@0 | 316 | * objects |
aoqi@0 | 317 | */ |
aoqi@0 | 318 | public abstract MimeHeaders getMimeHeaders(); |
aoqi@0 | 319 | |
aoqi@0 | 320 | /** |
aoqi@0 | 321 | * Creates an <code>AttachmentPart</code> object and populates it with |
aoqi@0 | 322 | * the specified data of the specified content type. The type of the |
aoqi@0 | 323 | * <code>Object</code> should correspond to the value given for the |
aoqi@0 | 324 | * <code>Content-Type</code>. |
aoqi@0 | 325 | * |
aoqi@0 | 326 | * @param content |
aoqi@0 | 327 | * an <code>Object</code> containing the content for the |
aoqi@0 | 328 | * <code>AttachmentPart</code> object to be created |
aoqi@0 | 329 | * @param contentType |
aoqi@0 | 330 | * a <code>String</code> object giving the type of content; |
aoqi@0 | 331 | * examples are "text/xml", "text/plain", and "image/jpeg" |
aoqi@0 | 332 | * @return a new <code>AttachmentPart</code> object that contains the |
aoqi@0 | 333 | * given data |
aoqi@0 | 334 | * @exception IllegalArgumentException |
aoqi@0 | 335 | * may be thrown if the contentType does not match the type |
aoqi@0 | 336 | * of the content object, or if there was no |
aoqi@0 | 337 | * <code>DataContentHandler</code> object for the given |
aoqi@0 | 338 | * content object |
aoqi@0 | 339 | * @see javax.activation.DataHandler |
aoqi@0 | 340 | * @see javax.activation.DataContentHandler |
aoqi@0 | 341 | */ |
aoqi@0 | 342 | public AttachmentPart createAttachmentPart( |
aoqi@0 | 343 | Object content, |
aoqi@0 | 344 | String contentType) { |
aoqi@0 | 345 | AttachmentPart attachment = createAttachmentPart(); |
aoqi@0 | 346 | attachment.setContent(content, contentType); |
aoqi@0 | 347 | return attachment; |
aoqi@0 | 348 | } |
aoqi@0 | 349 | |
aoqi@0 | 350 | /** |
aoqi@0 | 351 | * Updates this <code>SOAPMessage</code> object with all the changes that |
aoqi@0 | 352 | * have been made to it. This method is called automatically when |
aoqi@0 | 353 | * {@link SOAPMessage#writeTo(OutputStream)} is called. However, if |
aoqi@0 | 354 | * changes are made to a message that was received or to one that has |
aoqi@0 | 355 | * already been sent, the method <code>saveChanges</code> needs to be |
aoqi@0 | 356 | * called explicitly in order to save the changes. The method <code>saveChanges</code> |
aoqi@0 | 357 | * also generates any changes that can be read back (for example, a |
aoqi@0 | 358 | * MessageId in profiles that support a message id). All MIME headers in a |
aoqi@0 | 359 | * message that is created for sending purposes are guaranteed to have |
aoqi@0 | 360 | * valid values only after <code>saveChanges</code> has been called. |
aoqi@0 | 361 | * <P> |
aoqi@0 | 362 | * In addition, this method marks the point at which the data from all |
aoqi@0 | 363 | * constituent <code>AttachmentPart</code> objects are pulled into the |
aoqi@0 | 364 | * message. |
aoqi@0 | 365 | * <P> |
aoqi@0 | 366 | * |
aoqi@0 | 367 | * @exception <code>SOAPException</code> if there was a problem saving |
aoqi@0 | 368 | * changes to this message. |
aoqi@0 | 369 | */ |
aoqi@0 | 370 | public abstract void saveChanges() throws SOAPException; |
aoqi@0 | 371 | |
aoqi@0 | 372 | /** |
aoqi@0 | 373 | * Indicates whether this <code>SOAPMessage</code> object needs to have |
aoqi@0 | 374 | * the method <code>saveChanges</code> called on it. |
aoqi@0 | 375 | * |
aoqi@0 | 376 | * @return <code>true</code> if <code>saveChanges</code> needs to be |
aoqi@0 | 377 | * called; <code>false</code> otherwise. |
aoqi@0 | 378 | */ |
aoqi@0 | 379 | public abstract boolean saveRequired(); |
aoqi@0 | 380 | |
aoqi@0 | 381 | /** |
aoqi@0 | 382 | * Writes this <code>SOAPMessage</code> object to the given output |
aoqi@0 | 383 | * stream. The externalization format is as defined by the SOAP 1.1 with |
aoqi@0 | 384 | * Attachments specification. |
aoqi@0 | 385 | * <P> |
aoqi@0 | 386 | * If there are no attachments, just an XML stream is written out. For |
aoqi@0 | 387 | * those messages that have attachments, <code>writeTo</code> writes a |
aoqi@0 | 388 | * MIME-encoded byte stream. |
aoqi@0 | 389 | * <P> |
aoqi@0 | 390 | * Note that this method does not write the transport-specific MIME Headers |
aoqi@0 | 391 | * of the Message |
aoqi@0 | 392 | * |
aoqi@0 | 393 | * @param out |
aoqi@0 | 394 | * the <code>OutputStream</code> object to which this <code>SOAPMessage</code> |
aoqi@0 | 395 | * object will be written |
aoqi@0 | 396 | * @exception IOException |
aoqi@0 | 397 | * if an I/O error occurs |
aoqi@0 | 398 | * @exception SOAPException |
aoqi@0 | 399 | * if there was a problem in externalizing this SOAP message |
aoqi@0 | 400 | */ |
aoqi@0 | 401 | public abstract void writeTo(OutputStream out) |
aoqi@0 | 402 | throws SOAPException, IOException; |
aoqi@0 | 403 | |
aoqi@0 | 404 | /** |
aoqi@0 | 405 | * Associates the specified value with the specified property. If there was |
aoqi@0 | 406 | * already a value associated with this property, the old value is |
aoqi@0 | 407 | * replaced. |
aoqi@0 | 408 | * <p> |
aoqi@0 | 409 | * The valid property names include |
aoqi@0 | 410 | * {@link SOAPMessage#WRITE_XML_DECLARATION} and |
aoqi@0 | 411 | * {@link SOAPMessage#CHARACTER_SET_ENCODING}. All of these standard SAAJ |
aoqi@0 | 412 | * properties are prefixed by "javax.xml.soap". Vendors may also add |
aoqi@0 | 413 | * implementation specific properties. These properties must be prefixed |
aoqi@0 | 414 | * with package names that are unique to the vendor. |
aoqi@0 | 415 | * <p> |
aoqi@0 | 416 | * Setting the property <code>WRITE_XML_DECLARATION</code> to <code>"true"</code> |
aoqi@0 | 417 | * will cause an XML Declaration to be written out at the start of the SOAP |
aoqi@0 | 418 | * message. The default value of "false" suppresses this declaration. |
aoqi@0 | 419 | * <p> |
aoqi@0 | 420 | * The property <code>CHARACTER_SET_ENCODING</code> defaults to the value |
aoqi@0 | 421 | * <code>"utf-8"</code> which causes the SOAP message to be encoded using |
aoqi@0 | 422 | * UTF-8. Setting <code>CHARACTER_SET_ENCODING</code> to <code>"utf-16"</code> |
aoqi@0 | 423 | * causes the SOAP message to be encoded using UTF-16. |
aoqi@0 | 424 | * <p> |
aoqi@0 | 425 | * Some implementations may allow encodings in addition to UTF-8 and |
aoqi@0 | 426 | * UTF-16. Refer to your vendor's documentation for details. |
aoqi@0 | 427 | * |
aoqi@0 | 428 | * @param property |
aoqi@0 | 429 | * the property with which the specified value is to be |
aoqi@0 | 430 | * associated. |
aoqi@0 | 431 | * @param value |
aoqi@0 | 432 | * the value to be associated with the specified property |
aoqi@0 | 433 | * @exception SOAPException |
aoqi@0 | 434 | * if the property name is not recognized. |
aoqi@0 | 435 | * @since SAAJ 1.2 |
aoqi@0 | 436 | */ |
aoqi@0 | 437 | public void setProperty(String property, Object value) |
aoqi@0 | 438 | throws SOAPException { |
aoqi@0 | 439 | throw new UnsupportedOperationException("setProperty must be overridden by all subclasses of SOAPMessage"); |
aoqi@0 | 440 | } |
aoqi@0 | 441 | |
aoqi@0 | 442 | /** |
aoqi@0 | 443 | * Retrieves value of the specified property. |
aoqi@0 | 444 | * |
aoqi@0 | 445 | * @param property |
aoqi@0 | 446 | * the name of the property to retrieve |
aoqi@0 | 447 | * @return the value associated with the named property or <code>null</code> |
aoqi@0 | 448 | * if no such property exists. |
aoqi@0 | 449 | * @exception SOAPException |
aoqi@0 | 450 | * if the property name is not recognized. |
aoqi@0 | 451 | * @since SAAJ 1.2 |
aoqi@0 | 452 | */ |
aoqi@0 | 453 | public Object getProperty(String property) throws SOAPException { |
aoqi@0 | 454 | throw new UnsupportedOperationException("getProperty must be overridden by all subclasses of SOAPMessage"); |
aoqi@0 | 455 | } |
aoqi@0 | 456 | } |