001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package javax.xml.soap;
020:
021: import javax.activation.DataHandler;
022: import java.io.IOException;
023: import java.io.OutputStream;
024: import java.util.Iterator;
025:
026: /**
027: * <P>The root class for all SOAP messages. As transmitted on the "wire", a SOAP message is an XML
028: * document or a MIME message whose first body part is an XML/SOAP document.</P>
029: * <p/>
030: * <P>A <CODE>SOAPMessage</CODE> object consists of a SOAP part and optionally one or more
031: * attachment parts. The SOAP part for a <CODE>SOAPMessage</CODE> object is a <CODE>SOAPPart</CODE>
032: * object, which contains information used for message routing and identification, and which can
033: * contain application-specific content. All data in the SOAP Part of a message must be in XML
034: * format.</P>
035: * <p/>
036: * <P>A new <CODE>SOAPMessage</CODE> object contains the following by default:</P>
037: * <p/>
038: * <UL> <LI>A <CODE>SOAPPart</CODE> object</LI>
039: * <p/>
040: * <LI>A <CODE>SOAPEnvelope</CODE> object</LI>
041: * <p/>
042: * <LI>A <CODE>SOAPBody</CODE> object</LI>
043: * <p/>
044: * <LI>A <CODE>SOAPHeader</CODE> object</LI> </UL> The SOAP part of a message can be retrieved by
045: * calling the method <CODE>SOAPMessage.getSOAPPart()</CODE>. The <CODE> SOAPEnvelope</CODE> object
046: * is retrieved from the <CODE> SOAPPart</CODE> object, and the <CODE>SOAPEnvelope</CODE> object is
047: * used to retrieve the <CODE>SOAPBody</CODE> and <CODE> SOAPHeader</CODE> objects. <PRE> SOAPPart
048: * sp = message.getSOAPPart(); SOAPEnvelope se = sp.getEnvelope(); SOAPBody sb = se.getBody();
049: * SOAPHeader sh = se.getHeader(); </PRE>
050: * <p/>
051: * <P>In addition to the mandatory <CODE>SOAPPart</CODE> object, a <CODE>SOAPMessage</CODE> object
052: * may contain zero or more <CODE> AttachmentPart</CODE> objects, each of which contains
053: * application-specific data. The <CODE>SOAPMessage</CODE> interface provides methods for creating
054: * <CODE> AttachmentPart</CODE> objects and also for adding them to a <CODE>SOAPMessage</CODE>
055: * object. A party that has received a <CODE>SOAPMessage</CODE> object can examine its contents by
056: * retrieving individual attachment parts.</P>
057: * <p/>
058: * <P>Unlike the rest of a SOAP message, an attachment is not required to be in XML format and can
059: * therefore be anything from simple text to an image file. Consequently, any message content that
060: * is not in XML format must be in an <CODE> AttachmentPart</CODE> object.</P>
061: * <p/>
062: * <P>A <CODE>MessageFactory</CODE> object creates new <CODE> SOAPMessage</CODE> objects. If the
063: * <CODE>MessageFactory</CODE> object was initialized with a messaging Profile, it produces
064: * <CODE>SOAPMessage</CODE> objects that conform to that Profile. For example, a
065: * <CODE>SOAPMessage</CODE> object created by a <CODE>MessageFactory</CODE> object initialized with
066: * the ebXML Profile will have the appropriate ebXML headers.</P>
067: *
068: * @see MessageFactory MessageFactory
069: * @see AttachmentPart AttachmentPart
070: */
071: public abstract class SOAPMessage {
072:
073: public SOAPMessage() {
074: }
075:
076: /**
077: * Retrieves a description of this <CODE>SOAPMessage</CODE> object's content.
078: *
079: * @return a <CODE>String</CODE> describing the content of this message or <CODE>null</CODE> if
080: * no description has been set
081: * @see #setContentDescription(String) setContentDescription(java.lang.String)
082: */
083: public abstract String getContentDescription();
084:
085: /**
086: * Sets the description of this <CODE>SOAPMessage</CODE> object's content with the given
087: * description.
088: *
089: * @param description a <CODE>String</CODE> describing the content of this message
090: * @see #getContentDescription() getContentDescription()
091: */
092: public abstract void setContentDescription(String description);
093:
094: /**
095: * Gets the SOAP part of this <CODE>SOAPMessage</CODE> object.
096: * <p/>
097: * <p/>
098: * <P>If a <CODE>SOAPMessage</CODE> object contains one or more attachments, the SOAP Part must
099: * be the first MIME body part in the message.</P>
100: *
101: * @return the <CODE>SOAPPart</CODE> object for this <CODE> SOAPMessage</CODE> object
102: */
103: public abstract SOAPPart getSOAPPart();
104:
105: /**
106: * Removes all <CODE>AttachmentPart</CODE> objects that have been added to this
107: * <CODE>SOAPMessage</CODE> object.
108: * <p/>
109: * <P>This method does not touch the SOAP part.</P>
110: */
111: public abstract void removeAllAttachments();
112:
113: /**
114: * Gets a count of the number of attachments in this message. This count does not include the
115: * SOAP part.
116: *
117: * @return the number of <CODE>AttachmentPart</CODE> objects that are part of this
118: * <CODE>SOAPMessage</CODE> object
119: */
120: public abstract int countAttachments();
121:
122: /**
123: * Retrieves all the <CODE>AttachmentPart</CODE> objects that are part of this
124: * <CODE>SOAPMessage</CODE> object.
125: *
126: * @return an iterator over all the attachments in this message
127: */
128: public abstract Iterator getAttachments();
129:
130: /**
131: * Retrieves all the <CODE>AttachmentPart</CODE> objects that have header entries that match the
132: * specified headers. Note that a returned attachment could have headers in addition to those
133: * specified.
134: *
135: * @param headers a <CODE>MimeHeaders</CODE> object containing the MIME headers for which to
136: * search
137: * @return an iterator over all attachments that have a header that matches one of the given
138: * headers
139: */
140: public abstract Iterator getAttachments(MimeHeaders headers);
141:
142: /**
143: * Adds the given <CODE>AttachmentPart</CODE> object to this <CODE>SOAPMessage</CODE> object. An
144: * <CODE> AttachmentPart</CODE> object must be created before it can be added to a message.
145: *
146: * @param attachmentpart an <CODE> AttachmentPart</CODE> object that is to become part of this
147: * <CODE>SOAPMessage</CODE> object
148: * @throws IllegalArgumentException
149: *
150: */
151: public abstract void addAttachmentPart(AttachmentPart attachmentpart);
152:
153: /**
154: * Creates a new empty <CODE>AttachmentPart</CODE> object. Note that the method
155: * <CODE>addAttachmentPart</CODE> must be called with this new <CODE>AttachmentPart</CODE>
156: * object as the parameter in order for it to become an attachment to this
157: * <CODE>SOAPMessage</CODE> object.
158: *
159: * @return a new <CODE>AttachmentPart</CODE> object that can be populated and added to this
160: * <CODE>SOAPMessage</CODE> object
161: */
162: public abstract AttachmentPart createAttachmentPart();
163:
164: /**
165: * Creates an <CODE>AttachmentPart</CODE> object and populates it using the given
166: * <CODE>DataHandler</CODE> object.
167: *
168: * @param datahandler the <CODE> javax.activation.DataHandler</CODE> object that will generate
169: * the content for this <CODE>SOAPMessage</CODE> object
170: * @return a new <CODE>AttachmentPart</CODE> object that contains data generated by the given
171: * <CODE> DataHandler</CODE> object
172: * @throws IllegalArgumentException
173: * if there was a problem with the specified <CODE> DataHandler</CODE> object
174: * @see DataHandler DataHandler
175: * @see javax.activation.DataContentHandler DataContentHandler
176: */
177: public AttachmentPart createAttachmentPart(DataHandler datahandler) {
178:
179: AttachmentPart attachmentpart = createAttachmentPart();
180:
181: attachmentpart.setDataHandler(datahandler);
182:
183: return attachmentpart;
184: }
185:
186: /**
187: * Returns all the transport-specific MIME headers for this <CODE>SOAPMessage</CODE> object in a
188: * transport-independent fashion.
189: *
190: * @return a <CODE>MimeHeaders</CODE> object containing the <CODE>MimeHeader</CODE> objects
191: */
192: public abstract MimeHeaders getMimeHeaders();
193:
194: /**
195: * Creates an <CODE>AttachmentPart</CODE> object and populates it with the specified data of the
196: * specified content type.
197: *
198: * @param content an <CODE>Object</CODE> containing the content for this
199: * <CODE>SOAPMessage</CODE> object
200: * @param contentType a <CODE>String</CODE> object giving the type of content; examples are
201: * "text/xml", "text/plain", and "image/jpeg"
202: * @return a new <CODE>AttachmentPart</CODE> object that contains the given data
203: * @throws IllegalArgumentException
204: * if the contentType does not match the type of the content object, or if there was no
205: * <CODE> DataContentHandler</CODE> object for the given content object
206: * @see DataHandler DataHandler
207: * @see javax.activation.DataContentHandler DataContentHandler
208: */
209: public AttachmentPart createAttachmentPart(Object content,
210: String contentType) {
211:
212: AttachmentPart attachmentpart = createAttachmentPart();
213:
214: attachmentpart.setContent(content, contentType);
215:
216: return attachmentpart;
217: }
218:
219: /**
220: * Updates this <CODE>SOAPMessage</CODE> object with all the changes that have been made to it.
221: * This method is called automatically when a message is sent or written to by the methods
222: * <CODE>ProviderConnection.send</CODE>, <CODE> SOAPConnection.call</CODE>, or <CODE>
223: * SOAPMessage.writeTo</CODE>. However, if changes are made to a message that was received or to
224: * one that has already been sent, the method <CODE>saveChanges</CODE> needs to be called
225: * explicitly in order to save the changes. The method <CODE>saveChanges</CODE> also generates
226: * any changes that can be read back (for example, a MessageId in profiles that support a
227: * message id). All MIME headers in a message that is created for sending purposes are
228: * guaranteed to have valid values only after <CODE>saveChanges</CODE> has been called.
229: * <p/>
230: * <P>In addition, this method marks the point at which the data from all constituent
231: * <CODE>AttachmentPart</CODE> objects are pulled into the message.</P>
232: *
233: * @throws SOAPException if there was a problem saving changes to this message.
234: */
235: public abstract void saveChanges() throws SOAPException;
236:
237: /**
238: * Indicates whether this <CODE>SOAPMessage</CODE> object has had the method
239: * <CODE>saveChanges</CODE> called on it.
240: *
241: * @return <CODE>true</CODE> if <CODE>saveChanges</CODE> has been called on this message at
242: * least once; <CODE> false</CODE> otherwise.
243: */
244: public abstract boolean saveRequired();
245:
246: /**
247: * Writes this <CODE>SOAPMessage</CODE> object to the given output stream. The externalization
248: * format is as defined by the SOAP 1.1 with Attachments specification.
249: * <p/>
250: * <P>If there are no attachments, just an XML stream is written out. For those messages that
251: * have attachments, <CODE>writeTo</CODE> writes a MIME-encoded byte stream.</P>
252: *
253: * @param out the <CODE>OutputStream</CODE> object to which this <CODE>SOAPMessage</CODE> object
254: * will be written
255: * @throws SOAPException if there was a problem in externalizing this SOAP message
256: * @throws IOException if an I/O error occurs
257: */
258: public abstract void writeTo(OutputStream out)
259: throws SOAPException, IOException;
260:
261: /**
262: * Gets the SOAP Body contained in this <code>SOAPMessage</code> object.
263: *
264: * @return the <code>SOAPBody</code> object contained by this <code>SOAPMessage</code> object
265: * @throws SOAPException if the SOAP Body does not exist or cannot be retrieved
266: */
267: public SOAPBody getSOAPBody() throws SOAPException {
268: throw new UnsupportedOperationException(
269: "getSOAPBody must be overridden in subclasses of SOAPMessage");
270: }
271:
272: /**
273: * Gets the SOAP Header contained in this <code>SOAPMessage</code> object.
274: *
275: * @return the <code>SOAPHeader</code> object contained by this <code>SOAPMessage</code> object
276: * @throws SOAPException if the SOAP Header does not exist or cannot be retrieved
277: */
278: public SOAPHeader getSOAPHeader() throws SOAPException {
279: throw new UnsupportedOperationException(
280: "getSOAPHeader must be overridden in subclasses of SOAPMessage");
281: }
282:
283: /**
284: * Associates the specified value with the specified property. If there was already a value
285: * associated with this property, the old value is replaced.
286: * <p/>
287: * The valid property names include <code>WRITE_XML_DECLARATION</code> and
288: * <code>CHARACTER_SET_ENCODING</code>. All of these standard SAAJ properties are prefixed by
289: * "javax.xml.soap". Vendors may also add implementation specific properties. These properties
290: * must be prefixed with package names that are unique to the vendor.
291: * <p/>
292: * Setting the property <code>WRITE_XML_DECLARATION</code> to <code>"true"</code> will cause an
293: * XML Declaration to be written out at the start of the SOAP message. The default value of
294: * "false" suppresses this declaration.
295: * <p/>
296: * The property <code>CHARACTER_SET_ENCODING</code> defaults to the value <code>"utf-8"</code>
297: * which causes the SOAP message to be encoded using UTF-8. Setting
298: * <code>CHARACTER_SET_ENCODING</code> to <code>"utf-16"</code> causes the SOAP message to be
299: * encoded using UTF-16.
300: * <p/>
301: * Some implementations may allow encodings in addition to UTF-8 and UTF-16. Refer to your
302: * vendor's documentation for details.
303: *
304: * @param property the property with which the specified value is to be associated
305: * @param value the value to be associated with the specified property
306: * @throws SOAPException if the property name is not recognized
307: */
308: public void setProperty(String property, Object value)
309: throws SOAPException {
310: throw new UnsupportedOperationException(
311: "setProperty must be overridden in subclasses of SOAPMessage");
312: }
313:
314: /**
315: * Retrieves value of the specified property.
316: *
317: * @param property the name of the property to retrieve
318: * @return the value of the property or <code>null</code> if no such property exists
319: * @throws SOAPException if the property name is not recognized
320: */
321: public Object getProperty(String property) throws SOAPException {
322: throw new UnsupportedOperationException(
323: "getProperty must be overridden in subclasses of SOAPMessage");
324: }
325:
326: public abstract AttachmentPart getAttachment(SOAPElement soapelement)
327: throws SOAPException;
328:
329: public abstract void removeAttachments(MimeHeaders mimeheaders);
330:
331: /** Specifies the character type encoding for the SOAP Message. */
332: public static final String CHARACTER_SET_ENCODING = "javax.xml.soap.character-set-encoding";
333:
334: /** Specifies whether the SOAP Message should contain an XML declaration. */
335: public static final String WRITE_XML_DECLARATION = "javax.xml.soap.write-xml-declaration";
336: }
|