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