001 /*
002 * $Id: SOAPFactory.java,v 1.12 2005/04/05 22:46:26 mk125090 Exp $
003 * $Revision: 1.12 $
004 * $Datae$
005 */
006
007 /*
008 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
009 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
010 *
011 * This code is free software; you can redistribute it and/or modify it
012 * under the terms of the GNU General Public License version 2 only, as
013 * published by the Free Software Foundation. Sun designates this
014 * particular file as subject to the "Classpath" exception as provided
015 * by Sun in the LICENSE file that accompanied this code.
016 *
017 * This code is distributed in the hope that it will be useful, but WITHOUT
018 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
019 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
020 * version 2 for more details (a copy is included in the LICENSE file that
021 * accompanied this code).
022 *
023 * You should have received a copy of the GNU General Public License version
024 * 2 along with this work; if not, write to the Free Software Foundation,
025 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
026 *
027 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
028 * CA 95054 USA or visit www.sun.com if you need additional information or
029 * have any questions.
030 */
031
032 package javax.xml.soap;
033
034 import javax.xml.namespace.QName;
035
036 import org.w3c.dom.Element;
037
038 /**
039 * <code>SOAPFactory</code> is a factory for creating various objects
040 * that exist in the SOAP XML tree.
041
042 * <code>SOAPFactory</code> can be
043 * used to create XML fragments that will eventually end up in the
044 * SOAP part. These fragments can be inserted as children of the
045 * {@link SOAPHeaderElement} or {@link SOAPBodyElement} or
046 * {@link SOAPEnvelope} or other {@link SOAPElement} objects.
047 *
048 * <code>SOAPFactory</code> also has methods to create
049 * <code>javax.xml.soap.Detail</code> objects as well as
050 * <code>java.xml.soap.Name</code> objects.
051 *
052 */
053 public abstract class SOAPFactory {
054
055 /**
056 * A constant representing the property used to lookup the name of
057 * a <code>SOAPFactory</code> implementation class.
058 */
059 static private final String SOAP_FACTORY_PROPERTY = "javax.xml.soap.SOAPFactory";
060
061 /**
062 * Creates a <code>SOAPElement</code> object from an existing DOM
063 * <code>Element</code>. If the DOM <code>Element</code> that is passed in
064 * as an argument is already a <code>SOAPElement</code> then this method
065 * must return it unmodified without any further work. Otherwise, a new
066 * <code>SOAPElement</code> is created and a deep copy is made of the
067 * <code>domElement</code> argument. The concrete type of the return value
068 * will depend on the name of the <code>domElement</code> argument. If any
069 * part of the tree rooted in <code>domElement</code> violates SOAP rules, a
070 * <code>SOAPException</code> will be thrown.
071 *
072 * @param domElement - the <code>Element</code> to be copied.
073 *
074 * @return a new <code>SOAPElement</code> that is a copy of <code>domElement</code>.
075 *
076 * @exception SOAPException if there is an error in creating the
077 * <code>SOAPElement</code> object
078 *
079 * @since SAAJ 1.3
080 */
081 public SOAPElement createElement(Element domElement)
082 throws SOAPException {
083 throw new UnsupportedOperationException(
084 "createElement(org.w3c.dom.Element) must be overridden by all subclasses of SOAPFactory.");
085 }
086
087 /**
088 * Creates a <code>SOAPElement</code> object initialized with the
089 * given <code>Name</code> object. The concrete type of the return value
090 * will depend on the name given to the new <code>SOAPElement</code>. For
091 * instance, a new <code>SOAPElement</code> with the name
092 * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
093 * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.
094 *
095 * @param name a <code>Name</code> object with the XML name for
096 * the new element
097 *
098 * @return the new <code>SOAPElement</code> object that was
099 * 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)
106 throws SOAPException;
107
108 /**
109 * Creates a <code>SOAPElement</code> object initialized with the
110 * given <code>QName</code> object. The concrete type of the return value
111 * will depend on the name given to the new <code>SOAPElement</code>. For
112 * instance, a new <code>SOAPElement</code> with the name
113 * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
114 * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.
115 *
116 * @param qname a <code>QName</code> object with the XML name for
117 * the new element
118 *
119 * @return the new <code>SOAPElement</code> object that was
120 * created
121 *
122 * @exception SOAPException if there is an error in creating the
123 * <code>SOAPElement</code> object
124 * @see SOAPFactory#createElement(Name)
125 * @since SAAJ 1.3
126 */
127 public SOAPElement createElement(QName qname) throws SOAPException {
128 throw new UnsupportedOperationException(
129 "createElement(QName) must be overridden by all subclasses of SOAPFactory.");
130 }
131
132 /**
133 * Creates a <code>SOAPElement</code> object initialized with the
134 * given local name.
135 *
136 * @param localName a <code>String</code> giving the local name for
137 * the new element
138 *
139 * @return the new <code>SOAPElement</code> object that was
140 * created
141 *
142 * @exception SOAPException if there is an error in creating the
143 * <code>SOAPElement</code> object
144 */
145 public abstract SOAPElement createElement(String localName)
146 throws SOAPException;
147
148 /**
149 * Creates a new <code>SOAPElement</code> object with the given
150 * local name, prefix and uri. The concrete type of the return value
151 * will depend on the name given to the new <code>SOAPElement</code>. For
152 * instance, a new <code>SOAPElement</code> with the name
153 * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
154 * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.
155 *
156 * @param localName a <code>String</code> giving the local name
157 * for the new element
158 * @param prefix the prefix for this <code>SOAPElement</code>
159 * @param uri a <code>String</code> giving the URI of the
160 * namespace to which the new element belongs
161 *
162 * @exception SOAPException if there is an error in creating the
163 * <code>SOAPElement</code> object
164 */
165 public abstract SOAPElement createElement(String localName,
166 String prefix, String uri) throws SOAPException;
167
168 /**
169 * Creates a new <code>Detail</code> object which serves as a container
170 * for <code>DetailEntry</code> objects.
171 * <P>
172 * This factory method creates <code>Detail</code> objects for use in
173 * situations where it is not practical to use the <code>SOAPFault</code>
174 * abstraction.
175 *
176 * @return a <code>Detail</code> object
177 * @throws SOAPException if there is a SOAP error
178 * @throws UnsupportedOperationException if the protocol specified
179 * for the SOAPFactory was <code>DYNAMIC_SOAP_PROTOCOL</code>
180 */
181 public abstract Detail createDetail() throws SOAPException;
182
183 /**
184 *Creates a new <code>SOAPFault</code> object initialized with the given <code>reasonText</code>
185 * and <code>faultCode</code>
186 *@param reasonText the ReasonText/FaultString for the fault
187 *@param faultCode the FaultCode for the fault
188 *@return a <code>SOAPFault</code> object
189 *@throws SOAPException if there is a SOAP error
190 *@since SAAJ 1.3
191 */
192 public abstract SOAPFault createFault(String reasonText,
193 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(String localName, String prefix,
219 String uri) throws SOAPException;
220
221 /**
222 * Creates a new <code>Name</code> object initialized with the
223 * given local name.
224 * <P>
225 * This factory method creates <code>Name</code> objects for use in
226 * situations where it is not practical to use the <code>SOAPEnvelope</code>
227 * abstraction.
228 *
229 * @param localName a <code>String</code> giving the local name
230 * @return a <code>Name</code> object initialized with the given
231 * local name
232 * @throws SOAPException if there is a SOAP error
233 */
234 public abstract Name createName(String localName)
235 throws SOAPException;
236
237 /**
238 * Creates a new <code>SOAPFactory</code> object that is an instance of
239 * the default implementation (SOAP 1.1),
240 *
241 * This method uses the following ordered lookup procedure to determine the SOAPFactory implementation class to load:
242 * <UL>
243 * <LI> Use the javax.xml.soap.SOAPFactory system property.
244 * <LI> Use the properties file "lib/jaxm.properties" in the JRE directory. This configuration file is in standard
245 * java.util.Properties format and contains the fully qualified name of the implementation class with the key being the
246 * system property defined above.
247 * <LI> Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API
248 * will look for a classname in the file META-INF/services/javax.xml.soap.SOAPFactory in jars available to the runtime.
249 * <LI> Use the SAAJMetaFactory instance to locate the SOAPFactory implementation class.
250 * </UL>
251 *
252 * @return a new instance of a <code>SOAPFactory</code>
253 *
254 * @exception SOAPException if there was an error creating the
255 * default <code>SOAPFactory</code>
256 * @see SAAJMetaFactory
257 */
258 public static SOAPFactory newInstance() throws SOAPException {
259 try {
260 SOAPFactory factory = (SOAPFactory) FactoryFinder
261 .find(SOAP_FACTORY_PROPERTY);
262 if (factory != null)
263 return factory;
264 return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
265 } catch (Exception ex) {
266 throw new SOAPException("Unable to create SOAP Factory: "
267 + ex.getMessage());
268 }
269
270 }
271
272 /**
273 * Creates a new <code>SOAPFactory</code> object that is an instance of
274 * the specified implementation, this method uses the SAAJMetaFactory to
275 * locate the implementation class and create the SOAPFactory instance.
276 *
277 * @return a new instance of a <code>SOAPFactory</code>
278 *
279 * @param protocol a string constant representing the protocol of the
280 * specified SOAP factory implementation. May be
281 * either <code>DYNAMIC_SOAP_PROTOCOL</code>,
282 * <code>DEFAULT_SOAP_PROTOCOL</code> (which is the same
283 * as) <code>SOAP_1_1_PROTOCOL</code>, or
284 * <code>SOAP_1_2_PROTOCOL</code>.
285 *
286 * @exception SOAPException if there was an error creating the
287 * specified <code>SOAPFactory</code>
288 * @see SAAJMetaFactory
289 * @since SAAJ 1.3
290 */
291 public static SOAPFactory newInstance(String protocol)
292 throws SOAPException {
293 return SAAJMetaFactory.getInstance().newSOAPFactory(protocol);
294 }
295 }
|