001 /*
002 * Copyright 2001-2004 The Apache Software Foundation.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package javax.xml.soap;
017
018 import org.w3c.dom.Document;
019
020 import java.util.Locale;
021
022 /**
023 * An object that represents the contents of the SOAP body
024 * element in a SOAP message. A SOAP body element consists of XML data
025 * that affects the way the application-specific content is processed.
026 * <P>
027 * A <code>SOAPBody</code> object contains <code>SOAPBodyElement</code>
028 * objects, which have the content for the SOAP body.
029 * A <code>SOAPFault</code> object, which carries status and/or
030 * error information, is an example of a <code>SOAPBodyElement</code> object.
031 * @see SOAPFault SOAPFault
032 */
033 public interface SOAPBody extends SOAPElement {
034
035 /**
036 * Creates a new <code>SOAPFault</code> object and adds it to
037 * this <code>SOAPBody</code> object.
038 * @return the new <code>SOAPFault</code> object
039 * @throws SOAPException if there is a SOAP error
040 */
041 public abstract SOAPFault addFault() throws SOAPException;
042
043 /**
044 * Indicates whether a <code>SOAPFault</code> object exists in
045 * this <code>SOAPBody</code> object.
046 * @return <code>true</code> if a <code>SOAPFault</code> object exists in
047 * this <code>SOAPBody</code> object; <code>false</code>
048 * otherwise
049 */
050 public abstract boolean hasFault();
051
052 /**
053 * Returns the <code>SOAPFault</code> object in this <code>SOAPBody</code>
054 * object.
055 * @return the <code>SOAPFault</code> object in this <code>SOAPBody</code>
056 * object
057 */
058 public abstract SOAPFault getFault();
059
060 /**
061 * Creates a new <code>SOAPBodyElement</code> object with the
062 * specified name and adds it to this <code>SOAPBody</code> object.
063 * @param name a <code>Name</code> object with the name for the new
064 * <code>SOAPBodyElement</code> object
065 * @return the new <code>SOAPBodyElement</code> object
066 * @throws SOAPException if a SOAP error occurs
067 */
068 public abstract SOAPBodyElement addBodyElement(Name name)
069 throws SOAPException;
070
071 /**
072 * Creates a new <code>SOAPFault</code> object and adds it to this
073 * <code>SOAPBody</code> object. The new <code>SOAPFault</code> will have a
074 * <code>faultcode</code> element that is set to the <code>faultCode</code>
075 * parameter and a <code>faultstring</code> set to <code>faultstring</code>
076 * and localized to <code>locale</code>.
077 *
078 * @param faultCode a <code>Name</code> object giving the fault code to be
079 * set; must be one of the fault codes defined in the SOAP 1.1
080 * specification and of type QName
081 * @param faultString a <code>String</code> giving an explanation of the
082 * fault
083 * @param locale a <code>Locale</code> object indicating the native language
084 * of the <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,
090 Locale locale) throws SOAPException;
091
092 /**
093 * Creates a new <code>SOAPFault</code> object and adds it to this
094 * <code>SOAPBody</code> object. The new <code>SOAPFault</code> will have a
095 * <code>faultcode</code> element that is set to the <code>faultCode</code>
096 * parameter and a <code>faultstring</code> set to <code>faultstring</code>.
097 *
098 * @param faultCode a <code>Name</code> object giving the fault code to be
099 * set; must be one of the fault codes defined in the SOAP 1.1
100 * specification and of type QName
101 * @param faultString a <code>String</code> giving an explanation of the
102 * fault
103 * @return the new <code>SOAPFault</code> object
104 * @throws SOAPException if there is a SOAP error
105 */
106 public abstract SOAPFault addFault(Name faultCode, String faultString) throws SOAPException;
107
108 /**
109 * Adds the root node of the DOM <code>Document</code> to this
110 * <code>SOAPBody</code> object.
111 * <p>
112 * Calling this method invalidates the <code>document</code> parameter. The
113 * client application should discard all references to this
114 * <code>Document</code> and its contents upon calling
115 * <code>addDocument</code>. The behavior of an application that continues
116 * to use such references is undefined.
117 *
118 * @param document the <code>Document</code> object whose root node will be
119 * added to this <code>SOAPBody</code>
120 * @return the <code>SOAPBodyElement</code> that represents the root node
121 * that was added
122 * @throws SOAPException if the <code>Document</code> cannot be added
123 */
124 public abstract SOAPBodyElement addDocument(Document document) throws SOAPException;
125 }