001: /*
002: * $Id: SOAPMessage.java,v 1.23 2006/03/30 00:59:42 ofung Exp $
003: * $Revision: 1.23 $
004: * $Date: 2006/03/30 00:59:42 $
005: */
006:
007: /*
008: * The contents of this file are subject to the terms
009: * of the Common Development and Distribution License
010: * (the License). You may not use this file except in
011: * compliance with the License.
012: *
013: * You can obtain a copy of the license at
014: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
015: * See the License for the specific language governing
016: * permissions and limitations under the License.
017: *
018: * When distributing Covered Code, include this CDDL
019: * Header Notice in each file and include the License file
020: * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
021: * If applicable, add the following below the CDDL Header,
022: * with the fields enclosed by brackets [] replaced by
023: * you own identifying information:
024: * "Portions Copyrighted [year] [name of copyright owner]"
025: *
026: * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
027: */
028: package javax.xml.soap;
029:
030: import java.io.OutputStream;
031: import java.io.IOException;
032:
033: import java.util.Iterator;
034:
035: import javax.activation.DataHandler;
036:
037: /**
038: * The root class for all SOAP messages. As transmitted on the "wire", a SOAP
039: * message is an XML document or a MIME message whose first body part is an
040: * XML/SOAP document.
041: * <P>
042: * A <code>SOAPMessage</code> object consists of a SOAP part and optionally
043: * one or more attachment parts. The SOAP part for a <code>SOAPMessage</code>
044: * object is a <code>SOAPPart</code> object, which contains information used
045: * for message routing and identification, and which can contain
046: * application-specific content. All data in the SOAP Part of a message must be
047: * in XML format.
048: * <P>
049: * A new <code>SOAPMessage</code> object contains the following by default:
050: * <UL>
051: * <LI>A <code>SOAPPart</code> object
052: * <LI>A <code>SOAPEnvelope</code> object
053: * <LI>A <code>SOAPBody</code> object
054: * <LI>A <code>SOAPHeader</code> object
055: * </UL>
056: * The SOAP part of a message can be retrieved by calling the method <code>SOAPMessage.getSOAPPart()</code>.
057: * The <code>SOAPEnvelope</code> object is retrieved from the <code>SOAPPart</code>
058: * object, and the <code>SOAPEnvelope</code> object is used to retrieve the
059: * <code>SOAPBody</code> and <code>SOAPHeader</code> objects.
060: *
061: * <PRE>
062: * SOAPPart sp = message.getSOAPPart();
063: * SOAPEnvelope se = sp.getEnvelope();
064: * SOAPBody sb = se.getBody();
065: * SOAPHeader sh = se.getHeader();
066: * </PRE>
067: *
068: * <P>
069: * In addition to the mandatory <code>SOAPPart</code> object, a <code>SOAPMessage</code>
070: * object may contain zero or more <code>AttachmentPart</code> objects, each
071: * of which contains application-specific data. The <code>SOAPMessage</code>
072: * interface provides methods for creating <code>AttachmentPart</code>
073: * objects and also for adding them to a <code>SOAPMessage</code> object. A
074: * party that has received a <code>SOAPMessage</code> object can examine its
075: * contents by retrieving individual attachment parts.
076: * <P>
077: * Unlike the rest of a SOAP message, an attachment is not required to be in
078: * XML format and can therefore be anything from simple text to an image file.
079: * Consequently, any message content that is not in XML format must be in an
080: * <code>AttachmentPart</code> object.
081: * <P>
082: * A <code>MessageFactory</code> object may create <code>SOAPMessage</code>
083: * objects with behavior that is specialized to a particular implementation or
084: * application of SAAJ. For instance, a <code>MessageFactory</code> object
085: * may produce <code>SOAPMessage</code> objects that conform to a particular
086: * Profile such as ebXML. In this case a <code>MessageFactory</code> object
087: * might produce <code>SOAPMessage</code> objects that are initialized with
088: * ebXML headers.
089: * <P>
090: * In order to ensure backward source compatibility, methods that are added to
091: * this class after version 1.1 of the SAAJ specification are all concrete
092: * instead of abstract and they all have default implementations. Unless
093: * otherwise noted in the JavaDocs for those methods the default
094: * implementations simply throw an <code>UnsupportedOperationException</code>
095: * and the SAAJ implementation code must override them with methods that
096: * provide the specified behavior. Legacy client code does not have this
097: * restriction, however, so long as there is no claim made that it conforms to
098: * some later version of the specification than it was originally written for.
099: * A legacy class that extends the SOAPMessage class can be compiled and/or run
100: * against succeeding versions of the SAAJ API without modification. If such a
101: * class was correctly implemented then it will continue to behave correctly
102: * relative to the version of the specification against which it was written.
103: *
104: * @see MessageFactory
105: * @see AttachmentPart
106: */
107: public abstract class SOAPMessage {
108: /**
109: * Specifies the character type encoding for the SOAP Message. Valid values
110: * include "utf-8" and "utf-16". See vendor documentation for additional
111: * supported values. The default is "utf-8".
112: *
113: * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty
114: * @since SAAJ 1.2
115: */
116: public static final String CHARACTER_SET_ENCODING = "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 SAAJ 1.2
125: */
126: public static final String WRITE_XML_DECLARATION = "javax.xml.soap.write-xml-declaration";
127:
128: /**
129: * Sets the description of this <code>SOAPMessage</code> object's
130: * content with the given description.
131: *
132: * @param description a <code>String</code> 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</code> object's
140: * content.
141: *
142: * @return a <code>String</code> describing the content of this
143: * message or <code>null</code> 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</code> object.
150: * <P>
151: * <code>SOAPMessage</code> 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</code> object for this <code>SOAPMessage</code>
155: * object
156: */
157: public abstract SOAPPart getSOAPPart();
158:
159: /**
160: * Gets the SOAP Body contained in this <code>SOAPMessage</code> object.
161: * <p>
162: *
163: * @return the <code>SOAPBody</code> object contained by this <code>SOAPMessage</code>
164: * object
165: * @exception SOAPException
166: * if the SOAP Body does not exist or cannot be retrieved
167: * @since SAAJ 1.2
168: */
169: public SOAPBody getSOAPBody() throws SOAPException {
170: throw new UnsupportedOperationException(
171: "getSOAPBody must be overridden by all subclasses of SOAPMessage");
172: }
173:
174: /**
175: * Gets the SOAP Header contained in this <code>SOAPMessage</code>
176: * object.
177: * <p>
178: *
179: * @return the <code>SOAPHeader</code> object contained by this <code>SOAPMessage</code>
180: * object
181: * @exception SOAPException
182: * if the SOAP Header does not exist or cannot be retrieved
183: * @since SAAJ 1.2
184: */
185: public SOAPHeader getSOAPHeader() throws SOAPException {
186: throw new UnsupportedOperationException(
187: "getSOAPHeader must be overridden by all subclasses of SOAPMessage");
188: }
189:
190: /**
191: * Removes all <code>AttachmentPart</code> objects that have been added
192: * to this <code>SOAPMessage</code> object.
193: * <P>
194: * This method does not touch the SOAP part.
195: */
196: public abstract void removeAllAttachments();
197:
198: /**
199: * Gets a count of the number of attachments in this message. This count
200: * does not include the SOAP part.
201: *
202: * @return the number of <code>AttachmentPart</code> objects that are
203: * part of this <code>SOAPMessage</code> object
204: */
205: public abstract int countAttachments();
206:
207: /**
208: * Retrieves all the <code>AttachmentPart</code> objects that are part of
209: * this <code>SOAPMessage</code> object.
210: *
211: * @return an iterator over all the attachments in this message
212: */
213: public abstract Iterator getAttachments();
214:
215: /**
216: * Retrieves all the <code>AttachmentPart</code> objects that have header
217: * entries that match the specified headers. Note that a returned
218: * attachment could have headers in addition to those specified.
219: *
220: * @param headers
221: * a <code>MimeHeaders</code> object containing the MIME
222: * headers for which to search
223: * @return an iterator over all attachments that have a header that matches
224: * one of the given headers
225: */
226: public abstract Iterator getAttachments(MimeHeaders headers);
227:
228: /**
229: * Removes all the <code>AttachmentPart</code> objects that have header
230: * entries that match the specified headers. Note that the removed
231: * attachment could have headers in addition to those specified.
232: *
233: * @param headers
234: * a <code>MimeHeaders</code> object containing the MIME
235: * headers for which to search
236: * @since SAAJ 1.3
237: */
238: public abstract void removeAttachments(MimeHeaders headers);
239:
240: /**
241: * Returns an <code>AttachmentPart</code> object that is associated with an
242: * attachment that is referenced by this <code>SOAPElement</code> or
243: * <code>null</code> if no such attachment exists. References can be made
244: * via an <code>href</code> attribute as described in
245: * {@link <a href="http://www.w3.org/TR/SOAP-attachments#SOAPReferenceToAttachements">SOAP Messages with Attachments</a>},
246: * or via a single <code>Text</code> child node containing a URI as
247: * described in the WS-I Attachments Profile 1.0 for elements of schema
248: * type <i>ref:swaRef</i>({@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.
249: * The support for references via <code>href</code> attribute also implies that
250: * this method should also be supported on an element that is an
251: * <i>xop:Include</i> element (
252: * {@link <a href="http://www.w3.org/2000/xp/Group/3/06/Attachments/XOP.html">XOP</a>}).
253: * other reference mechanisms may be supported by individual
254: * implementations of this standard. Contact your vendor for details.
255: *
256: * @param element The <code>SOAPElement</code> containing the reference to an Attachment
257: * @return the referenced <code>AttachmentPart</code> or null if no such
258: * <code>AttachmentPart</code> exists or no reference can be
259: * found in this <code>SOAPElement</code>.
260: * @throws SOAPException if there is an error in the attempt to access the
261: * attachment
262: *
263: * @since SAAJ 1.3
264: */
265: public abstract AttachmentPart getAttachment(SOAPElement element)
266: throws SOAPException;
267:
268: /**
269: * Adds the given <code>AttachmentPart</code> object to this <code>SOAPMessage</code>
270: * object. An <code>AttachmentPart</code> object must be created before
271: * it can be added to a message.
272: *
273: * @param AttachmentPart
274: * an <code>AttachmentPart</code> object that is to become part
275: * of this <code>SOAPMessage</code> object
276: * @exception IllegalArgumentException
277: */
278: public abstract void addAttachmentPart(AttachmentPart AttachmentPart);
279:
280: /**
281: * Creates a new empty <code>AttachmentPart</code> object. Note that the
282: * method <code>addAttachmentPart</code> must be called with this new
283: * <code>AttachmentPart</code> object as the parameter in order for it to
284: * become an attachment to this <code>SOAPMessage</code> object.
285: *
286: * @return a new <code>AttachmentPart</code> object that can be populated
287: * and added to this <code>SOAPMessage</code> object
288: */
289: public abstract AttachmentPart createAttachmentPart();
290:
291: /**
292: * Creates an <code>AttachmentPart</code> object and populates it using
293: * the given <code>DataHandler</code> object.
294: *
295: * @param dataHandler
296: * the <code>javax.activation.DataHandler</code> object that
297: * will generate the content for this <code>SOAPMessage</code>
298: * object
299: * @return a new <code>AttachmentPart</code> object that contains data
300: * generated by the given <code>DataHandler</code> object
301: * @exception IllegalArgumentException
302: * if there was a problem with the specified <code>DataHandler</code>
303: * object
304: * @see javax.activation.DataHandler
305: * @see javax.activation.DataContentHandler
306: */
307: public AttachmentPart createAttachmentPart(DataHandler dataHandler) {
308: AttachmentPart attachment = createAttachmentPart();
309: attachment.setDataHandler(dataHandler);
310: return attachment;
311: }
312:
313: /**
314: * Returns all the transport-specific MIME headers for this <code>SOAPMessage</code>
315: * object in a transport-independent fashion.
316: *
317: * @return a <code>MimeHeaders</code> object containing the <code>MimeHeader</code>
318: * objects
319: */
320: public abstract MimeHeaders getMimeHeaders();
321:
322: /**
323: * Creates an <code>AttachmentPart</code> object and populates it with
324: * the specified data of the specified content type. The type of the
325: * <code>Object</code> should correspond to the value given for the
326: * <code>Content-Type</code>.
327: *
328: * @param content
329: * an <code>Object</code> containing the content for the
330: * <code>AttachmentPart</code> object to be created
331: * @param contentType
332: * a <code>String</code> object giving the type of content;
333: * examples are "text/xml", "text/plain", and "image/jpeg"
334: * @return a new <code>AttachmentPart</code> object that contains the
335: * given data
336: * @exception IllegalArgumentException
337: * may be thrown if the contentType does not match the type
338: * of the content object, or if there was no
339: * <code>DataContentHandler</code> object for the given
340: * content object
341: * @see javax.activation.DataHandler
342: * @see javax.activation.DataContentHandler
343: */
344: public AttachmentPart createAttachmentPart(Object content,
345: String contentType) {
346: AttachmentPart attachment = createAttachmentPart();
347: attachment.setContent(content, contentType);
348: return attachment;
349: }
350:
351: /**
352: * Updates this <code>SOAPMessage</code> object with all the changes that
353: * have been made to it. This method is called automatically when
354: * {@link SOAPMessage#writeTo(OutputStream)} is called. However, if
355: * changes are made to a message that was received or to one that has
356: * already been sent, the method <code>saveChanges</code> needs to be
357: * called explicitly in order to save the changes. The method <code>saveChanges</code>
358: * also generates any changes that can be read back (for example, a
359: * MessageId in profiles that support a message id). All MIME headers in a
360: * message that is created for sending purposes are guaranteed to have
361: * valid values only after <code>saveChanges</code> has been called.
362: * <P>
363: * In addition, this method marks the point at which the data from all
364: * constituent <code>AttachmentPart</code> objects are pulled into the
365: * message.
366: * <P>
367: *
368: * @exception <code>SOAPException</code> if there was a problem saving
369: * changes to this message.
370: */
371: public abstract void saveChanges() throws SOAPException;
372:
373: /**
374: * Indicates whether this <code>SOAPMessage</code> object needs to have
375: * the method <code>saveChanges</code> called on it.
376: *
377: * @return <code>true</code> if <code>saveChanges</code> needs to be
378: * called; <code>false</code> otherwise.
379: */
380: public abstract boolean saveRequired();
381:
382: /**
383: * Writes this <code>SOAPMessage</code> object to the given output
384: * stream. The externalization format is as defined by the SOAP 1.1 with
385: * Attachments specification.
386: * <P>
387: * If there are no attachments, just an XML stream is written out. For
388: * those messages that have attachments, <code>writeTo</code> writes a
389: * MIME-encoded byte stream.
390: * <P>
391: * Note that this method does not write the transport-specific MIME Headers
392: * of the Message
393: *
394: * @param out
395: * the <code>OutputStream</code> object to which this <code>SOAPMessage</code>
396: * object will be written
397: * @exception IOException
398: * if an I/O error occurs
399: * @exception SOAPException
400: * if there was a problem in externalizing this SOAP message
401: */
402: public abstract void writeTo(OutputStream out)
403: throws SOAPException, IOException;
404:
405: /**
406: * Associates the specified value with the specified property. If there was
407: * already a value associated with this property, the old value is
408: * replaced.
409: * <p>
410: * The valid property names include
411: * {@link SOAPMessage#WRITE_XML_DECLARATION} and
412: * {@link SOAPMessage#CHARACTER_SET_ENCODING}. All of these standard SAAJ
413: * properties are prefixed by "javax.xml.soap". Vendors may also add
414: * implementation specific properties. These properties must be prefixed
415: * with package names that are unique to the vendor.
416: * <p>
417: * Setting the property <code>WRITE_XML_DECLARATION</code> to <code>"true"</code>
418: * will cause an XML Declaration to be written out at the start of the SOAP
419: * message. The default value of "false" suppresses this declaration.
420: * <p>
421: * The property <code>CHARACTER_SET_ENCODING</code> defaults to the value
422: * <code>"utf-8"</code> which causes the SOAP message to be encoded using
423: * UTF-8. Setting <code>CHARACTER_SET_ENCODING</code> to <code>"utf-16"</code>
424: * causes the SOAP message to be encoded using UTF-16.
425: * <p>
426: * Some implementations may allow encodings in addition to UTF-8 and
427: * UTF-16. Refer to your vendor's documentation for details.
428: *
429: * @param property
430: * the property with which the specified value is to be
431: * associated.
432: * @param value
433: * the value to be associated with the specified property
434: * @exception SOAPException
435: * if the property name is not recognized.
436: * @since SAAJ 1.2
437: */
438: public void setProperty(String property, Object value)
439: throws SOAPException {
440: throw new UnsupportedOperationException(
441: "setProperty must be overridden by all subclasses of SOAPMessage");
442: }
443:
444: /**
445: * Retrieves value of the specified property.
446: *
447: * @param property
448: * the name of the property to retrieve
449: * @return the value associated with the named property or <code>null</code>
450: * if no such property exists.
451: * @exception SOAPException
452: * if the property name is not recognized.
453: * @since SAAJ 1.2
454: */
455: public Object getProperty(String property) throws SOAPException {
456: throw new UnsupportedOperationException(
457: "getProperty must be overridden by all subclasses of SOAPMessage");
458: }
459: }
|