/*
 * $Id: SOAPBody.java,v 1.16 2005/04/05 22:28:13 mk125090 Exp $
 * $Revision: 1.16 $
 * $Date: 2005/04/05 22:28:13 $
 */

/*
 * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */
package javax.xml.soap;

import java.util.Locale;

import org.w3c.dom.Document;

import javax.xml.namespace.QName;

/**
 * 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.
 * <P>
 * A <code>SOAPBody</code> object contains <code>SOAPBodyElement</code>
 * objects, which have the content for the SOAP body.
 * A <code>SOAPFault</code> object, which carries status and/or
 * error information, is an example of a <code>SOAPBodyElement</code> object.
 *
 * @see SOAPFault
 */
public interface SOAPBody extends SOAPElement {

    /**
     * Creates a new <code>SOAPFault</code> object and adds it to
     * this <code>SOAPBody</code> object. The new <code>SOAPFault</code> will
     * have default values set for the mandatory child elements. The type of 
     * the <code>SOAPFault</code> will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> 
     * depending on the <code>protocol</code> specified while creating the 
     * <code>MessageFactory</code> instance. 
     * <p>
     * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
     * child element.
     *
     * @return the new <code>SOAPFault</code> object
     * @exception SOAPException if there is a SOAP error
     */
    public SOAPFault addFault() throws SOAPException;


    /**
     * Creates a new <code>SOAPFault</code> object and adds it to
     * this <code>SOAPBody</code> object. The type of the 
     * <code>SOAPFault</code> will be a SOAP 1.1  or a SOAP 1.2 
     * <code>SOAPFault</code> depending on the <code>protocol</code>
     * specified while creating the <code>MessageFactory</code> instance.
     * <p>
     * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the 
     * <i>Fault/Code/Value</i> element  and the <code>faultString</code> parameter 
     * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1 
     * the <code>faultCode</code> parameter is the value of the <code>faultcode</code> 
     * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code> 
     * element. 
     * <p>
     * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
     * child element. 
     *
     * @param faultCode a <code>Name</code> object giving the fault
     *         code to be set; must be one of the fault codes defined in the Version 
     *         of SOAP specification in use
     * @param faultString a <code>String</code> giving an explanation of
     *         the fault
     * @param locale a {@link java.util.Locale} object indicating
     *         the native language of the <code>faultString</code> 
     * @return the new <code>SOAPFault</code> object
     * @exception SOAPException if there is a SOAP error
     * @see SOAPFault#setFaultCode
     * @see SOAPFault#setFaultString
     * @since SAAJ 1.2
     */
    public SOAPFault addFault(Name faultCode, String faultString, Locale locale) throws SOAPException;

    /**
     * Creates a new <code>SOAPFault</code> object and adds it to this 
     * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code> 
     * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on 
     * the <code>protocol</code> specified while creating the <code>MessageFactory</code> 
     * instance.
     * <p>
     * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the 
     * <i>Fault/Code/Value</i> element  and the <code>faultString</code> parameter 
     * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1 
     * the <code>faultCode</code> parameter is the value of the <code>faultcode</code> 
     * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code> 
     * element. 
     * <p>
     * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>
     * child element.
     * 
     * @param faultCode
     *            a <code>QName</code> object giving the fault code to be