src/javax/xml/parsers/DocumentBuilderFactory.java

Print this page




 406     public abstract Object getAttribute(String name)
 407                 throws IllegalArgumentException;
 408 
 409     /**
 410      * <p>Set a feature for this <code>DocumentBuilderFactory</code> and <code>DocumentBuilder</code>s created by this factory.</p>
 411      *
 412      * <p>
 413      * Feature names are fully qualified {@link java.net.URI}s.
 414      * Implementations may define their own features.
 415      * A {@link ParserConfigurationException} is thrown if this <code>DocumentBuilderFactory</code> or the
 416      * <code>DocumentBuilder</code>s it creates cannot support the feature.
 417      * It is possible for a <code>DocumentBuilderFactory</code> to expose a feature value but be unable to change its state.
 418      * </p>
 419      *
 420      * <p>
 421      * All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
 422      * When the feature is:</p>
 423      * <ul>
 424      *   <li>
 425      *     <code>true</code>: the implementation will limit XML processing to conform to implementation limits.
 426      *     Examples include enity expansion limits and XML Schema constructs that would consume large amounts of resources.
 427      *     If XML processing is limited for security reasons, it will be reported via a call to the registered
 428      *    {@link org.xml.sax.ErrorHandler#fatalError(SAXParseException exception)}.
 429      *     See {@link  DocumentBuilder#setErrorHandler(org.xml.sax.ErrorHandler errorHandler)}.
 430      *   </li>
 431      *   <li>
 432      *     <code>false</code>: the implementation will processing XML according to the XML specifications without
 433      *     regard to possible implementation limits.
 434      *   </li>
 435      * </ul>
 436      *
 437      * @param name Feature name.
 438      * @param value Is feature state <code>true</code> or <code>false</code>.
 439      *
 440      * @throws ParserConfigurationException if this <code>DocumentBuilderFactory</code> or the <code>DocumentBuilder</code>s
 441      *   it creates cannot support this feature.
 442      * @throws NullPointerException If the <code>name</code> parameter is null.
 443      */
 444     public abstract void setFeature(String name, boolean value)
 445             throws ParserConfigurationException;
 446 


 500      * When a {@link Schema} is non-null, a parser will use a validator
 501      * created from it to validate documents before it passes information
 502      * down to the application.
 503      *
 504      * <p>When errors are found by the validator, the parser is responsible
 505      * to report them to the user-specified {@link org.xml.sax.ErrorHandler}
 506      * (or if the error handler is not set, ignore them or throw them), just
 507      * like any other errors found by the parser itself.
 508      * In other words, if the user-specified {@link org.xml.sax.ErrorHandler}
 509      * is set, it must receive those errors, and if not, they must be
 510      * treated according to the implementation specific
 511      * default error handling rules.
 512      *
 513      * <p>
 514      * A validator may modify the outcome of a parse (for example by
 515      * adding default values that were missing in documents), and a parser
 516      * is responsible to make sure that the application will receive
 517      * modified DOM trees.
 518      *
 519      * <p>
 520      * Initialy, null is set as the {@link Schema}.
 521      *
 522      * <p>
 523      * This processing will take effect even if
 524      * the {@link #isValidating()} method returns <code>false</code>.
 525      *
 526      * <p>It is an error to use
 527      * the <code>http://java.sun.com/xml/jaxp/properties/schemaSource</code>
 528      * property and/or the <code>http://java.sun.com/xml/jaxp/properties/schemaLanguage</code>
 529      * property in conjunction with a {@link Schema} object.
 530      * Such configuration will cause a {@link ParserConfigurationException}
 531      * exception when the {@link #newDocumentBuilder()} is invoked.</p>
 532      *
 533      *
 534      * <h4>Note for implmentors</h4>
 535      *
 536      * <p>
 537      * A parser must be able to work with any {@link Schema}
 538      * implementation. However, parsers and schemas are allowed
 539      * to use implementation-specific custom mechanisms
 540      * as long as they yield the result described in the specification.
 541      * </p>
 542      *
 543      * @param schema <code>Schema</code> to use or <code>null</code>
 544      *   to remove a schema.
 545      *
 546      * @throws UnsupportedOperationException When implementation does not
 547      *   override this method.
 548      *
 549      * @since 1.5
 550      */
 551     public void setSchema(Schema schema) {
 552         throw new UnsupportedOperationException(
 553             "This parser does not support specification \""
 554             + this.getClass().getPackage().getSpecificationTitle()




 406     public abstract Object getAttribute(String name)
 407                 throws IllegalArgumentException;
 408 
 409     /**
 410      * <p>Set a feature for this <code>DocumentBuilderFactory</code> and <code>DocumentBuilder</code>s created by this factory.</p>
 411      *
 412      * <p>
 413      * Feature names are fully qualified {@link java.net.URI}s.
 414      * Implementations may define their own features.
 415      * A {@link ParserConfigurationException} is thrown if this <code>DocumentBuilderFactory</code> or the
 416      * <code>DocumentBuilder</code>s it creates cannot support the feature.
 417      * It is possible for a <code>DocumentBuilderFactory</code> to expose a feature value but be unable to change its state.
 418      * </p>
 419      *
 420      * <p>
 421      * All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
 422      * When the feature is:</p>
 423      * <ul>
 424      *   <li>
 425      *     <code>true</code>: the implementation will limit XML processing to conform to implementation limits.
 426      *     Examples include entity expansion limits and XML Schema constructs that would consume large amounts of resources.
 427      *     If XML processing is limited for security reasons, it will be reported via a call to the registered
 428      *    {@link org.xml.sax.ErrorHandler#fatalError(SAXParseException exception)}.
 429      *     See {@link  DocumentBuilder#setErrorHandler(org.xml.sax.ErrorHandler errorHandler)}.
 430      *   </li>
 431      *   <li>
 432      *     <code>false</code>: the implementation will processing XML according to the XML specifications without
 433      *     regard to possible implementation limits.
 434      *   </li>
 435      * </ul>
 436      *
 437      * @param name Feature name.
 438      * @param value Is feature state <code>true</code> or <code>false</code>.
 439      *
 440      * @throws ParserConfigurationException if this <code>DocumentBuilderFactory</code> or the <code>DocumentBuilder</code>s
 441      *   it creates cannot support this feature.
 442      * @throws NullPointerException If the <code>name</code> parameter is null.
 443      */
 444     public abstract void setFeature(String name, boolean value)
 445             throws ParserConfigurationException;
 446 


 500      * When a {@link Schema} is non-null, a parser will use a validator
 501      * created from it to validate documents before it passes information
 502      * down to the application.
 503      *
 504      * <p>When errors are found by the validator, the parser is responsible
 505      * to report them to the user-specified {@link org.xml.sax.ErrorHandler}
 506      * (or if the error handler is not set, ignore them or throw them), just
 507      * like any other errors found by the parser itself.
 508      * In other words, if the user-specified {@link org.xml.sax.ErrorHandler}
 509      * is set, it must receive those errors, and if not, they must be
 510      * treated according to the implementation specific
 511      * default error handling rules.
 512      *
 513      * <p>
 514      * A validator may modify the outcome of a parse (for example by
 515      * adding default values that were missing in documents), and a parser
 516      * is responsible to make sure that the application will receive
 517      * modified DOM trees.
 518      *
 519      * <p>
 520      * Initially, null is set as the {@link Schema}.
 521      *
 522      * <p>
 523      * This processing will take effect even if
 524      * the {@link #isValidating()} method returns <code>false</code>.
 525      *
 526      * <p>It is an error to use
 527      * the <code>http://java.sun.com/xml/jaxp/properties/schemaSource</code>
 528      * property and/or the <code>http://java.sun.com/xml/jaxp/properties/schemaLanguage</code>
 529      * property in conjunction with a {@link Schema} object.
 530      * Such configuration will cause a {@link ParserConfigurationException}
 531      * exception when the {@link #newDocumentBuilder()} is invoked.</p>
 532      *
 533      *
 534      * <h4>Note for implementors</h4>
 535      *
 536      * <p>
 537      * A parser must be able to work with any {@link Schema}
 538      * implementation. However, parsers and schemas are allowed
 539      * to use implementation-specific custom mechanisms
 540      * as long as they yield the result described in the specification.
 541      * </p>
 542      *
 543      * @param schema <code>Schema</code> to use or <code>null</code>
 544      *   to remove a schema.
 545      *
 546      * @throws UnsupportedOperationException When implementation does not
 547      *   override this method.
 548      *
 549      * @since 1.5
 550      */
 551     public void setSchema(Schema schema) {
 552         throw new UnsupportedOperationException(
 553             "This parser does not support specification \""
 554             + this.getClass().getPackage().getSpecificationTitle()