javax.xml.transform
类 Transformer

java.lang.Object
  javax.xml.transform.Transformer

public abstract class Transformer
extends Object

此抽象类的实例能够将源树转换为结果树。

可以通过 TransformerFactory.newTransformer 方法获取此类的实例。然后可以使用此实例处理来自不同源的 XML，并将转换输出写入各种接收器。

在多线程同时运行时不能使用此类的对象。不同线程可以同时使用不同的 Transformers。

Transformer 可以多次使用。可以在转换之间保留参数和输出属性。

构造方法摘要

protected

Transformer() 默认构造方法受到有意保护。

方法摘要

abstract void	clearParameters() 清除所有通过 setParameter 设置的参数。
abstract ErrorListener	getErrorListener() 获取转换的实际错误事件处理程序。
abstract Properties	getOutputProperties() 获取转换的输出属性的副本。
abstract String	getOutputProperty(String name) 获取对转换器有效的输出属性。
abstract Object	getParameter(String name) 获取通过 setParameter 显式设置的参数。
abstract URIResolver	getURIResolver() 获取将用于解析在 document() 中使用的 URI 的对象。
void	reset() 将此 Transformer 重置为其初始配置。
abstract void	setErrorListener(ErrorListener listener) 设置转换的实际错误事件侦听器。
abstract void	setOutputProperties(Properties oformat) 设置转换的输出属性。
abstract void	setOutputProperty(String name, String value) 设置转换中实际的输出属性。
abstract void	setParameter(String name, Object value) 添加一个转换参数。
abstract void	setURIResolver(URIResolver resolver) 设置将用于解析在 document() 中使用的 URI 的对象。
abstract void	transform(Source xmlSource, Result outputTarget) 将 XML Source 转换为 Result。

从类 java.lang.Object 继承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造方法详细信息

Transformer

protected Transformer()

默认构造方法受到有意保护。

方法详细信息

reset

public void reset()

将此 Transformer 重置为其初始配置。

Transformer 被重置为通过 TransformerFactory.newTransformer()、TransformerFactory.newTransformer(Source source) 或 Templates.newTransformer() 创建它时的状态。reset() 的设计目标是允许重用现有 Transformer，以节省与创建新 Transformer 有关的资源。

不保证重置的 Transformer 具有相同的 URIResolver 或 ErrorListener Object，例如 Object.equals(Object obj)。但保证具有功能相同的 URIResolver 和 ErrorListener。

抛出：

UnsupportedOperationException - 当实现不能重写此方法时。

从以下版本开始：

1.5

transform

public abstract void transform(Source xmlSource,
                               Result outputTarget)
                        throws TransformerException

将 XML Source 转换为 Result。当实例化 Transformer 和对 Transformer 实例进行任何修改时，指定的转换行为由 TransformerFactory 的实际设置决定。

空 Source 表示为由 DocumentBuilder.newDocument() 构造的空文档。空 Source 的转换结果取决于转换行为；结果不总为空 Result。

参数：

xmlSource - 要转换的 XML 输入。

outputTarget - 转换 xmlSource 的 Result。

抛出：

TransformerException - 如果转换过程中发生不可恢复的错误。

setParameter

public abstract void setParameter(String name,
                                  Object value)

添加一个转换参数。

以两部分字符串形式传递限定名称，即用花括号括起来的名称空间 URI，后跟本地名称。如果名称中有 null URL，则 String 只包含本地名称。应用程序可以通过测试安全地检查非 null URI，以查看名称的首字符是否为 '{' 字符。

例如，如果 URI 和本地名称是从通过 <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/> 定义的元素获取的，则限定名称将为 "{http://xyz.foo.com/yada/baz.html}foo"。注意，不使用前缀。

参数：

name - 参数名称，它可以以花括号（{}）中的名称空间 URI 开始。

value - 值对象。它可以为任何有效的 Java 对象。处理器负责提供正确的对象 coersion，或只传递在扩展中使用的对象。

抛出：

NullPointerException - 如果值为 null。

getParameter

public abstract Object getParameter(String name)

获取通过 setParameter 显式设置的参数。

此方法不返回默认参数值，默认参数值直到在转换过程中计算了节点上下文后才能确定。

参数：

name - 要获取的 Object

返回：

已通过 setParameter 设置的参数。

clearParameters

public abstract void clearParameters()

清除所有通过 setParameter 设置的参数。

setURIResolver

public abstract void setURIResolver(URIResolver resolver)

设置将用于解析在 document() 中使用的 URI 的对象。

如果解析器参数为 null，则将清除 URIResolver 值，且转换器将不再拥有解析器。

参数：

resolver - 实现 URIResolver 接口的对象，或为 null。

getURIResolver

public abstract URIResolver getURIResolver()

获取将用于解析在 document() 中使用的 URI 的对象。

返回：

实现 URIResolver 接口的对象，或返回 null。

setOutputProperties

public abstract void setOutputProperties(Properties oformat)

设置转换的输出属性。这些属性将重写通过 xsl:output 在 Templates 中设置的属性。

如果此函数的参数为 null，则移除任何以前设置的属性，且值将恢复为 templates 对象中定义的值。

以两部分字符串形式传递限定属性，即用花括号括起来的名称空间 URI，后跟本地名称。如果名称中有 null URL，则 String 只包含本地名称。应用程序可以通过测试安全地检查非 null URI，以查看名称的首字符是否为 '{' 字符。

例如，如果 URI 和本地名称是从通过 <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/> 定义的元素获取的，则限定名称将为 "{http://xyz.foo.com/yada/baz.html}foo"。注意，不使用前缀。

如果任何参数键不能被识别且不是名称空间限定的，则抛出 IllegalArgumentException。

参数：

oformat - 将用于重写在实际转换中任何相同属性的输出属性集。

抛出：

IllegalArgumentException - 当键无法识别且不是限定于名称空间的键时。

另请参见：

OutputKeys, Properties

getOutputProperties

public abstract Properties getOutputProperties()

获取转换的输出属性的副本。

返回的属性应包含由用户设置的属性，以及通过样式表设置的属性，且这些属性将 section 16 of the XSL Transformations (XSLT) W3C Recommendation 指定的默认属性作为“默认值”。由用户或通过样式表特定设置的属性应位于基本 Properties 列表中，而未特定设置的 XSLT 默认属性应位于默认的 Properties 列表中。因此，getOutputProperties().getProperty(String key) 将包含通过 setOutputProperty(java.lang.String, java.lang.String)、setOutputProperties(java.util.Properties) 设置的任何属性，或者在样式表或 默认属性中设置的任何属性，而 getOutputProperties().get(String key) 将只检索通过 setOutputProperty(java.lang.String, java.lang.String)、setOutputProperties(java.util.Properties) 显式设置的属性，或在样式表中显式设置的属性。

注意返回的 Properties 对象的变化将不影响转换器所包含的属性。

如果任何参数键不能被识别且不是名称空间限定的键，则属性将被忽略且不返回。换句话说，行为与 setOutputProperties 无关。

返回：

下一个实际转换中的输出属性集的副本。

另请参见：

OutputKeys, Properties, XSL Transformations (XSLT) Version 1.0

setOutputProperty

public abstract void setOutputProperty(String name,
                                       String value)
                                throws IllegalArgumentException

设置转换中实际的输出属性。

以两部分字符串形式传递限定属性名称，即用花括号括起来的名称空间 URI，后跟本地名称。如果名称中有 null URL，则 String 只包含本地名称。应用程序可以通过测试安全地检查非 null URI，以查看名称的首字符是否为 '{' 字符。

例如，如果 URI 和本地名称是从通过 <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/> 定义的元素获取的，则限定名称将为 "{http://xyz.foo.com/yada/baz.html}foo"。注意，不使用前缀。

传递给 setOutputProperties(java.util.Properties) 的 Properties 对象不会受到调用此方法的影响。

参数：

name - 指定了输出属性名称的非 null String，它可以是名称空间限定的。

value - 输出属性的非 null 字符串值。

抛出：

IllegalArgumentException - 如果不支持属性，且该属性没有限定于某一名称空间。

另请参见：

OutputKeys

getOutputProperty

public abstract String getOutputProperty(String name)
                                  throws IllegalArgumentException

获取对转换器有效的输出属性。

如果已经使用 setOutputProperty(java.lang.String, java.lang.String) 设置了属性，则返回所设置的值。如果在样式表中显式地指定了属性，则返回所指定的值。如果使用默认属性值，即没有使用 setOutputProperty(java.lang.String, java.lang.String) 或在样式表中显式地设置了任何值，则结果将随实现以及输入样式表而改变。

参数：

name - 指定了输出属性名称的非 null String，它可以是名称空间限定的。

返回：

输出属性的字符串值，如果找不到属性，则返回 null。

抛出：

IllegalArgumentException - 如果不支持属性。

另请参见：

OutputKeys

setErrorListener

public abstract void setErrorListener(ErrorListener listener)
                               throws IllegalArgumentException

设置转换的实际错误事件侦听器。

参数：

listener - 新错误侦听器。

抛出：

IllegalArgumentException - 如果侦听器为 null。

getErrorListener

public abstract ErrorListener getErrorListener()

获取转换的实际错误事件处理程序。实现必须提供默认错误侦听器。

返回：

当前错误处理程序，它永远不应为 null。