jdk8-mips64-public/jaxws: src/share/jaxws_classes/javax/xml/soap/SOAPMessage.java@b0610cd08440 (annotated)

src/share/jaxws_classes/javax/xml/soap/SOAPMessage.java@b0610cd08440 (annotated)

src/share/jaxws_classes/javax/xml/soap/SOAPMessage.java

Fri, 04 Oct 2013 16:21:34 +0100

author: mkos
date: Fri, 04 Oct 2013 16:21:34 +0100
changeset 408: b0610cd08440
parent 368: 0989ad8c0860
child 637: 9c07ef4934dd
permissions: -rw-r--r--

8025054: Update JAX-WS RI integration to 2.2.9-b130926.1035
Reviewed-by: chegar

 /*
  * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this
  * particular file as subject to the "Classpath" exception as provided
  * by Oracle in the LICENSE file that accompanied this code.
  *
  * This code is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  * version 2 for more details (a copy is included in the LICENSE file that
  * accompanied this code).
  *
  * You should have received a copy of the GNU General Public License version
  * 2 along with this work; if not, write to the Free Software Foundation,
  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  *
  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */
 package javax.xml.soap;
 import java.io.OutputStream;
 import java.io.IOException;
 import java.util.Iterator;
 import javax.activation.DataHandler;
 /**
  * The root class for all SOAP messages. As transmitted on the "wire", a SOAP
  * message is an XML document or a MIME message whose first body part is an
  * XML/SOAP document.
  * <P>
  * A <code>SOAPMessage</code> object consists of a SOAP part and optionally
  * one or more attachment parts. The SOAP part for a <code>SOAPMessage</code>
  * object is a <code>SOAPPart</code> object, which contains information used
  * for message routing and identification, and which can contain
  * application-specific content. All data in the SOAP Part of a message must be
  * in XML format.
  * <P>
  * A new <code>SOAPMessage</code> object contains the following by default:
  * <UL>
  *   <LI>A <code>SOAPPart</code> object
  *   <LI>A <code>SOAPEnvelope</code> object
  *   <LI>A <code>SOAPBody</code> object
  *   <LI>A <code>SOAPHeader</code> object
  * </UL>
  * The SOAP part of a message can be retrieved by calling the method <code>SOAPMessage.getSOAPPart()</code>.
  * The <code>SOAPEnvelope</code> object is retrieved from the <code>SOAPPart</code>
  * object, and the <code>SOAPEnvelope</code> object is used to retrieve the
  * <code>SOAPBody</code> and <code>SOAPHeader</code> objects.
  *
  * <PRE>
  *     SOAPPart sp = message.getSOAPPart();
  *     SOAPEnvelope se = sp.getEnvelope();
  *     SOAPBody sb = se.getBody();
  *     SOAPHeader sh = se.getHeader();
  * </PRE>
  *
  * <P>
  * In addition to the mandatory <code>SOAPPart</code> object, a <code>SOAPMessage</code>
  * object may contain zero or more <code>AttachmentPart</code> objects, each
  * of which contains application-specific data. The <code>SOAPMessage</code>
  * interface provides methods for creating <code>AttachmentPart</code>
  * objects and also for adding them to a <code>SOAPMessage</code> object. A
  * party that has received a <code>SOAPMessage</code> object can examine its
  * contents by retrieving individual attachment parts.
  * <P>
  * Unlike the rest of a SOAP message, an attachment is not required to be in
  * XML format and can therefore be anything from simple text to an image file.
  * Consequently, any message content that is not in XML format must be in an
  * <code>AttachmentPart</code> object.
  * <P>
  * A <code>MessageFactory</code> object may create <code>SOAPMessage</code>
  * objects with behavior that is specialized to a particular implementation or
  * application of SAAJ. For instance, a <code>MessageFactory</code> object
  * may produce <code>SOAPMessage</code> objects that conform to a particular
  * Profile such as ebXML. In this case a <code>MessageFactory</code> object
  * might produce <code>SOAPMessage</code> objects that are initialized with
  * ebXML headers.
  * <P>
  * In order to ensure backward source compatibility, methods that are added to
  * this class after version 1.1 of the SAAJ specification are all concrete
  * instead of abstract and they all have default implementations. Unless
  * otherwise noted in the JavaDocs for those methods the default
  * implementations simply throw an <code>UnsupportedOperationException</code>
  * and the SAAJ implementation code must override them with methods that
  * provide the specified behavior. Legacy client code does not have this
  * restriction, however, so long as there is no claim made that it conforms to
  * some later version of the specification than it was originally written for.
  * A legacy class that extends the SOAPMessage class can be compiled and/or run
  * against succeeding versions of the SAAJ API without modification. If such a
  * class was correctly implemented then it will continue to behave correctly
  * relative to the version of the specification against which it was written.
  *
  * @see MessageFactory
  * @see AttachmentPart
  */
 public abstract class SOAPMessage {
     /**
          * Specifies the character type encoding for the SOAP Message. Valid values
          * include "utf-8" and "utf-16". See vendor documentation for additional
          * supported values. The default is "utf-8".
          *
          * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty
          * @since SAAJ 1.2
          */
     public static final String CHARACTER_SET_ENCODING =
         "javax.xml.soap.character-set-encoding";
     /**
      * Specifies whether the SOAP Message will contain an XML declaration when
      * it is sent. The only valid values are "true" and "false". The default is
      * "false".
      *
      * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty
      * @since SAAJ 1.2
      */
     public static final String WRITE_XML_DECLARATION =
         "javax.xml.soap.write-xml-declaration";
     /**
      * Sets the description of this <code>SOAPMessage</code> object's
      * content with the given description.
      *
      * @param description a <code>String</code> describing the content of this
      *         message
      * @see #getContentDescription
      */
     public abstract void setContentDescription(String description);
     /**
      * Retrieves a description of this <code>SOAPMessage</code> object's
      * content.
      *
      * @return a <code>String</code> describing the content of this
      *         message or <code>null</code> if no description has been set
      * @see #setContentDescription
      */
     public abstract String getContentDescription();
     /**
          * Gets the SOAP part of this <code>SOAPMessage</code> object.
          * <P>
          * <code>SOAPMessage</code> object contains one or more attachments, the
          * SOAP Part must be the first MIME body part in the message.
          *
          * @return the <code>SOAPPart</code> object for this <code>SOAPMessage</code>
          *         object
          */
     public abstract SOAPPart getSOAPPart();
     /**
          * Gets the SOAP Body contained in this <code>SOAPMessage</code> object.
          * <p>
          *
          * @return the <code>SOAPBody</code> object contained by this <code>SOAPMessage</code>
          *         object
          * @exception SOAPException
          *               if the SOAP Body does not exist or cannot be retrieved
          * @since SAAJ 1.2
          */
     public SOAPBody getSOAPBody() throws SOAPException {
         throw new UnsupportedOperationException("getSOAPBody must be overridden by all subclasses of SOAPMessage");
     }
     /**
          * Gets the SOAP Header contained in this <code>SOAPMessage</code>
          * object.
          * <p>
          *
          * @return the <code>SOAPHeader</code> object contained by this <code>SOAPMessage</code>
          *         object
          * @exception SOAPException
          *               if the SOAP Header does not exist or cannot be retrieved
          * @since SAAJ 1.2
          */
     public SOAPHeader getSOAPHeader() throws SOAPException {
         throw new UnsupportedOperationException("getSOAPHeader must be overridden by all subclasses of SOAPMessage");
     }
     /**
          * Removes all <code>AttachmentPart</code> objects that have been added
          * to this <code>SOAPMessage</code> object.
          * <P>
          * This method does not touch the SOAP part.
          */
     public abstract void removeAllAttachments();
     /**
          * Gets a count of the number of attachments in this message. This count
          * does not include the SOAP part.
          *
          * @return the number of <code>AttachmentPart</code> objects that are
          *         part of this <code>SOAPMessage</code> object
          */
     public abstract int countAttachments();
     /**
          * Retrieves all the <code>AttachmentPart</code> objects that are part of
          * this <code>SOAPMessage</code> object.
          *
          * @return an iterator over all the attachments in this message
          */
     public abstract Iterator getAttachments();
     /**
          * Retrieves all the <code>AttachmentPart</code> objects that have header
          * entries that match the specified headers. Note that a returned
          * attachment could have headers in addition to those specified.
          *
          * @param headers
          *           a <code>MimeHeaders</code> object containing the MIME
          *           headers for which to search
          * @return an iterator over all attachments that have a header that matches
          *         one of the given headers
          */
     public abstract Iterator getAttachments(MimeHeaders headers);
     /**
      * Removes all the <code>AttachmentPart</code> objects that have header
      * entries that match the specified headers. Note that the removed
      * attachment could have headers in addition to those specified.
      *
      * @param headers
      *           a <code>MimeHeaders</code> object containing the MIME
      *           headers for which to search
      * @since SAAJ 1.3
      */
     public abstract void removeAttachments(MimeHeaders headers);
     /**
      * Returns an <code>AttachmentPart</code> object that is associated with an
      * attachment that is referenced by this <code>SOAPElement</code> or
      * <code>null</code> if no such attachment exists. References can be made
      * via an <code>href</code> attribute as described in
      * {@link <a href="http://www.w3.org/TR/SOAP-attachments#SOAPReferenceToAttachements">SOAP Messages with Attachments</a>},
      * or via a single <code>Text</code> child node containing a URI as
      * described in the WS-I Attachments Profile 1.0 for elements of schema
      * 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.
      * The support for references via <code>href</code> attribute also implies that
      * this method should also be supported on an element that is an
      * <i>xop:Include</i> element (
      * {@link <a  href="http://www.w3.org/2000/xp/Group/3/06/Attachments/XOP.html">XOP</a>}).
      * other reference mechanisms may be supported by individual
      * implementations of this standard. Contact your vendor for details.
      *
      * @param  element The <code>SOAPElement</code> containing the reference to an Attachment
      * @return the referenced <code>AttachmentPart</code> or null if no such
      *          <code>AttachmentPart</code> exists or no reference can be
      *          found in this <code>SOAPElement</code>.
      * @throws SOAPException if there is an error in the attempt to access the
      *          attachment
      *
      * @since SAAJ 1.3
      */
     public abstract AttachmentPart getAttachment(SOAPElement element) throws SOAPException;
     /**
      * Adds the given <code>AttachmentPart</code> object to this <code>SOAPMessage</code>
      * object. An <code>AttachmentPart</code> object must be created before
      * it can be added to a message.
      *
      * @param AttachmentPart
      *           an <code>AttachmentPart</code> object that is to become part
      *           of this <code>SOAPMessage</code> object
      * @exception IllegalArgumentException
      */
     public abstract void addAttachmentPart(AttachmentPart AttachmentPart);
     /**
      * Creates a new empty <code>AttachmentPart</code> object. Note that the
      * method <code>addAttachmentPart</code> must be called with this new
      * <code>AttachmentPart</code> object as the parameter in order for it to
      * become an attachment to this <code>SOAPMessage</code> object.
      *
      * @return a new <code>AttachmentPart</code> object that can be populated
      *         and added to this <code>SOAPMessage</code> object
      */
     public abstract AttachmentPart createAttachmentPart();
     /**
      * Creates an <code>AttachmentPart</code> object and populates it using
      * the given <code>DataHandler</code> object.
      *
      * @param dataHandler
      *           the <code>javax.activation.DataHandler</code> object that
      *           will generate the content for this <code>SOAPMessage</code>
      *           object
      * @return a new <code>AttachmentPart</code> object that contains data
      *         generated by the given <code>DataHandler</code> object
      * @exception IllegalArgumentException
      *               if there was a problem with the specified <code>DataHandler</code>
      *               object
      * @see javax.activation.DataHandler
      * @see javax.activation.DataContentHandler
      */
     public AttachmentPart createAttachmentPart(DataHandler dataHandler) {
         AttachmentPart attachment = createAttachmentPart();
         attachment.setDataHandler(dataHandler);
         return attachment;
     }
     /**
      * Returns all the transport-specific MIME headers for this <code>SOAPMessage</code>
      * object in a transport-independent fashion.
      *
      * @return a <code>MimeHeaders</code> object containing the <code>MimeHeader</code>
      *         objects
      */
     public abstract MimeHeaders getMimeHeaders();
     /**
      * Creates an <code>AttachmentPart</code> object and populates it with
      * the specified data of the specified content type. The type of the
      * <code>Object</code> should correspond to the value given for the
      * <code>Content-Type</code>.
      *
      * @param content
      *           an <code>Object</code> containing the content for the
      *           <code>AttachmentPart</code> object to be created
      * @param contentType
      *           a <code>String</code> object giving the type of content;
      *           examples are "text/xml", "text/plain", and "image/jpeg"
      * @return a new <code>AttachmentPart</code> object that contains the
      *         given data
      * @exception IllegalArgumentException
      *               may be thrown if the contentType does not match the type
      *               of the content object, or if there was no
      *               <code>DataContentHandler</code> object for the given
      *               content object
      * @see javax.activation.DataHandler
      * @see javax.activation.DataContentHandler
      */
     public AttachmentPart createAttachmentPart(
         Object content,
         String contentType) {
         AttachmentPart attachment = createAttachmentPart();
         attachment.setContent(content, contentType);
         return attachment;
     }
     /**
      * Updates this <code>SOAPMessage</code> object with all the changes that
      * have been made to it. This method is called automatically when
      * {@link SOAPMessage#writeTo(OutputStream)} is  called. However, if
      * changes are made to a message that was received or to one that has
      * already been sent, the method <code>saveChanges</code> needs to be
      * called explicitly in order to save the changes. The method <code>saveChanges</code>
      * also generates any changes that can be read back (for example, a
      * MessageId in profiles that support a message id). All MIME headers in a
      * message that is created for sending purposes are guaranteed to have
      * valid values only after <code>saveChanges</code> has been called.
      * <P>
      * In addition, this method marks the point at which the data from all
      * constituent <code>AttachmentPart</code> objects are pulled into the
      * message.
      * <P>
      *
      * @exception <code>SOAPException</code> if there was a problem saving
      *               changes to this message.
      */
     public abstract void saveChanges() throws SOAPException;
     /**
      * Indicates whether this <code>SOAPMessage</code> object needs to have
      * the method <code>saveChanges</code> called on it.
      *
      * @return <code>true</code> if <code>saveChanges</code> needs to be
      *         called; <code>false</code> otherwise.
      */
     public abstract boolean saveRequired();
     /**
      * Writes this <code>SOAPMessage</code> object to the given output
      * stream. The externalization format is as defined by the SOAP 1.1 with
      * Attachments specification.
      * <P>
      * If there are no attachments, just an XML stream is written out. For
      * those messages that have attachments, <code>writeTo</code> writes a
      * MIME-encoded byte stream.
      * <P>
      * Note that this method does not write the transport-specific MIME Headers
      * of the Message
      *
      * @param out
      *           the <code>OutputStream</code> object to which this <code>SOAPMessage</code>
      *           object will be written
      * @exception IOException
      *               if an I/O error occurs
      * @exception SOAPException
      *               if there was a problem in externalizing this SOAP message
      */
     public abstract void writeTo(OutputStream out)
         throws SOAPException, IOException;
     /**
      * Associates the specified value with the specified property. If there was
      * already a value associated with this property, the old value is
      * replaced.
      * <p>
      * The valid property names include
      * {@link SOAPMessage#WRITE_XML_DECLARATION}  and
      * {@link SOAPMessage#CHARACTER_SET_ENCODING}. All of these standard SAAJ
      * properties are prefixed by "javax.xml.soap". Vendors may also add
      * implementation specific properties. These properties must be prefixed
      * with package names that are unique to the vendor.
      * <p>
      * Setting the property <code>WRITE_XML_DECLARATION</code> to <code>"true"</code>
      * will cause an XML Declaration to be written out at the start of the SOAP
      * message. The default value of "false" suppresses this declaration.
      * <p>
      * The property <code>CHARACTER_SET_ENCODING</code> defaults to the value
      * <code>"utf-8"</code> which causes the SOAP message to be encoded using
      * UTF-8. Setting <code>CHARACTER_SET_ENCODING</code> to <code>"utf-16"</code>
      * causes the SOAP message to be encoded using UTF-16.
      * <p>
      * Some implementations may allow encodings in addition to UTF-8 and
      * UTF-16. Refer to your vendor's documentation for details.
      *
      * @param property
      *           the property with which the specified value is to be
      *           associated.
      * @param value
      *           the value to be associated with the specified property
      * @exception SOAPException
      *               if the property name is not recognized.
      * @since SAAJ 1.2
      */
     public void setProperty(String property, Object value)
         throws SOAPException {
             throw new UnsupportedOperationException("setProperty must be overridden by all subclasses of SOAPMessage");
     }
     /**
      * Retrieves value of the specified property.
      *
      * @param property
      *           the name of the property to retrieve
      * @return the value associated with the named property or <code>null</code>
      *         if no such property exists.
      * @exception SOAPException
      *               if the property name is not recognized.
      * @since SAAJ 1.2
      */
     public Object getProperty(String property) throws SOAPException {
         throw new UnsupportedOperationException("getProperty must be overridden by all subclasses of SOAPMessage");
     }
 }

Mercurial > jdk8-mips64-public > jaxws / annotate

src/share/jaxws_classes/javax/xml/soap/SOAPMessage.java@b0610cd08440 (annotated)

src/share/jaxws_classes/javax/xml/soap/SOAPMessage.java