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