javax.xml.soap.SOAPEnvelope Maven / Gradle / Ivy
Show all versions of jboss-javaee-all-8.0
/*
* $Id: SOAPEnvelope.java,v 1.7 2006/03/30 00:59:41 ofung Exp $
* $Revision: 1.7 $
* $Date: 2006/03/30 00:59:41 $
*/
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the License). You may not use this file except in
* compliance with the License.
*
* You can obtain a copy of the license at
* https://glassfish.dev.java.net/public/CDDLv1.0.html.
* See the License for the specific language governing
* permissions and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* Header Notice in each file and include the License file
* at https://glassfish.dev.java.net/public/CDDLv1.0.html.
* If applicable, add the following below the CDDL Header,
* with the fields enclosed by brackets [] replaced by
* you own identifying information:
* "Portions Copyrighted [year] [name of copyright owner]"
*
* Copyright 2006 Sun Microsystems Inc. All Rights Reserved
*/
package javax.xml.soap;
/**
* The container for the SOAPHeader and SOAPBody portions of a
* SOAPPart object. By default, a SOAPMessage
* object is created with a SOAPPart object that has a
* SOAPEnvelope object. The SOAPEnvelope object
* by default has an empty SOAPBody object and an empty
* SOAPHeader object. The SOAPBody object is
* required, and the SOAPHeader object, though
* optional, is used in the majority of cases. If the
* SOAPHeader object is not needed, it can be deleted,
* which is shown later.
*
* A client can access the SOAPHeader and SOAPBody
* objects by calling the methods SOAPEnvelope.getHeader and
* SOAPEnvelope.getBody. The
* following lines of code use these two methods after starting with
* the SOAPMessage
* object message to get the SOAPPart object sp,
* which is then used to get the SOAPEnvelope object se.
*
*
* SOAPPart sp = message.getSOAPPart();
* SOAPEnvelope se = sp.getEnvelope();
* SOAPHeader sh = se.getHeader();
* SOAPBody sb = se.getBody();
*
*
* 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 javax.xml.soap.Node method
* deleteNode deletes the XML element (node) on which it is
* called. For example, the following line of code deletes the
* SOAPBody object that is retrieved by the method getBody.
*
* se.getBody().detachNode();
*
* To create a SOAPHeader object to replace the one that was removed,
* a client uses
* the method SOAPEnvelope.addHeader, which creates a new header and
* adds it to the SOAPEnvelope object. Similarly, the method
* addBody creates a new SOAPBody object and adds
* it to the 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.
*
*
* SOAPPart sp = message.getSOAPPart();
* SOAPEnvelope se = sp.getEnvelope();
* se.getHeader().detachNode();
* SOAPHeader sh = se.addHeader();
* se.getBody().detachNode();
* SOAPBody sb = se.addBody();
*
* It is an error to add a SOAPBody or SOAPHeader
* object if one already exists.
*
* The SOAPEnvelope interface provides three methods for creating
* Name objects. One method creates Name objects with
* a local name, a namespace prefix, and a namesapce URI. The second method creates
* Name objects with a local name and a namespace prefix, and the third
* creates Name objects with just a local name. The following line of
* code, in which se is a SOAPEnvelope object, creates a new
* Name object with all three.
*
* Name name = se.createName("GetLastTradePrice", "WOMBAT",
* "http://www.wombat.org/trader");
*
*/
public interface SOAPEnvelope extends SOAPElement {
/**
* Creates a new Name object initialized with the
* given local name, namespace prefix, and namespace URI.
*
* This factory method creates Name objects for use in
* the SOAP/XML document.
*
* @param localName a String giving the local name
* @param prefix a String giving the prefix of the namespace
* @param uri a String giving the URI of the namespace
* @return a 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 Name object initialized with the
* given local name.
*
* This factory method creates Name objects for use in
* the SOAP/XML document.
*
* @param localName a String giving the local name
* @return a 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 SOAPHeader object for
* this SOAPEnvelope object.
*
* A new SOAPMessage object is by default created with a
* SOAPEnvelope object that contains an empty
* SOAPHeader object. As a result, the method
* getHeader will always return a SOAPHeader
* object unless the header has been removed and a new one has not
* been added.
*
* @return the SOAPHeader object or null if
* there is none
* @exception SOAPException if there is a problem obtaining the
* SOAPHeader object
*/
public SOAPHeader getHeader() throws SOAPException;
/**
* Returns the SOAPBody object associated with this
* SOAPEnvelope object.
*
* A new SOAPMessage object is by default created with a
* SOAPEnvelope object that contains an empty
* SOAPBody object. As a result, the method
* getBody will always return a SOAPBody
* object unless the body has been removed and a new one has not
* been added.
*
* @return the SOAPBody object for this
* SOAPEnvelope object or null
* if there is none
* @exception SOAPException if there is a problem obtaining the
* SOAPBody object
*/
public SOAPBody getBody() throws SOAPException;
/**
* Creates a SOAPHeader object and sets it as the
* SOAPHeader object for this SOAPEnvelope
* object.
*
* 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 SOAPHeader object
*
* @exception SOAPException if this
* SOAPEnvelope object already contains a
* valid SOAPHeader object
*/
public SOAPHeader addHeader() throws SOAPException;
/**
* Creates a SOAPBody object and sets it as the
* SOAPBody object for this SOAPEnvelope
* object.
*
* 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 SOAPBody object
*
* @exception SOAPException if this
* SOAPEnvelope object already contains a
* valid SOAPBody object
*/
public SOAPBody addBody() throws SOAPException;
}