この章では、Oracle Service Busコンソールを使用したXQuery変換リソースの作成、検索、編集および削除の方法について説明します。
XQueryトランスフォーメーション・マップは、XMLからXML、XMLから非XML、および非XMLからXMLのマッピングを記述できます。
この章の内容は次のとおりです。
XQueryは、XMLドキュメントに対してXMLデータを問い合わせる際に役立ちます。XQueryはXPathを使用および拡張し、XMLドキュメント内の要素および属性をナビゲートしてそれらを抽出します。
Service BusはXQueryを使用してビジネス・ロジックを実装します。Service Busは、変換、データ選択、条件評価およびデータ操作などの様々なアクティビティでXQueryリソースを使用します。Service BusはXQuery 1.0を完全にサポートします。これには、モジュールなどのオプション機能が含まれます。古いXQuery 2004もサポートされます。
XQueryトランスフォーメーション・マップは、2つのデータ型の間のマッピングを記述したものです。XQueryマップは、スキーマの異なるXMLドキュメント間のマッピングを記述したものです。Service BusでXQueryを使用すると、XMLドキュメントを処理して、ドキュメント・データをXMLスキーマから別のXMLスキーマに変換できます。これにより、異なるスキーマを使用するアプリケーション間でデータの交換が可能になります。XQueryを使用して、複雑なデータ操作と変換を実行できます。たとえば、受信する発注スキーマを、送信する請求書スキーマにマップできます。
XQuery式は、メッセージ・フローの実行中にメッセージ・コンテキスト変数のデータ・コンテンツ(メッセージ・コンテキスト変数の一部)を作成するために使用します。XQuery式エディタ内で直接テスト・コンソールを使用して、式の定義をテストすることができます。同様に、XQuery条件を使用して、メッセージ・フロー内のブール条件を評価できます。XQuery条件エディタ内で直接テスト・コンソールを使用して、条件の定義をテストすることができます。
JDeveloperには、XQueryを使用した変換をスクリプト化できる式ビルダーと、複雑なマッピングを作成できるXQueryマッパーがあります。
Oracle Service Busコンソールには、XQueryを使用した変換をスクリプト化するエディタがあります。このエディタには、XQuery式を定義したり、既存のXQueryリソースの名前として実行時に評価される式を定義したりするオプションが用意されています。
JDeveloperおよびコンソールのいずれの場合も、パイプラインまたは分割-結合のいずれかのアクションからエディタにアクセスします。
JDeveloperのXQueryマッパーは、スキーマのルート要素、WSDLメッセージ・パート、またはWSDLメッセージの間のマッピングを定義できるグラフィカル・ツールです。スキーマのルート要素はXSDスキーマ・ファイルまたはWSDLファイルから取得できますが、直接マップできるのは、単一のメッセージ・パートを含むWSDLメッセージのみです。JDeveloperでXSLTマッピングを作成したら、マッパーで生成された.xsl
ファイルをOracle Service BusコンソールのXSLTリソースにアップロードできます。
JDeveloperには様々な式ビルダーも用意されており、式を作成して、使用する既存のXSLTリソースを指定できます。JDeveloperのマッパーとエディタの詳細は、次のトピックを参照してください。
Oracle SOA Suiteを使用したSOAアプリケーションの開発のXQueryマッパーを使用した変換の作成に関する項
Oracle SOA Suiteを使用したSOAアプリケーションの開発のOracle JDeveloperの式ビルダーを使用したXPath式の作成に関する項
Oracle Service Busコンソールで、XQuery/XSLT式エディタを使用して式を作成し、使用する既存のXQueryリソースを指定できます。
XQueryリソースを参照するには、コンソールでリソースを作成し、既存のXQuery変換ファイル(.xqy
)をリソースにアップロードしておく必要があります。この機能により、JDeveloperで複雑なマッピングを作成し、それらをコンソールにインポートして使用できます。XQuery変換は複数のパイプラインおよび分割-結合で再利用できます。
Oracle Service Bus ConsoleのXQuery/XSLTエディタの詳細は、「Oracle Service Busコンソールでの式エディタの操作」を参照してください。
JDeveloperでService Busプロジェクト内にXQueryマップを作成し、パイプラインおよび分割-結合のXQuery式でそれらを使用して外部システム間でオブジェクトをマップできます。
Service BusプロジェクトをXQuery 2004からXQuery 1.0に変換する際に、すべての2004 XQueryはXQuery 1.0エンジンで実行されるように切り替えられます。XQuery 2004からXQuery 1.0に変換後、JDeveloperの「XQueryマッパー」タブが表示されるが、実際のマッピングは表示されません。
変換されたXQueryをテストする場合:
ネームスペース宣言を正確に作成します。これには2通りの方法があります。
XQuery仕様からimport文を使用:
import schema namespace ns0="http://www.example.com/custele" at "../TestInputSchemas/customerEle.xsd";
Oracleの注釈のメカニズムを使用:
xquery version "1.0"; (:: OracleAnnotationVersion "1.0" ::) declare namespace ns0="http://www.example.com/custele"; (:: import schema at "../TestInputSchemas/customerEle.xsd"::)
JDeveloperマッパー・メカニズムで認識されるように、変数をスキーマ要素として宣言します。次に例を示します。
declare function local:AttributeToElement($customerOut as element()(::schema-element(ns0:customerOut)::)) as element() (::schema-element (ns1:customer)::)
XQueryリソースをService Busプロジェクトに追加できます。JDeveloperまたは他のエディタを使用して作成されたXQueryファイルは、リソースとしてプロジェクトにインポートできます。
Oracle Service Busコンソールを使用して、XQueryリソースをService Busプロジェクトに追加します。JDeveloperなどのエディタで作成したXQueryファイルをインポートするか、ソースを作成してインラインでコードを編集できます。
コンソールでXQueryリソースを作成するには:
プロジェクト・ナビゲータでは、プロジェクトまたはフォルダを右クリックしてXQueryリソースを含め、「作成」をポイントし、「リソース」を選択します。「変換」、「XQuery」をクリックし、次に「OK」をクリックします。
XQueryの作成ダイアログが表示されます。
次のいずれかを行います:
既存のXQueryファイルからリソースを作成するには、「ファイルのアップロード」フィールドの横にある「ファイルの選択」をクリックし、使用するファイルを選択します。
「リソース名」フィールドに、ファイル拡張子なしのファイル名が自動的に移入されます。この名前は変更可能です。
XQueryを最初から作成するには、XQueryリソースに一意の名前を入力します。
必要に応じて、リソースの簡単な「説明」を入力します。
「作成」をクリックします。
XQueryリソースがXQuery定義エディタに表示されます。
XQueryを変更するには、次の手順を実行します。
ツールバーで、「XQueryコンテンツの編集」をクリックします。
「ソースの表示/編集」ダイアログが表示されます。
アップロードする新しいXQueryファイルを参照して選択するには、「ファイルの選択」をクリックします。
ファイルのコンテンツを変更するには、ダイアログの「コンテンツ」セクションでコードを直接更新します。
「保存」をクリックします。保存時にXQueryが検証されます。
XQuery定義エディタのツールバーで、「保存」をクリックします。
セッションを終了して構成をランタイムにデプロイするには、「アクティブ化」をクリックします。
Oracle Service Busコンソールを使用して、Service Busプロジェクト内のXQueryリソースを編集します。JDeveloperなどのエディタで作成した更新済XQueryファイルをインポートするか、インラインでコードを編集できます。
コンソールでXQueryリソースを編集するには:
Oracle Service Busコンソールを使用して、XQueryリソースをService Busプロジェクトから削除できます。リソースに参照がある場合は、リソースを削除する前に参照を削除します。XQuery定義エディタでXQueryリソースを開き、右上の「ツール」アイコンをクリックして「参照」を選択し、そこに参照があるかどうかを確認します。
コンソールでXQueryリソースを削除するには:
Service BusはXQuery 1.0をサポートします。古いXQuery 2004もサポートされます。Service Busで作成された新しいXQueryリソースは、デフォルトでXQuery 1.0を使用します。
12g以前のService Busプロジェクトからアップグレードした場合、プロジェクト内のすべてのXQueryリソースはXQuery 2004を使用するように構成されます。すべてのXQueryファイルで、次の行が1行目として存在します。
xquery version "2004-draft";
プロジェクト内のすべてのXQuery 2004リソースでXQuery 1.0を使用するようにアップグレードすることもできます。XQueryコンバータは、Query 2004ファイルからXQuery 1.0への基本的な変換を実行します。コンバータで処理できない構文エラーは、手動で確認して修正する必要があります。
プロジェクト内のXQueryリソースをアップグレードするには:
Service Busでは、次のXQuery関数をサポートしています。
W3C仕様で説明する標準のXQuery関数:
いくつか例外はありますが、Oracle XQueryエンジンの一部として提供されるOracle拡張関数および言語キーワード(「Oracleでサポートされる拡張関数」を参照)。
Service Bus固有の拡張関数。「Service Busの関数拡張機能」を参照してください。
注意:
すべてのOracleの拡張関数で、次の関数接頭辞fn-bea:
を使用します。つまり、XQueryの完全な表記では拡張関数は次の形式になります。
fn-bea: function_name.
すべてのOracle関数拡張機能の説明は、「Service Bus XQuery関数」を参照してください。
Service Busでは、XQueryに対し、次のものを除くすべてのOracle拡張関数がサポートされています。
fn-bea:is-access-allowed
fn-bea:is-user-in-group
fn-bea:is-user-in-role
fn-bea:userid
fn-bea:async
fn-bea:timeout
fn-bea:get-property
fn-bea:execute-sql()
Service Busでは、次の関数は使用しないでください。他の言語機能で代用することをお薦めします。
fn-bea:if-then-else
fn-bea:QName-from-string
fn-bea:sql-like
Service Busには、次のXQuery関数が用意されています。
fn-bea:lookupBasicCredentials
関数は、指定されたサービス・アカウントのユーザー名と暗号化されていないパスワードを返します。任意のタイプのサービス・アカウントを指定できます(静的、パススルー、またはユーザー・マッピング)。「サービス・アカウントの操作」を参照してください。
fn-bea:lookupBasicCredentials
関数は、カスタム・トランスポート・ヘッダー、またはSOAPエンベロープのアプリケーション固有の場所にあるユーザー名とパスワードのエンコードに使用するXQuery関数の大規模なセットの一部として使用します。HTTP認証ヘッダーにユーザー名とパスワードだけを含める必要がある場合、またはWS-Securityユーザー名トークンとしてユーザー名とパスワードだけを必要とする場合は、この関数を使用する必要はありません。Service Busは事前にサービス・アカウントからユーザー名とパスワードを取得し、必要に応じてHTTP認証ヘッダーにエンコードします(WS-Securityユーザー名トークンの場合も同様)。
関数には次の署名が含まれます。
fn-bea:lookupBasicCredentials( $service-account as xs:string ) as UsernamePasswordCredential
ここで、$service-account
は、次の形式のサービス・アカウントのパスと名前です。
project-name[/folder[...]]/service-account-name
戻り値は、次の形式のXML要素です。
<UsernamePasswordCredential xmlns="http://www.bea.com/wli/sb/services/security/config"> <username>name</username> <password>unencrypted-password</password> </UsernamePasswordCredential>
返された要素をユーザー定義の変数に保管し、必要なときにこの変数からユーザー名とパスワード値を取得できます。
たとえば、Service Busプロジェクトには、myProject
という名前が付けられます。myServiceAccount
という名前の静的なサービス・アカウントを、myFolder1/myFolder2
という名前のフォルダに作成します。サービス・アカウントに、ユーザー名pat
とパスワードpatspassword
を保存します。
サービス・アカウントのユーザー名とパスワードを取得するには、次の関数を呼び出します。
fn-bea:lookupBasicCredentials( myProject/myFolder1/myFolder2/myServiceAccount )
関数は次の要素を返します。
<UsernamePasswordCredential xmlns="http://www.bea.com/wli/sb/services/security/config"> <username>pat</username> <password>patspassword</password> </UsernamePasswordCredential>
特定のユーザーが特定のグループに所属するかどうかを返します(trueまたはfalse)。次に例を示します。
fn-bea:isUserInGroup($user-name as xs:string, $group-name as xs:string)
特定のユーザーが特定のロールに所属するかどうかを返します(trueまたはfalse)。次に例を示します。
fn-bea:isUserInRole($user-name as xs:string, $role-name as xs:string)
関数fn-bea:uuid
は、汎用一意識別子を返します。関数には次の署名が含まれます。
fn-bea:uuid() as xs:string
この関数をプロキシ・パイプラインで使用して、ユニークな識別子を生成できます。生成されたユニークな識別子を、要素としてXMLドキュメントに挿入できます。システム変数にユニークな識別子は生成できません。これを、メッセージ・ペイロードの変更に使用できます。
たとえば、トラッキング用にユニークな識別子を生成してメッセージに追加するとします。この関数を使用してユニークな識別子を生成できます。関数が返す文字列をSOAPヘッダーに追加できます。
fn-bea:execute-sql()
関数を使用すると、Service Busのメッセージ・フローでXQueryから低レベルのデータベースにアクセスできます。詳細は、「XQueryを使用したデータベースへのアクセス」を参照してください。問合せは、型付きデータを含むフラットな行要素のシーケンスを返します。
関数には次の署名が含まれます。
fn-bea:execute-sql( $datasource as xs:string, $rowElemName as xs:QName, $sql as xs:string, $param1, ..., $paramk) as element()*
説明:
$datasource
はデータソースのJNDI名。
$rowElemName
は行要素の名前。$rowElemName
を、結果の要素シーケンスの各要素に付けるQNameとして指定します。
$sql
はSQL文。
$param1, ..., $paramk
は1 - k個のパラメータ。
element()*
は返された要素のシーケンスを表します。
戻り値は、型付きデータを含むフラットな行要素のシーケンスで、SQL/JDBCデータ・モデルとXQueryデータ・モデル間で値を自動的に変換します。サポート対象のデータベースについてXQueryエンジンが生成する、またはサポートするデータ型マッピングの詳細は、「XQuery-SQLマッピング参照」を参照してください。
Service Busメッセージ・フローからfn-bea:execute-sql()
関数を実行する場合、返された要素をユーザー定義の変数に格納できます。
次の例では、Service Busでのfn-bea:execute sql()
関数の使用方法について説明します。
Service Busプロキシ・サービスでは、実行時のメッセージのルーティング(動的)先であるURIの仕様をサポートしています。詳細は、「動的ルーティングの使用」を参照してください。次の例は、動的ルーティング・シナリオでデータベースからURIを取得するfn-bea:execute-sql()
関数の使用例を示しています。
例 - データベースからのビジネス・サービスのURIの取得
<ctx:route><ctx:service> { fn-bea:execute-sql( 'ds.myJDBCDataSource', xs:QName('customer'), 'SELECT targetService FROM DISPATCH_MAPPING WHERE customer_priority=?', xs:string($body/m:Request/m:customer_pri/text()) )/TARGETSERVICE/text() } </ctx:service></ctx:route>
この例では:
ds.myJDBCDataSource
はデータ・ソースのJNDI名。
xs:string($body/m:Request/m:customer_pri/text())
は、リクエスト・メッセージを確認し、メッセージにcustomer_pri
の値を含むcustomer_priority=?
を生成します。
/TARGETSERVICE/text()
はSQL文の結果に適用されるパス。返される要素の文字列(CDATA)コンテンツを生成します。
<ctx:route><ctx:service> ... </ctx:service></ctx:route>
は、動的ルーティング・シナリオのXQuery文に必須の要素。
DISPATCH_MAPPING
の表定義を次に示します。
create table DISPATCH_MAPPING ( customer_priority varchar2(256), targetService varchar2(256), soapPayload varchar2(1024) );
DISPATCH_MAPPING
表は、次の例で示すように移入されます。
例 - DISPATCH_MAPPING表
INSERT INTO DISPATCH_MAPPING (customer_priority, targetService, soapPayload) VALUES ('0001', 'system/UCGetURI4DynamicRouting_proxy1', '<something/>'); INSERT INTO DISPATCH_MAPPING (customer_priority, targetService, soapPayload) VALUES ('0002', 'system/UCGetURI4DynamicRouting_proxy2', '<something/>');
注意:
このシナリオでは、表の3列目(soapPayload
)は使用しません。
例3のfn-bea:execute-sqlの実行
プロキシ・サービスが次の例のリクエスト・メッセージ(リクエスト・メッセージの<customer_pri>
の値は0001
)を受信した結果として、「データベースからのビジネス・サービスのURIの取得」の例のXQueryが実行された場合、動的ルーティング・シナリオで返されるURIは次のようになります。
system/UCGetURI4DynamicRouting_proxy1
リクエスト・メッセージの$bodyの例
<m:Request xmlns:m="http://www.bea.com/alsb/example"> <m:customer_pri>0001</m:customer_pri> </m:Request>
サポート対象のデータベースについてXQueryエンジンが生成する、またはサポートするデータ型マッピングの詳細は、「XQuery-SQLマッピング参照」を参照してください。SQLのXMLType
列タイプはサポートされていません。ただし、XMLType
オブジェクトの getStringVal()
メソッドを使用してXMLType
列のデータにアクセスし、文字列値に変換できます。
次のシナリオでは、Oracle DatabaseのXMLType
列からデータを選択する際に使用できる手順について説明します。
プロキシ・サービスのメッセージ・フローで割当てアクションを使用して、次のXQueryの結果を変数($result
)に割り当てます。
例 - データベースからのXMLTypeデータの取得
fn-bea:execute-sql( 'ds.myJDBCDataSource', 'Rec', 'SELECT a.purchase_order.getStringVal() purchase_order from datatypes a' )
説明:
ds.myJDBCDataSource
はデータ・ソースのJNDI名。
Rec
は$rowElemName
。したがって、Recは結果の要素シーケンスの各要素に指定されたQNameです。
select a.purchase_order.getStringVal() ...
は、文字列値に変換するために、XMLType
オブジェクトのgetStringVal()
メソッドを使用するSQL文。
datatypes
は、XMLの値の読込み元である表(この場合、datatypes
表には1つの行が含まれています)。
注意:
dataty.pes
表の表定義を次に示します。
create table datatypes ( purchase_order xmltype );
次の置換アクションを使用して、$body
のノードのコンテンツを(前の手順で$result
に割り当てた)fn-bea:execute-sql()
問合せの結果に置き換えます。
Replace [ node contents ] of [ undefined XPath ] in [ body ] with [ $result/purchase_order/text() ]
次のサンプル・コードは、置換後の$body
を示します。
注意:
datatypes
表には、(発注書データを含む)行が1つ含まれています。この行には、次の例に示すXMLが含まれています。
例 - XMLコンテンツをfn-bea:execute-sql()の結果に置き換えた後の$body
<soap-env:Body> <openuri:orders xmlns:openuri="http://openuri.com/"> <openuri:order> <openuri:customerID>123</openuri:customerID> <openuri:orderID>123A</openuri:orderID> </openuri:order> <openuri:order> <openuri:customerID>345</openuri:customerID> <openuri:orderID>345B</openuri:orderID> </openuri:order> <openuri:order> <openuri:customerID>789</openuri:customerID> <openuri:orderID>789C</openuri:orderID> </openuri:order> </openuri:orders> </soap-env:Body>
XMLドキュメントをXML要素としてではなく文字列として表す必要がある場合は、fn-bea:serialize()
関数を使用します。たとえば、EJBインタフェースを介してXMLドキュメントを交換する場合、EJBメソッドは引数を文字列として受け取ります。関数には次の署名が含まれます。
fn-bea:serialize($input as item()) as xs:string
インラインXQuery式およびXQueryリソースの両方で、独自のカスタムXPath関数を作成および使用できます。詳細は、「カスタムXPath関数の作成」を参照してください。