1 /*
   2  * Copyright (c) 2004, 2013, 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</code>
  34  * object. All messages are required to have a SOAP part, so when a
  35  * <code>SOAPMessage</code> object is created, it will automatically
  36  * have a <code>SOAPPart</code> object.
  37  *<P>
  38  * A <code>SOAPPart</code> 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</code> 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</code> object rather than in the
  45  * <code>SOAPPart</code> 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</code> object of a
  53  * <code>SOAPMessage</code> object by
  54  * calling the method <code>SOAPMessage.getSOAPPart</code>. The
  55  * following  line of code, in which <code>message</code> is a
  56  * <code>SOAPMessage</code> object, retrieves the SOAP part of a message.
  57  * <PRE>
  58  *   SOAPPart soapPart = message.getSOAPPart();
  59  * </PRE>
  60  * <P>
  61  * A <code>SOAPPart</code> object contains a <code>SOAPEnvelope</code> object,
  62  * which in turn contains a <code>SOAPBody</code> object and a
  63  * <code>SOAPHeader</code> object.
  64  * The <code>SOAPPart</code> method <code>getEnvelope</code> can be used
  65  * to retrieve the <code>SOAPEnvelope</code> object.
  66  * <P>
  67  *
  68  * @since 1.6
  69  */
  70 public abstract class SOAPPart implements org.w3c.dom.Document, Node {
  71 
  72     /**
  73      * Gets the <code>SOAPEnvelope</code> object associated with this
  74      * <code>SOAPPart</code> object. Once the SOAP envelope is obtained, it
  75      * can be used to get its contents.
  76      *
  77      * @return the <code>SOAPEnvelope</code> object for this
  78      *           <code>SOAPPart</code> object
  79      * @exception SOAPException if there is a SOAP error
  80      */
  81     public abstract SOAPEnvelope getEnvelope() throws SOAPException;
  82 
  83     /**
  84      * Retrieves the value of the MIME header whose name is "Content-Id".
  85      *
  86      * @return a <code>String</code> giving the value of the MIME header
  87      *         named "Content-Id"
  88      * @see #setContentId
  89      */
  90     public String getContentId() {
  91         String[] values = getMimeHeader("Content-Id");
  92         if (values != null && values.length > 0)
  93             return values[0];
  94         return null;
  95     }
  96 
  97     /**
  98      * Retrieves the value of the MIME header whose name is "Content-Location".
  99      *
 100      * @return a <code>String</code> giving the value of the MIME header whose
 101      *          name is "Content-Location"
 102      * @see #setContentLocation
 103      */
 104     public String getContentLocation() {
 105         String[] values = getMimeHeader("Content-Location");
 106         if (values != null && values.length > 0)
 107             return values[0];
 108         return null;
 109     }
 110 
 111     /**
 112      * Sets the value of the MIME header named "Content-Id"
 113      * to the given <code>String</code>.
 114      *
 115      * @param contentId a <code>String</code> giving the value of the MIME
 116      *        header "Content-Id"
 117      *
 118      * @exception IllegalArgumentException if there is a problem in
 119      * setting the content id
 120      * @see #getContentId
 121      */
 122     public void setContentId(String contentId)
 123     {
 124         setMimeHeader("Content-Id", contentId);
 125     }
 126     /**
 127      * Sets the value of the MIME header "Content-Location"
 128      * to the given <code>String</code>.
 129      *
 130      * @param contentLocation a <code>String</code> giving the value
 131      *        of the MIME
 132      *        header "Content-Location"
 133      * @exception IllegalArgumentException if there is a problem in
 134      *            setting the content location.
 135      * @see #getContentLocation
 136      */
 137     public void setContentLocation(String contentLocation)
 138     {
 139         setMimeHeader("Content-Location", contentLocation);
 140     }
 141     /**
 142      * Removes all MIME headers that match the given name.
 143      *
 144      * @param header a <code>String</code> giving the name of the MIME header(s) to
 145      *               be removed
 146      */
 147     public abstract void removeMimeHeader(String header);
 148 
 149     /**
 150      * Removes all the <code>MimeHeader</code> objects for this
 151      * <code>SOAPEnvelope</code> object.
 152      */
 153     public abstract void removeAllMimeHeaders();
 154 
 155     /**
 156      * Gets all the values of the <code>MimeHeader</code> object
 157      * in this <code>SOAPPart</code> object that
 158      * is identified by the given <code>String</code>.
 159      *
 160      * @param name the name of the header; example: "Content-Type"
 161      * @return a <code>String</code> array giving all the values for the
 162      *         specified header
 163      * @see #setMimeHeader
 164      */
 165     public abstract String[] getMimeHeader(String name);
 166 
 167     /**
 168      * Changes the first header entry that matches the given header name
 169      * so that its value is the given value, adding a new header with the
 170      * given name and value if no
 171      * existing header is a match. If there is a match, this method clears
 172      * all existing values for the first header that matches and sets the
 173      * given value instead. If more than one header has
 174      * the given name, this method removes all of the matching headers after
 175      * the first one.
 176      * <P>
 177      * Note that RFC822 headers can contain only US-ASCII characters.
 178      *
 179      * @param   name    a <code>String</code> giving the header name
 180      *                  for which to search
 181      * @param   value   a <code>String</code> giving the value to be set.
 182      *                  This value will be substituted for the current value(s)
 183      *                  of the first header that is a match if there is one.
 184      *                  If there is no match, this value will be the value for
 185      *                  a new <code>MimeHeader</code> object.
 186      *
 187      * @exception IllegalArgumentException if there was a problem with
 188      *            the specified mime header name or value
 189      * @see #getMimeHeader
 190      */
 191     public abstract void setMimeHeader(String name, String value);
 192 
 193     /**
 194      * Creates a <code>MimeHeader</code> object with the specified
 195      * name and value and adds it to this <code>SOAPPart</code> object.
 196      * If a <code>MimeHeader</code> with the specified name already
 197      * exists, this method adds the specified value to the already
 198      * existing value(s).
 199      * <P>
 200      * Note that RFC822 headers can contain only US-ASCII characters.
 201      *
 202      * @param   name    a <code>String</code> giving the header name
 203      * @param   value   a <code>String</code> giving the value to be set
 204      *                  or added
 205      * @exception IllegalArgumentException if there was a problem with
 206      *            the specified mime header name or value
 207      */
 208     public abstract void addMimeHeader(String name, String value);
 209 
 210     /**
 211      * Retrieves all the headers for this <code>SOAPPart</code> object
 212      * as an iterator over the <code>MimeHeader</code> objects.
 213      *
 214      * @return  an <code>Iterator</code> object with all of the Mime
 215      *          headers for this <code>SOAPPart</code> object
 216      */
 217     public abstract Iterator getAllMimeHeaders();
 218 
 219     /**
 220      * Retrieves all <code>MimeHeader</code> objects that match a name in
 221      * the given array.
 222      *
 223      * @param names a <code>String</code> array with the name(s) of the
 224      *        MIME headers to be returned
 225      * @return  all of the MIME headers that match one of the names in the
 226      *           given array, returned as an <code>Iterator</code> object
 227      */
 228     public abstract Iterator getMatchingMimeHeaders(String[] names);
 229 
 230     /**
 231      * Retrieves all <code>MimeHeader</code> objects whose name does
 232      * not match a name in the given array.
 233      *
 234      * @param names a <code>String</code> array with the name(s) of the
 235      *        MIME headers not to be returned
 236      * @return  all of the MIME headers in this <code>SOAPPart</code> object
 237      *          except those that match one of the names in the
 238      *           given array.  The nonmatching MIME headers are returned as an
 239      *           <code>Iterator</code> object.
 240      */
 241     public abstract Iterator getNonMatchingMimeHeaders(String[] names);
 242 
 243     /**
 244      * Sets the content of the <code>SOAPEnvelope</code> object with the data
 245      * from the given <code>Source</code> object. This <code>Source</code>
 246      * must contain a valid SOAP document.
 247      *
 248      * @param source the <code>javax.xml.transform.Source</code> object with the
 249      *        data to be set
 250      *
 251      * @exception SOAPException if there is a problem in setting the source
 252      * @see #getContent
 253      */
 254     public abstract void setContent(Source source) throws SOAPException;
 255 
 256     /**
 257      * Returns the content of the SOAPEnvelope as a JAXP <code>Source</code>
 258      * object.
 259      *
 260      * @return the content as a <code>javax.xml.transform.Source</code> object
 261      *
 262      * @exception SOAPException if the implementation cannot convert
 263      *                          the specified <code>Source</code> object
 264      * @see #setContent
 265      */
 266     public abstract Source getContent() throws SOAPException;
 267 }