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