1 /*
2 * Copyright (c) 2004, 2015, 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 *
154 * @exception SOAPException if there is an error in creating the
155 * {@code SOAPElement} object
156 */
157 public abstract SOAPElement createElement(
158 String localName,
159 String prefix,
160 String uri)
161 throws SOAPException;
162
163 /**
164 * Creates a new {@code Detail} object which serves as a container
165 * for {@code DetailEntry} objects.
166 * <P>
167 * This factory method creates {@code Detail} objects for use in
168 * situations where it is not practical to use the {@code SOAPFault}
169 * abstraction.
170 *
171 * @return a {@code Detail} object
172 * @throws SOAPException if there is a SOAP error
173 * @throws UnsupportedOperationException if the protocol specified
174 * for the SOAPFactory was {@code DYNAMIC_SOAP_PROTOCOL}
175 */
176 public abstract Detail createDetail() throws SOAPException;
177
178 /**
179 *Creates a new {@code SOAPFault} object initialized with the given {@code reasonText}
180 * and {@code faultCode}
181 *@param reasonText the ReasonText/FaultString for the fault
182 *@param faultCode the FaultCode for the fault
183 *@return a {@code SOAPFault} object
184 *@throws SOAPException if there is a SOAP error
185 *@since 1.6, SAAJ 1.3
186 */
187 public abstract SOAPFault createFault(String reasonText, QName faultCode) throws SOAPException;
188
189 /**
190 *Creates a new default {@code SOAPFault} object
191 *@return a {@code SOAPFault} object
192 *@throws SOAPException if there is a SOAP error
193 *@since 1.6, SAAJ 1.3
194 */
195 public abstract SOAPFault createFault() throws SOAPException;
196
197 /**
198 * Creates a new {@code Name} object initialized with the
199 * given local name, namespace prefix, and namespace URI.
200 * <P>
201 * This factory method creates {@code Name} objects for use in
202 * situations where it is not practical to use the {@code SOAPEnvelope}
203 * abstraction.
204 *
205 * @param localName a {@code String} giving the local name
206 * @param prefix a {@code String} giving the prefix of the namespace
207 * @param uri a {@code String} giving the URI of the namespace
208 * @return a {@code Name} object initialized with the given
209 * local name, namespace prefix, and namespace URI
210 * @throws SOAPException if there is a SOAP error
211 */
212 public abstract Name createName(
213 String localName,
214 String prefix,
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
277 * {@code SOAP_1_2_PROTOCOL}.
278 *
279 * @exception SOAPException if there was an error creating the
280 * specified {@code SOAPFactory}
281 * @see SAAJMetaFactory
282 * @since 1.6, SAAJ 1.3
283 */
284 public static SOAPFactory newInstance(String protocol)
285 throws SOAPException {
286 return SAAJMetaFactory.getInstance().newSOAPFactory(protocol);
287 }
288 }