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 package javax.xml.soap;
020
021 import javax.xml.transform.Source;
022 import java.util.Iterator;
023
024 /**
025 * <P>The container for the SOAP-specific portion of a <CODE> SOAPMessage</CODE> object. All
026 * messages are required to have a SOAP part, so when a <CODE>SOAPMessage</CODE> object is created,
027 * it will automatically have a <CODE>SOAPPart</CODE> object.</P>
028 * <p/>
029 * <P>A <CODE>SOAPPart</CODE> object is a MIME part and has the MIME headers Content-Id,
030 * Content-Location, and Content-Type. Because the value of Content-Type must be "text/xml", a
031 * <CODE> SOAPPart</CODE> object automatically has a MIME header of Content-Type with its value set
032 * to "text/xml". The value must be "text/xml" because content in the SOAP part of a message must be
033 * in XML format. Content that is not of type "text/xml" must be in an <CODE>AttachmentPart</CODE>
034 * object rather than in the <CODE>SOAPPart</CODE> object.</P>
035 * <p/>
036 * <P>When a message is sent, its SOAP part must have the MIME header Content-Type set to
037 * "text/xml". Or, from the other perspective, the SOAP part of any message that is received must
038 * have the MIME header Content-Type with a value of "text/xml".</P>
039 * <p/>
040 * <P>A client can access the <CODE>SOAPPart</CODE> object of a <CODE>SOAPMessage</CODE> object by
041 * calling the method <CODE> SOAPMessage.getSOAPPart</CODE>. The following line of code, in which
042 * <CODE>message</CODE> is a <CODE>SOAPMessage</CODE> object, retrieves the SOAP part of a
043 * message.</P> <PRE> SOAPPart soapPart = message.getSOAPPart(); </PRE>
044 * <p/>
045 * <P>A <CODE>SOAPPart</CODE> object contains a <CODE> SOAPEnvelope</CODE> object, which in turn
046 * contains a <CODE> SOAPBody</CODE> object and a <CODE>SOAPHeader</CODE> object. The
047 * <CODE>SOAPPart</CODE> method <CODE>getEnvelope</CODE> can be used to retrieve the
048 * <CODE>SOAPEnvelope</CODE> object.</P>
049 */
050 public abstract class SOAPPart implements javax.xml.soap.Node, org.w3c.dom.Document {
051
052 public SOAPPart() {
053 }
054
055 /**
056 * Gets the <CODE>SOAPEnvelope</CODE> object associated with this <CODE>SOAPPart</CODE> object.
057 * Once the SOAP envelope is obtained, it can be used to get its contents.
058 *
059 * @return the <CODE>SOAPEnvelope</CODE> object for this <CODE> SOAPPart</CODE> object
060 * @throws SOAPException if there is a SOAP error
061 */
062 public abstract SOAPEnvelope getEnvelope() throws SOAPException;
063
064 /**
065 * Retrieves the value of the MIME header whose name is "Content-Id".
066 *
067 * @return a <CODE>String</CODE> giving the value of the MIME header named "Content-Id"
068 * @see #setContentId(String) setContentId(java.lang.String)
069 */
070 public String getContentId() {
071
072 String as[] = getMimeHeader("Content-Id");
073
074 if (as != null && as.length > 0) {
075 return as[0];
076 } else {
077 return null;
078 }
079 }
080
081 /**
082 * Retrieves the value of the MIME header whose name is "Content-Location".
083 *
084 * @return a <CODE>String</CODE> giving the value of the MIME header whose name is
085 * "Content-Location"
086 * @see #setContentLocation(String) setContentLocation(java.lang.String)
087 */
088 public String getContentLocation() {
089
090 String as[] = getMimeHeader("Content-Location");
091
092 if (as != null && as.length > 0) {
093 return as[0];
094 } else {
095 return null;
096 }
097 }
098
099 /**
100 * Sets the value of the MIME header named "Content-Id" to the given <CODE>String</CODE>.
101 *
102 * @param contentId a <CODE>String</CODE> giving the value of the MIME header "Content-Id"
103 * @throws IllegalArgumentException
104 * if there is a problem in setting the content id
105 * @see #getContentId() getContentId()
106 */
107 public void setContentId(String contentId) {
108 setMimeHeader("Content-Id", contentId);
109 }
110
111 /**
112 * Sets the value of the MIME header "Content-Location" to the given <CODE>String</CODE>.
113 *
114 * @param contentLocation a <CODE>String</CODE> giving the value of the MIME header
115 * "Content-Location"
116 * @throws IllegalArgumentException
117 * if there is a problem in setting the content location.
118 * @see #getContentLocation() getContentLocation()
119 */
120 public void setContentLocation(String contentLocation) {
121 setMimeHeader("Content-Location", contentLocation);
122 }
123
124 /**
125 * Removes all MIME headers that match the given name.
126 *
127 * @param header a <CODE>String</CODE> giving the name of the MIME header(s) to be removed
128 */
129 public abstract void removeMimeHeader(String header);
130
131 /** Removes all the <CODE>MimeHeader</CODE> objects for this <CODE>SOAPEnvelope</CODE> object. */
132 public abstract void removeAllMimeHeaders();
133
134 /**
135 * Gets all the values of the <CODE>MimeHeader</CODE> object in this <CODE>SOAPPart</CODE>
136 * object that is identified by the given <CODE>String</CODE>.
137 *
138 * @param name the name of the header; example: "Content-Type"
139 * @return a <CODE>String</CODE> array giving all the values for the specified header
140 * @see #setMimeHeader(String, String) setMimeHeader(java.lang.String,
141 * java.lang.String)
142 */
143 public abstract String[] getMimeHeader(String name);
144
145 /**
146 * Changes the first header entry that matches the given header name so that its value is the
147 * given value, adding a new header with the given name and value if no existing header is a
148 * match. If there is a match, this method clears all existing values for the first header that
149 * matches and sets the given value instead. If more than one header has the given name, this
150 * method removes all of the matching headers after the first one.
151 * <p/>
152 * <P>Note that RFC822 headers can contain only US-ASCII characters.</P>
153 *
154 * @param name a <CODE>String</CODE> giving the header name for which to search
155 * @param value a <CODE>String</CODE> giving the value to be set. This value will be substituted
156 * for the current value(s) of the first header that is a match if there is one. If
157 * there is no match, this value will be the value for a new
158 * <CODE>MimeHeader</CODE> object.
159 * @throws IllegalArgumentException
160 * if there was a problem with the specified mime header name or value
161 * @throws IllegalArgumentException
162 * if there was a problem with the specified mime header name or value
163 * @see #getMimeHeader(String) getMimeHeader(java.lang.String)
164 */
165 public abstract void setMimeHeader(String name, String value);
166
167 /**
168 * Creates a <CODE>MimeHeader</CODE> object with the specified name and value and adds it to
169 * this <CODE>SOAPPart</CODE> object. If a <CODE>MimeHeader</CODE> with the specified name
170 * already exists, this method adds the specified value to the already existing value(s).
171 * <p/>
172 * <P>Note that RFC822 headers can contain only US-ASCII characters.</P>
173 *
174 * @param name a <CODE>String</CODE> giving the header name
175 * @param value a <CODE>String</CODE> giving the value to be set or added
176 * @throws IllegalArgumentException
177 * if there was a problem with the specified mime header name or value
178 */
179 public abstract void addMimeHeader(String name, String value);
180
181 /**
182 * Retrieves all the headers for this <CODE>SOAPPart</CODE> object as an iterator over the
183 * <CODE>MimeHeader</CODE> objects.
184 *
185 * @return an <CODE>Iterator</CODE> object with all of the Mime headers for this
186 * <CODE>SOAPPart</CODE> object
187 */
188 public abstract Iterator getAllMimeHeaders();
189
190 /**
191 * Retrieves all <CODE>MimeHeader</CODE> objects that match a name in the given array.
192 *
193 * @param names a <CODE>String</CODE> array with the name(s) of the MIME headers to be returned
194 * @return all of the MIME headers that match one of the names in the given array, returned as
195 * an <CODE>Iterator</CODE> object
196 */
197 public abstract Iterator getMatchingMimeHeaders(String names[]);
198
199 /**
200 * Retrieves all <CODE>MimeHeader</CODE> objects whose name does not match a name in the given
201 * array.
202 *
203 * @param names a <CODE>String</CODE> array with the name(s) of the MIME headers not to be
204 * returned
205 * @return all of the MIME headers in this <CODE>SOAPPart</CODE> object except those that match
206 * one of the names in the given array. The nonmatching MIME headers are returned as an
207 * <CODE>Iterator</CODE> object.
208 */
209 public abstract Iterator getNonMatchingMimeHeaders(String names[]);
210
211 /**
212 * Sets the content of the <CODE>SOAPEnvelope</CODE> object with the data from the given
213 * <CODE>Source</CODE> object.
214 *
215 * @param source javax.xml.transform.Source</CODE> object with the data to be set
216 * @throws SOAPException if there is a problem in setting the source
217 * @see #getContent() getContent()
218 */
219 public abstract void setContent(Source source) throws SOAPException;
220
221 /**
222 * Returns the content of the SOAPEnvelope as a JAXP <CODE> Source</CODE> object.
223 *
224 * @return the content as a <CODE> javax.xml.transform.Source</CODE> object
225 * @throws SOAPException if the implementation cannot convert the specified <CODE>Source</CODE>
226 * object
227 * @see #setContent(javax.xml.transform.Source) setContent(javax.xml.transform.Source)
228 */
229 public abstract Source getContent() throws SOAPException;
230 }