001 /*
002 * $Id: SOAPPart.java,v 1.8 2005/06/20 12:07:05 vj135062 Exp $
003 * $Revision: 1.8 $
004 * $Date: 2005/06/20 12:07:05 $
005 */
006
007 /*
008 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
009 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
010 *
011 * This code is free software; you can redistribute it and/or modify it
012 * under the terms of the GNU General Public License version 2 only, as
013 * published by the Free Software Foundation. Sun designates this
014 * particular file as subject to the "Classpath" exception as provided
015 * by Sun in the LICENSE file that accompanied this code.
016 *
017 * This code is distributed in the hope that it will be useful, but WITHOUT
018 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
019 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
020 * version 2 for more details (a copy is included in the LICENSE file that
021 * accompanied this code).
022 *
023 * You should have received a copy of the GNU General Public License version
024 * 2 along with this work; if not, write to the Free Software Foundation,
025 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
026 *
027 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
028 * CA 95054 USA or visit www.sun.com if you need additional information or
029 * have any questions.
030 */
031 package javax.xml.soap;
032
033 import java.util.Iterator;
034
035 import javax.xml.transform.Source;
036
037 /**
038 * The container for the SOAP-specific portion of a <code>SOAPMessage</code>
039 * object. All messages are required to have a SOAP part, so when a
040 * <code>SOAPMessage</code> object is created, it will automatically
041 * have a <code>SOAPPart</code> object.
042 *<P>
043 * A <code>SOAPPart</code> object is a MIME part and has the MIME headers
044 * Content-Id, Content-Location, and Content-Type. Because the value of
045 * Content-Type must be "text/xml", a <code>SOAPPart</code> object automatically
046 * has a MIME header of Content-Type with its value set to "text/xml".
047 * The value must be "text/xml" because content in the SOAP part of a
048 * message must be in XML format. Content that is not of type "text/xml"
049 * must be in an <code>AttachmentPart</code> object rather than in the
050 * <code>SOAPPart</code> object.
051 * <P>
052 * When a message is sent, its SOAP part must have the MIME header Content-Type
053 * set to "text/xml". Or, from the other perspective, the SOAP part of any
054 * message that is received must have the MIME header Content-Type with a
055 * value of "text/xml".
056 * <P>
057 * A client can access the <code>SOAPPart</code> object of a
058 * <code>SOAPMessage</code> object by
059 * calling the method <code>SOAPMessage.getSOAPPart</code>. The
060 * following line of code, in which <code>message</code> is a
061 * <code>SOAPMessage</code> object, retrieves the SOAP part of a message.
062 * <PRE>
063 * SOAPPart soapPart = message.getSOAPPart();
064 * </PRE>
065 * <P>
066 * A <code>SOAPPart</code> object contains a <code>SOAPEnvelope</code> object,
067 * which in turn contains a <code>SOAPBody</code> object and a
068 * <code>SOAPHeader</code> object.
069 * The <code>SOAPPart</code> method <code>getEnvelope</code> can be used
070 * to retrieve the <code>SOAPEnvelope</code> object.
071 * <P>
072 */
073 public abstract class SOAPPart implements org.w3c.dom.Document, Node {
074
075 /**
076 * Gets the <code>SOAPEnvelope</code> object associated with this
077 * <code>SOAPPart</code> object. Once the SOAP envelope is obtained, it
078 * can be used to get its contents.
079 *
080 * @return the <code>SOAPEnvelope</code> object for this
081 * <code>SOAPPart</code> object
082 * @exception SOAPException if there is a SOAP error
083 */
084 public abstract SOAPEnvelope getEnvelope() throws SOAPException;
085
086 /**
087 * Retrieves the value of the MIME header whose name is "Content-Id".
088 *
089 * @return a <code>String</code> giving the value of the MIME header
090 * named "Content-Id"
091 * @see #setContentId
092 */
093 public String getContentId() {
094 String[] values = getMimeHeader("Content-Id");
095 if (values != null && values.length > 0)
096 return values[0];
097 return null;
098 }
099
100 /**
101 * Retrieves the value of the MIME header whose name is "Content-Location".
102 *
103 * @return a <code>String</code> giving the value of the MIME header whose
104 * name is "Content-Location"
105 * @see #setContentLocation
106 */
107 public String getContentLocation() {
108 String[] values = getMimeHeader("Content-Location");
109 if (values != null && values.length > 0)
110 return values[0];
111 return null;
112 }
113
114 /**
115 * Sets the value of the MIME header named "Content-Id"
116 * to the given <code>String</code>.
117 *
118 * @param contentId a <code>String</code> giving the value of the MIME
119 * header "Content-Id"
120 *
121 * @exception IllegalArgumentException if there is a problem in
122 * setting the content id
123 * @see #getContentId
124 */
125 public void setContentId(String contentId) {
126 setMimeHeader("Content-Id", contentId);
127 }
128
129 /**
130 * Sets the value of the MIME header "Content-Location"
131 * to the given <code>String</code>.
132 *
133 * @param contentLocation a <code>String</code> giving the value
134 * of the MIME
135 * header "Content-Location"
136 * @exception IllegalArgumentException if there is a problem in
137 * setting the content location.
138 * @see #getContentLocation
139 */
140 public void setContentLocation(String contentLocation) {
141 setMimeHeader("Content-Location", contentLocation);
142 }
143
144 /**
145 * Removes all MIME headers that match the given name.
146 *
147 * @param header a <code>String</code> giving the name of the MIME header(s) to
148 * be removed
149 */
150 public abstract void removeMimeHeader(String header);
151
152 /**
153 * Removes all the <code>MimeHeader</code> objects for this
154 * <code>SOAPEnvelope</code> object.
155 */
156 public abstract void removeAllMimeHeaders();
157
158 /**
159 * Gets all the values of the <code>MimeHeader</code> object
160 * in this <code>SOAPPart</code> object that
161 * is identified by the given <code>String</code>.
162 *
163 * @param name the name of the header; example: "Content-Type"
164 * @return a <code>String</code> array giving all the values for the
165 * specified header
166 * @see #setMimeHeader
167 */
168 public abstract String[] getMimeHeader(String name);
169
170 /**
171 * Changes the first header entry that matches the given header name
172 * so that its value is the given value, adding a new header with the
173 * given name and value if no
174 * existing header is a match. If there is a match, this method clears
175 * all existing values for the first header that matches and sets the
176 * given value instead. If more than one header has
177 * the given name, this method removes all of the matching headers after
178 * the first one.
179 * <P>
180 * Note that RFC822 headers can contain only US-ASCII characters.
181 *
182 * @param name a <code>String</code> giving the header name
183 * for which to search
184 * @param value a <code>String</code> giving the value to be set.
185 * This value will be substituted for the current value(s)
186 * of the first header that is a match if there is one.
187 * If there is no match, this value will be the value for
188 * a new <code>MimeHeader</code> object.
189 *
190 * @exception IllegalArgumentException if there was a problem with
191 * the specified mime header name or value
192 * @see #getMimeHeader
193 */
194 public abstract void setMimeHeader(String name, String value);
195
196 /**
197 * Creates a <code>MimeHeader</code> object with the specified
198 * name and value and adds it to this <code>SOAPPart</code> object.
199 * If a <code>MimeHeader</code> with the specified name already
200 * exists, this method adds the specified value to the already
201 * existing value(s).
202 * <P>
203 * Note that RFC822 headers can contain only US-ASCII characters.
204 *
205 * @param name a <code>String</code> giving the header name
206 * @param value a <code>String</code> giving the value to be set
207 * or added
208 * @exception IllegalArgumentException if there was a problem with
209 * the specified mime header name or value
210 */
211 public abstract void addMimeHeader(String name, String value);
212
213 /**
214 * Retrieves all the headers for this <code>SOAPPart</code> object
215 * as an iterator over the <code>MimeHeader</code> objects.
216 *
217 * @return an <code>Iterator</code> object with all of the Mime
218 * headers for this <code>SOAPPart</code> object
219 */
220 public abstract Iterator getAllMimeHeaders();
221
222 /**
223 * Retrieves all <code>MimeHeader</code> objects that match a name in
224 * the given array.
225 *
226 * @param names a <code>String</code> array with the name(s) of the
227 * MIME headers to be returned
228 * @return all of the MIME headers that match one of the names in the
229 * given array, returned as an <code>Iterator</code> object
230 */
231 public abstract Iterator getMatchingMimeHeaders(String[] names);
232
233 /**
234 * Retrieves all <code>MimeHeader</code> objects whose name does
235 * not match a name in the given array.
236 *
237 * @param names a <code>String</code> array with the name(s) of the
238 * MIME headers not to be returned
239 * @return all of the MIME headers in this <code>SOAPPart</code> object
240 * except those that match one of the names in the
241 * given array. The nonmatching MIME headers are returned as an
242 * <code>Iterator</code> object.
243 */
244 public abstract Iterator getNonMatchingMimeHeaders(String[] names);
245
246 /**
247 * Sets the content of the <code>SOAPEnvelope</code> object with the data
248 * from the given <code>Source</code> object. This <code>Source</code>
249 * must contain a valid SOAP document.
250 *
251 * @param source the <code>javax.xml.transform.Source</code> object with the
252 * data to be set
253 *
254 * @exception SOAPException if there is a problem in setting the source
255 * @see #getContent
256 */
257 public abstract void setContent(Source source) throws SOAPException;
258
259 /**
260 * Returns the content of the SOAPEnvelope as a JAXP <code>Source</code>
261 * object.
262 *
263 * @return the content as a <code>javax.xml.transform.Source</code> object
264 *
265 * @exception SOAPException if the implementation cannot convert
266 * the specified <code>Source</code> object
267 * @see #setContent
268 */
269 public abstract Source getContent() throws SOAPException;
270 }
|