001: /*
002: * $Id: SOAPPart.java,v 1.10 2006/03/30 00:59:42 ofung Exp $
003: * $Revision: 1.10 $
004: * $Date: 2006/03/30 00:59:42 $
005: */
006:
007: /*
008: * The contents of this file are subject to the terms
009: * of the Common Development and Distribution License
010: * (the License). You may not use this file except in
011: * compliance with the License.
012: *
013: * You can obtain a copy of the license at
014: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
015: * See the License for the specific language governing
016: * permissions and limitations under the License.
017: *
018: * When distributing Covered Code, include this CDDL
019: * Header Notice in each file and include the License file
020: * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
021: * If applicable, add the following below the CDDL Header,
022: * with the fields enclosed by brackets [] replaced by
023: * you own identifying information:
024: * "Portions Copyrighted [year] [name of copyright owner]"
025: *
026: * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
027: */
028: package javax.xml.soap;
029:
030: import java.util.Iterator;
031:
032: import javax.xml.transform.Source;
033:
034: /**
035: * The container for the SOAP-specific portion of a <code>SOAPMessage</code>
036: * object. All messages are required to have a SOAP part, so when a
037: * <code>SOAPMessage</code> object is created, it will automatically
038: * have a <code>SOAPPart</code> object.
039: *<P>
040: * A <code>SOAPPart</code> object is a MIME part and has the MIME headers
041: * Content-Id, Content-Location, and Content-Type. Because the value of
042: * Content-Type must be "text/xml", a <code>SOAPPart</code> object automatically
043: * has a MIME header of Content-Type with its value set to "text/xml".
044: * The value must be "text/xml" because content in the SOAP part of a
045: * message must be in XML format. Content that is not of type "text/xml"
046: * must be in an <code>AttachmentPart</code> object rather than in the
047: * <code>SOAPPart</code> object.
048: * <P>
049: * When a message is sent, its SOAP part must have the MIME header Content-Type
050: * set to "text/xml". Or, from the other perspective, the SOAP part of any
051: * message that is received must have the MIME header Content-Type with a
052: * value of "text/xml".
053: * <P>
054: * A client can access the <code>SOAPPart</code> object of a
055: * <code>SOAPMessage</code> object by
056: * calling the method <code>SOAPMessage.getSOAPPart</code>. The
057: * following line of code, in which <code>message</code> is a
058: * <code>SOAPMessage</code> object, retrieves the SOAP part of a message.
059: * <PRE>
060: * SOAPPart soapPart = message.getSOAPPart();
061: * </PRE>
062: * <P>
063: * A <code>SOAPPart</code> object contains a <code>SOAPEnvelope</code> object,
064: * which in turn contains a <code>SOAPBody</code> object and a
065: * <code>SOAPHeader</code> object.
066: * The <code>SOAPPart</code> method <code>getEnvelope</code> can be used
067: * to retrieve the <code>SOAPEnvelope</code> object.
068: * <P>
069: */
070: public abstract class SOAPPart implements org.w3c.dom.Document, Node {
071:
072: /**
073: * Gets the <code>SOAPEnvelope</code> object associated with this
074: * <code>SOAPPart</code> object. Once the SOAP envelope is obtained, it
075: * can be used to get its contents.
076: *
077: * @return the <code>SOAPEnvelope</code> object for this
078: * <code>SOAPPart</code> object
079: * @exception SOAPException if there is a SOAP error
080: */
081: public abstract SOAPEnvelope getEnvelope() throws SOAPException;
082:
083: /**
084: * Retrieves the value of the MIME header whose name is "Content-Id".
085: *
086: * @return a <code>String</code> giving the value of the MIME header
087: * named "Content-Id"
088: * @see #setContentId
089: */
090: public String getContentId() {
091: String[] values = getMimeHeader("Content-Id");
092: if (values != null && values.length > 0)
093: return values[0];
094: return null;
095: }
096:
097: /**
098: * Retrieves the value of the MIME header whose name is "Content-Location".
099: *
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: setMimeHeader("Content-Id", contentId);
124: }
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: setMimeHeader("Content-Location", contentLocation);
139: }
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: }
|