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 */
47 public abstract class SOAPFactory {
48
49 /**
50 * A constant representing the property used to lookup the name of
51 * a <code>SOAPFactory</code> implementation class.
52 */
53 static private final String SOAP_FACTORY_PROPERTY =
54 "javax.xml.soap.SOAPFactory";
55
56 /**
57 * Class name of default <code>SOAPFactory</code> implementation.
58 */
59 static final String DEFAULT_SOAP_FACTORY
60 = "com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPFactory1_1Impl";
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
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;
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,
273
274 }
275
276 /**
277 * Creates a new <code>SOAPFactory</code> object that is an instance of
278 * the specified implementation, this method uses the SAAJMetaFactory to
279 * locate the implementation class and create the SOAPFactory instance.
280 *
281 * @return a new instance of a <code>SOAPFactory</code>
282 *
283 * @param protocol a string constant representing the protocol of the
284 * specified SOAP factory implementation. May be
285 * either <code>DYNAMIC_SOAP_PROTOCOL</code>,
286 * <code>DEFAULT_SOAP_PROTOCOL</code> (which is the same
287 * as) <code>SOAP_1_1_PROTOCOL</code>, or
288 * <code>SOAP_1_2_PROTOCOL</code>.
289 *
290 * @exception SOAPException if there was an error creating the
291 * specified <code>SOAPFactory</code>
292 * @see SAAJMetaFactory
293 * @since SAAJ 1.3
294 */
295 public static SOAPFactory newInstance(String protocol)
296 throws SOAPException {
297 return SAAJMetaFactory.getInstance().newSOAPFactory(protocol);
298 }
299 }
|
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
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;
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,
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 }
|