9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.parsers;
27
28 import javax.xml.validation.Schema;
29
30 import org.xml.sax.SAXException;
31 import org.xml.sax.SAXNotRecognizedException;
32 import org.xml.sax.SAXNotSupportedException;
33
34 /**
35 * Defines a factory API that enables applications to configure and
36 * obtain a SAX based parser to parse XML documents.
37 *
38 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
39 * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
40 *
41 * @version $Revision: 1.9 $, $Date: 2010/05/25 16:19:44 $
42 *
43 */
44 public abstract class SAXParserFactory {
45 /** The default property name according to the JAXP spec */
46 private static final String DEFAULT_PROPERTY_NAME = "javax.xml.parsers.SAXParserFactory";
47
48 /**
49 * <p>Should Parsers be validating?</p>
50 */
51 private boolean validating = false;
52
53 /**
54 * <p>Should Parsers be namespace aware?</p>
55 */
56 private boolean namespaceAware = false;
57
58 /**
59 * <p>Protected constructor to force use of {@link #newInstance()}.</p>
60 */
61 protected SAXParserFactory () {
62
63 }
64
65 /**
66 * Obtain a new instance of a <code>SAXParserFactory</code>. This
67 * static method creates a new factory instance
68 * This method uses the following ordered lookup procedure to determine
69 * the <code>SAXParserFactory</code> implementation class to
70 * load:
71 * <ul>
72 * <li>
73 * Use the <code>javax.xml.parsers.SAXParserFactory</code> system
74 * property.
75 * </li>
76 * <li>
77 * Use the properties file "lib/jaxp.properties" in the JRE directory.
78 * This configuration file is in standard <code>java.util.Properties
79 * </code> format and contains the fully qualified name of the
80 * implementation class with the key being the system property defined
81 * above.
82 *
83 * The jaxp.properties file is read only once by the JAXP implementation
84 * and it's values are then cached for future use. If the file does not exist
85 * when the first attempt is made to read from it, no further attempts are
86 * made to check for its existence. It is not possible to change the value
87 * of any property in jaxp.properties after it has been read for the first time.
88 * </li>
89 * <li>
90 * Use the Services API (as detailed in the JAR specification), if
91 * available, to determine the classname. The Services API will look
92 * for a classname in the file
93 * <code>META-INF/services/javax.xml.parsers.SAXParserFactory</code>
94 * in jars available to the runtime.
95 * </li>
96 * <li>
97 * Platform default <code>SAXParserFactory</code> instance.
98 * </li>
99 * </ul>
100 *
101 * Once an application has obtained a reference to a
102 * <code>SAXParserFactory</code> it can use the factory to
103 * configure and obtain parser instances.
104 *
105 *
106 *
107 * <h2>Tip for Trouble-shooting</h2>
108 * <p>Setting the <code>jaxp.debug</code> system property will cause
109 * this method to print a lot of debug messages
110 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
111 *
112 * <p> If you have problems loading {@link DocumentBuilder}s, try:</p>
113 * <pre>
114 * java -Djaxp.debug=1 YourProgram ....
115 * </pre>
116 *
117 *
118 * @return A new instance of a SAXParserFactory.
119 *
120 * @throws FactoryConfigurationError if the implementation is
121 * not available or cannot be instantiated.
122 */
123
124 public static SAXParserFactory newInstance() {
125 try {
126 return (SAXParserFactory) FactoryFinder.find(
127 /* The default property name according to the JAXP spec */
128 "javax.xml.parsers.SAXParserFactory",
129 /* The fallback implementation class name */
130 "com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl");
131 } catch (FactoryFinder.ConfigurationError e) {
132 throw new FactoryConfigurationError(e.getException(),
133 e.getMessage());
134 }
135 }
136
137 /**
138 * <p>Obtain a new instance of a <code>SAXParserFactory</code> from class name.
139 * This function is useful when there are multiple providers in the classpath.
140 * It gives more control to the application as it can specify which provider
141 * should be loaded.</p>
142 *
143 * <p>Once an application has obtained a reference to a <code>SAXParserFactory</code>
144 * it can use the factory to configure and obtain parser instances.</p>
145 *
146 *
147 * <h2>Tip for Trouble-shooting</h2>
148 * <p>Setting the <code>jaxp.debug</code> system property will cause
149 * this method to print a lot of debug messages
150 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
151 *
152 * <p> If you have problems, try:</p>
153 * <pre>
154 * java -Djaxp.debug=1 YourProgram ....
155 * </pre>
156 *
157 * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.parsers.SAXParserFactory</code>.
158 *
159 * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
160 * current <code>Thread</code>'s context classLoader is used to load the factory class.
161 *
162 * @return New instance of a <code>SAXParserFactory</code>
163 *
164 * @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or
165 * the factory class cannot be loaded, instantiated.
166 *
167 * @see #newInstance()
168 *
169 * @since 1.6
170 */
171 public static SAXParserFactory newInstance(String factoryClassName, ClassLoader classLoader){
172 try {
173 //do not fallback if given classloader can't find the class, throw exception
174 return (SAXParserFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);
175 } catch (FactoryFinder.ConfigurationError e) {
176 throw new FactoryConfigurationError(e.getException(),
177 e.getMessage());
178 }
179 }
180
181 /**
182 * <p>Creates a new instance of a SAXParser using the currently
183 * configured factory parameters.</p>
184 *
185 * @return A new instance of a SAXParser.
186 *
187 * @throws ParserConfigurationException if a parser cannot
188 * be created which satisfies the requested configuration.
189 * @throws SAXException for SAX errors.
190 */
191
192 public abstract SAXParser newSAXParser()
193 throws ParserConfigurationException, SAXException;
194
195
196 /**
197 * Specifies that the parser produced by this code will
198 * provide support for XML namespaces. By default the value of this is set
303 /**
304 *
305 * <p>Returns the particular property requested for in the underlying
306 * implementation of org.xml.sax.XMLReader.</p>
307 *
308 * @param name The name of the property to be retrieved.
309 *
310 * @return Value of the requested property.
311 *
312 * @throws ParserConfigurationException if a parser cannot be created which satisfies the requested configuration.
313 * @throws SAXNotRecognizedException When the underlying XMLReader does not recognize the property name.
314 * @throws SAXNotSupportedException When the underlying XMLReader recognizes the property name but doesn't support the property.
315 *
316 * @see org.xml.sax.XMLReader#getProperty
317 */
318 public abstract boolean getFeature(String name)
319 throws ParserConfigurationException, SAXNotRecognizedException,
320 SAXNotSupportedException;
321
322
323
324 /* <p>Get current state of canonicalization.</p>
325 *
326 * @return current state canonicalization control
327 */
328 /*
329 public boolean getCanonicalization() {
330 return canonicalState;
331 }
332 */
333
334 /**
335 * Gets the {@link Schema} object specified through
336 * the {@link #setSchema(Schema schema)} method.
337 *
338 *
339 * @throws UnsupportedOperationException When implementation does not
340 * override this method
341 *
342 * @return
343 * the {@link Schema} object that was last set through
344 * the {@link #setSchema(Schema)} method, or null
345 * if the method was not invoked since a {@link SAXParserFactory}
346 * is created.
347 *
348 * @since 1.5
349 */
350 public Schema getSchema() {
351 throw new UnsupportedOperationException(
352 "This parser does not support specification \""
353 + this.getClass().getPackage().getSpecificationTitle()
354 + "\" version \""
355 + this.getClass().getPackage().getSpecificationVersion()
356 + "\""
357 );
358 }
359
360 /** <p>Set canonicalization control to <code>true</code> or
361 * </code>false</code>.</p>
362 *
363 * @param state of canonicalization
364 */
365 /*
366 public void setCanonicalization(boolean state) {
367 canonicalState = state;
368 }
369 */
370
371 /**
372 * <p>Set the {@link Schema} to be used by parsers created
373 * from this factory.</p>
374 *
375 * <p>When a {@link Schema} is non-null, a parser will use a validator
376 * created from it to validate documents before it passes information
377 * down to the application.</p>
378 *
379 * <p>When warnings/errors/fatal errors are found by the validator, the parser must
380 * handle them as if those errors were found by the parser itself.
381 * In other words, if the user-specified {@link org.xml.sax.ErrorHandler}
382 * is set, it must receive those errors, and if not, they must be
383 * treated according to the implementation specific
384 * default error handling rules.
385 *
386 * <p>A validator may modify the SAX event stream (for example by
387 * adding default values that were missing in documents), and a parser
388 * is responsible to make sure that the application will receive
389 * those modified event stream.</p>
390 *
|
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.parsers;
27
28 import javax.xml.validation.Schema;
29 import org.xml.sax.SAXException;
30 import org.xml.sax.SAXNotRecognizedException;
31 import org.xml.sax.SAXNotSupportedException;
32
33 /**
34 * Defines a factory API that enables applications to configure and
35 * obtain a SAX based parser to parse XML documents.
36 *
37 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
38 * @author <a href="mailto:Neeraj.Bajaj@sun.com">Neeraj Bajaj</a>
39 *
40 * @version $Revision: 1.9 $, $Date: 2010/05/25 16:19:44 $
41 *
42 */
43 public abstract class SAXParserFactory {
44
45 /**
46 * <p>Should Parsers be validating?</p>
47 */
48 private boolean validating = false;
49
50 /**
51 * <p>Should Parsers be namespace aware?</p>
52 */
53 private boolean namespaceAware = false;
54
55 /**
56 * <p>Protected constructor to force use of {@link #newInstance()}.</p>
57 */
58 protected SAXParserFactory () {
59
60 }
61
62 /**
63 * Obtain a new instance of a <code>SAXParserFactory</code>. This
64 * static method creates a new factory instance
65 * This method uses the following ordered lookup procedure to determine
66 * the <code>SAXParserFactory</code> implementation class to
67 * load:
68 * <p></p>
69 * <ul>
70 * <li>
71 * Use the <code>javax.xml.parsers.SAXParserFactory</code> system
72 * property.
73 * </li>
74 * <li>
75 * Use the properties file "lib/jaxp.properties" in the JRE directory.
76 * This configuration file is in standard <code>java.util.Properties
77 * </code> format and contains the fully qualified name of the
78 * implementation class with the key being the system property defined
79 * above.
80 *
81 * The jaxp.properties file is read only once by the JAXP implementation
82 * and it's values are then cached for future use. If the file does not exist
83 * when the first attempt is made to read from it, no further attempts are
84 * made to check for its existence. It is not possible to change the value
85 * of any property in jaxp.properties after it has been read for the first time.
86 * </li>
87 * <li>
88 * Uses the service-provider loading facilities, defined by the
89 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
90 * implementation of the service. If there are providers other than the
91 * implementation system default located, then the first provider that is
92 * not the default is instantiated and returned.
93 * </li>
94 * <li>
95 * Otherwise the system default implementation is returned.
96 * </li>
97 * </ul>
98 *
99 * Once an application has obtained a reference to a
100 * <code>SAXParserFactory</code> it can use the factory to
101 * configure and obtain parser instances.
102 *
103 *
104 *
105 * <h2>Tip for Trouble-shooting</h2>
106 * <p>Setting the <code>jaxp.debug</code> system property will cause
107 * this method to print a lot of debug messages
108 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
109 *
110 * <p> If you have problems loading {@link SAXParser}s, try:</p>
111 * <pre>
112 * java -Djaxp.debug=1 YourProgram ....
113 * </pre>
114 *
115 *
116 * @return A new instance of a SAXParserFactory.
117 *
118 * @throws FactoryConfigurationError in case of {@linkplain
119 * java.util.ServiceConfigurationError service configuration error} or if
120 * the implementation is not available or cannot be instantiated.
121 */
122
123 public static SAXParserFactory newInstance() {
124 return FactoryFinder.find(
125 /* The default property name according to the JAXP spec */
126 SAXParserFactory.class,
127 /* The fallback implementation class name */
128 "com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl");
129 }
130
131 /**
132 * <p>Obtain a new instance of a <code>SAXParserFactory</code> from class name.
133 * This function is useful when there are multiple providers in the classpath.
134 * It gives more control to the application as it can specify which provider
135 * should be loaded.</p>
136 *
137 * <p>Once an application has obtained a reference to a <code>SAXParserFactory</code>
138 * it can use the factory to configure and obtain parser instances.</p>
139 *
140 *
141 * <h2>Tip for Trouble-shooting</h2>
142 * <p>Setting the <code>jaxp.debug</code> system property will cause
143 * this method to print a lot of debug messages
144 * to <code>System.err</code> about what it is doing and where it is looking at.</p>
145 *
146 * <p> If you have problems, try:</p>
147 * <pre>
148 * java -Djaxp.debug=1 YourProgram ....
149 * </pre>
150 *
151 * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.parsers.SAXParserFactory</code>.
152 *
153 * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
154 * current <code>Thread</code>'s context classLoader is used to load the factory class.
155 *
156 * @return New instance of a <code>SAXParserFactory</code>
157 *
158 * @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or
159 * the factory class cannot be loaded, instantiated.
160 *
161 * @see #newInstance()
162 *
163 * @since 1.6
164 */
165 public static SAXParserFactory newInstance(String factoryClassName, ClassLoader classLoader){
166 //do not fallback if given classloader can't find the class, throw exception
167 return (SAXParserFactory) FactoryFinder.newInstance(factoryClassName, classLoader, false);
168 }
169
170 /**
171 * <p>Creates a new instance of a SAXParser using the currently
172 * configured factory parameters.</p>
173 *
174 * @return A new instance of a SAXParser.
175 *
176 * @throws ParserConfigurationException if a parser cannot
177 * be created which satisfies the requested configuration.
178 * @throws SAXException for SAX errors.
179 */
180
181 public abstract SAXParser newSAXParser()
182 throws ParserConfigurationException, SAXException;
183
184
185 /**
186 * Specifies that the parser produced by this code will
187 * provide support for XML namespaces. By default the value of this is set
292 /**
293 *
294 * <p>Returns the particular property requested for in the underlying
295 * implementation of org.xml.sax.XMLReader.</p>
296 *
297 * @param name The name of the property to be retrieved.
298 *
299 * @return Value of the requested property.
300 *
301 * @throws ParserConfigurationException if a parser cannot be created which satisfies the requested configuration.
302 * @throws SAXNotRecognizedException When the underlying XMLReader does not recognize the property name.
303 * @throws SAXNotSupportedException When the underlying XMLReader recognizes the property name but doesn't support the property.
304 *
305 * @see org.xml.sax.XMLReader#getProperty
306 */
307 public abstract boolean getFeature(String name)
308 throws ParserConfigurationException, SAXNotRecognizedException,
309 SAXNotSupportedException;
310
311
312 /**
313 * Gets the {@link Schema} object specified through
314 * the {@link #setSchema(Schema schema)} method.
315 *
316 *
317 * @throws UnsupportedOperationException When implementation does not
318 * override this method
319 *
320 * @return
321 * the {@link Schema} object that was last set through
322 * the {@link #setSchema(Schema)} method, or null
323 * if the method was not invoked since a {@link SAXParserFactory}
324 * is created.
325 *
326 * @since 1.5
327 */
328 public Schema getSchema() {
329 throw new UnsupportedOperationException(
330 "This parser does not support specification \""
331 + this.getClass().getPackage().getSpecificationTitle()
332 + "\" version \""
333 + this.getClass().getPackage().getSpecificationVersion()
334 + "\""
335 );
336 }
337
338 /**
339 * <p>Set the {@link Schema} to be used by parsers created
340 * from this factory.</p>
341 *
342 * <p>When a {@link Schema} is non-null, a parser will use a validator
343 * created from it to validate documents before it passes information
344 * down to the application.</p>
345 *
346 * <p>When warnings/errors/fatal errors are found by the validator, the parser must
347 * handle them as if those errors were found by the parser itself.
348 * In other words, if the user-specified {@link org.xml.sax.ErrorHandler}
349 * is set, it must receive those errors, and if not, they must be
350 * treated according to the implementation specific
351 * default error handling rules.
352 *
353 * <p>A validator may modify the SAX event stream (for example by
354 * adding default values that were missing in documents), and a parser
355 * is responsible to make sure that the application will receive
356 * those modified event stream.</p>
357 *
|