001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019
020 package javax.xml.soap;
021
022 import javax.xml.transform.Source;
023 import java.util.Iterator;
024
025 /**
026 * <P>The container for the SOAP-specific portion of a <CODE>
027 * SOAPMessage</CODE> object. All messages are required to have a
028 * SOAP part, so when a <CODE>SOAPMessage</CODE> object is
029 * created, it will automatically have a <CODE>SOAPPart</CODE>
030 * object.</P>
031 *
032 * <P>A <CODE>SOAPPart</CODE> object is a MIME part and has the
033 * MIME headers Content-Id, Content-Location, and Content-Type.
034 * Because the value of Content-Type must be "text/xml", a <CODE>
035 * SOAPPart</CODE> object automatically has a MIME header of
036 * Content-Type with its value set to "text/xml". The value must
037 * be "text/xml" because content in the SOAP part of a message
038 * must be in XML format. Content that is not of type "text/xml"
039 * must be in an <CODE>AttachmentPart</CODE> object rather than in
040 * the <CODE>SOAPPart</CODE> object.</P>
041 *
042 * <P>When a message is sent, its SOAP part must have the MIME
043 * header Content-Type set to "text/xml". Or, from the other
044 * perspective, the SOAP part of any message that is received must
045 * have the MIME header Content-Type with a value of
046 * "text/xml".</P>
047 *
048 * <P>A client can access the <CODE>SOAPPart</CODE> object of a
049 * <CODE>SOAPMessage</CODE> object by calling the method <CODE>
050 * SOAPMessage.getSOAPPart</CODE>. The following line of code, in
051 * which <CODE>message</CODE> is a <CODE>SOAPMessage</CODE>
052 * object, retrieves the SOAP part of a message.</P>
053 * <PRE>
054 * SOAPPart soapPart = message.getSOAPPart();
055 * </PRE>
056 *
057 * <P>A <CODE>SOAPPart</CODE> object contains a <CODE>
058 * SOAPEnvelope</CODE> object, which in turn contains a <CODE>
059 * SOAPBody</CODE> object and a <CODE>SOAPHeader</CODE> object.
060 * The <CODE>SOAPPart</CODE> method <CODE>getEnvelope</CODE> can
061 * be used to retrieve the <CODE>SOAPEnvelope</CODE> object.</P>
062 */
063 public abstract class SOAPPart implements org.w3c.dom.Document {
064
065 public SOAPPart() {}
066
067 /**
068 * Gets the <CODE>SOAPEnvelope</CODE> object associated with
069 * this <CODE>SOAPPart</CODE> object. Once the SOAP envelope is
070 * obtained, it can be used to get its contents.
071 * @return the <CODE>SOAPEnvelope</CODE> object for this <CODE>
072 * SOAPPart</CODE> object
073 * @throws SOAPException if there is a SOAP error
074 */
075 public abstract SOAPEnvelope getEnvelope() throws SOAPException;
076
077 /**
078 * Retrieves the value of the MIME header whose name is
079 * "Content-Id".
080 * @return a <CODE>String</CODE> giving the value of the MIME
081 * header named "Content-Id"
082 * @see #setContentId(java.lang.String) setContentId(java.lang.String)
083 */
084 public String getContentId() {
085
086 String as[] = getMimeHeader("Content-Id");
087
088 if (as != null && as.length > 0) {
089 return as[0];
090 } else {
091 return null;
092 }
093 }
094
095 /**
096 * Retrieves the value of the MIME header whose name is
097 * "Content-Location".
098 * @return a <CODE>String</CODE> giving the value of the MIME
099 * header whose name is "Content-Location"
100 * @see #setContentLocation(java.lang.String) setContentLocation(java.lang.String)
101 */
102 public String getContentLocation() {
103
104 String as[] = getMimeHeader("Content-Location");
105
106 if (as != null && as.length > 0) {
107 return as[0];
108 } else {
109 return null;
110 }
111 }
112
113 /**
114 * Sets the value of the MIME header named "Content-Id" to
115 * the given <CODE>String</CODE>.
116 * @param contentId a <CODE>String</CODE> giving
117 * the value of the MIME header "Content-Id"
118 * @throws java.lang.IllegalArgumentException if
119 * there is a problem in setting the content id
120 * @see #getContentId() getContentId()
121 */
122 public void setContentId(String contentId) {
123 setMimeHeader("Content-Id", contentId);
124 }
125
126 /**
127 * Sets the value of the MIME header "Content-Location" to
128 * the given <CODE>String</CODE>.
129 * @param contentLocation a <CODE>String</CODE>
130 * giving the value of the MIME header
131 * "Content-Location"
132 * @throws java.lang.IllegalArgumentException if
133 * there is a problem in setting the content location.
134 * @see #getContentLocation() getContentLocation()
135 */
136 public void setContentLocation(String contentLocation) {
137 setMimeHeader("Content-Location", contentLocation);
138 }
139
140 /**
141 * Removes all MIME headers that match the given name.
142 * @param header a <CODE>String</CODE> giving
143 * the name of the MIME header(s) to 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 is identified by
156 * the given <CODE>String</CODE>.
157 * @param name the name of the header; example:
158 * "Content-Type"
159 * @return a <CODE>String</CODE> array giving all the values for
160 * the specified header
161 * @see #setMimeHeader(java.lang.String, java.lang.String) setMimeHeader(java.lang.String, java.lang.String)
162 */
163 public abstract String[] getMimeHeader(String name);
164
165 /**
166 * Changes the first header entry that matches the given
167 * header name so that its value is the given value, adding a
168 * new header with the given name and value if no existing
169 * header is a match. If there is a match, this method clears
170 * all existing values for the first header that matches and
171 * sets the given value instead. If more than one header has
172 * the given name, this method removes all of the matching
173 * headers after the first one.
174 *
175 * <P>Note that RFC822 headers can contain only US-ASCII
176 * characters.</P>
177 * @param name a <CODE>String</CODE> giving the
178 * header name for which to search
179 * @param value a <CODE>String</CODE> giving the
180 * value to be set. This value will be substituted for the
181 * current value(s) of the first header that is a match if
182 * there is one. If there is no match, this value will be
183 * the value for a new <CODE>MimeHeader</CODE> object.
184 * @throws java.lang.IllegalArgumentException if
185 * there was a problem with the specified mime header name
186 * or value
187 * @throws java.lang.IllegalArgumentException if there was a problem with the specified mime header name or value
188 * @see #getMimeHeader(java.lang.String) getMimeHeader(java.lang.String)
189 */
190 public abstract void setMimeHeader(String name, String value);
191
192 /**
193 * Creates a <CODE>MimeHeader</CODE> object with the specified
194 * name and value and adds it to this <CODE>SOAPPart</CODE>
195 * object. If a <CODE>MimeHeader</CODE> with the specified
196 * name already exists, this method adds the specified value
197 * to the already existing value(s).
198 *
199 * <P>Note that RFC822 headers can contain only US-ASCII
200 * characters.</P>
201 *
202 * @param name a <CODE>String</CODE> giving the
203 * header name
204 * @param value a <CODE>String</CODE> giving the
205 * value to be set or added
206 * @throws java.lang.IllegalArgumentException if
207 * there was a problem with the specified mime header name
208 * or value
209 */
210 public abstract void addMimeHeader(String name, String value);
211
212 /**
213 * Retrieves all the headers for this <CODE>SOAPPart</CODE>
214 * object as an iterator over the <CODE>MimeHeader</CODE>
215 * objects.
216 * @return an <CODE>Iterator</CODE> object with all of the Mime
217 * headers for this <CODE>SOAPPart</CODE> object
218 */
219 public abstract Iterator getAllMimeHeaders();
220
221 /**
222 * Retrieves all <CODE>MimeHeader</CODE> objects that match
223 * a name in the given array.
224 * @param names a <CODE>String</CODE> array with
225 * the name(s) of the MIME headers to be returned
226 * @return all of the MIME headers that match one of the names
227 * in the given array, returned as an <CODE>Iterator</CODE>
228 * object
229 */
230 public abstract Iterator getMatchingMimeHeaders(String names[]);
231
232 /**
233 * Retrieves all <CODE>MimeHeader</CODE> objects whose name
234 * does not match a name in the given array.
235 * @param names a <CODE>String</CODE> array with
236 * the name(s) of the MIME headers not to be returned
237 * @return all of the MIME headers in this <CODE>SOAPPart</CODE>
238 * object except those that match one of the names in the
239 * given array. The nonmatching MIME headers are returned as
240 * an <CODE>Iterator</CODE> object.
241 */
242 public abstract Iterator getNonMatchingMimeHeaders(String names[]);
243
244 /**
245 * Sets the content of the <CODE>SOAPEnvelope</CODE> object
246 * with the data from the given <CODE>Source</CODE> object.
247 * @param source javax.xml.transform.Source</CODE> object with the data to
248 * be set
249 * @throws SOAPException if there is a problem in
250 * setting the source
251 * @see #getContent() getContent()
252 */
253 public abstract void setContent(Source source) throws SOAPException;
254
255 /**
256 * Returns the content of the SOAPEnvelope as a JAXP <CODE>
257 * Source</CODE> object.
258 * @return the content as a <CODE>
259 * javax.xml.transform.Source</CODE> object
260 * @throws SOAPException if the implementation cannot
261 * convert the specified <CODE>Source</CODE> object
262 * @see #setContent(javax.xml.transform.Source) setContent(javax.xml.transform.Source)
263 */
264 public abstract Source getContent() throws SOAPException;
265 }