aoqi@0: /*
aoqi@0: * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved.
aoqi@0: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
aoqi@0: *
aoqi@0: * This code is free software; you can redistribute it and/or modify it
aoqi@0: * under the terms of the GNU General Public License version 2 only, as
aoqi@0: * published by the Free Software Foundation. Oracle designates this
aoqi@0: * particular file as subject to the "Classpath" exception as provided
aoqi@0: * by Oracle in the LICENSE file that accompanied this code.
aoqi@0: *
aoqi@0: * This code is distributed in the hope that it will be useful, but WITHOUT
aoqi@0: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
aoqi@0: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
aoqi@0: * version 2 for more details (a copy is included in the LICENSE file that
aoqi@0: * accompanied this code).
aoqi@0: *
aoqi@0: * You should have received a copy of the GNU General Public License version
aoqi@0: * 2 along with this work; if not, write to the Free Software Foundation,
aoqi@0: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
aoqi@0: *
aoqi@0: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
aoqi@0: * or visit www.oracle.com if you need additional information or have any
aoqi@0: * questions.
aoqi@0: */
aoqi@0:
aoqi@0: package javax.xml.soap;
aoqi@0:
aoqi@0: import java.util.Iterator;
aoqi@0:
aoqi@0: import javax.xml.transform.Source;
aoqi@0:
aoqi@0: /**
aoqi@0: * The container for the SOAP-specific portion of a SOAPMessage
aoqi@0: * object. All messages are required to have a SOAP part, so when a
aoqi@0: * SOAPMessage
object is created, it will automatically
aoqi@0: * have a SOAPPart
object.
aoqi@0: *
aoqi@0: * A SOAPPart
object is a MIME part and has the MIME headers
aoqi@0: * Content-Id, Content-Location, and Content-Type. Because the value of
aoqi@0: * Content-Type must be "text/xml", a SOAPPart
object automatically
aoqi@0: * has a MIME header of Content-Type with its value set to "text/xml".
aoqi@0: * The value must be "text/xml" because content in the SOAP part of a
aoqi@0: * message must be in XML format. Content that is not of type "text/xml"
aoqi@0: * must be in an AttachmentPart
object rather than in the
aoqi@0: * SOAPPart
object.
aoqi@0: *
aoqi@0: * When a message is sent, its SOAP part must have the MIME header Content-Type aoqi@0: * set to "text/xml". Or, from the other perspective, the SOAP part of any aoqi@0: * message that is received must have the MIME header Content-Type with a aoqi@0: * value of "text/xml". aoqi@0: *
aoqi@0: * A client can access the SOAPPart
object of a
aoqi@0: * SOAPMessage
object by
aoqi@0: * calling the method SOAPMessage.getSOAPPart
. The
aoqi@0: * following line of code, in which message
is a
aoqi@0: * SOAPMessage
object, retrieves the SOAP part of a message.
aoqi@0: *
aoqi@0: * SOAPPart soapPart = message.getSOAPPart(); aoqi@0: *aoqi@0: *
aoqi@0: * A SOAPPart
object contains a SOAPEnvelope
object,
aoqi@0: * which in turn contains a SOAPBody
object and a
aoqi@0: * SOAPHeader
object.
aoqi@0: * The SOAPPart
method getEnvelope
can be used
aoqi@0: * to retrieve the SOAPEnvelope
object.
aoqi@0: *
aoqi@0: */
aoqi@0: public abstract class SOAPPart implements org.w3c.dom.Document, Node {
aoqi@0:
aoqi@0: /**
aoqi@0: * Gets the SOAPEnvelope
object associated with this
aoqi@0: * SOAPPart
object. Once the SOAP envelope is obtained, it
aoqi@0: * can be used to get its contents.
aoqi@0: *
aoqi@0: * @return the SOAPEnvelope
object for this
aoqi@0: * SOAPPart
object
aoqi@0: * @exception SOAPException if there is a SOAP error
aoqi@0: */
aoqi@0: public abstract SOAPEnvelope getEnvelope() throws SOAPException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Retrieves the value of the MIME header whose name is "Content-Id".
aoqi@0: *
aoqi@0: * @return a String
giving the value of the MIME header
aoqi@0: * named "Content-Id"
aoqi@0: * @see #setContentId
aoqi@0: */
aoqi@0: public String getContentId() {
aoqi@0: String[] values = getMimeHeader("Content-Id");
aoqi@0: if (values != null && values.length > 0)
aoqi@0: return values[0];
aoqi@0: return null;
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * Retrieves the value of the MIME header whose name is "Content-Location".
aoqi@0: *
aoqi@0: * @return a String
giving the value of the MIME header whose
aoqi@0: * name is "Content-Location"
aoqi@0: * @see #setContentLocation
aoqi@0: */
aoqi@0: public String getContentLocation() {
aoqi@0: String[] values = getMimeHeader("Content-Location");
aoqi@0: if (values != null && values.length > 0)
aoqi@0: return values[0];
aoqi@0: return null;
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * Sets the value of the MIME header named "Content-Id"
aoqi@0: * to the given String
.
aoqi@0: *
aoqi@0: * @param contentId a String
giving the value of the MIME
aoqi@0: * header "Content-Id"
aoqi@0: *
aoqi@0: * @exception IllegalArgumentException if there is a problem in
aoqi@0: * setting the content id
aoqi@0: * @see #getContentId
aoqi@0: */
aoqi@0: public void setContentId(String contentId)
aoqi@0: {
aoqi@0: setMimeHeader("Content-Id", contentId);
aoqi@0: }
aoqi@0: /**
aoqi@0: * Sets the value of the MIME header "Content-Location"
aoqi@0: * to the given String
.
aoqi@0: *
aoqi@0: * @param contentLocation a String
giving the value
aoqi@0: * of the MIME
aoqi@0: * header "Content-Location"
aoqi@0: * @exception IllegalArgumentException if there is a problem in
aoqi@0: * setting the content location.
aoqi@0: * @see #getContentLocation
aoqi@0: */
aoqi@0: public void setContentLocation(String contentLocation)
aoqi@0: {
aoqi@0: setMimeHeader("Content-Location", contentLocation);
aoqi@0: }
aoqi@0: /**
aoqi@0: * Removes all MIME headers that match the given name.
aoqi@0: *
aoqi@0: * @param header a String
giving the name of the MIME header(s) to
aoqi@0: * be removed
aoqi@0: */
aoqi@0: public abstract void removeMimeHeader(String header);
aoqi@0:
aoqi@0: /**
aoqi@0: * Removes all the MimeHeader
objects for this
aoqi@0: * SOAPEnvelope
object.
aoqi@0: */
aoqi@0: public abstract void removeAllMimeHeaders();
aoqi@0:
aoqi@0: /**
aoqi@0: * Gets all the values of the MimeHeader
object
aoqi@0: * in this SOAPPart
object that
aoqi@0: * is identified by the given String
.
aoqi@0: *
aoqi@0: * @param name the name of the header; example: "Content-Type"
aoqi@0: * @return a String
array giving all the values for the
aoqi@0: * specified header
aoqi@0: * @see #setMimeHeader
aoqi@0: */
aoqi@0: public abstract String[] getMimeHeader(String name);
aoqi@0:
aoqi@0: /**
aoqi@0: * Changes the first header entry that matches the given header name
aoqi@0: * so that its value is the given value, adding a new header with the
aoqi@0: * given name and value if no
aoqi@0: * existing header is a match. If there is a match, this method clears
aoqi@0: * all existing values for the first header that matches and sets the
aoqi@0: * given value instead. If more than one header has
aoqi@0: * the given name, this method removes all of the matching headers after
aoqi@0: * the first one.
aoqi@0: *
aoqi@0: * Note that RFC822 headers can contain only US-ASCII characters.
aoqi@0: *
aoqi@0: * @param name a String
giving the header name
aoqi@0: * for which to search
aoqi@0: * @param value a String
giving the value to be set.
aoqi@0: * This value will be substituted for the current value(s)
aoqi@0: * of the first header that is a match if there is one.
aoqi@0: * If there is no match, this value will be the value for
aoqi@0: * a new MimeHeader
object.
aoqi@0: *
aoqi@0: * @exception IllegalArgumentException if there was a problem with
aoqi@0: * the specified mime header name or value
aoqi@0: * @see #getMimeHeader
aoqi@0: */
aoqi@0: public abstract void setMimeHeader(String name, String value);
aoqi@0:
aoqi@0: /**
aoqi@0: * Creates a MimeHeader
object with the specified
aoqi@0: * name and value and adds it to this SOAPPart
object.
aoqi@0: * If a MimeHeader
with the specified name already
aoqi@0: * exists, this method adds the specified value to the already
aoqi@0: * existing value(s).
aoqi@0: *
aoqi@0: * Note that RFC822 headers can contain only US-ASCII characters.
aoqi@0: *
aoqi@0: * @param name a String
giving the header name
aoqi@0: * @param value a String
giving the value to be set
aoqi@0: * or added
aoqi@0: * @exception IllegalArgumentException if there was a problem with
aoqi@0: * the specified mime header name or value
aoqi@0: */
aoqi@0: public abstract void addMimeHeader(String name, String value);
aoqi@0:
aoqi@0: /**
aoqi@0: * Retrieves all the headers for this SOAPPart
object
aoqi@0: * as an iterator over the MimeHeader
objects.
aoqi@0: *
aoqi@0: * @return an Iterator
object with all of the Mime
aoqi@0: * headers for this SOAPPart
object
aoqi@0: */
aoqi@0: public abstract Iterator getAllMimeHeaders();
aoqi@0:
aoqi@0: /**
aoqi@0: * Retrieves all MimeHeader
objects that match a name in
aoqi@0: * the given array.
aoqi@0: *
aoqi@0: * @param names a String
array with the name(s) of the
aoqi@0: * MIME headers to be returned
aoqi@0: * @return all of the MIME headers that match one of the names in the
aoqi@0: * given array, returned as an Iterator
object
aoqi@0: */
aoqi@0: public abstract Iterator getMatchingMimeHeaders(String[] names);
aoqi@0:
aoqi@0: /**
aoqi@0: * Retrieves all MimeHeader
objects whose name does
aoqi@0: * not match a name in the given array.
aoqi@0: *
aoqi@0: * @param names a String
array with the name(s) of the
aoqi@0: * MIME headers not to be returned
aoqi@0: * @return all of the MIME headers in this SOAPPart
object
aoqi@0: * except those that match one of the names in the
aoqi@0: * given array. The nonmatching MIME headers are returned as an
aoqi@0: * Iterator
object.
aoqi@0: */
aoqi@0: public abstract Iterator getNonMatchingMimeHeaders(String[] names);
aoqi@0:
aoqi@0: /**
aoqi@0: * Sets the content of the SOAPEnvelope
object with the data
aoqi@0: * from the given Source
object. This Source
aoqi@0: * must contain a valid SOAP document.
aoqi@0: *
aoqi@0: * @param source the javax.xml.transform.Source
object with the
aoqi@0: * data to be set
aoqi@0: *
aoqi@0: * @exception SOAPException if there is a problem in setting the source
aoqi@0: * @see #getContent
aoqi@0: */
aoqi@0: public abstract void setContent(Source source) throws SOAPException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns the content of the SOAPEnvelope as a JAXP Source
aoqi@0: * object.
aoqi@0: *
aoqi@0: * @return the content as a javax.xml.transform.Source
object
aoqi@0: *
aoqi@0: * @exception SOAPException if the implementation cannot convert
aoqi@0: * the specified Source
object
aoqi@0: * @see #setContent
aoqi@0: */
aoqi@0: public abstract Source getContent() throws SOAPException;
aoqi@0: }