包 javax.xml.transform
Source
和 Result
接口来实现这一点。
为了为用户提供具体的类,API 定义了在根级别找到的接口的专门化。这些接口位于 javax.xml.transform.sax
、javax.xml.transform.dom
、javax.xml.transform.stax
和 javax.xml.transform.stream
中。
创建对象
API 允许从静态函数 TransformerFactory.newInstance()
创建具体的 TransformerFactory
对象。
输入和输出规范
该 API 定义了两个接口对象,称为 Source
和 Result
。为了将 Source 和 Result 对象传递给接口,必须使用具体类。为这些对象中的每一个定义了以下具体表示:StreamSource
和StreamResult
、StAXSource
和StAXResult
、SAXSource
和SAXResult
以及DOMSource
和DOMResult
。这些对象中的每一个都定义了一个 FEATURE 字符串(以 URL 的形式),可以将其传递到 TransformerFactory.getFeature(java.lang.String)
以查看是否支持给定类型的 Source 或 Result 对象。例如,要测试是否支持 DOMSource 和 StreamResult,您可以应用以下测试。
TransformerFactory tfactory = TransformerFactory.newInstance();
if (tfactory.getFeature(DOMSource.FEATURE) &&
tfactory.getFeature(StreamResult.FEATURE)) {
...
}
限定名称表示
命名空间 在处理 XML 对象时出现了一些问题区域。限定名称作为前缀名称出现在 XML 标记中。但是前缀本身并不具有身份。相反,它们根据上下文映射到的 URI 拥有身份。因此,当在 Java 程序中传递“xyz:foo”这样的限定名称时,必须提供一种将“xyz”映射到名称空间的方法。
一种解决方案是创建一个“QName”对象,它包含命名空间 URI、前缀和本地名称,但这并不总是最佳解决方案,例如,当您想要使用唯一字符串作为字典对象。没有字符串表示也使得在 XML 文档上下文之外指定命名空间标识变得困难。
为了将命名空间值传递给转换,例如在 Transformer
对象上设置属性或参数时,本规范定义字符串“qname”对象参数作为两部分字符串传递,命名空间 URI 括在花括号中( {}),后跟本地名称。如果 qname 具有空 URI,则 String 对象仅包含本地名称。应用程序可以通过测试名称的第一个字符是否为“{”字符来安全地检查非空 URI。
例如,如果从使用 <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/> 定义的元素中获取 URI 和本地名称,则限定名称将为“{http://xyz.foo.com/yada/baz.html}foo”。请注意,前缀丢失了。
结果树序列化
可以使用 Transformer.setOutputProperties(java.util.Properties)
和 Transformer.setOutputProperty(java.lang.String, java.lang.String)
方法控制将结果树序列化为流。这些属性仅适用于流结果,当结果是 DOM 树或 SAX 事件流时,它们不起作用。
可以从 OutputKeys
类中引用与 xsl:output属性的 XSLT 规范 匹配的字符串。也可以指定其他字符串。如果转换器无法识别输出键,则会抛出 IllegalArgumentException
,除非键名是 命名空间限定。始终允许使用命名空间限定的输出键名称,尽管某些实现可能会忽略它们。
如果所需要的只是源到结果的简单身份转换,那么 TransformerFactory
会提供一个没有参数的 TransformerFactory.newTransformer()
方法。此方法创建一个 Transformer,可有效地将源复制到结果。此方法可用于从 SAX 事件创建 DOM,或者从 DOM 或 SAX 事件创建 XML 或 HTML 流。
异常和错误报告
转换 API 抛出三种类型的特殊异常。 TransformerFactoryConfigurationError
与 FactoryConfigurationError
平行,当 TransformerFactory 存在配置问题时抛出。当无法找到或实例化使用“javax.xml.transform.TransformerFactory”系统属性指定的转换工厂类时,通常会抛出此错误。
如果出于任何原因无法创建 Transformer,则可能会抛出 TransformerConfigurationException
。如果转换指令中存在语法错误,例如调用 TransformerFactory.newTransformer(javax.xml.transform.Source)
时,可能会抛出 TransformerConfigurationException。
TransformerException
是在转换过程中发生的一般异常。转换器异常可能会包装另一个异常,并且如果在其上调用任何 TransformerException.printStackTrace()
方法,它将生成堆栈转储列表,从最近的开始。转换器异常还提供了一个 SourceLocator
对象,它指示源代码树或转换指令中发生错误的位置。可以调用 TransformerException.getMessageAndLocation()
来获取包含位置信息的错误消息,可以调用 TransformerException.getLocationAsString()
来获取位置字符串。
转换警告和错误被发送到 ErrorListener
,此时应用程序可能决定报告错误或警告,并可能决定抛出 Exception
用于非致命错误。 ErrorListener
可以通过 TransformerFactory.setErrorListener(javax.xml.transform.ErrorListener)
设置以报告与转换指令中的语法错误有关的错误,或通过 Transformer.setErrorListener(javax.xml.transform.ErrorListener)
设置以报告转换期间发生的错误。两个对象上的 ErrorListener
将始终有效且非 null
,无论是由应用程序设置还是由处理器提供的默认实现。
在转换中解析 URI
API 提供了一种方法,可以让调用应用程序解析从样式表指令或转换中引用的 URI。这可以通过创建一个实现 URIResolver
接口的类来完成,它具有一个方法 URIResolver.resolve(java.lang.String, java.lang.String)
,并使用此类为转换指令或使用 TransformerFactory.setURIResolver(javax.xml.transform.URIResolver)
或 Transformer.setURIResolver(javax.xml.transform.URIResolver)
的转换设置 URI 解析。 URIResolver.resolve
方法采用两个字符串参数,在样式表指令中找到或作为转换过程的一部分构建的 URI,以及如果需要绝对 URI,第一个参数将根据其成为绝对 URI 的基本 URI。返回的 Source
对象必须可由转换器使用,如其实现的功能中所指定。
- 自从:
- 1.5
-
类描述
TransformerFactory
或Transformer
使用的监听器接口通知调用者转换过程中发生的错误消息。提供可用于设置 Transformer 的输出属性或从 Transformer 或 Templates 对象检索输出属性的字符串常量。实现此接口的对象包含构建转换结果树所需的信息。实现此接口的对象包含充当源输入(XML 源或转换指令)所需的信息。此接口主要用于报告 XML 源或转换指令中发生错误的位置。实现此接口的对象是已处理转换指令的运行时表示。这个抽象类的实例可以将源树转换为结果树。表示严重的配置错误。此类指定在转换过程中发生的异常情况。TransformerFactory 实例可用于创建Transformer
和Templates
对象。当 Transformer Factories 的配置存在问题时抛出。实现此接口的对象,处理器可以调用该接口将 document()、xsl:import 或 xsl:include 中使用的 URI 转换为 Source 对象。