1/*
2 * Copyright (c) 2004, 2015, 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
26package javax.xml.soap;
27
28import 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 */
40public class SAAJResult extends DOMResult {
41
42    /**
43     * Creates a {@code SAAJResult} 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} 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}, is drawn from the SAAJ
49     * API. When used in a transformation, the results are populated into the
50     * {@code SOAPPart} of a {@code SOAPMessage} that is created internally.
51     * The {@code SOAPPart} 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}
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} that will present results in the form
64     * of a SAAJ tree that supports the specified protocol. The
65     * {@code DYNAMIC_SOAP_PROTOCOL} is ambiguous in this context and will
66     * cause this constructor to throw an {@code UnsupportedOperationException}.
67     * <p>
68     * This kind of {@code SAAJResult} 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}, is drawn from the SAAJ
71     * API. When used in a transformation the results are populated into the
72     * {@code SOAPPart} of a {@code SOAPMessage} that is created
73     * internally. The {@code SOAPPart} 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} 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} that will write the results into the
90     * {@code SOAPPart} of the supplied {@code SOAPMessage}.
91     * In the normal case these results will be written using DOM APIs and,
92     * as a result, the finished {@code SOAPPart} 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}
95     * after the transformation can be guaranteed only by means outside SAAJ
96     * specification.
97     *
98     * @param message - the message whose {@code SOAPPart} 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} that will write the results as a
110     * child node of the {@code SOAPElement} 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} 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}
134