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