Module  java.xml
软件包  javax.xml.parsers

Class DocumentBuilderFactory


  • public abstract class DocumentBuilderFactory
extends Object
    定义工厂API，使应用程序能够从XML文档获取生成DOM对象树的解析器。
    从以下版本开始：
    1.4

    • 构造方法详细信息

      • DocumentBuilderFactory

        protected DocumentBuilderFactory​()
        受保护的构造函数以防止实例化。 使用newInstance() 。

    • 方法详细信息

      • newDefaultInstance

        public static DocumentBuilderFactory newDefaultInstance​()
        创建一个 DocumentBuilderFactory内置系统默认实现的新实例。
        结果
        DocumentBuilderFactory内置系统默认实现的新实例。
        从以下版本开始：
        9

      • newInstance

        public static DocumentBuilderFactory newInstance​()
        获得一个新的实例DocumentBuilderFactory 。 这个静态方法创建一个新的工厂实例。 此方法使用以下有序查找过程来确定要加载的DocumentBuilderFactory实现类：
        • 使用javax.xml.parsers.DocumentBuilderFactory系统属性。

        • 使用配置文件“jaxp.properties”。 该文件采用标准Properties格式，通常位于Java安装的conf目录中。 它包含实现类的完全限定名称，其中键是上面定义的系统属性。

          jaxp.properties文件由JAXP实现只读一次，然后将其值缓存以备将来使用。 如果文件第一次尝试读取文件不存在，则不再进一步检查其存在。 在第一次读取jaxp.properties之后，无法更改任何属性的值。

        • 使用由ServiceLoader类定义的服务提供商加载工具，使用default loading mechanism尝试定位和加载服务的实现 ：服务提供商加载工具将使用current thread's context class loader尝试加载服务。 如果上下文类加载器为null，将使用system class loader 。

        • 否则返回system-default的实现。

        一旦应用程序获得了对DocumentBuilderFactory的引用，就可以使用工厂来配置和获取解析器实例。

        提示进行故障排除

        设置jaxp.debug系统属性将导致此方法打印大量调试消息到System.err有关它在做什么和它在哪里看。

        如果加载DocumentBuilder有问题，请尝试： 

          java -Djaxp.debug=1 YourProgram ....
        结果
        新实例 DocumentBuilderFactory
        异常
        FactoryConfigurationError -在以下情况下service configuration error或者如果实现不可用或不能被实例化。

      • newInstance

        public static DocumentBuilderFactory newInstance​(String factoryClassName,
                                                 ClassLoader classLoader)
        从类名获取一个新的实例DocumentBuilderFactory 。 在类路径中有多个提供程序时，此功能很有用。 它可以更好地控制应用程序，因为它可以指定应该加载哪个提供程序。

        一旦应用程序获得了对DocumentBuilderFactory的引用，就可以使用工厂来配置和获取解析器实例。

        提示进行故障排除

        设置jaxp.debug系统属性将导致此方法打印大量调试消息到System.err有关它在做什么和它在哪里看。

        如果您有问题，请尝试： 

          java -Djaxp.debug=1 YourProgram ....
        参数
        factoryClassName - 提供 javax.xml.parsers.DocumentBuilderFactory实施的完全合格的工厂类名称。
        classLoader - ClassLoader用于加载工厂类。 如果null当前的Thread的上下文classLoader用于加载工厂类。
        结果
        新实例 DocumentBuilderFactory
        异常
        FactoryConfigurationError - 如果 factoryClassName是 null ，或者工厂类无法加载，实例化。
        从以下版本开始：
        1.6
        另请参见：
        newInstance()

      • setNamespaceAware

        public void setNamespaceAware​(boolean awareness)
        指定此代码生成的解析器将为XML命名空间提供支持。 默认值为false
        参数
        awareness - 如果生成的解析器将为XML命名空间提供支持， awareness true; 否则为假。

      • setValidating

        public void setValidating​(boolean validating)
        指定此代码生成的解析器将在文档解析时验证文档。 默认值为false 。

        请注意，这里的“验证”是指XML推荐中定义的a validating parser 。 换句话说，它基本上只是控制DTD验证。 （JAXP 1.2中定义的遗留的两个属性除外）

        要使用现代模式语言（如W3C XML Schema或RELAX NG而不是DTD），您可以通过离开setValidating(boolean)方法false将您的解析器配置为非验证解析器，然后使用setSchema(Schema)方法将模式与解析器相关联。

        参数
        validating - 如果解析器生成的文档将被验证， validating true; 否则为假。

      • setIgnoringElementContentWhitespace

        public void setIgnoringElementContentWhitespace​(boolean whitespace)
        指定此工厂创建的解析器必须在解析XML文档时消除元素内容中的空格（有时称为“可忽略的空白”）（请参阅XML Rec 2.10）。 请注意，只有具有仅包含元素内容模型（参见XML Rec 3.2.1）的元素内容中直接包含的空格将被消除。 由于依赖于内容模型，此设置需要解析器处于验证模式。 默认值为false 。
        参数
        whitespace - 如果创建的解析器在解析XML文档时必须消除元素内容中的空格， whitespace true; 否则为假。

      • setExpandEntityReferences

        public void setExpandEntityReferences​(boolean expandEntityRef)
        指定此代码生成的解析器将扩展实体引用节点。 默认值为true
        参数
        expandEntityRef - 如果生成的解析器将扩展实体引用节点， expandEntityRef true; 否则为假。

      • setIgnoringComments

        public void setIgnoringComments​(boolean ignoreComments)
        指定此代码生成的解析器将忽略注释。 默认值为false 。
        参数
        ignoreComments - boolean在处理过程中忽略注释的值

      • setCoalescing

        public void setCoalescing​(boolean coalescing)
        指定此代码生成的解析器将CDATA节点转换为文本节点并将其附加到相邻（如果有的话）文本节点。 默认值为false
        参数
        coalescing - 如果生成的解析器将CDATA节点转换为文本节点并将其附加到相邻（如果有的话）文本节点， coalescing true; 否则为假。

      • isNamespaceAware

        public boolean isNamespaceAware​()
        指示工厂是否配置为生成名称空间感知的解析器。
        结果
        如果工厂配置为生成名称空间感知的解析器，则为true; 否则为假。

      • isValidating

        public boolean isValidating​()
        指示工厂是否配置为生成在解析期间验证XML内容的解析器。
        结果
        如果工厂配置为生成在解析期间验证XML内容的解析器，则为true; 否则为假。

      • isIgnoringElementContentWhitespace

        public boolean isIgnoringElementContentWhitespace​()
        指示工厂是否配置为生成忽略元素内容中的可忽略空白的解析器。
        结果
        如果工厂配置为生成忽略元素内容中的可忽略空白的解析器，则为true; 否则为假。

      • isExpandEntityReferences

        public boolean isExpandEntityReferences​()
        指示工厂是否配置为生成扩展实体引用节点的解析器。
        结果
        如果工厂配置为生成扩展实体引用节点的解析器，则为true; 否则为假。

      • isIgnoringComments

        public boolean isIgnoringComments​()
        指示工厂是否配置为生成忽略注释的解析器。
        结果
        如果工厂配置为生成忽略注释的解析器，则为true; 否则为假。

      • isCoalescing

        public boolean isCoalescing​()
        指示工厂是否配置为生成将CDATA节点转换为文本节点并将其附加到相邻（如果有）文本节点）的解析器。
        结果
        如果工厂配置为生成将CDATA节点转换为文本节点并将其附加到相邻（如果有的话）文本节点的解析器，则为true; 否则为假。

      • getFeature

        public abstract boolean getFeature​(String name)
                            throws ParserConfigurationException
        获取命名功能的状态。

        功能名称完全符合条件URI s。 实现可以定义自己的特征。 如果这个DocumentBuilderFactory或其创建的DocumentBuilder不能支持该功能，则抛出一个ParserConfigurationException 。 DocumentBuilderFactory可以公开特征值，但无法更改其状态。

        参数
        name - 功能名称。
        结果
        命名功能的状态。
        异常
        ParserConfigurationException - 如果这个 DocumentBuilderFactory或其创建的 DocumentBuilder不能支持此功能。
        从以下版本开始：
        1.5

      • setSchema

        public void setSchema​(Schema schema)
        将Schema设置为由此工厂创建的解析器使用。

        当Schema为非空值时，解析器将使用从其创建的验证器在将信息传递给应用程序之前验证文档。

        当验证器发现错误时，解析器负责将其报告给用户指定的ErrorHandler （或者如果错误处理程序未设置，忽略它们或抛出它们），就像解析器本身发现的任何其他错误一样。 换句话说，如果设置了用户指定的ErrorHandler ，则必须接收到这些错误，如果不是，则必须根据实现特定的默认错误处理规则进行处理。

        验证器可以修改解析的结果（例如通过添加在文档中缺少的默认值），并且解析器负责确保应用程序将接收修改的DOM树。

        最初，null设置为Schema 。

        即使isValidating()方法返回false此处理也将生效。

        将http://java.sun.com/xml/jaxp/properties/schemaSource属性和/或http://java.sun.com/xml/jaxp/properties/schemaLanguage属性与Schema对象结合使用是一个错误。 这样的配置将导致一个ParserConfigurationException的时候例外newDocumentBuilder()被调用。

        实施者注意事项

        解析器必须能够使用任何Schema实现。 但是，解析器和模式允许使用实现特定的定制机制，只要它们产生规范中描述的结果即可。

        参数
        schema - Schema或 null删除一个模式。
        异常
        UnsupportedOperationException - 实现时不覆盖此方法。
        从以下版本开始：
        1.5

      • setXIncludeAware

        public void setXIncludeAware​(boolean state)
        设置XInclude处理的状态。

        如果在文档实例中找到XInclude标记，则应按XML Inclusions (XInclude) Version 1.0中的规定进行处理。

        XInclude处理默认为false 。

        参数
        state - 将XInclude处理设为 true或 false
        异常
        UnsupportedOperationException - 实现时不覆盖此方法。
        从以下版本开始：
        1.5

      • isXIncludeAware

        public boolean isXIncludeAware​()
        获取XInclude处理的状态。
        结果
        XInclude处理的当前状态
        异常
        UnsupportedOperationException - 实现时不覆盖此方法。
        从以下版本开始：
        1.5