javax.xml.soap.SOAPEnvelope Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2004-2012 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* http://glassfish.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
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;
}