< prev index next >

src/java.xml.ws/share/classes/javax/xml/soap/SOAPMessage.java

Print this page


   1 /*
   2  * Copyright (c) 2004, 2013, 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


  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>
  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


  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          * Specifies the character type encoding for the SOAP Message. Valid values
 108          * include "utf-8" and "utf-16". See vendor documentation for additional
 109          * supported values. The default is "utf-8".
 110          *
 111          * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty
 112          * @since 1.6, SAAJ 1.2
 113          */
 114     public static final String CHARACTER_SET_ENCODING =
 115         "javax.xml.soap.character-set-encoding";
 116 
 117     /**
 118      * Specifies whether the SOAP Message will contain an XML declaration when
 119      * it is sent. The only valid values are "true" and "false". The default is
 120      * "false".
 121      *
 122      * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty
 123      * @since 1.6, SAAJ 1.2
 124      */
 125     public static final String WRITE_XML_DECLARATION =


 130      * content with the given description.
 131      *
 132      * @param description a {@code String} describing the content of this
 133      *         message
 134      * @see #getContentDescription
 135      */
 136     public abstract void setContentDescription(String description);
 137 
 138     /**
 139      * Retrieves a description of this {@code SOAPMessage} object's
 140      * content.
 141      *
 142      * @return a {@code String} describing the content of this
 143      *         message or {@code null} if no description has been set
 144      * @see #setContentDescription
 145      */
 146     public abstract String getContentDescription();
 147 
 148     /**
 149          * Gets the SOAP part of this {@code SOAPMessage} object.
 150          * <P>
 151          * {@code SOAPMessage} object contains one or more attachments, the
 152          * SOAP Part must be the first MIME body part in the message.
 153          *
 154          * @return the {@code SOAPPart} object for this {@code SOAPMessage}
 155          *         object
 156          */
 157     public abstract SOAPPart getSOAPPart();
 158 
 159     /**
 160          * Gets the SOAP Body contained in this {@code SOAPMessage} object.
 161          *
 162          * @return the {@code SOAPBody} object contained by this {@code SOAPMessage}
 163          *         object
 164          * @exception SOAPException
 165          *               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 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
 216          *           a {@code MimeHeaders} object containing the MIME
 217          *           headers for which to search
 218          * @return an iterator over all attachments that have a header that matches
 219          *         one of the given headers
 220          */
 221     public abstract Iterator getAttachments(MimeHeaders headers);
 222 
 223     /**
 224      * Removes all the {@code AttachmentPart} objects that have header
 225      * entries that match the specified headers. Note that the removed
 226      * attachment could have headers in addition to those specified.
 227      *
 228      * @param headers
 229      *           a {@code MimeHeaders} object containing the MIME
 230      *           headers for which to search
 231      * @since 1.6, SAAJ 1.3
 232      */
 233     public abstract void removeAttachments(MimeHeaders headers);
 234 
 235 
 236     /**


   1 /*
   2  * Copyright (c) 2004, 2015, 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


  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  * {@code
  59  *     SOAPPart sp = message.getSOAPPart();
  60  *     SOAPEnvelope se = sp.getEnvelope();
  61  *     SOAPBody sb = se.getBody();
  62  *     SOAPHeader sh = se.getHeader();
  63  * }
  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


  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 =


 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 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 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     /**


< prev index next >