Module java.xml
Package javax.xml.parsers

Class DocumentBuilderFactory

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

  • Constructor Details

    • DocumentBuilderFactory

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

  • Method Details

    • newDefaultNSInstance

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

    • newNSInstance

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

    • newNSInstance

      public static DocumentBuilderFactory newNSInstance(String factoryClassName, ClassLoader classLoader)
      从类名创建NamespaceAware的DocumentBuilderFactory的新实例。由工厂实例生成的解析器默认提供对XML命名空间的支持。
      实现要求:
      除了使用与newInstance(java.lang.String, java.lang.ClassLoader)相同的过程创建工厂实例外，此方法必须将NamespaceAware设置为true。
      参数:
      factoryClassName - 提供javax.xml.parsers.DocumentBuilderFactory实现的完全限定工厂类名。
      classLoader - 用于加载工厂类的ClassLoader。如果为null，则使用当前Thread的上下文类加载器来加载工厂类。
      返回:
      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。如果null，则使用当前Thread的上下文类加载器来加载工厂类。
      返回:
      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命名空间的支持，则为true；否则为false。

    • setValidating

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

      请注意，这里的“验证”是指XML建议中定义的验证解析器。换句话说，它基本上只控制DTD验证。（除了JAXP 1.2中定义的两个旧属性。）

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

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

    • setIgnoringElementContentWhitespace

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

    • setExpandEntityReferences

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

    • setIgnoringComments

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

    • setCoalescing

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

    • isNamespaceAware

      public boolean isNamespaceAware()
      指示工厂是否配置为生成具有命名空间感知的解析器。
      返回：
      如果工厂配置为生成具有命名空间感知的解析器，则为true；否则为false。

    • isValidating

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

    • isIgnoringElementContentWhitespace

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

    • isExpandEntityReferences

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

    • isIgnoringComments

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

    • isCoalescing

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

    • 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。实现可以定义自己的功能。如果此DocumentBuilderFactory或其创建的DocumentBuilder不支持该功能，则会抛出ParserConfigurationException。可能会有DocumentBuilderFactory公开功能值但无法更改其状态。

      所有实现都必须支持XMLConstants.FEATURE_SECURE_PROCESSING功能。当功能为：

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

    • getFeature

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

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

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

    • getSchema

      public Schema getSchema()
      获取通过setSchema(Schema schema)方法指定的Schema对象。
      返回:
      通过Schema对象，最后通过setSchema(Schema)方法设置的对象，如果自从创建DocumentBuilderFactory以来未调用该方法，则返回null。
      抛出:
      UnsupportedOperationException - 当实现未覆盖此方法时。
      自:
      1.5

    • setSchema

      public void setSchema(Schema schema)
      设置从此工厂创建的解析器要使用的Schema。

      当Schema为非null时，解析器将使用从中创建的验证器来验证文档，然后将信息传递给应用程序。

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

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

      最初，将null设置为Schema。

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

      在使用Schema对象时，使用http://java.sun.com/xml/jaxp/properties/schemaSource属性和/或http://java.sun.com/xml/jaxp/properties/schemaLanguage属性是错误的。这样的配置将在调用newDocumentBuilder()时导致ParserConfigurationException异常。

      实现者注意事项

      解析器必须能够与任何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