Package 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)
以查看给定类型的“源”或“结果”对象是否受支持。 例如,要测试是否支持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”映射到命名空间的方法。
一个解决方案是创建一个保存命名空间URI的“QName”对象,以及前缀和本地名称,但这并不总是最佳的解决方案,例如,当你想使用唯一的字符串作为键一个字典对象。 没有字符串表示也使得很难在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事件流时,它们不起作用。
匹配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”系统属性指定的转换工厂类无法找到或实例化时,通常会抛出此错误。
如果由于任何原因无法创建变形金刚,可能会抛出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或通过调用应用程序解析的转换内的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
-
接口摘要 接口 描述 ErrorListener 要提供自定义错误处理,实现此接口并使用setErrorListener
方法注册与执行的实例Transformer
。Result 实现此接口的对象包含构建转换结果树所需的信息。Source 实现此接口的对象包含充当源输入(XML源或转换指令)所需的信息。SourceLocator 此接口主要用于报告XML源或转换指令中发生错误的目的。Templates 实现此接口的对象是已处理的转换指令的运行时代表。URIResolver 实现此接口的对象,可由处理器调用,将document(),xsl:import或xsl:include中使用的URI转换为Source对象。 -
类摘要 Class 描述 OutputKeys 提供可用于设置Transformer的输出属性或从Transformer或Templates对象检索输出属性的字符串常量。Transformer 这个抽象类的一个实例可以将一个源代码树转换成一个结果树。TransformerFactory TransformerFactory实例可用于创建Transformer
和Templates
对象。 -
异常摘要 异常 描述 TransformerConfigurationException 表示严重的配置错误。TransformerException 此类指定在转换过程中发生的异常情况。 -
Error Summary Error 描述 TransformerFactoryConfigurationError Thrown when a problem with configuration with the Transformer Factories exists.