模块 java.xml

包 javax.xml.transform


javax.xml.transform
定义用于处理转换指令和执行从源到结果的转换的通用 API。这些接口不依赖于 SAX 或 DOM 标准,并尝试尽可能少地假设源和转换结果的细节。它通过定义 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