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