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