XSLT 変換の実行
XSLT (Extensible Stylesheet Language Transformations) は XML ベースの言語であり、これを使用して指定の XML ドキュメントを別の XML ドキュメントまたは人間が読める別の形式のドキュメントに変換する方法を記述します。%XML.XSLT および %XML.XSLT2 パッケージ内のクラスを使用すると、XSLT 1.0 および 2.0 の変換を実行できます。
Note:
使用する任意の XML ドキュメントの XML 宣言にはそのドキュメントの文字エンコードを明記する必要があり、明記しておけば、ドキュメントは宣言どおりにエンコードされるようになります。文字エンコードが宣言されていない場合は、"入出力の文字エンコード" で説明されている既定値が使用されます。これらの既定値が正しくない場合は、XML 宣言を修正して、実際に使用されている文字セットを指定するようにします。
InterSystems IRIS における XSLT 変換の実行の概要
InterSystems IRIS は、それぞれ独自の API を備えた以下の 2 つの XSLT プロセッサを提供します。
-
Xalan プロセッサは XSLT 1.0 をサポートします。%XML.XSLT パッケージは、このプロセッサの API を提供します。
-
Saxon プロセッサは XSLT 2.0 をサポートします。%XML.XSLT2 パッケージは、このプロセッサの API を提供します。
%XML.XSLT2 の API は、XSLT 2.0 ゲートウェイへの接続を介して Saxon に要求を送信します。ゲートウェイは複数の接続を可能にします。つまり、それぞれ独自の一連のコンパイル済みスタイル・シートを備えた 2 つの異なる InterSystems IRIS プロセスをゲートウェイに接続して、複数の変換要求を同時に送信したりすることができます。
Saxon プロセッサでは、コンパイル済みスタイル・シートと isc:evaluate キャッシュは接続固有です。つまり、独自の接続を管理して、いずれかの機能を利用する必要があります。接続を開いてコンパイル済みスタイル・シートを作成した場合、または isc:evaluate キャッシュに生成する変換を評価した場合、その接続で評価されるその他の変換は、コンパイル済みスタイル・シートおよび isc:evaluate キャッシュ・エントリにアクセスできるようになります。新しい接続を開いた場合、その他の接続 (およびそれらのコンパイル済みスタイル・シートやキャッシュ) は無視されます。
2 つのプロセッサの API は類似していますが、%XML.XSLT2 のメソッドでは追加の引数を用いて、使用するゲートウェイ接続を指定します。
XSLT 変換を実行するには、以下の手順に従います。
-
Saxon プロセッサを使用する場合、次のセクションで説明するように、XSLT ゲートウェイ・サーバを構成します。または、既定の構成を使用します。
Xalan プロセッサを使用する場合、ゲートウェイは必要ありません。
必要に応じて、システムは自動的にゲートウェイを起動します。ゲートウェイは手動で起動することもできます。
-
Saxon プロセッサを使用する場合、必要に応じて、XSLT ゲートウェイへの単一接続を示す %Net.Remote.GatewayOpens in a new tab のインスタンスを作成します。
Saxon プロセッサを使用する際、コンパイル済みスタイル・シートや isc:evaluate キャッシュを利用するには、この手順を実行する必要があります。
-
必要に応じて、コンパイル済みスタイル・シートを作成して、メモリにロードします。"コンパイル済みスタイル・シートの作成" を参照してください。Saxon プロセッサを使用する場合、コンパイル済みスタイル・シートの作成時に gateway 引数を必ず指定してください。
この手順は同じスタイル・シートを繰り返して使用する場合に役立ちます。ただし、この手順ではメモリも消費します。コンパイル済みスタイル・シートは不要になったら必ず削除してください。
-
該当する API の変換メソッドのいずれかを呼び出します。Saxon プロセッサを使用する場合、変換メソッドを呼び出す際、必要に応じて gateway 引数を指定します。
"XSLT 変換の実行" を参照してください。
-
必要に応じて、他の変換メソッドを呼び出します。Saxon プロセッサを使用する場合、変換メソッドを呼び出す際、必要に応じて gateway 引数を指定します。これにより、同じ接続を使用して他の変換を評価できます。この変換は、この接続に関連付けられているすべてのコンパイル済みスタイル・シートおよび isc:evaluate キャッシュ・エントリにアクセスできるようになります。新しい接続を開いた場合、その他の接続 (およびそれらのコンパイル済みスタイル・シートやキャッシュ) は無視されます。
スタジオには、XSLT 変換のテストに使用できるウィザードも用意されています。
XSLT 2.0 ゲートウェイの構成、起動、および停止
(XSLT 2.0 変換を実行するために) Saxon プロセッサを使用する場合、InterSystems IRIS は XSLT 2.0 ゲートウェイを使用します (このゲートウェイは Java を使用します)。ゲートウェイを構成するには、以下の手順を実行します。
-
管理ポータルで、[システム管理]→[構成]→[接続性]→[XSLT 2.0 ゲートウェイ・サーバ] を選択します。
-
[移動] を選択します。
システムにより、XSLT ゲートウェイ・サーバ・ページが表示されます。
左側の領域に構成の詳細、右側の領域に最近のアクティビティが表示されます。
-
左側の領域では、必要に応じて以下の設定を指定できます。
-
ポート番号 — XSLT 2.0 ゲートウェイに専用の TCP ポート番号。このポート番号は、サーバ上のその他のローカル TCP ポートと競合してはいけません。
既定値は、InterSystems IRIS のスーパーサーバ・ポート番号に 3000 を加えた値になります。この数値が 65535 を超える場合は、システムにより 54773 が使用されます。
-
Java バージョン — 使用する Java のバージョン。
-
ログファイル — ログ・ファイルのファイル・パス名。この設定を省略すると、ロギングは実行されなくなります。ファイル名を指定してディレクトリを省略すると、ログ・ファイルはシステム管理者のディレクトリに書き込まれます。
-
Javaホームディレクトリ — Java bin ディレクトリを格納しているディレクトリのパス。これは、サーバ上に既定の Java が存在しない場合や、別の Java を使用する場合に指定します。
既定の Java を確認するには、サーバ上のシェルで以下のコマンドを実行します。
java -version
-
JVM の引数 — Java 仮想マシンで使用する追加の引数。
この領域には、JAVA_HOME 環境変数の現在の値も表示されます。
ゲートウェイの実行中には、これらの値が編集できなくなることに注意してください。
-
変更が完了したら、[保存] を選択して変更内容を保存します。または、[リセット] を選択して、変更内容を破棄します。
-
必要に応じて、[テスト] を選択し、変更内容をテストします。
このページでは、次の操作も実行できます。
-
ゲートウェイの開始。これを行うには、右側の領域で [開始] を選択します。
InterSystems IRIS は必要に応じて自動的にゲートウェイを開始することに注意してください。ゲートウェイを手動で開始する必要はありません。
-
ゲートウェイの停止。これを行うには、右側の領域で [停止] を選択します。
XSLT 2.0 ゲートウェイ・サーバ接続のトラブルシューティング
XSLT 2.0 ゲートウェイが開いている間に、InterSystems IRIS とゲートウェイ・サーバの間の接続が無効になることがあります。例えば、ネットワーク・エラーが発生した場合や、InterSystems IRIS がゲートウェイ・サーバに接続した後にこのサーバが再起動された場合、接続が正しく閉じられないことがあります。その結果、エラーが発生する場合があります。
XSLT ゲートウェイ接続オブジェクトOpens in a new tabの %LostConnectionCleanup() メソッドと %Reconnect メソッドを連続して呼び出すことによって、InterSystems IRIS のゲートウェイ・サーバへの再接続を試みることができます。詳細は、XSLT ゲートウェイ接続オブジェクトの継承元のクラスである "%Net.Remote.GatewayOpens in a new tabOpens in a new tab" を参照してください。
切断時におけるゲートウェイ・サーバへの再接続プロセスを自動化する場合は、ゲートウェイ接続オブジェクトの AttemptReconnect プロパティを true に設定します。
例
ここでは、以下のコードを使用する 2 つの変換を紹介します (ただし、入力ファイルは異なります)。
Set in="c:\0test\xslt-example-input.xml"
Set xsl="c:\0test\xslt-example-stylesheet.xsl"
Set out="c:\0test\xslt-example-output.xml"
Set tSC=##class(%XML.XSLT.Transformer).TransformFile(in,xsl,.out)
Write tSC
例 1 : 単純な置換
この例では、以下の入力 XML から始めます。
<?xml version="1.0" ?>
<s1 title="s1 title attr">
<s2 title="s2 title attr">
<s3 title="s3 title attr">Content</s3>
</s2>
</s1>
また、以下のスタイル・シートを使用します。
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="xml" indent="yes"/>
<xsl:template match="//@* | //node()">
<xsl:copy>
<xsl:apply-templates select="@*"/>
<xsl:apply-templates select="node()"/>
</xsl:copy>
</xsl:template>
<xsl:template match="/s1/s2/s3">
<xsl:apply-templates select="@*"/>
<xsl:copy>
Content Replaced
</xsl:copy>
</xsl:template>
</xsl:stylesheet>
この場合、出力ファイルは以下のようになります。
<?xml version="1.0" encoding="UTF-8"?>
<s1 title="s1 title attr">
<s2 title="s2 title attr">
<s3>
Content Replaced
</s3>
</s2>
</s1>
エラー処理のカスタマイズ
エラーが発生すると、XSLT プロセッサ (Xalan または Saxon) は現在のエラー・ハンドラの error() メソッドを実行し、引数としてメッセージをそのメソッドに送信します。同様に、致命的なエラーや警告が発生すると、XSLT プロセッサは fatalError() メソッドまたは warning() メソッドを必要に応じて実行します。
これら 3 つのメソッドすべての既定の動作は、現在のデバイスへのメッセージの書き込みです。
エラー処理をカスタマイズするには、以下の手順を実行します。
-
Xalan または Saxon プロセッサで、%XML.XSLT.ErrorHandlerOpens in a new tab のサブクラスを作成します。このサブクラスで、必要に応じて error() メソッド、fatalError() メソッド、および warning() メソッドを実装します。
これらのメソッドはそれぞれ、XSLT プロセッサから送信されたメッセージを含む文字列である単独の引数を受け入れます。
これらのメソッドは値を返しません。
-
次に、以下の操作を行います。
-
スタイル・シートのコンパイル中にこのエラー・ハンドラを使用するには、サブクラスのインスタンスを作成し、スタイル・シートのコンパイル時に引数リストでそれを使用します。"コンパイル済みスタイル・シートの作成" を参照してください。
-
XSLT 変換の実行中にこのエラー・ハンドラを使用するには、サブクラスのインスタンスを作成し、使用する変換メソッドの引数リストでそれを使用します。"XSLT 変換の実行" を参照してください。
スタイル・シートで使用するためのパラメータの指定
スタイル・シートで使用するためにパラメータを指定するには:
-
%ArrayOfDataTypesOpens in a new tab のインスタンスを作成します。
-
このインスタンスの SetAt() メソッドを呼び出して、このインスタンスのパラメータとその値を追加します。SetAt() では、最初の引数をパラメータ値として指定し、2 番目の引数をパラメータ名として指定します。
必要なだけパラメータを追加します。
例 :
Set tParameters=##class(%ArrayOfDataTypes).%New()
Set tSC=tParameters.SetAt(1,"myparameter")
Set tSC=tParameters.SetAt(2,"anotherparameter")
-
このインスタンスを変換メソッドの pParms 引数として使用します。
%ArrayOfDataTypesOpens in a new tab の代わりに、InterSystems IRIS 多次元配列を使用できます。この多次元配列は、以下の構造と値を持つ任意の数のノードを持つことができます。
ノード |
値 |
arrayname("parameter_name") |
parameter_name で指定されたパラメータの値 |
XSLT 拡張関数の追加と使用
InterSystems IRIS で XSLT 拡張関数を作成し、以下のようにスタイル・シート内でそれらを使用することができます。
-
XSLT 2.0 (Saxon プロセッサ) の場合、ネームスペース com.intersystems.xsltgateway.XSLTGateway の evaluate 関数またはネームスペース http://extension-functions.intersystems.com の evaluate 関数を使用できます
-
XSLT 1.0 (Xalan プロセッサ) の場合、ネームスペース http://extension-functions.intersystems.com の evaluate 関数のみを使用できます
既定では (および一例として)、後者の関数は受け取る文字を反転します。ただし、その他の動作が実装されるため、この既定の動作は一般的には使用されません。複数の個別の関数をシミュレートするには、セレクタを最初の引数として渡し、その値を使用して実行する処理を選択するスイッチを実装します。
内部的には、evaluate 関数はメソッド (evaluate()) として XSLT コールバック・ハンドラに実装されます。
XSLT 拡張関数を追加および使用するには、以下の手順を実行します。
-
Xalan または Saxon プロセッサで、%XML.XSLT.CallbackHandlerOpens in a new tab のサブクラスを作成します。このサブクラスで、必要に応じて evaluate() メソッドを実装します。この後のサブセクションを参照してください。
-
スタイル・シートで、evaluate 関数が属するネームスペースを宣言し、必要に応じて evaluate 関数を使用します。この後のサブセクションを参照してください。
-
XSLT 変換の実行中に、サブクラスのインスタンスを作成し、使用する変換メソッドの引数リストでそれを使用します。"XSLT 変換の実行" を参照してください。
evaluate() メソッドの実装
内部的には、XSLT プロセッサを呼び出すコードは、任意の数の位置を示す引数を現在のコールバック・ハンドラの evaluate() メソッドに渡すことができます。コールバック・ハンドラは以下の構造を持つ配列としてそれらを受け取ります。
ノード |
値 |
Args |
引数の数 |
Args(index) |
位置 index にある引数の値 |
このメソッドは単独の返り値を持ちます。返り値は以下のいずれかになります。
スタイル・シートでの evaluate の使用
XSLT で XSLT 拡張関数を使用するには、XSLT スタイル・シートで拡張関数のネームスペースを宣言する必要があります。前述のとおり、インターシステムズの evaluate 関数では、このネームスペースは http://extension-functions.intersystems.com または com.intersystems.xsltgateway.XSLTGateway です。
以下の例は、evaluate を使用するスタイル・シートを示します。
<?xml version="1.0"?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
xmlns:isc="http://extension-functions.intersystems.com">
<xsl:output method="xml" indent="yes"/>
<xsl:template match="//@* | //node()">
<xsl:copy>
<xsl:apply-templates select="@*"/>
<xsl:apply-templates select="node()"/>
</xsl:copy>
</xsl:template>
<xsl:template match="/s1/s2/s3">
<xsl:apply-templates select="@*"/>
<xsl:choose>
<xsl:when test="function-available('isc:evaluate')">
<xsl:copy>
<xsl:value-of select="isc:evaluate(.)" disable-output-escaping="yes"/>
</xsl:copy>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="."/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
</xsl:stylesheet>
この例の詳細を確認するには、%XML.XSLT.TransformerOpens in a new tab の Example3() メソッドのソース・コードを参照してください。
isc:evaluate キャッシュを使用した作業
XSLT 2.0 ゲートウェイは、isc:evaluate キャッシュに evaluate 関数の呼び出しをキャッシュします。キャッシュの既定の最大サイズは 1000 項目ですが、このサイズを異なる値に設定できます。また、キャッシュをクリアしたり、キャッシュをダンプしたり、以下の形式で %ListOpens in a new tab からキャッシュに自動生成したりすることができます。
-
キャッシュ・エントリの総数
-
各エントリについて :
-
evaluate 引数の総数
-
すべての evaluate 引数
-
evaluate 値
キャッシュには、キャッシュできる関数名のフィルタ・リストも含まれます。以下のことに注意してください。
フィルタ・リストに関数名を追加しても、evaluate キャッシュのサイズは制限されません。同じ関数を多数呼び出す場合がありますが、異なる引数と返り値になることがあります。関数名と引数の各組合せは、evaluate キャッシュでは異なるエントリになります。
%XML.XSLT2.TransformerOpens in a new tab クラスからメソッドを使用することで、evaluate キャッシュを操作できます。詳細は、クラスリファレンスを参照してください。
XSL 変換ウィザードの使用
スタジオで提供されている XSLT 変換を実行するウィザードは、スタイル・シートやカスタム XSLT 拡張関数を短時間でテストしたい場合に便利です。このウィザードを使用する手順は次のとおりです。
-
[ツール]→[アドイン]→[XSLT スキーマ・ウィザード] を選択します。
-
以下の必須情報を指定します。
-
[XMLファイル] で、[参照] を選択して、変換する XML ファイルを選択します。
-
[XSLファイル] で、[参照] を選択して、使用する XSL スタイル・シートを選択します。
-
[レンダリング] で、[テキスト] または [XML] を選択して、変換の表示方法を制御します。
-
この変換で使用する %XML.XSLT.CallbackHandlerOpens in a new tab のサブクラスを作成済みの場合は、以下の情報を指定します。
"XSLT 拡張関数の追加と使用" を参照してください。
-
[完了] を選択します。
ダイアログ・ボックスの下部に、変換後のファイルが表示されます。この領域からコピーして貼り付けることができます。
-
このダイアログ・ボックスを閉じるには、[キャンセル] を選択します。