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 /** 023 * The container for the SOAPHeader and SOAPBody portions of a 024 * <CODE>SOAPPart</CODE> object. By default, a <CODE> 025 * SOAPMessage</CODE> object is created with a <CODE> 026 * SOAPPart</CODE> object that has a <CODE>SOAPEnvelope</CODE> 027 * object. The <CODE>SOAPEnvelope</CODE> object by default has an 028 * empty <CODE>SOAPBody</CODE> object and an empty <CODE> 029 * SOAPHeader</CODE> object. The <CODE>SOAPBody</CODE> object is 030 * required, and the <CODE>SOAPHeader</CODE> object, though 031 * optional, is used in the majority of cases. If the <CODE> 032 * SOAPHeader</CODE> object is not needed, it can be deleted, 033 * which is shown later.</P> 034 * 035 * <P>A client can access the <CODE>SOAPHeader</CODE> and <CODE> 036 * SOAPBody</CODE> objects by calling the methods <CODE> 037 * SOAPEnvelope.getHeader</CODE> and <CODE> 038 * SOAPEnvelope.getBody</CODE>. The following lines of code use 039 * these two methods after starting with the <CODE> 040 * SOAPMessage</CODE> object <I>message</I> to get the <CODE> 041 * SOAPPart</CODE> object <I>sp</I>, which is then used to get the 042 * <CODE>SOAPEnvelope</CODE> object <I>se</I>.</P> 043 * <PRE> 044 * SOAPPart sp = message.getSOAPPart(); 045 * SOAPEnvelope se = sp.getEnvelope(); 046 * SOAPHeader sh = se.getHeader(); 047 * SOAPBody sb = se.getBody(); 048 * </PRE> 049 * 050 * <P>It is possible to change the body or header of a <CODE> 051 * SOAPEnvelope</CODE> object by retrieving the current one, 052 * deleting it, and then adding a new body or header. The <CODE> 053 * javax.xml.soap.Node</CODE> method <CODE>detachNode</CODE> 054 * detaches the XML element (node) on which it is called. For 055 * example, the following line of code deletes the <CODE> 056 * SOAPBody</CODE> object that is retrieved by the method <CODE> 057 * getBody</CODE>.</P> 058 * <PRE> 059 * se.getBody().detachNode(); 060 * </PRE> 061 * To create a <CODE>SOAPHeader</CODE> object to replace the one 062 * that was removed, a client uses the method <CODE> 063 * SOAPEnvelope.addHeader</CODE>, which creates a new header and 064 * adds it to the <CODE>SOAPEnvelope</CODE> object. Similarly, the 065 * method <CODE>addBody</CODE> creates a new <CODE>SOAPBody</CODE> 066 * object and adds it to the <CODE>SOAPEnvelope</CODE> object. The 067 * following code fragment retrieves the current header, removes 068 * it, and adds a new one. Then it retrieves the current body, 069 * removes it, and adds a new one. 070 * <PRE> 071 * SOAPPart sp = message.getSOAPPart(); 072 * SOAPEnvelope se = sp.getEnvelope(); 073 * se.getHeader().detachNode(); 074 * SOAPHeader sh = se.addHeader(); 075 * se.getBody().detachNode(); 076 * SOAPBody sb = se.addBody(); 077 * </PRE> 078 * It is an error to add a <CODE>SOAPBody</CODE> or <CODE> 079 * SOAPHeader</CODE> object if one already exists. 080 * 081 * <P>The <CODE>SOAPEnvelope</CODE> interface provides three 082 * methods for creating <CODE>Name</CODE> objects. One method 083 * creates <CODE>Name</CODE> objects with a local name, a 084 * namespace prefix, and a namesapce URI. The second method 085 * creates <CODE>Name</CODE> objects with a local name and a 086 * namespace prefix, and the third creates <CODE>Name</CODE> 087 * objects with just a local name. The following line of code, in 088 * which <I>se</I> is a <CODE>SOAPEnvelope</CODE> object, creates 089 * a new <CODE>Name</CODE> object with all three.</P> 090 * <PRE> 091 * Name name = se.createName("GetLastTradePrice", "WOMBAT", 092 * "http://www.wombat.org/trader"); 093 * </PRE> 094 */ 095 public interface SOAPEnvelope extends SOAPElement { 096 097 /** 098 * Creates a new <CODE>Name</CODE> object initialized with the 099 * given local name, namespace prefix, and namespace URI. 100 * 101 * <P>This factory method creates <CODE>Name</CODE> objects 102 * for use in the SOAP/XML document. 103 * @param localName a <CODE>String</CODE> giving 104 * the local name 105 * @param prefix a <CODE>String</CODE> giving 106 * the prefix of the namespace 107 * @param uri a <CODE>String</CODE> giving the 108 * URI of the namespace 109 * @return a <CODE>Name</CODE> object initialized with the given 110 * local name, namespace prefix, and namespace URI 111 * @throws SOAPException if there is a SOAP error 112 */ 113 public abstract Name createName(String localName, String prefix, String uri) 114 throws SOAPException; 115 116 /** 117 * Creates a new <CODE>Name</CODE> object initialized with the 118 * given local name. 119 * 120 * <P>This factory method creates <CODE>Name</CODE> objects 121 * for use in the SOAP/XML document. 122 * 123 * @param localName a <CODE>String</CODE> giving 124 * the local name 125 * @return a <CODE>Name</CODE> object initialized with the given 126 * local name 127 * @throws SOAPException if there is a SOAP error 128 */ 129 public abstract Name createName(String localName) throws SOAPException; 130 131 /** 132 * Returns the <CODE>SOAPHeader</CODE> object for this <CODE> 133 * SOAPEnvelope</CODE> object. 134 * 135 * <P>A new <CODE>SOAPMessage</CODE> object is by default 136 * created with a <CODE>SOAPEnvelope</CODE> object that 137 * contains an empty <CODE>SOAPHeader</CODE> object. As a 138 * result, the method <CODE>getHeader</CODE> will always 139 * return a <CODE>SOAPHeader</CODE> object unless the header 140 * has been removed and a new one has not been added. 141 * @return the <CODE>SOAPHeader</CODE> object or <CODE> 142 * null</CODE> if there is none 143 * @throws SOAPException if there is a problem 144 * obtaining the <CODE>SOAPHeader</CODE> object 145 */ 146 public abstract SOAPHeader getHeader() throws SOAPException; 147 148 /** 149 * Returns the <CODE>SOAPBody</CODE> object associated with 150 * this <CODE>SOAPEnvelope</CODE> object. 151 * 152 * <P>A new <CODE>SOAPMessage</CODE> object is by default 153 * created with a <CODE>SOAPEnvelope</CODE> object that 154 * contains an empty <CODE>SOAPBody</CODE> object. As a 155 * result, the method <CODE>getBody</CODE> will always return 156 * a <CODE>SOAPBody</CODE> object unless the body has been 157 * removed and a new one has not been added. 158 * @return the <CODE>SOAPBody</CODE> object for this <CODE> 159 * SOAPEnvelope</CODE> object or <CODE>null</CODE> if there 160 * is none 161 * @throws SOAPException if there is a problem 162 * obtaining the <CODE>SOAPBody</CODE> object 163 */ 164 public abstract SOAPBody getBody() throws SOAPException; 165 166 /** 167 * Creates a <CODE>SOAPHeader</CODE> object and sets it as the 168 * <CODE>SOAPHeader</CODE> object for this <CODE> 169 * SOAPEnvelope</CODE> object. 170 * 171 * <P>It is illegal to add a header when the envelope already 172 * contains a header. Therefore, this method should be called 173 * only after the existing header has been removed. 174 * @return the new <CODE>SOAPHeader</CODE> object 175 * @throws SOAPException if this <CODE> 176 * SOAPEnvelope</CODE> object already contains a valid 177 * <CODE>SOAPHeader</CODE> object 178 */ 179 public abstract SOAPHeader addHeader() throws SOAPException; 180 181 /** 182 * Creates a <CODE>SOAPBody</CODE> object and sets it as the 183 * <CODE>SOAPBody</CODE> object for this <CODE> 184 * SOAPEnvelope</CODE> object. 185 * 186 * <P>It is illegal to add a body when the envelope already 187 * contains a body. Therefore, this method should be called 188 * only after the existing body has been removed. 189 * @return the new <CODE>SOAPBody</CODE> object 190 * @throws SOAPException if this <CODE> 191 * SOAPEnvelope</CODE> object already contains a valid 192 * <CODE>SOAPBody</CODE> object 193 */ 194 public abstract SOAPBody addBody() throws SOAPException; 195 }