Module java.xml

Package javax.xml.transform

package 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"映射到命名空间的方法。

一种解决方案是创建一个包含命名空间URI、前缀和本地名称的"QName"对象，但这并不总是最佳解决方案，例如当您想要在字典对象中使用唯一字符串作为键时。没有字符串表示形式也使得在XML文档之外指定命名空间标识变得困难。

为了将带命名空间的值传递给转换，例如在为Transformer对象设置属性或参数时，该规范定义了一个名为"qname"的字符串对象参数，该参数作为两部分字符串传递，命名空间URI用大括号（{}）括起来，后跟本地名称。如果qname具有空URI，则字符串对象仅包含本地名称。应用程序可以通过检查名称的第一个字符是否为'{'字符来安全地检查非空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事件流时不起作用。

符合XSLT规范中xsl:output属性的字符串可以从OutputKeys类中引用。也可以指定其他字符串。如果转换器不识别输出键，将抛出一个IllegalArgumentException，除非键名是命名空间限定的。始终允许命名空间限定的输出键名称，尽管某些实现可能会忽略它们。

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

异常和错误报告

转换API抛出三种特殊异常。当存在与TransformerFactory的配置问题时，会抛出一个TransformerFactoryConfigurationError，类似于FactoryConfigurationError，当无法找到或实例化使用"javax.xml.transform.TransformerFactory"系统属性指定的转换工厂类时，通常会抛出此错误。

如果由于任何原因无法创建Transformer，则可能会抛出TransformerConfigurationException。如果转换指令中存在语法错误，例如调用TransformerFactory.newTransformer(javax.xml.transform.Source)时，可能会抛出TransformerConfigurationException。

TransformerException是在转换过程中发生的一般异常。转换器异常可能包装另一个异常，如果在其上调用任何TransformerException.printStackTrace()方法，则会生成一系列堆栈转储，从最近的开始。转换器异常还提供一个SourceLocator对象，指示错误发生在源树或转换指令的哪个位置。TransformerException.getMessageAndLocation()可用于获取带有位置信息的错误消息，TransformerException.getLocationAsString()可用于仅获取位置字符串。

转换警告和错误将发送到ErrorListener，此时应用程序可以决定报告错误或警告，并可能决定对非致命错误抛出异常。可以通过TransformerFactory.setErrorListener(javax.xml.transform.ErrorListener)设置ErrorListener以报告与转换指令中的语法错误有关的错误，或通过Transformer.setErrorListener(javax.xml.transform.ErrorListener)报告转换过程中发生的错误。这两个对象上的ErrorListener始终有效且非null，无论是由应用程序设置还是处理器提供的默认实现。

转换中URI的解析

API提供了一种方式，使得在样式表指令中引用的URI或转换中引用的URI可以由调用应用程序解析。这可以通过创建一个实现了URIResolver接口的类来实现，该接口具有一个方法URIResolver.resolve(java.lang.String, java.lang.String)，并使用此类为转换指令或转换设置URI解析，方法是通过TransformerFactory.setURIResolver(javax.xml.transform.URIResolver)或Transformer.setURIResolver(javax.xml.transform.URIResolver)。URIResolver.resolve方法接受两个String参数，第一个参数是在样式表指令中找到的URI或作为转换过程的一部分构建的URI，第二个参数是基本URI，如果需要绝对URI，则将第一个参数相对于基本URI。返回的Source对象必须可由转换器使用，如其实现的特性所指定。

自版本:
1.5