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