| Oracle® Fusion Middleware Oracle Service Busでのサービスの開発 12c (12.2.1) E69914-01 |
|
 前 |
 次 |
この付録では、Service Busで相互参照とドメイン値マップを操作するためのXPath拡張関数について説明します。また、ユーザー定義のXPath拡張関数の作成方法についても説明します。オラクルでは、Service BusおよびXPath標準に組み込まれた機能を使用する、新規関数を追加するためのXPath関数を提供しています。
この付録の内容は次のとおりです。
相互参照を使用して、あるアプリケーション内のエンティティの値を、他のアプリケーションの同等の値に動的にマップできます。これは、アプリケーション内のオブジェクトの情報を更新するとき、そしてその情報を他のアプリケーションの同一オブジェクトに伝播する必要がある場合に役立ちます。各アプリケーションは、オブジェクトの識別に独自の方法を使用できます。
相互参照はルックアップ表に格納され、相互参照XPath関数を使用して、表内のデータをモニターおよび管理できます。相互参照マッピング表のデータを追加、更新およびルックアップするには、これらの関数を使用します。グローバル・トランザクションは、これらの関数コール時に使用可能である必要があります。トランザクションが使用できない場合、新しいトランザクションが開始されます。
注意:
相互参照関数のほとんどは、Service Bus相互参照リソースの場所と名前を引数として取ります。Service Busでは、Oracle Metadata Services (MDS)リポジトリのリソースへの直接参照はサポートしていません。
相互参照の詳細は、『Oracle SOA SuiteでのSOAアプリケーションの開発』の相互参照の操作に関する項を参照してください。Service Busの相互参照の詳細は、「相互参照でのデータのマッピング」を参照してください。
この関数は、指定の相互参照表、相互参照列および値について、移入されたすべての列をルックアップします。ノードセット(各ノードに1つの列名と対応する値が含まれる)を返します。この関数の詳細な説明は、『Oracle SOA SuiteでのSOAアプリケーションの開発』のxref:lookupPopulatedColumns関数に関する項を参照してください。
署名
xref:lookupPopulatedColumns(xref-location, column, value, need-exception)
引数
特に断りのないかぎり、すべての引数は文字列値です。
xref-location: 相互参照リソースのフルパスおよび名前。
column: 参照列の名前。
value: 参照列に対応する値。
need-exception: 値が見つからない場合に例外をスローするかどうかを示すブール値。trueに設定されると、この関数は値が見つからない場合に例外をスローします。それ以外は、空の値を返します。
実行時に、次の理由で例外が発生することがあります。
指定された名前の相互参照表が見つからない。
指定された列名が見つからない。
指定された参照値が空である。
プロパティID
namespace-uri: http://www.oracle.com/osb/xpath-functions/xref
namespace-prefix: xref
例
xref:lookupPopulatedColumns('/BookSellers/XRefPublishers', 'HARPER', 'H_1500', true())
この関数は、参照列内の特定の値に対応する値について、相互参照列をルックアップします。この関数の詳細な説明は、『Oracle SOA SuiteでのSOAアプリケーションの開発』のxref:lookupXRef関数に関する項を参照してください。
署名
xref:lookupXRef(xref-location, ref-column, ref-value, column-name, need-exception)
引数
特に断りのないかぎり、すべての引数は文字列値です。
xref-location: 相互参照リソースのフルパスおよび名前。
ref-column: 参照列の名前。
ref-value: 参照列に対応する値。
column-name: 値をルックアップする列の名前。
need-exception: 値が見つからない場合に例外をスローするかどうかを示すブール値。trueに設定されると、この関数は値が見つからない場合に例外をスローします。それ以外は、空の値を返します。
実行時に、次の理由で例外が発生することがあります。
指定された名前の相互参照表が見つからない。
指定された列名が見つからない。
指定された参照値が空である。
複数の値が見つかった。
プロパティID
namespace-uri: http://www.oracle.com/osb/xpath-functions/xref
namespace-prefix: xref
例
xref:lookupXRef('/BookSellers/XRefPublishers', 'HARPER', 'H_1500', 'PENGUIN', false())
この関数は、参照列内の特定の値に対応する複数の値について、相互参照列をルックアップします。複数のノードを含むノードセット(各ノードに1つの値が含まれる)を返します。この関数の詳細な説明は、『Oracle SOA SuiteでのSOAアプリケーションの開発』のxref:lookupXRef1M関数に関する項を参照してください。
署名
xref:lookupXRef1M(xref-location, ref-column, ref-value, column-name, need-exception)
引数
特に断りのないかぎり、すべての引数は文字列値です。
xref-location: 相互参照リソースのフルパスおよび名前。
ref-column: 参照列の名前。
ref-value: 参照列に対応する値。
column-name: 値をルックアップする列の名前。
need-exception: 値が見つからない場合に例外をスローするかどうかを示すブール値。trueに設定されると、この関数は値が見つからない場合に例外をスローします。それ以外は、空の値を返します。
実行時に、次の理由で例外が発生することがあります。
指定された名前の相互参照表が見つからない。
指定された列名が見つからない。
指定された参照値が空である。
プロパティID
namespace-uri: http://www.oracle.com/osb/xpath-functions/xref
namespace-prefix: xref
例
xref:lookupXRef1M('/BookSellers/XRefPublishers', 'HARPER', 'H_1500', 'PENGUIN', true())
この関数は、相互参照表内の値を削除します。この関数に渡される列の値は、XREF_DATA表から削除され、XREF_DELETED_DATA表に移動されます。削除に成功すると、trueを返します。それ以外は、falseを返します。削除後に行に残された値が1つのみの場合、相互参照が残されていないため、その値も削除されます。
この関数の詳細な説明は、『Oracle SOA SuiteでのSOAアプリケーションの開発』の相互参照表の値の削除に関する項を参照してください。
署名
xref:markForDelete(xref-location, column, value)
引数
特に断りのないかぎり、すべての引数は文字列値です。
xref-location: 相互参照リソースのフルパスおよび名前。
column: 削除する値が含まれる列の名前。
value: 削除する値。
プロパティID
namespace-uri: http://www.oracle.com/osb/xpath-functions/xref
namespace-prefix: xref
例
xref:markForDelete('/BookSellers/XRefPublishers', 'HARPER', 'H_1500')
この関数は、実行されているモードに応じて、相互参照表の列に単一の値を移入します。新しい行を追加したり、既存の行にある列に値を追加するには、この関数を使用します。この関数は移入される値として文字列値を返します。populateXRefRow関数とは異なり、populateLookupXRefRow関数は同一のIDを持つレコードが同時に追加されたときに一意制約違反エラーをスローしません。かわりに、ルックアップとして動作してエラーの原因となった既存のソース値を返し、処理フローを停止しません。populateXRefRow関数の使用時に起こる同時実行性の問題を解決するには、この関数を使用します。
この関数の詳細な説明は、『Oracle SOA SuiteでのSOAアプリケーションの開発』のxref:populateLookupXRefRow関数に関する項を参照してください。
署名
xref:populateLookupXRefRow(xref-location, ref-column, ref-value, column, value, mode)
引数
すべての引数は文字列値です。
xref-location: 相互参照リソースのフルパスおよび名前。
ref-column: 参照列の名前。
ref-value: 参照列に対応する値。
column: 移入する列の名前。
value: 前述の列に移入する値。
mode: XREF移入モード。ADDまたはLINKを使用でき、すべて大文字で入力する必要があります。これらのモードの詳細は、『Oracle SOA SuiteでのSOAアプリケーションの開発』の異なるモードでのxref:populateLookupXRefRow関数の結果に関する項を参照してください。
プロパティID
namespace-uri: http://www.oracle.com/osb/xpath-functions/xref
namespace-prefix: xref
例
xref:populateLookupXRefRow('/BookSellers/XRefPublishers', 'HARPER', 'H_1500', 'PENGUIN', 'PEN_2001', 'ADD')
この関数は、実行されているモードに応じて、相互参照表の1つまたは2つの列に単一の値を移入します。新しい行を追加したり、既存の行にある列の値を更新または追加するには、この関数を使用します。この関数は移入される値として文字列値を返します。この関数の詳細な説明は、『Oracle SOA SuiteでのSOAアプリケーションの開発』のxref:populateXRefRow関数に関する項を参照してください。
注意:
この関数の使用時に同時実行性の問題が発生した場合は、populateLookupXRefRow関数も使用できますが、この関数は、一意制約違反につながる同時更新が行われる場合にのみ使用してください。
署名
xref:populateXRefRow(xref-location, ref-column, ref-value, column, value, mode)
引数
すべての引数は文字列値です。
xref-location: 相互参照リソースのフルパスおよび名前。
ref-column: 参照列の名前。
ref-value: 参照列に対応する値。
column: 移入する列の名前。
value: 前述の列に移入する値。
mode: XREF移入モード。ADD、LINKまたはUPDATEを使用でき、すべて大文字で入力する必要があります。これらのモードの詳細は、『Oracle SOA SuiteでのSOAアプリケーションの開発』のxref:populateXRefRow関数のモードに関する項を参照してください。
プロパティID
namespace-uri: http://www.oracle.com/osb/xpath-functions/xref
namespace-prefix: xref
例
xref:populateXRefRow('/BookSellers/XRefPublishers', 'HARPER', 'H_1500', 'PENGUIN', 'PEN_2001', 'ADD'
この関数は、実行されているモードに応じて、相互参照表の列に複数の値を移入します。新しい行を追加したり、既存の行にある列に複数の値を追加するには、この関数を使用します。1つの外部システムにある2つの値が、別のシステムの単一の値に対応します。そのような例では、この関数を使用して相互参照列に値を移入します。この関数は移入される相互参照値として文字列値を返します。
この関数の詳細な説明は、『Oracle SOA SuiteでのSOAアプリケーションの開発』のxref:populateXRefRow1M関数に関する項を参照してください。
署名
xref:populateXRefRow1M(ref-location, ref-column, ref-value, column, value, mode)
引数
すべての引数は文字列値です。
xref-location: 相互参照リソースのフルパスおよび名前。
ref-column: 参照列の名前。
ref-value: 参照列に対応する値。
column: 移入する列の名前。
value: 前述の列に移入する値。
mode: XREF移入モード。ADDまたはLINKを使用でき、すべて大文字で入力する必要があります。これらのモードの詳細は、『Oracle SOA SuiteでのSOAアプリケーションの開発』の異なるモードでのxref:populateXRefRow1M関数の結果に関する項を参照してください。
プロパティID
namespace-uri: http://www.oracle.com/osb/xpath-functions/xref
namespace-prefix: xref
例
xref:populateXRefRow1M(/BookSellers/XRefPublishers', 'HARPER', 'H_1500', 'PENGUIN', 'PEN_2001', 'LINK'
ドメイン値マップを使用すると、同一エンティティを説明するために異なるドメインで使用される用語をマップでき、1つのドメインで使用される特定のフィールドの値は、他のドメインで使用される同一フィールドの値にマップされます。たとえば、アプリケーション間で国コードや都道府県コードをマップできます。ドメイン値マップはルックアップ表に格納され、ドメイン値マップXPath関数を使用して、表内のデータをルックアップできます。
ドメイン値マップの詳細は、『Oracle SOA SuiteでのSOAアプリケーションの開発』のドメイン値マップ関数の使用に関する項を参照してください。Service Busの相互参照の詳細は、「ドメイン値マップでのデータのマッピング」を参照してください。
この関数は、ソース列に指定のソース値を含むドメイン値マップのターゲット列の値をルックアップして文字列を戻します。
署名
dvm:lookup(dvm-location, src-column, src-value, target-column, default-value)
引数
すべての引数は文字列値です。
dvm-location: ドメイン値マップのURI。
src-column: ソース列の名前。
src-value: ソース値(XSLT変換のソース・ドキュメントにバインドされたXPath式)。
target-column: ターゲット列の名前。
default-value: 値が見つからない場合、デフォルト値を戻します。
プロパティID
namespace-uri: http://www.oracle.com/osb/xpath-functions/dvm
namespace-prefix: dvm
例
次の例では、CityCodes表のBOという値に対応する値を、CityNames表で検索します。一致する値が見つからない場合は、かわりにCouldNotBeFoundを戻します。
dvm:lookup ('/CityMapsDVM/cityMap','CityCodes','BO','CityNames', 'CouldNotBeFound')
この関数は、ソース列に指定のソース値を含むドメイン値マップのターゲット列の値をルックアップして文字列を戻します。修飾列および値を指定することで、このルックアップを絞り込むことができます。この関数の詳細な説明は、『Oracle SOA SuiteでのSOAアプリケーションの開発』のドメイン値マップ関数の使用に関する項を参照してください。
署名
dvm:lookupValue(dvm-location, src-column, src-value, target-column, default-value, qualifiers[])
引数
すべての引数は文字列値です。
dvm-location: DVMリソースのフルパスおよび名前。
src-column: ソース列の名前。
src-value: ソース値(XSLT変換のソース・ドキュメントにバインドされたXPath式)。
target-column: ターゲット列の名前。
default-value: 値が見つからない場合、デフォルト値を戻します。
qualifier-column: 修飾子の値とともにルックアップを絞り込む列。修飾子の詳細は、『Oracle SOA SuiteでのSOAアプリケーションの開発』の修飾子ドメインに関する項を参照してください。
qualifier-value: 修飾子列の値。
プロパティID
namespace-uri: http://www.oracle.com/osb/xpath-functions/dvm
namespace-prefix: dvm
例
次の例では、CityCodes表のBOという値に対応する値を、CityNames表で検索します。State表のMassachusettsという修飾子は、市の名前をその州にのみ絞り込む場合に役立ちます。一致する値が見つからない場合は、かわりにCouldNotBeFoundを戻します。
dvm:lookupValue ('/CityMapsDVM/cityMap','CityCodes','BO','CityNames', 'CouldNotBeFound', 'State', 'Massachusetts')
この関数は、ソース列の値がソース値と等しいドメイン値マップの複数のターゲット列の値を含むXMLドキュメント・フラグメントを戻します。この関数を式で使用するときに、戻り値を変数に直接割り当てる場合、最初に出現したものが変数に割り当てられます。正しく割り当てるために、戻り値を繰り返す必要があります。
この関数の詳細な説明は、『Oracle SOA SuiteでのSOAアプリケーションの開発』のドメイン値マップ関数の使用に関する項を参照してください。
署名
dvm:lookupValue1M(dvm-location, src-column, src-value, target-columns[])
引数
すべての引数は文字列値です。
dvm-location: DVMリソースのフルパスおよび名前。
src-column: ソース列の名前。
src-value: ソース値(XSLT変換のソース・ドキュメントにバインドされたXPath式)。
target-columns: ターゲット列の名前。1つ以上の列名を指定する必要があります。ターゲット列の名前は、それぞれ個別の引数として複数指定できます。
プロパティID
namespace-uri: http://www.oracle.com/osb/xpath-functions/dvm
namespace-prefix: dvm
例
次の例では、CityCodes表のGarden Cityという値に対応する値を、CityNames表およびCityNickNames表で検索します。
dvm:lookupValue1M ('/CityMapsDVM/cityMap','CityCodes','Garden City','CityNames', 'CityNickName')
Service Busで提供される標準のXPath関数に加えて、式で使用するカスタムXPath関数を作成および登録できます。Service Busでは、カスタムXPath関数を作成するための充実したフレームワークが提供されます。カスタムXPath関数は、パイプライン、分割-結合、XQuery Mapper変換など、開発時や実行時のツールにおいてXQuery式エディタで使用できます。
この項の内容は次のとおりです。
注意:
Service Busでは、データベース表の更新やグローバル・トランザクションへの参加といった二次的な動作を含むカスタム関数はサポートされません。XQuery結果のみに影響するカスタム関数を作成し、二次的な動作はJavaコールアウトなど他の機能を使用して実行してください。
カスタム関数は、WebLogic Serverドメイン内のService Busのすべてのプロジェクトとサービスで使用できます。カスタム関数を登録するには、XMLファイル(およびローカライズ用のオプション・プロパティ・ファイル)を作成する必要があります。Service Bus提供の組込み関数はこの関数フレームワークが使用されるため、このような既存の登録リソースをガイドとして使用できます。これらのファイルは次のディレクトリにあります。
/service_bus_home/config/xpath-functions
Service Busの関数ファイルはosb-built-in.xmlです。このファイルでは、%記号で囲まれたキー(%OSB_FUNCTIONS%など)は対応する.propertiesファイルから値を取得します。新しいドメインにカスタム関数を拡張するには、次の場所にある新しいドメインに登録ファイル(XMLファイルとプロパティ・ファイル)をコピーする必要があります。
/domain_home/config/osb/xpath-functions
xpath-functionsサブディレクトリを作成する必要があります。
カスタム関数登録ファイルの基本構造の概要は次のとおりです。その後で要素について説明します。
category id
group id
function
name
comment
namespaceURI
className
method
isDeterministic
scope
要素にはxpf:接頭辞が付きます。
次の表では、カスタム登録ファイルの各要素を示して説明します。
表B-1 カスタム関数登録ファイルのプロパティ
| 要素 | 説明 |
|---|---|
カテゴリ |
式エディタで一連の関数を物理的に分類する、Service Bus Functionsなどのグループ。 |
グループ |
ユーザー・インタフェースで関数をグループ化するためのサブカテゴリ(General、Accessorsなど)。 |
名前 |
XQuery式に表示される関数の名前。namespaceURIと接頭辞を含む関数名は、一意であることが必要です。Service Busでは異なるメソッド引数でオーバーロードする関数はサポートされません。関数名が同一でもネームスペースが異なっていれば(つまり接頭辞が異なっていれば)使用できます。 |
コメント |
関数の説明。説明はService Busユーザー・インタフェースには表示されませんが、関数の呼出し方法やわかりやすい引数の名前を示すように指示を指定できます。 |
namespaceURI |
関数のネームスペース。たとえば、Service Busの関数ネームスペースは |
className |
関数を実装する、完全修飾されたカスタムJavaクラス。 |
method |
前に戻り型を指定する、関数を実装するカスタムJavaメソッド(例: メソッドが一次元配列を使用する場合は、XMLファイルにエントリを作成する方法について「一次元配列の使用」を参照してください。 |
isDeterministic |
関数が決定的かどうかを宣言する |
scope |
関数を適用するService Busリソースのタイプ(Pipeline、SplitJoinなど)。複数の範囲要素を定義できます。 |
カスタム関数が式エディタに表示されるのは、Service Busがカスタム・クラスを検出できるようになってからです。次のガイドラインに従って、Service Busで検索および使用できるよう、カスタムXPath関数のクラスを作成してパッケージ化します。
次のガイドラインに従って、カスタム関数のJavaクラスとメソッドを作成します。
クラス: クラスはパブリックであることが必要です。
メソッド: メソッドはパブリックかつ静的であることが必要です。
引数および戻り値: 次の表に、メソッドの引数と戻り値でサポートされる型を示します。この表に含まれない型はサポートされません。内部クラスおよび多次元配列はサポートされません。
表B-2 カスタム関数でサポートされるJavaメソッドの型
| Java型 | XQuery型 | XSLTの型 |
|---|---|---|
java.lang.String |
xs:string |
string |
int、java.lang.Integer |
xs:int |
number |
boolean、java.lang.Boolean |
xs:boolean |
boolean |
long、java.lang.Long |
xs:long |
number |
short、java.lang.Short |
xs:short |
number |
byte、java.lang.Byte |
xs:byte |
number |
double、java.lang.Double |
xs:double |
number |
float、java.lang.Float |
xs:float |
number |
char、java.lang.Char |
xs:string |
object |
java.math.BigInteger |
xs:integer |
number |
java.math.BigDecimal |
xs:decimal |
number |
java.util.Date |
xs:datetime |
脚注を参照してください1 |
java.sql.Date |
xs:date |
脚注を参照してください。 |
java.sql.Time |
xs:time |
脚注を参照してください。 |
javax.xml.namespace.QName |
xs:Qname |
脚注を参照してください。 |
org.apache.xmlbeans.XmlObject |
element() |
脚注を参照してください。 |
org.w3c.dom.Element |
element() |
XSLTのnode-set型はカスタムXPath関数ではサポートされません。 |
1次元配列(サポート対象のJavaの型を使用)が、アスタリスク(*)を使用して、対応するXQueryの型にマップされます(アスタリスクは、配列の複数のカーディナリティを暗黙に指定するワイルドカードです)。次に例を示します。
public static XmlObject[] getArrayOfXmlObjects(XmlObject[] a)
これが次の型にマップされます。
namespace:getArrayOfXmlObjects($arg1 as element()*) as element()*
1次元配列の入力引数または戻り値を含む関数のシグネチャでは、http://docs.oracle.com/javase/7/docs/api/java/lang/Class.html#getName%28%29で説明されている型のエンコーディングを使用する必要があります。次の例は、カスタム関数XMLファイルで、必要な配列エンコーディングを使用して1次元配列のメソッドを指定する方法を示します。
| Javaメソッド | カスタム関数XMLファイルでの入力 |
|---|---|
|
|
|
|
カスタム関数をXQueryエディタに組み込んで使用するためには、Service Busがそれらのカスタム関数を認識する必要があります。カスタム関数クラスをJARファイルにパッケージ化し、そのJARを次のいずれかのディレクトリに置きます。
service_bus_home/config/xpath-functions/
domain_home/config/osb/xpath-functions/
service_bus_homeはService Busがインストールされている場所を、domain_homeはService Busドメインがインストールされているディレクトリを表します。
IDEおよびサーバーの起動時に、Service Busは、これらのディレクトリのカスタム関数クラスから使用可能なカスタム関数を検索します。「Service Busでのカスタム関数の登録」に従って、カスタム関数のXMLファイルでカスタム・クラスおよびメソッドを正しく参照してください。
新しいカスタム関数を追加したら、IDEと新しい関数を使用するすべてのサーバーを再起動する必要があります。
ここでは、Service BusのXQuery式およびリソースでカスタム関数を使用する方法について説明します。
Service Bus提供の関数と同様に、インラインXQuery式とXQueryリソースの両方にカスタム関数を含めることができます。
XSLTリソース内からカスタム関数を呼び出すための構文は、Service Busで使用するXSLTエンジンによって異なります。次のカスタム関数コードを考えると、次に示すXalanエンジンを使用してカスタム関数を呼び出すための構文の例は、Xalan XSLTエンジン(Oracle JDK対応のMicrosoft Windowsでのデフォルト)を使用してカスタム関数を呼び出す構文を示します。
package tests.pipeline;
public class CustomXQFunctions
{
public static String myUppercaseString(String arg)
{
return arg.toUpperCase();
}
}
例 - Xalanエンジンを使用してカスタム関数を呼び出すための構文
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:param name="arg-string"/>
<xsl:template name="myUppercaseString"
xmlns:ns0="xalan://tests.pipeline.CustomXQFunctions">
<xsl:variable name="upcase" select="ns0:myUppercaseString($arg-string)" />
<originalInput>
<xsl:value-of select="$arg-string" />
</originalInput>
<result>
<xsl:value-of select="$upcase" />
</result>
</xsl:template>
<xsl:template match="*">
<xsl:copy>
<xsl:call-template name="myUppercaseString"/>
</xsl:copy>
</xsl:template>
</xsl:stylesheet>
入力ドキュメントが<example />、入力arg-stringの値がhelloの場合、変換は次のように行われます。
<example> <originalInput>hello</originalInput> <result>HELLO</result> </example>
文字列に変換されてから、元のタイプとして戻されます。
