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: package javax.xml.soap;
020:
021: import org.w3c.dom.Document;
022:
023: import java.util.Locale;
024:
025: /**
026: * An object that represents the contents of the SOAP body element in a SOAP message. A SOAP body
027: * element consists of XML data that affects the way the application-specific content is processed.
028: * <p/>
029: * A <code>SOAPBody</code> object contains <code>SOAPBodyElement</code> objects, which have the
030: * content for the SOAP body. A <code>SOAPFault</code> object, which carries status and/or error
031: * information, is an example of a <code>SOAPBodyElement</code> object.
032: *
033: * @see SOAPFault SOAPFault
034: */
035: public interface SOAPBody extends SOAPElement {
036:
037: /**
038: * Creates a new <code>SOAPFault</code> object and adds it to this <code>SOAPBody</code>
039: * object.
040: *
041: * @return the new <code>SOAPFault</code> object
042: * @throws SOAPException if there is a SOAP error
043: */
044: public abstract SOAPFault addFault() throws SOAPException;
045:
046: /**
047: * Indicates whether a <code>SOAPFault</code> object exists in this <code>SOAPBody</code>
048: * object.
049: *
050: * @return <code>true</code> if a <code>SOAPFault</code> object exists in this
051: * <code>SOAPBody</code> object; <code>false</code> otherwise
052: */
053: public abstract boolean hasFault();
054:
055: /**
056: * Returns the <code>SOAPFault</code> object in this <code>SOAPBody</code> object.
057: *
058: * @return the <code>SOAPFault</code> object in this <code>SOAPBody</code> object
059: */
060: public abstract SOAPFault getFault();
061:
062: /**
063: * Creates a new <code>SOAPBodyElement</code> object with the specified name and adds it to this
064: * <code>SOAPBody</code> object.
065: *
066: * @param name a <code>Name</code> object with the name for the new <code>SOAPBodyElement</code>
067: * object
068: * @return the new <code>SOAPBodyElement</code> object
069: * @throws SOAPException if a SOAP error occurs
070: */
071: public abstract SOAPBodyElement addBodyElement(Name name)
072: throws SOAPException;
073:
074: /**
075: * Creates a new <code>SOAPFault</code> object and adds it to this <code>SOAPBody</code> object.
076: * The new <code>SOAPFault</code> will have a <code>faultcode</code> element that is set to the
077: * <code>faultCode</code> parameter and a <code>faultstring</code> set to
078: * <code>faultstring</code> and localized to <code>locale</code>.
079: *
080: * @param faultCode a <code>Name</code> object giving the fault code to be set; must be one of
081: * the fault codes defined in the SOAP 1.1 specification and of type QName
082: * @param faultString a <code>String</code> giving an explanation of the fault
083: * @param locale a <code>Locale</code> object indicating the native language of the
084: * <ocde>faultString</code>
085: * @return the new <code>SOAPFault</code> object
086: * @throws SOAPException if there is a SOAP error
087: */
088: public abstract SOAPFault addFault(Name faultCode,
089: String faultString, Locale locale) throws SOAPException;
090:
091: /**
092: * Creates a new <code>SOAPFault</code> object and adds it to this <code>SOAPBody</code> object.
093: * The new <code>SOAPFault</code> will have a <code>faultcode</code> element that is set to the
094: * <code>faultCode</code> parameter and a <code>faultstring</code> set to
095: * <code>faultstring</code>.
096: *
097: * @param faultCode a <code>Name</code> object giving the fault code to be set; must be one of
098: * the fault codes defined in the SOAP 1.1 specification and of type QName
099: * @param faultString a <code>String</code> giving an explanation of the fault
100: * @return the new <code>SOAPFault</code> object
101: * @throws SOAPException if there is a SOAP error
102: */
103: public abstract SOAPFault addFault(Name faultCode,
104: String faultString) throws SOAPException;
105:
106: /**
107: * Adds the root node of the DOM <code>Document</code> to this <code>SOAPBody</code> object.
108: * <p/>
109: * Calling this method invalidates the <code>document</code> parameter. The client application
110: * should discard all references to this <code>Document</code> and its contents upon calling
111: * <code>addDocument</code>. The behavior of an application that continues to use such
112: * references is undefined.
113: *
114: * @param document the <code>Document</code> object whose root node will be added to this
115: * <code>SOAPBody</code>
116: * @return the <code>SOAPBodyElement</code> that represents the root node that was added
117: * @throws SOAPException if the <code>Document</code> cannot be added
118: */
119: public abstract SOAPBodyElement addDocument(Document document)
120: throws SOAPException;
121:
122: public abstract SOAPBodyElement addBodyElement(
123: javax.xml.namespace.QName qname) throws SOAPException;
124:
125: public abstract SOAPFault addFault(javax.xml.namespace.QName qname,
126: java.lang.String s) throws SOAPException;
127:
128: public abstract SOAPFault addFault(javax.xml.namespace.QName qname,
129: java.lang.String s, java.util.Locale locale)
130: throws SOAPException;
131:
132: public abstract org.w3c.dom.Document extractContentAsDocument()
133: throws SOAPException;
134: }
|