SOAPPart


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