001 package javax.xml.stream;
002
003 import javax.xml.transform.Source;
004 import javax.xml.stream.util.XMLEventAllocator;
005
006 /**
007 * Defines an abstract implementation of a factory for getting streams.
008 *
009 * The following table defines the standard properties of this specification.
010 * Each property varies in the level of support required by each implementation.
011 * The level of support required is described in the 'Required' column.
012 *
013 * <table border="2" rules="all" cellpadding="4">
014 * <thead>
015 * <tr>
016 * <th align="center" colspan="5">
017 * Configuration parameters
018 * </th>
019 * </tr>
020 * </thead>
021 * <tbody>
022 * <tr>
023 * <th>Property Name</th>
024 * <th>Behavior</th>
025 * <th>Return type</th>
026 * <th>Default Value</th>
027 * <th>Required</th>
028 * </tr>
029 * <tr><td>javax.xml.stream.isValidating</td><td>Turns on/off implementation specific DTD validation</td><td>Boolean</td><td>False</td><td>No</td></tr>
030 * <tr><td>javax.xml.stream.isNamespaceAware</td><td>Turns on/off namespace processing for XML 1.0 support</td><td>Boolean</td><td>True</td><td>True (required) / False (optional)</td></tr>
031 * <tr><td>javax.xml.stream.isCoalescing</td><td>Requires the processor to coalesce adjacent character data</td><td>Boolean</td><td>False</td><td>Yes</td></tr>
032 * <tr><td>javax.xml.stream.isReplacingEntityReferences</td><td>replace internal entity references with their replacement text and report them as characters</td><td>Boolean</td><td>True</td><td>Yes</td></tr>
033 *<tr><td>javax.xml.stream.isSupportingExternalEntities</td><td>Resolve external parsed entities</td><td>Boolean</td><td>Unspecified</td><td>Yes</td></tr>
034 *<tr><td>javax.xml.stream.supportDTD</td><td>Use this property to request processors that do not support DTDs</td><td>Boolean</td><td>True</td><td>Yes</td></tr>
035 *<tr><td>javax.xml.stream.reporter</td><td>sets/gets the impl of the XMLReporter </td><td>javax.xml.stream.XMLReporter</td><td>Null</td><td>Yes</td></tr>
036 *<tr><td>javax.xml.stream.resolver</td><td>sets/gets the impl of the XMLResolver interface</td><td>javax.xml.stream.XMLResolver</td><td>Null</td><td>Yes</td></tr>
037 *<tr><td>javax.xml.stream.allocator</td><td>sets/gets the impl of the XMLEventAllocator interface</td><td>javax.xml.stream.util.XMLEventAllocator</td><td>Null</td><td>Yes</td></tr>
038 * </tbody>
039 * </table>
040 *
041 *
042 * @version 1.0
043 * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
044 * @see XMLOutputFactory
045 * @see XMLEventReader
046 * @see XMLStreamReader
047 * @see EventFilter
048 * @see XMLReporter
049 * @see XMLResolver
050 * @see javax.xml.stream.util.XMLEventAllocator
051 * @since 1.6
052 */
053
054 public abstract class XMLInputFactory {
055 /**
056 * The property used to turn on/off namespace support,
057 * this is to support XML 1.0 documents,
058 * only the true setting must be supported
059 */
060 public static final String IS_NAMESPACE_AWARE = "javax.xml.stream.isNamespaceAware";
061
062 /**
063 * The property used to turn on/off implementation specific validation
064 */
065 public static final String IS_VALIDATING = "javax.xml.stream.isValidating";
066
067 /**
068 * The property that requires the parser to coalesce adjacent character data sections
069 */
070 public static final String IS_COALESCING = "javax.xml.stream.isCoalescing";
071
072 /**
073 * Requires the parser to replace internal
074 * entity references with their replacement
075 * text and report them as characters
076 */
077 public static final String IS_REPLACING_ENTITY_REFERENCES = "javax.xml.stream.isReplacingEntityReferences";
078
079 /**
080 * The property that requires the parser to resolve external parsed entities
081 */
082 public static final String IS_SUPPORTING_EXTERNAL_ENTITIES = "javax.xml.stream.isSupportingExternalEntities";
083
084 /**
085 * The property that requires the parser to support DTDs
086 */
087 public static final String SUPPORT_DTD = "javax.xml.stream.supportDTD";
088
089 /**
090 * The property used to
091 * set/get the implementation of the XMLReporter interface
092 */
093 public static final String REPORTER = "javax.xml.stream.reporter";
094
095 /**
096 * The property used to set/get the implementation of the XMLResolver
097 */
098 public static final String RESOLVER = "javax.xml.stream.resolver";
099
100 /**
101 * The property used to set/get the implementation of the allocator
102 */
103 public static final String ALLOCATOR = "javax.xml.stream.allocator";
104
105 protected XMLInputFactory() {
106 }
107
108 /**
109 * Create a new instance of the factory.
110 * This static method creates a new factory instance.
111 * This method uses the following ordered lookup procedure to determine
112 * the XMLInputFactory implementation class to load:
113 * Use the javax.xml.stream.XMLInputFactory system property.
114 * Use the properties file "lib/stax.properties" in the JRE directory.
115 * This configuration file is in standard java.util.Properties format and contains
116 * the fully qualified name of the implementation class with the key being the system property defined above.
117 * Use the Services API (as detailed in the JAR specification), if available, to determine the classname.
118 * The Services API will look for a classname in the file META-INF/services/javax.xml.stream.XMLInputFactory
119 * in jars available to the runtime.
120 * Platform default XMLInputFactory instance.
121 * Once an application has obtained a reference to a XMLInputFactory
122 * it can use the factory to configure and obtain stream instances.
123 *
124 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
125 */
126 public static XMLInputFactory newInstance()
127 throws FactoryConfigurationError {
128 return (XMLInputFactory) FactoryFinder.find(
129 "javax.xml.stream.XMLInputFactory",
130 "com.sun.xml.internal.stream.XMLInputFactoryImpl");
131 }
132
133 /**
134 * Create a new instance of the factory
135 *
136 * @param factoryId Name of the factory to find, same as
137 * a property name
138 * @param classLoader classLoader to use
139 * @return the factory implementation
140 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
141 */
142 public static XMLInputFactory newInstance(String factoryId,
143 ClassLoader classLoader) throws FactoryConfigurationError {
144 try {
145 //do not fallback if given classloader can't find the class, throw exception
146 return (XMLInputFactory) FactoryFinder.newInstance(
147 factoryId, classLoader, false);
148 } catch (FactoryFinder.ConfigurationError e) {
149 throw new FactoryConfigurationError(e.getException(), e
150 .getMessage());
151 }
152 }
153
154 /**
155 * Create a new XMLStreamReader from a reader
156 * @param reader the XML data to read from
157 * @throws XMLStreamException
158 */
159 public abstract XMLStreamReader createXMLStreamReader(
160 java.io.Reader reader) throws XMLStreamException;
161
162 /**
163 * Create a new XMLStreamReader from a JAXP source. This method is optional.
164 * @param source the source to read from
165 * @throws UnsupportedOperationException if this method is not
166 * supported by this XMLInputFactory
167 * @throws XMLStreamException
168 */
169 public abstract XMLStreamReader createXMLStreamReader(Source source)
170 throws XMLStreamException;
171
172 /**
173 * Create a new XMLStreamReader from a java.io.InputStream
174 * @param stream the InputStream to read from
175 * @throws XMLStreamException
176 */
177 public abstract XMLStreamReader createXMLStreamReader(
178 java.io.InputStream stream) throws XMLStreamException;
179
180 /**
181 * Create a new XMLStreamReader from a java.io.InputStream
182 * @param stream the InputStream to read from
183 * @param encoding the character encoding of the stream
184 * @throws XMLStreamException
185 */
186 public abstract XMLStreamReader createXMLStreamReader(
187 java.io.InputStream stream, String encoding)
188 throws XMLStreamException;
189
190 /**
191 * Create a new XMLStreamReader from a java.io.InputStream
192 * @param systemId the system ID of the stream
193 * @param stream the InputStream to read from
194 */
195 public abstract XMLStreamReader createXMLStreamReader(
196 String systemId, java.io.InputStream stream)
197 throws XMLStreamException;
198
199 /**
200 * Create a new XMLStreamReader from a java.io.InputStream
201 * @param systemId the system ID of the stream
202 * @param reader the InputStream to read from
203 */
204 public abstract XMLStreamReader createXMLStreamReader(
205 String systemId, java.io.Reader reader)
206 throws XMLStreamException;
207
208 /**
209 * Create a new XMLEventReader from a reader
210 * @param reader the XML data to read from
211 * @throws XMLStreamException
212 */
213 public abstract XMLEventReader createXMLEventReader(
214 java.io.Reader reader) throws XMLStreamException;
215
216 /**
217 * Create a new XMLEventReader from a reader
218 * @param systemId the system ID of the input
219 * @param reader the XML data to read from
220 * @throws XMLStreamException
221 */
222 public abstract XMLEventReader createXMLEventReader(
223 String systemId, java.io.Reader reader)
224 throws XMLStreamException;
225
226 /**
227 * Create a new XMLEventReader from an XMLStreamReader. After being used
228 * to construct the XMLEventReader instance returned from this method
229 * the XMLStreamReader must not be used.
230 * @param reader the XMLStreamReader to read from (may not be modified)
231 * @return a new XMLEventReader
232 * @throws XMLStreamException
233 */
234 public abstract XMLEventReader createXMLEventReader(
235 XMLStreamReader reader) throws XMLStreamException;
236
237 /**
238 * Create a new XMLEventReader from a JAXP source.
239 * Support of this method is optional.
240 * @param source the source to read from
241 * @throws UnsupportedOperationException if this method is not
242 * supported by this XMLInputFactory
243 */
244 public abstract XMLEventReader createXMLEventReader(Source source)
245 throws XMLStreamException;
246
247 /**
248 * Create a new XMLEventReader from a java.io.InputStream
249 * @param stream the InputStream to read from
250 * @throws XMLStreamException
251 */
252 public abstract XMLEventReader createXMLEventReader(
253 java.io.InputStream stream) throws XMLStreamException;
254
255 /**
256 * Create a new XMLEventReader from a java.io.InputStream
257 * @param stream the InputStream to read from
258 * @param encoding the character encoding of the stream
259 * @throws XMLStreamException
260 */
261 public abstract XMLEventReader createXMLEventReader(
262 java.io.InputStream stream, String encoding)
263 throws XMLStreamException;
264
265 /**
266 * Create a new XMLEventReader from a java.io.InputStream
267 * @param systemId the system ID of the stream
268 * @param stream the InputStream to read from
269 * @throws XMLStreamException
270 */
271 public abstract XMLEventReader createXMLEventReader(
272 String systemId, java.io.InputStream stream)
273 throws XMLStreamException;
274
275 /**
276 * Create a filtered reader that wraps the filter around the reader
277 * @param reader the reader to filter
278 * @param filter the filter to apply to the reader
279 * @throws XMLStreamException
280 */
281 public abstract XMLStreamReader createFilteredReader(
282 XMLStreamReader reader, StreamFilter filter)
283 throws XMLStreamException;
284
285 /**
286 * Create a filtered event reader that wraps the filter around the event reader
287 * @param reader the event reader to wrap
288 * @param filter the filter to apply to the event reader
289 * @throws XMLStreamException
290 */
291 public abstract XMLEventReader createFilteredReader(
292 XMLEventReader reader, EventFilter filter)
293 throws XMLStreamException;
294
295 /**
296 * The resolver that will be set on any XMLStreamReader or XMLEventReader created
297 * by this factory instance.
298 */
299 public abstract XMLResolver getXMLResolver();
300
301 /**
302 * The resolver that will be set on any XMLStreamReader or XMLEventReader created
303 * by this factory instance.
304 * @param resolver the resolver to use to resolve references
305 */
306 public abstract void setXMLResolver(XMLResolver resolver);
307
308 /**
309 * The reporter that will be set on any XMLStreamReader or XMLEventReader created
310 * by this factory instance.
311 */
312 public abstract XMLReporter getXMLReporter();
313
314 /**
315 * The reporter that will be set on any XMLStreamReader or XMLEventReader created
316 * by this factory instance.
317 * @param reporter the resolver to use to report non fatal errors
318 */
319 public abstract void setXMLReporter(XMLReporter reporter);
320
321 /**
322 * Allows the user to set specific feature/property on the underlying implementation. The underlying implementation
323 * is not required to support every setting of every property in the specification and may use IllegalArgumentException
324 * to signal that an unsupported property may not be set with the specified value.
325 * @param name The name of the property (may not be null)
326 * @param value The value of the property
327 * @throws java.lang.IllegalArgumentException if the property is not supported
328 */
329 public abstract void setProperty(java.lang.String name, Object value)
330 throws java.lang.IllegalArgumentException;
331
332 /**
333 * Get the value of a feature/property from the underlying implementation
334 * @param name The name of the property (may not be null)
335 * @return The value of the property
336 * @throws IllegalArgumentException if the property is not supported
337 */
338 public abstract Object getProperty(java.lang.String name)
339 throws java.lang.IllegalArgumentException;
340
341 /**
342 * Query the set of properties that this factory supports.
343 *
344 * @param name The name of the property (may not be null)
345 * @return true if the property is supported and false otherwise
346 */
347 public abstract boolean isPropertySupported(String name);
348
349 /**
350 * Set a user defined event allocator for events
351 * @param allocator the user defined allocator
352 */
353 public abstract void setEventAllocator(XMLEventAllocator allocator);
354
355 /**
356 * Gets the allocator used by streams created with this factory
357 */
358 public abstract XMLEventAllocator getEventAllocator();
359
360 }
|