XMLInputFactory


1   package javax.xml.stream;
2   
3   import javax.xml.transform.Source  ;
4   import javax.xml.stream.util.XMLEventAllocator;
5   
6   /**
7    * Defines an abstract implementation of a factory for getting streams.
8    * 
9    * The following table defines the standard properties of this specification.  
10   * Each property varies in the level of support required by each implementation.
11   * The level of support required is described in the 'Required' column.
12   *
13   *   <table border="2" rules="all" cellpadding="4">
14   *    <thead>
15   *      <tr>
16   *        <th align="center" colspan="5">
17   *          Configuration parameters
18   *        </th>
19   *      </tr>
20   *    </thead>
21   *    <tbody>
22   *      <tr>
23   *        <th>Property Name</th>
24   *        <th>Behavior</th>
25   *        <th>Return type</th>
26   *        <th>Default Value</th>
27   *        <th>Required</th>
28   *      </tr>
29   * <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>
30   * <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>
31   * <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>
32   * <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>
33   *<tr><td>javax.xml.stream.isSupportingExternalEntities</td><td>Resolve external parsed entities</td><td>Boolean</td><td>Unspecified</td><td>Yes</td></tr>
34   *<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>
35   *<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>
36   *<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>
37   *<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>
38   *    </tbody>
39   *  </table>
40   *
41   *
42   * @version 1.0
43   * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
44   * @see XMLOutputFactory
45   * @see XMLEventReader
46   * @see XMLStreamReader
47   * @see EventFilter
48   * @see XMLReporter
49   * @see XMLResolver
50   * @see javax.xml.stream.util.XMLEventAllocator
51   * @since 1.6
52   */
53  
54  public abstract class XMLInputFactory {
55    /** 
56     * The property used to turn on/off namespace support, 
57     * this is to support XML 1.0 documents,
58     * only the true setting must be supported
59     */
60    public static final String   IS_NAMESPACE_AWARE=
61      "javax.xml.stream.isNamespaceAware";
62  
63    /** 
64     * The property used to turn on/off implementation specific validation 
65     */
66    public static final String   IS_VALIDATING=
67      "javax.xml.stream.isValidating";
68    
69    /** 
70     * The property that requires the parser to coalesce adjacent character data sections 
71     */
72    public static final String   IS_COALESCING=
73      "javax.xml.stream.isCoalescing";
74    
75    /** 
76     * Requires the parser to replace internal 
77     * entity references with their replacement 
78     * text and report them as characters
79     */
80    public static final String   IS_REPLACING_ENTITY_REFERENCES=
81      "javax.xml.stream.isReplacingEntityReferences";
82    
83    /** 
84     *  The property that requires the parser to resolve external parsed entities
85     */
86    public static final String   IS_SUPPORTING_EXTERNAL_ENTITIES=
87      "javax.xml.stream.isSupportingExternalEntities";
88  
89    /** 
90     *  The property that requires the parser to support DTDs
91     */
92    public static final String   SUPPORT_DTD=
93      "javax.xml.stream.supportDTD";
94  
95    /**
96     * The property used to
97     * set/get the implementation of the XMLReporter interface 
98     */
99    public static final String   REPORTER=
100     "javax.xml.stream.reporter";
101 
102   /**
103    * The property used to set/get the implementation of the XMLResolver
104    */
105   public static final String   RESOLVER=
106     "javax.xml.stream.resolver";
107   
108   /**
109    * The property used to set/get the implementation of the allocator
110    */
111   public static final String   ALLOCATOR=
112     "javax.xml.stream.allocator";
113 
114   protected XMLInputFactory(){}
115 
116   /**
117    * Create a new instance of the factory.
118    * This static method creates a new factory instance. 
119    * This method uses the following ordered lookup procedure to determine 
120    * the XMLInputFactory implementation class to load: 
121    * Use the javax.xml.stream.XMLInputFactory system property. 
122    * Use the properties file "lib/stax.properties" in the JRE directory. 
123    * This configuration file is in standard java.util.Properties format and contains 
124    * the fully qualified name of the implementation class with the key being the system property defined above. 
125    * Use the Services API (as detailed in the JAR specification), if available, to determine the classname. 
126    * The Services API will look for a classname in the file META-INF/services/javax.xml.stream.XMLInputFactory 
127    * in jars available to the runtime. 
128    * Platform default XMLInputFactory instance. 
129    * Once an application has obtained a reference to a XMLInputFactory 
130    * it can use the factory to configure and obtain stream instances. 
131    *
132    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
133    */
134   public static XMLInputFactory newInstance()
135     throws FactoryConfigurationError
136   {
137     return (XMLInputFactory) FactoryFinder.find(
138       "javax.xml.stream.XMLInputFactory",
139       "com.sun.xml.internal.stream.XMLInputFactoryImpl");
140   }
141 
142   /**
143    * Create a new instance of the factory 
144    *
145    * @param factoryId             Name of the factory to find, same as
146    *                              a property name
147    * @param classLoader           classLoader to use
148    * @return the factory implementation
149    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
150    */
151   public static XMLInputFactory newInstance(String   factoryId,
152           ClassLoader   classLoader)
153           throws FactoryConfigurationError {
154       try {
155           //do not fallback if given classloader can't find the class, throw exception
156           return (XMLInputFactory) FactoryFinder.newInstance(factoryId, classLoader, false);
157       } catch (FactoryFinder.ConfigurationError e) {
158           throw new FactoryConfigurationError(e.getException(),
159                   e.getMessage());
160       }
161   }
162 
163   /**
164    * Create a new XMLStreamReader from a reader
165    * @param reader the XML data to read from
166    * @throws XMLStreamException 
167    */
168   public abstract XMLStreamReader createXMLStreamReader(java.io.Reader   reader) 
169     throws XMLStreamException;
170 
171   /**
172    * Create a new XMLStreamReader from a JAXP source.  This method is optional.
173    * @param source the source to read from
174    * @throws UnsupportedOperationException if this method is not 
175    * supported by this XMLInputFactory
176    * @throws XMLStreamException 
177    */
178   public abstract XMLStreamReader createXMLStreamReader(Source   source) 
179     throws XMLStreamException;
180 
181   /**
182    * Create a new XMLStreamReader from a java.io.InputStream
183    * @param stream the InputStream to read from
184    * @throws XMLStreamException 
185    */
186   public abstract XMLStreamReader createXMLStreamReader(java.io.InputStream   stream) 
187     throws XMLStreamException;
188 
189   /**
190    * Create a new XMLStreamReader from a java.io.InputStream
191    * @param stream the InputStream to read from
192    * @param encoding the character encoding of the stream
193    * @throws XMLStreamException 
194    */
195   public abstract XMLStreamReader createXMLStreamReader(java.io.InputStream   stream, String   encoding)
196     throws XMLStreamException;
197 
198   /**
199    * Create a new XMLStreamReader from a java.io.InputStream
200    * @param systemId the system ID of the stream
201    * @param stream the InputStream to read from
202    */
203   public abstract XMLStreamReader createXMLStreamReader(String   systemId, java.io.InputStream   stream)
204     throws XMLStreamException;
205 
206   /**
207    * Create a new XMLStreamReader from a java.io.InputStream
208    * @param systemId the system ID of the stream
209    * @param reader the InputStream to read from
210    */
211   public abstract XMLStreamReader createXMLStreamReader(String   systemId, java.io.Reader   reader)
212     throws XMLStreamException;
213 
214   /**
215    * Create a new XMLEventReader from a reader
216    * @param reader the XML data to read from
217    * @throws XMLStreamException 
218    */
219   public abstract XMLEventReader createXMLEventReader(java.io.Reader   reader) 
220     throws XMLStreamException;
221 
222   /**
223    * Create a new XMLEventReader from a reader
224    * @param systemId the system ID of the input 
225    * @param reader the XML data to read from
226    * @throws XMLStreamException 
227    */
228   public abstract XMLEventReader createXMLEventReader(String   systemId, java.io.Reader   reader)
229     throws XMLStreamException;
230 
231   /**
232    * Create a new XMLEventReader from an XMLStreamReader.  After being used
233    * to construct the XMLEventReader instance returned from this method
234    * the XMLStreamReader must not be used.  
235    * @param reader the XMLStreamReader to read from (may not be modified)
236    * @return a new XMLEventReader
237    * @throws XMLStreamException 
238    */
239   public abstract XMLEventReader createXMLEventReader(XMLStreamReader reader) 
240     throws XMLStreamException;
241 
242   /**
243    * Create a new XMLEventReader from a JAXP source.
244    * Support of this method is optional.
245    * @param source the source to read from
246    * @throws UnsupportedOperationException if this method is not 
247    * supported by this XMLInputFactory
248    */
249   public abstract XMLEventReader createXMLEventReader(Source   source) 
250     throws XMLStreamException;
251 
252   /**
253    * Create a new XMLEventReader from a java.io.InputStream
254    * @param stream the InputStream to read from
255    * @throws XMLStreamException 
256    */
257   public abstract XMLEventReader createXMLEventReader(java.io.InputStream   stream) 
258     throws XMLStreamException;
259 
260   /**
261    * Create a new XMLEventReader from a java.io.InputStream
262    * @param stream the InputStream to read from
263    * @param encoding the character encoding of the stream
264    * @throws XMLStreamException 
265    */
266   public abstract XMLEventReader createXMLEventReader(java.io.InputStream   stream, String   encoding) 
267     throws XMLStreamException;
268 
269   /**
270    * Create a new XMLEventReader from a java.io.InputStream
271    * @param systemId the system ID of the stream
272    * @param stream the InputStream to read from
273    * @throws XMLStreamException 
274    */
275   public abstract XMLEventReader createXMLEventReader(String   systemId, java.io.InputStream   stream)
276     throws XMLStreamException;
277 
278   /**
279    * Create a filtered reader that wraps the filter around the reader
280    * @param reader the reader to filter
281    * @param filter the filter to apply to the reader
282    * @throws XMLStreamException 
283    */
284   public abstract XMLStreamReader createFilteredReader(XMLStreamReader reader, StreamFilter filter) 
285     throws XMLStreamException;
286 
287   /**
288    * Create a filtered event reader that wraps the filter around the event reader
289    * @param reader the event reader to wrap
290    * @param filter the filter to apply to the event reader
291    * @throws XMLStreamException 
292    */
293   public abstract XMLEventReader createFilteredReader(XMLEventReader reader, EventFilter filter) 
294     throws XMLStreamException;
295 
296   /**
297    * The resolver that will be set on any XMLStreamReader or XMLEventReader created 
298    * by this factory instance.
299    */
300   public abstract XMLResolver getXMLResolver();
301 
302   /**
303    * The resolver that will be set on any XMLStreamReader or XMLEventReader created 
304    * by this factory instance.
305    * @param resolver the resolver to use to resolve references
306    */
307   public abstract void  setXMLResolver(XMLResolver resolver);
308 
309   /**
310    * The reporter that will be set on any XMLStreamReader or XMLEventReader created 
311    * by this factory instance.
312    */
313   public abstract XMLReporter getXMLReporter();
314 
315   /**
316    * The reporter that will be set on any XMLStreamReader or XMLEventReader created 
317    * by this factory instance.
318    * @param reporter the resolver to use to report non fatal errors
319    */
320   public abstract void setXMLReporter(XMLReporter reporter);
321 
322   /**
323    * Allows the user to set specific feature/property on the underlying implementation. The underlying implementation
324    * is not required to support every setting of every property in the specification and may use IllegalArgumentException
325    * to signal that an unsupported property may not be set with the specified value.
326    * @param name The name of the property (may not be null)
327    * @param value The value of the property
328    * @throws java.lang.IllegalArgumentException if the property is not supported
329    */
330   public abstract void setProperty(java.lang.String   name, Object   value) 
331     throws java.lang.IllegalArgumentException  ;  
332 
333   /**
334    * Get the value of a feature/property from the underlying implementation
335    * @param name The name of the property (may not be null)
336    * @return The value of the property
337    * @throws IllegalArgumentException if the property is not supported
338    */
339   public abstract Object   getProperty(java.lang.String   name) 
340     throws java.lang.IllegalArgumentException  ;  
341 
342 
343   /**
344    * Query the set of properties that this factory supports.
345    *
346    * @param name The name of the property (may not be null)
347    * @return true if the property is supported and false otherwise
348    */
349   public abstract boolean isPropertySupported(String   name);
350 
351   /**
352    * Set a user defined event allocator for events
353    * @param allocator the user defined allocator
354    */
355   public abstract void setEventAllocator(XMLEventAllocator allocator);
356 
357   /**
358    * Gets the allocator used by streams created with this factory
359    */
360   public abstract XMLEventAllocator getEventAllocator();
361 
362 }
363 
364
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags