1. // $Id: SAXParserFactory.java,v 1.39 2004/04/20 00:22:02 kk122374 Exp $
  2. /*
  3. * @(#)SAXParserFactory.java 1.41 04/07/26
  4. *
  5. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  6. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  7. */
  8. package javax.xml.parsers;
  9. import javax.xml.validation.Schema;
  10. import org.xml.sax.SAXException;
  11. import org.xml.sax.SAXNotRecognizedException;
  12. import org.xml.sax.SAXNotSupportedException;
  13. /**
  14. * Defines a factory API that enables applications to configure and
  15. * obtain a SAX based parser to parse XML documents.
  16. *
  17. * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
  18. * @version $Revision: 1.39 $, $Date: 2004/04/20 00:22:02 $
  19. */
  20. public abstract class SAXParserFactory {
  21. /** The default property name according to the JAXP spec */
  22. private static final String DEFAULT_PROPERTY_NAME = "javax.xml.parsers.SAXParserFactory";
  23. /**
  24. * <p>Should Parsers be validating?</p>
  25. */
  26. private boolean validating = false;
  27. /**
  28. * <p>Should Parsers be namespace aware?</p>
  29. */
  30. private boolean namespaceAware = false;
  31. /**
  32. * <p>Protected constructor to force use of {@link #newInstance()}.</p>
  33. */
  34. protected SAXParserFactory () {
  35. }
  36. /**
  37. * Obtain a new instance of a <code>SAXParserFactory</code>. This
  38. * static method creates a new factory instance
  39. * This method uses the following ordered lookup procedure to determine
  40. * the <code>SAXParserFactory</code> implementation class to
  41. * load:
  42. * <ul>
  43. * <li>
  44. * Use the <code>javax.xml.parsers.SAXParserFactory</code> system
  45. * property.
  46. * </li>
  47. * <li>
  48. * Use the properties file "lib/jaxp.properties" in the JRE directory.
  49. * This configuration file is in standard <code>java.util.Properties
  50. * </code> format and contains the fully qualified name of the
  51. * implementation class with the key being the system property defined
  52. * above.
  53. *
  54. * The jaxp.properties file is read only once by the JAXP implementation
  55. * and it's values are then cached for future use. If the file does not exist
  56. * when the first attempt is made to read from it, no further attempts are
  57. * made to check for its existence. It is not possible to change the value
  58. * of any property in jaxp.properties after it has been read for the first time.
  59. * </li>
  60. * <li>
  61. * Use the Services API (as detailed in the JAR specification), if
  62. * available, to determine the classname. The Services API will look
  63. * for a classname in the file
  64. * <code>META-INF/services/javax.xml.parsers.SAXParserFactory</code>
  65. * in jars available to the runtime.
  66. * </li>
  67. * <li>
  68. * Platform default <code>SAXParserFactory</code> instance.
  69. * </li>
  70. * </ul>
  71. *
  72. * Once an application has obtained a reference to a
  73. * <code>SAXParserFactory</code> it can use the factory to
  74. * configure and obtain parser instances.
  75. *
  76. *
  77. *
  78. * <h2>Tip for Trouble-shooting</h2>
  79. * <p>Setting the <code>jaxp.debug</code> system property will cause
  80. * this method to print a lot of debug messages
  81. * to <tt>System.err</tt> about what it is doing and where it is looking at.</p>
  82. *
  83. * <p> If you have problems loading {@link DocumentBuilder}s, try:</p>
  84. * <pre>
  85. * java -Djaxp.debug=1 YourProgram ....
  86. * </pre>
  87. *
  88. *
  89. * @return A new instance of a SAXParserFactory.
  90. *
  91. * @exception FactoryConfigurationError if the implementation is
  92. * not available or cannot be instantiated.
  93. */
  94. public static SAXParserFactory newInstance() {
  95. try {
  96. return (SAXParserFactory) FactoryFinder.find(
  97. /* The default property name according to the JAXP spec */
  98. "javax.xml.parsers.SAXParserFactory",
  99. /* The fallback implementation class name */
  100. "com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl");
  101. } catch (FactoryFinder.ConfigurationError e) {
  102. throw new FactoryConfigurationError(e.getException(),
  103. e.getMessage());
  104. }
  105. }
  106. /**
  107. * <p>Creates a new instance of a SAXParser using the currently
  108. * configured factory parameters.</p>
  109. *
  110. * @return A new instance of a SAXParser.
  111. *
  112. * @exception ParserConfigurationException if a parser cannot
  113. * be created which satisfies the requested configuration.
  114. * @exception SAXException for SAX errors.
  115. */
  116. public abstract SAXParser newSAXParser()
  117. throws ParserConfigurationException, SAXException;
  118. /**
  119. * Specifies that the parser produced by this code will
  120. * provide support for XML namespaces. By default the value of this is set
  121. * to <code>false</code>.
  122. *
  123. * @param awareness true if the parser produced by this code will
  124. * provide support for XML namespaces; false otherwise.
  125. */
  126. public void setNamespaceAware(boolean awareness) {
  127. this.namespaceAware = awareness;
  128. }
  129. /**
  130. * Specifies that the parser produced by this code will
  131. * validate documents as they are parsed. By default the value of this is
  132. * set to <code>false</code>.
  133. *
  134. * <p>
  135. * Note that "the validation" here means
  136. * <a href="http://www.w3.org/TR/REC-xml#proc-types">a validating
  137. * parser</a> as defined in the XML recommendation.
  138. * In other words, it essentially just controls the DTD validation.
  139. * (except the legacy two properties defined in JAXP 1.2.
  140. * See <a href="#validationCompatibility">here</a> for more details.)
  141. * </p>
  142. *
  143. * <p>
  144. * To use modern schema languages such as W3C XML Schema or
  145. * RELAX NG instead of DTD, you can configure your parser to be
  146. * a non-validating parser by leaving the {@link #setValidating(boolean)}
  147. * method <tt>false</tt>, then use the {@link #setSchema(Schema)}
  148. * method to associate a schema to a parser.
  149. * </p>
  150. *
  151. * @param validating true if the parser produced by this code will
  152. * validate documents as they are parsed; false otherwise.
  153. */
  154. public void setValidating(boolean validating) {
  155. this.validating = validating;
  156. }
  157. /**
  158. * Indicates whether or not the factory is configured to produce
  159. * parsers which are namespace aware.
  160. *
  161. * @return true if the factory is configured to produce
  162. * parsers which are namespace aware; false otherwise.
  163. */
  164. public boolean isNamespaceAware() {
  165. return namespaceAware;
  166. }
  167. /**
  168. * Indicates whether or not the factory is configured to produce
  169. * parsers which validate the XML content during parse.
  170. *
  171. * @return true if the factory is configured to produce parsers which validate
  172. * the XML content during parse; false otherwise.
  173. */
  174. public boolean isValidating() {
  175. return validating;
  176. }
  177. /**
  178. *
  179. * <p>Sets the particular feature in the underlying implementation of
  180. * org.xml.sax.XMLReader.
  181. * A list of the core features and properties can be found at
  182. * <a href="http://www.saxproject.org/">http://www.saxproject.org/</a></p>
  183. *
  184. * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
  185. * When the feature is</p>
  186. * <ul>
  187. * <li>
  188. * <code>true</code>: the implementation will limit XML processing to conform to implementation limits.
  189. * Examples include enity expansion limits and XML Schema constructs that would consume large amounts of resources.
  190. * If XML processing is limited for security reasons, it will be reported via a call to the registered
  191. * {@link org.xml.sax.ErrorHandler#fatalError(SAXParseException exception)}.
  192. * See {@link SAXParser} <code>parse</code> methods for handler specification.
  193. * </li>
  194. * <li>
  195. * When the feature is <code>false</code>, the implementation will processing XML according to the XML specifications without
  196. * regard to possible implementation limits.
  197. * </li>
  198. * </ul>
  199. *
  200. * @param name The name of the feature to be set.
  201. * @param value The value of the feature to be set.
  202. *
  203. * @exception ParserConfigurationException if a parser cannot
  204. * be created which satisfies the requested configuration.
  205. * @exception SAXNotRecognizedException When the underlying XMLReader does
  206. * not recognize the property name.
  207. * @exception SAXNotSupportedException When the underlying XMLReader
  208. * recognizes the property name but doesn't support the
  209. * property.
  210. * @throws NullPointerException If the <code>name</code> parameter is null.
  211. *
  212. * @see org.xml.sax.XMLReader#setFeature
  213. */
  214. public abstract void setFeature(String name, boolean value)
  215. throws ParserConfigurationException, SAXNotRecognizedException,
  216. SAXNotSupportedException;
  217. /**
  218. *
  219. * <p>Returns the particular property requested for in the underlying
  220. * implementation of org.xml.sax.XMLReader.</p>
  221. *
  222. * @param name The name of the property to be retrieved.
  223. *
  224. * @return Value of the requested property.
  225. *
  226. * @exception ParserConfigurationException if a parser cannot be created which satisfies the requested configuration.
  227. * @exception SAXNotRecognizedException When the underlying XMLReader does not recognize the property name.
  228. * @exception SAXNotSupportedException When the underlying XMLReader recognizes the property name but doesn't support the property.
  229. *
  230. * @see org.xml.sax.XMLReader#getProperty
  231. */
  232. public abstract boolean getFeature(String name)
  233. throws ParserConfigurationException, SAXNotRecognizedException,
  234. SAXNotSupportedException;
  235. /* <p>Get current state of canonicalization.</p>
  236. *
  237. * @return current state canonicalization control
  238. */
  239. /*
  240. public boolean getCanonicalization() {
  241. return canonicalState;
  242. }
  243. */
  244. /**
  245. * Gets the {@link Schema} object specified through
  246. * the {@link #setSchema(Schema schema)} method.
  247. *
  248. *
  249. * @throws UnsupportedOperationException
  250. * For backward compatibility, when implementations for
  251. * earlier versions of JAXP is used, this exception will be
  252. * thrown.
  253. *
  254. * @return
  255. * the {@link Schema} object that was last set through
  256. * the {@link #setSchema(Schema)} method, or null
  257. * if the method was not invoked since a {@link SAXParserFactory}
  258. * is created.
  259. *
  260. * @since 1.5
  261. */
  262. public Schema getSchema() {
  263. throw new UnsupportedOperationException(
  264. "This parser does not support specification \""
  265. + this.getClass().getPackage().getSpecificationTitle()
  266. + "\" version \""
  267. + this.getClass().getPackage().getSpecificationVersion()
  268. + "\""
  269. );
  270. }
  271. /** <p>Set canonicalization control to <code>true</code> or
  272. * </code>false</code>.</p>
  273. *
  274. * @param state of canonicalization
  275. */
  276. /*
  277. public void setCanonicalization(boolean state) {
  278. canonicalState = state;
  279. }
  280. */
  281. /**
  282. * <p>Set the {@link Schema} to be used by parsers created
  283. * from this factory.</p>
  284. *
  285. * <p>When a {@link Schema} is non-null, a parser will use a validator
  286. * created from it to validate documents before it passes information
  287. * down to the application.</p>
  288. *
  289. * <p>When warnings/errors/fatal errors are found by the validator, the parser must
  290. * handle them as if those errors were found by the parser itself.
  291. * In other words, if the user-specified {@link org.xml.sax.ErrorHandler}
  292. * is set, it must receive those errors, and if not, they must be
  293. * treated according to the implementation specific
  294. * default error handling rules.
  295. *
  296. * <p>A validator may modify the SAX event stream (for example by
  297. * adding default values that were missing in documents), and a parser
  298. * is responsible to make sure that the application will receive
  299. * those modified event stream.</p>
  300. *
  301. * <p>Initialy, <code>null</code> is set as the {@link Schema}.</p>
  302. *
  303. * <p>This processing will take effect even if
  304. * the {@link #isValidating()} method returns <code>false</code>.
  305. *
  306. * <p>It is an error to use
  307. * the <code>http://java.sun.com/xml/jaxp/properties/schemaSource</code>
  308. * property and/or the <code>http://java.sun.com/xml/jaxp/properties/schemaLanguage</code>
  309. * property in conjunction with a non-null {@link Schema} object.
  310. * Such configuration will cause a {@link SAXException}
  311. * exception when those properties are set on a {@link SAXParser}.</p>
  312. *
  313. * <h4>Note for implmentors</h4>
  314. * <p>
  315. * A parser must be able to work with any {@link Schema}
  316. * implementation. However, parsers and schemas are allowed
  317. * to use implementation-specific custom mechanisms
  318. * as long as they yield the result described in the specification.
  319. * </p>
  320. *
  321. * @param schema <code>Schema</code> to use, <code>null</code> to remove a schema.
  322. *
  323. * @throws UnsupportedOperationException
  324. * For backward compatibility, when implementations for
  325. * earlier versions of JAXP is used, this exception will be
  326. * thrown.
  327. *
  328. * @since 1.5
  329. */
  330. public void setSchema(Schema schema) {
  331. throw new UnsupportedOperationException(
  332. "This parser does not support specification \""
  333. + this.getClass().getPackage().getSpecificationTitle()
  334. + "\" version \""
  335. + this.getClass().getPackage().getSpecificationVersion()
  336. + "\""
  337. );
  338. }
  339. /**
  340. * <p>Set state of XInclude processing.</p>
  341. *
  342. * <p>If XInclude markup is found in the document instance, should it be
  343. * processed as specified in <a href="http://www.w3.org/TR/xinclude/">
  344. * XML Inclusions (XInclude) Version 1.0</a>.</p>
  345. *
  346. * <p>XInclude processing defaults to <code>false</code>.</p>
  347. *
  348. * @param state Set XInclude processing to <code>true</code> or
  349. * <code>false</code>
  350. *
  351. * @throws UnsupportedOperationException
  352. * For backward compatibility, when implementations for
  353. * earlier versions of JAXP is used, this exception will be
  354. * thrown.
  355. *
  356. * @since 1.5
  357. */
  358. public void setXIncludeAware(final boolean state) {
  359. throw new UnsupportedOperationException(
  360. "This parser does not support specification \""
  361. + this.getClass().getPackage().getSpecificationTitle()
  362. + "\" version \""
  363. + this.getClass().getPackage().getSpecificationVersion()
  364. + "\""
  365. );
  366. }
  367. /**
  368. * <p>Get state of XInclude processing.</p>
  369. *
  370. * @return current state of XInclude processing
  371. *
  372. * @throws UnsupportedOperationException
  373. * For backward compatibility, when implementations for
  374. * earlier versions of JAXP is used, this exception will be
  375. * thrown.
  376. *
  377. * @since 1.5
  378. */
  379. public boolean isXIncludeAware() {
  380. throw new UnsupportedOperationException(
  381. "This parser does not support specification \""
  382. + this.getClass().getPackage().getSpecificationTitle()
  383. + "\" version \""
  384. + this.getClass().getPackage().getSpecificationVersion()
  385. + "\""
  386. );
  387. }
  388. }