SOAPFactory


1   /*
2    * $Id: SOAPFactory.java,v 1.13 2005/06/22 10:24:11 vj135062 Exp $
3    * $Revision: 1.13 $
4    * $Datae$
5    */
6   
7   /*
8    * The contents of this file are subject to the terms
9    * of the Common Development and Distribution License
10   * (the License).  You may not use this file except in
11   * compliance with the License.
12   * 
13   * You can obtain a copy of the license at
14   * https://glassfish.dev.java.net/public/CDDLv1.0.html.
15   * See the License for the specific language governing
16   * permissions and limitations under the License.
17   * 
18   * When distributing Covered Code, include this CDDL
19   * Header Notice in each file and include the License file
20   * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
21   * If applicable, add the following below the CDDL Header,
22   * with the fields enclosed by brackets [] replaced by
23   * you own identifying information:
24   * "Portions Copyrighted [year] [name of copyright owner]"
25   * 
26   * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
27   */
28  
29  package javax.xml.soap;
30  
31  import javax.xml.namespace.QName  ;
32  
33  import org.w3c.dom.Element  ;
34  
35  /**
36   * <code>SOAPFactory</code> is a factory for creating various objects
37   * that exist in the SOAP XML tree.
38  
39   * <code>SOAPFactory</code> can be
40   * used to create XML fragments that will eventually end up in the
41   * SOAP part. These fragments can be inserted as children of the
42   * {@link SOAPHeaderElement} or {@link SOAPBodyElement} or
43   * {@link SOAPEnvelope} or other {@link SOAPElement} objects.
44   *
45   * <code>SOAPFactory</code> also has methods to create
46   * <code>javax.xml.soap.Detail</code> objects as well as
47   * <code>java.xml.soap.Name</code> objects.
48   *
49   */
50  public abstract class SOAPFactory {
51  
52      /**
53       * A constant representing the property used to lookup the name of
54       * a <code>SOAPFactory</code> implementation class.
55       */
56      static private final String   SOAP_FACTORY_PROPERTY =
57          "javax.xml.soap.SOAPFactory";
58  
59      /**
60       * Creates a <code>SOAPElement</code> object from an existing DOM 
61       * <code>Element</code>. If the DOM <code>Element</code> that is passed in
62       * as an argument is already a <code>SOAPElement</code> then this method 
63       * must return it unmodified without any further work. Otherwise, a new
64       * <code>SOAPElement</code> is created and a deep copy is made of the 
65       * <code>domElement</code> argument. The concrete type of the return value
66       * will depend on the name of the <code>domElement</code> argument. If any
67       * part of the tree rooted in <code>domElement</code> violates SOAP rules, a 
68       * <code>SOAPException</code> will be thrown.
69       * 
70       * @param domElement - the <code>Element</code> to be copied.
71       * 
72       * @return a new <code>SOAPElement</code> that is a copy of <code>domElement</code>.
73       * 
74       * @exception SOAPException if there is an error in creating the
75       *            <code>SOAPElement</code> object
76       * 
77       * @since SAAJ 1.3
78       */
79      public SOAPElement   createElement(Element   domElement) throws SOAPException   {
80          throw new UnsupportedOperationException  ("createElement(org.w3c.dom.Element) must be overridden by all subclasses of SOAPFactory.");
81      }
82      
83      /**
84       * Creates a <code>SOAPElement</code> object initialized with the
85       * given <code>Name</code> object. The concrete type of the return value
86       * will depend on the name given to the new <code>SOAPElement</code>. For 
87       * instance, a new <code>SOAPElement</code> with the name 
88       * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a 
89       * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.
90       *
91       * @param name a <code>Name</code> object with the XML name for
92       *             the new element
93       *
94       * @return the new <code>SOAPElement</code> object that was
95       *         created
96       *
97       * @exception SOAPException if there is an error in creating the
98       *            <code>SOAPElement</code> object
99       * @see SOAPFactory#createElement(javax.xml.namespace.QName)
100      */
101     public abstract SOAPElement   createElement(Name   name) throws SOAPException  ;
102 
103     /**
104      * Creates a <code>SOAPElement</code> object initialized with the
105      * given <code>QName</code> object. The concrete type of the return value
106      * will depend on the name given to the new <code>SOAPElement</code>. For 
107      * instance, a new <code>SOAPElement</code> with the name 
108      * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a 
109      * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.
110      *
111      * @param qname a <code>QName</code> object with the XML name for
112      *             the new element
113      *
114      * @return the new <code>SOAPElement</code> object that was
115      *         created
116      *
117      * @exception SOAPException if there is an error in creating the
118      *            <code>SOAPElement</code> object
119      * @see SOAPFactory#createElement(Name)
120      * @since SAAJ 1.3
121      */
122     public  SOAPElement   createElement(QName   qname) throws SOAPException   {
123         throw new UnsupportedOperationException  ("createElement(QName) must be overridden by all subclasses of SOAPFactory.");
124     }
125 
126     /**
127      * Creates a <code>SOAPElement</code> object initialized with the
128      * given local name. 
129      *
130      * @param localName a <code>String</code> giving the local name for
131      *             the new element
132      *
133      * @return the new <code>SOAPElement</code> object that was
134      *         created
135      *
136      * @exception SOAPException if there is an error in creating the
137      *            <code>SOAPElement</code> object
138      */
139     public abstract SOAPElement   createElement(String   localName)
140         throws SOAPException  ;
141     
142 
143     /**
144      * Creates a new <code>SOAPElement</code> object with the given
145      * local name, prefix and uri. The concrete type of the return value
146      * will depend on the name given to the new <code>SOAPElement</code>. For 
147      * instance, a new <code>SOAPElement</code> with the name 
148      * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a 
149      * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.
150      *
151      * @param localName a <code>String</code> giving the local name
152      *                  for the new element
153      * @param prefix the prefix for this <code>SOAPElement</code>
154      * @param uri a <code>String</code> giving the URI of the
155      *            namespace to which the new element belongs
156      *
157      * @exception SOAPException if there is an error in creating the
158      *            <code>SOAPElement</code> object
159      */
160     public abstract SOAPElement   createElement(
161         String   localName,
162         String   prefix,
163         String   uri)
164         throws SOAPException  ;
165 
166     /**
167      * Creates a new <code>Detail</code> object which serves as a container
168      * for <code>DetailEntry</code> objects.
169      * <P>
170      * This factory method creates <code>Detail</code> objects for use in
171      * situations where it is not practical to use the <code>SOAPFault</code>
172      * abstraction.
173      *
174      * @return a <code>Detail</code> object
175      * @throws SOAPException if there is a SOAP error 
176      * @throws UnsupportedOperationException if the protocol specified 
177      *         for the SOAPFactory was <code>DYNAMIC_SOAP_PROTOCOL</code>
178      */
179     public abstract Detail   createDetail() throws SOAPException  ;
180 
181     /**
182      *Creates a new <code>SOAPFault</code> object initialized with the given <code>reasonText</code>
183      *  and <code>faultCode</code>
184      *@param reasonText the ReasonText/FaultString for the fault
185      *@param faultCode the FaultCode for the fault
186      *@return a <code>SOAPFault</code> object
187      *@throws SOAPException if there is a SOAP error
188      *@since SAAJ 1.3
189      */
190     public abstract SOAPFault   createFault(String   reasonText, QName   faultCode) throws SOAPException  ;
191 
192     /**
193      *Creates a new default <code>SOAPFault</code> object 
194      *@return a <code>SOAPFault</code> object
195      *@throws SOAPException if there is a SOAP error
196      *@since SAAJ 1.3
197      */
198     public abstract SOAPFault   createFault() throws SOAPException  ;
199 
200     /**
201      * Creates a new <code>Name</code> object initialized with the
202      * given local name, namespace prefix, and namespace URI.
203      * <P>
204      * This factory method creates <code>Name</code> objects for use in
205      * situations where it is not practical to use the <code>SOAPEnvelope</code>
206      * abstraction.
207      *
208      * @param localName a <code>String</code> giving the local name
209      * @param prefix a <code>String</code> giving the prefix of the namespace
210      * @param uri a <code>String</code> giving the URI of the namespace
211      * @return a <code>Name</code> object initialized with the given
212      *         local name, namespace prefix, and namespace URI
213      * @throws SOAPException if there is a SOAP error
214      */
215     public abstract Name   createName(
216         String   localName,
217         String   prefix,
218         String   uri)
219         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) throws SOAPException  ;
235 
236     /**
237      * Creates a new <code>SOAPFactory</code> object that is an instance of
238      * the default implementation (SOAP 1.1),
239      *
240      * This method uses the following ordered lookup procedure to determine the SOAPFactory implementation class to load:
241      * <UL>
242      *  <LI> Use the javax.xml.soap.SOAPFactory system property.
243      *  <LI> Use the properties file "lib/jaxm.properties" in the JRE directory. This configuration file is in standard
244      * java.util.Properties format and contains the fully qualified name of the implementation class with the key being the
245      * system property defined above.
246      *  <LI> Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API
247      * will look for a classname in the file META-INF/services/javax.xml.soap.SOAPFactory in jars available to the runtime.
248      *  <LI> Use the SAAJMetaFactory instance to locate the SOAPFactory implementation class.
249      * </UL>
250      *
251      * @return a new instance of a <code>SOAPFactory</code>
252      *
253      * @exception SOAPException if there was an error creating the
254      *            default <code>SOAPFactory</code>
255      * @see SAAJMetaFactory
256      */
257     public static SOAPFactory   newInstance()
258         throws SOAPException  
259     {
260         try {
261             SOAPFactory   factory = (SOAPFactory  ) FactoryFinder.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  (
267                 "Unable to create SOAP Factory: " + 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 }
296
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags