1 /*
2 * $Id: SOAPFactory.java,v 1.12 2005/04/05 22:46:26 mk125090 Exp $
3 * $Revision: 1.12 $
4 * $Datae$
5 */
6
7 /*
8 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
9 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
10 *
11 * This code is free software; you can redistribute it and/or modify it
12 * under the terms of the GNU General Public License version 2 only, as
13 * published by the Free Software Foundation. Sun designates this
14 * particular file as subject to the "Classpath" exception as provided
15 * by Sun in the LICENSE file that accompanied this code.
16 *
17 * This code is distributed in the hope that it will be useful, but WITHOUT
18 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20 * version 2 for more details (a copy is included in the LICENSE file that
21 * accompanied this code).
22 *
23 * You should have received a copy of the GNU General Public License version
24 * 2 along with this work; if not, write to the Free Software Foundation,
25 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
26 *
27 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
28 * CA 95054 USA or visit www.sun.com if you need additional information or
29 * have any questions.
30 */
31
32 package javax.xml.soap;
33
34 import javax.xml.namespace.QName;
35
36 import org.w3c.dom.Element;
37
38 /**
39 * <code>SOAPFactory</code> is a factory for creating various objects
40 * that exist in the SOAP XML tree.
41
42 * <code>SOAPFactory</code> can be
43 * used to create XML fragments that will eventually end up in the
44 * SOAP part. These fragments can be inserted as children of the
45 * {@link SOAPHeaderElement} or {@link SOAPBodyElement} or
46 * {@link SOAPEnvelope} or other {@link SOAPElement} objects.
47 *
48 * <code>SOAPFactory</code> also has methods to create
49 * <code>javax.xml.soap.Detail</code> objects as well as
50 * <code>java.xml.soap.Name</code> objects.
51 *
52 */
53 public abstract class SOAPFactory {
54
55 /**
56 * A constant representing the property used to lookup the name of
57 * a <code>SOAPFactory</code> implementation class.
58 */
59 static private final String SOAP_FACTORY_PROPERTY =
60 "javax.xml.soap.SOAPFactory";
61
62 /**
63 * Creates a <code>SOAPElement</code> object from an existing DOM
64 * <code>Element</code>. If the DOM <code>Element</code> that is passed in
65 * as an argument is already a <code>SOAPElement</code> then this method
66 * must return it unmodified without any further work. Otherwise, a new
67 * <code>SOAPElement</code> is created and a deep copy is made of the
68 * <code>domElement</code> argument. The concrete type of the return value
69 * will depend on the name of the <code>domElement</code> argument. If any
70 * part of the tree rooted in <code>domElement</code> violates SOAP rules, a
71 * <code>SOAPException</code> will be thrown.
72 *
73 * @param domElement - the <code>Element</code> to be copied.
74 *
75 * @return a new <code>SOAPElement</code> that is a copy of <code>domElement</code>.
76 *
77 * @exception SOAPException if there is an error in creating the
78 * <code>SOAPElement</code> object
79 *
80 * @since SAAJ 1.3
81 */
82 public SOAPElement createElement(Element domElement) throws SOAPException {
83 throw new UnsupportedOperationException("createElement(org.w3c.dom.Element) must be overridden by all subclasses of SOAPFactory.");
84 }
85
86 /**
87 * Creates a <code>SOAPElement</code> object initialized with the
88 * given <code>Name</code> object. The concrete type of the return value
89 * will depend on the name given to the new <code>SOAPElement</code>. For
90 * instance, a new <code>SOAPElement</code> with the name
91 * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
92 * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.
93 *
94 * @param name a <code>Name</code> object with the XML name for
95 * the new element
96 *
97 * @return the new <code>SOAPElement</code> object that was
98 * created
99 *
100 * @exception SOAPException if there is an error in creating the
101 * <code>SOAPElement</code> object
102 * @see SOAPFactory#createElement(javax.xml.namespace.QName)
103 */
104 public abstract SOAPElement createElement(Name name) throws SOAPException;
105
106 /**
107 * Creates a <code>SOAPElement</code> object initialized with the
108 * given <code>QName</code> object. The concrete type of the return value
109 * will depend on the name given to the new <code>SOAPElement</code>. For
110 * instance, a new <code>SOAPElement</code> with the name
111 * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
112 * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.
113 *
114 * @param qname a <code>QName</code> object with the XML name for
115 * the new element
116 *
117 * @return the new <code>SOAPElement</code> object that was
118 * created
119 *
120 * @exception SOAPException if there is an error in creating the
121 * <code>SOAPElement</code> object
122 * @see SOAPFactory#createElement(Name)
123 * @since SAAJ 1.3
124 */
125 public SOAPElement createElement(QName qname) throws SOAPException {
126 throw new UnsupportedOperationException("createElement(QName) must be overridden by all subclasses of SOAPFactory.");
127 }
128
129 /**
130 * Creates a <code>SOAPElement</code> object initialized with the
131 * given local name.
132 *
133 * @param localName a <code>String</code> giving the local name for
134 * the new element
135 *
136 * @return the new <code>SOAPElement</code> object that was
137 * created
138 *
139 * @exception SOAPException if there is an error in creating the
140 * <code>SOAPElement</code> object
141 */
142 public abstract SOAPElement createElement(String localName)
143 throws SOAPException;
144
145
146 /**
147 * Creates a new <code>SOAPElement</code> object with the given
148 * local name, prefix and uri. The concrete type of the return value
149 * will depend on the name given to the new <code>SOAPElement</code>. For
150 * instance, a new <code>SOAPElement</code> with the name
151 * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
152 * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.
153 *
154 * @param localName a <code>String</code> giving the local name
155 * for the new element
156 * @param prefix the prefix for this <code>SOAPElement</code>
157 * @param uri a <code>String</code> giving the URI of the
158 * namespace to which the new element belongs
159 *
160 * @exception SOAPException if there is an error in creating the
161 * <code>SOAPElement</code> object
162 */
163 public abstract SOAPElement createElement(
164 String localName,
165 String prefix,
166 String uri)
167 throws SOAPException;
168
169 /**
170 * Creates a new <code>Detail</code> object which serves as a container
171 * for <code>DetailEntry</code> objects.
172 * <P>
173 * This factory method creates <code>Detail</code> objects for use in
174 * situations where it is not practical to use the <code>SOAPFault</code>
175 * abstraction.
176 *
177 * @return a <code>Detail</code> object
178 * @throws SOAPException if there is a SOAP error
179 * @throws UnsupportedOperationException if the protocol specified
180 * for the SOAPFactory was <code>DYNAMIC_SOAP_PROTOCOL</code>
181 */
182 public abstract Detail createDetail() throws SOAPException;
183
184 /**
185 *Creates a new <code>SOAPFault</code> object initialized with the given <code>reasonText</code>
186 * and <code>faultCode</code>
187 *@param reasonText the ReasonText/FaultString for the fault
188 *@param faultCode the FaultCode for the fault
189 *@return a <code>SOAPFault</code> object
190 *@throws SOAPException if there is a SOAP error
191 *@since SAAJ 1.3
192 */
193 public abstract SOAPFault createFault(String reasonText, QName faultCode) throws SOAPException;
194
195 /**
196 *Creates a new default <code>SOAPFault</code> object
197 *@return a <code>SOAPFault</code> object
198 *@throws SOAPException if there is a SOAP error
199 *@since SAAJ 1.3
200 */
201 public abstract SOAPFault createFault() throws SOAPException;
202
203 /**
204 * Creates a new <code>Name</code> object initialized with the
205 * given local name, namespace prefix, and namespace URI.
206 * <P>
207 * This factory method creates <code>Name</code> objects for use in
208 * situations where it is not practical to use the <code>SOAPEnvelope</code>
209 * abstraction.
210 *
211 * @param localName a <code>String</code> giving the local name
212 * @param prefix a <code>String</code> giving the prefix of the namespace
213 * @param uri a <code>String</code> giving the URI of the namespace
214 * @return a <code>Name</code> object initialized with the given
215 * local name, namespace prefix, and namespace URI
216 * @throws SOAPException if there is a SOAP error
217 */
218 public abstract Name createName(
219 String localName,
220 String prefix,
221 String uri)
222 throws SOAPException;
223
224 /**
225 * Creates a new <code>Name</code> object initialized with the
226 * given local name.
227 * <P>
228 * This factory method creates <code>Name</code> objects for use in
229 * situations where it is not practical to use the <code>SOAPEnvelope</code>
230 * abstraction.
231 *
232 * @param localName a <code>String</code> giving the local name
233 * @return a <code>Name</code> object initialized with the given
234 * local name
235 * @throws SOAPException if there is a SOAP error
236 */
237 public abstract Name createName(String localName) throws SOAPException;
238
239 /**
240 * Creates a new <code>SOAPFactory</code> object that is an instance of
241 * the default implementation (SOAP 1.1),
242 *
243 * This method uses the following ordered lookup procedure to determine the SOAPFactory implementation class to load:
244 * <UL>
245 * <LI> Use the javax.xml.soap.SOAPFactory system property.
246 * <LI> Use the properties file "lib/jaxm.properties" in the JRE directory. This configuration file is in standard
247 * java.util.Properties format and contains the fully qualified name of the implementation class with the key being the
248 * system property defined above.
249 * <LI> Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API
250 * will look for a classname in the file META-INF/services/javax.xml.soap.SOAPFactory in jars available to the runtime.
251 * <LI> Use the SAAJMetaFactory instance to locate the SOAPFactory implementation class.
252 * </UL>
253 *
254 * @return a new instance of a <code>SOAPFactory</code>
255 *
256 * @exception SOAPException if there was an error creating the
257 * default <code>SOAPFactory</code>
258 * @see SAAJMetaFactory
259 */
260 public static SOAPFactory newInstance()
261 throws SOAPException
262 {
263 try {
264 SOAPFactory factory = (SOAPFactory) FactoryFinder.find(SOAP_FACTORY_PROPERTY);
265 if (factory != null)
266 return factory;
267 return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
268 } catch (Exception ex) {
269 throw new SOAPException(
270 "Unable to create SOAP Factory: " + ex.getMessage());
271 }
272
273 }
274
275 /**
276 * Creates a new <code>SOAPFactory</code> object that is an instance of
277 * the specified implementation, this method uses the SAAJMetaFactory to
278 * locate the implementation class and create the SOAPFactory instance.
279 *
280 * @return a new instance of a <code>SOAPFactory</code>
281 *
282 * @param protocol a string constant representing the protocol of the
283 * specified SOAP factory implementation. May be
284 * either <code>DYNAMIC_SOAP_PROTOCOL</code>,
285 * <code>DEFAULT_SOAP_PROTOCOL</code> (which is the same
286 * as) <code>SOAP_1_1_PROTOCOL</code>, or
287 * <code>SOAP_1_2_PROTOCOL</code>.
288 *
289 * @exception SOAPException if there was an error creating the
290 * specified <code>SOAPFactory</code>
291 * @see SAAJMetaFactory
292 * @since SAAJ 1.3
293 */
294 public static SOAPFactory newInstance(String protocol)
295 throws SOAPException {
296 return SAAJMetaFactory.getInstance().newSOAPFactory(protocol);
297 }
298 }
Save This Page