javax.xml.transform

クラス TransformerFactory

java.lang.Object

javax.xml.transform.TransformerFactory

直系の既知のサブクラス:

SAXTransformerFactory

public abstract class TransformerFactory
extends Object

TransformerFactory インスタンスを使用して、Transformer および Templates オブジェクトを作成できます。

どのファクトリ実装を作成するかを決めるシステムプロパティーの名前は "javax.xml.transform.TransformerFactory" です。このプロパティーは、TransformerFactory abstract クラスの具象サブクラスを命名します。このプロパティーが定義されていない場合は、プラットフォームのデフォルトが使用されます。

導入されたバージョン:

1.5

コンストラクタのサマリー

コンストラクタ

修飾子	コンストラクタと説明
protected	TransformerFactory() デフォルトのコンストラクタが意図的に保護されます。

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
abstract Source	getAssociatedStylesheet(Source source, String media, String title, String charset) 「The xml-stylesheet processing instruction」から、指定された基準に一致する XML Source ドキュメントに関連付けられているスタイルシート仕様を取得します。
abstract Object	getAttribute(String name) ユーザーがベースとなる実装の特定の属性を取り出すことができるようにします。
abstract ErrorListener	getErrorListener() TransformerFactory のエラーイベントハンドラを取得します。
abstract boolean	getFeature(String name) 機能の値を検索します。
abstract URIResolver	getURIResolver() document()、xsl:import、または xsl:include で使用される URI を解決するために変換時にデフォルトで使用されるオブジェクトを取得します。
static TransformerFactory	newInstance() TransformerFactory の新しいインスタンスを取得します。
static TransformerFactory	newInstance(String factoryClassName, ClassLoader classLoader) ファクトリクラス名から TransformerFactory の新しいインスタンスを取得します。
abstract Templates	newTemplates(Source source) Source を処理して、ソースのコンパイル表現である Templates オブジェクトにします。
abstract Transformer	newTransformer() Source の Result へのコピーを実行する新しい Transformer を作成します。
abstract Transformer	newTransformer(Source source) Source を Transformer Object に処理します。
abstract void	setAttribute(String name, Object value) ユーザーがベースとなる実装に特定の属性を設定できるようにします。
abstract void	setErrorListener(ErrorListener listener) TransformerFactory のエラーイベントリスナーを設定します。TransformerFactory は、変換自体のためではなく、変換命令を処理するために使用されます。
abstract void	setFeature(String name, boolean value) このファクトリによって生成された TransformerFactory および Transformer または Template の機能を設定します。
abstract void	setURIResolver(URIResolver resolver) document()、xsl:import、または xsl:include で使用される URI を解決するために変換時にデフォルトで使用されるオブジェクトを設定します。

クラス java.lang.Object から継承されたメソッド

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

コンストラクタの詳細

TransformerFactory

protected TransformerFactory()

デフォルトのコンストラクタが意図的に保護されます。

メソッドの詳細

newInstance

public static TransformerFactory newInstance()
                                      throws TransformerFactoryConfigurationError

TransformerFactory の新しいインスタンスを取得します。この static メソッドは新しいファクトリインスタンスを作成します。このメソッドは次の順序のルックアップ手順で、ロードする TransformerFactory 実装クラスを判定します。

• javax.xml.transform.TransformerFactory システムプロパティーを使用する。
• JRE ディレクトリ内のプロパティーファイル lib/jaxp.properties を使用する。この構成ファイルは標準の java.util.Properties 形式であり、上記のように定義されたシステムプロパティーであるキーを持つ実装クラスの完全指定名を含む。 jaxp.properties ファイルは JAXP 実装によって 1 回だけ読み込まれ、その値がその後の使用のためキャッシュされる。最初の読み込み時にファイルが存在しないと、そのあとにその存在がチェックされることはない。最初に読み込まれたあと、jaxp.properties のプロパティーの値を変更することはできない。
• 可能であれば、JAR 仕様で詳細に説明されているサービス API を使用して、クラス名を判定する。Services API は、実行時に使用できる jar 内の META-INF/services/javax.xml.transform.TransformerFactory ファイルからクラス名を検索する。
• デフォルトの TransformerFactory インスタンスをプラットフォームとする。

アプリケーションが TransformerFactory への参照を取得すると、ファクトリを使用して transformer のインスタンスを構成および取得することができます。

戻り値:

新しい TransformerFactory インスタンス。null は不可。

例外:

TransformerFactoryConfigurationError - 実装が使用できないかインスタンス化できない場合、スローされる。

newInstance

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

ファクトリクラス名から TransformerFactory の新しいインスタンスを取得します。この関数は、クラスパスに複数のプロバイダがある場合に便利です。どのプロバイダがロードされるかを指定できるため、アプリケーションをさらに制御できます。

アプリケーションが TransformerFactory への参照を取得すると、ファクトリを使用して transformer のインスタンスを構成および取得することができます。

トラブルシューティングのヒント

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 ドキュメントです。この Transformer は並行して動作する複数の Thread で使用することはできません。異なる TransformerFactories は、異なる Thread によって並行して使用できます。

パラメータ:

source - Transformer の作成に使用される XSLT ドキュメントの Source 。XML Source の例には、DOMSource、SAXSource、および StreamSource が含まれます。

戻り値:

1 つの Thread で変換を実行するために使用される Transformer オブジェクト。null は不可。

例外:

TransformerConfigurationException - Source の構文解析時にエラーが発生するか、Transformer インスタンスを作成できない場合にスローされる。

関連項目:

XSL Transformations (XSLT) Version 1.0

newTransformer

public abstract Transformer newTransformer()
                                    throws TransformerConfigurationException

Source の Result へのコピーを実行する新しい Transformer (恒等変換) を作成します。

戻り値:

1 つのスレッドで変換を実行するために使用される 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

「The xml-stylesheet processing instruction」から、指定された基準に一致する XML Source ドキュメントに関連付けられているスタイルシート仕様を取得します。いくつかのスタイルシートを返すことができます。その場合、それらのスタイルシートは、1 つのスタイルシート内のインポートまたはカスケードのリストであるかのように適用されます。

パラメータ:

source - XML ソースドキュメント。

media - 一致するメディア属性。null の場合があり、その場合、設定されているテンプレートが使用される (つまり alternate = no)。

title - 一致するタイトル属性の値。null も可。

charset - 一致する文字セット属性の値。null も可。

戻り値:

TransformerFactory に渡すのに適した Source Object。

例外:

TransformerConfigurationException - source の構文解析時にエラーが発生した場合 Exception がスローされる。

関連項目:

Associating Style Sheets with XML documents Version 1.0

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 がスローされます。

JAXP 1.5 またはそれ以降を実装する実装はすべて、XMLConstants.ACCESS_EXTERNAL_DTD および XMLConstants.ACCESS_EXTERNAL_STYLESHEET プロパティーをサポートしている必要があります。

• ソースファイル内の外部 DTD へのアクセスが、XMLConstants.ACCESS_EXTERNAL_DTD プロパティーで指定されたプロトコルに制限されます。このプロパティーの制限が原因で変換中にアクセスが拒否された場合は、Transformer.transform(Source, Result) によって TransformerException がスローされます。

  スタイルシート内の外部 DTD へのアクセスが、XMLConstants.ACCESS_EXTERNAL_DTD プロパティーで指定されたプロトコルに制限されます。このプロパティーの制限が原因で新しいトランスフォーマの作成中にアクセスが拒否された場合は、newTransformer(Source) メソッドによって TransformerConfigurationException がスローされます。

  スタイルシートの処理命令、Import および Include 要素によって設定された外部参照へのアクセスが、XMLConstants.ACCESS_EXTERNAL_STYLESHEET プロパティーで指定されたプロトコルに制限されます。このプロパティーの制限が原因で新しいトランスフォーマの作成中にアクセスが拒否された場合は、newTransformer(Source) メソッドによって TransformerConfigurationException がスローされます。

  XSLT ドキュメント関数による外部ドキュメントへのアクセスが、そのプロパティーで指定されたプロトコルに制限されます。このプロパティーの制限が原因で変換中にアクセスが拒否された場合は、Transformer.transform(Source, Result) メソッドによって TransformerException がスローされます。

パラメータ:

name - 属性の名前。

value - 属性の値。

例外:

IllegalArgumentException - 実装が属性を認識しない場合。

getAttribute

public abstract Object getAttribute(String name)

ユーザーがベースとなる実装の特定の属性を取り出すことができるようにします。ベースとなる実装が属性を認識しない場合に IllegalArgumentException がスローされます。

パラメータ:

name - 属性の名前。

戻り値:

属性の値。

例外:

IllegalArgumentException - 実装が属性を認識しない場合。

setErrorListener

public abstract void setErrorListener(ErrorListener listener)

TransformerFactory のエラーイベントリスナーを設定します。TransformerFactory は、変換自体のためではなく、変換命令を処理するために使用されます。ErrorListener リスナーが null の場合は IllegalArgumentException がスローされます。

パラメータ:

listener - 新しいエラーリスナー。

例外:

IllegalArgumentException - listener が null の場合

getErrorListener

public abstract ErrorListener getErrorListener()

TransformerFactory のエラーイベントハンドラを取得します。

戻り値:

現在のエラーハンドラ。null は不可。