ナビゲーション・リンクをスキップ
Java(tm) Platform
Standard Edition 8

パッケージ javax.xml.transform

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

参照: 説明

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

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

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

オブジェクトの作成

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

入力と出力の仕様

このAPIは、SourceおよびResultと呼ばれる2つのインタフェース・オブジェクトを定義します。SourceおよびResultオブジェクトをインタフェースに渡すためには、具象クラスを使用する必要があります。StreamSourceおよびStreamResultSAXSourceおよび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つの型の特殊な例外をスローします。TransformerFactoryConfigurationErrorFactoryConfigurationErrorに対応し、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で使用可能である必要があります。

ナビゲーション・リンクをスキップ
Java(tm) Platform
Standard Edition 8

バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2017, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Documentation Redistribution Policyも参照してください。