1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185
/* * $Id: SOAPEnvelope.java,v 1.5 2004/04/02 01:24:18 ofung Exp $ * $Revision: 1.5 $ * $Date: 2004/04/02 01:24:18 $ */ /* * Copyright 2005 Sun Microsystems, Inc. All rights reserved. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ package javax.xml.soap; /** * The container for the SOAPHeader and SOAPBody portions of a * <code>SOAPPart</code> object. By default, a <code>SOAPMessage</code> * object is created with a <code>SOAPPart</code> object that has a * <code>SOAPEnvelope</code> object. The <code>SOAPEnvelope</code> object * by default has an empty <code>SOAPBody</code> object and an empty * <code>SOAPHeader</code> object. The <code>SOAPBody</code> object is * required, and the <code>SOAPHeader</code> object, though * optional, is used in the majority of cases. If the * <code>SOAPHeader</code> object is not needed, it can be deleted, * which is shown later. * <P> * A client can access the <code>SOAPHeader</code> and <code>SOAPBody</code> * objects by calling the methods <code>SOAPEnvelope.getHeader</code> and * <code>SOAPEnvelope.getBody</code>. The * following lines of code use these two methods after starting with * the <code>SOAPMessage</code> * object <i>message</i> to get the <code>SOAPPart</code> object <i>sp</i>, * which is then used to get the <code>SOAPEnvelope</code> object <i>se</i>. * * <PRE> * SOAPPart sp = message.getSOAPPart(); * SOAPEnvelope se = sp.getEnvelope(); * SOAPHeader sh = se.getHeader(); * SOAPBody sb = se.getBody(); * </PRE> * <P> * It is possible to change the body or header of a <code>SOAPEnvelope</code> * object by retrieving the current one, deleting it, and then adding * a new body or header. The <code>javax.xml.soap.Node</code> method * <code>deleteNode</code> deletes the XML element (node) on which it is * called. For example, the following line of code deletes the * <code>SOAPBody</code> object that is retrieved by the method <code>getBody</code>. * <PRE> * se.getBody().detachNode(); * </PRE> * To create a <code>SOAPHeader</code> object to replace the one that was removed, * a client uses * the method <code>SOAPEnvelope.addHeader</code>, which creates a new header and * adds it to the <code>SOAPEnvelope</code> object. Similarly, the method * <code>addBody</code> creates a new <code>SOAPBody</code> object and adds * it to the <code>SOAPEnvelope</code> object. The following code fragment * retrieves the current header, removes it, and adds a new one. Then * it retrieves the current body, removes it, and adds a new one. * * <PRE> * SOAPPart sp = message.getSOAPPart(); * SOAPEnvelope se = sp.getEnvelope(); * se.getHeader().detachNode(); * SOAPHeader sh = se.addHeader(); * se.getBody().detachNode(); * SOAPBody sb = se.addBody(); * </PRE> * It is an error to add a <code>SOAPBody</code> or <code>SOAPHeader</code> * object if one already exists. * <P> * The <code>SOAPEnvelope</code> interface provides three methods for creating * <code>Name</code> objects. One method creates <code>Name</code> objects with * a local name, a namespace prefix, and a namesapce URI. The second method creates * <code>Name</code> objects with a local name and a namespace prefix, and the third * creates <code>Name</code> objects with just a local name. The following line of * code, in which <i>se</i> is a <code>SOAPEnvelope</code> object, creates a new * <code>Name</code> object with all three. * <PRE> * Name name = se.createName("GetLastTradePrice", "WOMBAT", * "http://www.wombat.org/trader"); * </PRE> */ public interface SOAPEnvelope extends SOAPElement { /** * Creates a new <code>Name</code> object initialized with the * given local name, namespace prefix, and namespace URI. * <P> * This factory method creates <code>Name</code> objects for use in * the SOAP/XML document. * * @param localName a <code>String</code> giving the local name * @param prefix a <code>String</code> giving the prefix of the namespace * @param uri a <code>String</code> giving the URI of the namespace * @return a <code>Name</code> object initialized with the given * local name, namespace prefix, and namespace URI * @throws SOAPException if there is a SOAP error */ public abstract Name createName(String localName, String prefix, String uri) throws SOAPException; /** * Creates a new <code>Name</code> object initialized with the * given local name. * <P> * This factory method creates <code>Name</code> objects for use in * the SOAP/XML document. * * @param localName a <code>String</code> giving the local name * @return a <code>Name</code> object initialized with the given * local name * @throws SOAPException if there is a SOAP error */ public abstract Name createName(String localName) throws SOAPException; /** * Returns the <code>SOAPHeader</code> object for * this <code>SOAPEnvelope</code> object. * <P> * A new <code>SOAPMessage</code> object is by default created with a * <code>SOAPEnvelope</code> object that contains an empty * <code>SOAPHeader</code> object. As a result, the method * <code>getHeader</code> will always return a <code>SOAPHeader</code> * object unless the header has been removed and a new one has not * been added. * * @return the <code>SOAPHeader</code> object or <code>null</code> if * there is none * @exception SOAPException if there is a problem obtaining the * <code>SOAPHeader</code> object */ public SOAPHeader getHeader() throws SOAPException; /** * Returns the <code>SOAPBody</code> object associated with this * <code>SOAPEnvelope</code> object. * <P> * A new <code>SOAPMessage</code> object is by default created with a * <code>SOAPEnvelope</code> object that contains an empty * <code>SOAPBody</code> object. As a result, the method * <code>getBody</code> will always return a <code>SOAPBody</code> * object unless the body has been removed and a new one has not * been added. * * @return the <code>SOAPBody</code> object for this * <code>SOAPEnvelope</code> object or <code>null</code> * if there is none * @exception SOAPException if there is a problem obtaining the * <code>SOAPBody</code> object */ public SOAPBody getBody() throws SOAPException; /** * Creates a <code>SOAPHeader</code> object and sets it as the * <code>SOAPHeader</code> object for this <code>SOAPEnvelope</code> * object. * <P> * It is illegal to add a header when the envelope already * contains a header. Therefore, this method should be called * only after the existing header has been removed. * * @return the new <code>SOAPHeader</code> object * * @exception SOAPException if this * <code>SOAPEnvelope</code> object already contains a * valid <code>SOAPHeader</code> object */ public SOAPHeader addHeader() throws SOAPException; /** * Creates a <code>SOAPBody</code> object and sets it as the * <code>SOAPBody</code> object for this <code>SOAPEnvelope</code> * object. * <P> * It is illegal to add a body when the envelope already * contains a body. Therefore, this method should be called * only after the existing body has been removed. * * @return the new <code>SOAPBody</code> object * * @exception SOAPException if this * <code>SOAPEnvelope</code> object already contains a * valid <code>SOAPBody</code> object */ public SOAPBody addBody() throws SOAPException; }