1 /*

     2  * Copyright (c) 2004, 2013, 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  */

    25 

    26 package javax.xml.soap;

    27 

    28 import javax.xml.transform.dom.DOMResult;

    29 

    30 /**

    31  * Acts as a holder for the results of a JAXP transformation or a JAXB

    32  * marshalling, in the form of a SAAJ tree. These results should be accessed

    33  * by using the {@link #getResult()} method. The {@link DOMResult#getNode()}

    34  * method should be avoided in almost all cases.

    35  *

    36  * @author XWS-Security Development Team

    37  *

    38  * @since 1.6, SAAJ 1.3

    39  */

    40 public class SAAJResult extends DOMResult {

    41 

    42     /**

    43      * Creates a <code>SAAJResult</code> that will present results in the form

    44      * of a SAAJ tree that supports the default (SOAP 1.1) protocol.

    45      * <p>

    46      * This kind of <code>SAAJResult</code> is meant for use in situations where the

    47      * results will be used as a parameter to a method that takes a parameter

    48      * whose type, such as <code>SOAPElement</code>, is drawn from the SAAJ

    49      * API. When used in a transformation, the results are populated into the

    50      * <code>SOAPPart</code> of a <code>SOAPMessage</code> that is created internally.

    51      * The <code>SOAPPart</code> returned by {@link DOMResult#getNode()}

    52      * is not guaranteed to be well-formed.

    53      *

    54      * @throws SOAPException if there is a problem creating a <code>SOAPMessage</code>

    55      *

    56      * @since 1.6, SAAJ 1.3

    57      */

    58     public SAAJResult() throws SOAPException {

    59         this(MessageFactory.newInstance().createMessage());

    60     }

    61 

    62     /**

    63      * Creates a <code>SAAJResult</code> that will present results in the form

    64      * of a SAAJ tree that supports the specified protocol. The

    65      * <code>DYNAMIC_SOAP_PROTOCOL</code> is ambiguous in this context and will

    66      * cause this constructor to throw an <code>UnsupportedOperationException</code>.

    67      * <p>

    68      * This kind of <code>SAAJResult</code> is meant for use in situations where the

    69      * results will be used as a parameter to a method that takes a parameter

    70      * whose type, such as <code>SOAPElement</code>, is drawn from the SAAJ

    71      * API. When used in a transformation the results are populated into the

    72      * <code>SOAPPart</code> of a <code>SOAPMessage</code> that is created

    73      * internally. The <code>SOAPPart</code> returned by {@link DOMResult#getNode()}

    74      * is not guaranteed to be well-formed.

    75      *

    76      * @param protocol - the name of the SOAP protocol that the resulting SAAJ

    77      *                      tree should support

    78      *

    79      * @throws SOAPException if a <code>SOAPMessage</code> supporting the

    80      *             specified protocol cannot be created

    81      *

    82      * @since 1.6, SAAJ 1.3

    83      */

    84     public SAAJResult(String protocol) throws SOAPException {

    85         this(MessageFactory.newInstance(protocol).createMessage());

    86     }

    87 

    88     /**

    89      * Creates a <code>SAAJResult</code> that will write the results into the

    90      * <code>SOAPPart</code> of the supplied <code>SOAPMessage</code>.

    91      * In the normal case these results will be written using DOM APIs and,

    92      * as a result, the finished <code>SOAPPart</code> will not be guaranteed

    93      * to be well-formed unless the data used to create it is also well formed.

    94      * When used in a transformation the validity of the <code>SOAPMessage</code>

    95      * after the transformation can be guaranteed only by means outside SAAJ

    96      * specification.

    97      *

    98      * @param message - the message whose <code>SOAPPart</code> will be

    99      *                  populated as a result of some transformation or

   100      *                  marshalling operation

   101      *

   102      * @since 1.6, SAAJ 1.3

   103      */

   104     public SAAJResult(SOAPMessage message) {

   105         super(message.getSOAPPart());

   106     }

   107 

   108     /**

   109      * Creates a <code>SAAJResult</code> that will write the results as a

   110      * child node of the <code>SOAPElement</code> specified. In the normal

   111      * case these results will be written using DOM APIs and as a result may

   112      * invalidate the structure of the SAAJ tree. This kind of

   113      * <code>SAAJResult</code> should only be used when the validity of the

   114      * incoming data can be guaranteed by means outside of the SAAJ

   115      * specification.

   116      *

   117      * @param rootNode - the root to which the results will be appended

   118      *

   119      * @since 1.6, SAAJ 1.3

   120      */

   121     public SAAJResult(SOAPElement rootNode) {

   122         super(rootNode);

   123     }

   124 

   125 

   126     /**

   127      * @return the resulting Tree that was created under the specified root Node.

   128      * @since 1.6, SAAJ 1.3

   129      */

   130     public javax.xml.soap.Node getResult() {

   131         return (javax.xml.soap.Node)super.getNode().getFirstChild();

   132      }

   133 }