001: /*
002: * $Id: SOAPFactory.java,v 1.14 2006/03/30 00:59:41 ofung Exp $
003: * $Revision: 1.14 $
004: * $Datae$
005: */
006:
007: /*
008: * The contents of this file are subject to the terms
009: * of the Common Development and Distribution License
010: * (the License). You may not use this file except in
011: * compliance with the License.
012: *
013: * You can obtain a copy of the license at
014: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
015: * See the License for the specific language governing
016: * permissions and limitations under the License.
017: *
018: * When distributing Covered Code, include this CDDL
019: * Header Notice in each file and include the License file
020: * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
021: * If applicable, add the following below the CDDL Header,
022: * with the fields enclosed by brackets [] replaced by
023: * you own identifying information:
024: * "Portions Copyrighted [year] [name of copyright owner]"
025: *
026: * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
027: */
028:
029: package javax.xml.soap;
030:
031: import javax.xml.namespace.QName;
032:
033: import org.w3c.dom.Element;
034:
035: /**
036: * <code>SOAPFactory</code> is a factory for creating various objects
037: * that exist in the SOAP XML tree.
038:
039: * <code>SOAPFactory</code> can be
040: * used to create XML fragments that will eventually end up in the
041: * SOAP part. These fragments can be inserted as children of the
042: * {@link SOAPHeaderElement} or {@link SOAPBodyElement} or
043: * {@link SOAPEnvelope} or other {@link SOAPElement} objects.
044: *
045: * <code>SOAPFactory</code> also has methods to create
046: * <code>javax.xml.soap.Detail</code> objects as well as
047: * <code>java.xml.soap.Name</code> objects.
048: *
049: */
050: public abstract class SOAPFactory {
051:
052: /**
053: * A constant representing the property used to lookup the name of
054: * a <code>SOAPFactory</code> implementation class.
055: */
056: static private final String SOAP_FACTORY_PROPERTY = "javax.xml.soap.SOAPFactory";
057:
058: /**
059: * Creates a <code>SOAPElement</code> object from an existing DOM
060: * <code>Element</code>. If the DOM <code>Element</code> that is passed in
061: * as an argument is already a <code>SOAPElement</code> then this method
062: * must return it unmodified without any further work. Otherwise, a new
063: * <code>SOAPElement</code> is created and a deep copy is made of the
064: * <code>domElement</code> argument. The concrete type of the return value
065: * will depend on the name of the <code>domElement</code> argument. If any
066: * part of the tree rooted in <code>domElement</code> violates SOAP rules, a
067: * <code>SOAPException</code> will be thrown.
068: *
069: * @param domElement - the <code>Element</code> to be copied.
070: *
071: * @return a new <code>SOAPElement</code> that is a copy of <code>domElement</code>.
072: *
073: * @exception SOAPException if there is an error in creating the
074: * <code>SOAPElement</code> object
075: *
076: * @since SAAJ 1.3
077: */
078: public SOAPElement createElement(Element domElement)
079: throws SOAPException {
080: throw new UnsupportedOperationException(
081: "createElement(org.w3c.dom.Element) must be overridden by all subclasses of SOAPFactory.");
082: }
083:
084: /**
085: * Creates a <code>SOAPElement</code> object initialized with the
086: * given <code>Name</code> object. The concrete type of the return value
087: * will depend on the name given to the new <code>SOAPElement</code>. For
088: * instance, a new <code>SOAPElement</code> with the name
089: * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
090: * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.
091: *
092: * @param name a <code>Name</code> object with the XML name for
093: * the new element
094: *
095: * @return the new <code>SOAPElement</code> object that was
096: * created
097: *
098: * @exception SOAPException if there is an error in creating the
099: * <code>SOAPElement</code> object
100: * @see SOAPFactory#createElement(javax.xml.namespace.QName)
101: */
102: public abstract SOAPElement createElement(Name name)
103: throws SOAPException;
104:
105: /**
106: * Creates a <code>SOAPElement</code> object initialized with the
107: * given <code>QName</code> object. The concrete type of the return value
108: * will depend on the name given to the new <code>SOAPElement</code>. For
109: * instance, a new <code>SOAPElement</code> with the name
110: * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
111: * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.
112: *
113: * @param qname a <code>QName</code> object with the XML name for
114: * the new element
115: *
116: * @return the new <code>SOAPElement</code> object that was
117: * created
118: *
119: * @exception SOAPException if there is an error in creating the
120: * <code>SOAPElement</code> object
121: * @see SOAPFactory#createElement(Name)
122: * @since SAAJ 1.3
123: */
124: public SOAPElement createElement(QName qname) throws SOAPException {
125: throw new UnsupportedOperationException(
126: "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: * Creates a new <code>SOAPElement</code> object with the given
147: * local name, prefix and uri. The concrete type of the return value
148: * will depend on the name given to the new <code>SOAPElement</code>. For
149: * instance, a new <code>SOAPElement</code> with the name
150: * "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a
151: * <code>SOAPEnvelope</code> that supports SOAP 1.2 behavior to be created.
152: *
153: * @param localName a <code>String</code> giving the local name
154: * for the new element
155: * @param prefix the prefix for this <code>SOAPElement</code>
156: * @param uri a <code>String</code> giving the URI of the
157: * namespace to which the new element belongs
158: *
159: * @exception SOAPException if there is an error in creating the
160: * <code>SOAPElement</code> object
161: */
162: public abstract SOAPElement createElement(String localName,
163: String prefix, String uri) throws SOAPException;
164:
165: /**
166: * Creates a new <code>Detail</code> object which serves as a container
167: * for <code>DetailEntry</code> objects.
168: * <P>
169: * This factory method creates <code>Detail</code> objects for use in
170: * situations where it is not practical to use the <code>SOAPFault</code>
171: * abstraction.
172: *
173: * @return a <code>Detail</code> object
174: * @throws SOAPException if there is a SOAP error
175: * @throws UnsupportedOperationException if the protocol specified
176: * for the SOAPFactory was <code>DYNAMIC_SOAP_PROTOCOL</code>
177: */
178: public abstract Detail createDetail() throws SOAPException;
179:
180: /**
181: *Creates a new <code>SOAPFault</code> object initialized with the given <code>reasonText</code>
182: * and <code>faultCode</code>
183: *@param reasonText the ReasonText/FaultString for the fault
184: *@param faultCode the FaultCode for the fault
185: *@return a <code>SOAPFault</code> object
186: *@throws SOAPException if there is a SOAP error
187: *@since SAAJ 1.3
188: */
189: public abstract SOAPFault createFault(String reasonText,
190: 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(String localName, String prefix,
216: String uri) throws SOAPException;
217:
218: /**
219: * Creates a new <code>Name</code> object initialized with the
220: * given local name.
221: * <P>
222: * This factory method creates <code>Name</code> objects for use in
223: * situations where it is not practical to use the <code>SOAPEnvelope</code>
224: * abstraction.
225: *
226: * @param localName a <code>String</code> giving the local name
227: * @return a <code>Name</code> 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)
232: throws SOAPException;
233:
234: /**
235: * Creates a new <code>SOAPFactory</code> object that is an instance of
236: * the default implementation (SOAP 1.1),
237: *
238: * This method uses the following ordered lookup procedure to determine the SOAPFactory implementation class to load:
239: * <UL>
240: * <LI> Use the javax.xml.soap.SOAPFactory system property.
241: * <LI> Use the properties file "lib/jaxm.properties" in the JRE directory. This configuration file is in standard
242: * java.util.Properties format and contains the fully qualified name of the implementation class with the key being the
243: * system property defined above.
244: * <LI> Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API
245: * will look for a classname in the file META-INF/services/javax.xml.soap.SOAPFactory in jars available to the runtime.
246: * <LI> Use the SAAJMetaFactory instance to locate the SOAPFactory implementation class.
247: * </UL>
248: *
249: * @return a new instance of a <code>SOAPFactory</code>
250: *
251: * @exception SOAPException if there was an error creating the
252: * default <code>SOAPFactory</code>
253: * @see SAAJMetaFactory
254: */
255: public static SOAPFactory newInstance() throws SOAPException {
256: try {
257: SOAPFactory factory = (SOAPFactory) FactoryFinder
258: .find(SOAP_FACTORY_PROPERTY);
259: if (factory != null)
260: return factory;
261: return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
262: } catch (Exception ex) {
263: throw new SOAPException("Unable to create SOAP Factory: "
264: + ex.getMessage());
265: }
266:
267: }
268:
269: /**
270: * Creates a new <code>SOAPFactory</code> object that is an instance of
271: * the specified implementation, this method uses the SAAJMetaFactory to
272: * locate the implementation class and create the SOAPFactory instance.
273: *
274: * @return a new instance of a <code>SOAPFactory</code>
275: *
276: * @param protocol a string constant representing the protocol of the
277: * specified SOAP factory implementation. May be
278: * either <code>DYNAMIC_SOAP_PROTOCOL</code>,
279: * <code>DEFAULT_SOAP_PROTOCOL</code> (which is the same
280: * as) <code>SOAP_1_1_PROTOCOL</code>, or
281: * <code>SOAP_1_2_PROTOCOL</code>.
282: *
283: * @exception SOAPException if there was an error creating the
284: * specified <code>SOAPFactory</code>
285: * @see SAAJMetaFactory
286: * @since SAAJ 1.3
287: */
288: public static SOAPFactory newInstance(String protocol)
289: throws SOAPException {
290: return SAAJMetaFactory.getInstance().newSOAPFactory(protocol);
291: }
292: }
|