compact3

パッケージ 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で使用可能である必要があります。