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