001: /*
002: * $Id: SOAPBody.java,v 1.18 2006/03/30 00:59:39 ofung Exp $
003: * $Revision: 1.18 $
004: * $Date: 2006/03/30 00:59:39 $
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.Locale;
031:
032: import org.w3c.dom.Document;
033:
034: import javax.xml.namespace.QName;
035:
036: /**
037: * An object that represents the contents of the SOAP body
038: * element in a SOAP message. A SOAP body element consists of XML data
039: * that affects the way the application-specific content is processed.
040: * <P>
041: * A <code>SOAPBody</code> object contains <code>SOAPBodyElement</code>
042: * objects, which have the content for the SOAP body.
043: * A <code>SOAPFault</code> object, which carries status and/or
044: * error information, is an example of a <code>SOAPBodyElement</code> object.
045: *
046: * @see SOAPFault
047: */
048: public interface SOAPBody extends SOAPElement {
049:
050: /**
051: * Creates a new <code>SOAPFault</code> object and adds it to
052: * this <code>SOAPBody</code> object. The new <code>SOAPFault</code> will
053: * have default values set for the mandatory child elements. The type of
054: * the <code>SOAPFault</code> will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code>
055: * depending on the <code>protocol</code> specified while creating the
056: * <code>MessageFactory</code> instance.
057: * <p>
058: * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
059: * child element.
060: *
061: * @return the new <code>SOAPFault</code> object
062: * @exception SOAPException if there is a SOAP error
063: */
064: public SOAPFault addFault() throws SOAPException;
065:
066: /**
067: * Creates a new <code>SOAPFault</code> object and adds it to
068: * this <code>SOAPBody</code> object. The type of the
069: * <code>SOAPFault</code> will be a SOAP 1.1 or a SOAP 1.2
070: * <code>SOAPFault</code> depending on the <code>protocol</code>
071: * specified while creating the <code>MessageFactory</code> instance.
072: * <p>
073: * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
074: * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter
075: * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
076: * the <code>faultCode</code> parameter is the value of the <code>faultcode</code>
077: * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code>
078: * element.
079: * <p>
080: * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
081: * child element.
082: *
083: * @param faultCode a <code>Name</code> object giving the fault
084: * code to be set; must be one of the fault codes defined in the Version
085: * of SOAP specification in use
086: * @param faultString a <code>String</code> giving an explanation of
087: * the fault
088: * @param locale a {@link java.util.Locale} object indicating
089: * the native language of the <code>faultString</code>
090: * @return the new <code>SOAPFault</code> object
091: * @exception SOAPException if there is a SOAP error
092: * @see SOAPFault#setFaultCode
093: * @see SOAPFault#setFaultString
094: * @since SAAJ 1.2
095: */
096: public SOAPFault addFault(Name faultCode, String faultString,
097: Locale locale) throws SOAPException;
098:
099: /**
100: * Creates a new <code>SOAPFault</code> object and adds it to this
101: * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code>
102: * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on
103: * the <code>protocol</code> specified while creating the <code>MessageFactory</code>
104: * instance.
105: * <p>
106: * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
107: * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter
108: * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
109: * the <code>faultCode</code> parameter is the value of the <code>faultcode</code>
110: * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code>
111: * element.
112: * <p>
113: * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
114: * child element.
115: *
116: * @param faultCode
117: * a <code>QName</code> object giving the fault code to be
118: * set; must be one of the fault codes defined in the version
119: * of SOAP specification in use.
120: * @param faultString
121: * a <code>String</code> giving an explanation of the fault
122: * @param locale
123: * a {@link java.util.Locale Locale} object indicating the
124: * native language of the <code>faultString</code>
125: * @return the new <code>SOAPFault</code> object
126: * @exception SOAPException
127: * if there is a SOAP error
128: * @see SOAPFault#setFaultCode
129: * @see SOAPFault#setFaultString
130: * @see SOAPBody#addFault(Name faultCode, String faultString, Locale locale)
131: *
132: * @since SAAJ 1.3
133: */
134: public SOAPFault addFault(QName faultCode, String faultString,
135: Locale locale) throws SOAPException;
136:
137: /**
138: * Creates a new <code>SOAPFault</code> object and adds it to this
139: * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code>
140: * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on
141: * the <code>protocol</code> specified while creating the <code>MessageFactory</code>
142: * instance.
143: * <p>
144: * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
145: * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter
146: * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
147: * the <code>faultCode</code> parameter is the value of the <i>faultcode</i>
148: * element and the <code>faultString</code> parameter is the value of the <i>faultstring</i>
149: * element.
150: * <p>
151: * In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code>
152: * attribute on the <i>Fault/Reason/Text</i> element will be set to
153: * <code>java.util.Locale.getDefault()</code>
154: * <p>
155: * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
156: * child element.
157: *
158: * @param faultCode
159: * a <code>Name</code> object giving the fault code to be set;
160: * must be one of the fault codes defined in the version of SOAP
161: * specification in use
162: * @param faultString
163: * a <code>String</code> giving an explanation of the fault
164: * @return the new <code>SOAPFault</code> object
165: * @exception SOAPException
166: * if there is a SOAP error
167: * @see SOAPFault#setFaultCode
168: * @see SOAPFault#setFaultString
169: * @since SAAJ 1.2
170: */
171: public SOAPFault addFault(Name faultCode, String faultString)
172: throws SOAPException;
173:
174: /**
175: * Creates a new <code>SOAPFault</code> object and adds it to this <code>SOAPBody</code>
176: * object. The type of the <code>SOAPFault</code>
177: * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on
178: * the <code>protocol</code> specified while creating the <code>MessageFactory</code>
179: * instance.
180: * <p>
181: * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the
182: * <i>Fault/Code/Value</i> element and the <code>faultString</code> parameter
183: * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1
184: * the <code>faultCode</code> parameter is the value of the <i>faultcode</i>
185: * element and the <code>faultString</code> parameter is the value of the <i>faultstring</i>
186: * element.
187: * <p>
188: * In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code>
189: * attribute on the <i>Fault/Reason/Text</i> element will be set to
190: * <code>java.util.Locale.getDefault()</code>
191: * <p>
192: * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
193: * child element
194: *
195: * @param faultCode
196: * a <code>QName</code> object giving the fault code to be
197: * set; must be one of the fault codes defined in the version
198: * of SOAP specification in use
199: * @param faultString
200: * a <code>String</code> giving an explanation of the fault
201: * @return the new <code>SOAPFault</code> object
202: * @exception SOAPException
203: * if there is a SOAP error
204: * @see SOAPFault#setFaultCode
205: * @see SOAPFault#setFaultString
206: * @see SOAPBody#addFault(Name faultCode, String faultString)
207: * @since SAAJ 1.3
208: */
209: public SOAPFault addFault(QName faultCode, String faultString)
210: throws SOAPException;
211:
212: /**
213: * Indicates whether a <code>SOAPFault</code> object exists in this
214: * <code>SOAPBody</code> object.
215: *
216: * @return <code>true</code> if a <code>SOAPFault</code> object exists
217: * in this <code>SOAPBody</code> object; <code>false</code>
218: * otherwise
219: */
220: public boolean hasFault();
221:
222: /**
223: * Returns the <code>SOAPFault</code> object in this <code>SOAPBody</code>
224: * object.
225: *
226: * @return the <code>SOAPFault</code> object in this <code>SOAPBody</code>
227: * object if present, null otherwise.
228: */
229: public SOAPFault getFault();
230:
231: /**
232: * Creates a new <code>SOAPBodyElement</code> object with the specified
233: * name and adds it to this <code>SOAPBody</code> object.
234: *
235: * @param name
236: * a <code>Name</code> object with the name for the new <code>SOAPBodyElement</code>
237: * object
238: * @return the new <code>SOAPBodyElement</code> object
239: * @exception SOAPException
240: * if a SOAP error occurs
241: * @see SOAPBody#addBodyElement(javax.xml.namespace.QName)
242: */
243: public SOAPBodyElement addBodyElement(Name name)
244: throws SOAPException;
245:
246: /**
247: * Creates a new <code>SOAPBodyElement</code> object with the specified
248: * QName and adds it to this <code>SOAPBody</code> object.
249: *
250: * @param qname
251: * a <code>QName</code> object with the qname for the new
252: * <code>SOAPBodyElement</code> object
253: * @return the new <code>SOAPBodyElement</code> object
254: * @exception SOAPException
255: * if a SOAP error occurs
256: * @see SOAPBody#addBodyElement(Name)
257: * @since SAAJ 1.3
258: */
259: public SOAPBodyElement addBodyElement(QName qname)
260: throws SOAPException;
261:
262: /**
263: * Adds the root node of the DOM <code>{@link org.w3c.dom.Document}</code>
264: * to this <code>SOAPBody</code> object.
265: * <p>
266: * Calling this method invalidates the <code>document</code> parameter.
267: * The client application should discard all references to this <code>Document</code>
268: * and its contents upon calling <code>addDocument</code>. The behavior
269: * of an application that continues to use such references is undefined.
270: *
271: * @param document
272: * the <code>Document</code> object whose root node will be
273: * added to this <code>SOAPBody</code>.
274: * @return the <code>SOAPBodyElement</code> that represents the root node
275: * that was added.
276: * @exception SOAPException
277: * if the <code>Document</code> cannot be added
278: * @since SAAJ 1.2
279: */
280: public SOAPBodyElement addDocument(org.w3c.dom.Document document)
281: throws SOAPException;
282:
283: /**
284: * Creates a new DOM <code>{@link org.w3c.dom.Document}</code> and sets
285: * the first child of this <code>SOAPBody</code> as it's document
286: * element. The child <code>SOAPElement</code> is removed as part of the
287: * process.
288: *
289: * @return the <code>{@link org.w3c.dom.Document}</code> representation
290: * of the <code>SOAPBody</code> content.
291: *
292: * @exception SOAPException
293: * if there is not exactly one child <code>SOAPElement</code> of the <code>
294: * <code>SOAPBody</code>.
295: *
296: * @since SAAJ 1.3
297: */
298: public org.w3c.dom.Document extractContentAsDocument()
299: throws SOAPException;
300: }
|