SOAPEnvelope


1   /*
2    * $Id: SOAPEnvelope.java,v 1.6 2005/04/05 22:42:05 mk125090 Exp $
3    * $Revision: 1.6 $
4    * $Date: 2005/04/05 22:42:05 $
5    */
6   
7   /*
8    * The contents of this file are subject to the terms
9    * of the Common Development and Distribution License
10   * (the License).  You may not use this file except in
11   * compliance with the License.
12   * 
13   * You can obtain a copy of the license at
14   * https://glassfish.dev.java.net/public/CDDLv1.0.html.
15   * See the License for the specific language governing
16   * permissions and limitations under the License.
17   * 
18   * When distributing Covered Code, include this CDDL
19   * Header Notice in each file and include the License file
20   * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
21   * If applicable, add the following below the CDDL Header,
22   * with the fields enclosed by brackets [] replaced by
23   * you own identifying information:
24   * "Portions Copyrighted [year] [name of copyright owner]"
25   * 
26   * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
27   */
28  package javax.xml.soap;
29  
30  
31  /**
32   * The container for the SOAPHeader and SOAPBody portions of a
33   * <code>SOAPPart</code> object. By default, a <code>SOAPMessage</code>
34   * object is created with a <code>SOAPPart</code> object that has a
35   * <code>SOAPEnvelope</code> object. The <code>SOAPEnvelope</code> object
36   * by default has an empty <code>SOAPBody</code> object and an empty
37   * <code>SOAPHeader</code> object.  The <code>SOAPBody</code> object is
38   * required, and the <code>SOAPHeader</code> object, though
39   * optional, is used in the majority of cases. If the
40   * <code>SOAPHeader</code> object is not needed, it can be deleted,
41   * which is shown later.
42   * <P>
43   * A client can access the <code>SOAPHeader</code> and <code>SOAPBody</code>
44   * objects by calling the methods <code>SOAPEnvelope.getHeader</code> and
45   * <code>SOAPEnvelope.getBody</code>. The
46   * following  lines of code use these two methods after starting with
47   * the <code>SOAPMessage</code>
48   * object <i>message</i> to get the <code>SOAPPart</code> object <i>sp</i>,
49   * which is then used to get the <code>SOAPEnvelope</code> object <i>se</i>.
50   *
51   * <PRE>
52   *     SOAPPart sp = message.getSOAPPart();
53   *     SOAPEnvelope se = sp.getEnvelope();
54   *     SOAPHeader sh = se.getHeader();
55   *     SOAPBody sb = se.getBody();
56   * </PRE>
57   * <P>
58   * It is possible to change the body or header of a <code>SOAPEnvelope</code>
59   * object by retrieving the current one, deleting it, and then adding
60   * a new body or header. The <code>javax.xml.soap.Node</code> method
61   * <code>deleteNode</code> deletes the XML element (node) on which it is
62   * called.  For example, the following line of code deletes the
63   * <code>SOAPBody</code> object that is retrieved by the method <code>getBody</code>.
64   * <PRE>
65   *      se.getBody().detachNode();
66   * </PRE>
67   * To create a <code>SOAPHeader</code> object to replace the one that was removed,
68   * a client uses
69   * the method <code>SOAPEnvelope.addHeader</code>, which creates a new header and
70   * adds it to the <code>SOAPEnvelope</code> object. Similarly, the method
71   * <code>addBody</code> creates a new <code>SOAPBody</code> object and adds
72   * it to the <code>SOAPEnvelope</code> object. The following code fragment
73   * retrieves the current header, removes it, and adds a new one. Then
74   * it retrieves the current body, removes it, and adds a new one.
75   *
76   * <PRE>
77   *     SOAPPart sp = message.getSOAPPart();
78   *     SOAPEnvelope se = sp.getEnvelope();
79   *     se.getHeader().detachNode();
80   *     SOAPHeader sh = se.addHeader();
81   *     se.getBody().detachNode();
82   *     SOAPBody sb = se.addBody();
83   * </PRE>
84   * It is an error to add a <code>SOAPBody</code> or <code>SOAPHeader</code>
85   * object if one already exists.
86   * <P>
87   * The <code>SOAPEnvelope</code> interface provides three methods for creating
88   * <code>Name</code> objects. One method creates <code>Name</code> objects with
89   * a local name, a namespace prefix, and a namesapce URI. The second method creates
90   * <code>Name</code> objects with a local name and a namespace prefix, and the third
91   * creates <code>Name</code> objects with just a local name.  The following line of
92   * code, in which <i>se</i> is a <code>SOAPEnvelope</code> object, creates a new
93   * <code>Name</code> object with all three.
94   * <PRE>
95   *     Name name = se.createName("GetLastTradePrice", "WOMBAT",
96   *                                "http://www.wombat.org/trader");
97   * </PRE>
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 }
203
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags