1 /* 2 * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.xml.soap; 27 28 29 /** 30 * The container for the SOAPHeader and SOAPBody portions of a 31 * <code>SOAPPart</code> object. By default, a <code>SOAPMessage</code> 32 * object is created with a <code>SOAPPart</code> object that has a 33 * <code>SOAPEnvelope</code> object. The <code>SOAPEnvelope</code> object 34 * by default has an empty <code>SOAPBody</code> object and an empty 35 * <code>SOAPHeader</code> object. The <code>SOAPBody</code> object is 36 * required, and the <code>SOAPHeader</code> object, though 37 * optional, is used in the majority of cases. If the 38 * <code>SOAPHeader</code> object is not needed, it can be deleted, 39 * which is shown later. 40 * <P> 41 * A client can access the <code>SOAPHeader</code> and <code>SOAPBody</code> 42 * objects by calling the methods <code>SOAPEnvelope.getHeader</code> and 43 * <code>SOAPEnvelope.getBody</code>. The 44 * following lines of code use these two methods after starting with 45 * the <code>SOAPMessage</code> 46 * object <i>message</i> to get the <code>SOAPPart</code> object <i>sp</i>, 47 * which is then used to get the <code>SOAPEnvelope</code> object <i>se</i>. 48 * 49 * <PRE> 50 * SOAPPart sp = message.getSOAPPart(); 51 * SOAPEnvelope se = sp.getEnvelope(); 52 * SOAPHeader sh = se.getHeader(); 53 * SOAPBody sb = se.getBody(); 54 * </PRE> 55 * <P> 56 * It is possible to change the body or header of a <code>SOAPEnvelope</code> 57 * object by retrieving the current one, deleting it, and then adding 58 * a new body or header. The <code>javax.xml.soap.Node</code> method 59 * <code>deleteNode</code> deletes the XML element (node) on which it is 60 * called. For example, the following line of code deletes the 61 * <code>SOAPBody</code> object that is retrieved by the method <code>getBody</code>. 62 * <PRE> 63 * se.getBody().detachNode(); 64 * </PRE> 65 * To create a <code>SOAPHeader</code> object to replace the one that was removed, 66 * a client uses 67 * the method <code>SOAPEnvelope.addHeader</code>, which creates a new header and 68 * adds it to the <code>SOAPEnvelope</code> object. Similarly, the method 69 * <code>addBody</code> creates a new <code>SOAPBody</code> object and adds 70 * it to the <code>SOAPEnvelope</code> object. The following code fragment 71 * retrieves the current header, removes it, and adds a new one. Then 72 * it retrieves the current body, removes it, and adds a new one. 73 * 74 * <PRE> 75 * SOAPPart sp = message.getSOAPPart(); 76 * SOAPEnvelope se = sp.getEnvelope(); 77 * se.getHeader().detachNode(); 78 * SOAPHeader sh = se.addHeader(); 79 * se.getBody().detachNode(); 80 * SOAPBody sb = se.addBody(); 81 * </PRE> 82 * It is an error to add a <code>SOAPBody</code> or <code>SOAPHeader</code> 83 * object if one already exists. 84 * <P> 85 * The <code>SOAPEnvelope</code> interface provides three methods for creating 86 * <code>Name</code> objects. One method creates <code>Name</code> objects with 87 * a local name, a namespace prefix, and a namesapce URI. The second method creates 88 * <code>Name</code> objects with a local name and a namespace prefix, and the third 89 * creates <code>Name</code> objects with just a local name. The following line of 90 * code, in which <i>se</i> is a <code>SOAPEnvelope</code> object, creates a new 91 * <code>Name</code> object with all three. 92 * <PRE> 93 * Name name = se.createName("GetLastTradePrice", "WOMBAT", 94 * "http://www.wombat.org/trader"); 95 * </PRE> 96 * 97 * @since 1.6 98 */ 99 public interface SOAPEnvelope extends SOAPElement { 100 101 /** 102 * Creates a new <code>Name</code> object initialized with the 103 * given local name, namespace prefix, and namespace URI. 104 * <P> 105 * This factory method creates <code>Name</code> objects for use in 106 * the SOAP/XML document. 107 * 108 * @param localName a <code>String</code> giving the local name 109 * @param prefix a <code>String</code> giving the prefix of the namespace 110 * @param uri a <code>String</code> giving the URI of the namespace 111 * @return a <code>Name</code> object initialized with the given 112 * local name, namespace prefix, and namespace URI 113 * @throws SOAPException if there is a SOAP error 114 */ 115 public abstract Name createName(String localName, String prefix, 116 String uri) 117 throws SOAPException; 118 119 /** 120 * Creates a new <code>Name</code> object initialized with the 121 * given local name. 122 * <P> 123 * This factory method creates <code>Name</code> objects for use in 124 * the SOAP/XML document. 125 * 126 * @param localName a <code>String</code> giving the local name 127 * @return a <code>Name</code> object initialized with the given 128 * local name 129 * @throws SOAPException if there is a SOAP error 130 */ 131 public abstract Name createName(String localName) 132 throws SOAPException; 133 134 /** 135 * Returns the <code>SOAPHeader</code> object for 136 * this <code>SOAPEnvelope</code> object. 137 * <P> 138 * A new <code>SOAPMessage</code> object is by default created with a 139 * <code>SOAPEnvelope</code> object that contains an empty 140 * <code>SOAPHeader</code> object. As a result, the method 141 * <code>getHeader</code> will always return a <code>SOAPHeader</code> 142 * object unless the header has been removed and a new one has not 143 * been added. 144 * 145 * @return the <code>SOAPHeader</code> object or <code>null</code> if 146 * there is none 147 * @exception SOAPException if there is a problem obtaining the 148 * <code>SOAPHeader</code> object 149 */ 150 public SOAPHeader getHeader() throws SOAPException; 151 152 /** 153 * Returns the <code>SOAPBody</code> object associated with this 154 * <code>SOAPEnvelope</code> object. 155 * <P> 156 * A new <code>SOAPMessage</code> object is by default created with a 157 * <code>SOAPEnvelope</code> object that contains an empty 158 * <code>SOAPBody</code> object. As a result, the method 159 * <code>getBody</code> will always return a <code>SOAPBody</code> 160 * object unless the body has been removed and a new one has not 161 * been added. 162 * 163 * @return the <code>SOAPBody</code> object for this 164 * <code>SOAPEnvelope</code> object or <code>null</code> 165 * if there is none 166 * @exception SOAPException if there is a problem obtaining the 167 * <code>SOAPBody</code> object 168 */ 169 public SOAPBody getBody() throws SOAPException; 170 /** 171 * Creates a <code>SOAPHeader</code> object and sets it as the 172 * <code>SOAPHeader</code> object for this <code>SOAPEnvelope</code> 173 * object. 174 * <P> 175 * It is illegal to add a header when the envelope already 176 * contains a header. Therefore, this method should be called 177 * only after the existing header has been removed. 178 * 179 * @return the new <code>SOAPHeader</code> object 180 * 181 * @exception SOAPException if this 182 * <code>SOAPEnvelope</code> object already contains a 183 * valid <code>SOAPHeader</code> object 184 */ 185 public SOAPHeader addHeader() throws SOAPException; 186 /** 187 * Creates a <code>SOAPBody</code> object and sets it as the 188 * <code>SOAPBody</code> object for this <code>SOAPEnvelope</code> 189 * object. 190 * <P> 191 * It is illegal to add a body when the envelope already 192 * contains a body. Therefore, this method should be called 193 * only after the existing body has been removed. 194 * 195 * @return the new <code>SOAPBody</code> object 196 * 197 * @exception SOAPException if this 198 * <code>SOAPEnvelope</code> object already contains a 199 * valid <code>SOAPBody</code> object 200 */ 201 public SOAPBody addBody() throws SOAPException; 202 } | 1 /* 2 * Copyright (c) 2004, 2015, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.xml.soap; 27 28 29 /** 30 * The container for the SOAPHeader and SOAPBody portions of a 31 * {@code SOAPPart} object. By default, a {@code SOAPMessage} 32 * object is created with a {@code SOAPPart} object that has a 33 * {@code SOAPEnvelope} object. The {@code SOAPEnvelope} object 34 * by default has an empty {@code SOAPBody} object and an empty 35 * {@code SOAPHeader} object. The {@code SOAPBody} object is 36 * required, and the {@code SOAPHeader} object, though 37 * optional, is used in the majority of cases. If the 38 * {@code SOAPHeader} object is not needed, it can be deleted, 39 * which is shown later. 40 * <P> 41 * A client can access the {@code SOAPHeader} and {@code SOAPBody} 42 * objects by calling the methods {@code SOAPEnvelope.getHeader} and 43 * {@code SOAPEnvelope.getBody}. The 44 * following lines of code use these two methods after starting with 45 * the {@code SOAPMessage} 46 * object <i>message</i> to get the {@code SOAPPart} object <i>sp</i>, 47 * which is then used to get the {@code SOAPEnvelope} object <i>se</i>. 48 * 49 * <pre>{@code 50 * SOAPPart sp = message.getSOAPPart(); 51 * SOAPEnvelope se = sp.getEnvelope(); 52 * SOAPHeader sh = se.getHeader(); 53 * SOAPBody sb = se.getBody(); 54 * }</pre> 55 * <P> 56 * It is possible to change the body or header of a {@code SOAPEnvelope} 57 * object by retrieving the current one, deleting it, and then adding 58 * a new body or header. The {@code javax.xml.soap.Node} method 59 * {@code deleteNode} deletes the XML element (node) on which it is 60 * called. For example, the following line of code deletes the 61 * {@code SOAPBody} object that is retrieved by the method {@code getBody}. 62 * <pre>{@code 63 * se.getBody().detachNode(); 64 * }</pre> 65 * To create a {@code SOAPHeader} object to replace the one that was removed, 66 * a client uses 67 * the method {@code SOAPEnvelope.addHeader}, which creates a new header and 68 * adds it to the {@code SOAPEnvelope} object. Similarly, the method 69 * {@code addBody} creates a new {@code SOAPBody} object and adds 70 * it to the {@code SOAPEnvelope} object. The following code fragment 71 * retrieves the current header, removes it, and adds a new one. Then 72 * it retrieves the current body, removes it, and adds a new one. 73 * 74 * <pre>{@code 75 * SOAPPart sp = message.getSOAPPart(); 76 * SOAPEnvelope se = sp.getEnvelope(); 77 * se.getHeader().detachNode(); 78 * SOAPHeader sh = se.addHeader(); 79 * se.getBody().detachNode(); 80 * SOAPBody sb = se.addBody(); 81 * }</pre> 82 * It is an error to add a {@code SOAPBody} or {@code SOAPHeader} 83 * object if one already exists. 84 * <P> 85 * The {@code SOAPEnvelope} interface provides three methods for creating 86 * {@code Name} objects. One method creates {@code Name} objects with 87 * a local name, a namespace prefix, and a namesapce URI. The second method creates 88 * {@code Name} objects with a local name and a namespace prefix, and the third 89 * creates {@code Name} objects with just a local name. The following line of 90 * code, in which <i>se</i> is a {@code SOAPEnvelope} object, creates a new 91 * {@code Name} object with all three. 92 * <pre>{@code 93 * Name name = se.createName("GetLastTradePrice", "WOMBAT", 94 * "http://www.wombat.org/trader"); 95 * }</pre> 96 * 97 * @since 1.6 98 */ 99 public interface SOAPEnvelope extends SOAPElement { 100 101 /** 102 * Creates a new {@code Name} object initialized with the 103 * given local name, namespace prefix, and namespace URI. 104 * <P> 105 * This factory method creates {@code Name} objects for use in 106 * the SOAP/XML document. 107 * 108 * @param localName a {@code String} giving the local name 109 * @param prefix a {@code String} giving the prefix of the namespace 110 * @param uri a {@code String} giving the URI of the namespace 111 * @return a {@code Name} object initialized with the given 112 * local name, namespace prefix, and namespace URI 113 * @throws SOAPException if there is a SOAP error 114 */ 115 public abstract Name createName(String localName, String prefix, 116 String uri) 117 throws SOAPException; 118 119 /** 120 * Creates a new {@code Name} object initialized with the 121 * given local name. 122 * <P> 123 * This factory method creates {@code Name} objects for use in 124 * the SOAP/XML document. 125 * 126 * @param localName a {@code String} giving the local name 127 * @return a {@code Name} object initialized with the given 128 * local name 129 * @throws SOAPException if there is a SOAP error 130 */ 131 public abstract Name createName(String localName) 132 throws SOAPException; 133 134 /** 135 * Returns the {@code SOAPHeader} object for 136 * this {@code SOAPEnvelope} object. 137 * <P> 138 * A new {@code SOAPMessage} object is by default created with a 139 * {@code SOAPEnvelope} object that contains an empty 140 * {@code SOAPHeader} object. As a result, the method 141 * {@code getHeader} will always return a {@code SOAPHeader} 142 * object unless the header has been removed and a new one has not 143 * been added. 144 * 145 * @return the {@code SOAPHeader} object or {@code null} if 146 * there is none 147 * @exception SOAPException if there is a problem obtaining the 148 * {@code SOAPHeader} object 149 */ 150 public SOAPHeader getHeader() throws SOAPException; 151 152 /** 153 * Returns the {@code SOAPBody} object associated with this 154 * {@code SOAPEnvelope} object. 155 * <P> 156 * A new {@code SOAPMessage} object is by default created with a 157 * {@code SOAPEnvelope} object that contains an empty 158 * {@code SOAPBody} object. As a result, the method 159 * {@code getBody} will always return a {@code SOAPBody} 160 * object unless the body has been removed and a new one has not 161 * been added. 162 * 163 * @return the {@code SOAPBody} object for this 164 * {@code SOAPEnvelope} object or {@code null} 165 * if there is none 166 * @exception SOAPException if there is a problem obtaining the 167 * {@code SOAPBody} object 168 */ 169 public SOAPBody getBody() throws SOAPException; 170 /** 171 * Creates a {@code SOAPHeader} object and sets it as the 172 * {@code SOAPHeader} object for this {@code SOAPEnvelope} 173 * object. 174 * <P> 175 * It is illegal to add a header when the envelope already 176 * contains a header. Therefore, this method should be called 177 * only after the existing header has been removed. 178 * 179 * @return the new {@code SOAPHeader} object 180 * 181 * @exception SOAPException if this 182 * {@code SOAPEnvelope} object already contains a 183 * valid {@code SOAPHeader} object 184 */ 185 public SOAPHeader addHeader() throws SOAPException; 186 /** 187 * Creates a {@code SOAPBody} object and sets it as the 188 * {@code SOAPBody} object for this {@code SOAPEnvelope} 189 * object. 190 * <P> 191 * It is illegal to add a body when the envelope already 192 * contains a body. Therefore, this method should be called 193 * only after the existing body has been removed. 194 * 195 * @return the new {@code SOAPBody} object 196 * 197 * @exception SOAPException if this 198 * {@code SOAPEnvelope} object already contains a 199 * valid {@code SOAPBody} object 200 */ 201 public SOAPBody addBody() throws SOAPException; 202 } |