soapmessage.java

开源的axis2框架的源码。用于开发WEBSERVER

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package javax.xml.soap;

import javax.activation.DataHandler;
import java.io.IOException;
import java.io.OutputStream;
import java.util.Iterator;

/**
 * <P>The root class for all SOAP messages. As transmitted on the "wire", a SOAP message is an XML
 * document or a MIME message whose first body part is an XML/SOAP document.</P>
 * <p/>
 * <P>A <CODE>SOAPMessage</CODE> object consists of a SOAP part and optionally one or more
 * attachment parts. The SOAP part for a <CODE>SOAPMessage</CODE> object is a <CODE>SOAPPart</CODE>
 * object, which contains information used for message routing and identification, and which can
 * contain application-specific content. All data in the SOAP Part of a message must be in XML
 * format.</P>
 * <p/>
 * <P>A new <CODE>SOAPMessage</CODE> object contains the following by default:</P>
 * <p/>
 * <UL> <LI>A <CODE>SOAPPart</CODE> object</LI>
 * <p/>
 * <LI>A <CODE>SOAPEnvelope</CODE> object</LI>
 * <p/>
 * <LI>A <CODE>SOAPBody</CODE> object</LI>
 * <p/>
 * <LI>A <CODE>SOAPHeader</CODE> object</LI> </UL> The SOAP part of a message can be retrieved by
 * calling the method <CODE>SOAPMessage.getSOAPPart()</CODE>. The <CODE> SOAPEnvelope</CODE> object
 * is retrieved from the <CODE> SOAPPart</CODE> object, and the <CODE>SOAPEnvelope</CODE> object is
 * used to retrieve the <CODE>SOAPBody</CODE> and <CODE> SOAPHeader</CODE> objects. <PRE> SOAPPart
 * sp = message.getSOAPPart(); SOAPEnvelope se = sp.getEnvelope(); SOAPBody sb = se.getBody();
 * SOAPHeader sh = se.getHeader(); </PRE>
 * <p/>
 * <P>In addition to the mandatory <CODE>SOAPPart</CODE> object, a <CODE>SOAPMessage</CODE> object
 * may contain zero or more <CODE> AttachmentPart</CODE> objects, each of which contains
 * application-specific data. The <CODE>SOAPMessage</CODE> interface provides methods for creating
 * <CODE> AttachmentPart</CODE> objects and also for adding them to a <CODE>SOAPMessage</CODE>
 * object. A party that has received a <CODE>SOAPMessage</CODE> object can examine its contents by
 * retrieving individual attachment parts.</P>
 * <p/>
 * <P>Unlike the rest of a SOAP message, an attachment is not required to be in XML format and can
 * therefore be anything from simple text to an image file. Consequently, any message content that
 * is not in XML format must be in an <CODE> AttachmentPart</CODE> object.</P>
 * <p/>
 * <P>A <CODE>MessageFactory</CODE> object creates new <CODE> SOAPMessage</CODE> objects. If the
 * <CODE>MessageFactory</CODE> object was initialized with a messaging Profile, it produces
 * <CODE>SOAPMessage</CODE> objects that conform to that Profile. For example, a
 * <CODE>SOAPMessage</CODE> object created by a <CODE>MessageFactory</CODE> object initialized with
 * the ebXML Profile will have the appropriate ebXML headers.</P>
 *
 * @see MessageFactory MessageFactory
 * @see AttachmentPart AttachmentPart
 */
public abstract class SOAPMessage {

    public SOAPMessage() {
    }

    /**
     * Retrieves a description of this <CODE>SOAPMessage</CODE> object's content.
     *
     * @return a <CODE>String</CODE> describing the content of this message or <CODE>null</CODE> if
     *         no description has been set
     * @see #setContentDescription(String) setContentDescription(java.lang.String)
     */
    public abstract String getContentDescription();

    /**
     * Sets the description of this <CODE>SOAPMessage</CODE> object's content with the given
     * description.
     *
     * @param description a <CODE>String</CODE> describing the content of this message
     * @see #getContentDescription() getContentDescription()
     */
    public abstract void setContentDescription(String description);

    /**
     * Gets the SOAP part of this <CODE>SOAPMessage</CODE> object.
     * <p/>
     * <p/>
     * <P>If a <CODE>SOAPMessage</CODE> object contains one or more attachments, the SOAP Part must
     * be the first MIME body part in the message.</P>
     *
     * @return the <CODE>SOAPPart</CODE> object for this <CODE> SOAPMessage</CODE> object
     */
    public abstract SOAPPart getSOAPPart();

    /**
     * Removes all <CODE>AttachmentPart</CODE> objects that have been added to this
     * <CODE>SOAPMessage</CODE> object.
     * <p/>
     * <P>This method does not touch the SOAP part.</P>
     */
    public abstract void removeAllAttachments();

    /**
     * Gets a count of the number of attachments in this message. This count does not include the
     * SOAP part.
     *
     * @return the number of <CODE>AttachmentPart</CODE> objects that are part of this
     *         <CODE>SOAPMessage</CODE> object
     */
    public abstract int countAttachments();

    /**
     * Retrieves all the <CODE>AttachmentPart</CODE> objects that are part of this
     * <CODE>SOAPMessage</CODE> object.
     *
     * @return an iterator over all the attachments in this message
     */
    public abstract Iterator getAttachments();

    /**
     * Retrieves all the <CODE>AttachmentPart</CODE> objects that have header entries that match the
     * specified headers. Note that a returned attachment could have headers in addition to those
     * specified.
     *
     * @param headers a <CODE>MimeHeaders</CODE> object containing the MIME headers for which to
     *                search
     * @return an iterator over all attachments that have a header that matches one of the given
     *         headers
     */
    public abstract Iterator getAttachments(MimeHeaders headers);

    /**
     * Adds the given <CODE>AttachmentPart</CODE> object to this <CODE>SOAPMessage</CODE> object. An
     * <CODE> AttachmentPart</CODE> object must be created before it can be added to a message.
     *
     * @param attachmentpart an <CODE> AttachmentPart</CODE> object that is to become part of this
     *                       <CODE>SOAPMessage</CODE> object
     * @throws IllegalArgumentException
     *
     */
    public abstract void addAttachmentPart(AttachmentPart attachmentpart);

    /**
     * Creates a new empty <CODE>AttachmentPart</CODE> object. Note that the method
     * <CODE>addAttachmentPart</CODE> must be called with this new <CODE>AttachmentPart</CODE>
     * object as the parameter in order for it to become an attachment to this
     * <CODE>SOAPMessage</CODE> object.
     *
     * @return a new <CODE>AttachmentPart</CODE> object that can be populated and added to this
     *         <CODE>SOAPMessage</CODE> object
     */
    public abstract AttachmentPart createAttachmentPart();

    /**
     * Creates an <CODE>AttachmentPart</CODE> object and populates it using the given
     * <CODE>DataHandler</CODE> object.
     *
     * @param datahandler the <CODE> javax.activation.DataHandler</CODE> object that will generate
     *                    the content for this <CODE>SOAPMessage</CODE> object
     * @return a new <CODE>AttachmentPart</CODE> object that contains data generated by the given