org.apache.xmlbeans.impl.soap.SOAPPart Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-xmlbeans Show documentation
The Apache Commons Codec package contains simple encoder and decoders for various formats such as Base64 and Hexadecimal. In addition to these widely used encoders and decoders, the codec package also maintains a collection of phonetic encoding utilities.
The newest version!
/*   Copyright 2004 The Apache Software Foundation
 *
 *   Licensed 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 org.apache.xmlbeans.impl.soap;

import javax.xml.transform.Source;
import java.util.Iterator;

/**
 * The container for the SOAP-specific portion of a 
 * SOAPMessage object. All messages are required to have a
 * SOAP part, so when a SOAPMessage object is
 * created, it will automatically have a SOAPPart
 * object.
 *
 * A SOAPPart object is a MIME part and has the
 * MIME headers Content-Id, Content-Location, and Content-Type.
 * Because the value of Content-Type must be "text/xml", a 
 * SOAPPart object automatically has a MIME header of
 * Content-Type with its value set to "text/xml". The value must
 * be "text/xml" because content in the SOAP part of a message
 * must be in XML format. Content that is not of type "text/xml"
 * must be in an AttachmentPart object rather than in
 * the SOAPPart object.
 *
 * When a message is sent, its SOAP part must have the MIME
 * header Content-Type set to "text/xml". Or, from the other
 * perspective, the SOAP part of any message that is received must
 * have the MIME header Content-Type with a value of
 * "text/xml".
 *
 * A client can access the SOAPPart object of a
 * SOAPMessage object by calling the method 
 * SOAPMessage.getSOAPPart. The following line of code, in
 * which message is a SOAPMessage
 * object, retrieves the SOAP part of a message.
 *  * SOAPPart soapPart = message.getSOAPPart();
 * 
 *
 * A SOAPPart object contains a 
 * SOAPEnvelope object, which in turn contains a 
 * SOAPBody object and a SOAPHeader object.
 * The SOAPPart method getEnvelope can
 * be used to retrieve the SOAPEnvelope object.
 */
public abstract class SOAPPart implements org.w3c.dom.Document {

    public SOAPPart() {}

    /**
     * Gets the SOAPEnvelope object associated with
     * this SOAPPart object. Once the SOAP envelope is
     * obtained, it can be used to get its contents.
     * @return the SOAPEnvelope object for this 
     *     SOAPPart object
     * @throws  SOAPException if there is a SOAP error
     */
    public abstract SOAPEnvelope getEnvelope() throws SOAPException;

    /**
     * Retrieves the value of the MIME header whose name is
     * "Content-Id".
     * @return  a String giving the value of the MIME
     *     header named "Content-Id"
     * @see #setContentId(java.lang.String) setContentId(java.lang.String)
     */
    public String getContentId() {

        String as[] = getMimeHeader("Content-Id");

        if (as != null && as.length > 0) {
            return as[0];
        } else {
            return null;
        }
    }

    /**
     * Retrieves the value of the MIME header whose name is
     * "Content-Location".
     * @return a String giving the value of the MIME
     *     header whose name is "Content-Location"
     * @see #setContentLocation(java.lang.String) setContentLocation(java.lang.String)
     */
    public String getContentLocation() {

        String as[] = getMimeHeader("Content-Location");

        if (as != null && as.length > 0) {
            return as[0];
        } else {
            return null;
        }
    }

    /**
     * Sets the value of the MIME header named "Content-Id" to
     * the given String.
     * @param  contentId  a String giving
     *     the value of the MIME header "Content-Id"
     * @throws java.lang.IllegalArgumentException if
     *     there is a problem in setting the content id
     * @see #getContentId() getContentId()
     */
    public void setContentId(String contentId) {
        setMimeHeader("Content-Id", contentId);
    }

    /**
     * Sets the value of the MIME header "Content-Location" to
     * the given String.
     * @param  contentLocation a String
     *     giving the value of the MIME header
     *     "Content-Location"
     * @throws java.lang.IllegalArgumentException if
     *     there is a problem in setting the content location.
     * @see #getContentLocation() getContentLocation()
     */
    public void setContentLocation(String contentLocation) {
        setMimeHeader("Content-Location", contentLocation);
    }

    /**
     * Removes all MIME headers that match the given name.
     * @param  header  a String giving
     *     the name of the MIME header(s) to be removed
     */
    public abstract void removeMimeHeader(String header);

    /**
     * Removes all the MimeHeader objects for this
     * SOAPEnvelope object.
     */
    public abstract void removeAllMimeHeaders();

    /**
     * Gets all the values of the MimeHeader object
     * in this SOAPPart object that is identified by
     * the given String.
     * @param   name  the name of the header; example:
     *     "Content-Type"
     * @return a String array giving all the values for
     *     the specified header
     * @see #setMimeHeader(java.lang.String, java.lang.String) setMimeHeader(java.lang.String, java.lang.String)
     */
    public abstract String[] getMimeHeader(String name);

    /**
     * Changes the first header entry that matches the given
     *   header name so that its value is the given value, adding a
     *   new header with the given name and value if no existing
     *   header is a match. If there is a match, this method clears
     *   all existing values for the first header that matches and
     *   sets the given value instead. If more than one header has
     *   the given name, this method removes all of the matching
     *   headers after the first one.
     *
     *   Note that RFC822 headers can contain only US-ASCII
     *   characters.
     * @param  name a String giving the
     *     header name for which to search
     * @param  value a String giving the
     *     value to be set. This value will be substituted for the
     *     current value(s) of the first header that is a match if
     *     there is one. If there is no match, this value will be
     *     the value for a new MimeHeader object.
     * @throws java.lang.IllegalArgumentException if
     *     there was a problem with the specified mime header name
     *     or value
     * @throws java.lang.IllegalArgumentException if there was a problem with the specified mime header name or value
     * @see #getMimeHeader(java.lang.String) getMimeHeader(java.lang.String)
     */
    public abstract void setMimeHeader(String name, String value);

    /**
     *  Creates a MimeHeader object with the specified
     *   name and value and adds it to this SOAPPart
     *   object. If a MimeHeader with the specified
     *   name already exists, this method adds the specified value
     *   to the already existing value(s).
     *
     *   Note that RFC822 headers can contain only US-ASCII
     *   characters.
     *
     * @param  name a String giving the
     *     header name
     * @param  value a String giving the
     *     value to be set or added
     * @throws java.lang.IllegalArgumentException if
     * there was a problem with the specified mime header name
     *     or value
     */
    public abstract void addMimeHeader(String name, String value);

    /**
     * Retrieves all the headers for this SOAPPart
     * object as an iterator over the MimeHeader
     * objects.
     * @return an Iterator object with all of the Mime
     *     headers for this SOAPPart object
     */
    public abstract Iterator getAllMimeHeaders();

    /**
     * Retrieves all MimeHeader objects that match
     * a name in the given array.
     * @param   names a String array with
     *     the name(s) of the MIME headers to be returned
     * @return all of the MIME headers that match one of the names
     *     in the given array, returned as an Iterator
     *     object
     */
    public abstract Iterator getMatchingMimeHeaders(String names[]);

    /**
     * Retrieves all MimeHeader objects whose name
     * does not match a name in the given array.
     * @param   names a String array with
     *     the name(s) of the MIME headers not to be returned
     * @return all of the MIME headers in this SOAPPart
     *     object except those that match one of the names in the
     *     given array. The nonmatching MIME headers are returned as
     *     an Iterator object.
     */
    public abstract Iterator getNonMatchingMimeHeaders(String names[]);

    /**
     * Sets the content of the SOAPEnvelope object
     * with the data from the given Source object.
     * @param   source javax.xml.transform.Source object with the data to
     *     be set
     * @throws  SOAPException if there is a problem in
     *     setting the source
     * @see #getContent() getContent()
     */
    public abstract void setContent(Source source) throws SOAPException;

    /**
     * Returns the content of the SOAPEnvelope as a JAXP 
     * Source object.
     * @return the content as a 
     *     javax.xml.transform.Source object
     * @throws  SOAPException  if the implementation cannot
     *     convert the specified Source object
     * @see #setContent(javax.xml.transform.Source) setContent(javax.xml.transform.Source)
     */
    public abstract Source getContent() throws SOAPException;
}