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