javax.xml.soap.SOAPBody Maven / Gradle / Ivy

Go to download
/*
 * Copyright 2001-2004 The Apache Software Foundation.
 * 
 * Licensed 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;

import org.w3c.dom.Document;

import java.util.Locale;

/**
 * An object that represents the contents of the SOAP body
 * element in a SOAP message. A SOAP body element consists of XML data
 * that affects the way the application-specific content is processed.
 * 
 * A SOAPBody object contains SOAPBodyElement
 * objects, which have the content for the SOAP body.
 * A SOAPFault object, which carries status and/or
 * error information, is an example of a SOAPBodyElement object.
 * @see SOAPFault SOAPFault
 */
public interface SOAPBody extends SOAPElement {

    /**
     * Creates a new SOAPFault object and adds it to
     * this SOAPBody object.
     * @return the new SOAPFault object
     * @throws  SOAPException if there is a SOAP error
     */
    public abstract SOAPFault addFault() throws SOAPException;

    /**
     * Indicates whether a SOAPFault object exists in
     * this SOAPBody object.
     * @return true if a SOAPFault object exists in
     *     this SOAPBody object; false
     *     otherwise
     */
    public abstract boolean hasFault();

    /**
     * Returns the SOAPFault object in this SOAPBody
     * object.
     * @return the SOAPFault object in this SOAPBody
     *    object
     */
    public abstract SOAPFault getFault();

    /**
     * Creates a new SOAPBodyElement object with the
     * specified name and adds it to this SOAPBody object.
     * @param name a Name object with the name for the new
     *   SOAPBodyElement object
     * @return the new SOAPBodyElement object
     * @throws SOAPException  if a SOAP error occurs
     */
    public abstract SOAPBodyElement addBodyElement(Name name)
        throws SOAPException;

    /**
     * Creates a new SOAPFault object and adds it to this
     * SOAPBody object. The new SOAPFault will have a
     * faultcode element that is set to the faultCode
     * parameter and a faultstring set to faultstring
     * and localized to locale.
     *
     * @param faultCode a Name object giving the fault code to be
     *              set; must be one of the fault codes defined in the SOAP 1.1
     *              specification and of type QName
     * @param faultString a String giving an explanation of the
     *              fault
     * @param locale a Locale object indicating the native language
     *              of the faultString
     * @return the new SOAPFault object
     * @throws SOAPException  if there is a SOAP error
     */
    public abstract SOAPFault addFault(Name faultCode,
                                       String faultString,
                                       Locale locale) throws SOAPException;

    /**
     * Creates a new SOAPFault object and adds it to this
     * SOAPBody object. The new SOAPFault will have a
     * faultcode element that is set to the faultCode
     * parameter and a faultstring set to faultstring.
     *
     * @param faultCode a Name object giving the fault code to be
     *              set; must be one of the fault codes defined in the SOAP 1.1
     *              specification and of type QName
     * @param faultString a String giving an explanation of the
     *              fault
     * @return the new SOAPFault object
     * @throws SOAPException  if there is a SOAP error
     */
    public abstract SOAPFault addFault(Name faultCode, String faultString) throws SOAPException;

    /**
     * Adds the root node of the DOM Document to this
     * SOAPBody object.
     * 

     * Calling this method invalidates the document parameter. The
     * client application should discard all references to this
     * Document and its contents upon calling
     * addDocument. The behavior of an application that continues
     * to use such references is undefined.
     *
     * @param document the Document object whose root node will be
     *              added to this SOAPBody
     * @return the SOAPBodyElement that represents the root node
     *              that was added
     * @throws SOAPException if the Document cannot be added
     */
    public abstract SOAPBodyElement addDocument(Document document) throws SOAPException;
    }