TransformerFactory(示例,出错代码)

javax.xml.transform
类 TransformerFactory

java.lang.Object  javax.xml.transform.TransformerFactory

直接已知子类：

SAXTransformerFactory

---

public abstract class TransformerFactory
extends Object

TransformerFactory 实例可用于创建 Transformer 和 Templates 对象。

确定要创建的哪一个 Factory 实现被命名为 "javax.xml.transform.TransformerFactory" 的系统属性。此属性命名了 TransformerFactory 抽象类的一个具体子类。如果未定义此属性，则使用平台默认的属性。

newInstance

public static TransformerFactory newInstance()                                      throws TransformerFactoryConfigurationError

获取 TransformerFactory 的新实例。此静态方法创建新的工厂实例。此方法使用以下顺序的查找程序来确定要加载的 TransformerFactory 实现类：

• 使用 javax.xml.transform.TransformerFactory 系统属性。
• 使用 JRE 文件夹中的属性文件 "lib/jaxp.properties"。此配置文件格式为标准的 java.util.Properties 且包含实现类的完全限定名，其中实现类的键是上述定义的系统属性。 JAXP 实现只读取一次 jaxp.properties 文件，然后缓存其值供以后使用。如果首次尝试读取文件时，文件不存在，则不会再次尝试检查该文件是否存在。首次读取 jaxp.properties 后，其中的属性值不能再更改。
• 如果 Services API（在 JAR 规范中进行了详细描述）可用，可以使用它来确定类名称。Services API 将查找在运行时可用的 jar 文件中 META-INF/services/javax.xml.transform.TransformerFactory 中的类名称。
• 平台默认的 TransformerFactory 实例。

在应用程序已获取对 TransformerFactory 的引用后，它可以使用工厂来配置和获取转换器实例。

返回：

新的 TransformerFactory 实例，永远不能为 null。

抛出：

TransformerFactoryConfigurationError - 如果实现不可用或不能被实例化。

---

newInstance

public static TransformerFactory newInstance(String factoryClassName,                                             ClassLoader classLoader)                                      throws TransformerFactoryConfigurationError

根据类名称获得一个新 TransformerFactory 实例。当类路径中有多个提供者时此功能很有用。它给了应用程序更多的控制权，因为它能指定应该加载哪个提供者。

在应用程序已获取对 TransformerFactory 的引用后，它可以使用工厂来配置和获取转换器实例。

疑难解答提示

设置 jaxp.debug 系统属性将导致此方法将许多调试消息打印到 System.err，以说明其执行的操作以及在何处查找这些操作。

如有问题，请尝试：

 java -Djaxp.debug=1 YourProgram .... 

参数：

factoryClassName - 完全限定工厂类名称，提供 javax.xml.transform.TransformerFactory 的实现。

classLoader - 用来加载工厂类的 ClassLoader。如果为 null，则使用当前 Thread 的上下文 classLoader 来加载工厂类。

返回：

新 TransformerFactory 实例，永远不能为 null。

抛出：

TransformerFactoryConfigurationError - 如果 factoryClassName 为 null，或者不能加载或实例化工厂类。

从以下版本开始：

1.6

另请参见：

newInstance()

---

newTransformer

public abstract Transformer newTransformer(Source source)                                    throws TransformerConfigurationException

将 Source 处理为 Transformer Object。Source 是遵守 XSL Transformations (XSLT) Version 1.0 的 XSLT 文档。必须注意的是，在多个 Thread 并发运行中不能使用此Transformer。不同 Thread 可以并发使用不同的 TransformerFactories。

参数：

用于创建 - Transformer 的 XSLT 文档的源 Source。XML Source 的示例包括 DOMSource、SAXSource 和 StreamSource。

返回：

可用于在单个 Thread 中执行转换的 Transformer 对象，永远不能返回 null。

抛出：

TransformerConfigurationException - 如果当解析 Source 时发生错误，或不能创建 Transformer 实例。

另请参见：

XSL Transformations (XSLT) Version 1.0

---

newTransformer

public abstract Transformer newTransformer()                                    throws TransformerConfigurationException

创建执行从 Source 到 Result 的复制的新 Transformer。即 "identity transform"。

返回：

可用于在单个进程中执行转换的 Transformer 对象，永远不能返回 null。

抛出：

TransformerConfigurationException - 当不能创建 Transformer 实例时。

---

newTemplates

public abstract Templates newTemplates(Source source)                                throws TransformerConfigurationException

将 Source 处理为 Templates 对象，后者是源的编译后表示形式。然后此 Templates 对象可由多个线程并发使用。创建 Templates 对象允许 TransformerFactory 执行转换指令的详细性能优化，而不影响运行时转换。

参数：

source - 保持 URL、输入流等的对象。

返回：

可用于转换目的的 Templates 对象，永远不能返回 null。

抛出：

TransformerConfigurationException - 当对构造 Templates 对象进行解析失败时。

---

getAssociatedStylesheet

public abstract Source getAssociatedStylesheet(Source source,                                               String media,                                               String title,                                               String charset)                                        throws TransformerConfigurationException

通过与给定标准匹配的 xml 样式表的处理指令 获取与 XML Source 文档关联的样式表规范（或多个规范）。注意，可能返回几个样式表，在这种情况下它们作为导入列表或单个样式表中的层叠列表来使用。

参数：

source - XML 源文档。

media - 要匹配的介质属性。可以为 null，此时将使用首选的 template（即 alternate = no）。

title - 要匹配的标题属性值。可以为 null。

charset - 要匹配的字符集属性值。可以为 null。

返回：

适合传递给 TransformerFactory 的 Source Object。

抛出：

TransformerConfigurationException - 如果 source 的解析过程中发生错误，则抛出 Exception。

另请参见：

与 1.0 版本的 XML 文档关联的样式表

---

setURIResolver

public abstract void setURIResolver(URIResolver resolver)

设置在转换过程中默认用于解析 document()、xsl:import 或 xsl:include 中所使用的 URI 的对象。

参数：

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

---

getURIResolver

public abstract URIResolver getURIResolver()

获取在转换过程中默认用于解析 document()、xsl:import 或 xsl:include 中所使用的 URI 的对象。

返回：

通过 setURIResolver 设置的 URIResolver。

---

setFeature

public abstract void setFeature(String name,                                boolean value)                         throws TransformerConfigurationException

设置通过此工厂创建的此 TransformerFactory 和 Transformer 或 Template 的功能。

功能名称是完全限定的 URI。实现可以定义它们自己的功能。如果它创建的此 TransformerFactory 或 Transformer 或 Template 不支持该功能，则抛出 TransformerConfigurationException。TransformerFactory 可以公开功能值，但不能更改其状态。

所有实现必须支持 XMLConstants.FEATURE_SECURE_PROCESSING 功能。当功能为以下情况时：

• true: 实现将限制 XML 处理遵守实现限制，并且实现方式为实现所定义的安全方式。示例包括解析用户定义的样式表和函数。如果出于安全原因使 XML 处理受到限制，则将通过对注册的 ErrorListener.fatalError(TransformerException exception) 的调用来报告此情况。参见 setErrorListener(ErrorListener listener)。
• false: 实现将根据 XML 规范来处理 XML，而不管可能的实现限制。

参数：

name - 功能名称。

value - 功能状态为 true 或 false。

抛出：

TransformerConfigurationException - 如果它创建的此 TransformerFactory 或 Transformer 或 Template 不支持此功能。

NullPointerException - 如果 name 参数为 null。

---

getFeature

public abstract boolean getFeature(String name)

查找功能值。

功能名称为完全限定的 URI。实现可以定义其自己的功能。如果其创建的 TransformerFactory 或 Transformer 或 Template 不支持该功能，则返回false。TransformerFactory 可以公开功能值，但不能更改其状态。

参数：

name - 功能名称。

返回：

功能的当前状态，true 或 false。

抛出：

NullPointerException - 如果 name 参数为 null。

---

setAttribute

public abstract void setAttribute(String name,                                  Object value)

允许用户设置底层实现上的指定属性。此上下文中的属性定义为实现所提供的一个选项。如果底层实现不识别该属性，则抛出 IllegalArgumentException。

参数：

name - 属性名称。

value - 属性值。

抛出：

IllegalArgumentException - 当实现不能识别属性时。

---

getAttribute

public abstract Object getAttribute(String name)

允许用户在底层实现上检索指定属性。如果底层实现不识别该属性，则抛出 IllegalArgumentException。

参数：

name - 属性名称。

value - 属性值。

抛出：

IllegalArgumentException - 当实现不能识别属性时。

---

setErrorListener

public abstract void setErrorListener(ErrorListener listener)

设置此 TransformerFactory 的错误事件侦听器，它将用于转换指令的处理，而不用于转换本身。如果 ErrorListener 侦听器为 null，则抛出 IllegalArgumentException。

参数：

listener - 新错误侦听器。

抛出：

IllegalArgumentException - 当 listener 为 null 时。

---

getErrorListener

public abstract ErrorListener getErrorListener()

获取 TransformerFactory 的错误事件处理程序。

返回：

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