6 * published by the Free Software Foundation. Oracle designates this
7 * particular file as subject to the "Classpath" exception as provided
8 * by Oracle in the LICENSE file that accompanied this code.
9 *
10 * This code is distributed in the hope that it will be useful, but WITHOUT
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>
127 public static final String REPORTER=
128 "javax.xml.stream.reporter";
129
130 /**
131 * The property used to set/get the implementation of the XMLResolver
132 */
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
|
6 * published by the Free Software Foundation. Oracle designates this
7 * particular file as subject to the "Classpath" exception as provided
8 * by Oracle in the LICENSE file that accompanied this code.
9 *
10 * This code is distributed in the hope that it will be useful, but WITHOUT
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, 2013, 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>
127 public static final String REPORTER=
128 "javax.xml.stream.reporter";
129
130 /**
131 * The property used to set/get the implementation of the XMLResolver
132 */
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 * Creates a new instance of the factory in exactly the same manner as the
148 * {@link #newFactory()} method.
149 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
150 */
151 public static XMLInputFactory newInstance()
152 throws FactoryConfigurationError
153 {
154 return FactoryFinder.find(XMLInputFactory.class, DEFAULIMPL);
155 }
156
157 /**
158 * Create a new instance of the factory.
159 * <p>
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 * </p>
164 * <ul>
165 * <li>
166 * Use the javax.xml.stream.XMLInputFactory system property.
167 * </li>
168 * <li>
169 * Use the properties file "lib/stax.properties" in the JRE directory.
170 * This configuration file is in standard java.util.Properties format
171 * and contains the fully qualified name of the implementation class
172 * with the key being the system property defined above.
173 * </li>
174 * <li>
175 * Use the service-provider loading facilities, defined by the
176 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
177 * implementation of the service.
178 * </li>
179 * <li>
180 * Otherwise, the system-default implementation is returned.
181 * </li>
182 * </ul>
183 * <p>
184 * Once an application has obtained a reference to a XMLInputFactory it
185 * can use the factory to configure and obtain stream instances.
186 * </p>
187 * <p>
188 * Note that this is a new method that replaces the deprecated newInstance() method.
189 * No changes in behavior are defined by this replacement method relative to
190 * the deprecated method.
191 * </p>
192 * @throws FactoryConfigurationError in case of {@linkplain
193 * java.util.ServiceConfigurationError service configuration error} or if
194 * the implementation is not available or cannot be instantiated.
195 */
196 public static XMLInputFactory newFactory()
197 throws FactoryConfigurationError
198 {
199 return FactoryFinder.find(XMLInputFactory.class, DEFAULIMPL);
200 }
201
202 /**
203 * Create a new instance of the factory
204 *
205 * @param factoryId Name of the factory to find, same as
206 * a property name
207 * @param classLoader classLoader to use
208 * @return the factory implementation
209 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
210 *
211 * @deprecated This method has been deprecated to maintain API consistency.
212 * All newInstance methods have been replaced with corresponding
213 * newFactory methods. The replacement {@link
214 * #newFactory(java.lang.String, java.lang.ClassLoader)} method
215 * defines no changes in behavior.
216 */
217 public static XMLInputFactory newInstance(String factoryId,
218 ClassLoader classLoader)
219 throws FactoryConfigurationError {
220 //do not fallback if given classloader can't find the class, throw exception
221 return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);
222 }
223
224 /**
225 * Create a new instance of the factory.
226 * If the classLoader argument is null, then the ContextClassLoader is used.
227 * <p>
228 * This method uses the following ordered lookup procedure to determine
229 * the XMLInputFactory implementation class to load:
230 * </p>
231 * <ul>
232 * <li>
233 * Use the value of the system property identified by {@code factoryId}.
234 * </li>
235 * <li>
236 * Use the properties file "lib/stax.properties" in the JRE directory.
237 * This configuration file is in standard java.util.Properties format
238 * and contains the fully qualified name of the implementation class
239 * with the key being the given {@code factoryId}.
240 * </li>
241 * <li>
242 * If {@code factoryId} is "javax.xml.stream.XMLInputFactory",
243 * use the service-provider loading facilities, defined by the
244 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
245 * implementation of the service.
246 * </li>
247 * <li>
248 * Otherwise, throws a {@link FactoryConfigurationError}.
249 * </li>
250 * </ul>
251 *
252 * <p>
253 * Note that this is a new method that replaces the deprecated
254 * {@link #newInstance(java.lang.String, java.lang.ClassLoader)
255 * newInstance(String factoryId, ClassLoader classLoader)} method.
256 * No changes in behavior are defined by this replacement method relative
257 * to the deprecated method.
258 * </p>
259 *
260 * @param factoryId Name of the factory to find, same as
261 * a property name
262 * @param classLoader classLoader to use
263 * @return the factory implementation
264 * @throws FactoryConfigurationError in case of {@linkplain
265 * java.util.ServiceConfigurationError service configuration error} or if
266 * the implementation is not available or cannot be instantiated.
267 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
268 */
269 public static XMLInputFactory newFactory(String factoryId,
270 ClassLoader classLoader)
271 throws FactoryConfigurationError {
272 //do not fallback if given classloader can't find the class, throw exception
273 return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null);
274 }
275
276 /**
277 * Create a new XMLStreamReader from a reader
278 * @param reader the XML data to read from
279 * @throws XMLStreamException
280 */
281 public abstract XMLStreamReader createXMLStreamReader(java.io.Reader reader)
282 throws XMLStreamException;
283
284 /**
285 * Create a new XMLStreamReader from a JAXP source. This method is optional.
286 * @param source the source to read from
287 * @throws UnsupportedOperationException if this method is not
288 * supported by this XMLInputFactory
289 * @throws XMLStreamException
290 */
291 public abstract XMLStreamReader createXMLStreamReader(Source source)
292 throws XMLStreamException;
293
|