JavaTM Platform
Standard Ed. 6

javax.xml.parsers
类 SAXParserFactory

java.lang.Object
  继承者 javax.xml.parsers.SAXParserFactory

public abstract class SAXParserFactory
     
extends Object

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


构造方法摘要
protected SAXParserFactory()
          受保护构造方法,以强制使用 newInstance()
 
方法摘要
abstract  boolean getFeature(String name)
          返回 org.xml.sax.XMLReader 的底层实现中请求的特定属性。
 Schema getSchema()
          获取通过 setSchema(Schema schema) 方法指定的 Schema 对象。
 boolean isNamespaceAware()
          指示是否将工厂配置为生成具有感知名称空间功能的解析器。
 boolean isValidating()
          指示是否将工厂配置为生成解析器,该解析器在解析时验证 XML 内容。
 boolean isXIncludeAware()
          获取 XInclude 处理的状态。
static SAXParserFactory newInstance()
          获取 SAXParserFactory 的一个新实例。
static SAXParserFactory newInstance(String factoryClassName, ClassLoader classLoader)
          从类名称中获取新的 SAXParserFactory 实例。
abstract  SAXParser newSAXParser()
          使用当前配置的工厂参数创建 SAXParser 的一个新实例。
abstract  void setFeature(String name, boolean value)
          在 org.xml.sax.XMLReader 的底层实现中设置特定的功能。
 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
 

构造方法详细信息

SAXParserFactory

protected SAXParserFactory()

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

方法详细信息

newInstance

public static SAXParserFactory newInstance()
获取 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 - 如果 factoryClassNamenull,或者无法加载和实例化工厂类。
从以下版本开始:
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 功能。当功能为以下情况时:

参数:
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 处理设置为 truefalse
抛出:
UnsupportedOperationException - 当该实现没有重写此方法时
从以下版本开始:
1.5

isXIncludeAware

public boolean isXIncludeAware()

获取 XInclude 处理的状态。

返回:
XInclude 处理的当前状态
抛出:
UnsupportedOperationException - 当实现没有重写此方法时
从以下版本开始:
1.5

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

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