パッケージ javax.xml.transform

このパッケージは、変換命令の処理、およびソースから結果への変換を実行するためのジェネリック API を定義します。

参照: 説明

インタフェースのサマリー

インタフェース	説明
ErrorListener	カスタマイズされたエラー処理を提供するには、このインタフェースを実装し、setErrorListener メソッドを使用して、Transformer で実装のインスタンスを登録します。
Result	このインタフェースを実装するオブジェクトには、変換結果ツリーを作成するのに必要な情報が含まれています。
Source	このインタフェースを実装するオブジェクトには、ソース入力 (XML ソースまたは変換命令) として動作するのに必要な情報が含まれています。
SourceLocator	このインタフェースは、XML ソースまたは変換命令内で発生したエラーの場所をレポートすることを主な目的としています。
Templates	このインタフェースを実装するオブジェクトは、処理された変換命令の実行時表現です。
URIResolver	このインタフェースを実装するオブジェクトは、document()、xsl:import、または xsl:include で使用される URI を Source オブジェクトに変換するプロセッサで呼び出すことができます。

クラスのサマリー

クラス	説明
OutputKeys	Transformer の出力プロパティーを設定するために、あるいは Transformer または Templates オブジェクトから出力プロパティーを取り出すために使用できる文字列定数を提供します。
Transformer	この abstract クラスのインスタンスは、ソースツリーを結果ツリーに変換することができます。
TransformerFactory	TransformerFactory インスタンスを使用して、Transformer および Templates オブジェクトを作成できます。

例外のサマリー

例外	説明
TransformerConfigurationException	重大な構成エラーを示します。
TransformerException	このクラスは、変換処理中に発生した例外状態を示します。

エラーのサマリー

エラー	説明
TransformerFactoryConfigurationError	変換ファクトリの構成で問題が存在する場合にスローされます。

パッケージ javax.xml.transform の説明

このパッケージは、変換命令の処理、およびソースから結果への変換を実行するためのジェネリック API を定義します。これらのインタフェースは、SAX または DOM 標準に依存しておらず、変換のソースと結果の詳細に関する仮定をできるだけ少なくしています。Source および Result インタフェースを定義してこれを実現します。

ユーザーの具象クラスを定義するために、この API は、ルートレベルにあるインタフェースの特殊化を定義します。これらのインタフェースは、javax.xml.transform.sax、javax.xml.transform.dom、および javax.xml.transform.stream にあります。

オブジェクトの作成

API により、具象 TransformerFactory オブジェクトを static 関数 TransformerFactory.newInstance() から作成できるようになります。

入力と出力の仕様

この API は、Source および Result と呼ばれる 2 つのインタフェースオブジェクトを定義します。Source および Result オブジェクトをインタフェースに渡すためには、具象クラスを使用する必要があります。StreamSource および StreamResult、SAXSource および SAXResult、および DOMSource および DOMResult の各オブジェクトに対して、3 つの具象表現が定義されます。これらのオブジェクトはそれぞれ FEATURE 文字列 (URL 形式) を定義します。この文字列を TransformerFactory.getFeature(java.lang.String) に渡して、指定された型の Source または Result オブジェクトがサポートされているかどうかを確認できます。たとえば、DOMSource および StreamResult がサポートされているかどうかを判定するには、次のテストを行います。

TransformerFactory tfactory = TransformerFactory.newInstance();
if (tfactory.getFeature(DOMSource.FEATURE) && tfactory.getFeature(StreamResult.FEATURE)) {
...
}

修飾名表現

「名前空間」は、XML オブジェクトを扱う際の問題領域を提示します。修飾名は XML マークアップの接頭辞が付いた名前として表示されます。接頭辞自体は識別情報を保持しません。接頭辞は識別情報を保持する URI にコンテキスト依存でマッピングされます。したがって、Java プログラム間で xyz:foo のような修飾名を渡す場合は、xyz を名前空間にマッピングする手段を提供する必要があります。

1 つの解決策は、名前空間 URI と、接頭辞およびローカル名を保持する Qname オブジェクトを作成することです。ただし、たとえばディクショナリオブジェクトのキーとして一意の文字列を使用する場合のように、これが常に最適の解決策であるとはかぎりません。文字列表現がないと、XML ドキュメントのコンテキスト外の名前空間で修飾された識別情報を指定することも困難になります。

Transformer オブジェクトにプロパティーまたはパラメータを設定する場合など、名前空間で修飾された値を変換に渡すために、この仕様では String 型 qname オブジェクトパラメータは 2 部形式の文字列として渡されるように定義されます。つまり、中括弧 ({}) で囲まれた名前空間 URI のあとにローカル名が続きます。qname が null の URI を持つ場合、String オブジェクトにはローカル名だけが含まれます。アプリケーションは、名前の最初の文字が「{」文字であるかどうかを判定して、null でない 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 イベントストリームの場合は、何の影響もありません。

xsl:output 属性の XSLT 仕様に一致する文字列は OutputKeys クラスから参照できます。ほかの文字列も指定できます。変換が出力キーを認識しない場合、キー名が修飾された名前空間でないと、IllegalArgumentException がスローされます。名前空間で修飾された出力キー名は、常に許可されていますが、実装によっては無視される場合があります。

ソースから結果への単純な恒等変換だけが必要な場合、TransformerFactory は引数を指定せずに TransformerFactory.newTransformer() メソッドを提供します。このメソッドは、ソースを結果に効果的にコピーする Transformer を作成します。このメソッドを使用して、SAX イベントからの DOM を作成するか、DOM または SAX イベントから XML または HTML ストリームを作成することができます。

例外とエラーレポート

変換 API は 3 つの型の特殊な例外をスローします。TransformerFactoryConfigurationError は FactoryConfigurationError に対応し、TransformerFactory での構成に問題が存在するとスローされます。通常、このエラーは、javax.xml.transform.TransformerFactory システムプロパティーを使用して指定された変換ファクトリクラスが見つからない、あるいはインスタンス化できない場合にスローされます。

何らかの理由で Transformer を作成できない場合は、TransformerConfigurationException がスローされることがあります。変換命令に構文エラーがある場合、たとえば TransformerFactory.newTransformer(javax.xml.transform.Source) が呼び出された場合は、TransformerConfigurationException がスローされることがあります。

TransformerException は、変換の過程で発生する一般的な例外です。Transformer 例外は別の例外をラップすることができ、その発生時に TransformerException.printStackTrace() メソッドのいずれかが呼び出されると、最新のものから始まるスタックダンプのリストを作成します。Transformer 例外はまた、エラーが発生したソースツリーまたは変換命令内の場所を示す SourceLocator オブジェクトも提供します。TransformerException.getMessageAndLocation() を呼び出して場所の情報を含むエラーメッセージを取得することができ、TransformerException.getLocationAsString() を呼び出して場所の文字列だけを取得することができます。

変換の警告とエラーは、ErrorListener に送られ、その時点でアプリケーションはエラーまたは警告をレポートするよう決定することができるほか、重大でないエラーの Exception をスローするよう決定できます。ErrorListener は、TransformerFactory.setErrorListener(javax.xml.transform.ErrorListener) を介して変換命令の構文エラーに関係するエラーをレポートするように設定するか、Transformer.setErrorListener(javax.xml.transform.ErrorListener) を介して変換時に発生するエラーをレポートするように設定できます。両方のオブジェクトの ErrorListener は、アプリケーションによって設定されるか、プロセッサが提供するデフォルトの実装によって設定されるかにかかわらず、常に有効で、null ではありません。プロセッサが提供するデフォルトの実装では、すべての警告とエラーが System.err にレポートされ、Exception がスローされません。アプリケーションでは警告とエラーの正常な動作を確保するため、ErrorListener を登録して使用することを強くお勧めします。

変換内の URI の解決

この API は、スタイルシート命令内または変換内から参照される URI を呼び出し側アプリケーションで解決する手段を提供します。これは、その 1 つのメソッド、URIResolver.resolve(java.lang.String, java.lang.String) を使用して URIResolver インタフェースを実装するクラスを作成することにより実現でき、このクラスを使用して変換命令、あるいは TransformerFactory.setURIResolver(javax.xml.transform.URIResolver)、または Transformer.setURIResolver(javax.xml.transform.URIResolver) を使用した変換のために URI 解決を設定します。URIResolver.resolve メソッドは 2 つの String 引数をとります。1 つは、スタイルシート命令内にある URI または変換プロセスの一部として構築された URI で、もう 1 つは、絶対 URI が必要な場合に最初の引数が絶対となるベース URI です。返された Source オブジェクトは、その実装された機能で指定されているように、Transformer で使用可能である必要があります。