JavaTM Platform
Standard Ed. 6

软件包 javax.xml.transform

此包定义了用于处理转换指令,以及执行从源到结果的转换的一般 API。

请参见:
          描述

接口摘要
ErrorListener 要提供自定义错误处理,则需实现此接口并使用 setErrorListener 方法注册一个带有 Transformer 的实现的实例。
Result 实现此接口的对象包含构建转换结果树所需的信息。
Source 实现此接口的对象包含充当源输入(XML 源或转换指令)所需的信息
SourceLocator 此接口的主要目的是报告在 XML 源或转换指令中发生错误的位置。
Templates 实现此接口的对象是处理后的转换指令的运行时表示形式。
URIResolver 实现此接口的对象可由处理器进行调用,以将 document()、xsl:import 或 xsl:include 中使用的 URI 转换为 Source 对象。
 

类摘要
OutputKeys 提供可用于设置 Transformer 的输出属性或从 Transformer 或 Templates 对象检索输出属性的字符串常量。
Transformer 此抽象类的实例能够将源树转换为结果树。
TransformerFactory TransformerFactory 实例可用于创建 TransformerTemplates 对象。
 

异常摘要
TransformerConfigurationException 指示严重的配置错误。
TransformerException 此类指定了转换过程中发生的异常条件。
 

错误摘要
TransformerFactoryConfigurationError 当通过 Transformer Factories 进行的配置存在问题时抛出此异常。
 

软件包 javax.xml.transform 的描述

此包定义了用于处理转换指令,以及执行从源到结果的转换的一般 API。这些接口不依赖于 SAX 或 DOM 标准,且尽可能少地进行有关转换的源和结果的细节的假定。它通过定义 SourceResult 接口来实现这一点。

为了定义具体的用户类,API 定义了根级接口规范。这些接口可以在 javax.xml.transform.saxjavax.xml.transform.domjavax.xml.transform.stream 中找到。

创建对象

API 从静态函数 TransformerFactory.newInstance() 创建具体 TransformerFactory 对象。

输入和输出规范

此 API 定义了两个接口对象,它们称为 SourceResult。为将 Source 和 Result 对象传递到接口,必须使用具体类。为每个对象定义了三个具体表示形式:StreamSourceStreamResultSAXSourceSAXResultDOMSourceDOMResult。这些对象中的每一个对象均定义了一个 FEATURE 字符串,可以将它传递到 TransformerFactory.getFeature(java.lang.String) 中以查看是否支持给定类型的 Source 或 Result 对象。例如,要测试是否支持 DOMSource 和 StreamResult,可以使用以下测试。


TransformerFactory tfactory = TransformerFactory.newInstance();
if (tfactory.getFeature(DOMSource.FEATURE) && tfactory.getFeature(StreamResult.FEATURE)) {
...
}

Qualified Name 表示形式

当处理 XML 对象时,Namespaces 存在某些问题。XML 中出现的 Qualified Names 标记为带前缀的名称。但前缀本身不保持标识。而由它们在上下文中所映射到的 URI 来保持标识。因此,当在 Java 程序中传递像 "xyz:foo" 这样的 Qualified Name 时,必须提供将 "xyz" 映射到名称空间的方式。

一种解决方案是创建一个保持名称空间以及前缀和本地名称的 "QName" 对象,但这不总是最佳解决方案,例如,当要将唯一字符串用作字典中的键时就是如此。没有字符串表示形式还将导致难以在 XML 文档的上下文之外指定名称空间的标识。

为了将名称空间的值传递给转换,例如当设置 Transformer 上的属性或参数时,此规范定义 String "qname" 对象参数作为两部分字符串来传递,即用花括号({})括起来的名称空间 URI,后跟本地名称。如果 qname 有 null URI,则 String 对象只包含本地名称。应用程序可以通过测试安全地检查非 null URI,以查看名称的首字符是否为 '{' 字符。

例如,如果 URI 和本地名称是从通过 <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/> 定义的元素获取的,则 Qualified Name 将为 "{http://xyz.foo.com/yada/baz.html}foo"。注意不使用前缀。

结果树序列化

结果树到流的序列化可以通过 Transformer.setOutputProperties(java.util.Properties)Transformer.setOutputProperty(java.lang.String, java.lang.String) 方法来控制。这些属性只应用于流结果,当结果为 DOM 树或 SAX 事件流时,它们无效。

可以从 OutputKeys 类引用匹配 XSLT specification for xsl:output attributes 的字符串。也可以指定其他字符串。如果转换器不识别输出键,则抛出 IllegalArgumentException,除非键名称为 namespace qualified。虽然某些实现可能会忽略名称空间限定的输出键名称,但它们总是允许的。

如果只需从源到结果的简单标识转换,则 TransformerFactory 提供一个不带参数的 TransformerFactory.newTransformer() 方法。此方法创建一个将源有效复制到结果的 Transformer。此方法可用于从 SAX 事件创建 DOM,或从 DOM 或 SAX 事件创建 XML。

异常和错误报告

转换 API 抛出三种类型的特殊异常。


JavaTM Platform
Standard Ed. 6

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

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