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    }