模块  java.xml

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)) { ... }

Qualified Name Representation

Namespaces在处理XML对象时出现了一些问题区域。 限定名称在XML标记中显示为带前缀的名称。 但前缀本身并不具有身份。 相反，它是上下文映射到的URI，用于保存标识。 因此，当在Java程序中传递诸如“xyz：foo”之类的限定名称时，必须提供将“xyz”映射到命名空间的方法。

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

为了将命名空间值传递给转换，例如在Transformer对象上设置属性或参数时，此规范定义String“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事件流时，它们不起作用。

匹配的字符串XSLT specification for xsl:output attributes可以从被引用OutputKeys类。 也可以指定其他字符串。 如果变压器无法识别输出键，则抛出IllegalArgumentException ，除非键名为namespace qualified 。 始终允许命名空间限定的输出键名称，但某些实现可能会忽略它们。

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

例外和错误报告

转换API抛出三种类型的专用异常。 甲TransformerFactoryConfigurationError平行于FactoryConfigurationError ，并且当与所述的TransformerFactory的结构存在问题，则抛出。 当无法找到或实例化使用“javax.xml.transform.TransformerFactory”系统属性指定的转换工厂类时，通常会抛出此错误。

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

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

转换警告和错误发送到ErrorListener ，此时应用程序可能决定报告错误或警告，并可能决定抛出异常以发现非致命错误。 ErrorListener可以通过TransformerFactory.setErrorListener(javax.xml.transform.ErrorListener)设置，用于报告与转换指令中的语法错误有关的错误，或通过Transformer.setErrorListener(javax.xml.transform.ErrorListener)报告转换期间发生的错误。 两个对象上的ErrorListener始终有效且非null ，无论是由应用程序设置还是由处理器提供的默认实现。 处理器提供的默认实现将向System.err报告所有警告和错误，并且不会抛出任何异常 。 强烈建议应用程序注册并使用ErrorListener ，以确保警告和错误的正确行为。

解析转换中的URI

API为样式表指令内或转换中引用的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。 返回的Source对象必须可由变换器使用，如其实现的功能中所指定。

从以下版本开始：
1.5