jdk8-mips64-public/jaxws: src/share/jaxws_classes/javax/xml/soap/SOAPBody.java@9c07ef4934dd

     1 /*

     2  * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    26 package javax.xml.soap;

    28 import java.util.Locale;

    30 import org.w3c.dom.Document;

    32 import javax.xml.namespace.QName;

    34 /**

    35  * An object that represents the contents of the SOAP body

    36  * element in a SOAP message. A SOAP body element consists of XML data

    37  * that affects the way the application-specific content is processed.

    38  * <P>

    39  * A <code>SOAPBody</code> object contains <code>SOAPBodyElement</code>

    40  * objects, which have the content for the SOAP body.

    41  * A <code>SOAPFault</code> object, which carries status and/or

    42  * error information, is an example of a <code>SOAPBodyElement</code> object.

    43  *

    44  * @see SOAPFault

    45  */

    46 public interface SOAPBody extends SOAPElement {

    48     /**

    49      * Creates a new <code>SOAPFault</code> object and adds it to

    50      * this <code>SOAPBody</code> object. The new <code>SOAPFault</code> will

    51      * have default values set for the mandatory child elements. The type of

    52      * the <code>SOAPFault</code> will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code>

    53      * depending on the <code>protocol</code> specified while creating the

    54      * <code>MessageFactory</code> instance.

    55      * <p>

    56      * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>

    57      * child element.

    58      *

    59      * @return the new <code>SOAPFault</code> object

    60      * @exception SOAPException if there is a SOAP error

    61      */

    62     public SOAPFault addFault() throws SOAPException;

    65     /**

    66      * Creates a new <code>SOAPFault</code> object and adds it to

    67      * this <code>SOAPBody</code> object. The type of the

    68      * <code>SOAPFault</code> will be a SOAP 1.1  or a SOAP 1.2

    69      * <code>SOAPFault</code> depending on the <code>protocol</code>

    70      * specified while creating the <code>MessageFactory</code> instance.

    71      * <p>

    72      * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the

    73      * <i>Fault/Code/Value</i> element  and the <code>faultString</code> parameter

    74      * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1

    75      * the <code>faultCode</code> parameter is the value of the <code>faultcode</code>

    76      * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code>

    77      * element.

    78      * <p>

    79      * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>

    80      * child element.

    81      *

    82      * @param faultCode a <code>Name</code> object giving the fault

    83      *         code to be set; must be one of the fault codes defined in the Version

    84      *         of SOAP specification in use

    85      * @param faultString a <code>String</code> giving an explanation of

    86      *         the fault

    87      * @param locale a {@link java.util.Locale} object indicating

    88      *         the native language of the <code>faultString</code>

    89      * @return the new <code>SOAPFault</code> object

    90      * @exception SOAPException if there is a SOAP error

    91      * @see SOAPFault#setFaultCode

    92      * @see SOAPFault#setFaultString

    93      * @since SAAJ 1.2

    94      */

    95     public SOAPFault addFault(Name faultCode, String faultString, Locale locale) throws SOAPException;

    97     /**

    98      * Creates a new <code>SOAPFault</code> object and adds it to this

    99      * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code>

   100      * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on

   101      * the <code>protocol</code> specified while creating the <code>MessageFactory</code>

   102      * instance.

   103      * <p>

   104      * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the

   105      * <i>Fault/Code/Value</i> element  and the <code>faultString</code> parameter

   106      * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1

   107      * the <code>faultCode</code> parameter is the value of the <code>faultcode</code>

   108      * element and the <code>faultString</code> parameter is the value of the <code>faultstring</code>

   109      * element.

   110      * <p>

   111      * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>

   112      * child element.

   113      *

   114      * @param faultCode

   115      *            a <code>QName</code> object giving the fault code to be

   116      *            set; must be one of the fault codes defined in the version

   117      *            of SOAP specification in use.

   118      * @param faultString

   119      *            a <code>String</code> giving an explanation of the fault

   120      * @param locale

   121      *            a {@link java.util.Locale Locale} object indicating the

   122      *            native language of the <code>faultString</code>

   123      * @return the new <code>SOAPFault</code> object

   124      * @exception SOAPException

   125      *                if there is a SOAP error

   126      * @see SOAPFault#setFaultCode

   127      * @see SOAPFault#setFaultString

   128      * @see SOAPBody#addFault(Name faultCode, String faultString, Locale locale)

   129      *

   130      * @since SAAJ 1.3

   131      */

   132     public SOAPFault addFault(QName faultCode, String faultString, Locale locale)

   133         throws SOAPException;

   135     /**

   136      * Creates a new  <code>SOAPFault</code> object and adds it to this

   137      * <code>SOAPBody</code> object. The type of the <code>SOAPFault</code>

   138      * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on

   139      * the <code>protocol</code> specified while creating the <code>MessageFactory</code>

   140      * instance.

   141      * <p>

   142      * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the

   143      * <i>Fault/Code/Value</i> element  and the <code>faultString</code> parameter

   144      * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1

   145      * the <code>faultCode</code> parameter is the value of the <i>faultcode</i>

   146      * element and the <code>faultString</code> parameter is the value of the <i>faultstring</i>

   147      * element.

   148      * <p>

   149      * In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code>

   150      * attribute on the <i>Fault/Reason/Text</i> element will be set to

   151      * <code>java.util.Locale.getDefault()</code>

   152      * <p>

   153      * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>

   154      * child element.

   155      *

   156      * @param faultCode

   157      *            a <code>Name</code> object giving the fault code to be set;

   158      *            must be one of the fault codes defined in the version of SOAP

   159      *            specification in use

   160      * @param faultString

   161      *            a <code>String</code> giving an explanation of the fault

   162      * @return the new <code>SOAPFault</code> object

   163      * @exception SOAPException

   164      *                if there is a SOAP error

   165      * @see SOAPFault#setFaultCode

   166      * @see SOAPFault#setFaultString

   167      * @since SAAJ 1.2

   168      */

   169     public SOAPFault addFault(Name faultCode, String faultString)

   170         throws SOAPException;

   172     /**

   173      * Creates a new <code>SOAPFault</code> object and adds it to this <code>SOAPBody</code>

   174      * object. The type of the <code>SOAPFault</code>

   175      * will be a SOAP 1.1 or a SOAP 1.2 <code>SOAPFault</code> depending on

   176      * the <code>protocol</code> specified while creating the <code>MessageFactory</code>

   177      * instance.

   178      * <p>

   179      * For SOAP 1.2 the <code>faultCode</code> parameter is the value of the

   180      * <i>Fault/Code/Value</i> element  and the <code>faultString</code> parameter

   181      * is the value of the <i>Fault/Reason/Text</i> element. For SOAP 1.1

   182      * the <code>faultCode</code> parameter is the value of the <i>faultcode</i>

   183      * element and the <code>faultString</code> parameter is the value of the <i>faultstring</i>

   184      * element.

   185      * <p>

   186      * In case of a SOAP 1.2 fault, the default value for the mandatory <code>xml:lang</code>

   187      * attribute on the <i>Fault/Reason/Text</i> element will be set to

   188      * <code>java.util.Locale.getDefault()</code>

   189      * <p>

   190      * A <code>SOAPBody</code> may contain at most one <code>SOAPFault</code>

   191      * child element

   192      *

   193      * @param faultCode

   194      *            a <code>QName</code> object giving the fault code to be

   195      *            set; must be one of the fault codes defined in the version

   196      *            of  SOAP specification in use

   197      * @param faultString

   198      *            a <code>String</code> giving an explanation of the fault

   199      * @return the new <code>SOAPFault</code> object

   200      * @exception SOAPException

   201      *                if there is a SOAP error

   202      * @see SOAPFault#setFaultCode

   203      * @see SOAPFault#setFaultString

   204      * @see SOAPBody#addFault(Name faultCode, String faultString)

   205      * @since SAAJ 1.3

   206      */

   207     public SOAPFault addFault(QName faultCode, String faultString)

   208         throws SOAPException;

   210     /**

   211      * Indicates whether a <code>SOAPFault</code> object exists in this

   212      * <code>SOAPBody</code> object.

   213      *

   214      * @return <code>true</code> if a <code>SOAPFault</code> object exists

   215      *         in this <code>SOAPBody</code> object; <code>false</code>

   216      *         otherwise

   217      */

   218     public boolean hasFault();

   220     /**

   221      * Returns the <code>SOAPFault</code> object in this <code>SOAPBody</code>

   222      * object.

   223      *

   224      * @return the <code>SOAPFault</code> object in this <code>SOAPBody</code>

   225      *         object if present, null otherwise.

   226      */

   227     public SOAPFault getFault();

   229     /**

   230      * Creates a new <code>SOAPBodyElement</code> object with the specified

   231      * name and adds it to this <code>SOAPBody</code> object.

   232      *

   233      * @param name

   234      *            a <code>Name</code> object with the name for the new <code>SOAPBodyElement</code>

   235      *            object

   236      * @return the new <code>SOAPBodyElement</code> object

   237      * @exception SOAPException

   238      *                if a SOAP error occurs

   239      * @see SOAPBody#addBodyElement(javax.xml.namespace.QName)

   240      */

   241     public SOAPBodyElement addBodyElement(Name name) throws SOAPException;

   244     /**

   245      * Creates a new <code>SOAPBodyElement</code> object with the specified

   246      * QName and adds it to this <code>SOAPBody</code> object.

   247      *

   248      * @param qname

   249      *            a <code>QName</code> object with the qname for the new

   250      *            <code>SOAPBodyElement</code> object

   251      * @return the new <code>SOAPBodyElement</code> object

   252      * @exception SOAPException

   253      *                if a SOAP error occurs

   254      * @see SOAPBody#addBodyElement(Name)

   255      * @since SAAJ 1.3

   256      */

   257     public SOAPBodyElement addBodyElement(QName qname) throws SOAPException;

   259     /**

   260      * Adds the root node of the DOM <code>{@link org.w3c.dom.Document}</code>

   261      * to this <code>SOAPBody</code> object.

   262      * <p>

   263      * Calling this method invalidates the <code>document</code> parameter.

   264      * The client application should discard all references to this <code>Document</code>

   265      * and its contents upon calling <code>addDocument</code>. The behavior

   266      * of an application that continues to use such references is undefined.

   267      *

   268      * @param document

   269      *            the <code>Document</code> object whose root node will be

   270      *            added to this <code>SOAPBody</code>.

   271      * @return the <code>SOAPBodyElement</code> that represents the root node

   272      *         that was added.

   273      * @exception SOAPException

   274      *                if the <code>Document</code> cannot be added

   275      * @since SAAJ 1.2

   276      */

   277     public SOAPBodyElement addDocument(org.w3c.dom.Document document)

   278         throws SOAPException;

   280     /**

   281      * Creates a new DOM <code>{@link org.w3c.dom.Document}</code> and sets

   282      * the first child of this <code>SOAPBody</code> as it's document

   283      * element. The child <code>SOAPElement</code> is removed as part of the

   284      * process.

   285      *

   286      * @return the <code>{@link org.w3c.dom.Document}</code> representation

   287      *         of the <code>SOAPBody</code> content.

   288      *

   289      * @exception SOAPException

   290      *                if there is not exactly one child <code>SOAPElement</code> of the <code>

   291      *              <code>SOAPBody</code>.

   292      *

   293      * @since SAAJ 1.3

   294      */

   295     public org.w3c.dom.Document extractContentAsDocument()

   296         throws SOAPException;

   297 }

Mercurial > jdk8-mips64-public > jaxws / file revision

src/share/jaxws_classes/javax/xml/soap/SOAPBody.java@9c07ef4934dd

src/share/jaxws_classes/javax/xml/soap/SOAPBody.java