模块 java.xml
包 javax.xml.parsers

类 DocumentBuilderFactory

java.lang.Object
javax.xml.parsers.DocumentBuilderFactory
public abstract class DocumentBuilderFactory extends Object
定义一个工厂 API，使应用程序能够获得一个解析器，该解析器从 XML 文档生成 DOM 对象树。
自从：
1.4

  • 构造方法详细信息

    • DocumentBuilderFactory

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

  • 方法详情

    • newDefaultNSInstance

      public static DocumentBuilderFactory  newDefaultNSInstance()
      创建 DocumentBuilderFactory 内置系统默认实现的新 NamespaceAware 实例。默认情况下，工厂实例生成的解析器提供对 XML 命名空间的支持。
      实现要求：
      除了使用与 newDefaultInstance() 相同的进程创建工厂实例外，此方法还必须将 NamespaceAware 设置为 true。
      返回：
      DocumentBuilderFactory 内置系统默认实现的新实例。
      自从：
      13

    • newNSInstance

      public static DocumentBuilderFactory  newNSInstance()
      创建 DocumentBuilderFactory 的新 NamespaceAware 实例。默认情况下，工厂实例生成的解析器提供对 XML 命名空间的支持。
      实现要求：
      除了使用与 newInstance() 相同的进程创建工厂实例外，此方法还必须将 NamespaceAware 设置为 true。
      返回：
      DocumentBuilderFactory 的新实例
      抛出：
      FactoryConfigurationError - 在 服务配置错误 的情况下，或者如果实现不可用或无法实例化。
      自从：
      13

    • newNSInstance

      public static DocumentBuilderFactory  newNSInstance(String  factoryClassName, ClassLoader  classLoader)
      从类名创建 DocumentBuilderFactory 的新 NamespaceAware 实例。默认情况下，工厂实例生成的解析器提供对 XML 命名空间的支持。
      实现要求：
      除了使用与 newInstance(java.lang.String, java.lang.ClassLoader) 相同的进程创建工厂实例外，此方法还必须将 NamespaceAware 设置为 true。
      参数：
      factoryClassName - 提供 javax.xml.parsers.DocumentBuilderFactory 实现的完全限定工厂类名称。
      classLoader - ClassLoader 用于加载工厂类。如果是null，则使用当前Thread的context classLoader加载工厂类。
      返回：
      DocumentBuilderFactory 的新实例
      抛出：
      FactoryConfigurationError - 如果 factoryClassName 是 null ，或者无法加载、实例化工厂类。
      自从：
      13

    • newDefaultInstance

      public static DocumentBuilderFactory  newDefaultInstance()
      创建 DocumentBuilderFactory 内置系统默认实现的新实例。
      返回：
      DocumentBuilderFactory 内置系统默认实现的新实例。
      自从：
      9

    • newInstance

      public static DocumentBuilderFactory  newInstance()
      获得 DocumentBuilderFactory 的新实例。此方法使用 JAXP 查找机制 来确定要加载的 DocumentBuilderFactory 实现类。

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

      故障排除提示

      设置 jaxp.debug 系统属性将导致此方法向 System.err 打印大量调试消息，说明它正在做什么以及正在查看的位置。

      如果您在加载 DocumentBuilder 时遇到问题，请尝试：

       java -Djaxp.debug=1 YourProgram ....
      返回：
      DocumentBuilderFactory 的新实例
      抛出：
      FactoryConfigurationError - 在 服务配置错误 的情况下，或者如果实现不可用或无法实例化。

    • 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 用于加载工厂类。如果使用nullcurrentThread的context classLoader加载工厂类。
      返回：
      DocumentBuilderFactory 的新实例
      抛出：
      FactoryConfigurationError - 如果 factoryClassName 是 null ，或者无法加载、实例化工厂类。
      自从：
      1.6
      参见：

    • newDocumentBuilder

      public abstract DocumentBuilder  newDocumentBuilder() throws ParserConfigurationException
      使用当前配置的参数创建 DocumentBuilder 的新实例。
      返回：
      DocumentBuilder 的新实例。
      抛出：
      ParserConfigurationException - 如果无法创建满足请求配置的 DocumentBuilder。

    • setNamespaceAware

      public void setNamespaceAware(boolean awareness)
      指定由此代码生成的解析器将提供对 XML 名称空间的支持。默认情况下，此值设置为false
      参数：
      awareness - 如果生成的解析器将提供对 XML 名称空间的支持，则为真；否则为假。

    • setValidating

      public void setValidating(boolean validating)
      指定由此代码生成的解析器将在解析文档时验证它们。默认情况下，此值设置为 false 。

      请注意，此处的“验证”是指 XML 推荐中定义的 验证解析器。换句话说，它本质上只是控制 DTD 验证。 （JAXP 1.2 中定义的遗留两个属性除外。）

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

      参数：
      validating - 如果生成的解析器将在解析文档时验证文档，则为真；否则为假。

    • setIgnoringElementContentWhitespace

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

    • setExpandEntityReferences

      public void setExpandEntityReferences(boolean expandEntityRef)
      指定由此代码生成的解析器将扩展实体引用节点。默认情况下，此值设置为true
      参数：
      expandEntityRef - 如果生成的解析器将扩展实体引用节点，则为真；否则为假。

    • setIgnoringComments

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

    • setCoalescing

      public void setCoalescing(boolean coalescing)
      指定此代码生成的解析器会将 CDATA 节点转换为文本节点并将其附加到相邻的（如果有）文本节点。默认情况下，此值设置为false
      参数：
      coalescing - 如果生成的解析器将 CDATA 节点转换为文本节点并将其附加到相邻（如果有）文本节点，则为真；否则为假。

    • isNamespaceAware

      public boolean isNamespaceAware()
      指示工厂是否配置为生成可识别名称空间的解析器。
      返回：
      如果工厂配置为生成名称空间感知的解析器，则为真；否则为假。

    • isValidating

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

    • isIgnoringElementContentWhitespace

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

    • isExpandEntityReferences

      public boolean isExpandEntityReferences()
      指示工厂是否配置为生成扩展实体引用节点的解析器。
      返回：
      如果工厂配置为生成扩展实体引用节点的解析器，则为真；否则为假。

    • isIgnoringComments

      public boolean isIgnoringComments()
      指示工厂是否配置为生成忽略注解的解析器。
      返回：
      如果工厂配置为生成忽略注释的解析器，则为真；否则为假。

    • isCoalescing

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

    • setAttribute

      public abstract void setAttribute(String  name, Object  value) throws IllegalArgumentException
      允许用户在底层实现上设置特定属性。

      所有实现 JAXP 1.5 或更新版本的实现都需要支持 XMLConstants.ACCESS_EXTERNAL_DTD 和 XMLConstants.ACCESS_EXTERNAL_SCHEMA 属性。

      参数：
      name - 属性的名称。
      value - 属性的值。
      抛出：
      IllegalArgumentException - 如果底层实现无法识别该属性则抛出。

    • getAttribute

      public abstract Object  getAttribute(String  name) throws IllegalArgumentException
      允许用户检索底层实现的特定属性。
      参数：
      name - 属性的名称。
      返回：
      值 属性的值。
      抛出：
      IllegalArgumentException - 如果底层实现无法识别该属性则抛出。

    • setFeature

      public abstract void setFeature(String  name, boolean value) throws ParserConfigurationException
      为此工厂创建的 DocumentBuilderFactory 和 DocumentBuilder 设置一个功能。

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

      所有实现都需要支持 XMLConstants.FEATURE_SECURE_PROCESSING 功能。当特征是：

      参数：
      name - 特征名称。
      value - 是特征状态 true 或 false。
      抛出：
      ParserConfigurationException - 如果此 DocumentBuilderFactory 或它创建的 DocumentBuilder 不支持此功能。
      NullPointerException - 如果 name 参数为空。
      自从：
      1.5

    • getFeature

      public abstract boolean getFeature(String  name) throws ParserConfigurationException
      获取指定功能的状态。

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

      参数：
      name - 特征名称。
      返回：
      命名功能的状态。
      抛出：
      ParserConfigurationException - 如果此 DocumentBuilderFactory 或它创建的 DocumentBuilder 不支持此功能。
      自从：
      1.5

    • getSchema

      public Schema  getSchema()
      获取通过 setSchema(Schema schema) 方法指定的 Schema 对象。
      返回：
      最后通过 setSchema(Schema) 方法设置的 Schema 对象，如果自创建 DocumentBuilderFactory 以来未调用该方法，则为 null。
      抛出：
      UnsupportedOperationException - 当实现不覆盖此方法时。
      自从：
      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 对象结合使用是错误的。调用 newDocumentBuilder() 时，此类配置将导致 ParserConfigurationException 异常。

      实现者须知

      解析器必须能够与任何 Schema 实现一起工作。但是，解析器和模式可以使用特定于实现的自定义机制，只要它们产生规范中描述的结果即可。

      参数：
      schema - Schema 使用或 null 删除架构。
      抛出：
      UnsupportedOperationException - 当实现不覆盖此方法时。
      自从：
      1.5

    • setXIncludeAware

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

      如果在文档实例中发现 XInclude 标记，是否应按照 XML 包含 (XInclude) 1.0 版 中指定的方式进行处理。

      XInclude 处理默认为 false 。

      参数：
      state - 将 XInclude 处理设置为 true 或 false
      抛出：
      UnsupportedOperationException - 当实现不覆盖此方法时。
      自从：
      1.5

    • isXIncludeAware

      public boolean isXIncludeAware()
      获取 XInclude 处理的状态。
      返回：
      XInclude 处理的当前状态
      抛出：
      UnsupportedOperationException - 当实现不覆盖此方法时。
      自从：
      1.5