11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * version 2 for more details (a copy is included in the LICENSE file that
14 * accompanied this code).
15 *
16 * You should have received a copy of the GNU General Public License version
17 * 2 along with this work; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19 *
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
22 * questions.
23 */
24
25 /*
26 * Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
27 */
28
29 package javax.xml.stream;
30
31 import javax.xml.transform.Source;
32 import javax.xml.stream.util.XMLEventAllocator;
33
34 /**
35 * Defines an abstract implementation of a factory for getting streams.
36 *
37 * The following table defines the standard properties of this specification.
38 * Each property varies in the level of support required by each implementation.
39 * The level of support required is described in the 'Required' column.
40 *
41 * <table border="2" rules="all" cellpadding="4">
42 * <thead>
43 * <tr>
44 * <th align="center" colspan="5">
45 * Configuration parameters
46 * </th>
47 * </tr>
48 * </thead>
49 * <tbody>
50 * <tr>
51 * <th>Property Name</th>
52 * <th>Behavior</th>
133 public static final String RESOLVER=
134 "javax.xml.stream.resolver";
135
136 /**
137 * The property used to set/get the implementation of the allocator
138 */
139 public static final String ALLOCATOR=
140 "javax.xml.stream.allocator";
141
142 static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLInputFactoryImpl";
143
144 protected XMLInputFactory(){}
145
146 /**
147 * Create a new instance of the factory.
148 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
149 */
150 public static XMLInputFactory newInstance()
151 throws FactoryConfigurationError
152 {
153 return (XMLInputFactory) FactoryFinder.find(
154 "javax.xml.stream.XMLInputFactory",
155 DEFAULIMPL);
156 }
157
158 /**
159 * Create a new instance of the factory.
160 * This static method creates a new factory instance.
161 * This method uses the following ordered lookup procedure to determine
162 * the XMLInputFactory implementation class to load:
163 * Use the javax.xml.stream.XMLInputFactory system property.
164 * Use the properties file "lib/stax.properties" in the JRE directory.
165 * This configuration file is in standard java.util.Properties format
166 * and contains the fully qualified name of the implementation class
167 * with the key being the system property defined above.
168 * Use the Services API (as detailed in the JAR specification), if available,
169 * to determine the classname. The Services API will look for a classname
170 * in the file META-INF/services/javax.xml.stream.XMLInputFactory in jars
171 * available to the runtime.
172 * Platform default XMLInputFactory instance.
173 *
174 * Once an application has obtained a reference to a XMLInputFactory it
175 * can use the factory to configure and obtain stream instances.
176 *
177 * Note that this is a new method that replaces the deprecated newInstance() method.
178 * No changes in behavior are defined by this replacement method relative to
179 * the deprecated method.
180 *
181 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
182 */
183 public static XMLInputFactory newFactory()
184 throws FactoryConfigurationError
185 {
186 return (XMLInputFactory) FactoryFinder.find(
187 "javax.xml.stream.XMLInputFactory",
188 DEFAULIMPL);
189 }
190
191 /**
192 * Create a new instance of the factory
193 *
194 * @param factoryId Name of the factory to find, same as
195 * a property name
196 * @param classLoader classLoader to use
197 * @return the factory implementation
198 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
199 *
200 * @deprecated This method has been deprecated to maintain API consistency.
201 * All newInstance methods have been replaced with corresponding
202 * newFactory methods. The replacement {@link
203 * #newFactory(java.lang.String, java.lang.ClassLoader)} method
204 * defines no changes in behavior.
205 */
206 public static XMLInputFactory newInstance(String factoryId,
207 ClassLoader classLoader)
208 throws FactoryConfigurationError {
209 try {
210 //do not fallback if given classloader can't find the class, throw exception
211 return (XMLInputFactory) FactoryFinder.find(factoryId, classLoader, null);
212 } catch (FactoryFinder.ConfigurationError e) {
213 throw new FactoryConfigurationError(e.getException(),
214 e.getMessage());
215 }
216 }
217
218 /**
219 * Create a new instance of the factory.
220 * If the classLoader argument is null, then the ContextClassLoader is used.
221 *
222 * Note that this is a new method that replaces the deprecated
223 * newInstance(String factoryId, ClassLoader classLoader) method.
224 * No changes in behavior are defined by this replacement method relative
225 * to the deprecated method.
226 *
227 * @param factoryId Name of the factory to find, same as
228 * a property name
229 * @param classLoader classLoader to use
230 * @return the factory implementation
231 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
232 */
233 public static XMLInputFactory newFactory(String factoryId,
234 ClassLoader classLoader)
235 throws FactoryConfigurationError {
236 try {
237 //do not fallback if given classloader can't find the class, throw exception
238 return (XMLInputFactory) FactoryFinder.find(factoryId, classLoader, null);
239 } catch (FactoryFinder.ConfigurationError e) {
240 throw new FactoryConfigurationError(e.getException(),
241 e.getMessage());
242 }
243 }
244
245 /**
246 * Create a new XMLStreamReader from a reader
247 * @param reader the XML data to read from
248 * @throws XMLStreamException
249 */
250 public abstract XMLStreamReader createXMLStreamReader(java.io.Reader reader)
251 throws XMLStreamException;
252
253 /**
254 * Create a new XMLStreamReader from a JAXP source. This method is optional.
255 * @param source the source to read from
256 * @throws UnsupportedOperationException if this method is not
257 * supported by this XMLInputFactory
258 * @throws XMLStreamException
259 */
260 public abstract XMLStreamReader createXMLStreamReader(Source source)
261 throws XMLStreamException;
262
|
11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * version 2 for more details (a copy is included in the LICENSE file that
14 * accompanied this code).
15 *
16 * You should have received a copy of the GNU General Public License version
17 * 2 along with this work; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19 *
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
22 * questions.
23 */
24
25 /*
26 * Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
27 */
28
29 package javax.xml.stream;
30
31 import javax.xml.stream.util.XMLEventAllocator;
32 import javax.xml.transform.Source;
33
34 /**
35 * Defines an abstract implementation of a factory for getting streams.
36 *
37 * The following table defines the standard properties of this specification.
38 * Each property varies in the level of support required by each implementation.
39 * The level of support required is described in the 'Required' column.
40 *
41 * <table border="2" rules="all" cellpadding="4">
42 * <thead>
43 * <tr>
44 * <th align="center" colspan="5">
45 * Configuration parameters
46 * </th>
47 * </tr>
48 * </thead>
49 * <tbody>
50 * <tr>
51 * <th>Property Name</th>
52 * <th>Behavior</th>
133 public static final String RESOLVER=
134 "javax.xml.stream.resolver";
135
136 /**
137 * The property used to set/get the implementation of the allocator
138 */
139 public static final String ALLOCATOR=
140 "javax.xml.stream.allocator";
141
142 static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLInputFactoryImpl";
143
144 protected XMLInputFactory(){}
145
146 /**
147 * Create a new instance of the factory.
148 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
149 */
150 public static XMLInputFactory newInstance()
151 throws FactoryConfigurationError
152 {
153 return FactoryFinder.find(XMLInputFactory.class, DEFAULIMPL);
154 }
155
156 /**
157 * Create a new instance of the factory.
158 * <p>
159 * This static method creates a new factory instance.
160 * This method uses the following ordered lookup procedure to determine
161 * the XMLInputFactory implementation class to load:
162 * </p>
163 * <ul>
164 * <li>
165 * Use the javax.xml.stream.XMLInputFactory system property.
166 * </li>
167 * <li>
168 * Use the properties file "lib/stax.properties" in the JRE directory.
169 * This configuration file is in standard java.util.Properties format
170 * and contains the fully qualified name of the implementation class
171 * with the key being the system property defined above.
172 * </li>
173 * <li>
174 * Use the service-provider loading facilities, defined by the
175 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
176 * implementation of the service.
177 * </li>
178 * <li>
179 * Otherwise, the system-default implementation is returned.
180 * </li>
181 * </ul>
182 * <p>
183 * Once an application has obtained a reference to a XMLInputFactory it
184 * can use the factory to configure and obtain stream instances.
185 * </p>
186 * <p>
187 * Note that this is a new method that replaces the deprecated newInstance() method.
188 * No changes in behavior are defined by this replacement method relative to
189 * the deprecated method.
190 * </p>
191 * @throws FactoryConfigurationError in case of {@linkplain
192 * java.util.ServiceConfigurationError service configuration error} or if
193 * the implementation is not available or cannot be instantiated.
194 */
195 public static XMLInputFactory newFactory()
196 throws FactoryConfigurationError
197 {
198 return FactoryFinder.find(XMLInputFactory.class, DEFAULIMPL);
199 }
200
201 /**
202 * Create a new instance of the factory
203 *
204 * @param factoryId Name of the factory to find, same as
205 * a property name
206 * @param classLoader classLoader to use
207 * @return the factory implementation
208 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
209 *
210 * @deprecated This method has been deprecated to maintain API consistency.
211 * All newInstance methods have been replaced with corresponding
212 * newFactory methods. The replacement {@link
213 * #newFactory(java.lang.String, java.lang.ClassLoader)} method
214 * defines no changes in behavior.
215 */
216 public static XMLInputFactory newInstance(String factoryId,
217 ClassLoader classLoader)
218 throws FactoryConfigurationError {
219 //do not fallback if given classloader can't find the class, throw exception
220 return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);
221 }
222
223 /**
224 * Create a new instance of the factory.
225 * If the classLoader argument is null, then the ContextClassLoader is used.
226 *
227 * Note that this is a new method that replaces the deprecated
228 * newInstance(String factoryId, ClassLoader classLoader) method.
229 * No changes in behavior are defined by this replacement method relative
230 * to the deprecated method.
231 *
232 * @param factoryId Name of the factory to find, same as
233 * a property name
234 * @param classLoader classLoader to use
235 * @return the factory implementation
236 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
237 */
238 public static XMLInputFactory newFactory(String factoryId,
239 ClassLoader classLoader)
240 throws FactoryConfigurationError {
241 //do not fallback if given classloader can't find the class, throw exception
242 return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);
243 }
244
245 /**
246 * Create a new XMLStreamReader from a reader
247 * @param reader the XML data to read from
248 * @throws XMLStreamException
249 */
250 public abstract XMLStreamReader createXMLStreamReader(java.io.Reader reader)
251 throws XMLStreamException;
252
253 /**
254 * Create a new XMLStreamReader from a JAXP source. This method is optional.
255 * @param source the source to read from
256 * @throws UnsupportedOperationException if this method is not
257 * supported by this XMLInputFactory
258 * @throws XMLStreamException
259 */
260 public abstract XMLStreamReader createXMLStreamReader(Source source)
261 throws XMLStreamException;
262
|