javax.xml.parsers
类 DocumentBuilderFactory

java.lang.Object
  javax.xml.parsers.DocumentBuilderFactory

public abstract class DocumentBuilderFactory
extends Object

定义工厂 API，使应用程序能够从 XML 文档获取生成 DOM 对象树的解析器。

DocumentBuilderFactory

protected DocumentBuilderFactory()

用于阻止实例化的受保护构造方法。请使用 newInstance()。

newInstance

public static DocumentBuilderFactory newInstance()

获取 DocumentBuilderFactory 的新实例。此 static 方法创建一个新的工厂实例。此方法使用以下查找过程顺序来确定要加载的 DocumentBuilderFactory 实现类：

• 使用 javax.xml.parsers.DocumentBuilderFactory 系统属性。
• 使用 JRE 文件夹中的属性文件 "lib/jaxp.properties"。此配置文件格式为标准的 java.util.Properties 且包含实现类的完全限定名，其中实现类的键是上述定义的系统属性。 JAXP 实现只读取一次 jaxp.properties 文件，然后缓存其值供以后使用。如果首次尝试读取文件时，文件不存在，则不会再次尝试检查该文件是否存在。首次读取 jaxp.properties 后，其中的属性值不能再更改。
• 如果可以，使用 Services API（在 JAR 规范中进行了详细描述）来确定类名称。Services API 将查找在运行时可用的 jar 中 META-INF/services/javax.xml.parsers.DocumentBuilderFactory 文件中的类名。
• 平台默认的 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

另请参见：

newInstance()

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 Rec 2.10）。注意，只有在空格直接包含在元素内容中，并且该元素内容是只有一个元素的内容模式时，才能删除空格（请参阅 XML Rec 3.2.1）。由于依赖于内容模式，因此此设置要求解析器处于验证模式。默认情况下，其值设置为 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 节点转换为 Text 节点，并将其附加到相邻（如果有）的 Text 节点。默认情况下，其值设置为 false。

参数：

coalescing - 生成的解析器将把 CDATA 节点转换为 Text 节点，并将其附加到相邻（如果有）的文本节点，则为 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 节点转换为 Text 节点，并将其附加到相邻（如果有）的 Text 节点。

返回：

将工厂配置为满足以下条件的解析器：该解析器将 CDATA 节点转换为 Text 节点，并将其附加到相邻（如果有）的 Text 节点，则返回 true；否则返回 false。

setAttribute

public abstract void setAttribute(String name,
                                  Object value)
                           throws IllegalArgumentException

允许用户在底层实现上设置特定属性。

参数：

name - 属性名称。

value - 属性值。

抛出：

IllegalArgumentException - 如果底层实现无法识别该属性，则抛出该异常。

getAttribute

public abstract Object getAttribute(String name)
                             throws IllegalArgumentException

允许用户在底层实现上检索特定属性。

参数：

name - 属性名称。

返回：

value 属性值。

抛出：

IllegalArgumentException - 如果底层实现无法识别该属性，则抛出该异常。

setFeature

public abstract void setFeature(String name,
                                boolean value)
                         throws ParserConfigurationException

设置由此工厂创建的此 DocumentBuilderFactory 和 DocumentBuilder 的功能。

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

所有实现必须支持 XMLConstants.FEATURE_SECURE_PROCESSING 功能。当功能为以下情况时：

• true：该实现将限制 XML 处理遵守实现限制。示例包括实体扩展限制和将使用大量资源的 XML 模式构造。如果出于安全原因限制 XML 处理，将通过调用注册的 ErrorHandler.fatalError(SAXParseException exception) 进行报告。请参阅 DocumentBuilder.setErrorHandler(org.xml.sax.ErrorHandler errorHandler)。
• false：实现将根据 XML 规范来处理 XML，而无需考虑可能的实现限制。

参数：

name - 功能名称。

value - 功能状态为 true 或 false。

抛出：

ParserConfigurationException - 如果此 DocumentBuilderFactory 或其创建的 DocumentBuilder 不能支持此功能。

NullPointerException - 如果 name 参数为 null。

getFeature

public abstract boolean getFeature(String name)
                            throws ParserConfigurationException

获取指定功能的状态。

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

参数：

name - 功能名称。

返回：

指定功能的状态。

抛出：

ParserConfigurationException - 如果此 DocumentBuilderFactory 或其创建的 DocumentBuilder 不能支持此功能。

getSchema

public Schema getSchema()

获取通过 setSchema(Schema schema) 方法指定的 Schema 对象。

返回：

最后通过 setSchema(Schema) 方法设置的 Schema 对象，如果由于创建了 DocumentBuilderFactory 而没有调用该方法，则返回 null。

抛出：

UnsupportedOperationException - 当实现没有重写此方法时。

从以下版本开始：

1.5

setSchema

public void setSchema(Schema schema)

设置将由解析器使用的 Schema，该解析器从此工厂创建。

如果 Schema 为非 null，则在将信息向下传递到应用程序之前，解析器将使用从中创建的验证器来验证文档。

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

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

最初，null 被设置为 Schema。

即使 isValidating() 方法返回 false，此过程也将生效。

将 https://java.sun.com/xml/jaxp/properties/schemaSource 属性和/或 https://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 Inclusions (XInclude) Version 1.0 中指定的方式处理。

XInclude 处理默认为 false。

参数：

state - 将 XInclude 处理设置为 true 或 false

抛出：

UnsupportedOperationException - 当实现没有重写此方法时。

从以下版本开始：

1.5

isXIncludeAware

public boolean isXIncludeAware()

获取 XInclude 处理的状态。

返回：

XInclude 处理的当前状态

抛出：

UnsupportedOperationException - 当实现没有重写此方法时。

从以下版本开始：

1.5

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。