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.namespace.QName; 29 30 import org.w3c.dom.Element; 31 32 /** 33 * {@code SOAPFactory} is a factory for creating various objects 34 * that exist in the SOAP XML tree. 35 36 * {@code SOAPFactory} can be 37 * used to create XML fragments that will eventually end up in the 38 * SOAP part. These fragments can be inserted as children of the 39 * {@link SOAPHeaderElement} or {@link SOAPBodyElement} or 40 * {@link SOAPEnvelope} or other {@link SOAPElement} objects. 41 * 42 * {@code SOAPFactory} also has methods to create 43 * {@code javax.xml.soap.Detail} objects as well as 44 * {@code java.xml.soap.Name} objects. 45 * 46 * @since 1.6 47 */ 48 public abstract class SOAPFactory { 49 50 /** 51 * Class name of default {@code SOAPFactory} implementation. 52 */ 53 private static final String DEFAULT_SOAP_FACTORY 54 = "com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPFactory1_1Impl"; 55 56 /** 57 * Creates a {@code SOAPElement} object from an existing DOM 58 * {@code Element}. If the DOM {@code Element} that is passed in 59 * as an argument is already a {@code SOAPElement} then this method 60 * must return it unmodified without any further work. Otherwise, a new 61 * {@code SOAPElement} is created and a deep copy is made of the 62 * {@code domElement} argument. The concrete type of the return value 63 * will depend on the name of the {@code domElement} argument. If any 64 * part of the tree rooted in {@code domElement} violates SOAP rules, a 65 * {@code SOAPException} will be thrown. 66 * 67 * @param domElement - the {@code Element} to be copied. 68 * 69 * @return a new {@code SOAPElement} that is a copy of {@code domElement}. 70 * 71 * @exception SOAPException if there is an error in creating the 72 * {@code SOAPElement} object 73 * 74 * @since 1.6, SAAJ 1.3 75 */ 76 public SOAPElement createElement(Element domElement) throws SOAPException { 77 throw new UnsupportedOperationException("createElement(org.w3c.dom.Element) must be overridden by all subclasses of SOAPFactory."); 78 } 79 80 /** 81 * Creates a {@code SOAPElement} object initialized with the 82 * given {@code Name} object. The concrete type of the return value 83 * will depend on the name given to the new {@code SOAPElement}. For 84 * instance, a new {@code SOAPElement} with the name 85 * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a 86 * {@code SOAPEnvelope} that supports SOAP 1.2 behavior to be created. 87 * 88 * @param name a {@code Name} object with the XML name for 89 * the new element 90 * 91 * @return the new {@code SOAPElement} object that was 92 * created 93 * 94 * @exception SOAPException if there is an error in creating the 95 * {@code SOAPElement} object 96 * @see SOAPFactory#createElement(javax.xml.namespace.QName) 97 */ 98 public abstract SOAPElement createElement(Name name) throws SOAPException; 99 100 /** 101 * Creates a {@code SOAPElement} object initialized with the 102 * given {@code QName} object. The concrete type of the return value 103 * will depend on the name given to the new {@code SOAPElement}. For 104 * instance, a new {@code SOAPElement} with the name 105 * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a 106 * {@code SOAPEnvelope} that supports SOAP 1.2 behavior to be created. 107 * 108 * @param qname a {@code QName} object with the XML name for 109 * the new element 110 * 111 * @return the new {@code SOAPElement} object that was 112 * created 113 * 114 * @exception SOAPException if there is an error in creating the 115 * {@code SOAPElement} object 116 * @see SOAPFactory#createElement(Name) 117 * @since 1.6, SAAJ 1.3 118 */ 119 public SOAPElement createElement(QName qname) throws SOAPException { 120 throw new UnsupportedOperationException("createElement(QName) must be overridden by all subclasses of SOAPFactory."); 121 } 122 123 /** 124 * Creates a {@code SOAPElement} object initialized with the 125 * given local name. 126 * 127 * @param localName a {@code String} giving the local name for 128 * the new element 129 * 130 * @return the new {@code SOAPElement} object that was 131 * created 132 * 133 * @exception SOAPException if there is an error in creating the 134 * {@code SOAPElement} object 135 */ 136 public abstract SOAPElement createElement(String localName) 137 throws SOAPException; 138 139 140 /** 141 * Creates a new {@code SOAPElement} object with the given 142 * local name, prefix and uri. The concrete type of the return value 143 * will depend on the name given to the new {@code SOAPElement}. For 144 * instance, a new {@code SOAPElement} with the name 145 * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a 146 * {@code SOAPEnvelope} that supports SOAP 1.2 behavior to be created. 147 * 148 * @param localName a {@code String} giving the local name 149 * for the new element 150 * @param prefix the prefix for this {@code SOAPElement} 151 * @param uri a {@code String} giving the URI of the 152 * namespace to which the new element belongs 153 * @return the new {@code SOAPElement} object that was 154 * created 155 * 156 * @exception SOAPException if there is an error in creating the 157 * {@code SOAPElement} object 158 */ 159 public abstract SOAPElement createElement( 160 String localName, 161 String prefix, 162 String uri) 163 throws SOAPException; 164 165 /** 166 * Creates a new {@code Detail} object which serves as a container 167 * for {@code DetailEntry} objects. 168 * <P> 169 * This factory method creates {@code Detail} objects for use in 170 * situations where it is not practical to use the {@code SOAPFault} 171 * abstraction. 172 * 173 * @return a {@code Detail} object 174 * @throws SOAPException if there is a SOAP error 175 * @throws UnsupportedOperationException if the protocol specified 176 * for the SOAPFactory was {@code DYNAMIC_SOAP_PROTOCOL} 177 */ 178 public abstract Detail createDetail() throws SOAPException; 179 180 /** 181 *Creates a new {@code SOAPFault} object initialized with the given {@code reasonText} 182 * and {@code faultCode} 183 *@param reasonText the ReasonText/FaultString for the fault 184 *@param faultCode the FaultCode for the fault 185 *@return a {@code SOAPFault} object 186 *@throws SOAPException if there is a SOAP error 187 *@since 1.6, SAAJ 1.3 188 */ 189 public abstract SOAPFault createFault(String reasonText, QName faultCode) throws SOAPException; 190 191 /** 192 *Creates a new default {@code SOAPFault} object 193 *@return a {@code SOAPFault} object 194 *@throws SOAPException if there is a SOAP error 195 *@since 1.6, SAAJ 1.3 196 */ 197 public abstract SOAPFault createFault() throws SOAPException; 198 199 /** 200 * Creates a new {@code Name} object initialized with the 201 * given local name, namespace prefix, and namespace URI. 202 * <P> 203 * This factory method creates {@code Name} objects for use in 204 * situations where it is not practical to use the {@code SOAPEnvelope} 205 * abstraction. 206 * 207 * @param localName a {@code String} giving the local name 208 * @param prefix a {@code String} giving the prefix of the namespace 209 * @param uri a {@code String} giving the URI of the namespace 210 * @return a {@code Name} object initialized with the given 211 * local name, namespace prefix, and namespace URI 212 * @throws SOAPException if there is a SOAP error 213 */ 214 public abstract Name createName( 215 String localName, 216 String prefix, 217 String uri) 218 throws SOAPException; 219 220 /** 221 * Creates a new {@code Name} object initialized with the 222 * given local name. 223 * <P> 224 * This factory method creates {@code Name} objects for use in 225 * situations where it is not practical to use the {@code SOAPEnvelope} 226 * abstraction. 227 * 228 * @param localName a {@code String} giving the local name 229 * @return a {@code Name} object initialized with the given 230 * local name 231 * @throws SOAPException if there is a SOAP error 232 */ 233 public abstract Name createName(String localName) throws SOAPException; 234 235 /** 236 * Creates a new {@code SOAPFactory} object that is an instance of 237 * the default implementation (SOAP 1.1). 238 * 239 * This method uses the lookup procedure specified in {@link javax.xml.soap} to locate and load the 240 * {@link javax.xml.soap.SOAPFactory} class. 241 * 242 * @return a new instance of a {@code SOAPFactory} 243 * 244 * @exception SOAPException if there was an error creating the 245 * default {@code SOAPFactory} 246 * @see SAAJMetaFactory 247 */ 248 public static SOAPFactory newInstance() 249 throws SOAPException 250 { 251 try { 252 SOAPFactory factory = FactoryFinder.find( 253 SOAPFactory.class, 254 DEFAULT_SOAP_FACTORY, 255 false); 256 if (factory != null) return factory; 257 258 // leave it on SAAJMetaFactory 259 return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL); 260 } catch (Exception ex) { 261 throw new SOAPException( 262 "Unable to create SOAP Factory: " + ex.getMessage()); 263 } 264 265 } 266 267 /** 268 * Creates a new {@code SOAPFactory} object that is an instance of 269 * the specified implementation, this method uses the SAAJMetaFactory to 270 * locate the implementation class and create the SOAPFactory instance. 271 * 272 * @return a new instance of a {@code SOAPFactory} 273 * 274 * @param protocol a string constant representing the protocol of the 275 * specified SOAP factory implementation. May be 276 * either {@code DYNAMIC_SOAP_PROTOCOL}, 277 * {@code DEFAULT_SOAP_PROTOCOL} (which is the same 278 * as) {@code SOAP_1_1_PROTOCOL}, or 279 * {@code SOAP_1_2_PROTOCOL}. 280 * 281 * @exception SOAPException if there was an error creating the 282 * specified {@code SOAPFactory} 283 * @see SAAJMetaFactory 284 * @since 1.6, SAAJ 1.3 285 */ 286 public static SOAPFactory newInstance(String protocol) 287 throws SOAPException { 288 return SAAJMetaFactory.getInstance().newSOAPFactory(protocol); 289 } 290 }