ohair@286: /* alanb@368: * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved. ohair@286: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. ohair@286: * ohair@286: * This code is free software; you can redistribute it and/or modify it ohair@286: * under the terms of the GNU General Public License version 2 only, as ohair@286: * published by the Free Software Foundation. Oracle designates this ohair@286: * particular file as subject to the "Classpath" exception as provided ohair@286: * by Oracle in the LICENSE file that accompanied this code. ohair@286: * ohair@286: * This code is distributed in the hope that it will be useful, but WITHOUT ohair@286: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or ohair@286: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License ohair@286: * version 2 for more details (a copy is included in the LICENSE file that ohair@286: * accompanied this code). ohair@286: * ohair@286: * You should have received a copy of the GNU General Public License version ohair@286: * 2 along with this work; if not, write to the Free Software Foundation, ohair@286: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. ohair@286: * ohair@286: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@286: * or visit www.oracle.com if you need additional information or have any ohair@286: * questions. ohair@286: */ ohair@286: ohair@286: package javax.xml.soap; ohair@286: ohair@286: import java.util.Locale; ohair@286: ohair@286: import org.w3c.dom.Document; ohair@286: ohair@286: import javax.xml.namespace.QName; ohair@286: ohair@286: /** ohair@286: * An object that represents the contents of the SOAP body ohair@286: * element in a SOAP message. A SOAP body element consists of XML data ohair@286: * that affects the way the application-specific content is processed. ohair@286: *
ohair@286: * A SOAPBody
object contains SOAPBodyElement
ohair@286: * objects, which have the content for the SOAP body.
ohair@286: * A SOAPFault
object, which carries status and/or
ohair@286: * error information, is an example of a SOAPBodyElement
object.
ohair@286: *
ohair@286: * @see SOAPFault
ohair@286: */
ohair@286: public interface SOAPBody extends SOAPElement {
ohair@286:
ohair@286: /**
ohair@286: * Creates a new SOAPFault
object and adds it to
ohair@286: * this SOAPBody
object. The new SOAPFault
will
ohair@286: * have default values set for the mandatory child elements. The type of
ohair@286: * the SOAPFault
will be a SOAP 1.1 or a SOAP 1.2 SOAPFault
ohair@286: * depending on the protocol
specified while creating the
ohair@286: * MessageFactory
instance.
ohair@286: *
ohair@286: * A SOAPBody
may contain at most one SOAPFault
ohair@286: * child element.
ohair@286: *
ohair@286: * @return the new SOAPFault
object
ohair@286: * @exception SOAPException if there is a SOAP error
ohair@286: */
ohair@286: public SOAPFault addFault() throws SOAPException;
ohair@286:
ohair@286:
ohair@286: /**
ohair@286: * Creates a new SOAPFault
object and adds it to
ohair@286: * this SOAPBody
object. The type of the
ohair@286: * SOAPFault
will be a SOAP 1.1 or a SOAP 1.2
ohair@286: * SOAPFault
depending on the protocol
ohair@286: * specified while creating the MessageFactory
instance.
ohair@286: *
ohair@286: * For SOAP 1.2 the faultCode
parameter is the value of the
ohair@286: * Fault/Code/Value element and the faultString
parameter
ohair@286: * is the value of the Fault/Reason/Text element. For SOAP 1.1
ohair@286: * the faultCode
parameter is the value of the faultcode
ohair@286: * element and the faultString
parameter is the value of the faultstring
ohair@286: * element.
ohair@286: *
ohair@286: * A SOAPBody
may contain at most one SOAPFault
ohair@286: * child element.
ohair@286: *
ohair@286: * @param faultCode a Name
object giving the fault
ohair@286: * code to be set; must be one of the fault codes defined in the Version
ohair@286: * of SOAP specification in use
ohair@286: * @param faultString a String
giving an explanation of
ohair@286: * the fault
ohair@286: * @param locale a {@link java.util.Locale} object indicating
ohair@286: * the native language of the faultString
ohair@286: * @return the new SOAPFault
object
ohair@286: * @exception SOAPException if there is a SOAP error
ohair@286: * @see SOAPFault#setFaultCode
ohair@286: * @see SOAPFault#setFaultString
ohair@286: * @since SAAJ 1.2
ohair@286: */
ohair@286: public SOAPFault addFault(Name faultCode, String faultString, Locale locale) throws SOAPException;
ohair@286:
ohair@286: /**
ohair@286: * Creates a new SOAPFault
object and adds it to this
ohair@286: * SOAPBody
object. The type of the SOAPFault
ohair@286: * will be a SOAP 1.1 or a SOAP 1.2 SOAPFault
depending on
ohair@286: * the protocol
specified while creating the MessageFactory
ohair@286: * instance.
ohair@286: *
ohair@286: * For SOAP 1.2 the faultCode
parameter is the value of the
ohair@286: * Fault/Code/Value element and the faultString
parameter
ohair@286: * is the value of the Fault/Reason/Text element. For SOAP 1.1
ohair@286: * the faultCode
parameter is the value of the faultcode
ohair@286: * element and the faultString
parameter is the value of the faultstring
ohair@286: * element.
ohair@286: *
ohair@286: * A SOAPBody
may contain at most one SOAPFault
ohair@286: * child element.
ohair@286: *
ohair@286: * @param faultCode
ohair@286: * a QName
object giving the fault code to be
ohair@286: * set; must be one of the fault codes defined in the version
ohair@286: * of SOAP specification in use.
ohair@286: * @param faultString
ohair@286: * a String
giving an explanation of the fault
ohair@286: * @param locale
ohair@286: * a {@link java.util.Locale Locale} object indicating the
ohair@286: * native language of the faultString
ohair@286: * @return the new SOAPFault
object
ohair@286: * @exception SOAPException
ohair@286: * if there is a SOAP error
ohair@286: * @see SOAPFault#setFaultCode
ohair@286: * @see SOAPFault#setFaultString
ohair@286: * @see SOAPBody#addFault(Name faultCode, String faultString, Locale locale)
ohair@286: *
ohair@286: * @since SAAJ 1.3
ohair@286: */
ohair@286: public SOAPFault addFault(QName faultCode, String faultString, Locale locale)
ohair@286: throws SOAPException;
ohair@286:
ohair@286: /**
ohair@286: * Creates a new SOAPFault
object and adds it to this
ohair@286: * SOAPBody
object. The type of the SOAPFault
ohair@286: * will be a SOAP 1.1 or a SOAP 1.2 SOAPFault
depending on
ohair@286: * the protocol
specified while creating the MessageFactory
ohair@286: * instance.
ohair@286: *
ohair@286: * For SOAP 1.2 the faultCode
parameter is the value of the
ohair@286: * Fault/Code/Value element and the faultString
parameter
ohair@286: * is the value of the Fault/Reason/Text element. For SOAP 1.1
ohair@286: * the faultCode
parameter is the value of the faultcode
ohair@286: * element and the faultString
parameter is the value of the faultstring
ohair@286: * element.
ohair@286: *
ohair@286: * In case of a SOAP 1.2 fault, the default value for the mandatory xml:lang
ohair@286: * attribute on the Fault/Reason/Text element will be set to
ohair@286: * java.util.Locale.getDefault()
ohair@286: *
ohair@286: * A SOAPBody
may contain at most one SOAPFault
ohair@286: * child element.
ohair@286: *
ohair@286: * @param faultCode
ohair@286: * a Name
object giving the fault code to be set;
ohair@286: * must be one of the fault codes defined in the version of SOAP
ohair@286: * specification in use
ohair@286: * @param faultString
ohair@286: * a String
giving an explanation of the fault
ohair@286: * @return the new SOAPFault
object
ohair@286: * @exception SOAPException
ohair@286: * if there is a SOAP error
ohair@286: * @see SOAPFault#setFaultCode
ohair@286: * @see SOAPFault#setFaultString
ohair@286: * @since SAAJ 1.2
ohair@286: */
ohair@286: public SOAPFault addFault(Name faultCode, String faultString)
ohair@286: throws SOAPException;
ohair@286:
ohair@286: /**
ohair@286: * Creates a new SOAPFault
object and adds it to this SOAPBody
ohair@286: * object. The type of the SOAPFault
ohair@286: * will be a SOAP 1.1 or a SOAP 1.2 SOAPFault
depending on
ohair@286: * the protocol
specified while creating the MessageFactory
ohair@286: * instance.
ohair@286: *
ohair@286: * For SOAP 1.2 the faultCode
parameter is the value of the
ohair@286: * Fault/Code/Value element and the faultString
parameter
ohair@286: * is the value of the Fault/Reason/Text element. For SOAP 1.1
ohair@286: * the faultCode
parameter is the value of the faultcode
ohair@286: * element and the faultString
parameter is the value of the faultstring
ohair@286: * element.
ohair@286: *
ohair@286: * In case of a SOAP 1.2 fault, the default value for the mandatory xml:lang
ohair@286: * attribute on the Fault/Reason/Text element will be set to
ohair@286: * java.util.Locale.getDefault()
ohair@286: *
ohair@286: * A SOAPBody
may contain at most one SOAPFault
ohair@286: * child element
ohair@286: *
ohair@286: * @param faultCode
ohair@286: * a QName
object giving the fault code to be
ohair@286: * set; must be one of the fault codes defined in the version
ohair@286: * of SOAP specification in use
ohair@286: * @param faultString
ohair@286: * a String
giving an explanation of the fault
ohair@286: * @return the new SOAPFault
object
ohair@286: * @exception SOAPException
ohair@286: * if there is a SOAP error
ohair@286: * @see SOAPFault#setFaultCode
ohair@286: * @see SOAPFault#setFaultString
ohair@286: * @see SOAPBody#addFault(Name faultCode, String faultString)
ohair@286: * @since SAAJ 1.3
ohair@286: */
ohair@286: public SOAPFault addFault(QName faultCode, String faultString)
ohair@286: throws SOAPException;
ohair@286:
ohair@286: /**
ohair@286: * Indicates whether a SOAPFault
object exists in this
ohair@286: * SOAPBody
object.
ohair@286: *
ohair@286: * @return true
if a SOAPFault
object exists
ohair@286: * in this SOAPBody
object; false
ohair@286: * otherwise
ohair@286: */
ohair@286: public boolean hasFault();
ohair@286:
ohair@286: /**
ohair@286: * Returns the SOAPFault
object in this SOAPBody
ohair@286: * object.
ohair@286: *
ohair@286: * @return the SOAPFault
object in this SOAPBody
ohair@286: * object if present, null otherwise.
ohair@286: */
ohair@286: public SOAPFault getFault();
ohair@286:
ohair@286: /**
ohair@286: * Creates a new SOAPBodyElement
object with the specified
ohair@286: * name and adds it to this SOAPBody
object.
ohair@286: *
ohair@286: * @param name
ohair@286: * a Name
object with the name for the new SOAPBodyElement
ohair@286: * object
ohair@286: * @return the new SOAPBodyElement
object
ohair@286: * @exception SOAPException
ohair@286: * if a SOAP error occurs
ohair@286: * @see SOAPBody#addBodyElement(javax.xml.namespace.QName)
ohair@286: */
ohair@286: public SOAPBodyElement addBodyElement(Name name) throws SOAPException;
ohair@286:
ohair@286:
ohair@286: /**
ohair@286: * Creates a new SOAPBodyElement
object with the specified
ohair@286: * QName and adds it to this SOAPBody
object.
ohair@286: *
ohair@286: * @param qname
ohair@286: * a QName
object with the qname for the new
ohair@286: * SOAPBodyElement
object
ohair@286: * @return the new SOAPBodyElement
object
ohair@286: * @exception SOAPException
ohair@286: * if a SOAP error occurs
ohair@286: * @see SOAPBody#addBodyElement(Name)
ohair@286: * @since SAAJ 1.3
ohair@286: */
ohair@286: public SOAPBodyElement addBodyElement(QName qname) throws SOAPException;
ohair@286:
ohair@286: /**
ohair@286: * Adds the root node of the DOM {@link org.w3c.dom.Document}
ohair@286: * to this SOAPBody
object.
ohair@286: *
ohair@286: * Calling this method invalidates the document
parameter.
ohair@286: * The client application should discard all references to this Document
ohair@286: * and its contents upon calling addDocument
. The behavior
ohair@286: * of an application that continues to use such references is undefined.
ohair@286: *
ohair@286: * @param document
ohair@286: * the Document
object whose root node will be
ohair@286: * added to this SOAPBody
.
ohair@286: * @return the SOAPBodyElement
that represents the root node
ohair@286: * that was added.
ohair@286: * @exception SOAPException
ohair@286: * if the Document
cannot be added
ohair@286: * @since SAAJ 1.2
ohair@286: */
ohair@286: public SOAPBodyElement addDocument(org.w3c.dom.Document document)
ohair@286: throws SOAPException;
ohair@286:
ohair@286: /**
ohair@286: * Creates a new DOM {@link org.w3c.dom.Document}
and sets
ohair@286: * the first child of this SOAPBody
as it's document
ohair@286: * element. The child SOAPElement
is removed as part of the
ohair@286: * process.
ohair@286: *
ohair@286: * @return the {@link org.w3c.dom.Document}
representation
ohair@286: * of the SOAPBody
content.
ohair@286: *
ohair@286: * @exception SOAPException
ohair@286: * if there is not exactly one child SOAPElement
of the
ohair@286: *
SOAPBody
.
ohair@286: *
ohair@286: * @since SAAJ 1.3
ohair@286: */
ohair@286: public org.w3c.dom.Document extractContentAsDocument()
ohair@286: throws SOAPException;
ohair@286: }