javax.xml.parsers
类 SAXParserFactory

java.lang.Object
  javax.xml.parsers.SAXParserFactory

public abstract class SAXParserFactory
extends Object

定义工厂 API，使应用程序能够配置和获取基于 SAX 的解析器以解析 XML 文档。

SAXParserFactory

protected SAXParserFactory()

受保护构造方法，以强制使用 newInstance()。

newInstance

public static SAXParserFactory newInstance()

获取 SAXParserFactory 的一个新实例。此静态方法创建一个新的工厂实例，此方法按照以下查找过程顺序来确定要加载的 SAXParserFactory 实例类：

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

在应用程序获取对 SAXParserFactory 的引用后，它可以使用工厂来配置和获取解析器实例。

疑难解答提示

设置 jaxp.debug 系统属性将导致此方法将许多调试消息打印到 System.err，以说明其执行的操作以及在何处查找。

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

 java -Djaxp.debug=1 YourProgram ....
 

返回：

新的 SAXParserFactory 实例。

抛出：

FactoryConfigurationError - 如果该实现不可用，或者无法被实例化。

newInstance

public static SAXParserFactory newInstance(String factoryClassName,
                                           ClassLoader classLoader)

从类名称中获取新的 SAXParserFactory 实例。此函数在类路径中有多个提供者时很有用。它可以对应用程序提供更多的控制，因为它可以指定应该加载哪个提供者。

在应用程序获取对 SAXParserFactory 的引用后，它可以使用工厂来配置和获取解析器实例。

疑难解答提示

设置 jaxp.debug 系统属性将导致此方法将许多调试消息打印到 System.err，这些消息说明了正在执行的操作以及何处可以找到它。

如有问题，可尝试使用以下代码：

 java -Djaxp.debug=1 YourProgram ....
 

参数：

factoryClassName - 提供 javax.xml.parsers.SAXParserFactory 的实现的完全限定工厂类名称。

classLoader - 用来加载工厂类的 ClassLoader。如果该参数为 null，则使用当前 Thread 的上下文类加载器来加载工厂类。

返回：

新的 SAXParserFactory 实例

抛出：

FactoryConfigurationError - 如果 factoryClassName 为 null，或者无法加载和实例化工厂类。

从以下版本开始：

1.6

另请参见：

newInstance()

newSAXParser

public abstract SAXParser newSAXParser()
                                throws ParserConfigurationException,
                                       SAXException

使用当前配置的工厂参数创建 SAXParser 的一个新实例。

返回：

新的 SAXParser 实例。

抛出：

ParserConfigurationException - 如果无法创建满足所请求配置的解析器，将抛出该异常。

SAXException - 用于 SAX 错误。

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。

isNamespaceAware

public boolean isNamespaceAware()

指示是否将工厂配置为生成具有感知名称空间功能的解析器。

返回：

如果将工厂配置为生成具有感知名称空间功能的解析器，则返回 true；否则返回 false。

isValidating

public boolean isValidating()

指示是否将工厂配置为生成解析器，该解析器在解析时验证 XML 内容。

返回：

如果将工厂配置为生成在解析时验证 XML 内容的解析器，则返回 true；否则返回 false。

setFeature

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

在 org.xml.sax.XMLReader 的底层实现中设置特定的功能。核心功能和属性列表可以在 http://www.saxproject.org/ 中找到。

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

• true：该实现将限制 XML 处理遵守实现限制。示例包括实体扩展限制和将使用大量资源的 XML 模式构造。如果出于安全原因限制 XML 处理，将通过调用注册的 ErrorHandler.fatalError(SAXParseException exception) 进行报告。请参见处理程序规范的 SAXParser parse 方法。
• 当该功能为 false 时，该实现将根据 XML 规范处理 XML，而无需考虑可能的实现限制。

参数：

name - 要设置的功能的名称。

value - 要设置的功能值。

抛出：

ParserConfigurationException - 如果无法创建满足所请求配置的解析器。

SAXNotRecognizedException - 当底层 XMLReader 不能识别属性名称时。

SAXNotSupportedException - 当底层 XMLReader 可以识别属性名称，但不支持该属性时。

NullPointerException - 如果 name 参数为 null。

另请参见：

XMLReader.setFeature(java.lang.String, boolean)

getFeature

public abstract boolean getFeature(String name)
                            throws ParserConfigurationException,
                                   SAXNotRecognizedException,
                                   SAXNotSupportedException

返回 org.xml.sax.XMLReader 的底层实现中请求的特定属性。

参数：

name - 要检索的属性的名称。

返回：

所请求属性的值。

抛出：

ParserConfigurationException - 如果无法创建满足所请求配置的解析器，将抛出该异常。

SAXNotRecognizedException - 当底层 XMLReader 不能识别属性名称时。

SAXNotSupportedException - 当底层 XMLReader 可以识别属性名称，但不支持该属性时。

另请参见：

XMLReader.getProperty(java.lang.String)

getSchema

public Schema getSchema()

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

返回：

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

抛出：

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

从以下版本开始：

1.5

setSchema

public void setSchema(Schema schema)

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

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

在验证器发现警告/错误/致命错误时，解析器必须处理它们，就好像这些错误是由解析器自己发现的一样。换句话说，如果设置了用户指定的 ErrorHandler，则它必须接收这些错误，否则，必须根据特定于实现的默认错误处理规则来处理它们。

验证器可以修改 SAX 事件流（例如，通过添加在文档中缺少的默认值），解析器负责确保应用程序将接收这些修改的事件流。

最初，null 被设置为 Schema。

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

将 http://java.sun.com/xml/jaxp/properties/schemaSource 属性和/或 http://java.sun.com/xml/jaxp/properties/schemaLanguage 属性与非 null Schema 对象一起使用将发生错误。当在 SAXParser 上设置这些属性时，此类配置将导致 SAXException 异常。

实现者请注意：

解析器必须能够与任何 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. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。