001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package javax.xml.soap;
020:
021: /**
022: * <code>SOAPFactory</code> is a factory for creating various objects that exist in the SOAP XML
023: * tree.
024: * <p/>
025: * <code>SOAPFactory</code> can be used to create XML fragments that will eventually end up in the
026: * SOAP part. These fragments can be inserted as children of the <code>SOAPHeaderElement</code> or
027: * <code>SOAPBodyElement</code> or <code>SOAPEnvelope</code>.
028: * <p/>
029: * <code>SOAPFactory</code> also has methods to create <code>javax.xml.soap.Detail</code> objects as
030: * well as <code>java.xml.soap.Name</code> objects.
031: */
032: public abstract class SOAPFactory {
033:
034: public SOAPFactory() {
035: }
036:
037: /**
038: * Create a <code>SOAPElement</code> object initialized with the given <code>Name</code>
039: * object.
040: *
041: * @param name a <code>Name</code> object with the XML name for the new element
042: * @return the new <code>SOAPElement</code> object that was created
043: * @throws SOAPException if there is an error in creating the <code>SOAPElement</code> object
044: */
045: public abstract SOAPElement createElement(Name name)
046: throws SOAPException;
047:
048: /**
049: * Create a <code>SOAPElement</code> object initialized with the given local name.
050: *
051: * @param localName a <code>String</code> giving the local name for the new element
052: * @return the new <code>SOAPElement</code> object that was created
053: * @throws SOAPException if there is an error in creating the <code>SOAPElement</code> object
054: */
055: public abstract SOAPElement createElement(String localName)
056: throws SOAPException;
057:
058: /**
059: * Create a new <code>SOAPElement</code> object with the given local name, prefix and uri.
060: *
061: * @param localName a <code>String</code> giving the local name for the new element
062: * @param prefix the prefix for this <code>SOAPElement</code>
063: * @param uri a <code>String</code> giving the URI of the namespace to which the new
064: * element belongs
065: * @return the new <code>SOAPElement</code> object that was created
066: * @throws SOAPException if there is an error in creating the <code>SOAPElement</code> object
067: */
068: public abstract SOAPElement createElement(String localName,
069: String prefix, String uri) throws SOAPException;
070:
071: /**
072: * Creates a new <code>Detail</code> object which serves as a container for
073: * <code>DetailEntry</code> objects.
074: * <p/>
075: * This factory method creates <code>Detail</code> objects for use in situations where it is not
076: * practical to use the <code>SOAPFault</code> abstraction.
077: *
078: * @return a <code>Detail</code> object
079: * @throws SOAPException if there is a SOAP error
080: */
081: public abstract Detail createDetail() throws SOAPException;
082:
083: /**
084: * Creates a new <code>Name</code> object initialized with the given local name, namespace
085: * prefix, and namespace URI.
086: * <p/>
087: * This factory method creates <code>Name</code> objects for use in situations where it is not
088: * practical to use the <code>SOAPEnvelope</code> abstraction.
089: *
090: * @param localName a <code>String</code> giving the local name
091: * @param prefix a <code>String</code> giving the prefix of the namespace
092: * @param uri a <code>String</code> giving the URI of the namespace
093: * @return a <code>Name</code> object initialized with the given local name, namespace prefix,
094: * and namespace URI
095: * @throws SOAPException if there is a SOAP error
096: */
097: public abstract Name createName(String localName, String prefix,
098: String uri) throws SOAPException;
099:
100: /**
101: * Creates a new <code>Name</code> object initialized with the given local name.
102: * <p/>
103: * This factory method creates <code>Name</code> objects for use in situations where it is not
104: * practical to use the <code>SOAPEnvelope</code> abstraction.
105: *
106: * @param localName a <code>String</code> giving the local name
107: * @return a <code>Name</code> object initialized with the given local name
108: * @throws SOAPException if there is a SOAP error
109: */
110: public abstract Name createName(String localName)
111: throws SOAPException;
112:
113: /**
114: * Creates a new instance of <code>SOAPFactory</code>.
115: *
116: * @return a new instance of a <code>SOAPFactory</code>
117: * @throws SOAPException if there was an error creating the default <code>SOAPFactory</code>
118: */
119: public static SOAPFactory newInstance() throws SOAPException {
120:
121: try {
122: return (SOAPFactory) FactoryFinder.find(SF_PROPERTY,
123: DEFAULT_SF);
124: } catch (Exception exception) {
125: throw new SOAPException("Unable to create SOAP Factory: "
126: + exception.getMessage());
127: }
128: }
129:
130: /**
131: * Creates a new SOAPFactory object that is an instance of the specified implementation, this
132: * method uses the SAAJMetaFactory to locate the implementation class and create the SOAPFactory
133: * instance.
134: *
135: * @param protocol - a string constant representing the protocol of the specified SOAP factory
136: * implementation. May be either DYNAMIC_SOAP_PROTOCOL, DEFAULT_SOAP_PROTOCOL
137: * (which is the same as) SOAP_1_1_PROTOCOL, or SOAP_1_2_PROTOCOL. Returns: a
138: * new instance of a SOAPFactory
139: * @return javax.xml.soap.SOAPFactory
140: * @throws SOAPException - if there is an error creating the specified SOAPFactory
141: * @see <CODE>SAAJMetaFactory</CODE>
142: */
143: public static SOAPFactory newInstance(String s)
144: throws SOAPException {
145: return SAAJMetaFactory.getInstance().newSOAPFactory(s);
146: }
147:
148: /**
149: * Creates a SOAPElement object from an existing DOM Element. If the DOM Element that is passed
150: * in as an argument is already a SOAPElement then this method must return it unmodified without
151: * any further work. Otherwise, a new SOAPElement is created and a deep copy is made of the
152: * domElement argument. The concrete type of the return value will depend on the name of the
153: * domElement argument. If any part of the tree rooted in domElement violates SOAP rules, a
154: * SOAPException will be thrown.
155: *
156: * @param domElement - the Element to be copied.
157: * @return a new SOAPElement that is a copy of domElement.
158: * @throws SOAPException - if there is an error in creating the SOAPElement object
159: * @see SOAPFactoryImpl
160: * @since SAAJ 1.3
161: */
162: public SOAPElement createElement(org.w3c.dom.Element element)
163: throws SOAPException {
164: //see SOAPFactoryImpl
165: return null;
166: }
167:
168: /**
169: * Creates a SOAPElement object initialized with the given QName object. The concrete type of
170: * the return value will depend on the name given to the new SOAPElement. For instance, a new
171: * SOAPElement with the name {http://www.w3.org/2003/05/soap-envelope}Envelope} Envelope would
172: * cause a SOAPEnvelope that supports SOAP 1.2 behavior to be created.
173: *
174: * @param qname - a QName object with the XML name for the new element
175: * @return the new SOAPElement object that was created
176: * @throws SOAPException - if there is an error in creating the SOAPElement object
177: * @see SOAPFactoryImpl
178: */
179: public SOAPElement createElement(javax.xml.namespace.QName qname)
180: throws SOAPException {
181: return null;
182: }
183:
184: public abstract SOAPFault createFault() throws SOAPException;
185:
186: public abstract SOAPFault createFault(java.lang.String reasonText,
187: javax.xml.namespace.QName faultCode) throws SOAPException;
188:
189: private static final String SF_PROPERTY = "javax.xml.soap.SOAPFactory";
190:
191: private static final String DEFAULT_SF = "org.apache.axis2.saaj.SOAPFactoryImpl";
192: }
|