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 * A constant representing the property used to lookup the name of
52 * a {@code SOAPFactory} 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} 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} object from an existing DOM
65 * {@code Element}. If the DOM {@code Element} that is passed in
66 * as an argument is already a {@code SOAPElement} then this method
67 * must return it unmodified without any further work. Otherwise, a new
68 * {@code SOAPElement} is created and a deep copy is made of the
69 * {@code domElement} argument. The concrete type of the return value
70 * will depend on the name of the {@code domElement} argument. If any
71 * part of the tree rooted in {@code domElement} violates SOAP rules, a
72 * {@code SOAPException} will be thrown.
73 *
74 * @param domElement - the {@code Element} to be copied.
75 *
76 * @return a new {@code SOAPElement} that is a copy of {@code domElement}.
77 *
78 * @exception SOAPException if there is an error in creating the
79 * {@code SOAPElement} object
80 *
222 String uri)
223 throws SOAPException;
224
225 /**
226 * Creates a new {@code Name} object initialized with the
227 * given local name.
228 * <P>
229 * This factory method creates {@code Name} objects for use in
230 * situations where it is not practical to use the {@code SOAPEnvelope}
231 * abstraction.
232 *
233 * @param localName a {@code String} giving the local name
234 * @return a {@code Name} 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} 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}
256 *
257 * @exception SOAPException if there was an error creating the
258 * default {@code SOAPFactory}
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} 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}
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},
287 * {@code DEFAULT_SOAP_PROTOCOL} (which is the same
288 * as) {@code SOAP_1_1_PROTOCOL}, or
|
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 *
215 String uri)
216 throws SOAPException;
217
218 /**
219 * Creates a new {@code Name} object initialized with the
220 * given local name.
221 * <P>
222 * This factory method creates {@code Name} objects for use in
223 * situations where it is not practical to use the {@code SOAPEnvelope}
224 * abstraction.
225 *
226 * @param localName a {@code String} giving the local name
227 * @return a {@code Name} object initialized with the given
228 * local name
229 * @throws SOAPException if there is a SOAP error
230 */
231 public abstract Name createName(String localName) throws SOAPException;
232
233 /**
234 * Creates a new {@code SOAPFactory} object that is an instance of
235 * the default implementation (SOAP 1.1).
236 *
237 * This method uses the lookup procedure specified in {@link javax.xml.soap} to locate and load the
238 * {@link javax.xml.soap.SOAPFactory} class.
239 *
240 * @return a new instance of a {@code SOAPFactory}
241 *
242 * @exception SOAPException if there was an error creating the
243 * default {@code SOAPFactory}
244 * @see SAAJMetaFactory
245 */
246 public static SOAPFactory newInstance()
247 throws SOAPException
248 {
249 try {
250 SOAPFactory factory = FactoryFinder.find(
251 SOAPFactory.class,
252 DEFAULT_SOAP_FACTORY,
253 false);
254 if (factory != null) return factory;
255
256 // leave it on SAAJMetaFactory
257 return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
258 } catch (Exception ex) {
259 throw new SOAPException(
260 "Unable to create SOAP Factory: " + ex.getMessage());
261 }
262
263 }
264
265 /**
266 * Creates a new {@code SOAPFactory} object that is an instance of
267 * the specified implementation, this method uses the SAAJMetaFactory to
268 * locate the implementation class and create the SOAPFactory instance.
269 *
270 * @return a new instance of a {@code SOAPFactory}
271 *
272 * @param protocol a string constant representing the protocol of the
273 * specified SOAP factory implementation. May be
274 * either {@code DYNAMIC_SOAP_PROTOCOL},
275 * {@code DEFAULT_SOAP_PROTOCOL} (which is the same
276 * as) {@code SOAP_1_1_PROTOCOL}, or
|