ohair@286: /* alanb@368: * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved. ohair@286: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. ohair@286: * ohair@286: * This code is free software; you can redistribute it and/or modify it ohair@286: * under the terms of the GNU General Public License version 2 only, as ohair@286: * published by the Free Software Foundation. Oracle designates this ohair@286: * particular file as subject to the "Classpath" exception as provided ohair@286: * by Oracle in the LICENSE file that accompanied this code. ohair@286: * ohair@286: * This code is distributed in the hope that it will be useful, but WITHOUT ohair@286: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or ohair@286: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License ohair@286: * version 2 for more details (a copy is included in the LICENSE file that ohair@286: * accompanied this code). ohair@286: * ohair@286: * You should have received a copy of the GNU General Public License version ohair@286: * 2 along with this work; if not, write to the Free Software Foundation, ohair@286: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. ohair@286: * ohair@286: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@286: * or visit www.oracle.com if you need additional information or have any ohair@286: * questions. ohair@286: */ ohair@286: ohair@286: package javax.xml.soap; ohair@286: import java.io.OutputStream; ohair@286: import java.io.IOException; ohair@286: ohair@286: import java.util.Iterator; ohair@286: ohair@286: import javax.activation.DataHandler; ohair@286: ohair@286: /** ohair@286: * The root class for all SOAP messages. As transmitted on the "wire", a SOAP ohair@286: * message is an XML document or a MIME message whose first body part is an ohair@286: * XML/SOAP document. ohair@286: *

ohair@286: * A SOAPMessage object consists of a SOAP part and optionally ohair@286: * one or more attachment parts. The SOAP part for a SOAPMessage ohair@286: * object is a SOAPPart object, which contains information used ohair@286: * for message routing and identification, and which can contain ohair@286: * application-specific content. All data in the SOAP Part of a message must be ohair@286: * in XML format. ohair@286: *

ohair@286: * A new SOAPMessage object contains the following by default: ohair@286: *

ohair@286: * The SOAP part of a message can be retrieved by calling the method SOAPMessage.getSOAPPart(). ohair@286: * The SOAPEnvelope object is retrieved from the SOAPPart ohair@286: * object, and the SOAPEnvelope object is used to retrieve the ohair@286: * SOAPBody and SOAPHeader objects. ohair@286: * ohair@286: * 
ohair@286:  *     SOAPPart sp = message.getSOAPPart();
ohair@286:  *     SOAPEnvelope se = sp.getEnvelope();
ohair@286:  *     SOAPBody sb = se.getBody();
ohair@286:  *     SOAPHeader sh = se.getHeader();
ohair@286:  *
ohair@286: * ohair@286: *

ohair@286: * In addition to the mandatory SOAPPart object, a SOAPMessage ohair@286: * object may contain zero or more AttachmentPart objects, each ohair@286: * of which contains application-specific data. The SOAPMessage ohair@286: * interface provides methods for creating AttachmentPart ohair@286: * objects and also for adding them to a SOAPMessage object. A ohair@286: * party that has received a SOAPMessage object can examine its ohair@286: * contents by retrieving individual attachment parts. ohair@286: *

ohair@286: * Unlike the rest of a SOAP message, an attachment is not required to be in ohair@286: * XML format and can therefore be anything from simple text to an image file. ohair@286: * Consequently, any message content that is not in XML format must be in an ohair@286: * AttachmentPart object. ohair@286: *

ohair@286: * A MessageFactory object may create SOAPMessage ohair@286: * objects with behavior that is specialized to a particular implementation or ohair@286: * application of SAAJ. For instance, a MessageFactory object ohair@286: * may produce SOAPMessage objects that conform to a particular ohair@286: * Profile such as ebXML. In this case a MessageFactory object ohair@286: * might produce SOAPMessage objects that are initialized with ohair@286: * ebXML headers. ohair@286: *

ohair@286: * In order to ensure backward source compatibility, methods that are added to ohair@286: * this class after version 1.1 of the SAAJ specification are all concrete ohair@286: * instead of abstract and they all have default implementations. Unless ohair@286: * otherwise noted in the JavaDocs for those methods the default ohair@286: * implementations simply throw an UnsupportedOperationException ohair@286: * and the SAAJ implementation code must override them with methods that ohair@286: * provide the specified behavior. Legacy client code does not have this ohair@286: * restriction, however, so long as there is no claim made that it conforms to ohair@286: * some later version of the specification than it was originally written for. ohair@286: * A legacy class that extends the SOAPMessage class can be compiled and/or run ohair@286: * against succeeding versions of the SAAJ API without modification. If such a ohair@286: * class was correctly implemented then it will continue to behave correctly ohair@286: * relative to the version of the specification against which it was written. ohair@286: * ohair@286: * @see MessageFactory ohair@286: * @see AttachmentPart ohair@286: */ ohair@286: public abstract class SOAPMessage { ohair@286: /** ohair@286: * Specifies the character type encoding for the SOAP Message. Valid values ohair@286: * include "utf-8" and "utf-16". See vendor documentation for additional ohair@286: * supported values. The default is "utf-8". ohair@286: * ohair@286: * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty ohair@286: * @since SAAJ 1.2 ohair@286: */ ohair@286: public static final String CHARACTER_SET_ENCODING = ohair@286: "javax.xml.soap.character-set-encoding"; ohair@286: ohair@286: /** ohair@286: * Specifies whether the SOAP Message will contain an XML declaration when ohair@286: * it is sent. The only valid values are "true" and "false". The default is ohair@286: * "false". ohair@286: * ohair@286: * @see SOAPMessage#setProperty(String, Object) SOAPMessage.setProperty ohair@286: * @since SAAJ 1.2 ohair@286: */ ohair@286: public static final String WRITE_XML_DECLARATION = ohair@286: "javax.xml.soap.write-xml-declaration"; ohair@286: ohair@286: /** ohair@286: * Sets the description of this SOAPMessage object's ohair@286: * content with the given description. ohair@286: * ohair@286: * @param description a String describing the content of this ohair@286: * message ohair@286: * @see #getContentDescription ohair@286: */ ohair@286: public abstract void setContentDescription(String description); ohair@286: ohair@286: /** ohair@286: * Retrieves a description of this SOAPMessage object's ohair@286: * content. ohair@286: * ohair@286: * @return a String describing the content of this ohair@286: * message or null if no description has been set ohair@286: * @see #setContentDescription ohair@286: */ ohair@286: public abstract String getContentDescription(); ohair@286: ohair@286: /** ohair@286: * Gets the SOAP part of this SOAPMessage object. ohair@286: *

ohair@286: * SOAPMessage object contains one or more attachments, the ohair@286: * SOAP Part must be the first MIME body part in the message. ohair@286: * ohair@286: * @return the SOAPPart object for this SOAPMessage ohair@286: * object ohair@286: */ ohair@286: public abstract SOAPPart getSOAPPart(); ohair@286: ohair@286: /** ohair@286: * Gets the SOAP Body contained in this SOAPMessage object. ohair@286: *

ohair@286: * ohair@286: * @return the SOAPBody object contained by this SOAPMessage ohair@286: * object ohair@286: * @exception SOAPException ohair@286: * if the SOAP Body does not exist or cannot be retrieved ohair@286: * @since SAAJ 1.2 ohair@286: */ ohair@286: public SOAPBody getSOAPBody() throws SOAPException { ohair@286: throw new UnsupportedOperationException("getSOAPBody must be overridden by all subclasses of SOAPMessage"); ohair@286: } ohair@286: ohair@286: /** ohair@286: * Gets the SOAP Header contained in this SOAPMessage ohair@286: * object. ohair@286: *

ohair@286: * ohair@286: * @return the SOAPHeader object contained by this SOAPMessage ohair@286: * object ohair@286: * @exception SOAPException ohair@286: * if the SOAP Header does not exist or cannot be retrieved ohair@286: * @since SAAJ 1.2 ohair@286: */ ohair@286: public SOAPHeader getSOAPHeader() throws SOAPException { ohair@286: throw new UnsupportedOperationException("getSOAPHeader must be overridden by all subclasses of SOAPMessage"); ohair@286: } ohair@286: ohair@286: /** ohair@286: * Removes all AttachmentPart objects that have been added ohair@286: * to this SOAPMessage object. ohair@286: *

ohair@286: * This method does not touch the SOAP part. ohair@286: */ ohair@286: public abstract void removeAllAttachments(); ohair@286: ohair@286: /** ohair@286: * Gets a count of the number of attachments in this message. This count ohair@286: * does not include the SOAP part. ohair@286: * ohair@286: * @return the number of AttachmentPart objects that are ohair@286: * part of this SOAPMessage object ohair@286: */ ohair@286: public abstract int countAttachments(); ohair@286: ohair@286: /** ohair@286: * Retrieves all the AttachmentPart objects that are part of ohair@286: * this SOAPMessage object. ohair@286: * ohair@286: * @return an iterator over all the attachments in this message ohair@286: */ ohair@286: public abstract Iterator getAttachments(); ohair@286: ohair@286: /** ohair@286: * Retrieves all the AttachmentPart objects that have header ohair@286: * entries that match the specified headers. Note that a returned ohair@286: * attachment could have headers in addition to those specified. ohair@286: * ohair@286: * @param headers ohair@286: * a MimeHeaders object containing the MIME ohair@286: * headers for which to search ohair@286: * @return an iterator over all attachments that have a header that matches ohair@286: * one of the given headers ohair@286: */ ohair@286: public abstract Iterator getAttachments(MimeHeaders headers); ohair@286: ohair@286: /** ohair@286: * Removes all the AttachmentPart objects that have header ohair@286: * entries that match the specified headers. Note that the removed ohair@286: * attachment could have headers in addition to those specified. ohair@286: * ohair@286: * @param headers ohair@286: * a MimeHeaders object containing the MIME ohair@286: * headers for which to search ohair@286: * @since SAAJ 1.3 ohair@286: */ ohair@286: public abstract void removeAttachments(MimeHeaders headers); ohair@286: ohair@286: ohair@286: /** ohair@286: * Returns an AttachmentPart object that is associated with an ohair@286: * attachment that is referenced by this SOAPElement or ohair@286: * null if no such attachment exists. References can be made ohair@286: * via an href attribute as described in ohair@286: * {@link SOAP Messages with Attachments}, ohair@286: * or via a single Text child node containing a URI as ohair@286: * described in the WS-I Attachments Profile 1.0 for elements of schema ohair@286: * type {@link ref:swaRef}. These two mechanisms must be supported. ohair@286: * The support for references via href attribute also implies that ohair@286: * this method should also be supported on an element that is an ohair@286: * xop:Include element ( ohair@286: * {@link XOP}). ohair@286: * other reference mechanisms may be supported by individual ohair@286: * implementations of this standard. Contact your vendor for details. ohair@286: * ohair@286: * @param element The SOAPElement containing the reference to an Attachment ohair@286: * @return the referenced AttachmentPart or null if no such ohair@286: * AttachmentPart exists or no reference can be ohair@286: * found in this SOAPElement. ohair@286: * @throws SOAPException if there is an error in the attempt to access the ohair@286: * attachment ohair@286: * ohair@286: * @since SAAJ 1.3 ohair@286: */ ohair@286: public abstract AttachmentPart getAttachment(SOAPElement element) throws SOAPException; ohair@286: ohair@286: ohair@286: /** ohair@286: * Adds the given AttachmentPart object to this SOAPMessage ohair@286: * object. An AttachmentPart object must be created before ohair@286: * it can be added to a message. ohair@286: * ohair@286: * @param AttachmentPart ohair@286: * an AttachmentPart object that is to become part ohair@286: * of this SOAPMessage object ohair@286: * @exception IllegalArgumentException ohair@286: */ ohair@286: public abstract void addAttachmentPart(AttachmentPart AttachmentPart); ohair@286: ohair@286: /** ohair@286: * Creates a new empty AttachmentPart object. Note that the ohair@286: * method addAttachmentPart must be called with this new ohair@286: * AttachmentPart object as the parameter in order for it to ohair@286: * become an attachment to this SOAPMessage object. ohair@286: * ohair@286: * @return a new AttachmentPart object that can be populated ohair@286: * and added to this SOAPMessage object ohair@286: */ ohair@286: public abstract AttachmentPart createAttachmentPart(); ohair@286: ohair@286: /** ohair@286: * Creates an AttachmentPart object and populates it using ohair@286: * the given DataHandler object. ohair@286: * ohair@286: * @param dataHandler ohair@286: * the javax.activation.DataHandler object that ohair@286: * will generate the content for this SOAPMessage ohair@286: * object ohair@286: * @return a new AttachmentPart object that contains data ohair@286: * generated by the given DataHandler object ohair@286: * @exception IllegalArgumentException ohair@286: * if there was a problem with the specified DataHandler ohair@286: * object ohair@286: * @see javax.activation.DataHandler ohair@286: * @see javax.activation.DataContentHandler ohair@286: */ ohair@286: public AttachmentPart createAttachmentPart(DataHandler dataHandler) { ohair@286: AttachmentPart attachment = createAttachmentPart(); ohair@286: attachment.setDataHandler(dataHandler); ohair@286: return attachment; ohair@286: } ohair@286: ohair@286: /** ohair@286: * Returns all the transport-specific MIME headers for this SOAPMessage ohair@286: * object in a transport-independent fashion. ohair@286: * ohair@286: * @return a MimeHeaders object containing the MimeHeader ohair@286: * objects ohair@286: */ ohair@286: public abstract MimeHeaders getMimeHeaders(); ohair@286: ohair@286: /** ohair@286: * Creates an AttachmentPart object and populates it with ohair@286: * the specified data of the specified content type. The type of the ohair@286: * Object should correspond to the value given for the ohair@286: * Content-Type. ohair@286: * ohair@286: * @param content ohair@286: * an Object containing the content for the ohair@286: * AttachmentPart object to be created ohair@286: * @param contentType ohair@286: * a String object giving the type of content; ohair@286: * examples are "text/xml", "text/plain", and "image/jpeg" ohair@286: * @return a new AttachmentPart object that contains the ohair@286: * given data ohair@286: * @exception IllegalArgumentException ohair@286: * may be thrown if the contentType does not match the type ohair@286: * of the content object, or if there was no ohair@286: * DataContentHandler object for the given ohair@286: * content object ohair@286: * @see javax.activation.DataHandler ohair@286: * @see javax.activation.DataContentHandler ohair@286: */ ohair@286: public AttachmentPart createAttachmentPart( ohair@286: Object content, ohair@286: String contentType) { ohair@286: AttachmentPart attachment = createAttachmentPart(); ohair@286: attachment.setContent(content, contentType); ohair@286: return attachment; ohair@286: } ohair@286: ohair@286: /** ohair@286: * Updates this SOAPMessage object with all the changes that ohair@286: * have been made to it. This method is called automatically when ohair@286: * {@link SOAPMessage#writeTo(OutputStream)} is called. However, if ohair@286: * changes are made to a message that was received or to one that has ohair@286: * already been sent, the method saveChanges needs to be ohair@286: * called explicitly in order to save the changes. The method saveChanges ohair@286: * also generates any changes that can be read back (for example, a ohair@286: * MessageId in profiles that support a message id). All MIME headers in a ohair@286: * message that is created for sending purposes are guaranteed to have ohair@286: * valid values only after saveChanges has been called. ohair@286: *

ohair@286: * In addition, this method marks the point at which the data from all ohair@286: * constituent AttachmentPart objects are pulled into the ohair@286: * message. ohair@286: *

ohair@286: * ohair@286: * @exception SOAPException if there was a problem saving ohair@286: * changes to this message. ohair@286: */ ohair@286: public abstract void saveChanges() throws SOAPException; ohair@286: ohair@286: /** ohair@286: * Indicates whether this SOAPMessage object needs to have ohair@286: * the method saveChanges called on it. ohair@286: * ohair@286: * @return true if saveChanges needs to be ohair@286: * called; false otherwise. ohair@286: */ ohair@286: public abstract boolean saveRequired(); ohair@286: ohair@286: /** ohair@286: * Writes this SOAPMessage object to the given output ohair@286: * stream. The externalization format is as defined by the SOAP 1.1 with ohair@286: * Attachments specification. ohair@286: *

ohair@286: * If there are no attachments, just an XML stream is written out. For ohair@286: * those messages that have attachments, writeTo writes a ohair@286: * MIME-encoded byte stream. ohair@286: *

ohair@286: * Note that this method does not write the transport-specific MIME Headers ohair@286: * of the Message ohair@286: * ohair@286: * @param out ohair@286: * the OutputStream object to which this SOAPMessage ohair@286: * object will be written ohair@286: * @exception IOException ohair@286: * if an I/O error occurs ohair@286: * @exception SOAPException ohair@286: * if there was a problem in externalizing this SOAP message ohair@286: */ ohair@286: public abstract void writeTo(OutputStream out) ohair@286: throws SOAPException, IOException; ohair@286: ohair@286: /** ohair@286: * Associates the specified value with the specified property. If there was ohair@286: * already a value associated with this property, the old value is ohair@286: * replaced. ohair@286: *

ohair@286: * The valid property names include ohair@286: * {@link SOAPMessage#WRITE_XML_DECLARATION} and ohair@286: * {@link SOAPMessage#CHARACTER_SET_ENCODING}. All of these standard SAAJ ohair@286: * properties are prefixed by "javax.xml.soap". Vendors may also add ohair@286: * implementation specific properties. These properties must be prefixed ohair@286: * with package names that are unique to the vendor. ohair@286: *

ohair@286: * Setting the property WRITE_XML_DECLARATION to "true" ohair@286: * will cause an XML Declaration to be written out at the start of the SOAP ohair@286: * message. The default value of "false" suppresses this declaration. ohair@286: *

ohair@286: * The property CHARACTER_SET_ENCODING defaults to the value ohair@286: * "utf-8" which causes the SOAP message to be encoded using ohair@286: * UTF-8. Setting CHARACTER_SET_ENCODING to "utf-16" ohair@286: * causes the SOAP message to be encoded using UTF-16. ohair@286: *

ohair@286: * Some implementations may allow encodings in addition to UTF-8 and ohair@286: * UTF-16. Refer to your vendor's documentation for details. ohair@286: * ohair@286: * @param property ohair@286: * the property with which the specified value is to be ohair@286: * associated. ohair@286: * @param value ohair@286: * the value to be associated with the specified property ohair@286: * @exception SOAPException ohair@286: * if the property name is not recognized. ohair@286: * @since SAAJ 1.2 ohair@286: */ ohair@286: public void setProperty(String property, Object value) ohair@286: throws SOAPException { ohair@286: throw new UnsupportedOperationException("setProperty must be overridden by all subclasses of SOAPMessage"); ohair@286: } ohair@286: ohair@286: /** ohair@286: * Retrieves value of the specified property. ohair@286: * ohair@286: * @param property ohair@286: * the name of the property to retrieve ohair@286: * @return the value associated with the named property or null ohair@286: * if no such property exists. ohair@286: * @exception SOAPException ohair@286: * if the property name is not recognized. ohair@286: * @since SAAJ 1.2 ohair@286: */ ohair@286: public Object getProperty(String property) throws SOAPException { ohair@286: throw new UnsupportedOperationException("getProperty must be overridden by all subclasses of SOAPMessage"); ohair@286: } ohair@286: }