Mercurial > jdk8-mips64-public > jaxws / file comparison

comparison: src/share/jaxws_classes/javax/xml/soap/SOAPPart.java

src/share/jaxws_classes/javax/xml/soap/SOAPPart.java

changeset 0
373ffda63c9a
child 637
9c07ef4934dd
equal deleted inserted replaced
-1:000000000000 0:373ffda63c9a
1 /*
2 * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.soap;
27
28 import java.util.Iterator;
29
30 import javax.xml.transform.Source;
31
32 /**
33 * The container for the SOAP-specific portion of a <code>SOAPMessage</code>
34 * object. All messages are required to have a SOAP part, so when a
35 * <code>SOAPMessage</code> object is created, it will automatically
36 * have a <code>SOAPPart</code> object.
37 *<P>
38 * A <code>SOAPPart</code> object is a MIME part and has the MIME headers
39 * Content-Id, Content-Location, and Content-Type. Because the value of
40 * Content-Type must be "text/xml", a <code>SOAPPart</code> object automatically
41 * has a MIME header of Content-Type with its value set to "text/xml".
42 * The value must be "text/xml" because content in the SOAP part of a
43 * message must be in XML format. Content that is not of type "text/xml"
44 * must be in an <code>AttachmentPart</code> object rather than in the
45 * <code>SOAPPart</code> object.
46 * <P>
47 * When a message is sent, its SOAP part must have the MIME header Content-Type
48 * set to "text/xml". Or, from the other perspective, the SOAP part of any
49 * message that is received must have the MIME header Content-Type with a
50 * value of "text/xml".
51 * <P>
52 * A client can access the <code>SOAPPart</code> object of a
53 * <code>SOAPMessage</code> object by
54 * calling the method <code>SOAPMessage.getSOAPPart</code>. The
55 * following line of code, in which <code>message</code> is a
56 * <code>SOAPMessage</code> object, retrieves the SOAP part of a message.
57 * <PRE>
58 * SOAPPart soapPart = message.getSOAPPart();
59 * </PRE>
60 * <P>
61 * A <code>SOAPPart</code> object contains a <code>SOAPEnvelope</code> object,
62 * which in turn contains a <code>SOAPBody</code> object and a
63 * <code>SOAPHeader</code> object.
64 * The <code>SOAPPart</code> method <code>getEnvelope</code> can be used
65 * to retrieve the <code>SOAPEnvelope</code> object.
66 * <P>
67 */
68 public abstract class SOAPPart implements org.w3c.dom.Document, Node {
69
70 /**
71 * Gets the <code>SOAPEnvelope</code> object associated with this
72 * <code>SOAPPart</code> object. Once the SOAP envelope is obtained, it
73 * can be used to get its contents.
74 *
75 * @return the <code>SOAPEnvelope</code> object for this
76 * <code>SOAPPart</code> object
77 * @exception SOAPException if there is a SOAP error
78 */
79 public abstract SOAPEnvelope getEnvelope() throws SOAPException;
80
81 /**
82 * Retrieves the value of the MIME header whose name is "Content-Id".
83 *
84 * @return a <code>String</code> giving the value of the MIME header
85 * named "Content-Id"
86 * @see #setContentId
87 */
88 public String getContentId() {
89 String[] values = getMimeHeader("Content-Id");
90 if (values != null && values.length > 0)
91 return values[0];
92 return null;
93 }
94
95 /**
96 * Retrieves the value of the MIME header whose name is "Content-Location".
97 *
98 * @return a <code>String</code> giving the value of the MIME header whose
99 * name is "Content-Location"
100 * @see #setContentLocation
101 */
102 public String getContentLocation() {
103 String[] values = getMimeHeader("Content-Location");
104 if (values != null && values.length > 0)
105 return values[0];
106 return null;
107 }
108
109 /**
110 * Sets the value of the MIME header named "Content-Id"
111 * to the given <code>String</code>.
112 *
113 * @param contentId a <code>String</code> giving the value of the MIME
114 * header "Content-Id"
115 *
116 * @exception IllegalArgumentException if there is a problem in
117 * setting the content id
118 * @see #getContentId
119 */
120 public void setContentId(String contentId)
121 {
122 setMimeHeader("Content-Id", contentId);
123 }
124 /**
125 * Sets the value of the MIME header "Content-Location"
126 * to the given <code>String</code>.
127 *
128 * @param contentLocation a <code>String</code> giving the value
129 * of the MIME
130 * header "Content-Location"
131 * @exception IllegalArgumentException if there is a problem in
132 * setting the content location.
133 * @see #getContentLocation
134 */
135 public void setContentLocation(String contentLocation)
136 {
137 setMimeHeader("Content-Location", contentLocation);
138 }
139 /**
140 * Removes all MIME headers that match the given name.
141 *
142 * @param header a <code>String</code> giving the name of the MIME header(s) to
143 * 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
156 * is identified by the given <code>String</code>.
157 *
158 * @param name the name of the header; example: "Content-Type"
159 * @return a <code>String</code> array giving all the values for the
160 * specified header
161 * @see #setMimeHeader
162 */
163 public abstract String[] getMimeHeader(String name);
164
165 /**
166 * Changes the first header entry that matches the given header name
167 * so that its value is the given value, adding a new header with the
168 * given name and value if no
169 * existing header is a match. If there is a match, this method clears
170 * all existing values for the first header that matches and sets the
171 * given value instead. If more than one header has
172 * the given name, this method removes all of the matching headers after
173 * the first one.
174 * <P>
175 * Note that RFC822 headers can contain only US-ASCII characters.
176 *
177 * @param name a <code>String</code> giving the header name
178 * for which to search
179 * @param value a <code>String</code> giving the value to be set.
180 * This value will be substituted for the current value(s)
181 * of the first header that is a match if there is one.
182 * If there is no match, this value will be the value for
183 * a new <code>MimeHeader</code> object.
184 *
185 * @exception IllegalArgumentException if there was a problem with
186 * the specified mime header name or value
187 * @see #getMimeHeader
188 */
189 public abstract void setMimeHeader(String name, String value);
190
191 /**
192 * Creates a <code>MimeHeader</code> object with the specified
193 * name and value and adds it to this <code>SOAPPart</code> object.
194 * If a <code>MimeHeader</code> with the specified name already
195 * exists, this method adds the specified value to the already
196 * existing value(s).
197 * <P>
198 * Note that RFC822 headers can contain only US-ASCII characters.
199 *
200 * @param name a <code>String</code> giving the header name
201 * @param value a <code>String</code> giving the value to be set
202 * or added
203 * @exception IllegalArgumentException if there was a problem with
204 * the specified mime header name or value
205 */
206 public abstract void addMimeHeader(String name, String value);
207
208 /**
209 * Retrieves all the headers for this <code>SOAPPart</code> object
210 * as an iterator over the <code>MimeHeader</code> objects.
211 *
212 * @return an <code>Iterator</code> object with all of the Mime
213 * headers for this <code>SOAPPart</code> object
214 */
215 public abstract Iterator getAllMimeHeaders();
216
217 /**
218 * Retrieves all <code>MimeHeader</code> objects that match a name in
219 * the given array.
220 *
221 * @param names a <code>String</code> array with the name(s) of the
222 * MIME headers to be returned
223 * @return all of the MIME headers that match one of the names in the
224 * given array, returned as an <code>Iterator</code> object
225 */
226 public abstract Iterator getMatchingMimeHeaders(String[] names);
227
228 /**
229 * Retrieves all <code>MimeHeader</code> objects whose name does
230 * not match a name in the given array.
231 *
232 * @param names a <code>String</code> array with the name(s) of the
233 * MIME headers not to be returned
234 * @return all of the MIME headers in this <code>SOAPPart</code> object
235 * except those that match one of the names in the
236 * given array. The nonmatching MIME headers are returned as an
237 * <code>Iterator</code> object.
238 */
239 public abstract Iterator getNonMatchingMimeHeaders(String[] names);
240
241 /**
242 * Sets the content of the <code>SOAPEnvelope</code> object with the data
243 * from the given <code>Source</code> object. This <code>Source</code>
244 * must contain a valid SOAP document.
245 *
246 * @param source the <code>javax.xml.transform.Source</code> object with the
247 * data to be set
248 *
249 * @exception SOAPException if there is a problem in setting the source
250 * @see #getContent
251 */
252 public abstract void setContent(Source source) throws SOAPException;
253
254 /**
255 * Returns the content of the SOAPEnvelope as a JAXP <code>Source</code>
256 * object.
257 *
258 * @return the content as a <code>javax.xml.transform.Source</code> object
259 *
260 * @exception SOAPException if the implementation cannot convert
261 * the specified <code>Source</code> object
262 * @see #setContent
263 */
264 public abstract Source getContent() throws SOAPException;
265 }

Mercurial Repository: jdk8-mips64-public/jaxws

mercurial