Mercurial > jdk8-mips64-public > jaxws / file comparison

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

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

changeset 0
373ffda63c9a
child 637
9c07ef4934dd
equal deleted inserted replaced
-1:000000000000 0:373ffda63c9a
1 /*
2 * Copyright (c) 2004, 2012, 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</code> object consists of a SOAP part and optionally
40 * one or more attachment parts. The SOAP part for a <code>SOAPMessage</code>
41 * object is a <code>SOAPPart</code> 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</code> object contains the following by default:
47 * <UL>
48 * <LI>A <code>SOAPPart</code> object
49 * <LI>A <code>SOAPEnvelope</code> object
50 * <LI>A <code>SOAPBody</code> object
51 * <LI>A <code>SOAPHeader</code> object
52 * </UL>
53 * The SOAP part of a message can be retrieved by calling the method <code>SOAPMessage.getSOAPPart()</code>.
54 * The <code>SOAPEnvelope</code> object is retrieved from the <code>SOAPPart</code>
55 * object, and the <code>SOAPEnvelope</code> object is used to retrieve the
56 * <code>SOAPBody</code> and <code>SOAPHeader</code> 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</code> object, a <code>SOAPMessage</code>
67 * object may contain zero or more <code>AttachmentPart</code> objects, each
68 * of which contains application-specific data. The <code>SOAPMessage</code>
69 * interface provides methods for creating <code>AttachmentPart</code>
70 * objects and also for adding them to a <code>SOAPMessage</code> object. A
71 * party that has received a <code>SOAPMessage</code> 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</code> object.
78 * <P>
79 * A <code>MessageFactory</code> object may create <code>SOAPMessage</code>
80 * objects with behavior that is specialized to a particular implementation or
81 * application of SAAJ. For instance, a <code>MessageFactory</code> object
82 * may produce <code>SOAPMessage</code> objects that conform to a particular
83 * Profile such as ebXML. In this case a <code>MessageFactory</code> object
84 * might produce <code>SOAPMessage</code> 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</code>
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 */
104 public abstract class SOAPMessage {
105 /**
106 * Specifies the character type encoding for the SOAP Message. Valid values
107 * include "utf-8" and "utf-16". See vendor documentation for additional
108 * supported values. The default is "utf-8".
109 *
110 * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty
111 * @since SAAJ 1.2
112 */
113 public static final String CHARACTER_SET_ENCODING =
114 "javax.xml.soap.character-set-encoding";
115
116 /**
117 * Specifies whether the SOAP Message will contain an XML declaration when
118 * it is sent. The only valid values are "true" and "false". The default is
119 * "false".
120 *
121 * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty
122 * @since SAAJ 1.2
123 */
124 public static final String WRITE_XML_DECLARATION =
125 "javax.xml.soap.write-xml-declaration";
126
127 /**
128 * Sets the description of this <code>SOAPMessage</code> object's
129 * content with the given description.
130 *
131 * @param description a <code>String</code> describing the content of this
132 * message
133 * @see #getContentDescription
134 */
135 public abstract void setContentDescription(String description);
136
137 /**
138 * Retrieves a description of this <code>SOAPMessage</code> object's
139 * content.
140 *
141 * @return a <code>String</code> describing the content of this
142 * message or <code>null</code> if no description has been set
143 * @see #setContentDescription
144 */
145 public abstract String getContentDescription();
146
147 /**
148 * Gets the SOAP part of this <code>SOAPMessage</code> object.
149 * <P>
150 * <code>SOAPMessage</code> object contains one or more attachments, the
151 * SOAP Part must be the first MIME body part in the message.
152 *
153 * @return the <code>SOAPPart</code> object for this <code>SOAPMessage</code>
154 * object
155 */
156 public abstract SOAPPart getSOAPPart();
157
158 /**
159 * Gets the SOAP Body contained in this <code>SOAPMessage</code> object.
160 * <p>
161 *
162 * @return the <code>SOAPBody</code> object contained by this <code>SOAPMessage</code>
163 * object
164 * @exception SOAPException
165 * if the SOAP Body does not exist or cannot be retrieved
166 * @since 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</code>
174 * object.
175 * <p>
176 *
177 * @return the <code>SOAPHeader</code> object contained by this <code>SOAPMessage</code>
178 * object
179 * @exception SOAPException
180 * if the SOAP Header does not exist or cannot be retrieved
181 * @since SAAJ 1.2
182 */
183 public SOAPHeader getSOAPHeader() throws SOAPException {
184 throw new UnsupportedOperationException("getSOAPHeader must be overridden by all subclasses of SOAPMessage");
185 }
186
187 /**
188 * Removes all <code>AttachmentPart</code> objects that have been added
189 * to this <code>SOAPMessage</code> object.
190 * <P>
191 * This method does not touch the SOAP part.
192 */
193 public abstract void removeAllAttachments();
194
195 /**
196 * Gets a count of the number of attachments in this message. This count
197 * does not include the SOAP part.
198 *
199 * @return the number of <code>AttachmentPart</code> objects that are
200 * part of this <code>SOAPMessage</code> object
201 */
202 public abstract int countAttachments();
203
204 /**
205 * Retrieves all the <code>AttachmentPart</code> objects that are part of
206 * this <code>SOAPMessage</code> object.
207 *
208 * @return an iterator over all the attachments in this message
209 */
210 public abstract Iterator getAttachments();
211
212 /**
213 * Retrieves all the <code>AttachmentPart</code> objects that have header
214 * entries that match the specified headers. Note that a returned
215 * attachment could have headers in addition to those specified.
216 *
217 * @param headers
218 * a <code>MimeHeaders</code> object containing the MIME
219 * headers for which to search
220 * @return an iterator over all attachments that have a header that matches
221 * one of the given headers
222 */
223 public abstract Iterator getAttachments(MimeHeaders headers);
224
225 /**
226 * Removes all the <code>AttachmentPart</code> objects that have header
227 * entries that match the specified headers. Note that the removed
228 * attachment could have headers in addition to those specified.
229 *
230 * @param headers
231 * a <code>MimeHeaders</code> object containing the MIME
232 * headers for which to search
233 * @since SAAJ 1.3
234 */
235 public abstract void removeAttachments(MimeHeaders headers);
236
237
238 /**
239 * Returns an <code>AttachmentPart</code> object that is associated with an
240 * attachment that is referenced by this <code>SOAPElement</code> or
241 * <code>null</code> if no such attachment exists. References can be made
242 * via an <code>href</code> attribute as described in
243 * {@link <a href="http://www.w3.org/TR/SOAP-attachments#SOAPReferenceToAttachements">SOAP Messages with Attachments</a>},
244 * or via a single <code>Text</code> child node containing a URI as
245 * described in the WS-I Attachments Profile 1.0 for elements of schema
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.
247 * The support for references via <code>href</code> attribute also implies that
248 * this method should also be supported on an element that is an
249 * <i>xop:Include</i> element (
250 * {@link <a href="http://www.w3.org/2000/xp/Group/3/06/Attachments/XOP.html">XOP</a>}).
251 * other reference mechanisms may be supported by individual
252 * implementations of this standard. Contact your vendor for details.
253 *
254 * @param element The <code>SOAPElement</code> containing the reference to an Attachment
255 * @return the referenced <code>AttachmentPart</code> or null if no such
256 * <code>AttachmentPart</code> exists or no reference can be
257 * found in this <code>SOAPElement</code>.
258 * @throws SOAPException if there is an error in the attempt to access the
259 * attachment
260 *
261 * @since SAAJ 1.3
262 */
263 public abstract AttachmentPart getAttachment(SOAPElement element) throws SOAPException;
264
265
266 /**
267 * Adds the given <code>AttachmentPart</code> object to this <code>SOAPMessage</code>
268 * object. An <code>AttachmentPart</code> object must be created before
269 * it can be added to a message.
270 *
271 * @param AttachmentPart
272 * an <code>AttachmentPart</code> object that is to become part
273 * of this <code>SOAPMessage</code> object
274 * @exception IllegalArgumentException
275 */
276 public abstract void addAttachmentPart(AttachmentPart AttachmentPart);
277
278 /**
279 * Creates a new empty <code>AttachmentPart</code> object. Note that the
280 * method <code>addAttachmentPart</code> must be called with this new
281 * <code>AttachmentPart</code> object as the parameter in order for it to
282 * become an attachment to this <code>SOAPMessage</code> object.
283 *
284 * @return a new <code>AttachmentPart</code> object that can be populated
285 * and added to this <code>SOAPMessage</code> object
286 */
287 public abstract AttachmentPart createAttachmentPart();
288
289 /**
290 * Creates an <code>AttachmentPart</code> object and populates it using
291 * the given <code>DataHandler</code> object.
292 *
293 * @param dataHandler
294 * the <code>javax.activation.DataHandler</code> object that
295 * will generate the content for this <code>SOAPMessage</code>
296 * object
297 * @return a new <code>AttachmentPart</code> object that contains data
298 * generated by the given <code>DataHandler</code> object
299 * @exception IllegalArgumentException
300 * if there was a problem with the specified <code>DataHandler</code>
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</code>
313 * object in a transport-independent fashion.
314 *
315 * @return a <code>MimeHeaders</code> object containing the <code>MimeHeader</code>
316 * objects
317 */
318 public abstract MimeHeaders getMimeHeaders();
319
320 /**
321 * Creates an <code>AttachmentPart</code> object and populates it with
322 * the specified data of the specified content type. The type of the
323 * <code>Object</code> should correspond to the value given for the
324 * <code>Content-Type</code>.
325 *
326 * @param content
327 * an <code>Object</code> containing the content for the
328 * <code>AttachmentPart</code> object to be created
329 * @param contentType
330 * a <code>String</code> object giving the type of content;
331 * examples are "text/xml", "text/plain", and "image/jpeg"
332 * @return a new <code>AttachmentPart</code> 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</code> 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</code> 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</code> needs to be
356 * called explicitly in order to save the changes. The method <code>saveChanges</code>
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</code> has been called.
361 * <P>
362 * In addition, this method marks the point at which the data from all
363 * constituent <code>AttachmentPart</code> objects are pulled into the
364 * message.
365 * <P>
366 *
367 * @exception <code>SOAPException</code> if there was a problem saving
368 * changes to this message.
369 */
370 public abstract void saveChanges() throws SOAPException;
371
372 /**
373 * Indicates whether this <code>SOAPMessage</code> object needs to have
374 * the method <code>saveChanges</code> called on it.
375 *
376 * @return <code>true</code> if <code>saveChanges</code> needs to be
377 * called; <code>false</code> otherwise.
378 */
379 public abstract boolean saveRequired();
380
381 /**
382 * Writes this <code>SOAPMessage</code> object to the given output
383 * stream. The externalization format is as defined by the SOAP 1.1 with
384 * Attachments specification.
385 * <P>
386 * If there are no attachments, just an XML stream is written out. For
387 * those messages that have attachments, <code>writeTo</code> writes a
388 * MIME-encoded byte stream.
389 * <P>
390 * Note that this method does not write the transport-specific MIME Headers
391 * of the Message
392 *
393 * @param out
394 * the <code>OutputStream</code> object to which this <code>SOAPMessage</code>
395 * object will be written
396 * @exception IOException
397 * if an I/O error occurs
398 * @exception SOAPException
399 * if there was a problem in externalizing this SOAP message
400 */
401 public abstract void writeTo(OutputStream out)
402 throws SOAPException, IOException;
403
404 /**
405 * Associates the specified value with the specified property. If there was
406 * already a value associated with this property, the old value is
407 * replaced.
408 * <p>
409 * The valid property names include
410 * {@link SOAPMessage#WRITE_XML_DECLARATION} and
411 * {@link SOAPMessage#CHARACTER_SET_ENCODING}. All of these standard SAAJ
412 * properties are prefixed by "javax.xml.soap". Vendors may also add
413 * implementation specific properties. These properties must be prefixed
414 * with package names that are unique to the vendor.
415 * <p>
416 * Setting the property <code>WRITE_XML_DECLARATION</code> to <code>"true"</code>
417 * will cause an XML Declaration to be written out at the start of the SOAP
418 * message. The default value of "false" suppresses this declaration.
419 * <p>
420 * The property <code>CHARACTER_SET_ENCODING</code> defaults to the value
421 * <code>"utf-8"</code> which causes the SOAP message to be encoded using
422 * UTF-8. Setting <code>CHARACTER_SET_ENCODING</code> to <code>"utf-16"</code>
423 * causes the SOAP message to be encoded using UTF-16.
424 * <p>
425 * Some implementations may allow encodings in addition to UTF-8 and
426 * UTF-16. Refer to your vendor's documentation for details.
427 *
428 * @param property
429 * the property with which the specified value is to be
430 * associated.
431 * @param value
432 * the value to be associated with the specified property
433 * @exception SOAPException
434 * if the property name is not recognized.
435 * @since SAAJ 1.2
436 */
437 public void setProperty(String property, Object value)
438 throws SOAPException {
439 throw new UnsupportedOperationException("setProperty must be overridden by all subclasses of SOAPMessage");
440 }
441
442 /**
443 * Retrieves value of the specified property.
444 *
445 * @param property
446 * the name of the property to retrieve
447 * @return the value associated with the named property or <code>null</code>
448 * if no such property exists.
449 * @exception SOAPException
450 * if the property name is not recognized.
451 * @since SAAJ 1.2
452 */
453 public Object getProperty(String property) throws SOAPException {
454 throw new UnsupportedOperationException("getProperty must be overridden by all subclasses of SOAPMessage");
455 }
456 }

Mercurial Repository: jdk8-mips64-public/jaxws

mercurial