The Axis 2 SOAPEnvelope.java source code
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package javax.xml.soap;
/**
* The container for the SOAPHeader and SOAPBody portions of a <CODE>SOAPPart object. By
* default, a <CODE> SOAPMessage object is created with a SOAPPart object that
* has a <CODE>SOAPEnvelope object. The SOAPEnvelope object by default has an
* empty <CODE>SOAPBody object and an empty SOAPHeader object. The
* <CODE>SOAPBody object is required, and the SOAPHeader object, though
* optional, is used in the majority of cases. If the <CODE> SOAPHeader object is not needed,
* it can be deleted, which is shown later.</P>
* <p/>
* <P>A client can access the SOAPHeader and SOAPBody objects by calling
* the methods <CODE> SOAPEnvelope.getHeader and SOAPEnvelope.getBody. The
* following lines of code use these two methods after starting with the <CODE> SOAPMessage
* object <I>message to get the SOAPPart object sp, which is then used to
* get the <CODE>SOAPEnvelope object se. SOAPPart sp =
* message.getSOAPPart(); SOAPEnvelope se = sp.getEnvelope(); SOAPHeader sh = se.getHeader();
* SOAPBody sb = se.getBody(); </PRE>
* <p/>
* <P>It is possible to change the body or header of a SOAPEnvelope object by
* retrieving the current one, deleting it, and then adding a new body or header. The <CODE>
* javax.xml.soap.Node</CODE> method detachNode detaches the XML element (node) on
* which it is called. For example, the following line of code deletes the <CODE> SOAPBody
* object that is retrieved by the method <CODE> getBody.
* se.getBody().detachNode(); </PRE> To create a SOAPHeader object to replace the one
* that was removed, a client uses the method <CODE> SOAPEnvelope.addHeaderBlock, which
* creates a new header and adds it to the <CODE>SOAPEnvelope object. Similarly, the method
* <CODE>addBody creates a new SOAPBody object and adds it to the
* <CODE>SOAPEnvelope 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.addHeaderBlock(); se.getBody().detachNode();
* SOAPBody sb = se.addBody(); </PRE> It is an error to add a SOAPBody or
* SOAPHeader</CODE> object if one already exists.
* <p/>
* <P>The SOAPEnvelope interface provides three methods for creating Name
* objects. One method creates <CODE>Name objects with a local name, a namespace prefix, and
* a namesapce URI. The second method creates <CODE>Name objects with a local name and a
* namespace prefix, and the third creates <CODE>Name objects with just a local name. The
* following line of code, in which <I>se is a SOAPEnvelope object, creates a new
* <CODE>Name object with all three. Name name = se.createName("GetLastTradePrice",
* "WOMBAT", "http://www.wombat.org/trader"); </PRE>
*/
public interface SOAPEnvelope extends SOAPElement {
/**
* Creates a new <CODE>Name object initialized with the given local name, namespace
* prefix, and namespace URI.
* <p/>
* <P>This factory method creates Name objects for use in the SOAP/XML document.
*
* @param localName a <CODE>String giving the local name
* @param prefix a <CODE>String giving the prefix of the namespace
* @param uri a <CODE>String giving the URI of the namespace
* @return a <CODE>Name 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 object initialized with the given local name.
* <p/>
* <P>This factory method creates Name objects for use in the SOAP/XML document.
*
* @param localName a <CODE>String giving the local name
* @return a <CODE>Name 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 object for this SOAPEnvelope object.
* <p/>
* <P>A new SOAPMessage object is by default created with a
* <CODE>SOAPEnvelope object that contains an empty SOAPHeader object. As a
* result, the method <CODE>getHeader will always return a SOAPHeader object
* unless the header has been removed and a new one has not been added.
*
* @return the <CODE>SOAPHeader object or null if there is none
* @throws SOAPException if there is a problem obtaining the <CODE>SOAPHeader object
*/
public abstract SOAPHeader getHeader() throws SOAPException;
/**
* Returns the <CODE>SOAPBody object associated with this SOAPEnvelope
* object.
* <p/>
* <P>A new SOAPMessage object is by default created with a
* <CODE>SOAPEnvelope object that contains an empty SOAPBody object. As a
* result, the method <CODE>getBody will always return a SOAPBody object
* unless the body has been removed and a new one has not been added.
*
* @return the <CODE>SOAPBody object for this SOAPEnvelope object or
* <CODE>null if there is none
* @throws SOAPException if there is a problem obtaining the <CODE>SOAPBody object
*/
public abstract SOAPBody getBody() throws SOAPException;
/**
* Creates a <CODE>SOAPHeader object and sets it as the SOAPHeader object
* for this <CODE> SOAPEnvelope object.
* <p/>
* <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 object
* @throws SOAPException if this <CODE> SOAPEnvelope object already contains a valid
* <CODE>SOAPHeader object
*/
public abstract SOAPHeader addHeader() throws SOAPException;
/**
* Creates a <CODE>SOAPBody object and sets it as the SOAPBody object for
* this <CODE> SOAPEnvelope object.
* <p/>
* <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 object
* @throws SOAPException if this <CODE> SOAPEnvelope object already contains a valid
* <CODE>SOAPBody object
*/
public abstract SOAPBody addBody() throws SOAPException;
}
Other Axis 2 examples (source code examples)
Here is a short list of links related to this Axis 2 SOAPEnvelope.java source code file:
The search page
Other Axis 2 source code examples at this package level
Click here to learn more about this project
