API Overview API Index Package Overview Direct link to this page
JDK 1.6
  javax.xml.soap. SOAPEnvelope View Javadoc
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;
}

Generated By: JavaOnTracks Doclet 0.1.4     ©Thibaut Colar