1 /*
   2  * Copyright (c) 2004, 2015, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.soap;
  27 
  28 import java.util.Iterator;
  29 
  30 import javax.xml.transform.Source;
  31 
  32 /**
  33  * The container for the SOAP-specific portion of a {@code SOAPMessage}
  34  * object. All messages are required to have a SOAP part, so when a
  35  * {@code SOAPMessage} object is created, it will automatically
  36  * have a {@code SOAPPart} object.
  37  * <P>
  38  * A {@code SOAPPart} object is a MIME part and has the MIME headers
  39  * Content-Id, Content-Location, and Content-Type.  Because the value of
  40  * Content-Type must be "text/xml", a {@code SOAPPart} object automatically
  41  * has a MIME header of Content-Type with its value set to "text/xml".
  42  * The value must be "text/xml" because content in the SOAP part of a
  43  * message must be in XML format.  Content that is not of type "text/xml"
  44  * must be in an {@code AttachmentPart} object rather than in the
  45  * {@code SOAPPart} object.
  46  * <P>
  47  * When a message is sent, its SOAP part must have the MIME header Content-Type
  48  * set to "text/xml". Or, from the other perspective, the SOAP part of any
  49  * message that is received must have the MIME header Content-Type with a
  50  * value of "text/xml".
  51  * <P>
  52  * A client can access the {@code SOAPPart} object of a
  53  * {@code SOAPMessage} object by
  54  * calling the method {@code SOAPMessage.getSOAPPart}. The
  55  * following  line of code, in which {@code message} is a
  56  * {@code SOAPMessage} object, retrieves the SOAP part of a message.
  57  * <pre>{@code
  58  *   SOAPPart soapPart = message.getSOAPPart();
  59  * }</pre>
  60  * <P>
  61  * A {@code SOAPPart} object contains a {@code SOAPEnvelope} object,
  62  * which in turn contains a {@code SOAPBody} object and a
  63  * {@code SOAPHeader} object.
  64  * The {@code SOAPPart} method {@code getEnvelope} can be used
  65  * to retrieve the {@code SOAPEnvelope} object.
  66  *
  67  * @since 1.6
  68  */
  69 public abstract class SOAPPart implements org.w3c.dom.Document, Node {
  70 
  71     /**
  72      * Gets the {@code SOAPEnvelope} object associated with this
  73      * {@code SOAPPart} object. Once the SOAP envelope is obtained, it
  74      * can be used to get its contents.
  75      *
  76      * @return the {@code SOAPEnvelope} object for this
  77      *           {@code SOAPPart} object
  78      * @exception SOAPException if there is a SOAP error
  79      */
  80     public abstract SOAPEnvelope getEnvelope() throws SOAPException;
  81 
  82     /**
  83      * Retrieves the value of the MIME header whose name is "Content-Id".
  84      *
  85      * @return a {@code String} giving the value of the MIME header
  86      *         named "Content-Id"
  87      * @see #setContentId
  88      */
  89     public String getContentId() {
  90         String[] values = getMimeHeader("Content-Id");
  91         if (values != null && values.length > 0)
  92             return values[0];
  93         return null;
  94     }
  95 
  96     /**
  97      * Retrieves the value of the MIME header whose name is "Content-Location".
  98      *
  99      * @return a {@code String} giving the value of the MIME header whose
 100      *          name is "Content-Location"
 101      * @see #setContentLocation
 102      */
 103     public String getContentLocation() {
 104         String[] values = getMimeHeader("Content-Location");
 105         if (values != null && values.length > 0)
 106             return values[0];
 107         return null;
 108     }
 109 
 110     /**
 111      * Sets the value of the MIME header named "Content-Id"
 112      * to the given {@code String}.
 113      *
 114      * @param contentId a {@code String} giving the value of the MIME
 115      *        header "Content-Id"
 116      *
 117      * @exception IllegalArgumentException if there is a problem in
 118      * setting the content id
 119      * @see #getContentId
 120      */
 121     public void setContentId(String contentId)
 122     {
 123         setMimeHeader("Content-Id", contentId);
 124     }
 125     /**
 126      * Sets the value of the MIME header "Content-Location"
 127      * to the given {@code String}.
 128      *
 129      * @param contentLocation a {@code String} giving the value
 130      *        of the MIME
 131      *        header "Content-Location"
 132      * @exception IllegalArgumentException if there is a problem in
 133      *            setting the content location.
 134      * @see #getContentLocation
 135      */
 136     public void setContentLocation(String contentLocation)
 137     {
 138         setMimeHeader("Content-Location", contentLocation);
 139     }
 140     /**
 141      * Removes all MIME headers that match the given name.
 142      *
 143      * @param header a {@code String} giving the name of the MIME header(s) to
 144      *               be removed
 145      */
 146     public abstract void removeMimeHeader(String header);
 147 
 148     /**
 149      * Removes all the {@code MimeHeader} objects for this
 150      * {@code SOAPEnvelope} object.
 151      */
 152     public abstract void removeAllMimeHeaders();
 153 
 154     /**
 155      * Gets all the values of the {@code MimeHeader} object
 156      * in this {@code SOAPPart} object that
 157      * is identified by the given {@code String}.
 158      *
 159      * @param name the name of the header; example: "Content-Type"
 160      * @return a {@code String} array giving all the values for the
 161      *         specified header
 162      * @see #setMimeHeader
 163      */
 164     public abstract String[] getMimeHeader(String name);
 165 
 166     /**
 167      * Changes the first header entry that matches the given header name
 168      * so that its value is the given value, adding a new header with the
 169      * given name and value if no
 170      * existing header is a match. If there is a match, this method clears
 171      * all existing values for the first header that matches and sets the
 172      * given value instead. If more than one header has
 173      * the given name, this method removes all of the matching headers after
 174      * the first one.
 175      * <P>
 176      * Note that RFC822 headers can contain only US-ASCII characters.
 177      *
 178      * @param   name    a {@code String} giving the header name
 179      *                  for which to search
 180      * @param   value   a {@code String} giving the value to be set.
 181      *                  This value will be substituted for the current value(s)
 182      *                  of the first header that is a match if there is one.
 183      *                  If there is no match, this value will be the value for
 184      *                  a new {@code MimeHeader} object.
 185      *
 186      * @exception IllegalArgumentException if there was a problem with
 187      *            the specified mime header name or value
 188      * @see #getMimeHeader
 189      */
 190     public abstract void setMimeHeader(String name, String value);
 191 
 192     /**
 193      * Creates a {@code MimeHeader} object with the specified
 194      * name and value and adds it to this {@code SOAPPart} object.
 195      * If a {@code MimeHeader} with the specified name already
 196      * exists, this method adds the specified value to the already
 197      * existing value(s).
 198      * <P>
 199      * Note that RFC822 headers can contain only US-ASCII characters.
 200      *
 201      * @param   name    a {@code String} giving the header name
 202      * @param   value   a {@code String} giving the value to be set
 203      *                  or added
 204      * @exception IllegalArgumentException if there was a problem with
 205      *            the specified mime header name or value
 206      */
 207     public abstract void addMimeHeader(String name, String value);
 208 
 209     /**
 210      * Retrieves all the headers for this {@code SOAPPart} object
 211      * as an iterator over the {@code MimeHeader} objects.
 212      *
 213      * @return  an {@code Iterator} object with all of the Mime
 214      *          headers for this {@code SOAPPart} object
 215      */
 216     public abstract Iterator getAllMimeHeaders();
 217 
 218     /**
 219      * Retrieves all {@code MimeHeader} objects that match a name in
 220      * the given array.
 221      *
 222      * @param names a {@code String} array with the name(s) of the
 223      *        MIME headers to be returned
 224      * @return  all of the MIME headers that match one of the names in the
 225      *           given array, returned as an {@code Iterator} object
 226      */
 227     public abstract Iterator getMatchingMimeHeaders(String[] names);
 228 
 229     /**
 230      * Retrieves all {@code MimeHeader} objects whose name does
 231      * not match a name in the given array.
 232      *
 233      * @param names a {@code String} array with the name(s) of the
 234      *        MIME headers not to be returned
 235      * @return  all of the MIME headers in this {@code SOAPPart} object
 236      *          except those that match one of the names in the
 237      *           given array.  The nonmatching MIME headers are returned as an
 238      *           {@code Iterator} object.
 239      */
 240     public abstract Iterator getNonMatchingMimeHeaders(String[] names);
 241 
 242     /**
 243      * Sets the content of the {@code SOAPEnvelope} object with the data
 244      * from the given {@code Source} object. This {@code Source}
 245      * must contain a valid SOAP document.
 246      *
 247      * @param source the {@code javax.xml.transform.Source} object with the
 248      *        data to be set
 249      *
 250      * @exception SOAPException if there is a problem in setting the source
 251      * @see #getContent
 252      */
 253     public abstract void setContent(Source source) throws SOAPException;
 254 
 255     /**
 256      * Returns the content of the SOAPEnvelope as a JAXP {@code Source}
 257      * object.
 258      *
 259      * @return the content as a {@code javax.xml.transform.Source} object
 260      *
 261      * @exception SOAPException if the implementation cannot convert
 262      *                          the specified {@code Source} object
 263      * @see #setContent
 264      */
 265     public abstract Source getContent() throws SOAPException;
 266 }