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