DocumentBuilderFactory

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM 2 Platform
Standard Ed. 5.0

上一个类 下一个类

框架 无框架

摘要：嵌套 | 字段 | 构造方法 | 方法

详细信息：字段 | 构造方法 | 方法

javax.xml.parsers
类 DocumentBuilderFactory

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

public abstract class DocumentBuilderFactory
extends Object
extends Object

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

构造方法摘要
`protected`	`DocumentBuilderFactory()`

方法摘要
`abstract Object`	`getAttribute(String name)` 允许用户在基础实现上检索特定属性。
`abstract boolean`	`getFeature(String name)` 获取指定功能的状态。
`Schema`	`getSchema()` 获取通过 `setSchema(Schema schema)` 方法指定的 `Schema` 对象。
`boolean`	`isCoalescing()` 指示是否将工厂配置为名称空间这样的解析器，该解析器将 CDATA 节点转换为 Text 节点，并将其附加到相邻（如果有）的 Text 节点。
`boolean`	`isExpandEntityReferences()` 指示是否将工厂配置为生成扩展实体引用节点的解析器。
`boolean`	`isIgnoringComments()` 指示是否将工厂配置为生成忽略注释的解析器。
`boolean`	`isIgnoringElementContentWhitespace()` 指示是否将工厂配置为生成解析器，该解析器忽略元素内容中的可忽略空格。
`boolean`	`isNamespaceAware()` 指示是否将工厂配置为生成具有感知名称空间功能的解析器。
`boolean`	`isValidating()` 指示是否将工厂配置为生成解析器，该解析器在解析时验证 XML 内容。
`boolean`	`isXIncludeAware()` 获取 XInclude 处理的状态。
`abstract DocumentBuilder`	`newDocumentBuilder()` 使用当前配置的参数创建一个新的 `DocumentBuilder` 实例。
`static DocumentBuilderFactory`	`newInstance()` 获取 `DocumentBuilderFactory` 的新实例。
`abstract void`	`setAttribute(String name, Object value)` 允许用户在基础实现上设置特定属性。
`void`	`setCoalescing(boolean coalescing)` 指定由此代码生成的解析器将把 CDATA 节点转换为 Text 节点，并将其附加到相邻（如果有）的 Text 节点。
`void`	`setExpandEntityReferences(boolean expandEntityRef)` 指定由此代码产生的解析器将扩展实体引用节点。
`abstract void`	`setFeature(String name, boolean value)` 设置由此工厂创建的此 `DocumentBuilderFactory` 和 `DocumentBuilder` 的功能。
`void`	`setIgnoringComments(boolean ignoreComments)` 指定由此代码生成的解析器将忽略注释。
`void`	`setIgnoringElementContentWhitespace(boolean whitespace)` 指定由此工厂创建的解析器在解析 XML 文档时，必须删除元素内容中的空格（有时是指一般的“可忽略空格”，请参阅 XML Rec 2.10）。
`void`	`setNamespaceAware(boolean awareness)` 指定由此代码生成的解析器将提供对 XML 名称空间的支持。
`void`	`setSchema(Schema schema)` 设置将由解析器使用的 `Schema`，该解析器从此工厂创建。
`void`	`setValidating(boolean validating)` 指定由此代码生成的解析器将验证被解析的文档。
`void`	`setXIncludeAware(boolean state)` 设置 XInclude 处理的状态。

从类 java.lang.Object 继承的方法
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

构造方法详细信息

DocumentBuilderFactory

protected DocumentBuilderFactory()

方法详细信息

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 - 如果该实现不可用，或者无法实例化。

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 Schema 构造。如果出于安全原因限制 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

获取指定功能的状态。

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

getSchema

public Schema getSchema()

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

返回：: 最后通过 setSchema(Schema) 方法设置的 Schema 对象，如果该方法由于创建了 SAXParserFactory 而没有被调用，则返回 null。
抛出：: UnsupportedOperationException - 为了向后兼容，当使用 JAXP 较早版本的实现时，将抛出此异常。
从以下版本开始：: 1.5

setSchema

public void setSchema(Schema schema)

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

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

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

验证器可以修改解析器的结果（例如，通过在文档中添加丢失的默认值），解析器负责确保应用程序接收修改的 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 - 为了向后兼容，当使用 JAXP 较早版本的实现时，将抛出此异常。
从以下版本开始：: 1.5

setXIncludeAware

public void setXIncludeAware(boolean state)

设置 XInclude 处理的状态。

如果在文档实例中发现 XInclude 标记，则应按 XML Inclusions (XInclude) Version 1.0 中指定的方式处理。

XInclude 处理默认为 false。

参数：: state - 将 XInclude 处理设置为 true 或 false
抛出：: UnsupportedOperationException - 为了向后兼容，当使用 JAXP 较早版本的实现时，将抛出此异常。
从以下版本开始：: 1.5

isXIncludeAware

public boolean isXIncludeAware()

获取 XInclude 处理的状态。

返回：: XInclude 处理的当前状态
抛出：: UnsupportedOperationException - 为了向后兼容，当使用 JAXP 较早版本的实现时，将抛出此异常。
从以下版本开始：: 1.5

概述