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 /**
023 * <code>SOAPFactory</code> is a factory for creating various objects that exist in the SOAP XML
024 * tree.
025 * <p/>
026 * <code>SOAPFactory</code> can be used to create XML fragments that will eventually end up in the
027 * SOAP part. These fragments can be inserted as children of the <code>SOAPHeaderElement</code> or
028 * <code>SOAPBodyElement</code> or <code>SOAPEnvelope</code>.
029 * <p/>
030 * <code>SOAPFactory</code> also has methods to create <code>javax.xml.soap.Detail</code> objects as
031 * well as <code>java.xml.soap.Name</code> objects.
032 */
033 public abstract class SOAPFactory {
034
035 public SOAPFactory() {
036 }
037
038 /**
039 * Create a <code>SOAPElement</code> object initialized with the given <code>Name</code>
040 * object.
041 *
042 * @param name a <code>Name</code> object with the XML name for the new element
043 * @return the new <code>SOAPElement</code> object that was created
044 * @throws SOAPException if there is an error in creating the <code>SOAPElement</code> object
045 */
046 public abstract SOAPElement createElement(Name name) 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) throws SOAPException;
056
057 /**
058 * Create a new <code>SOAPElement</code> object with the given local name, prefix and uri.
059 *
060 * @param localName a <code>String</code> giving the local name for the new element
061 * @param prefix the prefix for this <code>SOAPElement</code>
062 * @param uri a <code>String</code> giving the URI of the namespace to which the new
063 * element belongs
064 * @return the new <code>SOAPElement</code> object that was created
065 * @throws SOAPException if there is an error in creating the <code>SOAPElement</code> object
066 */
067 public abstract SOAPElement createElement(String localName,
068 String prefix,
069 String uri)
070 throws SOAPException;
071
072 /**
073 * Creates a new <code>Detail</code> object which serves as a container for
074 * <code>DetailEntry</code> objects.
075 * <p/>
076 * This factory method creates <code>Detail</code> objects for use in situations where it is not
077 * practical to use the <code>SOAPFault</code> abstraction.
078 *
079 * @return a <code>Detail</code> object
080 * @throws SOAPException if there is a SOAP error
081 */
082 public abstract Detail createDetail() throws SOAPException;
083
084 /**
085 * Creates a new <code>Name</code> object initialized with the given local name, namespace
086 * prefix, and namespace URI.
087 * <p/>
088 * This factory method creates <code>Name</code> objects for use in situations where it is not
089 * practical to use the <code>SOAPEnvelope</code> abstraction.
090 *
091 * @param localName a <code>String</code> giving the local name
092 * @param prefix a <code>String</code> giving the prefix of the namespace
093 * @param uri a <code>String</code> giving the URI of the namespace
094 * @return a <code>Name</code> object initialized with the given local name, namespace prefix,
095 * and namespace URI
096 * @throws SOAPException if there is a SOAP error
097 */
098 public abstract Name createName(String localName,
099 String prefix,
100 String uri)
101 throws SOAPException;
102
103 /**
104 * Creates a new <code>Name</code> object initialized with the given local name.
105 * <p/>
106 * This factory method creates <code>Name</code> objects for use in situations where it is not
107 * practical to use the <code>SOAPEnvelope</code> abstraction.
108 *
109 * @param localName a <code>String</code> giving the local name
110 * @return a <code>Name</code> object initialized with the given local name
111 * @throws SOAPException if there is a SOAP error
112 */
113 public abstract Name createName(String localName) throws SOAPException;
114
115 /**
116 * Creates a new instance of <code>SOAPFactory</code>.
117 *
118 * @return a new instance of a <code>SOAPFactory</code>
119 * @throws SOAPException if there was an error creating the default <code>SOAPFactory</code>
120 */
121 public static SOAPFactory newInstance() throws SOAPException {
122 try {
123 SOAPFactory factory = (SOAPFactory)FactoryFinder.find(SOAP_FACTORY_PROPERTY);
124 if (factory == null) {
125 factory = newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
126 }
127 return factory;
128 } catch (Exception exception) {
129 throw new SOAPException("Unable to create SOAPFactory: " + exception.getMessage());
130 }
131 }
132
133
134 /**
135 * Creates a new SOAPFactory object that is an instance of the specified implementation, this
136 * method uses the SAAJMetaFactory to locate the implementation class and create the SOAPFactory
137 * instance.
138 *
139 * @param protocol - a string constant representing the protocol of the specified SOAP factory
140 * implementation. May be either DYNAMIC_SOAP_PROTOCOL, DEFAULT_SOAP_PROTOCOL
141 * (which is the same as) SOAP_1_1_PROTOCOL, or SOAP_1_2_PROTOCOL. Returns: a
142 * new instance of a SOAPFactory
143 * @return javax.xml.soap.SOAPFactory
144 * @throws SOAPException - if there is an error creating the specified SOAPFactory
145 * @see <CODE>SAAJMetaFactory</CODE>
146 */
147 public static SOAPFactory newInstance(String protocol) throws SOAPException {
148 return SAAJMetaFactory.getInstance().newSOAPFactory(protocol);
149 }
150
151
152 /**
153 * Creates a SOAPElement object from an existing DOM Element. If the DOM Element that is passed
154 * in as an argument is already a SOAPElement then this method must return it unmodified without
155 * any further work. Otherwise, a new SOAPElement is created and a deep copy is made of the
156 * domElement argument. The concrete type of the return value will depend on the name of the
157 * domElement argument. If any part of the tree rooted in domElement violates SOAP rules, a
158 * SOAPException will be thrown.
159 *
160 * @param domElement - the Element to be copied.
161 * @return a new SOAPElement that is a copy of domElement.
162 * @throws SOAPException - if there is an error in creating the SOAPElement object
163 * @see SOAPFactoryImpl
164 * @since SAAJ 1.3
165 */
166 public SOAPElement createElement(org.w3c.dom.Element element)
167 throws SOAPException {
168 //see SOAPFactoryImpl
169 return null;
170 }
171
172
173 /**
174 * Creates a SOAPElement object initialized with the given QName object. The concrete type of
175 * the return value will depend on the name given to the new SOAPElement. For instance, a new
176 * SOAPElement with the name {http://www.w3.org/2003/05/soap-envelope}Envelope} Envelope would
177 * cause a SOAPEnvelope that supports SOAP 1.2 behavior to be created.
178 *
179 * @param qname - a QName object with the XML name for the new element
180 * @return the new SOAPElement object that was created
181 * @throws SOAPException - if there is an error in creating the SOAPElement object
182 * @see SOAPFactoryImpl
183 */
184 public SOAPElement createElement(javax.xml.namespace.QName qname)
185 throws SOAPException {
186 return null;
187 }
188
189 public abstract SOAPFault createFault()
190 throws SOAPException;
191
192 public abstract SOAPFault createFault(java.lang.String reasonText,
193 javax.xml.namespace.QName faultCode)
194 throws SOAPException;
195
196 private static final String SOAP_FACTORY_PROPERTY = "javax.xml.soap.SOAPFactory";
197
198 }