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,
090 Locale locale) throws SOAPException;
091
092 /**
093 * Creates a new <code>SOAPFault</code> object and adds it to this <code>SOAPBody</code> object.
094 * The new <code>SOAPFault</code> will have a <code>faultcode</code> element that is set to the
095 * <code>faultCode</code> parameter and a <code>faultstring</code> set to
096 * <code>faultstring</code>.
097 *
098 * @param faultCode a <code>Name</code> object giving the fault code to be set; must be one of
099 * the fault codes defined in the SOAP 1.1 specification and of type QName
100 * @param faultString a <code>String</code> giving an explanation of the fault
101 * @return the new <code>SOAPFault</code> object
102 * @throws SOAPException if there is a SOAP error
103 */
104 public abstract SOAPFault addFault(Name faultCode, 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) throws SOAPException;
120
121 public abstract SOAPBodyElement addBodyElement(javax.xml.namespace.QName qname)
122 throws SOAPException;
123
124 public abstract SOAPFault addFault(javax.xml.namespace.QName qname,
125 java.lang.String s)
126 throws SOAPException;
127
128 public abstract SOAPFault addFault(javax.xml.namespace.QName qname,
129 java.lang.String s,
130 java.util.Locale locale)
131 throws SOAPException;
132
133 public abstract org.w3c.dom.Document extractContentAsDocument()
134 throws SOAPException;
135 }