10g（10.1.3.1.0）
B31858-01
 目次 |
 索引 |
| Oracle Containers for J2EE サービス・ガイド 10g（10.1.3.1.0） B31858-01 |
|
この章では、Oracle XML Query Service（XQS）の使用方法について説明します。XQSサービスはエンタープライズ・データの取得、分析、統合および変換に役立つユーザー・モデルを提供します。この章には、次の項目が含まれます。
この項では、XQSおよびXQSの基盤となる関連テクノロジの概略を提供し、Oracle XML Query Serviceについて説明します。内容は次のとおりです。
XQSとは、OC4Jサービスの1つで、XQuery（XML問合せ言語）で作成されており、エンタープライズ・データの統合ビューを作成するための簡単な宣言方式を提供します。
通常、XQSなどのサービスがなければ、XQueryはXML文書にしかアクセスできません。XQSを使用することで、SOAPやJDBCなどのアクセス・メカニズムを介して、XML以外のドキュメント、リレーショナル・データベース、およびXML以外のその他のエンタープライズ情報システムからもデータを取得できます。
XQSを使用すると、プログラミング作業が簡略化されます。計画の段階では、XQuery式の設計（問合せ、組込みファンクション・コールまたはユーザー定義ファンクション・コール）およびデータ構造のみに集中して作業できます。データソースへのアクセスの詳細は、構成設定によって後で決定されます。XQuery式とアクセスするデータ間のバインドは、この構成設定で発生します。その後、XQSによって、XQS関数と呼ばれる外部XQuery関数が作成されます。この関数は、目的のソースからデータを取得するために使用します。
XQSは、非定型問合せ（実行時に渡されるXQuery式）またはXQSビュー（以前作成して保存した問合せ）をサポートします。ビューはXQuery関数になり、後で名前でアクセスできます。（XQuery自体は、ビューの概念をサポートしていません。）ビューを使用することで、XQuery式を再利用し、強力で保守しやすい階層問合せを作成できます。
XQSは、多様なクライアント・インタフェースを提供します。そのため、EJB、JSPタグ・ライブラリ、JavaクラスまたはWebサービスを介してXQuery式を実行できます。
この項では、XQSの基盤となるテクノロジの概要を説明します。
XQueryは、XMLデータの問合せと変換に使用できる宣言型言語です。目的の条件を使用してXMLソースをインテリジェントに問い合せ、要素と属性、およびそれらに含まれるデータを取得し、解析できます。これは、XMLデータベースやXML文書などの多種多様なXMLソースで幅広く適用される、柔軟性の高い標準テクノロジです。XQueryは、SQLと類似した機能を持ち、リレーショナル・データベースの問合せにおけるSQLのような役割を果します。
XQueryでは、データの問合せだけでなく、XMLデータの変換も行えます。そのため、XSLTの補足機能または代替として使用できます。
XPath 2.0に基づく式のデータ・モデルでは、XQueryの基本的な構成メンバーは式です。それぞれのXQueryの結果は、XML順序として戻されます。XML順序は、0（ゼロ）個以上の連続したデータ項目の列で、各項目はスカラー値、XMLノードまたはXML文書です。項目のタイプの定義は、XML Schema標準に基づきます。
各問合せは、1つ以上の、モジュールと呼ばれる部分で構成され、各モジュールは、1つのプロローグおよびそれに続く1つの問合せボディで構成されます。プロローグは、モジュールの処理環境を定義する一連の宣言およびインポートです。
XQueryに含まれる問合せの一般的なモデルは、for-let-where-order-return（FLWOR）式です。次の疑似コードは、FLWOR式で可能な処理の例を示しています。
For each department in depts.xml Let [variable] represent each employee in each department Where the headcount of employees in a department is at least 10 Order by average salary of department Return headcount and average salary of each department
XQueryでは、定義および事前定義済関数を使用して問合せを実行することもできます。複雑な問合せの場合は、外部関数を別途提供し、XQuery定義から宣言および起動できます。外部関数は、JavaやSQLなどの様々な言語で実装できます。
外部関数の使用は、XQS機能の重要な部分です。独自のデータに対して目的の問合せが実行できるように、XQS構成に従って外部関数が作成されます。
JavaでのOracle XQueryの実装は、XQSの基礎となるエンジンであり、Oracle XML Query Serviceの一部として提供されます。このOracle XQuery実装は、Oracleデータベース製品のOracle XML DBの一部であるOracle XQuery実装と起点や機能が共通していますが、この2つを混同しないようにしてください。
OracleのXQuery実装では、タイプoracle.xml.xqxp.datamodel.XMLItemを使用して、問合せ結果のXML順序に含まれる個々の項目が表されます。
次の表に、XQueryおよびXQSで使用できる、事前定義済の名前空間および接頭辞を示します。
これらの接頭辞は、XQuery式のプロローグで宣言せずにXQuery式で使用できます。また、xml以外は、すべてプロローグ内で再定義できます。oraおよびurn以外のすべての接頭辞は、XQuery標準で事前定義済です。
JavaバージョンのOracle XQueryには、このデータベース・バージョンで最初に導入されたora拡張関数のサポートが含まれています。サポート対象は次のとおりです。
ora:containsを使用すると、フルテキスト述語を伴う構成検索を制限できます。
ora:matchesを使用すると、正規表現を使用して文字列内のテキストを一致させることができます。
ora:replaceを使用すると、正規表現を使用して文字列内のテキストを置換できます。
ora:sqrtを使用すると、数値の平方根を戻すことができます。
ora:viewを使用すると、XML文書のように、XQuery式に含まれる既存のデータベース表またはデータベース・ビューを問い合せることができます。実際には、この関数によって、リレーショナル・データに関連するXMLビューが作成されます。
これらの関数の詳細は、『Oracle XML DB開発者ガイド』を参照してください。
暗黙的タイムゾーンのサポート: XQSのXQueryでは、暗黙的タイムゾーンは常にZとみなされます。
+0と-0の境界条件の相違: XQuery標準では正のゼロと負のゼロが区別されますが、XQSのXQueryでは区別されません。両方とも0と表示され、同様に処理されます。
W3Cによって定義されているXQueryのオプション機能を次に示します。ただし、これらの機能は現時点ではサポートされていません。
これらの定義済のオプション機能に加えて、W3C仕様では、実装によって、実装定義のプラグマおよび拡張機能が提供されます。提供されるものは次のとおりです。
Oracle実装では、このようなプラグマや拡張機能は要求されません。
XQSでは、最新の仕様に含まれるほとんどのXQuery関数とXQuery演算子がサポートされていますが、次のものはサポートされていません。
正規表現（regular-expression）の操作には、かわりにOracle拡張機能を使用してください。
fn: trace、fn:id、fn:idref、fn:codepoint-equal、fn:prefix-from-QName、fn:doc-availableおよび fn:collection()（引数を取らないfn:collection()）
XQuery組込み関数fn:docおよびfn:collectionは、本質的に実装定義済です。XQSでは、これらの関数はサポートされています。関数docは、URI引数によって対象に指定されたローカル・ファイル・システムからファイルを取得します。ファイルは、整形式のXMLデータである必要があります。関数collectionも同様ですが、ファイルではなくフォルダを取得します（フォルダ内の各ファイルは整形式のXMLデータである必要があります）。
fn:docおよびfn:collectionのXQS実装では、次に示すファンクション・コールのように、引数はプロトコルがfileで、ローカル・ファイル・システムにあるファイルへのパスを指定するURLである必要があります。
fn:doc("C:/MyDocuments/XQS/myView.xq")
URLのプロトコル部分は省略できます。プロトコルは、デフォルトではfileです。
fn:doc()関数のかわりに、XQSドキュメント関数を使用し、Oracle Application Serverがサポートする任意のURLを介してドキュメントにアクセスできます。たとえば、HTTPプロトコルを使用してXMLドキュメントにアクセスするには、次の構成で<document-source>を定義します。
<document-source> <function-name prefix="ns"> genericFile </function-name> </document-source>
次に示すように、XQS関数genericFile()は問合せ式の一部にすることも可能です。
declare namespace ns = "…"; declare function ns:genericFile() external; for $i in ns:genericFile("http://www.acme.com/repository/item137560.xml") return ...
XQuery API for Java（XQJ）は、JavaアプリケーションからXQuery式を実行するための、進化中の標準です。（JSR-225を参照してください。）また、JDBCに相当する低水準プログラム・インタフェースです。ただし、XQJはまだ標準ではないため、Oracle Application Serverでは、サポートされていません。
XQSでは、同様の基礎機能のための高水準APIが提供されます。データソースに接続するためのコードを記述せずにJavaからXQuery式を実行したり、XQuery式のオブジェクトを作成するなどの処理が可能です。
XQSは様々な用途に使用できます。WebサービスおよびJavaアプリケーションだけでなく、XMLデータやXML以外のデータへのアクセスにも役立ちます。
また、XQSを使用すると、低水準のXQJインタフェースを使用してXQuery式を実行するなどの、コーディング手順を行う必要がありません。プログラム的でない構成を介したデータソース・アクセスのXQSモデルにより、より迅速に、より便利に開発が行えます。さらに、XQSによって作成される外部関数のライブラリの登録は自動的に処理され、名前空間の割当ては自由に制御できます。
データを取得するだけでなく、XQSは、XMLデータを変換したり、複数のソースからのデータを結合するための便利なメカニズムとしての機能を果します。
これ以外にも、XQSには次の利点と利便性があります。
「XQSのパフォーマンス機能および最適化機能の概要」も参照してください。
XQS実装には、次の要件、制限事項および特記事項があります。
(: Q1 :) declare namespace xqs="http://xmlns.oracle.com/ias/xqs"; declare function xqs:a() external; let $x := xqs:a() return $x/b is $x/b
ノードIDテストの対象が、同じファンクション・コールから取得されたノードであれば、Q1では、常にtrueが戻されます。
(: Q2 :) declare namespace xqs="http://xmlns.oracle.com/ias/xqs"; declare function xqs:a() external; xqs:a()/b is xqs:a()/b
Q2では、パフォーマンスの最適化の設定によって、trueまたはfalseが戻されます。
この項では、XQSの重要な機能の概要を説明します。詳細は、この章で後述しています。
前述のように、XQSでは、数種類のデータソースがサポートされています。この項には、次の関連項目が含まれます。
XQSでは、多様なアクセス・プロトコルが要求されるデータソースは、WSDLドキュメントを介して記述されます。これは、XQSのサポートにより、一般に普及しているApache Web Services Invocation Framework（WSIF）（SOAPやHTTPの背後にあるWebサービス・メカニズムの拡張機能）で、すべてのカスタム起動プロトコルが組み込まれるためです。このメカニズムにより、XQSは、SOAPベースのWebサービスではなく、WSDLベースのソースをサポートします。XQSでは、SQLで記述されたXQSビューのメカニズムを使用し、JDBCを介してリレーショナル・データベースにアクセスすることもできます。
XQSによってサポートされるすべてのデータソースのカテゴリは、次のとおりです。これらのデータソースには、SQLベースのビューまたはWSDLドキュメントを介して多様なソースにアクセスするための特別な機能があります。
fn:doc()の機能に似ています。XQSでは、XML以外のファイルもサポートしているため、XML以外のデータをXMLに変換するOracle Data Definition Description Language（D3L）トランスレータ・プラグインをサポートしています。
WSDLソース用に指定したWSDLドキュメントでは、適切なバインディングを使用して、一連のコール可能な操作が記述され、ソースへの接続に関する詳細が提供されます。XQS構成では、各操作の名前を参照し、WSDLをポイントして操作の説明を参照します。WSDLには作業URLが必要です。作業URLは、XQS構成で指定します。XQSでは、WSDLをフェッチする際にこのURLに移動します。また、XQSでは、WSDL URLをXQuery名前空間として使用することや、WSDLポートの個々の操作をその名前空間のローカル名として処理することが可能です。
データソースへのアクセスと操作の実行には、前述の、XQS関数と呼ばれる外部XQuery関数が使用されます。XQSは、XQS構成に基づいて、自動的に作成および起動されます。構成内で、関数の名前と名前空間、およびその他の関連項目（入力パラメータなど）を指定します。問合せでデータソースを使用する際には、XQueryプロローグで、関連するXQS関数を外部関数として宣言する必要があります。
名前空間は、関数オブジェクトを含む1つの関数ライブラリに対応します。各関数オブジェクトは、1つの操作に対応します。たとえば、SOAPバインディングを伴うWSDLソースの場合、WSDLドキュメント内の各操作に対して1つの関数オブジェクトがあります。XQSビュー・ソースでは、各関数オブジェクトは個々のストアド・クエリーに対応しています。
XQSによって作成されたそれぞれの関数オブジェクトは、XQS構成に従ってインスタンス化され、次の基本タスクを実行します。
XQSで使用できるほとんどのデータソースには、必要な準備手順があります。次に例を示します。
.xqファイルとして保存し、その配置場所を決定する必要があります。
詳細は、「データソースを使用するための準備」を参照してください。
XQS構成ファイルはxqs-config.xmlです。XQSは、アプリケーションEARファイルのトップレベルにあるxqs-resources.jarファイル（OC4Jパッケージ化ユーティリティで作成）で、この構成ファイルを検索します。この構成ファイルを使用して、XQS関数およびデータソースの情報を指定します。
xqs-config.xmlのトップレベルの要素は次のとおりです。
<document-source>を使用すると、XMLファイルまたはXML以外のファイルを含むドキュメントのデータにアクセスできます。
<xqsview-source>を使用すると、XQSビューを使用できます。
<wsdl-source>は、ユーザーが指定したWSDLドキュメントに関連するデータソースに使用できます。
XQSは、構成ファイルから情報を読み取り、その情報を使用して、データソースにアクセスするXQS関数オブジェクトを移入します。
構成の更新時には、OC4Jの再起動は不要ですが、アプリケーションを再デプロイする必要があります。（詳細は、『Oracle Containers for J2EEデプロイメント・ガイド』を参照してください。）
追加情報は、「XQS関数の構成方法」を参照してください。
XQSでは、XQuery機能の実装に使用できる、次のクライアント・インタフェースがサポートされています。各インタフェースの使用方法および例は、「アプリケーション・コードの開発方法: XQSクライアント・インタフェースを使用した場合」を参照してください。
|
注意 問合せにいずれかのXQSクライアントAPIを使用する場合、問合せの実行によって結果が定義されますが、すべての結果がただちにメモリーに格納されるとはかぎりません。メモリーにただちに、および完全に格納される一連の結果は、「マテリアライズされている」（実体がある）と表現されます。これに対して、暗黙カーソルを介し、次の項目を処理するための（next item）機能を使用して1回（バッチの場合は複数回）にアクセスされる一連の結果は、「マテリアライズされていない」（実体がない）と表現されます。マテリアライズされていない結果は、いつ取得されてメモリーに書き込まれるのかが保証されません。次の項目を処理する（next item）コールによって、次の結果項目を作成するXQuery式の評価がトリガーされます。 後続の説明のように、XQSクライアントAPIでは、マテリアライズされた結果に対してステートレス・クライアント・オブジェクトを使用するか、マテリアライズされていない結果に対してステートフル・クライアント・オブジェクトを使用するかを選択できます。 これらの概念の詳細および重要な考慮事項は、「ステートフル・クライアントとステートレス・クライアント」を参照してください。 |
XQSFacadeIが提供されます。このJavaインタフェースは、目的のXQuery機能のJava実装に使用できます。このインタフェースは、ファサードというデザイン・パターンに基づいており、表面上は、基礎となるXQS機能の詳細や複雑さが見えないようになっています。適切な実行（execute）メソッドを使用して、非定型問合せまたはXQSビュー名、およびバインド・パラメータを渡します。どちらの場合も、次の項目を取得する（get next item）メソッドを使用して、結果を処理します。問合せの実行後、XQSFacadeIインスタンスによりXMLの結果順序がラップされ、現在の状態が維持されます。順序の項目を段階的に取得して処理するか（ステートフル・アプローチ）、順序の全項目を一度に取得して処理し、その後基礎となるデータソース・リソースを解放するか（ステートレス・アプローチ）は、クライアントによって決まります。com.collaxa.cube.xml.xpath.functions.xml.GetElementFromXQueryFunction）用のJavaクラスが用意されています。このクラスはBPELプロセス付きのXPath関数として登録し、実行用にBPELプロセスとともにパッケージ化したXQueryのいずれかの名前を渡すことができます。
Objectインスタンスの配列として戻されます。
XQS
注意
QueryParameterIインタフェースにも注意する必要があります。JavaクライアントAPIまたはEJBクライアントAPIの外部バインドを伴う問合せを使用するには、そのバインド値のQueryParameterIオブジェクトの配列を作成する必要があります。「XQS QueryParameterIリファレンス」を参照してください。（このインタフェースも、JSPクライアント・インタフェースでは背後で使用されます。）
XQSで提供されるOC4JPackagerは、XQS関連のファイルをJ2EEアプリケーションまたはWebアプリケーションでパッケージ化し、そのアプリケーションでXQS機能を使用できるようにするコマンドラインJavaツールです。
通常は、XQSクライアントAPI（XQSFacadeIインタフェース、EJBクライアントAPIまたはJSPタグ・ライブラリ）の1つを介してXQSをコールするWebアプリケーションを書き込みます。また、関連するデータソースおよびXQSビューをポイントするXQS構成ファイルxqs-config.xmlを作成し、ビューが配置されているディレクトリであるXQSリポジトリを選択します。その後、アプリケーション、XQS構成ファイルおよびXQSリポジトリをEARファイルにバンドルします。このファイルは後でデプロイします。
コマンドライン・パラメータを介してOC4JPackagerに命令が出されると、すべてのバンドルの手順が自動的に完了します。具体的には、次の処理が行われます。
xqs-config.xmlおよびすべてのXQSリポジトリ・ファイルを、xqs-resources.jarというファイルにバンドルします。
MANIFEST.MF）内のClass-Path属性を変更して、xqs-resources.jarを含めます。
xqs-resources.jarで構成されるEARアーカイブをバンドルします。
orion-application.xmlファイルを（必要に応じて）作成または変更し、EARのすべてのコンポーネントがアクセスできるライブラリのリストにxqs-resources.jarを追加します。
OC4JPackagerを実行する際には、次のいずれかを含むディレクトリを指定します。
Webサービス操作として公開するXQSビューに対し、OC4JPackagerにより、Webサービス操作の起動がXQSビューに委譲され、追加のタスクが実行されます。操作は、自動的に生成されるWSDLドキュメントに追加されます。詳細は、「XQSビューをWebサービス操作として公開するためのOC4JPackagerの追加の出力」を参照してください。
一般的なOC4JPackagerの詳細は、「OC4JPackagerを使用したXQSアプリケーションのパッケージ方法」および「OC4JPackagerのリファレンス」を参照してください。
XQS自体では、セキュリティ層はまったく追加されません。この点で、XQSは本質的にJ2EEアプリケーションと似ています。セキュリティは、使用するXQSクライアントおよびアクセスするデータソースのタイプに応じて、必須のWebおよびJ2EEの標準セキュリティ機能を介して、OC4Jによって提供されます。
たとえば、SQLバインディングを伴うSQLベースのXQSビューを使用する場合は、データソース・セキュリティ機能を使用します。XQS EJBクライアント・インタフェースを使用する場合は、標準のEJBセキュリティを使用します。XQS JSPタグ・ライブラリを使用する場合は、標準のHTTP接続認証を使用します。その他を使用する場合も、それぞれのセキュリティ機能を使用します。
XQSでは、パフォーマンスを向上させる次の機能が提供されます。
詳細は、「XQSパフォーマンス機能の使用方法」を参照してください。
XQSアプリケーションの実行時には、入力パラメータをデータソースで要求されるタイプに変換する際や、データソースによって戻されたデータをXMLに変換する際などに、XQS外部関数および基礎となるデータソースに関連する問題が発生する場合があります。また、データソースが使用できない場合や、エラーが戻されることもあります。XQSのデフォルトの動作では、このような状況でXQuery動的エラーが発生します。それによって問合せの実行が停止し、結果が戻されなくなります。
XQS構成属性（onError）を使用して、より影響の少ない動作を選択すると、XQSを続行して、発生したエラーに関する追加情報を取得できます。使用できるエラー処理モードは次のとおりです。
emptySequenceモードまたはerrorMessageモードを使用した場合、そのモードの設定対象となったXQS外部関数の実行時にエラーが発生しても、問合せの実行は停止せず、必要に応じて後で取得できるようにXQSによって保存されます。XQSにより、空のXML順序（emptySequenceモードの場合）または1つのエラー・メッセージで構成される単一項目のXML順序（errorMessageモードの場合）が戻されます。errorMessageモードでは、XQS構成で固定エラー・メッセージを事前に構成しておくか、データソースから戻されたエラー・メッセージをそのまま使用することができます。
XQS外部関数の抑止されたエラーの情報は、XQSによって、XQSErrorIオブジェクトのイテレータ内に戻されます。
XQSでは、XQS関数内部のエラーにのみ、特別な処理が適用されます。構文エラーやタイプの不一致などの通常のXQueryエラーの場合は、いずれのXQSエラー・モードでも、問合せの実行が停止します。
XQSエラー・モードは、XQS関数ごとに個別に構成します。1つの関数のエラー・モードが、同じ問合せ内の他のXQS関数の動作に影響することはありません。
詳細は、「XQSエラー処理モードおよびAPIの使用方法」を参照してください。
XQSを使用する場合の主な手順を次に示します。各手順の詳細を記述した項へのリンクも提供しています。
xqs-config.xmlファイルを使用して、アクセスするデータソースおよび実行する問合せの指定と構成を行い、問合せのデータソースを表すXQS関数へのマッピングを作成します。「XQS関数の構成方法」を参照してください。
XQSで使用するほとんどのデータソースには、必要な準備手順があります。この項には、次の項目が含まれます。
ドキュメントの中には、ネイティブのメッセージ書式としてXMLを使用せず、バイトおよび文字の構造化された記録などのネイティブ書式を使用するものがあります。この例として、Excelのカンマ区切り（CSV）ファイルがあります。XQSおよびXQueryでXML以外のデータが理解されるには、XQSで適切な変換ツールを使用できることが必要です。そのためには、事前定義済の、構造化された一連の規則にデータが従っている必要があります。このような構造化された書式のデータは処理が可能なため、取得されてからXML書式に変換され、アプリケーションで使用できるようになります。
XML以外のドキュメントを使用できるように、XQS実装では、Oracle Data Definition Description Language（D3L）をサポートしています。XQSでXML以外のドキュメントを使用するための準備として、次の手順を行います。
次の各項では、D3Lおよびその使用方法の概要を示します。
D3Lには、ネイティブの、XML書式以外のドキュメントが従う必要がある構造が記述されます。これにより、特定のOracleの中間層コンポーネント（OracleAS Integration InterConnectが一般的ですが、ここではXQS）で処理されるようになります。
D3Lによって提供されるものは、次のとおりです。
D3Lスキーマ・ファイルは、D3L Document Type Definition（DTD）によって定義された構文に準拠している必要があります。XQS構成を介して、使用するD3Lスキーマ・ファイルを指定します。
D3Lスキーマ・ファイルには、D3L変換エンジンがデータを解析してXMLに変換するために必要な、データ型、書式およびデリミタが記述されています。このスキーマ・ファイルは、d3l.dtdの仕様に準拠する必要があります。
D3Lスキーマ・ファイルの詳細および作成方法は、『Oracle Application Server Integration InterConnectユーザーズ・ガイド』を参照してください。ここでは、このファイルの概要がわかるように、ファイルの一部分を示します。
<?xml version="1.0" encoding="US-ASCII"?> <!DOCTYPE message SYSTEM "d3l.dtd"> <message name="replyFlight" type="BookingReplyType" object="Booking" header="D3L-Header" value="replyOptions"> <unsigned4 id="u4" /> <unsigned2 id="u2" /> <struct id="DateTimeRecord"> <field name="DateInfo"> <date format="MMDDYY"> <pfxstring id="datstr" length="u4" /> </date> </field> <field name="TimeHour"><limstring delimiter="*" /></field> <field name="TimeMinute"><limstring delimiter="*" /></field> </struct> ... </message>
XML以外のドキュメント・ソースに対し、XQSでD3Lの変換メカニズムを使用するには、次の手順を行います。
<document-source>の<XMLTranslate>サブ要素を使用して、D3Lを使用するようにXQSに対して指定します。（後で、その他のツールもサポートして、同様に指定することができます。）
<XMLTranslate>の<schema-file>サブ要素を使用して、データ解析に使用するD3Lのスキーマ・ファイルを指定します。
次に、PersonalInfoD3L.xmlという名前のD3Lスキーマ・ファイルを使用するためのXQS構成を示します。
<document-source ... > ... <XMLTranslate method="D3L"> <schema-file>http://host:port/xqs/PersonalInfoD3L.xml</schema-file> </XMLTranslate> ... </document-source>
前述のように、XQSビューとは、将来使用できるように格納された問合せです。XQSでは、ビュー自体がソースとして扱われるため、ビューの構成は、<xqsview-source>要素を介して行います。問合せをXQSビューとして使用するための準備手順は、次のとおりです。
.xqファイルとして保存します。（「問合せの設計方法」も参照してください。）
.xqファイルの保存場所を考慮します。.xqファイルの保存場所は、XQSリポジトリと呼ばれます。この場所は、XQS構成を介して（<repository>要素を使用して）指定できるほか、OC4JPackagerの実行時に-repositoryオプションを介して指定した場所を使用することもできます。
<xqsview-source>要素のWSDLvisibility属性を介して行います。これにより、1つの操作としてWebサービスにビューが含められ、XQSによってアプリケーションに追加されます。Webサービス操作としてビューを公開する場合は、XMLの出力タイプに注意してください。この出力タイプを、構成に含まれる<xqsview-source>の<output-element>サブ要素に反映することをお薦めします。（追加情報として、「Webサービス操作として公開されたXQSビューの使用方法」も参照してください。）
次に示すのは、XQSビューに使用するXQuery式です。この式では、外部変数locが受け入れられ、ファイルから注文（purchase order）データを読み取る関数readFileに渡されます。.xqファイルの保存時には目的の名前を付け、XQS構成でその名前を指定できます。ビューを実行するためにXQSが実装するXQS関数にも、目的の名前を指定する必要があります。ファイル名と関数名は別個のものですが、必要に応じて、デフォルトで関数名をファイルのベース名として使用できます。
declare variable $loc external; declare namespace xqs = "http://xmlns.oracle.com/ias/xqs"; declare function xqs:readFile($l as xs:string) external; for $po in xqs:readFile($loc)//po return $po//total
通常、XQS構成の<xqsview-source>要素の中では、少なくとも次のものを使用します。
WSDLvisibility属性、また、実際にビューを公開する場合は<output-element>サブ要素
<function-name>サブ要素
loc）を指定するための、<input-parameters>サブ要素およびそのサブ要素
.xqファイルの名前を指定するための<queryName>サブ要素（XQS関数名と同じファイル・ベース名を使用する場合を除く）
.xqファイルの場所を指定するための<repository>サブ要素（OC4JPackagerの実行時に-repositoryオプションを介して指定した場所にファイルがある場合は不要）SQLベースのXQSビューを使用すると、リレーショナル・データベースから取得したデータに（XMLのサポートも含め）XQueryを使用できます。データはJDBC経由で取得されます。SQLベースのXQSビューは、SQL言語で記述されたストアド・クエリーです。XQSでは、SQLベースのビュー自体がソースとして扱われます。ビューは、<xqsview-source>要素を介して構成されます。
SQL問合せをXQSビューとして使用するには、次の手順を実行します。
data-sources.xml構成ファイルで、適切な<managed-data-source>または<data-source>要素を探すか定義します。そのデータソースのJNDI名を、<xqsview-source>構成要素の参照として使用します。データソースのJNDI名は、<xqsview-source>要素の<dataSource>サブ要素に明示的に指定します。XQSでは、JDBC接続の確立にデータソースを使用します。SQL問合せに基づいたXQSビューの場合、<dataSource>構成要素は必須です。
:1、:2、:3などの位置指定のバインド変数を使用します。
SELECT文）のみが実行されます。問合せでは、JavaまたはPL/SQLストアド・プロシージャを起動できます。INSERTやUPDATEのSQL文、またはデータ定義言語（DDL）文は使用できません。問合せを.sqlファイルとして保存します。
XMLType型の場合、XQSでは結果はそのまま使用され、変換は行われません。結果がすでにXML形式であることを指定するには、XMLTypeにSQLResultType属性を設定します（データベースへの追加のラウンドトリップが必要で、パフォーマンスが低下するため、XQSでは問合せの独自の分析は行われません）。データベース問合せでデータをリレーショナル形式で戻す場合は、SQLResultType属性がrelationalに設定されている必要があります（これはデフォルトでもあります）。この場合、XQSはOracle XML-SQLユーティリティ（XSU）を使用して、リレーショナルの結果をXMLに変換します。XSUでは、結果セットのすべての行がXML要素に変換されます。デフォルトの要素名はROWです。デフォルトの要素は、<xqsview-source>構成要素のrowTag属性を設定することでカスタマイズできます。行要素は、ユーザーが選択した属性で番号付けできます。XSUでは、デフォルトでは行要素には番号は割り当てられません。行を番号付けする場合は、<xqsview-source>構成要素のrowIdAttr属性を指定します。rowIdAttr属性の値は、結果の行要素の番号付け属性の名前です。行は1から開始して、1、2、3のように番号付けされます。
XSUでは、リレーショナルの結果の各列を、行要素にネストする要素に変換します。要素タグは、列名から導出されます。列要素名はカスタマイズできません。ただし、SQL問合せでリレーショナルの結果を作成する場合には、列に別名を割り当てられます。
たとえば、デフォルトのOracle Order EntryスキーマOEで実行される次のようなSQL問合せがあるとします。
select PRODUCT_ID,PRODUCT_NAME,PRODUCT_STATUS,LIST_PRICE from PRODUCT_INFORMATION where product_id < :1
rowTag="product"およびrowIdAttr="record_num"属性が設定されている場合、このSQLベースのビューの実行結果は次のようになります。
<product record_num="1"> <product_id>1726<product_id> <product_name>LCD Monitor 11/PM<product_name> <product_status>under development<product_status> <list_price>259<list_price> </product> <product record_num="2"> <product_id>1729<product_id> <product_name>Chemicals - RCP<product_name> <product_status>orderable<product_status> <list_price>80<list_price> </product>
SQL問合せを記述する際には、前述のXML変換も考慮してください。
.sqlファイルを保存する場所を決定します。.sqlファイルの保存場所は、XQSリポジトリと呼ばれます。場所はビュー・ソースのXQS構成を介して（<repository>要素を使用して）指定します。または、OC4JPackagerユーティリティの実行時に-repositoryオプションを使用して指定します。同じリポジトリに複数の.xqおよび.sqlファイルを保存できます。前の例のSELECT文は、SQLベースのXQSビューで使用される式です。SQLバインド変数:1を受け入れてSQL問合せを実行し、結果を要素のXML順序の形式で戻します。.sqlファイルは任意の名前で保存し、XQS構成に指定できます。ビューを実行するXQSビュー関数の名前は、getProductInfoです。.sqlファイルの名前と関数名は別個のものですが、関数名はファイルのデフォルトのベース名と同一にできます。
次に示す要素および属性は、通常、SQLベースのXQSビュー用のXQS構成で使用されます。要素は、<xqsview-source>要素のサブ要素です。
<function-name>サブ要素は、ビューにXQS関数の目的の名前を指定するために使用されます。<dataSource>サブ要素は、data-sources.xml構成ファイルに定義されているデータソースのJNDI名を指定するために使用されます。データソースは、JDBC接続の確立に使用されます。このサブ要素は、SQLベースのビューには必須です。<input-parameters>サブ要素およびその<part>サブ要素は、XQS関数の入力パラメータに対応するバインド変数を指定するために使用されます。SQLバインド変数は位置によってバインドされるため、この場合、<part>サブ要素のname属性は無視されますが、位置属性は重要です（前の例で説明されているように、:1はposition="1"と等価です）。<xqsview-source>要素のfetchSize属性は、一度のラウンドトリップでデータベースから複数の行が転送されるよう設定するために使用されます。デフォルトは1です。この属性は、java.sql.PreparedStatementのsetFetchSizeメソッドへのコールに変換されます。JDBCのsetFetchSizeパラメータは（つまり、XQSのfetchSize属性も）単なるヒントであり、バインディングではありません。<queryName>サブ要素は、SQL問合せが含まれている.sqlファイルの名前を指定するために使用されます（XQS関数名と同じベース・ファイル名を使用する場合を除く）。<repository>サブ要素は、.sqlファイルの場所を指定するために使用されます（OC4JPackagerユーティリティの使用時に-repositoryオプションを介して指定した場所にファイルがある場合は不要）。
次に示す<xqsview-source>要素の属性はオプションです。属性が設定されていない場合は、デフォルト値が使用されます。
Webサービス操作を介してデータソースにアクセスするには、WebサービスのWSDLドキュメントを指定し、XQS構成でWSDLの場所を指定する必要があります。1つのXQSビュー関数は、XQSによって実装される1つのWebサービス操作に対応します。
WSDLを調査します。XQS構成ファイルに含まれる<wsdl-source>要素およびそのサブ要素を使用して、XQS関数を構成します。その際、次に示すように、WSDLエントリに対応する構成設定（一部はオプション）を使用します。
<operation>要素に対応します。
<input-parameters>の<part>サブ要素に対応します。
<service>要素に対応します。
<port>要素に対応します。
<portType>要素に対応します。
また、XQSからWSDLドキュメントへのアクセス方法を考慮し、<wsdlURL>要素を使用してドキュメントの場所を指定します。
|
注意
|
Java用またはEJB用のWSIFプロバイダを使用すると、カスタムJavaクラスまたはEJBを介してデータソースにアクセスできます。これは、Apache Foundationの公開テクノロジであるため、XQSによる特別な動作は行われません。必要な手順は次のとおりです。
XQS構成に関するWSDLの一般的な考慮事項は、「SOAPバインディングを伴うWSDLソースを使用するための準備」を参照してください。
クラスまたはBeanの実装方法は、『Oracle Application Server Web Services開発者ガイド』、また、Java用およびEJB用のWSIFプロバイダの情報は、『Oracle Application Server Web Servicesアドバンスト開発者ガイド』を参照してください。
Javaバインディングを伴うWSDLドキュメントの一部を例として示します。これを使用すると、操作名に基づいて、JavaメソッドreadEntry()などを起動できます。WSDLの<format:typeMapping>の仕様は、XQS構成の<typeMap>要素に対応することに注意してください。
< definitions> ... <binding name="JavaBinding" type="tns:AddressBook"> <java:binding /> <format:typeMapping encoding="Java" style="Java"> <format:typeMap typeName="typens:address" formatType = "localjava.client.stub.addressbook.wsiftypes.Address" /> <format:typeMap typeName="xsd:string" formatType="java.lang.String" /> </format:typeMapping> <operation name="readEntry"> <java:operation methodName="readEntry" parameterOrder = "name" methodType = "instance" /> <input name="ReadEntryWholeNameRequest" /> <operation name="readAllMatchingEntries"> ... </operation> </binding> <service name="AddressBookService"> <port name="JavaPort" binding="tns:JavaBinding"> <java:address className = "localjava.service.AddressBookImpl" /> </port> </service> ... </definitions>
すべてのXQuery式で使用されるそれぞれのXQuery外部関数、つまり、XQSによって実装されるそれぞれのXQS関数に対して、アプリケーションのXQS構成内に、問合せ、アクセスするデータソースおよび入力パラメータに使用されるXQS関数の詳細（名前など）を指定する1つのエントリが必要になります。構成には、ドキュメント・ソース、XQSビュー、WSDLソースの3つの基本カテゴリがあります。また、これらに対応する<document-source>、<xqsview-source>、<wsdl-source>という3つの高レベルの構成要素があります。
この項には、次の項目が含まれます。
XQS構成ファイルの関連する概要は、「XQSの構成および構成ファイルの概要」を参照してください。
この項で説明した構成要素のリファレンス情報は、「XQS構成ファイルのリファレンス」を参照してください。
この項では、ドキュメント・ソースにアクセスするXQS関数の構成方法を説明し、最後に例を示します。この項に出てくる要素は、<document-source>要素のサブ要素です。追加情報は、「<document-source>」を参照してください。すべてのサブ要素の情報へのリンクも含まれています。
ドキュメント・ソースに対して、少なくとも次の要素を構成する必要があります。
<function-name>: この要素を介して、ドキュメント・ソースへのアクセス用にXQSによって実装されるXQS関数の修飾名を指定します。この要素の値はローカル名で、名前空間の属性（namespaceまたはprefix。詳細は「<function-name>」を参照）があります。XQS関数をXQuery外部関数として宣言する際には、XQueryのプロローグでも同じ名前を使用する必要があります。構成の例を示します。
<document-source ... > <function-name namespace="http://xmlns.oracle.com/ias/xqs"> myFileSource </function-name> ... </document-source>
対応するXQueryの宣言と使用方法は次のとおりです。
declare namespace xqs = "http://xmlns.oracle.com/ias/xqs"; declare function xqs:myFileSource() external; for $po in xqs:myFileSource()//po return $po
場合により必須または適切であるドキュメント・ソースの要素は、次のとおりです。
<documentURL>: この要素を使用して、ドキュメント・ソースのURLを指定します。次に例を示します。
<document-source ... > ... <documentURL> http://host:port/xqsdemos/Repository/pos-2KB.xml </documentURL> ... </document-source>
<documentURL>要素を指定すると、XQS関数が引数を取らないことを暗黙的に指定することになります。<documentURL>を省略することもできます。その場合は、次の例で示すように、実行時にURLをXQS関数に渡す必要があります。また、この関数をXQueryで宣言して、URL用のパラメータを1つ定義する必要があります。
declare namespace xqs = "http://xmlns.oracle.com/ias/xqs"; declare function xqs:myFileSource($bind as xs:string) external; for $po in xqs:myFileSource ("http://host:port/xqsdemos/Repository/pos-2KB.xml")//po return $po
<output-element>: このサブ要素を使用すると、XML要素の修飾名または戻されたデータの出力型（単純型または複合型）を指定できます。このサブ要素は常に必須ではありませんが、この情報は、XQSによるタイプ・チェックに使用できます。次に例を示します。
<document-source ... > ... <output-element namespace="http://xmlns.oracle.com/ias/xqs/CustomerDemo" location="http://host:port/xqsdemos/Customers.xsd"> type=Customers </output-element> ... </document-source>
<output-element>を定義する<xqsview-source>要素については、基になる問合せ、または別の<xqsview-source>関数を使用してネストされている問合せのerrorMessageエラー処理オプションを定義するXQS関数ごとに、<output-element>サブ要素を使用する必要があります。この要件の詳細は、「XQSエラー処理モードおよびAPIの使用方法」を参照してください。
<XMLTranslate>: XML以外のドキュメント・ソースについては、この要素を使用して、使用する変換ツールを指定し、そのツールに必要なすべての情報を指定します。現在サポートされているのはD3Lのみです。D3Lを使用するには、<schema-file>サブ要素を介してD3Lスキーマ・ファイルを指定する必要があります。D3Lの詳細は、「XML以外のドキュメント・ソースを使用するための準備」を参照してください。 次に例を示します。
<document-source ... > ... <XMLTranslate method="D3L"> <schema-file> http://host:port/xqsdemos/paymentInfoD3L.xml </schema-file> </XMLTranslate> ... </document-source>
エラー処理の設定を行い、キャッシングやラージ・データセットの特別な処理などのパフォーマンス機能の使用を指定できます。これらの設定には、<document-source>の属性isCached、largeData、onError、およびサブ要素の<cache-properties>と<error-message>を使用します。これらの機能の構成は、ここでは省略します。「XQSエラー処理モードおよびAPIの使用方法」および「XQSパフォーマンス機能の使用方法」を参照してください。
それぞれの例では、キャッシング、ラージ・データおよびエラー処理のデフォルト設定が使用されています。これは、<document-source>属性がisCached="false"、largeData="false"およびonError="dynamicError"と設定されていることと同じです。
固定の場所にあるXML文書のソースの例を示します。
<document-source> <function-name namespace="http://xmlns.oracle.com/ias/xqs"> myFileSource </function-name> <documentURL> http://host:port/xqsdemos/Repository/pos-2KB.xml </documentURL> </document-source>
D3L変換ツールおよびpaymentInfoD3L.xml D3Lスキーマ・ファイルを使用する、XML書式以外のドキュメント・ソースの例を示します。
<document-source> <function-name prefix="xqs"> paymentStatusInfo </function-name> <documentURL>http://host:port/xqsdemos/paymentInfo.csv</documentURL> <XMLTranslate method="D3L"> <schema-file> http://host:port/xqsdemos/paymentInfoD3L.xml </schema-file> </XMLTranslate> </document-source>
この項では、XQSビューを使用するXQS関数の構成方法を説明し、最後に例を示します。この項に出てくる要素は、<xqsview-source>要素のサブ要素です。追加情報は、「<xqsview-source>」を参照してください。すべてのサブ要素の情報へのリンクも含まれています。
使用するXQSビューの作成方法などの準備手順は、「XQSビューを使用するための準備」を参照してください。
<xqsview-source>の属性設定WSDLvisibility="true"を使用すると、XQSビューをWebサービス操作として公開できます。XQSによって生成されるWSDLに、その操作が追加されます。Webサービス操作は、そのアプリケーションのWebサービスの一部になります。WSDLvisibility属性はオプションで、デフォルト値はfalseです。
XQSビューをWebサービスとして公開する場合の詳細情報は、「XQSビューをWebサービス操作として公開するためのOC4JPackagerの追加の出力」を参照してください。
後述の説明は、次に示す例がXQSビューとしてmytotals.xqに保存されていることを前提としています。この例では、ファイルからデータを読み取る関数が使用されており、入力パラメータloc（ファイルの場所を示す文字列変数）を取得して関数に渡し、整数の合計を戻します。
declare variable $loc external; declare namespace xqs = "http://xmlns.oracle.com/ias/xqs"; declare function xqs:readFile($l as xs:string) as xs:int external; for $po in xqs:readFile($loc)//po return $po//total
XQSビューを使用するには、少なくとも次の要素を構成する必要があります。
<function-name>: この要素を介して、ビューの実行用にXQSによって実装されるXQS関数の修飾名を指定します。この要素の値はローカル名で、名前空間の属性（namespaceまたはprefix。詳細は「<function-name>」を参照）があります。（executeView()コールで直接ビューを使用するのではなく）問合せでこの関数を使用する場合には、<function-name>要素で指定した関数名を使用して、このXQS関数をXQuery外部関数として宣言する必要があります。構成の例を示します。
<xqsview-source ... > <function-name namespace="http://xmlns.oracle.com/ias/xqs"> totals </function-name> ... </xqsview-source>
<input-parameters>: XQSビューで外部変数（SQLベースのビューの場合はバインド変数）が使用される場合は、XQSによって実装されるこの関数で、ビュー内の外部変数またはバインド変数ごとに、入力パラメータを使用する必要があります。問合せの実行前に、XQSによって、外部またはバインド変数に関数の引数の値が割り当てられます。<input-parameters>要素を使用して、入力パラメータを構成します。その際には、パラメータごとに1つの<part>サブ要素を使用します。XQSビューでは、この要素は常に必須です。入力パラメータがない場合は、空の要素を使用してください。
<xqsview-source ... > ... <input-parameters/> ... </xqsview-source>
外部文字列変数locにバインドされる1つの入力パラメータを使用した例を次に示します。XQSビューの入力パラメータには、<schema-type>または<xquery-sequence>要素を使用して、オプションでタイプ情報を指定することができます。この例は、xs接頭辞がXML Schemaの名前空間に対応するように設定されていることを前提としています。（<input-parameters>、<part>、<schema-type>および<xquery-sequence>の各要素の詳細は、この章の後半部分に含まれているリファレンス・ドキュメントを参照してください。）
<xqsview-source ... > ... <input-parameters type-match="none" > <part position="1" name="loc"> <schema-type prefix="xs">string</schema-type> </part> </input-parameters> ... </xqsview-source>
SQLベースのビューのバインド変数は、:1、:2などの位置で示されます。同一の<input-parameters>および<part>構成要素を使用します。<part>には名前属性を指定する必要がありますが、名前の値は無視されます。SQLバインド変数は、1つ目の位置の引数は:1に、2つ目の位置の引数は:2などのように、実際の引数の位置によってそれぞれの値にバインドされます。
次の例では、問合せでのXQSビューの使用方法を示します。XQueryの宣言および使用方法は、前述の<function-name>および<input-parameters>の説明に対応しています。
declare namespace xqs = "http://xmlns.oracle.com/ias/xqs"; declare function xqs:totals($loc as xs:string) as xs:int external; for $t in xqs:totals("C:¥MyPurchaseOrders.xml") return <outstanding_balance> fn:sum($t) </outstanding_balance>
場合により必須または適切であるXQSビューの要素は、次のとおりです。
<output-element>: この要素を使用すると、XML要素の修飾名または戻されたデータの出力型（単純型または複合型）を指定できます。WSDLvisibility="true"を使用するXQSビューでは、特に<output-element>要素の使用が適しており、その属性であるlocationは、要素定義またはタイプ定義を含むXMLスキーマ・ファイルをポイントする必要があります。次に例を示します。
<xqsview-source WSDLvisibility="true"> ... <output-element namespace="http://xmlns.oracle.com/ias/xqs/CustomerDemo" location="http://host:port/xqsdemos/Customers.xsd"> </output-element> ... </xqsview-source>
WSDLvisibility="false"を使用するXQSビューでも、<output-element>要素を使用するとタイプ・チェックに役立ちます。接頭辞xsは、XML Schemaの名前空間に対応するように設定されているとします。
<xqsview-source WSDLvisibility="false"> ... <output-element prefix="xs">integer</output-element> ... </xqsview-source>
<queryName>: この要素を使用して、XQSビューを保存した.xqまたは.sqlファイルの名前を指定します。.xqまたは.sql拡張子は指定してもしなくても構いません（必要に応じて自動的に追加されます）。この<queryName>要素はオプションです。この要素を省略した場合、.xqまたは.sqlファイルのベース名は<function-name>要素で指定されたXQS関数名と同じであるとみなされます。
XQueryベースのXQSビュー・ファイルの拡張子は
注意
.xqである必要があります。SQLベースのビュー・ファイルの拡張子は.sqlである必要があります。<xqsview-source>構成要素に<dataSource>サブ要素が含まれている場合のみ、XQSではビューがSQLベースであるとみなされます。詳細は、「SQLベースのXQSビューに固有の考慮事項（必須）」を参照してください。
mytotals.xqに保存されたXQSビューの例を示します。
<xqsview-source ... > ... <queryName>mytotals</queryName> ... </xqsview-source>
<function-name>要素に関する前述の例では、<queryName>を省略すると、XQSによってtotals.xqという名前のファイルが検索されます。
<repository>: この要素を使用して、XQSビュー・リポジトリの場所（.xqまたは.sqlファイルの場所）を指定します。この要素を省略した場合は、OC4JPackagerの-repositoryオプションを使用して指定したリポジトリとみなされます。次に例を示します。
<xqsview-source ... > ... <repository>META-INF/xqs/mydir</repository> ... </xqsview-source>
SQLResultType: <xqsview-source>要素のオプションの属性で、SQLベースのビューにのみ適用できます。この属性では、データベース問合せで、データをリレーショナル（表）形式またはXMLのいずれで戻すかを設定します。SQLResultTypeのデフォルト値は、relationalです。Oracle XMLデータベースを使用している場合は、SQLResultType属性をXMLTypeに設定することで、SQLベースのXQSビューを使用して（それ以上変換せずに）データベースからXML型の値を選択できます。XQSでは、リレーショナルからXMLへの変換をデータベースの結果に適用するかどうかの決定は、SQLResultType属性のみに依存します。データベースへの追加のラウンドトリップが必要で、パフォーマンスが低下するため、XQSでは問合せの独自の分析は行われません。データベース問合せでデータをリレーショナル形式で戻す場合は、SQLResultType属性が、明示的にまたはデフォルトでrelationalに設定されている必要があります。この場合、XQSはOracle XML-SQLユーティリティ（XSU）を使用して、リレーショナルの結果をXMLに変換します。
rowTagおよびrowIdAttr: <xqsview-source>要素のオプションの属性で、SQLベースのビューにのみ適用できます。これらの属性が指定されている場合、データベースの結果のリレーショナルからXMLへの変換で使用された要素および属性のデフォルト名は、これらの値でそれぞれ上書きされます。これらの属性は、SQLResultType属性がrelationalに設定されている場合にのみ適用可能です。XSUでは、結果セットのすべての行がXML要素に変換されます。デフォルトの要素名はROWです。デフォルトの要素は、<xqsview-source>構成要素のrowTag属性を設定することでカスタマイズできます。行要素は、ユーザーが選択した属性で番号付けできます。XSUでは、デフォルトでは行要素には番号は割り当てられません。行を番号付けする場合は、<xqsview-source>構成要素のrowIdAttr属性を指定します。rowIdAttr属性の値は、結果の行要素の番号付け属性の名前です。行は1から開始して、1、2、3のように番号付けされます。設定rowIdAttr=""はデフォルトの動作と同じで、行の番号付け属性を抑止します。
rowTagおよびrowIdAttr属性は、それぞれ別々に使用されます。つまり、指定できる属性は1つのみで、もう一方にはデフォルトを使用します。
fetchSize: <xqsview-source>要素のオプションの属性で、SQLベースのビューにのみ適用できます。fetchSizeは、JDBCを介した1回のラウンドトリップでデータベースから取得する行数を推奨します。この属性は、java.sql.PreparedStatementのsetFetchSizeメソッドへのコールに変換されます。JDBCのsetFetchSizeパラメータは（つまり、XQSのfetchSize属性も）単なるヒントであり、実装で無視される場合もあります。fetchSize属性のデフォルト値は1です。
XMLFormat: <xqsview-source>要素のオプションの属性で、現在使用できる値はデフォルトのXSUのみです。その他の値は今後のリリースで使用できるようになり、WebRowset形式の結果がサポートされます。現行リリースの制限は、JDK 1.5機能への依存性が原因です。
WSDLvisibility属性をtrueに設定すると、ビューのWebサービス操作が生成され、WSDLドキュメントにこの操作の定義が含められます。次に示すように、<xqsview-source>の<output-element>の内容により、WSDL操作の出力メッセージのタイプが決定されます。
<output-element>を省略した場合、WSDL操作の出力メッセージの結果タイプは、次のように宣言されます。
<sequence> <any/> </sequence>
<output-element>が存在する場合は、その中で、名前空間属性または接頭辞属性の書式で出力要素の名前空間が指定されている必要があります。この名前空間は、WSDLでは<import>要素になります。次に例を示します。
<output-element namespace="urn:PurchaseOrders" location="http://myhost:80/myapp/PurchaseOrders.xsd" />
このコードにより、WSDLで次のインポート要素が生成されます。
<types> <schema...> <import namespace="urn:PurchaseOrders" schemaLocation="http://myhost:80/myapp/PurchaseOrders.xsd" /> ... </schema> </types>
ロケーション属性を使用することで、WSDLの<import>要素がより完全になります。そのため、ロケーション属性はできるかぎり指定してください。
<output-element>で属性タイプが指定される場合は、この属性がnamespace属性またはprefix属性とともに使用され、結果要素タイプの修飾名が作成されます。<output-element>のテキスト値は、結果要素自体の名前として使用されます。次に例を示します。
<output-element namespace="urn:PurchaseOrders" location="http://myhost:80/myapp/PurchaseOrders.xsd" type="POType" > po </output-element>
このコードは、前述の<import> 要素と、次に示すWSDL操作の結果タイプの定義になります。
<complexType name="POswithRetTypeResultType"> ... <element name="result" nillable="true"> <complexType > <sequence> <element name="po" xnlns:_ns1="urn:PurchaseOrders" type="_ns1:POType" minOccurs="0" maxOccurs="unbounded" /> </sequence> ...
<output-element>によってtype属性が指定されない場合は、WSDL操作の出力メッセージの結果要素は、インポートされたスキーマの要素への参照として宣言されます。たとえば、次の構成要素があるとします。
<output-element namespace="urn:PurchaseOrders" location="http://myhost:80/myapp/PurchaseOrders.xsd"> polist </output-element>
このような要素は、WSDLで次のような結果定義を生成します。
<complexType name="POListResultType"> ... <element name="result" nillable="true"> <complexType > <sequence> <element ref="_ns1:polist" minOccurs="0" maxOccurs="unbounded" /> </sequence> ...
<output-element>によってtype属性が指定されていても、それが空の（text要素値がない）場合、XQSでは、結果要素の固定名itemが使用されますが、指定されたタイプ名が使用されます。たとえば、次の構成があるとします。
<output-element namespace="urn:PurchaseOrders" location="http://myhost:80/myapp/PurchaseOrders.xsd" type="POType" />
このような構成では、次のような結果要素の定義が生成されます。
<complexType name="POsResultType"> ... <element name="result" nillable="true"> <complexType > <sequence> <element name="item" xnlns:_ns1="urn:PurchaseOrders" type="_ns1:POType" minOccurs="0" maxOccurs="unbounded" /> </sequence>
<dataSource>: XQSにデータベース接続情報を提供します。SQL問合せに基づいたXQSビューには、<dataSource>構成要素が必須です。OC4J data-sources.xml構成ファイルの<managed-data-source>または<data-source>要素に定義されているように、<dataSource>要素にはデータソースのJNDI名が含まれている必要があります。
エラー処理の設定を行い、キャッシングやラージ・データセットの特別な処理などのパフォーマンス機能の使用を指定できます。これらの設定には、<xqsview-source>の属性isCached、largeData、onError、およびサブ要素の<cache-properties>と<error-message>を使用します。これらの機能の構成は、ここでは省略します。「XQSエラー処理モードおよびAPIの使用方法」および「XQSパフォーマンス機能の使用方法」を参照してください。
次の例では、前に示したそれぞれの部分を1つにまとめてXQS関数totalsが構成されています。また、文字列変数loc（ファイルの場所用）を使用して整数の結果が出力されます。便宜上、ここでもXQSビューmytotals.xqを使用します。
declare variable $loc external; declare namespace xqs = "http://xmlns.oracle.com/ias/xqs"; declare function xqs:readFile($l as xs:string) external; for $po in xqs:readFile($loc)//po return $po//total
次の例では、キャッシング、ラージ・データおよびエラー処理のデフォルト設定が使用されています。これは、<xqsview-source>属性がisCached="false"、largeData="false"およびonError="dynamicError"と設定されていることと同じです。XQSは、Webサービスとして公開されません。
<xqsview-source WSDLvisibility="false"> <function-name namespace="http://xmlns.oracle.com/ias/xqs"> totals </function-name> <input-parameters type-match="none" > <part position="1" name="loc"> <schema-type prefix="xs">string</schema-type> </part> </input-parameters> <repository>META-INF/xqs/mydir</repository> <queryName>mytotals</queryName> <output-element prefix="xs">int</output-element> </xqsview-source>
この項では、WSDLベースのソースにアクセスするXQS関数の構成方法について説明し、最後にWSDLドキュメントの一部分の例および対応する構成を示します。この項に出てくる要素は、<wsdl-source>要素のサブ要素です。追加情報は、「<wsdl-source>」を参照してください。すべてのサブ要素の情報へのリンクも含まれています。
使用するWSDLソースのタイプにより、「SOAPバインディングを伴うWSDLソースを使用するための準備」または「カスタム・クラスまたはEJBを使用するための準備（JavaまたはEJBのバインディングを伴うWSDLソース）」も参照してください。
WSDLソースに対して、少なくとも次の要素を構成する必要があります。
<function-name>: この要素を介して、WSDLソースへのアクセス用にXQSによって実装されるXQS関数の修飾名を指定します。この要素の値はローカル名で、名前空間の属性（namespaceまたはprefix。詳細は「<function-name>」を参照）があります。XQS関数をXQuery外部関数として宣言する際には、XQueryのプロローグでも同じ名前を使用する必要があります。構成の例を示します。
<wsdl-source ... > <function-name namespace="http://xmlns.oracle.com/ias/xqs"> getmySearchCachedPage </function-name> ... </wsdl-source>
<input-parameters>: それぞれのWSDLソースで、XQSによって実装される関数は、WSDLで指定された入力パートごとに1つの入力パラメータを使用する必要があります。<input-parameters>要素を使用して、入力パラメータを構成します。その際には、パラメータごとに1つの<part>サブ要素を使用します。WSDLソースでは、この要素は常に必須です。入力パラメータがない場合は、空の要素を使用してください。
<wsdl-source ... > ... <input-parameters/> ... </wsdl-source>
次に、2つの入力パラメータを使用した例を示します。ここでは、外部文字列変数keyおよびurlを使用しています。<schema-type>要素を介して指定するタイプ情報は、WSDLソースの入力パラメータでは必須ではありませんが、使用すると、Webサービスの起動時にタイプ・チェックを実行できます。次の例は、xs接頭辞がXML Schemaの名前空間に対応するように設定されていることを前提としています。（<input-parameters>、<part>および<schema-type>の各要素の詳細は、この章の後半部分に含まれているリファレンス・ドキュメントを参照してください。）
<wsdl-source ... > ... <input-parameters> <part position="1" name="key" > <schema-type prefix="xs">string</schema-type> </part> <part position="2" name="url" > <schema-type prefix="xs">string</schema-type> </part> </input-parameters> ... </wsdl-source>
<wsdlURL>: URLを指定して、XQSに対し、WSDLドキュメントの検索場所を指示します。次に例を示します。
<wsdl-source ... > ... <wsdlURL>http://api.mySearch.com/mySearch.wsdl</wsdlURL> ... </wsdl-source>
<operation>: WSDL内の操作名に対応する、実行対象のWebサービス操作を指定します。次に例を示します。
<wsdl-source ... > ... <operation>doGetCachedPage</operation> ... </wsdl-source>
<port>: WSDL内のポート名に対応する、適切なWebサービス・ポートを指定します。次に例を示します。
<wsdl-source ... > ... <port namespace="urn:mySearch">mySearchPort</port> ... </wsdl-source>
前述の例で使用された<function-name>および<input-parameters>の例に対応する、関数の宣言の例を示します。
declare namespace xqs = "http://xmlns.oracle.com/ias/xqs"; declare function xqs:getmySearchCachedPage ($key as xs:string, $url as xs:string) as xs:base64Binary external;
場合により必須または適切であるWSDLソースの要素は、次のとおりです。
<service>: この要素を使用して、WSDL内のサービス名に対応する、適切なサービスを指定します。この要素は、WSDLによって1つのサービスしか定義されない場合のみ、オプションです。サービスの構成の例を示します。
<wsdl-source ... > ... <service namespace="urn:mySearch">mySearchService</service> ... </wsdl-source>
<portType>: この要素を使用して、WSDL内のポート・タイプ名に対応する、適切なポート・タイプを指定します。この要素は、WSDLで1つのバインディングのみ（つまり、1つのポート・タイプのみ）がサポートされている場合にかぎり、オプションです。ポート・タイプの構成の例を示します。
<wsdl-source ... > ... <portType namespace="urn:mySearch">mySearchPort</portType> ... </wsdl-source>
<output-element>: オプションでこの要素を使用すると、XML要素の修飾名または戻されたデータの出力型（単純型または複合型）を指定できます。この要素は必須ではありませんが、この情報は、XQSによるタイプ・チェックに使用されます。次に例を示します。
<wsdl-source ... > ... <output-element namespace="http://xmlns.oracle.com/ias/xqs/CustomerDemo" location="http://host:port/xqsdemos/Customers.xsd"> type="Customers> </output-element> ... </wsdl-source>
<typeMap>: JavaまたはEJBのバインディングを伴うWSDLソースでは、この要素を使用してXML型をJava型にマップできます。その際には、次に示すように、サブ要素<mapping>およびそのサブ要素<xmlType>を使用します。（<typeMap>、<mapping>および<xmlType>の各要素の詳細は、この章の後半部分に含まれているリファレンス・ドキュメントを参照してください。）
<wsdl-source ... > ... <typeMap> <mapping typeClass="org.w3c.dom.Node"> <xmlType prefix="myeis">Customer</xmlType> </mapping> ... </typeMap> ... </wsdl-source>
（<typeMap>要素は、SOAPのバインディングを伴うWSDLソースでは無視されます。）
エラー処理の設定を行い、キャッシングの使用を指定できます。これらの設定には、<wsdl-source>の属性isCachedとonError、およびサブ要素の<cache-properties>と<error-message>を使用します。これらの機能の構成は、ここでは省略します。「XQSエラー処理モードおよびAPIの使用方法」および「XQSキャッシングの構成」を参照してください。
この例では、前に示したそれぞれの部分のいくつかを1つにまとめて、（この後に説明する）mySearch.wsdlで定義されるWebサービス操作のXQS関数が構成されます。
次の例では、キャッシングおよびエラー処理のデフォルト設定が使用されています。これは、<wsdl-source>属性がisCached="false"およびonError="dynamicError"と設定されていることと同じです。
<wsdl-source> <function-name namespace="http://xmlns.oracle.com/ias/xqs"> getmySearchCachedPage </function-name> <wsdlURL>http://api.mySearch.com/mySearch.wsdl</wsdlURL> <operation>doGetCachedPage</operation> <service namespace="urn:mySearch">mySearchService</service> <port namespace="urn:mySearch">mySearchPort</port> <input-parameters> <part position="1" name="key" > <schema-type prefix="xs">string</schema-type> </part> <part position="2" name="url" > <schema-type prefix="xs">string</schema-type> </part> </input-parameters> </wsdl-source>
次に示すのは、前述の構成に関連するmySearch.wsdlの各部分です。WSDLの太字で示した部分は、構成要素に対応します。
<?xml version="1.0" ?> <definitions name="mySearch" targetNamespace="urn:mySearch" xmlns:typens="urn:mySearch" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/"> ... <message name="doGetCachedPage"> <part name="key" type="xs:string" /> <part name="url" type="xs:string" /> </message> <message name="doGetCachedPageResponse"> <part name="return" type="xs:base64Binary" /> </message> ... <portType name="mySearchPort"> <operation name="doGetCachedPage"> <input message="typens:doGetCachedPage" /> <output message="typens:doGetCachedPageResponse" /> </operation> ... </portType> ... <binding name="mySearchBinding" type="typens:mySearchPort"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http" /> <operation name="doGetCachedPage"> <soap:operation soapAction="urn:mySearchAction" /> <input> <soap:body use="encoded" namespace="urn:mySearch" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" /> </input> <output> <soap:body use="encoded" namespace="urn:mySearch" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" /> </output> </operation> ... </binding> ... <service name="mySearchService"> <port name="mySearchPort" binding="typens:mySearchBinding"> <soap:address location="http://api.mySearch.com/search/beta2" /> </port> </service> </definitions>
この章の内容は、開発者がすでにXQuery言語および効果的で効率的な問合せの設計方法の基礎を理解していることを前提としていますが、この項では、XQSを使用する際の特別な考慮事項など、重要なポイントを要約し、問合せの例を示します。この項には、次の項目が含まれます。
最初の手順として、当然ながらデータソースを考慮する必要があります。これには、アクセス方法や含まれるデータのタイプも含まれます。一部のデータソースに対して行う必要がある準備手順は、「データソースを使用するための準備」で前述しています。
次に、問合せ自体の様々な側面を考慮する必要があります。これには、次のことが含まれます。
.xqファイル）として保存するか。
前述のように、XQSでは、データソースにアクセスするための外部XQuery関数が実装されます。XQSによって作成されるこの関数の宣言を、選択した関数名を使用してXQueryのプロローグに含める必要があります。また、このプロローグは、適切な名前空間を参照する必要があります。宣言する関数名は、データソースの構成時に<function-name>要素で指定した名前と一致する必要があります。（「XQS関数の構成方法」を参照してください）。
XML文書からデータを取得する、単純な問合せを次に示します。このドキュメントの場所は、実行時にXQS関数に渡されます。
declare namespace xqs = "http://xmlns.oracle.com/ias/xqs"; declare function xqs:get_poSQ($bind as xs:string) external; for $po in xqs:get_poSQ("http://host:port/xqsdemos/Repository/pos-2KB.xml") return $po
XQSでは、XQS構成に基づいて関数が実装されます。関数名（この例ではget_poSQ）は、ユーザーが選択する名前です。この関数は、ドキュメント・ソースpos-2KB.xmlの名前と場所を示す文字列を入力として使用し、このファイルから注文（purchase order）データを戻します。
次に、XQueryコードを介してパラメータ値を渡す問合せの例を示します。このXQS関数はexampleで、構成に基づいてXQSによって実装されます。
declare namespace xqs = "http://xmlns.oracle.com/ias/xqs"; declare function xqs:example($i as xs:int, $d as xs:duration, $h as xs:hexBinary, $bin as xs:base64Binary, $t as xs:boolean) external; for $result in xqs:example(xs:int(1), xs:duration("P1Y2MT2H"), xs:hexBinary("0FB7"), xs:base64Binary("vYrfOJ39673//-BDiIIGHSPM=+"), xs:boolean("true")) return $result;
次に、より複雑な問合せの例を示します。この問合せでは、顧客の名前を指定すると、その顧客の注文に関する支払記録が検索されます。そして、顧客の情報および注文が戻されます。この例には、2つのデータソースが関係しています。1）顧客情報はWSIFのカスタム拡張機能myeisを介してアクセスされます。2）支払情報はExcelシート（XML以外のドキュメント・ソース）に保存されています。顧客情報のデータソースへのアクセスには、XQS関数customerInfoが使用され、顧客名を示す文字列が入力として使用されます。この関数は、顧客情報のデータソースにアクセスし、指定された顧客の情報（顧客キーを含む）を生成します。その後、XQS関数paymentStatusInfoを使用して支払情報のExcelファイルにアクセスし、顧客情報のデータソースと同じキーを持つ顧客の注文情報を戻します。このXQueryコードには、結果のXML変換が含まれています。
declare namespace xqs = "http://xmlns.oracle.com/ias/xqs"; (: returns payment info for all customers:) declare function xqs:paymentStatusInfo() external; (: returns customer info given customer name :) declare function xqs:customerInfo ($name as xs:string) external; (: customer name passed in to query :) declare variable $custName external; let $custInfo := xqs:customerInfo($custName) for $custOrderInfo in xqs:paymentStatusInfo()/excel/Row[CustomerKey eq $custInfo/key] return <result> <MYEIS_RESULT> <Row> <Name> { $custInfo/name } </Name> <Company> { $custInfo/company} </Company> <Address> { $custInfo/address} </Address> <City> { $custInfo/city} </City> <State> { $custInfo/state} </State> <Zip> { $custInfo/zip} </Zip> </Row> </MYEIS_RESULT> <EXCEL_RESULT> <Row> <OrderID>{$custOrderInfo/OrderId}</OrderID> <Amount>{$custOrderInfo/Amount}</Amount> <PaymentStatus>{$custOrderInfo/PaymentStatus}</PaymentStatus> </Row> </EXCEL_RESULT> </result>
WSDLソースまたはXQSビューで、基礎となるデータソースに入力引数を送る前に、XQueryによる追加のタイプ・チェックの手順を実行する場合は、次の手順を行います。
<input-parameters>要素の下にある<part>サブ要素を介して、構成内で適切なXQS関数に対して指定した入力パラメータごとに、パラメータ・タイプを指定します。XQSビュー・ソースの場合は、必要に応じて、次のいずれかを介して指定します。
WSDLソースの場合は、順序は入力としてサポートされないため、関係があるのは<schema-type>のみです。
（これらの各要素の詳細は、この章の後半部分に含まれているリファレンス・ドキュメントを参照してください。）
次に例を示します。最初はXQS構成です。
<wsdl-source isCached="false"> <function-name namespace="http://xmlns.oracle.com/ias/xqs"> SplitRatio </function-name> ... <input-parameters> <part position="1" name="parameters"> <schema-type namespace="http://www.xignite.com/services/"> GetSplitRatio </schema-type> </part> </input-parameters> </wsdl-source>
次は、対応するXQuery式です。
import schema namespace xignite="http://www.xignite.com/services/" at "http://www.xignite.com/xSecurity.asmx?wsdl" declare namespace xqs="http://xmlns.oracle.com/ias/xqs"; declare function xqs:SplitRatio($params as xignite:GetSplitRatio) as xignite:GetSplitRatioResponse external; let $in := <xignite:GetSplitRatio> .....</xignite:GetSplitRatio> let $y := xqs:SplitRatio($in) return <split>$y//xignite:Ratio</split>
実行時に、xqs:SplitRatioに渡された引数のタイプが、インポートされたスキーマのタイプxignite:GetSplitRatioであることがXQueryによって確認されます。
この項では、（「XQSクライアント・インタフェースの概要」で最初に説明した）XQSで提供されるクライアントAPIを使用する場合の手順について説明し、例を示します。ここでは、JavaクライアントAPI、EJBクライアントAPIおよびJSPタグ・ライブラリについて説明します。Webサービス・クライアントに関して、XQSビューをWebサービス操作として公開するXQSの詳細は、パッケージ化の項で後述しています（「XQSビューをWebサービス操作として公開するためのOC4JPackagerの追加の出力」を参照）。それ以外では、XQSによってSOAP 1.1バインディングを伴う標準のWSDLが生成されます。ここに示す内容は、Webサービス・クライアントの作成に関する知識があることを前提としています。
この項には、次の項目が含まれます。
注意
ejb-jar.xmlファイル、Webモジュールを使用する場合はweb.xmlファイルなど、追加の構成もすべて完了しておく必要があります。
XQSのoracle.xqs.client.QueryParameterIインタフェースは、XQSのJavaクライアントAPIおよびEJBクライアントAPIで、問合せ用のバインド・パラメータの配列に使用します。このクラスは、XQSのJSPタグ・ライブラリでも、背後で使用されます。（追加情報は、「XQS QueryParameterIリファレンス」を参照してください。）表8-2は、XQSでサポートされているXML型、およびQueryParameterIインタフェースのインスタンスを介して入力値を渡すために使用するJava型の対応を示しています。
XQSクライアントAPIを使用するためには、次に示す、基本的なコーディング手順を行います。
.xqファイルに問合せを保存します。「問合せの設計方法」も参照してください。
getXQSFacade()を使用して、またはJSPページにXQS JSPタグ・ライブラリを含めることで、XQSFactoryファクトリからXQSFacadeIインタフェースのインスタンスを取得します。
oracle.xqs.client.QueryParameterIの配列を作成し、静的メソッドgetQueryParameter()を使用してXQSFactoryファクトリからQueryParameterIインタフェースのインスタンスを取得して、その配列を移入します。（「XQS QueryParameterIリファレンス」を参照してください。）JSPタグ・ライブラリの場合は、executeまたはexecuteCursorのparamサブタグを使用します。（「XQS paramタグ」を参照してください。）前項の「サポートされている問合せパラメータのタイプ」も参照してください。
java.util.Vectorインスタンス内に一度にすべての結果が戻されるか、（JSPタグを使用している場合は）java.util.ArrayListインスタンスとXML文書が戻されます。ステートフル・クライアントの場合は、Oracle XQueryタイプoracle.xml.xqxp.datamodel.XMLItemを使用するか、（JSPタグを使用している場合は）java.lang.ObjectインスタンスとXML文書のノードを使用して、アイテムごとに結果を取得します。XQS EJB APIおよびJSPタグ・ライブラリの場合は、ステートレスとステートフルのいずれかのアクセス・パターンを選択して使用できます。 XQSFacadeIインタフェースでは、ステートフル・アクセス・パターンを使用します。XQSFacadeIインタフェースの使用に関する情報は、「Javaインタフェース・クライアントAPIの使用方法」を参照してください。
ここでは、セキュリティまたはパフォーマンスの考慮事項については言及しません。これらの項目の情報は、「XQSアプリケーションのセキュリティ」および「XQSパフォーマンス機能の使用方法」を参照してください。
注意
XQSクライアントAPIは、問合せ結果をXML順序として戻します。この順序には1つ以上のXML項目が含まれ、各項目は、XML文書、XMLノードまたはプリミティブ値になります。問合せを実行することで、結果は定義されますが、すべての結果項目が即座にマテリアライズされてプロセス・メモリーに格納されるわけではないことを認識しておくことが重要です。リレーショナル問合せの結果セットのように、XML順序でのカーソルの位置は、最初の項目の前になるように暗黙的に維持されており、次へ移動するための（next）操作で移動できます。暗黙カーソルを使用して次へ（next）の操作のコールを繰り返すことでXML順序にアクセスした場合は、次への操作をコールするたびに、要求された次の項目を作成するためのXQuery式の評価が、実際にトリガーされる可能性があります。XQueryによって式が評価される正確なタイミング、また、評価が段階的に行われるか一度に全部行われるかは、そのXQuery式およびXQuery実装の最適化レベルによって異なります。XQSクライアントAPIでは、このようにカーソルでアクセスするかわりに、シングル・ステップですべての問合せ結果を読み取り、プロセス・メモリーに格納することもできます。
シングル・ステップ・モードおよびカーソル・モードの実行には、それぞれ長所と短所があります。ほとんどの状況では、シングル・ステップによる実行が適しています。これは、関連するリソース（基礎となるデータソースへの接続、およびその式専用の内部XQueryリソース）が、実行の完了後にただちに解放されるためです。また、データソースへ繰り返しアクセスすることによるパフォーマンスへの潜在的な影響を受けることもありません。ただし、結果順序に含まれる項目の全体のサイズが大きすぎて、順序全体を一度にマテリアライズするとプロセス・メモリーが不足する場合には、シングル・ステップによる実行を使用できません。このような場合は、問合せが結果を項目ごとに提供するのを妨げるもの（たとえば集計式など）がないかぎり、カーソル・モードが唯一の手段になります。
シングル・ステップ・モードまたはカーソル・モードを選択できるように、XQSでは2種類のクライアントAPIを用意しています。シングル・ステップ・モード用のステートレスおよびカーソル・モード用のステートフルです。（この場合の「ステート」は、XQueryエンジンの内部状態を指します。）これらのクライアントAPIは、次のように動作します。
XQS EJBクライアントAPIおよびJSPクライアントAPIには、それぞれステートレス実行用の機能とステートフル実行用の機能があります。XQS Javaインタフェース（XQSFacadeI）クライアントAPIは、ステートフル・アクセスを提供します。すべての結果項目をただちに取得し、クライアント・オブジェクトを解放することで、ステートレス・アクセスをシミュレートできます。
「XQSクライアントAPIを使用するための一般的なコーディング手順」を参照してください。（問合せの作成後に）XQS JavaクライアントAPIを使用してこれらの手順を適用するには、次の手順に従います。
getXQSFacade()を使用して、XQSFactoryファクトリからXQSFacadeIインタフェースのインスタンスを取得します。次の各手順のメソッド・コールは、このインスタンスからコールされます。
QueryParameterI配列を作成し、静的メソッドgetQueryParameter()を使用してXQSFactoryファクトリからQueryParameterIインタフェースのインスタンスを取得して、その配列を移入します。
execute()メソッドを使用して非定型問合せを実行するか、executeView()メソッドを使用してXQSビューを実行し、問合せとQueryParameterI配列（入力パラメータがない場合はnull）を渡します。executeView()を使用する場合は、そのビューのXQS関数の名前空間も渡します。
emptySequenceエラー・モードまたはerrorMessageエラー・モードを使用した場合は、必要に応じてgetErrors()メソッドを使用して、問合せの実行時に発生したエラーを取得できます。これにより、XQSErrorIオブジェクトのコレクションに対するイテレータが戻されます。エラーの構成と処理の詳細は、「XQSエラー処理モードおよびAPIの使用方法」を参照してください。
getNextItem()メソッドを繰り返し使用して、項目ごとに結果を取得します。各項目は、XMLItemインスタンス内に戻されます。必要に応じてこれらの項目を処理します。
close()メソッドを使用して、問合せに関連付けられているすべてのリソースを解放します。
これらの手順は、次の例の中で示されています。「XQSFacadeIリファレンス」も参照してください。
この例は、XQSFacadeI APIの一般的な使用方法を示しています。この問合せでは、バインド・パラメータが順序内に戻され、バインド方法とデータの取得方法が示されます。関数が使用されないため、構成は不要です。
問合せ結果を処理するために、コードには（oracle.xml.xqxp.datamodelパッケージ内で）XMLItemクラスが使用されています。
import oracle.xml.xqxp.datamodel.XMLItem; import oracle.xml.parser.v2.XMLDocument; import oracle.xml.parser.v2.XMLElement; import oracle.xqs.client.XQSFacadeI; import oracle.xqs.client.QueryParameterI; import oracle.xqs.client.XQSErrorI; import java.util.Vector; public class XQSFacadeITest { public static void main(String[] args) throws Exception { try{ //get XQSFacadeI XQSFacadeI facade = XQSFactory.getXQSFacade(); String xquery = "declare variable $bind1 external;\n"+ "declare variable $bind2 external;\n"+ "declare variable $bind3 external;\n"+ "declare variable $bind4 external;\n"+ "declare variable $bind5 external;\n"+ "declare variable $bind6 external;\n"+ "declare variable $bind7 external;\n"+ "declare variable $bind8 external;\n"+ "declare variable $bind9 external;\n"+ "declare variable $bind10 external;\n"+ "declare variable $bind11 external;\n"+ "declare variable $bind12 external;\n"+ "declare variable $bind13 external;\n"+ "declare variable $bind14 external;\n"+ "declare variable $bind15 external;\n"+ "declare variable $bind16 external;\n"+ "("+"$bind1,$bind2,$bind3,$bind4,$bind5,$bind6,$bind7,\n"+ "$bind8,$bind9,$bind10,$bind11,$bind12,$bind13,$bind14,$bind15, $bind16)"; QueryParameterI params[] = new QueryParameterI[16]; params[0]=XQSFactory.getQueryParameter ("bind1"); params[0].setString("test"); params[1]=XQSFactory.getQueryParameter ("bind2"); params[1].setInteger(new BigInteger("100")); params[2]=XQSFactory.getQueryParameter ("bind3"); params[2].setBoolean(true); params[3]=XQSFactory.getQueryParameter ("bind4"); params[3].setFloat(-1); params[4]=XQSFactory.getQueryParameter ("bind5"); params[4].setDuration("P1Y2M3DT10H30M"); params[5]=XQSFactory.getQueryParameter ("bind6"); params[5].setDouble(-11.0); TimeZone LAtz = new SimpleTimeZone(-28800000, "America/Los_Angeles", Calendar.APRIL, 1, -Calendar.SUNDAY, 7200000, Calendar.OCTOBER, -1, Calendar.SUNDAY, 7200000, 3600000); GregorianCalendar cal = new GregorianCalendar(LAtz); params[6]=XQSFactory.getQueryParameter ("bind7"); params[6].setDateTime(cal,true); URI uri = new URI("http://www.test.com"); params[7]=XQSFactory.getQueryParameter ("bind8"); params[7].setAnyURI(uri); params[8]=XQSFactory.getQueryParameter ("bind9"); params[8].setInt(-7); params[9]=XQSFactory.getQueryParameter ("bind10"); params[9].setLong(50l); params[10]=XQSFactory.getQueryParameter ("bind11"); params[10].setDecimal(new BigDecimal(999999)); params[11]=XQSFactory.getQueryParameter ("bind12"); XMLDocument document = new XMLDocument(); Element elem = document.createElementNS("http://client.xqs.oracle/", "tns:result"); document.appendChild(elem); params[11].setNode(elem); params[12]=XQSFactory.getQueryParameter ("bind13"); params[12].setBase64Binary("vYrfOJ39673//-BDiIIGHSPM=+"); params[13]=XQSFactory.getQueryParameter ("bind14"); params[13].setHexBinary("0FB7"); params[14]=XQSFactory.getQueryParameter ("bind15"); params[14].setDayTimeDuration(60.5); params[15]=XQSFactory.getQueryParameter ("bind16"); params[15].setYearMonthDuration(13); facade.execute(xquery, params); // lookup functions XMLItem item = facade.getNextItem(); while(item != null) { if (item.instanceOfType(XMLItem.XMLITEM_STRING)) { System.out.println("string item value: expected: \"test\", actual:", item.getString()); } else if (item.instanceOfType(XMLItem.XMLITEM_INT)) { System.out.println("int item value: expected: \"-7\", actual: ", item.getInt()); } else if (item.instanceOfType(XMLItem.XMLITEM_LONG)) { System.out.println("long item value: expected: \"501\", actual: ", item.getInt()); } else if(item.instanceOfType(XMLItem.XMLITEM_INTEGER)) { if(item.intFormat()) System.out.println("integer item value: expected: \"100\", actual:", item.getInt()); else System.out.println("integer item value: expected: \"100\", actual: ", item.getDecimal().intValue()); } else if(item.instanceOfType(XMLItem.XMLITEM_BOOLEAN)) { System.out.println("boolean item value: expected: \"true\", actual: ", item.getBoolean()); } else if(item.instanceOfType(XMLItem.XMLITEM_FLOAT)) { System.out.println("float item value: expected: \"-1\", actual: ",(float)item.getDouble()); } else if (item.instanceOfType(XMLItem.XMLITEM_XDT_DAYTIMEDURATION)) { System.out.println("dayTimeDuration item value: expected: \"60.5 seconds\", actual: ", item.getDayTimeDuration()); } else if (item.instanceOfType(XMLItem.XMLITEM_XDT_YEARMONTHDURATION)) { System.out.println("yearMonthDuration item value: expected: \"13 months\", actual: ", item.getYearMonthDuration()); } else if (item.instanceOfType(XMLItem.XMLITEM_DURATION)) { System.out.println("duration item value: expected: \" P1Y2M3DT10H30M \", actual: ", item.getLexicalValue()); } else if(item.instanceOfType(XMLItem.XMLITEM_DOUBLE)) { System.out.println("double item value: expected: \" -11.0\", actual: ", item.getDouble()); } else if(item.instanceOfType(XMLItem.XMLITEM_DATETIME)) { System.out.println("dateTime item value: expected Timezone: \"Pacific (Latz) \", actual: ", item.getCalendar().getTimeZone()); } else if (item.instanceOfType(XMLItem.XMLITEM_ANYURI)) { System.out.println("anyURI item value: expected: \"http://www.test.com\", actual: ", item.getString()); } else if (item.instanceOfType(XMLItem.XMLITEM_DECIMAL)) { System.out.println("decimal item value: expected: \"999999 \", actual: ", item.getDecimal().intValue()); } else if(item.instanceOfType(XMLItem.XMLITEM_NODE)) { XMLElement node = (XMLElement)item.getNode(); //when obtained from document function, it returns XMLDocument if(node instanceof XMLDocument) node = (XMLElement)node.getFirstChild(); System.out.println("node item value: expected namespace: \" http://client.xqs.oracle \", actual: ",node.getNamespaceURI()); System.out.println("node item value: expected local name: \"result\", actual: ",node.getLocalName()); } else if (item.instanceOfType(XMLItem.XMLITEM_HEXBINARY)) { System.out.println("hexBinary item value: expected: \"0FB7\", actual: ", item.getString()); } else if (item.instanceOfType(XMLItem.XMLITEM_BASE64BINARY)) { System.out.println("base64Binary item value: expected: \" vYrfOJ39673//-BDiIIGHSPM=+ \", actual: ", item.getString()); } else { System.out.println("item type not supported:"+item.getLexicalValue()); } item = facade.getNextItem(); } }catch(Exception ex){ ex.printStackTrace(); fail(ex.getMessage()); assertTrue("xquery execution failed", false); } facade.close(); } }
この項では、Javaクラスを使用して、クライアント・コード内のXQSFacadeI APIおよび関連するXQS構成の使用の手順を示します。この例の非定型問合せでは、XQSソースが使用されます。また、このXQSソースでは、ドキュメント・ソースが使用されます。
この例では、次の非定型問合せが使用されます。
declare namespace xqs="http://xmlns.oracle.com/ias/xqs"; declare function xqs:get_poSQ($bind as xs:string) external; for $po in xqs:get_poSQ("http://localhost:8888/myrepository/pos-2KB.xml") return $po
次に、この問合せで、次の例に示すように構成されたXQSビュー・ソースに対応するXQS関数get_poSQが使用されます。.xqファイルの名前と場所を（<queryName>要素および<repository>要素を介して）構成内で指定しなかった場合、デフォルトでは、ファイル名は関数名、ファイルの場所はOC4JPackagerの実行時に-repositoryオプションを介して指定した場所であるとみなされます。
<xqsview-source> <function-name prefix="xqs">get_poSQ</function-name> <input-parameters> <part position="1" name="bind" > <schema-type prefix="xs">string</schema-type> </part> </input-parameters> </xqsview-source>
ファイルget_poSQ.xqで定義されたXQSビューget_poSQでは、ドキュメント・ソースが使用されます。このドキュメント・ソースは、次のように定義されます。
declare namespace xqs = "http://xmlns.oracle.com/ias/xqs"; declare variable $bind external; declare function xqs:genericFile($bind as xs:string) external; for $po in xqs:genericFile($bind)//po return $po
また、ドキュメント・ソースgenericFileは、次のように構成されます。
<document-source> <function-name namespace="http://xmlns.oracle.com/ias/xqs"> genericFile </function-name> </document-source>
genericFile関数では、ドキュメントURLが入力として使用されるため、<documentURL>要素は使用されていません。
次はコードです。このコードは、次のことを行う完全なクラスです。
getXQSFacade()を使用して、XQSFactoryファクトリからXQSFacadeIインタフェースのインスタンスを取得します。
get_poSQを使用する非定型問合せを定義します。問合せは文字列バッファxqueryBufに統合され、その後、文字列xqueryStrに格納されます。バックエンド・ドキュメント・ソースのURLは、get_poSQ関数によって入力として使用されます。
execute()メソッドに、QueryParameterI配列のかわりにnullが渡されます。（次の、「例3: XQSFacadeI APIを使用したXQSビュー」の例では、入力パラメータが使用されています。）
errorMessageまたはemptySequenceを使用）、エラー・オブジェクトを取得して処理できます。（次の例では、エラー処理についても示しています。もしくは、追加情報として、「XQSエラー処理モードおよびAPIの使用方法」を参照してください。）
whileループは、項目ごとに結果順序を経由します。そのため、ノード内の各項目は、XML文書docに格納されます。そこから、結果を表示したり、必要に応じてさらに処理できます（この時点からの処理は、XQS固有ではありません）。
close()コールにより、カーソルがクローズされ、関連付けられているリソースが解放されます。
import oracle.xml.xqxp.datamodel.XMLItem; import oracle.xml.parser.v2.XMLDocument; import oracle.xml.parser.v2.XMLElement; import oracle.xml.parser.v2.XMLNode; import oracle.xqs.client.XQSFacadeI; public class XQSFacadeITest { public static void main(String[] args) throws Exception{ XQSFacadeI bean = XQSFactory.getXQSFacade(); StringBuffer xqueryBuf = new StringBuffer(); xqueryBuf.append ("declare namespace xqs=\"http://xmlns.oracle.com/ias/xqs\";\n"); xqueryBuf.append ("declare function xqs:get_poSQ($bind as xs:string) external;\n"); xqueryBuf.append("for $po in xqs:get_poSQ (\"http://localhost:8888/myrepository/pos-2KB.xml\") \n"); xqueryBuf.append("return $po\n"); String xqueryStr = xqueryBuf.toString(); //no parameters to be bound, so pass null bean.execute(xqueryStr, null); XMLItem item = bean.getNextItem(); XMLDocument doc = new XMLDocument(); XMLElement rootElem = (XMLElement)doc.createElement("QueryResult"); doc.appendChild(rootElem); while(item != null) { /* the test is actually superfluous - all items are expected to nodes for Purchase Order, here we show a standard treatment of items that are XML nodes, including entire documents (where node type is DOCUMENT_NODE) */ if(item.getItemType().isNode()) { rootElem.appendChild(doc.importNode( item.getNode().getNodeType()== XMLNode.DOCUMENT_NODE?(XMLNode) ((XMLDocument)item.getNode()).getDocumentElement(): (XMLNode)item.getNode(), true)); } item = bean.getNextItem(); } bean.close(); } }
この項では、XQSFacadeI APIを使用し、executeView()コールを介してXQSビューを直接実行する場合の例を示します。
BasicFileWSという名前のXQSビューの構成を示します。
<xqsview-source WSDLvisibility="true" isCached="false" onError="errorMessage"> <function-name prefix="xqs">BasicFileWS</function-name> <input-parameters type-match="none" > <part position="1" name="custName"> <schema-type prefix="xs">string</schema-type> </part> </input-parameters> <output-element namespace="http://xmlns.oracle.com/ias/xqs/CustomerDemo" location="http://host:port/xqsdemos/MyTypes.xsd" type="CustomerOrdersType"> </output-element> </xqsview-source>
<queryName>要素がないため、.xqファイルの名前は、（指定された関数名と同じ）BasicFileWS.xqとみなされます。このビューでは、文字列のパラメータcustNameが入力として使用されます。
次に、ビューBasicFileWS.xq（「問合せの例」で前述した問合せ）の定義を示します。顧客名を入力として使用するための変数も含まれます。このビューでは、データソースに対して2つのXQS関数が使用されます。このデータソースの構成は、この例の後に示しています。
declare namespace xqs = "http://xmlns.oracle.com/ias/xqs" ; (: returns payment info for all customers:) declare function xqs:paymentStatusInfo () external; (: returns customer info given customer name :) declare function xqs:customerInfo ($name as xs:string) external; (: customer name passed in to query :) declare variable $custName external; let $custInfo := xqs:customerInfo($custName) for $custOrderInfo in xqs:paymentStatusInfo()/excel/Row[CustomerKey eq $custInfo/key] return <result> <MYEIS_RESULT> <Row> <Name> { $custInfo/name } </Name> <Company> { $custInfo/company} </Company> <Address> { $custInfo/address} </Address> <City> { $custInfo/city} </City> <State> { $custInfo/state} </State> <Zip> { $custInfo/zip} </Zip> </Row> </MYEIS_RESULT> <EXCEL_RESULT> <Row> <OrderID>{$custOrderInfo/OrderId}</OrderID> <Amount>{$custOrderInfo/Amount}</Amount> <PaymentStatus>{$custOrderInfo/PaymentStatus}</PaymentStatus> </Row> </EXCEL_RESULT> </result>
次に、関数paymentStatusInfoに関連付けられているドキュメント・ソースの構成を示します。このドキュメントはXMLではないため、変換にD3Lが使用されます。（「XML以外のドキュメント・ソースを使用するための準備」を参照してください。）
<document-source isCached="false"> <function-name prefix="xqs">paymentStatusInfo</function-name> <documentURL>http://host:port/xqsdemos/paymentInfo.csv</documentURL> <XMLTranslate method="D3L"> <schema-file> http://host:port/xqsdemos/paymentInfoD3L.xml </schema-file> </XMLTranslate> </document-source>
次に、関数customerInfoに関連付けられているWSDLソースの構成を示します。これには、JavaとXMLの型マッピングに関する情報も含まれます。
<wsdl-source isCached="false"> <function-name namespace="http://xmlns.oracle.com/ias/xqs"> customerInfo </function-name> <wsdlURL>http://host:port/xqsdemos/CustomerInfo.wsdl</wsdlURL> <operation>getCustomer</operation> <service prefix="myeis">CustomerInfoMYEISService</service> <port prefix="myeis">CustomerInfo</port> <input-parameters> <part position="1" name="name"> <schema-type prefix="xs">string</schema-type> </part> </input-parameters> <typeMap> <mapping typeClass="org.w3c.dom.Node"> <xmlType prefix="myeis"> Customer </xmlType> </mapping> </typeMap> </wsdl-source>
この項では、ビューBasicFileWSを実行するためのJavaコードを使用し、次のことを行う完全なクラスを示します。
getXQSFacade()を使用して、XQSFactoryファクトリからXQSFacadeIインタフェースのインスタンスを取得します。
QueryParameterI配列を設定します。静的メソッドgetQueryParameter()を使用して、XQSFactoryファクトリからQueryParameterIインタフェースのインスタンスを取得します。顧客名を設定するには、QueryParameterIインタフェースのsetString()メソッドを使用します。
executeView()メソッドに渡されるビュー名は、構成内でそのビューに関連付けられている関数名と一致する必要があります。このメソッドでは、関数の名前空間（同じく構成内で指定済）も使用されます。この例では、ビューはXQS名前空間で宣言されています。
XQSErrorIインタフェースのメソッドは、問合せ時に発生したエラーの情報を印刷するために使用します。その前提として、適切なXQSのエラー構成でemptySequenceモードまたはerrorMessage モードが使用されている必要があります。そうでない場合は、エラーが発生すると問合せが停止し、エラーのイテレータには有用な情報が含まれません。BasicFileWSの構成で示したように、この例では、errorMessageモードが使用されています。（追加情報は、「XQSエラー処理モードおよびAPIの使用方法」および「XQSErrorIリファレンス」を参照してください。）
oracle.xml.xqxp.datamodelパッケージ内の）クラスXMLItemのインスタンスとして取得されます。XMLItemクラスの型定数および型固有のアクセッサを使用して、値が取得されます。
import oracle.xml.xqxp.datamodel.XMLItem; import oracle.xml.parser.v2.XMLDocument; import oracle.xml.parser.v2.XMLElement; import oracle.xml.parser.v2.XMLNode; import oracle.xqs.client.XQSFacadeI; import oracle.xqs.client.XQSErrorI; import oracle.xqs.client.QueryParameterI; public class XQSFacadeIViewTest { public static void main(String[] args) throws Exception{ XQSFacadeI facade = XQSFactory.getXQSFacade(); String xqueryView = "BasicFileWS"; QueryParameterI param = XQSFactory.getQueryParameter("custName"); param.setString("John Ford"); QueryParameterI[] params = new QueryParameterI[1]; params[0] = param; facade.executeView(xqueryView, "http://xmlns.oracle.com/ias/xqs", params); java.util.ListIterator errors = facade.getErrors(); while(errors.hasNext()) { XQSErrorI error = (XQSErrorI)errors.next(); System.out.println ("The function which gives error is: " + error.getFunctionQName()); System.out.println("The error type is: "+error.getErrorType()+ " which is - "+XQSErrorI.typeNames(error.getErrorType())); System.out.println("The error code is:" + error.getErrorCode()); System.out.println("The error message is:" + error.getErrorMessage()); } XMLItem item = facade.getNextItem(); StringBuffer resultBuf = new StringBuffer(); XMLDocument doc = new XMLDocument(); XMLElement rootElem = (XMLElement)doc.createElement("QueryResult"); doc.appendChild(rootElem); while(item != null) { if(item.instanceOfType(XMLItem.XMLITEM_STRING)) { resultBuf.append(item.getString()); } else if(item.instanceOfType(XMLItem.XMLITEM_INT)) { resultBuf.append(item.getInt()); } else if(item.instanceOfType(XMLItem.XMLITEM_LONG)) { resultBuf.append(item.getInt()); } else if(item.instanceOfType(XMLItem.XMLITEM INTEGER)) { if(item.intFormat()) resultBuf.append(item.getInt()); else resultBuf.append(item.getDecimal().intValue()); } else if(item.instanceOfType(XMLItem.XMLITEM_BOOLEAN)) { resultBuf.append(item.getBoolean()); } else if(item.instanceOfType(XMLItem.XMLITEM_FLOAT)) { resultBuf.append((float)item.getDouble()); } else if(item.instanceOfType(XMLItem.XMLITEM_DOUBLE)) { resultBuf.append(item.getDouble()); } else if(item.instanceOfType(XMLItem.XMLITEM_XDT_DAYTIMEDURATION)) { resultBuf.append(item.getDayTimeDuration()); } else if(item.instanceOfType(XMLItem.XMLITEM_YEARMONTHDURATION)) { resultBuf.append(item.getYearMonthDuration()); } else if(item.instanceOfType(XMLItem.XMLITEM_DURATION)) { resultBuf.append(item.getLexicalValue()); } else if(item.instanceOfType(XMLItem.XMLITEM_DATETIME)) { resultBuf.append(item.getCalendar().getTime()); } else if(item.instanceOfType(XMLItem.XMLITEM_ANYURI)) { resultBuf.append(item.getString()); } else if(item.instanceOfType(XMLItem.XMLITEM_DECIMAL)) { resultBuf.append(item.getDecimal().intValue()); } else if(item.instanceOfType(XMLItem.XMLITEM_NODE)) { resultBuf.append(item.getNode().getNodeName()); } else if(item.instanceOfType(XMLItem.XMLITEM_HEXBINARY)) { resultBuf.append(item.getString()); } else if(item.instanceOfType(XMLItem.XMLITEM_BASE64BINARY)) { resultBuf.append(item.getString()); } item = facade.getNextItem(); } facade.close(); } }
「XQSクライアントAPIを使用するための一般的なコーディング手順」を参照してください。XQS EJBクライアントAPIの場合は、（問合せの作成後に）ステートフル・セッションとステートレス・セッションのどちらを選択するかによって、次に示すように手順の詳細が異なります。
QueryParameterI配列を作成し、静的メソッドgetQueryParameter()を使用してXQSFactoryファクトリからQueryParameterIインタフェースのインスタンスを取得して、その配列を移入します。
execute()メソッドを使用して非定型問合せを実行するか、executeView()メソッドを使用してXQSビューを実行し、問合せとQueryParameterI配列（入力パラメータがない場合はnull）を渡します。executeView()を使用する場合は、そのビューのXQS関数の名前空間も渡します。
getNextItem()メソッドを繰返し使用して、項目ごとに結果を取得します。各項目は、XMLItemインスタンス内に戻されます。必要に応じてこれらの項目を処理します。ステートレスBeanの場合は、問合せ結果がベクターjava.util.Vectorとして完全にマテリアライズされ、XMLItemインスタンスが含まれます。必要に応じてこれらの項目のベクターを処理します。
emptySequenceエラー・モードまたはerrorMessageエラー・モードを使用した場合は、必要に応じてgetErrors()メソッドを使用し、問合せの実行時にこれらのデータソース内で発生したエラーを取得できます。これにより、XQSErrorIオブジェクトのコレクションに対するイテレータが戻されます。エラーの構成と処理の詳細は、「XQSエラー処理モードおよびAPIの使用方法」を参照してください。
close()メソッドを使用して、問合せに関連付けられているすべてのリソースを解放します。この手順は、ステートレスBeanには適用されません。
これらの手順は、次の例の中で示されています。「XQS EJBクライアントAPIリファレンス」も参照してください。
ステートフル・セッションとステートレス・セッションの使い分けの詳細は、「ステートフル・クライアントとステートレス・クライアント」を参照してください。
ステートフルEJBとステートレスEJBのどちらを取得するかは、JNDI検索および使用するXQSパッケージで決まります。次の例では、ステートフルBeanが取得されます。
//Look up and create the EJB to execute the query. InitialContext ic = new InitialContext(); //Use Local client. oracle.xqs.client.ejb.stateful.XQSClientLocalHome home = (oracle.xqs.client.ejb.stateful.XQSClientLocalHome)ic.lookup ("java:comp/env/XQSClientStatefulLocal"); oracle.xqs.client.ejb.stateful.XQSClientLocal bean = home.create();
次の例では、ステートレスBeanが取得されます。
//Look up and create the EJB to execute the query. InitialContext ic = new InitialContext(); //Use Local client. oracle.xqs.client.ejb.stateless.XQSClientLocalHome home = (oracle.xqs.client.ejb.stateless.XQSClientLocalHome)ic.lookup ("java:comp/env/XQSClientStatelessLocal"); oracle.xqs.client.ejb.stateless.XQSClientLocal bean = home.create();
前述のように、ステートレスEJBセッションで問合せ（非定型またはビュー）を実行すると、XMLItemインスタンスを含むベクターとして、結果が完全にマテリアライズされます。また、このベクターは、必要に応じて後で処理します。ステートフル・セッションの場合は、問合せの実行後に、getNextItem()メソッドを使用して項目を1つずつ取得します。これにより、タイプXMLItemの項目が戻されます。
XQS EJBステートフル・クライアントAPIは、XQSFacadeI APIと同じです。前の項で示したBean作成用のコード以外にも、ステートフルEJBクライアントのコード例は、「例2: XQSFacadeI APIを使用した非定型問合せ」および「例3: XQSFacadeI APIを使用したXQSビュー」で示したXQSFacadeIの例と類似します。getNextItem()メソッドを繰返し使用して、項目を1つずつ、XMLItemインスタンスとして取得し、処理します。
ステートフルEJBと関連付けられているXQSの問合せ状態は、非アクティブ化および後続の再アクティブ化では維持されません。問合せ状態は、execute()またはexecuteView()メソッドの起動後に確立されます。問合せ状態には問合せの実行計画を管理する内部構造が含まれ、項目の取得後には、結果順序の現在の項目の位置も含まれます。ステートフルBeanインタフェースを使用すると、毎回サーバー・セッションに接続することで、結果項目を一度に1つずつフェッチできます。
このオプションは、各項目のサイズまたは結果順序の合計サイズが大きすぎて、一度のラウンドトリップでは送信できない場合に重要です。また、最初の項目をすぐに戻すことによる迅速なレスポンスが必要な場合にも便利です。このオプションのデメリットは、サーバーによってBeanが非アクティブ化され、処理中の問合せの状態が失われる可能性があることです。
問合せ状態が失われ、クライアントにより後続のgetNextItem()のコールが試行されると、XQSによりエラー・コードがXQS 0088のXQSExceptionがスローされます。この制限を緩和する方法の1つは、キャッシュ済のXQSビューとしてステートフルBeanに起動される問合せを構成することです。キャッシュ済のXQSビューを使用すると、getNextItem()のコールを複数回実行して結果順序の目的の位置まで移動することにより、問合せを即座に再実行し、中断する前に現在の位置であった場所からフェッチを再開できます。
このステートレスEJBの例では、「例3: XQSFacadeI APIを使用したXQSビュー」で使用したBasicFileWS XQSビューを再使用しており、そのコードの一部が繰り返されています。ビューとその構成は、この項を参照してください。
JNDI参照およびステートレスBeanの作成に加えて、このステートレスEJBの例とXQSFacadeIの例の重要な違いは、結果の処理にあります。ステートレス・セッションの結果は、XMLItemインスタンスを含むベクターとして完全にマテリアライズされます。XMLItemインスタンスを取得するためのgetNextItem()メソッドがBean内にあるのとは対照的に、その後、そこから項目を1つずつ取得し、XMLItemとしてキャストします。ただし、処理の基本的な性質は変わりません。
... //lookup and create the EJB to execute the xquery InitialContext ic = new InitialContext(); oracle.xqs.client.ejb.stateless.XQSClientLocalHome home = (oracle.xqs.client.ejb.stateless.XQSClientLocalHome) ic.lookup("java:comp/env/XQSClientStatelessLocal"); oracle.xqs.client.ejb.stateless.XQSClientLocal bean = home.create(); String xqueryView = "BasicFileWS"; QueryParameterI param = XQSFactory.getQueryParameter("custName"); param.setString("John Ford"); QueryParameterI[] params = new QueryParameterI[1]; params[0] = param; java.util.Vector result = bean.executeView(xqueryView,"http://xmlns.oracle.com/ias/xqs",params); java.util.Enumeration resultEnum = result.elements(); while(resultEnum!=null && resultEnum.hasMoreElements()) { XMLItem item = (XMLItem)resultEnum.nextElement(); if(item.instanceOfType(XMLItem.XMLITEM_STRING)) { resultBuf.append(item.getString()); } else if(item.instanceOfType(XMLItem.XMLITEM_INT)) { resultBuf.append(item.getInt()); } else if(item.instanceOfType(XMLItem.XMLITEM_LONG)) { resultBuf.append(item.getInt()); } else if(item.instanceOfType(XMLItem.XMLITEM_INTEGER)) { if(item.intFormat()) resultBuf.append(item.getInt()); else resultBuf.append(item.getDecimal().intValue()); } else if(item.instanceOfType(XMLItem.XMLITEM_BOOLEAN)) { resultBuf.append(item.getBoolean()); } else if(item.instanceOfType(XMLItem.XMLITEM_FLOAT)) { resultBuf.append((float)item.getDouble()); } else if(item.instanceOfType(XMLItem.XMLITEM_DOUBLE)) { resultBuf.append(item.getDouble()); } else if(item.instanceOfType(XMLItem.XMLITEM_XDT_DAYTIMEDURATION)) { resultBuf.append(item.getDayTimeDuration()); } else if(item.instanceOfType(XMLItem.XMLITEM_YEARMONTHDURATION)) { resultBuf.append(item.getYearMonthDuration()); } else if(item.instanceOfType(XMLItem.XMLITEM_DURATION)) { resultBuf.append(item.getLexicalValue()); } else if(item.instanceOfType(XMLItem.XMLITEM_DATETIME)) { resultBuf.append(item.getCalendar().getTime()); } else if(item.instanceOfType(XMLItem.XMLITEM_ANYURI)) { resultBuf.append(item.getString()); } else if(item.instanceOfType(XMLItem.XMLITEM_DECIMAL)) { resultBuf.append(item.getDecimal().intValue()); } else if(item.instanceOfType(XMLItem.XMLITEM_NODE)) { resultBuf.append(item.getNode().getNodeName()); } else if(item.instanceOfType(XMLItem.XMLITEM_HEXBINARY)) { resultBuf.append(item.getString()); } else if(item.instanceOfType(XMLItem.XMLITEM_BASE64BINARY)) { resultBuf.append(item.getString()); } // Here is where you might use a bean.getErrors() call and process errors. // (Assuming appropriate configuration.) } ...
「XQSクライアントAPIを使用するための一般的なコーディング手順」を参照してください。XQS JSPタグ・ライブラリの場合は、（問合せの作成後に）ステートフル・アクセス・モードとステートレス・アクセス・モードのどちらを選択するかによって、次に示すように手順の詳細が異なります。
taglibを介して、TLD URIおよび目的の接頭辞を指定してXQS JSPタグ・ライブラリをインポートします。
executeCursorタグを使用してステートフル・モードで問合せを実行するか、executeタグを使用してステートレス・モードで問合せを実行します。executeCursorタグまたはexecuteタグで次の処理を行います。
xqueryString属性を使用して非定型問合せを指定するか、xqsViewName属性およびnamespace属性を使用してXQSビューを指定します。
toXMLDoc属性を使用）、および結果のjava.util.ArrayListインスタンス（resultItems属性を使用）です。必要に応じて、JSP出力ストリーム（toWriter属性を使用）に出力することもできます。結果は、表8-2「バインド・パラメータ用にXQSでサポートされている型」に基づいて、Javaオブジェクト型で表されます。
emptySequenceエラー・モードまたはerrorMessageエラー・モードを使用した場合は、必要に応じてerrors属性を使用し、問合せの実行時にこれらのデータソース内で発生したエラーを処理できます。これにより、XQSErrorIオブジェクトのコレクションに対するイテレータが戻されます。エラーの構成と処理の詳細は、「XQSエラー処理モードおよびAPIの使用方法」を参照してください。
executeCursorタグまたはexecuteタグでは、各入力パラメータに対してparamサブタグを使用します。必要に応じて、paramタグのlocalName、namespace、valueおよびtypeの各属性を使用します。
executeCursorタグの場合は、関連するnextタグを使用して結果を項目ごとに取得するか、結果をバッチで取得して出力媒体に送ります。 executeタグの場合は、結果が完全にマテリアライズされて、出力媒体に送られます。
nextを1回実行するたびに、その結果を処理する必要があることに注意してください。処理せずに再びnextを実行すると、結果が上書きされます。
executeCursorタグの場合は、closeタグを使用して、問合せに関連付けられているすべてのリソースを解放します。この手順は、executeタグには適用されません。
これらの手順は、次の例の中で示されています。「XQS JSPタグ・ライブラリのリファレンス」も参照してください。
ステートフル・アクセスとステートレス・アクセスの使い分けの詳細は、「ステートフル・クライアントとステートレス・クライアント」を参照してください。
XQSを使用するJSPページでは、ステートフル・アクセスとステートレス・アクセスのどちらを使用するかは、使用するタグによって決まります。executeCursorタグの場合はステートフル・アクセスを使用しますが、executeタグの場合はステートレス・アクセスを使用します。
前述のように、問合せ（非定型またはビュー）をステートレスJSPアクセス・パターンで実行すると、結果が完全にマテリアライズされて、属性の設定（XML DOMドキュメント、Object[]配列、およびオプションのJSP出力ストリーム）を介して選択した出力媒体に送られます。その後、これらの結果を必要に応じて処理します。ステートフル・アクセス・パターンの場合は、問合せの実行後に、nextタグを使用して、1つずつ項目を取得して処理します。
このステートフルJSPの例では、「例3: XQSFacadeI APIを使用したXQSビュー」のBasicFileWS XQSビューを再使用しています。ビューとその構成は、この項を参照してください。
この項のコード例では、次のことが実行されます。
pageディレクティブによって、要求されたクラスがインポートされます。
taglibディレクティブによって、タグ・ライブラリのTLD URIおよび使用するタグ接頭辞が指定されます。
executeCursorタグによってビューが実行され、オープン・カーソルがフェッチ可能な状態になります。namespace属性によって、基礎となるXQSView関数が定義される名前空間が指定されます。
executeCursorのparamサブタグによって、入力パラメータ（顧客名）が指定されます。
cursorIdの設定を介してexecuteCursorタグに関連付けられているnextタグにより、結果ごとに処理が繰り返され、出力媒体（XML文書および結果項目のArrayListインスタンス）が移入されます。その際には、処理対象のデータが残っているかどうかを調べるために、繰返し処理のたびにitemsFetched属性が使用されます。nextタグは、executeCursorタグで指定されたカーソルID（mycursor）を参照する必要があります。
closeタグにより、カーソルがクローズされ、関連付けられているリソースが解放されます。このタグも、executeCursorタグで指定されたカーソルID（mycursor）を参照する必要があります。
注意
emptySequenceモードまたはerrorMessageモード）を使用していれば、myerrorsイテレータを処理できます。「XQSエラー処理モードおよびAPIの使用方法」を参照してください。
<%@ page import="oracle.xml.parser.v2.XMLElement" %> <%@ page import="oracle.xml.parser.v2.XMLDocument" %> <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/xquerytag.tld" prefix="xq"%> <% String xqueryView = "BasicFileWS"; int items; %> <xq:executeCursor xqsViewName="<%=xqueryView%>" namespace="http://xmlns.oracle.com/ias/xqs" resultItems="myresults" toXMLDoc="mydoc" cursorId="mycursor" errors="myerrors" > <xq:param localName="custName" value="John Ford" type="String"/> </xq:executeCursor> <% do{ // Populate the XML document and result items array. %> <xq:next cursorId="mycursor" itemsFetched="fetched" /> <% items=fetched.intValue(); }while(items>0) // Here is where you might process the "myerrors" error iterator. // (Assuming appropriate configuration.) // Retrieve results from the XML document mydoc and the result items array myresults. // (This processing is not XQS-specific.) %> <xq:close cursorId="mycursor" />
この例では、XQS JSP executeタグを使用して非定型問合せが実行され、ステートレス・アクセス・パターンが使用されます。この例の主な目的は、前述のステートフル・アクセスの使用例と比較することで、次の事項を比較および対比させることにあります。
executeCursorタグを使用しますが、ステートレス・アクセスでは、かわりにexecuteタグを使用します。executeタグにnextサブタグが使用されていないため、closeタグは不要です。
<%@ page import="oracle.xml.xqxp.datamodel.XMLItem" %> <%@ page import="oracle.xml.parser.v2.XMLElement" %> <%@ page import="oracle.xml.parser.v2.XMLDocument" %> <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/xquerytag.tld" prefix="xq"%> <% StringBuffer xqueryBuf = new StringBuffer(); xqueryBuf.append("declare namespace xqs=\"http://xmlns.oracle.com/ias/xqs\";\n"); xqueryBuf.append("declare function xqs:get_poSQ($bind as xs:string) external;\n"); xqueryBuf.append("for $po in xqs:get_poSQ(\"http://localhost:8888/myrepository/pos-2KB.xml\") \n"); xqueryBuf.append("return $po\n"); String xqueryStr = xqueryBuf.toString(); %> <xq:execute xqueryString="<%=xqueryStr%>" toXMLDoc="mydoc" resultItems="myresults" errors="myerrors" /> <% // Here is where you might process the "myerrors" error iterator. // (Assuming appropriate configuration.) %> <% // Retrieve the results from either the XML document mydoc or result items array // myresults. (This processing is not XQS-specific.) %>
XQSでは、自動生成されたサーブレットを介して実装されたWebサービスを使用して、XQSビューをWebサービス操作として公開できます。詳細および関連する詳細は、「XQSビューをWebサービス操作として公開するためのOC4JPackagerの追加の出力」を参照してください。
Webサービス・クライアントは、独自に提供する必要があります。
この項では、OC4JPackagerを使用してXQS関連ファイルをアプリケーションにバンドルする方法について説明します。概要は、「OC4JPackagerの概要」を参照してください。
OC4JPackagerでは、他のEARのようにOC4Jにデプロイできる、EARファイルが作成されます。一般情報は、『Oracle Containers for J2EEデプロイメント・ガイド』を参照してください。
この項には、次の項目が含まれます。
この項では、J2EEアプリケーションでOC4JPackagerを実行し、XQS機能を使用できるようにするための基本的な準備および実行の手順を示します。ここに出てくるOC4JPackagerのパラメータおよびJavaのプロパティに関する一般情報は、「OC4JPackagerのリファレンス」を参照してください。
OC4JPackagerを実行するには、次の準備手順を完了してください。
web.xmlおよびejb-jar.xmlなど）を使用します。その後、必要に応じてこれらのファイルをOC4JPackagerのEARファイルにバンドルするか、他の関連ファイル（application.xmlなど）とともに、EARファイルの構造と内容を反映するディレクトリ構造に置いておきます。
-appArchivesパラメータ（必須）を介して、OC4JPackagerにそのディレクトリを指定します。
.xqまたは.sql）ファイルが配置されるXQSリポジトリとして目的のディレクトリを選択し、XQSビュー（.xqまたは.sql）ファイルをそこに配置します。 -repositoryパラメータを介して、OC4JPackagerにそのディレクトリを指定します。
xqs-config.xmlファイルの目的のディレクトリを選択し、ファイルをそのディレクトリに配置します。ただし、XQS構成が完了していることが前提条件になります（「XQS関数の構成方法」を参照）。-xqsConfigパラメータ（必須）を介して、OC4JPackagerにそのディレクトリを指定します。
OC4JPackagerの実行時には、必要に応じて次を指定します。例は、次項「コマンドラインでのOC4JPackagerの実行」を参照してください。
-appArchivesパラメータを使用して、アプリケーションが配置されている場所（EARファイルの場所、つまりEAR構造のトップレベル・ディレクトリ）を指定します。
-repositoryパラメータを使用して、XQSリポジトリのディレクトリを指定します。
-xqsConfigパラメータを使用して、アプリケーションのxqs-config.xmlファイルへのフルパス（ファイル名を含む）を指定します。
-nameパラメータおよび-outputパラメータを使用して、OC4JPackagerによって作成されるEARファイルの名前と出力ディレクトリを指定します。
-jspフラグを使用します。
-sfフラグを使用します。
-slフラグを使用します。
-no_wsフラグを使用します。
（XQSFacadeIインタフェースは常に含まれます。）
java.homeを使用して、Javaのホーム・ディレクトリを指定します。OC4JPackagerによって、このディレクトリから、タスクに必要なjavaコマンドが実行されます。
xds.packager.work.dirを使用します。デフォルトは、user.home Javaプロパティで指定されたディレクトリです。
java.util.logging.properties.fileを使用して、Javaのロギング設定（OC4JPackagerのロギング・レベルを含む）を指定するロギング・プロパティ・ファイルを指定します。ロギング・プロパティは、次の場所で説明されているように、標準のJ2SEロギングによって定義されます。
http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/
oracle.homeを使用します。この処理は、OC4JPackagerフラグ-jsp、-sf、-sl（「OC4JPackagerのパラメータ」を参照）、および関連するJARファイルを使用する場合には必須です。
OC4JPackagerは、OC4JPackager.jarを起動するjavaコマンド（コマンド・プロンプトは%）を使用して、コマンドラインから実行できます。
% java -jar OC4JPackager.jar ...
OC4JPackager.jarは、XQS配布のxds/toolsディレクトリにあり、OC4Jコンテナ内のインストール場所から使用する必要があります。
次に例を示します（$ORACLE_HOMEはOracleインストールのホーム・ディレクトリとして設定されており、\は行折返しを示します）。この例は、XQS JSPタグ・ライブラリおよびステートフルEJBクライアントAPIを使用するアプリケーション用です。現在のディレクトリからの相対パス、または絶対パスを指定できます。
% java -jar OC4JPackager.jar \ -Djava.home=/home/myjavainstall \ -Dxds.packager.work.dir=$ORACLE_HOME/temp \ -Doracle.home=$ORACLE_HOME \ -Djava.util.logging.properties.file=myfile.properties \ -appArchives $ORACLE_HOME/myapp \ -xqsConfig $ORACLE_HOME/xds/myconfig/xqs-config.xml \ -repository $ORACLE_HOME/xds/repository \ -output $ORACLE_HOME/xds/mystaging -name myxqsapp.ear \ -jsp -sf
もしくは、次の項で説明するように、Antを介してOC4JPackagerを実行できます。
「OC4JPackagerの基本的な出力」も参照してください。
前の項で説明したように、コマンドラインからOC4JPackagerを実行するかわりに、標準のAnt javaタスクを介して、Antを使用したビルド処理の一部としてOC4JPackagerを実行できます。Antの一般情報は、ApacheのWebサイトhttp://ant.apache.org/manual/を参照してください。（また、OC4J固有のAntタスクに関する情報は、『Oracle Containers for J2EEデプロイメント・ガイド』を参照してください。）
例として次に示すAntビルド・ファイルの一部では、OC4JPackagerが起動されます。この例は、前項で示した例のコマンドラインに対応しています。
<java jar="OC4JPackager.jar" fork="true" failonerror="true"> <jvmarg value="-Doracle.home=${ORACLE_HOME}"/> <jvmarg value="-Djava.home=/home/myjavainstall"/> <jvmarg value="-Dxds.packager.work.dir=${ORACLE_HOME}/temp"/> <jvmarg value="-Djava.util.logging.properties.file=myfile.properties"/> <arg line="-appArchives ${ORACLE_HOME}/myapp"/> <arg line="-xqsConfig ${ORACLE_HOME}/xds/myconfig/xqs-config.xml"/> <arg line="-repository ${ORACLE_HOME}/xds/repository"/> <arg line="-output ${ORACLE_HOME}/xds/mystaging" /> <arg line="-name myxqsapp.ear"/> <arg line="-jsp"/> <arg line="-sf"/> </java>
OC4JPackagerで作成されたEARファイルは標準的な構造を持ち、少なくとも1つの追加コンポーネントがあります。このコンポーネントはxqs-resources.jarという名前のファイルで、XQS構成ファイルおよびXQSリポジトリ・ファイル（XQSビューの.xqファイル）のディレクトリが含まれます。
|
注意 Webサービス操作として公開するXQSビューが存在する場合は、EARファイルに追加のコンポーネントが含まれます。次項「XQSビューをWebサービス操作として公開するためのOC4JPackagerの追加の出力」を参照してください。 |
WebモジュールmywebappおよびEJBモジュールmyejbで構成されるアプリケーションでは、OC4JPackagerによって次のようなEARファイルの内容が作成されます。
META-INF/ application.xml orion-application.xml data-sources.xml mywebapp.war myejb.jar xqs-resources.jar
xqs-resources.jar以外にも、アプリケーションには、application.xmlファイル、必要に応じてオプションのorion-application.xmlファイルとdata-sources.xmlファイル、Webモジュール用WARファイル、EJBモジュール用EJB JARファイルなどがすでに含まれている必要があります。
xqs-resources.jarの構造は次のとおりです。
APP-REPOSITORY/ filename.xq filename.xq filename.xq ... xqs-config.xml xds-application.properties
ファイルxds-application.propertiesは、XQSによって内部的に使用されます。
XQS構成でWSDLvisibility="true"と設定されたXQSビュー（SQLベースのビューを除く）では、XQSによって、ビューがWebサービス操作として公開されます。いずれのWebサービスでも、操作を起動するWebサービス・クライアントが必要です。
OC4JPackagerによって、Webサービスの実装、および公開される各XQSビューの操作を定義するWSDLドキュメントが作成されます。その後、OC4JPackagerによって、次の内容を含むWARファイルが作成されます。
また、OC4JPackagerによって、アプリケーションのapplication.xmlファイルが更新され、追加のWebモジュールのエントリが作成されます。
XQSビューWebサービスを表す追加のWebモジュールの名前、コンテキスト・ルートおよびWAEファイルは、アプリケーションの名前に対応します。アプリケーションmyappの場合は次のようになります。
生成されたWSDLファイルは、常にxqsview-WS.wsdlになります。
Webサービスを表し、Oracle Webサービスのテスト・ページにつながるサーブレットのURLパターンは、常に/xqs-wsです。
つまり、XQSビューWebサービスのWSDLのURLは、http://host:port/myapp-WS/xqs-ws?WSDLとなります。
WSDLドキュメントでは、wsdl:operationの名前は、XQS構成（<xqsview-source>の<function-name>サブ要素）で定義された対応するXQS関数の名前と同じになります。各wsdl:inputメッセージ・タイプは、XQS構成（<xqsview-source>の<input-parameters>サブ要素）で定義された入力パラメータ・タイプに対応するXML型にマップされます。各wsdl:outputメッセージ・タイプは、XQS構成（<xqsview-source>の<output-element>サブ要素）で定義された出力要素に対応するXML要素または型にマップされます。これらは、stringやintなどの単純型、またはユーザーが定義した複合型のどちらかになります。バインディングは、SOAPドキュメント/ラップ・バインディングになります。
次の例は、次のすべての項の内容を合せたものです。
この章で前述した次の構成では、WSDLvisibility="true"の設定を介して、ビューBasicFileWSがWebサービス操作として公開されます。
<xqsview-source WSDLvisibility="true" isCached="false"> <function-name prefix="xqs">BasicFileWS</function-name> <input-parameters type-match="none" > <part position="1" name="custName"> <schema-type prefix="xs">string</schema-type> </part> </input-parameters> <output-element namespace="http://xmlns.oracle.com/ias/xqs/CustomerDemo" location="http://host:port/xqsdemos/MyTypes.xsd" type=CustomerOrdersType>customerOrders </output-element> </xqsview-source>
後述の説明は、この例がmyappというアプリケーションの一部であることを前提としています。
アプリケーションmyappがmywebapp.warおよびmyejb.jarで構成されており、1つ以上のXQSビューがWebサービス操作として公開されると仮定します。OC4JPackager実行後のアプリケーションEARファイルの関連する内容は、次のようになります。
META-INF/ application.xml mywebapp.war myejb.jar myapp-WS-web.war xqs-resources.jar
WARファイルmyapp-WS-web.warは、公開されるビューのWebサービス操作の自動作成済サーブレット実装用です。この内容は、次の項を参照してください。
公開されるビューのWebサービス操作のサーブレット実装用に作成されたmyapp-WS-web.warの内容は、次のとおりです。
WEB-INF/ web.xml oracle-webservices.xml wsdl/ xqsview-WS.wsdl
特に、WSDLドキュメントに注意してください。WSDLの部分的な例は、次項「例: Webサービス操作として公開されるビューのWSDLドキュメント」を参照してください。
この項では、Webサービスとして公開されるXQSビュー用のOC4JPackagerによって生成されるWSDLドキュメントの一部を示します。この例では、BasicFileWSという名前のビューに関連する部分を示します。
... <definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xqscwsNsPref="xqs-client-ws" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xqs0="http://xmlns.oracle.com/ias/xqs" xmlns:tns="xqs- client-ws_myapp-WS" name="myapp-WS" targetNamespace="xqs- client-ws_myapp-WS"> <types> ... <schema targetNamespace="http://xmlns.oracle.com/ias/xqs" xmlns:xqs1="http://xmlns.oracle.com/ias/xqs/CustomerDemo" xmlns:tns="http://xmlns.oracle.com/ias/xqs" ... > <import namespace="xqs-client-ws"/> <import namespace="http://xmlns.oracle.com/ias/xqs/CustomerDemo" schemaLocation="http://host:port/xqsdemos/MyTypes.xsd"/> <complexType name="BasicFileWSType"> <sequence> <element name="custName" type="string" nillable="true" /> </sequence> </complexType> <complexType name="BasicFileWSResultType"> <sequence> <element name="return" nillable="true"> <complexType> <sequence> <element name="result" nillable="true"> <complexType> <sequence> <element name="customerOrders" type="xqs1:CustomerOrdersType" minOccurs="0" maxOccurs="unbounded" /> </sequence> </complexType> </element> <element name="errors" nillable="true" minOccurs="0"> <complexType> <sequence> <element name="xqserror" type="xqscwsNsPref:XQSErrorType" maxOccurs="unbounded" /> </sequence> </complexType> </element> </sequence> </complexType> </element> </sequence> </complexType> <element name="BasicFileWS" type="tns:BasicFileWSType" /> <element name="BasicFileWSResult" type="tns:BasicFileWSResultType" /> … </schema> … </types> … <message name="BasicFileWSRequest"> <part name="parameters" element="xqs0:BasicFileWS" /> </message> <message name="BasicFileWSResponse"> <part name="return" element="xqs0:BasicFileWSResult" /> </message> … <portType name="XQSViewWebServices"> <operation name="BasicFileWS"> <input message="tns:BasicFileWSRequest" /> <output message="tns:BasicFileWSResponse" /> </operation> … </portType> <binding name="HttpSoap11Binding" type="tns:XQSViewWebServices"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" /> <operation name="BasicFileWS"> <soap:operation /> <input> <soap:body use="literal" parts="parameters" /> </input> <output> <soap:body use="literal" parts="return" /> </output> </operation> … </binding> <service name="XQSView-WS"> <port name="HttpSoap11" binding="tns:HttpSoap11Binding"> <soap:address xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" location="http://host:port/myapp-WS/xqs-ws" /> </port> </service> </definitions>
この項では、XQSで提供されるパフォーマンス機能について説明します。この項には、次の項目が含まれます。
前述のように、XQSクライアントAPIでは、結果が完全にマテリアライズされてプロセス・メモリーに格納されるステートレス問合せの実行、またはカーソルを介して結果が段階的にアクセスされるステートフル問合せの実行を選択できます。どちらの方法にも、長所と短所があります。
ほとんどの状況では、ステートレス実行が適しています。これは、評価が完了した直後に、関連付けられているリソースが解放されるためです。ただし、結果順序に含まれる項目の全体のサイズが大きすぎて、順序全体を一度にマテリアライズするとプロセス・メモリーが不足する場合には、ステートレス実行を使用できません。このような場合は、問合せが結果を項目ごとに提供するのを妨げるもの（たとえば集計式など）がないかぎり、カーソル・モードが唯一の手段になります。
追加情報は、「ステートフル・クライアントとステートレス・クライアント」を参照してください。
この項では、XQS使用時のキャッシュの構成方法を詳しく説明し、関連する考慮事項を示します。
XQS実装では、OC4J Java Object Cacheを使用してキャッシングが行われます。Java Object Cacheが実行中で（また、必要に応じて自動的に起動され）、その構成ファイル
Java Object Cacheのすべての構成は、XQSアプリケーションだけでなく、OC4Jインスタンス全体に適用されることに注意してください。
重要
ORACLE_HOME/j2ee/home/config/javacache.xmlが存在する必要があります。通常は、このファイル・ディレクトリを更新する必要はありませんが、更新してもかまいません。第7章「Java Object Cache」を参照してください。
XQSキャッシングは、XQS関数ごとに（本質的には、アクセスするデータソースごとに）個別に構成されます。特定のXQS関数に対してキャッシングを使用するには、次の手順を行います。
考慮すべき対策は、次項「XQSキャッシングの対策」を参照してください。すべての要素と属性に関する完全な説明は、「XQS構成ファイルのリファレンス」を参照してください。
<document-source>要素、<xqsview-source>要素または<wsdl-source>要素のisCached属性を介して、キャッシングを有効化します。次に例を示します。
<document-source isCached="true"> ... </document-source>
<document-source>要素、<xqsview-source>要素または<wsdl-source>要素の<cache-properties>サブ要素を使用します。time-to-live属性には、キャッシュ・エントリの期限が切れるまでの保持時間（秒単位）を決定する整数値が使用されます。次に例を示します。
<cache-properties time-to-live="600"> ... </cache-properties>
<cache-properties>の<in-memory>サブ要素を使用し、useSpool属性およびuseDiskCache属性を介して、使用するキャッシュ・モードを指定します。単純なメモリーベースのキャッシングの場合は、useSpoolとuseDiskCacheの両方をfalseに設定します。メモリー不足になると必要に応じてキャッシュ・データをディスクにスプールできるメモリーベースのキャッシングの場合は、useSpoolをtrueに設定し、useDiskCacheをfalseに設定します。ディスクベースのキャッシングの場合は、useDiskCacheをtrueに設定し、useSpoolをfalseに設定します。（関連する考慮事項は、次項「XQSキャッシングの対策」を参照してください。）次の例では、必要に応じてスプーリングを使用する、メモリーベースのキャッシングが使用されています。
<in-memory useSpool="true" useDiskCache="false"/>
次に、完全なキャッシュ構成の例を示します。
<document-source isCached="true"> ... <cache-properties time-to-live="600"> <in-memory useSpool="true" useDiskCache="false"/> </cache-properties> ... </document-source>
XQSキャッシングに関して、次の考慮事項に注意してください。
<in-memory>設定の定義では、単純なメモリーベースのキャッシング（useSpool="false"およびuseDiskCache="false"）、メモリー不足により必要になった場合にディスクにスプールできるメモリーベースのキャッシング（useSpool="true"およびuseDiskCache="false"）、ディスクベースのキャッシング（useSpool="false"およびuseDiskCache="true"）のどれを使用するかを考慮します。追加情報は、「<in-memory>」を参照してください。注意事項は次のとおりです。
キャッシュ・データの危険度と実行速度の重要度を比較検討します。
「要件、制限事項および特記事項」で説明しているXQS関数とノードIDの問題は、一部の例外的または特殊な状況で発生し、キャッシングを使用しているかどうかによって、問合せ結果が異なる場合があることに注意してください。ただし、ほとんどの問合せが（ノードではなく）値が等しいことに依存するため、通常はこの問題は発生しません。
システム容量や一般的なメモリー節約オプションの使用に関係なく、データセットが大きいためにメモリーによる制限を受ける場合があります。この問題を解決するには、背後で作業単位方式を使用します。この方法では、取得されるデータの合計量に関係なく、一定量のメモリーが使用されます。XQSは、Oracle XDK内の依存するテクノロジおよび中間層のXQueryと連携しているため、XQSの実行中は常に、このスケーラブルな解決方法が提供されます。
ただし、この作業単位方式でも解決できないほどデータセットが大きい場合もあります。ドキュメント・ソースについてこのような状況が発生した場合は、データソースによって大量のメモリー・リソースが消費されるため、メモリー節約の内部最適化オプションを使用するように、XQSに指示することができます。次の例のように、<document-source>要素の属性であるlargeDataフラグを使用します。
<document-source largeData="true"> ... </document-source>
サイズの大きいドキュメント・ソースをメモリーにロードできないときは、このフラグを有効化することで可能になる場合があります。
「XQSエラー処理の概要」で示したように、XQS関数を構成して、（データソースを使用できない、またはデータ変換の問題などの）エラーが発生しても処理を続行することができます。処理を続行するようにXQS関数を構成した場合は、後でoracle.xqs.client.XQSErrorIオブジェクトのイテレータとして戻されるエラーを取得し、エラーの情報を入手できます。
XQSでは、XQS関数内部のエラーにのみ、特別な処理が適用されます。構文エラーやタイプの不一致などの通常のXQueryエラーの場合は、いずれのXQSエラー・モードでも、問合せの実行が停止します。
XQSエラー・モードは、XQS関数ごとに個別に構成します。1つの関数のエラー・モードが、同じ問合せ内の他のXQS関数の動作に影響することはありません。
次の各項では、処理を続行してエラー情報を戻すためのXQS関数の構成方法、およびエラー情報の取得に使用できるメソッドについて説明します。
xqs-config.xmlで構成する各データソースについて、ソース要素<document-source>、<xqsview-source>または<wsdl-source>のonError属性を介して、XQSのエラー処理を指定できます。サポートされている設定は次のとおりです。
dynamicError（デフォルト）: この設定では、XQS関数の評価時に問題が発生すると、XQuery動的エラーが発生し、問合せが停止します。このような状況ではエラー・オブジェクトは戻されず、例外メッセージ以外の情報を取得できません。
emptySequence: この設定では、XQS関数によって生成されたエラーが発生しても、空のXML順序が関数の結果として戻され、問合せの実行は続行されます。次の各項で示すように、エラー・オブジェクトを取得して、そのオブジェクトから情報を入手できます。
errorMessage: この設定では、XQS関数によって生成されたエラーが発生すると、関数の結果に対して単一項目のXML順序が戻されます。順序内の項目はエラー・メッセージを表します。このメッセージは、事前構成済のメッセージまたはデータソースが戻すなんらかのメッセージで、構成によって異なります。また、次の各項で示すように、エラー・オブジェクトを取得して、そのオブジェクトから情報を入手できます。
特定のデータソースに対するXQSエラー処理の構成手順は、場合によって2つになります。
<document-source>要素、<xqsview-source>要素または<wsdl-source>要素のonError属性の設定を指定します。
errorMessageモードを使用する場合は、必要に応じて<document-source>、<xqsview-source>または<wsdl-source>の<error-message>サブ要素を使用します。これにより、問合せ結果に対して戻される単一項目のXML順序に、XQSのエラー・メッセージが含まれるように、エラー・メッセージが事前構成されます。
次に、emptySequenceモードを使用するソースの例を示します。
<document-source onError="emptySequence"> ... </document-source>
次に、事前構成済のメッセージを使用するerrorMessageモードの使用例を示します。
<wsdl-source onError="errorMessage"> ... <error-message>No information available</error-message> ... </wsdl-source>
errorMessageモードの場合、事前構成済のメッセージを指定しないと（つまり、<error-message>要素を使用しないと）、データソースによって戻されたメッセージがそのままXQSによって使用され、そのメッセージが、関数の結果として戻された単一項目のXML順序に含められます。データソースのエラー・レポート機能が不十分な場合には、意味のあるエラー・メッセージを取得することが不可能になることがあります。この場合は、事前構成済のメッセージが指定されていないと、エラー・メッセージが空の状態で戻されます。
戻される順序に含まれる単一項目のタイプは、xs:stringまたはxs:nodeのどちらかになります。
xqserrorで、そのテキスト値がエラー・メッセージになります。また、エラー・ノードには、functionName、typeおよびcodeという3つの属性があります。XQSエラー・ノードは次のようになります。
<xqserror functionName="XQS function name" type="XQSERR_XXX" code="XQS 0NNN" > error message</xqsrror>
XQSにより、関数のタイプ情報に基づいて、そのエラー項目により適したタイプが選択されます。
xs:nodeになります。これは、ドキュメント関数が常にXMLノードを戻すことになっているためです。
<output-element>を使用して構成されており、タイプ名または要素名がプリミティブXML Schemaタイプでない場合、この関数はXQSによってXML要素タイプであるとみなされ、エラー項目がXMLノードとして作成されます。
xs:stringではないにもかかわらず）<output-element>によってプリミティブXML Schemaタイプが指定されている場合、または<output-element>が指定されていない場合は、XQSによって、エラー項目が文字列として作成されます。
errorMessageエラー・モードを使用してXQS関数を構成し、<output-element>を指定しない場合、または<output-type>を指定したがユーザーが定義した複合型もしくはxs:stringでない場合は、その関数を使用する問合せのXQueryプロローグでその関数の戻り型を指定しないでください。外部XQuery関数の戻り型の宣言は、オプションです。前述の状況で戻り型を指定すると、実行時に、この戻り型がXQueryによって強制的に使用されます。XQS関数の実行時にエラーが発生すると、XQSによって、エラー・メッセージが文字列として戻されます。これが、問合せのプロローグで宣言された戻り型と競合します。戻り型を宣言しない場合は、強制的な型の一致は実行されません。
<xqsview-source>要素について、基礎となる問合せまたは別の<xqsview-source>関数を使用してネストされた問合せの中のXQS関数によって、errorMessageエラー処理オプションが定義されているかどうかを確認してください。このような、onError="errorMessage"オプションを使用するネストされた<xqsview-source>関数では、それぞれ適切な<output-element>定義が指定される必要があります。この要件が満たされていない場合に、ネストされたXQSビュー関数でエラーがすると、XQSによって、その関数に対してxs:stringタイプの戻り値が作成されます。これは、宣言された最外部のXQSビュー関数のタイプに違反するため、タイプの不一致による追加のXQueryエラーが作成されます。その他のエラー処理オプションは、この要件の対象ではありません。
dynamicErrorモードでエラーが発生した場合は、XQSクライアントによって、例外が次のように伝播されます。まず、EJBによってEJB例外が戻されます。次に、XQSFacadeIインスタンスによってXQS例外をラップするXQS例外がスローされます。そして、JSPタグによって、標準のJSP errorPage属性を介して処理できるJSPタグ例外がスローされます。
ORACLE_HOME/j2ee/home/log/oc4j/log.xmlなど）。OC4Jロギングの一般情報は、『Oracle Containers for J2EE構成および管理ガイド』を参照してください。
XQS関数がemptySequenceまたはerrorMessageのエラー処理モードを使用するように構成されていれば、XQSクライアントAPIの機能を使用して、エラー・オブジェクトのイテレータを取得でき、このイテレータから、問合せ中に発生した問題に関する情報を入手できます。概要は次のとおりです。
XQSFacadeIインタフェースまたはXQS EJB APIのどちらか一方（ステートフルまたはステートレス）を使用する場合は、次のメソッドを使用して、エラー・オブジェクトを含むイテレータを取得します。
java.util.ListIterator getErrors()
executeタグまたはexecuteCursorタグのerrors属性の値として目的の変数名を指定します。JSPタグの実装により、ListIterator変数が作成され、この変数に、エラー・オブジェクトを含むイテレータが移入されます。
どちらの場合も、oracle.xqs.client.XQSErrorIオブジェクトを含むイテレータを取得できます。次に例を示します。
... XQSFacadeI bean = XQSFactory.getXQSFacade(); ... bean.executeView(viewname, namespace, queryparams); ... ListIterator errorIt = bean.getErrors(); XQSErrorI error = null; while(errorIt.hasNext()) { error = (XQSErrorI)errorIt.next(); (Process errors) } ... bean.close(); ...
次に、JSPの例を示します。
XQSErrorI error=null; ... <xq:executeCursor ... errors="errorIt" ... > ... </xq:executeCursor> ... <xq:next ... /> while(errorIt.hasNext()) { error = (XQSErrorI)errorIt.next(); (Process errors) }
詳細およびエラー情報取得の例は、次の「XQSエラー・オブジェクトからの情報の取得」および「例: エラーの取得および処理」の各項を参照してください。
前項の「XQSエラー・オブジェクトの取得」で、oracle.xqs.client.XQSErrorIオブジェクトを含むjava.util.ListIteratorインスタンスの取得方法について説明しました。
このイテレータ・インスタンスを処理すると、個々のXQSErrorIオブジェクトを取得できます。ListIteratorタイプには、次のメソッドが含まれます。
Object next(): このメソッドを使用すると、イテレータ内に次の要素が戻されます。各要素は、XQSErrorIタイプにキャストできます。
boolean hasNext(): このメソッドを使用すると、要素が残っている場合にtrueが戻されます。
その後、個々のXQSErrorIインスタンスを使用して、問合せ中に発生した各エラーの情報を取得できます。
|
注意
|
この項では、エラー情報を取得するためのXQSErrorIメソッドを要約し、XQSエラーのタイプを要約します。完全な情報は、「XQSErrorIリファレンス」を参照してください。
各XQSErrorIインスタンスでは、次の処理を行えます。ここに示す例では、xqserrというXQSErrorIインスタンスを使用しています。
String funcname = xqserr.getFunctionQName();
int errortype = xqserr.getErrorType();
String typeStr= XQSErrorI.typeNames(xqserr.getErrorType()
String errormessage = xqserr.getErrorMessage();
ORA-xxxxxコードなど）について、エラー・コードを取得します。
String errorcode = xqserr.getErrorCode();
String errorstring = xqserr.toString(); ... String errorxmlstring = xqserr.toXMLString(); ... org.w3c.dom.node errornode = xqserr.toXMLNode();
エラー・タイプの整定数の要約は、次のとおりです。
XQSERR_MISSING_SRC: データソースが見つかりません。
XQSERR_SRC_ACCESS: データソースは見つかりましたがアクセス・エラー（無効なログインなど）が戻されました。
XQSERR_SRC_ERROR: データソースが見つかりアクセスしましたが、その他のエラーが戻されました。
XQSERR_PARAM: バインド・パラメータをソースに渡すとき、もしくはソースから出力パラメータを受け取るときに、問題が発生しました。
XQSERR_SRC_CONFIG: XQS構成の処理中に問題が発生しました。
XQSERR_INTERNAL: XQSで予期しない内部エラーが発生しました。
これらの定数の追加情報は、「XQSErrorIリファレンス」を参照してください。
この項では、単純なエラー処理の例および対応する構成を示します。
（「XQS関数のエラー処理の構成」で説明したように）XQSアプリケーションでXQSErrorIオブジェクトを使用するには、データソースがエラー・モードemptySequenceまたはerrorMessage用に構成されている必要があります。次の例では、errorMessageモードが使用されています。
<xqsview-source ... onError="errorMessage"> <function-name prefix="xqs">BasicFileWS</function-name> <output-element namespace="myNS">myElement</output-element> ... </xqsview-source>
<error-message>要素が使用されていないため、戻される単一項目のXML結果順序には、事前定義済メッセージが含まれず、かわりにデータソースから取得されるメッセージがそのまま転送されます。XQSビュー関数で実際にエラーが発生すると、XQSによって<xqserror> XMLノードが構成され、そのノードが関数の結果として戻されます。エラー・メッセージは、<xqserror>ノードのテキスト値になります。XQSビュー構成によって<output-element>構成内のユーザー定義の要素が指定されるため、XMLのノード表現が選択されます。
次の例は、ビューを実行してから次のエラー処理を行うコードの一部分です。
XQSFacadeIインタフェースのgetErrors()メソッドをコールして、XQSErrorIオブジェクトのjava.util.ListIteratorインスタンスを取得します。
ListIteratorクラスのhasNext()メソッドを使用して、反復するエラー・オブジェクトの数を指定します。
... XQSFacadeI bean = XQSFactory.getXQSFacade(); String xqueryView = "BasicFileWS"; QueryParameterI param = XQSFactory.getQueryParameter("custName"); param.setString("John Ford"); QueryParameterI[] params = new QueryParameterI[1]; params[0] = param; bean.executeView(xqueryView, null, params); while(bean.getNextItem() !=null) { } ListIterator errors = bean.getErrors(); while(errors.hasNext()) { XQSErrorI error = (XQSErrorI)errors.next(); System.out.println("The function which gives error is: " + error.getFunctionQName()); System.out.println("The error type is:" + error.getErrorType()) + ", which means " +XQSErrorI.typeNames(error.getErrorType())); System.out.println("The error message is:" + error.getErrorMessage()); System.out.println("The error code is:" + error.getErrorCode()); } ...
XQueryおよびXQSは、Oracle Application Server上で実行されているOracle BPEL Process Managerから使用できます。
Oracle BPELには、Oracle BPEL Process ManagerによるXQueryベースのXML問合せを可能にするXPath機能があります。問合せはXQSビューに保存できます。XQSビューはフォルダ（2階層まで）および名前空間に編成できます。XQSビューを使用すると、あるXQSビューを他のXQSビューから呼び出すことで複雑な問合せを作成する機能が改善されるだけでなく、アプリケーションのモジュール性も向上します。
この項には、次の項目が含まれます。
Oracle BPELには、次に示すように、orabpel¥domains¥default¥config¥xpath-functions.xmlファイルに登録されているJavaクラス（com.collaxa.cube.xml.xpath.functions.xml.GetElementFromXQueryFunction）が用意されています。
<function id="processXQuery"> <classname> com.collaxa.cube.xml.xpath.functions.xml.GetElementFromXQueryFunction </classname> <comment> <![CDATA[This function returns result of XQuery execution. The signature of this function is <i>ora:processXQuery('view_name','context_node'?)</i>.]]> </comment> <property id="namespace-uri"> <value>http://schemas.oracle.com/xpath/extension</value> <comment>Namespace URI for this function</comment> </property> <property id="namespace-prefix"> <value>ora</value> <comment>Namespace prefix for this function</comment> </property> </function>
この例では、GetElementFromXQueryFunction.classファイルをorabpel¥system¥classes¥com¥collaxa¥cube¥xml¥xpath¥functions¥xmlディレクトリに配置したことを前提としています。ora:processXQuery関数は、BPELプロセス定義のその他のXPath関数と同じように使用されています。次に例を示します。
<assign name="runXQuery"> <copy> <from expression="'Associated Press'"/> <to variable="publisher"/> </copy> <copy> <from> <category xmlns="http://samples.otn.com">Computing</category> </from> <to variable="category"/> </copy> <copy> <from expression="ora:processXQuery ('books.xq',bpws:getVariableData('input','payload'))"/> <to variable="output" part="payload"/> </copy> </assign>
前の例（ora:processXQuery）で示されたOracle BPEL XQuery関数には2つのパラメータがあります。
view_nameパラメータは必須で、文字列である必要があります。このパラメータでは、実行する保存済のXQueryファイル（XQSビューとも呼ばれる）の名前を指定します。オプションで、ファイル名にはファイル拡張子.xqを指定することもできます。1つ目の引数が.xqで終わらない場合は、ファイルを検索する前にXQSによってファイル拡張子が追加されます。
context_nodeパラメータはオプションです。指定する場合、値はXMLノードである必要があります。このXMLノードは、実行される問合せのコンテキスト項目になります。詳細は、「XQueryを使用したコンテキスト項目へのアクセス」を参照してください。
外部変数にバインドせずに、XMLドキュメントをXQuery式に渡すことができます。これは、ドキュメントのコンテキスト項目へのバインドと呼ばれます。問合せ式内では、コンテキスト項目には特別な構文（.）を使用してアクセスします。
たとえば、コンテキスト項目がルート要素<books>および一連の<book>子要素を持つドキュメントにバインドされている場合は、次の式が有効です。
for $i in ./book/title return $i
XMLドキュメントをXQueryコンテキスト項目としてバインドするには、BPEL XQuery関数のcontext_nodeパラメータを使用します。
XQSを使用すると、XQSビューと呼ばれるファイルに保存された問合せという形で、標準のXQuery言語を拡張できます。XQSには名前および関連付けられたXQuery式があります。
ビューの実装は、そのビューと関連付けられたXQuery式です。次に示す問合せ式を、ファイルmyView.xqと関連付けることができます。
for $i in fn:doc("/dir/file.xml") return $i/line-item[@id=10]
トップレベルのビューは、BPELプロセスから直接起動されます。次の例では、myTopViewという名前のビューが、processXQuery XPath関数を使用してBPELプロセスから起動されています。
<copy> <from expression="ora:processXQuery('myTopView.xq'))"/> <to variable="output" part="payload"/> </copy>
トップレベルのビューには次の規則が適用されます。
例として、myTopViewの内容を次に示します。
for $i in fn:doc("/dir/file.xml") return $i/line-item[@id=$bpelVar]
外部変数$bpelVarは宣言されておらず、BPELプロセス変数とみなされています。
ネストされたビューは、別のXQSビューから呼び出されたXQSビューです。XQuery言語の構文に合せるため、呼出し元のビューはネストされたビューを外部関数として参照します。ネストされたビューでは、ビューの名前は外部関数の名前でもあり、そのビューを使用する別の問合せ式で宣言されます。次の例では、myViewがネストされたビューの名前です。
declare namespace bpel="urn:oracle.bpel.xq"; declare function bpel:myView($arg as xs:integer) as node()* external;
外部関数myView()が問合せ式で呼び出されるたびに、XQSが関数の整数パラメータをmyView()内の外部関数にバインドし、前の問合せを実行します。結果順序は、外部関数呼出しの結果です。
XQSビューは、基本的にストアド・クエリーであり、あるXQueryを別のXQuery内に埋め込むことができます。同時に、ネストされた問合せを他から分離し、モジュール化して個別に変更できるようにします。たとえば、外側（埋込み先）の問合せは次のようになります。
declare namespace bpel="urn:oracle.bpel.xq"; declare function bpel:myView($arg as xs:integer) as node()* external; for $i in bpel:myView(2301) return $i/shipping-status
外部のXQSビュー関数は、関数と同じ名前のテキスト・ファイルを介して問合せと関連付けられます。ファイル拡張子は.xqです。たとえば、myView.xqという名前のファイルには次のテキストが含まれます。
declare variable $x as xs:integer external; for $i in fn:doc("/dir/file.xml") return $i/line-item[@id=$x]
これまでの例からわかるように、ネストされたすべてのビューはいずれかの名前空間に属します。この名前空間は、デフォルトのOracle BPELの名前空間urn:oracle.bpel.xq、またはユーザー定義の名前空間です。ネストされたビューをユーザー定義の名前空間にグループ化する方法は、「XQSビュー用のBPEL名前空間およびフォルダの使用」で説明します。
XQueryの外部変数を使用すると、XQuery式を別のXQuery式に埋め込む環境からの入力値を渡すことができます。この概念は、SQLのバインド変数に似ています。次に、3つの外部変数（$x、$yおよび$z）を宣言する単純な問合せの例を示します。問合せでは、変数の値が順番に戻されます。
declare variable $x as xs:string external; declare variable $y as xs:integer external; declare variable $z external; ($x, $y, $z)
外部変数のタイプの宣言は、変数$zで示されているようにオプションです。問合せに対する追加の静的および動的タイプ・チェックが実行され、アプリケーションがより堅牢になるため、あらかじめタイプがわかる場合にはタイプを指定して外部変数を宣言することをお薦めします。
また、XQueryでは外部変数を暗黙的に宣言できます。前もって宣言せずにXQuery式で変数表記（$）が使用された場合、変数は暗黙的に宣言された外部変数とみなされます。次のXQuery式は、3つの外部変数が暗黙的に宣言されていること以外は前の例と同じです。
($x, $y, $z)
XQuery評価では、すべての外部変数が実際の値にバインドされている必要があります。暗黙的に宣言された外部変数と明示的に宣言された外部変数では処理が異なります。
外部変数が暗黙的に宣言されている場合、その名前は現在対象範囲内にあるBPELプロセス変数の名前と一致する必要があります。BPEL Process ManagerおよびXQSにより、プロセス変数の値が同じ名前の外部変数にバインドされます。
|
注意 暗黙的に宣言された外部変数を使用できるのは、BPEL XQuery関数から直接呼び出されたビューでのみで、ネストされたXQSビューでは使用できません。 XQSビューでBPELプロセス変数を使用するその他の例は、「XQSビューにおけるBPELプロセス変数の使用」を参照してください。 |
XQueryの外部変数が問合せ内で明示的に宣言されている場合、そのビューで外部変数が宣言されている順序に従って、変数の値はXQSビュー関数に対する引数から取得されます。別のビューからXQS関数として起動されたXQSビューは、ネストされたビューと呼ばれます。
まとめると、XQSビューがBPEL XQuery関数から直接起動された場合、そのビューで使用するのは暗黙的に宣言された外部変数のみの必要があります。また、その値は、XQuery関数が呼び出された際に対象範囲であった同じ名前のBPELプロセス変数から取得されます。次に例を示します。
topLevelView.xq XQSビュー・ファイル内の問合せ
for $b in $bpelVar1/a/b return $b[@id = $bpelVar2]
この問合せは、変数$bpelVar1および$bpelVar2が対象範囲であるBPELプロセスで起動されます。
<copy> <from expression="ora:processXQuery('topLevel.xq')"/> <to variable="output" part="payload"/> </copy>
XQSの外部変数を使用してXQSビューが別のXQSビューから起動された場合、そのビューで使用されるのは明示的に宣言された外部変数のみである必要があります。XQSビュー関数の引数の値は引数が渡された順序で取得され、そのビューで変数が宣言された順序で外部変数に割り当てられます。nestedView.xq XQSビュー・ファイルの例を示します。
declare variable $x as element() external; declare variable $y as xs:integer external; for $b in $x/a/b return $b[@id = $y]
nestedView問合せは、topViewという別のビューから起動されます。topView.xqの内容は次のとおりです。
declare namespace ns1="folder1"; declare function ns1:nestedView($arg1 as element(), $arg2 as xs:integer) external; let $el := <x> <a> <b id="1">b-content</b> </a> </x> return ns1:nestedView($el, 1)
nestedViewを実行する前に、XQSでは外部変数$xを要素<x>に、外部変数$yを整数1にバインドします。
XQuery XPath関数から直接呼び出されたXQSビューでは、そのビュー内で追加の宣言を行わずに、BPELプロセスで宣言された変数を使用できます。
BPELプロセスに変数$bpPurchaseAmtおよび$stateが含まれ、これらの変数にはBPELプロセス内で値が割り当てられているとします。
また、XQSビュー・ファイル（purchaseAmtAddTax.xq）はBPELプロセスとともにパッケージ化されており、次のような内容だとします。
declare namespace bpl = "urn:oracle.bpel.xq"; declare function bpl:stateTax($st as xs:string) as xs:decimal external; $bpPurchaseAmt *(1+ bpl:stateTax($state))
この例では、別のXQSビュー・ファイル（stateTax.xq）もBPELプロセスとともにパッケージ化されていると仮定されています。
例では、2つの外部変数（$bpPurchaseAmtおよび$state）が使用されています。これらの外部変数は問合せ内では宣言されていません。検証を成功させるためには、BPELプロセス内のXQuery XPath関数からXQSビューを呼び出す必要があります。また、プロセスには、対象範囲内の変数$bpPurchaseAmtおよび$stateが含まれていて、その値が処理する問合せに対して適切である必要があります。
BPEL環境内でのXQSビュー用の名前空間およびフォルダの使用には、2つのオプションがあります。
XQueryファイルのデフォルトの場所は、BPELプロセス・スーツケースのルート・フォルダです。XQSは、名前空間とフォルダを関連付けます。デフォルトのXQueryフォルダは、デフォルトのOracle BPEL名前空間urn:oracle.bpel.xqと関連付けられます。この名前空間を指定するには、dflt、bpel、myrootなど、任意の接頭辞を使用できます。
BPELプロセスから直接起動されたビューであるすべてのトップレベルのXQSビューは、デフォルトのフォルダに配置する必要があります。つまり、トップレベルのすべてのビューはデフォルトの名前空間urn:oracle.bpel.xqに属します。そのため、XQuery processXQuery関数にビューの名前が渡される際には、デフォルトの名前空間は渡されません。
デフォルトのフォルダに配置されたビューも、デフォルトの名前空間の接頭辞を使用してネストされたビューとして起動されます。次のフォルダ構造があるとします。
<process suitcase root> /view1.xq /view2.xq
view2.xqを起動できるview1.xqの内容は次のとおりです。
declare namespace dflt = "urn:oracle.bpel.xq"; declare function dflt:view2($st as xs:string) as xs:decimal; for $i in dflt:view2("Oracle") return $i
Oracle BPEL環境のXQSには、問合せをデフォルト・フォルダのサブフォルダに編成するオプションもあります。サブフォルダは1階層のみです。たとえば、次のようなフォルダ構造では、XQSはビューview1.xq、view2.xq、view3.xq、view4.xqおよびview5.xqを検出できます。一方、invisible.xqはスーツケースのルートから2階層下のフォルダにあるため、XQSで検出できません。
<process suitcase root> /view1.xq /view2.xq /subfolder1 /view3.xq /view4.xq /subfolder12 /invisible.xq /subfolder2 /view5.xq
サブフォルダに配置されたビューは、ネストされたビューとしてのみ使用されます。ネストされたすべてのビューは、呼出し元の問合せで外部関数として宣言する必要があるため、名前空間に属している必要があります。サブフォルダに配置されたビューの名前空間が、サブフォルダの名前になります。ただし、その名前空間に任意の接頭辞を1つ以上付けることができます。
フォルダ構造の例では、subfolder1/およびsubfolder2/のビューを起動する前に、次の宣言が使用されています。
declare namespace dflt="urn:oracle.bpel.xq"; declare namespace sub1="subfolder1"; declare namespace sub2="subfolder2"; declare function dflt:view1() as external; declare function sub1:view4() as external; declare function sub2:view5() as external;
フォルダ構造の前の例で説明すると、view1.xqおよびview3.xqは次のようにしてview5.xqから起動されます。
declare namespace dflt="urn:oracle.bpel.xq"; declare namespace sub1="subfolder1"; declare function dflt:view1() as external; declare function sub1:view3() as external; dflt:view1()//price - sub1:view3()//discount
XQSでは、ローカル・ファイル・システムのファイルだけでなく、（http:、ftp:またはfile:プロトコルを使用している）有効なWeb URLを使用してアクセス可能なビューを起動することもできます。ビューの名前がURLの場合、アクセスするファイルの正確な名前を反映している必要があります（XQSでは、.xqファイル拡張子は追加されません）。また、ビューのテキスト・ファイルが、起動時にそのURLからアクセスできる必要があります。次に例を示します。
<copy> <from expression="ora:processXQuery ('http://myhost/bpeldemos/views/myView.xq')"/> <to variable="output" part="payload"/> </copy>
この項では、XQS publicクラスおよびユーザー・インタフェースに関するリファレンス・ドキュメントを提供します。
この項では、oracle.xqs.client.XQSFactoryクラスのメソッドを示します。ファクトリ・クラスは、メインのXQSクライアント・インタフェースXQSFacadeIおよびQueryParameterIのインスタンスの作成に使用されます。これらのメソッドは、ファクトリによって戻される特定のインタフェースが記載されている後続の項で詳細に説明されています。oracle.xqs.client.XQSFactoryクラスには次のメソッドがあります。
XQSFacadeI getXQSFacade()
QueryParameterI getQueryParameter()
QueryParameterI getQueryParameter(String namespace, String localName)
QueryParameterI getQueryParameter(String localName)
この項では、oracle.xqs.client.QueryParameterIインタフェースおよびそのメソッドの取得に使用されるファクトリ・メソッドについて説明します。QueryParameterI配列は、XQSの汎用Java APIまたはEJB APIの使用時に、問合せの外部変数をバインドするために使用します。
「例3: XQSFacadeI APIを使用したXQSビュー」には、入力パラメータのQueryParameterIの使用例が含まれています。
oracle.xqs.client.XQSFactoryクラスには、QueryParameterIインタフェースのインスタンスを作成する次のメソッドがあります。
getQueryParameter()
getQueryParameter(String namespace, String localName)
getQueryParameter(String localName)
QueryParameterIインスタンスをXQSFactoryファクトリから取得する際には、バインドする外部XQuery変数の名前を指定します。この名前は、XQueryプロローグ内の対応する外部変数宣言の名前と一致する必要があります。また、名前を付けずにQueryParameterIインスタンスを作成し、QueryParameterIインタフェースのsetName()メソッドを使用して後からパラメータ名を設定できます。この名前も、XQueryプロローグの外部変数の名前と一致する必要があります。XQuery変数ではXML名が使用されるため、QueryParameterIコンストラクタでは、名前空間用とローカル名用の2つの文字列値を使用できます。名前空間を指定しない場合は、修飾名内の名前空間に、nullが割り当てられます。
QueryParameterIインタフェースでは、外部XQuery変数の値を設定するための、次のメソッドが提供されます。これらのメソッドは、XQSでサポートされているXML型、およびそれに対応するJava型を反映しています。「サポートされている問合せパラメータのタイプ」も参照してください。パラメータ名を設定および取得するメソッドや、パラメータがNULLかどうかを確認するメソッドもあります。
javax.xml.namespace.QName getName()このメソッドは、パラメータ名の特定に使用します。
void setName(String namespace, String localPart)このメソッドは、名前空間およびQNameのローカル部分を指定してパラメータ名を設定するために使用します。
boolean isNull()このメソッドは、パラメータ値がNullに設定されているかどうかを特定するために使用します。パラメータをNullに設定するには、この項にリストされているset*Null()メソッドのいずれかを呼び出します。初期化されていないパラメータは、Nullに設定されているとはみなされません。
void setBase64Binary(String value)このメソッドは、Java文字列（たとえば、vYrfOJ39673//-BDiIIGHSPM=+）で表された、XML base64Binary型に対応するBase64Binary値のバインドに使用します。
void setBase64BinaryNull()このメソッドは、Base64Binary外部変数をNullにバインドするために使用します。
void setBoolean(boolean value)このメソッドは、XML boolean型に対応するboolean値のバインドに使用します。
void setBooleanNull()このメソッドは、boolean外部変数をNullにバインドするために使用します。
void setDateTime(java.util.GregorianCalendar value boolean isTimeZoneSet)このメソッドは、XML dateTime型に対応する、ある特定の時間を表すGregorianCalendar値のバインドに使用します。カレンダ・オブジェクトのTimeZoneプロパティが設定されている場合は、isTimeZoneをtrueに設定します。（GregorianCalendarオブジェクトの使用に関する情報は、http://java.sun.com/j2se/1.4.2/docs/api/を参照してください。）
void setDateTimeNull()このメソッドは、dateTime外部変数をNullにバインドするために使用します。
void setDateTime(String strValue)このメソッドは、XML dateTime型に対応する、ある特定の時間を表すString値のバインドに使用します。
void setDecimal(java.math.BigDecimal value)このメソッドは、XML decimal型に対応するBigDecimal値のバインドに使用します。
void setDecimalNull()このメソッドは、decimal外部変数をNullにバインドするために使用します。
void setDouble(double value)このメソッドは、XML double型に対応するdouble値のバインドに使用します。
void setDoubleNull()このメソッドは、double外部変数をNullにバインドするために使用します。
void setDuration(String value)このメソッドは、XML duration型に対応する、期間を表すString値のバインドに使用します。期間の字句（文字列）表現の情報は、http://www.w3.org/TR/xmlschema-2/#durationを参照してください。
void setDurationNull()このメソッドは、duration外部変数をNullにバインドするために使用します。
void setDayTimeDuration(double seconds)このメソッドは、XML dayTimeDuration型に対応する、期間の値（秒単位）のdayTime部分を表すdouble値のバインドに使用します。dayTimeDurationの表現の情報は、http://www.w3.org/TR/xmlschema-2/#dayTimeDurationを参照してください。
void setDayTimeDurationNull()このメソッドは、DayTimeDuration外部変数をNullにバインドするために使用します。
void setYearMonthDuration(int months)このメソッドは、XML yearMonthDuration型に対応する、期間の値（月単位）のyearMonth部分を表すint値のバインドに使用します。yearMonthDurationの表現の情報は、http://www.w3.org/TR/xmlschema-2/#yearMonthDurationを参照してください。
void setYearMonthDurationNull()このメソッドは、yearMonthDuration外部変数をNullにバインドするために使用します。
void setFloat(float value)このメソッドは、XML float型に対応する浮動小数点値のバインドに使用します。
void setFloatNull()このメソッドは、float外部変数をNullにバインドするために使用します。
void setHexBinary(String value)このメソッドは、Java文字列（たとえば、0FB7）で表された、XML hexBinary型に対応する16進バイナリ値のバインドに使用します。
void setHexBinaryNull()このメソッドは、hexBinary外部変数をNullにバインドするために使用します。
void setInt(int value)このメソッドは、XML int型に対応するinteger値のバインドに使用します。
void setIntNull()このメソッドは、int外部変数をNullにバインドするために使用します。
void setInteger(int value)
void setInteger(long value)
void setInteger(java.math.BigInteger value)いずれかのsetInteger()メソッドを使用して、XML integer型に対応する整数値をバインドします。値の表現または大きさに基づいて、適切なシグネチャを選択します。
void setIntegerNull()このメソッドは、integer外部変数をNullにバインドするために使用します。
void setLong(long value)このメソッドは、XML long型に対応するlong整数値のバインドに使用します。
void setLongNull()このメソッドは、long external変数をNullにバインドするために使用します。
void setString(String value)このメソッドは、XML string型に対応するJava string値のバインドに使用します。
void setStringNull()このメソッドは、string外部変数をNullにバインドするために使用します。
void setAnyURI(java.net.URI value)このメソッドは、XML anyURI型に対応するURI値のバインドに使用します。
void setAnyURINull()このメソッドは、anyURI外部変数をNullにバインドするために使用します。
void setNode(org.w3c.dom.Node value)このメソッドは、XML anyType型またはユーザー定義のXML型に対応するXMLノードのバインドに使用します。
void setNodeNull()このメソッドは、外部変数anyTypeまたはユーザー定義のXML型をNullにバインドするために使用します。
この項では、oracle.xqs.client.XQSFacadeIインタフェースおよびそのメソッドの取得に使用されるファクトリ・メソッドについて説明します。このインタフェースは、XQSが提供する汎用目的のJavaクライアントAPIです。使用方法および例は、「Javaインタフェース・クライアントAPIの使用方法」を参照してください。
oracle.xqs.client.XQSFactoryクラスには、XQSFacadeIインタフェースのインスタンスを作成する次のメソッドがあります。
XQSFacadeIインタフェースでは、次のメソッドが提供されます。
void execute(String xquery, QueryParameterI[] params)このメソッドを使用して、非定型問合せを実行します。問合せを含む文字列、およびバインド・パラメータのQueryParameterI配列を渡します。（「XQS QueryParameterIリファレンス」を参照してください。）渡すパラメータがない場合、配列はnullになります。
void executeView(String viewName, String namespace, QueryParameterI[] params)このメソッドを使用して、XQSビューを直接実行します。ローカル名および名前空間を（文字列として）指定することでビュー名を渡し、バインド・パラメータのQueryParameterI配列（またはnull）を渡します。ビュー名および名前空間は、ともに修飾名の定義に使用されるため、<xqsview-source>の<function-name>サブ要素、およびそのnamespace属性またはprefix属性に基づいて、構成内の対応する関数名および名前空間と一致する必要があります。
oracle.xml.xqxp.datamodel.XMLItem getNextItem()execute()またはexecuteView()を使用した後、getNextItem()を使用して結果順序内の次の項目をOracle XMLItemインスタンスとして取得します。最初のgetNextItem()コールでは、順序内の最初の項目が戻されます。最後の項目を取得した後にこのメソッドをコールすると、nullが戻されます。
java.util.ListIterator getErrors()問合せで使用するいずれかのXQS関数を、エラーの発生後も続行するように構成した場合は（「XQS関数のエラー処理の構成」を参照）、getErrors()を使用して、XQS関数の実行時に発生した可能性があるエラーの情報を取得できます。このメソッドでは、XQSErrorIオブジェクトのコレクションに対するイテレータが戻されます。このイテレータから、各エラーの詳細を取得できます。（「XQSErrorIリファレンス」を参照してください。）エラーが発生しなかった場合は、イテレータによって空のコレクションがポイントされます。
void close()このメソッドを使用して、問合せに関連付けられているすべてのリソースを解放します。close()は、問合せ結果をすべて取得した後でコールするのが適正です。
この項では、リモートEJB用のXQSClientRemoteインタフェースとXQSClientHomeインタフェース、およびローカルEJB用のXQSClientLocalインタフェースとXQSClientLocalHomeインタフェースを介してXQSでサポートされる、EJBクライアント・メソッドについて説明します。ステートフル・セッションBeanまたはステートレス・セッションBean用に、これらのインタフェースには複数のバージョンがあります。
使用方法および例は、「EJBクライアントAPIの使用方法」を参照してください。
ステートフル・セッションBeanでは、次に示すOracle固有のメソッドを、パッケージoracle.xqs.client.ejb.statefulに含まれるEJBインタフェースから使用できます。これらのメソッドの機能は、「XQSFacadeIリファレンス」に含まれる同じ名前のメソッドと同じです。
void execute(String xquery, QueryParameterI[] params)
throws EJBException
void executeView(String viewName, String namespace, QueryParameterI[] params)
throws EJBException
oracle.xml.xqxp.datamodel.XMLItem getNextItem()
throws EJBException
java.util.ListIterator getErrors()
void close()
ステートレス・セッションBeanでは、パッケージoracle.xds.client.ejb.statelessに含まれるEJBインタフェースを介して、次に示すOracle固有のメソッドを使用できます。
java.util.Vector execute(String xquery, QueryParameterI[] params)
throws EJBExceptionこのメソッドを使用して、非定型問合せを実行します。問合せを含む文字列、およびバインド・パラメータのQueryParameterI配列を渡します。（「XQS QueryParameterIリファレンス」を参照してください。）渡すパラメータがない場合、配列はnullになります。結果は完全にマテリアライズされ、Vectorインスタンス内に戻されます。
java.util.Vector executeView(String viewName, String namespace, QueryParameterI[] params)
throws EJBExceptionこのメソッドを使用して、XQSビューを実行します。ローカル名および名前空間を（文字列として）指定することでビュー名を渡し、バインド・パラメータのQueryParameterI配列（またはnull）を渡します。ビュー名および名前空間は、ともに修飾名の定義に使用されるため、<xqsview-source>の<function-name>サブ要素、およびそのnamespace属性またはprefix属性に基づいて、構成内の対応する関数名および名前空間と一致する必要があります。結果は完全にマテリアライズされ、Vectorインスタンス内に戻されます。
java.util.ListIterator getErrors()このメソッドには、「XQSFacadeIリファレンス」に含まれる同じ名前のメソッドと同じ機能があります。
XQSでは、XQueryへのステートフル・アクセスまたはステートレス・アクセス用のカスタムJSPタグが提供されます。
使用方法および例は、「JSPタグ・ライブラリの使用方法」を参照してください。
JSPタグ・ライブラリの使用に関する一般情報は、『Oracle Containers for J2EE JavaServer Pages開発者ガイド』を参照してください。
これらのタグは、XQueryへのステートフル・アクセスを使用する場合に使用します。
このタグを使用して、問合せの準備および実行を行います。構文は次のとおりです。（paramサブタグは、すべてのバインド・パラメータに使用されます。後続の説明を参照してください。）
<xq:executeCursor [ xqueryString = "query" ] [ xqsViewName = "viewname" ] [ namespace = "namespace" ] cursorId = "cursorname" [ maxItems = "maxnumber" ] [ toWriter = "true" | "false" ] toXMLDoc = "docname" resultItems = "arrayname" errors = "errorvarname" > <xq:param ... /> <xq:param ... /> ... </xq:executeCursor>
executeCursorタグの属性は、次のように使用します。
xqueryString: 非定型問合せを使用する場合は、この属性を使用して、問合せの完全なXQuery構文を指定します。通常は、文字列変数で問合せを定義し、その変数の名前をJSP式で指定するのが最も簡単です。
String myquerystring = "..."; ... <xq:executeCursor ... xqueryString = "<%=myquerystring%>" ... > ... </xq:executeCursor>
xqsViewName: XQSビューを使用する場合は、この属性を使用してビューを指定します。厳密には、これは、構成内の対応するXQS関数の名前です。
namespace: xqsViewNameを使用してビューを指定する場合は、namespaceも併用して、XQS構成に基づいてビューのXQS関数の名前空間を指定する必要があります。
cursorId（必須）: このタグを使用して、カーソルの変数の名前を指定し、後で使用できるようにします。（この変数は、JSPコンテナによって宣言されます。）指定した変数名は、nextタグを使用してカーソルから結果を取得するとき、およびcloseタグを使用してカーソルをクローズするときに参照します。次に例を示します。
<xq:executeCursor ... cursorId="mycursor" ... > ... </xq:executeCursor> ... <xq:next cursorId="mycursor" /> ... <xq:close cursorId="mycursor" />
maxItems: maxItems="10000"のように、問合せから受け取る項目の最大数を指定する場合に使用します。超過分の項目は廃棄され、maxItemの項目を受け取った後は、nextタグによって値が戻されなくなります。
toWriter: trueに設定すると、JSP出力ストリームに問合せ結果が出力されます。書込みは、nextタグが実行されるたびに行われます。
toXMLDoc（必須）: XML DOMドキュメントに問合せ結果を出力するために、関連するnextタグで使用される変数の名前を指定します。ドキュメントは、executeCursorタグの後に使用できます。タイプorg.w3c.dom.Documentの変数は、JSPコンテナによって宣言されます。次に例を示します。
<xq:executeCursor cursorId="mycursor" toXMLDoc="mydoc" ... > ... </xq:executeCursor> <xq:next cursorId="mycursor" /> Element root = mydoc.getDocumentElement(); ...
executeCursorタグの使用後は、nextタグを実行するたびに、ドキュメントmydoc内で収集された結果ノードのバッチを受け取ります。
resultItems（必須）: 配列リストに問合せ結果を出力するために、関連するnextタグで使用される変数の名前を指定します。タイプjava.util.ArrayListの変数は、JSPコンテナによって宣言されます。ArrayListインスタンスは、executeCursorタグの後に使用できます。次に例を示します。
<xq:executeCursor ... resultItems="myobjects" ... > ... </xq:executeCursor> Node node = (Node)myobjects.get(0); ...
executeCursorタグの使用後は、nextタグを実行するたびに、myobjects変数から結果項目にアクセスできます。
errors（必須）: XQS問合せの実行により発生したエラーの取得に使用する変数の名前を指定します。タイプjava.util.ListIteratorの変数は、XQSErrorIオブジェクト（エラーごとに1つのオブジェクト）のコレクションに対するイテレータのJSPコンテナによって宣言されます。イテレータは、executeCursorタグの後に使用できます。次に例を示します。
<xq:executeCursor cursorId="mycursor" errors="myerroriter" ... > ... </xq:executeCursor> <xq:next cursorId="mycursor" /> XQSErrorI error = (XQSErrorI)myerroriterator.next(); ...
XQSErrorIオブジェクトの使用方法は、「XQSErrorIリファレンス」を参照してください。
executeCursorおよびexecuteのサブタグです。このタグを使用して、問合せの外部バインド・パラメータ（1つのparamタグ・パラメータ）を指定します。構文は次のとおりです。
<xq:param localName = "localvarname" [ namespace = "namespace" ] value = "bindvalue" type = "bindparamtype" />
paramタグの属性は、次のように使用します。
localName（必須）: 外部変数名のローカル部分の指定に使用します。
namespace: 外部変数名の名前空間部分の指定に使用します。名前空間を伴わないローカル変数名も使用できるため、この属性はオプションです。
value（必須）: バインドされる値に使用します。推定上、この値はJSP実行時式を使用したランタイム値になります。
<xq:param ... value = "<%=jspExpression%>"... />
type（必須）: XQS QueryParameterIインタフェースによって対応するJava型がサポートされているXML型を示す、バインド・パラメータのデータ型の指定に使用します。サポートされている設定および使用に適した型は、表8-3を参照してください。（「サポートされている問合せパラメータのタイプ」も参照してください。）このタグを使用して、項目またはバッチごとに、executeCursorタグから結果を処理します。その際には、そのタグで指定したカーソルID名が参照されます。nextタグの構文は次のとおりです。
<xq:next cursorId = "cursorname" [ batchSize= "numitems" ] [ itemsFetched = "intvarname" ] />
nextタグの属性は、次のように使用します。
cursorId（必須）: この属性を使用して、executeCursorタグでの指定に従って、問合せのカーソル名を参照します。カーソルは、まだオープンである（同じカーソル名を指定するcloseタグがまだ存在していない）ことが必要です。
batchSize: XQSでの問合せにバッチ・モードを使用する場合は、この属性を使用します。nextタグを実行するたびにカーソルからフェッチする項目数を、整数値で指定します。デフォルトは1（バッチ不使用）です。
itemsFetched: 現在のnextタグの実行でカーソルからフェッチされた項目数を示す値のjava.lang.Integer変数の名前を指定します。この変数は、JSPコンテナによって宣言されます。
次に例を示します。
... <xq:executeCursor cursorId="mycursor" resultItems="myresults" toXMLDoc="mydoc" errors="myerrors" ... > <xq:param ... /> ... </xq:executeCursor> <% int items; do { // Populate output vehicles (myresults array and mydoc document) %> <xq:next cursorId="mycursor" itemsFetched="fetched" /> <% items = fetched.intValue(); } while(items>0) // ... Here is where you would retrieve results from the output vehicles ... %> ...
（executeCursorタグを使用する）ステートフルJSPの場合は、closeタグを使用して、問合せに関連付けられているすべてのリソースを解放します。構文は次のとおりです。
<xq:close cursorId = "cursorname" />
closeタグの属性は、次のように使用します。
XQueryへのステートレス・アクセスを使用する場合は、executeタグを使用します。
このタグを使用して、問合せの準備および実行を行います。構文は次のとおりです。
<xq:execute [ xqueryString = "query" ] [ xqsViewName = "viewname" ] [ namespace = "namespace" ] [ maxItems = "maxnumber" ] [ toWriter = "true" | "false" ] toXMLDoc = "docname" resultItems = "arrayname" errors = "errorvarname" > <xq:param ... /> <xq:param ... /> ... </xq:execute>
cursorIdを除き、このタグでは、（ステートフル・アクセス用の）executeCursorタグと同じ属性が使用されます。executeCursorと同様に、バインド・パラメータに対してXQS paramサブタグも使用されます。「XQS executeCursorタグ」および「XQS paramタグ」を参照してください。
この項では、インタフェースoracle.xqs.client.XQSErrorIのリファレンス・ドキュメントを提供します。
問合せで使用するいずれかのXQS関数を、エラーの発生後も続行するように構成した場合は（「XQS関数のエラー処理の構成」を参照）、問合せのXQS関数の実行時に発生した可能性があるエラーの情報を取得できます。エラーは、XQSErrorIオブジェクトのイテレータ内に戻されます。
XQSErrorIインタフェースでは、エラーが発生したXQS関数、エラーのタイプ（XQS固有の指定）、エラー・メッセージおよびエラー・コード（適用される場合）などの主な情報を様々な書式で戻すメソッドが多数提供されます。使用方法および例は、「XQSエラー・オブジェクトからの情報の取得」を参照してください。
String getFunctionQName()このメソッドは、エラーが発生したXQS関数の完全修飾名を取得する場合に、次のように使用します。
{namespace_URI}/local_name
int getErrorType()このメソッドは、次のようなXQSエラー・タイプの指定を示す整定数を取得するために使用します。
XQSERR_MISSING_SRC: HTTP 404エラーが戻された、ドキュメント・ソースのファイルが見つからない、ソースが停止している、目的の表がデータベース・ソースに存在しないなどの理由で、データソースが見つかりません。
XQSERR_SRC_ACCESS: データソースは見つかりましたがアクセス・エラーが戻されました。これには、OracleデータベースのORA-xxxxxエラー、Webサイトのログイン・エラー、ドキュメント・ソース読取り時のパーサー・エラーなどが含まれます。
XQSERR_SRC_ERROR: データソースは見つかりましたが、アクセス・エラー以外のなんらかのエラーが戻されました。これには、Webサービスのフォルト・メッセージ、データベース・ソースのSQLエラーなどが含まれます。
XQSERR_PARAM: バインド・パラメータをデータソースに渡すとき、もしくはデータソースから出力パラメータを受け取るときに、XQSで問題が発生しました。これが戻されるのは、たとえば、WSDLドキュメントに従って要求される対応データ型に入力文字列を変換できなかった場合や、使用する特定の変換機能でXML以外のファイルをXML文書に変換できなかった場合などです。
XQSERR_SRC_CONFIG: XQS関数の構成の処理中に、XQSで問題が発生しました。
String getErrorMessage()このメソッドは、必要に応じて、データソースまたはXQSから、エラー・メッセージを取得する場合に使用します。このメソッドでは、nullが戻されることはありません。データソースによってエラーが生成され、メッセージが戻されなかった場合は、関数でエラーが生成されたことを示す汎用メッセージが、XQSによって戻されます。
String getErrorCode()このメソッドは、データソースによって生成されたエラーについて、XQSエラー・コードの文字列を戻すために使用します。
String toString()このメソッドは、関数名、エラー・タイプ、エラー・コードおよびエラー・メッセージを組み合せて単一の文字列にするために使用します。
String toXMLString()このメソッドは、関数名、エラー・タイプ、エラー・コードおよびエラー・メッセージを組み合せてXMLエラー要素の1つの文字列表現にするために使用します。
public static String[] typenamesこの静的配列には、次に示すXQSエラー・タイプの文字列表現が含まれます。
XQSERR_MISSING_SRC
XQSERR_SRC_ACCESS
XQSERR_PARAM
XQSERR_SRC_ERROR
XQSERR_SRC_CONFIG
XQSERR_INTERNAL
Javaオブジェクトのエラー・タイプがXQSErrorIの場合は、式XQSErrorI.typNames[error.getErrorType()]によって、オブジェクトのエラー・タイプに適した文字列が戻されます。
org.w3c.dom.Node toXMLNode()このメソッドは、関数名、エラー・タイプ、エラー・コードおよびエラー・メッセージをDOMノード書式で取得するために使用します。
この項では、XQS構成ファイルxqs-config.xmlの要素の説明をアルファベット順に示します。このXQS構成ファイルのXMLスキーマは、http://www.oracle.com/technology/tech/xml/xqs/xqs-config.xsdにあります。また、このファイルは、xds/samples/XQSDemo/XDS/xqs-config.xsdのXLSDemoアプリケーションでも使用可能です。データソースの各カテゴリの主要な要素の使用方法の詳細は、「XQS関数の構成方法」を参照してください。
XQSにより、アプリケーションEARファイルのトップレベルにあるxqs-resources.jarファイルのxqs-config.xmlが参照されます。XQuery式に対して宣言された各外部関数では、XQSによりxqs-config.xmlファイルの関数の構成が参照されます。
XQS構成ファイルの要素の階層を要約します。構成するそれぞれのXQS関数について、関数がアクセスするデータソースの種類に応じて、<document-source>、<wsdl-source>または<xqsview-source>要素を使用します。
オプション。使用数: 0または1つ。
XQS構成要素内の特定のXML名前空間を表す接頭辞を指定する場合は、<use-prefix>サブ要素とともにこの要素を使用します。1つの<use-prefix>サブ要素によって、1つの接頭辞が指定されます。
<bind-prefix>要素には、属性はありません。
<document-source>、<wsdl-source>または<xqsview-source>
オプション。使用数: 0または1。使用場所: 出現する各親要素の内部。
<document-source>、<wsdl-source>または<xqsview-source>のisCached属性を介してXQSキャッシングを有効化する場合は、<cache-properties>要素およびその必須のサブ要素<in-memory>を使用して、特定のXQS関数で使用するキャッシング・プロパティを設定します。関連する考慮事項は、「XQSキャッシングの対策」を参照してください。
isCached="false"（デフォルト）と設定されている場合、<cache-properties>要素は無視されます。
| 名前 | 説明 |
|---|---|
|
time-to-live |
項目が期限切れになるまでの、キャッシュ内での保持期間を指定します。 |
なし
オプション。使用数: 0または1。使用場所: 出現する各親要素の内部。
この要素の値を使用して、data-sources.xml構成ファイルに定義されているデータソースのJNDI名を指定します。指定されたデータソースは、次の例に示すように、XQSによるデータベースへの接続に使用されます。
<dataSource>jdbc/OracleCoreDS</dataSource>
<dataSource>要素には、属性はありません。
<cache-properties>、<documentURL>、<error-message>、<function-name>、<output-element>、<XMLTranslate>
オプション。使用数: 0以上。
構成するXQS関数のうち、ドキュメント・ソースを使用するそれぞれの関数に、<document-source>要素および（必要に応じて）そのサブ要素を使用します。
実行時にURLを使用する汎用ドキュメント・ソースの使用を構成できます。もしくは、<documentURL>サブ要素を使用して、構成内で固定URLを指定できます。（実行時にURLを使用する例は、「ドキュメント・ソースにアクセスするXQS関数の構成」を参照してください。）
XML以外のドキュメントの場合は、そのドキュメントがD3Lツールでサポートされている書式に準拠している場合は、<XMLTranslate>要素を使用してXMLへの変換を構成できます。（D3Lの詳細は、「XML以外のドキュメント・ソースを使用するための準備」を参照してください。）
| 名前 | 説明 |
|---|---|
|
isCached |
データソースから結果をキャッシュするには、 |
|
largeData |
大量のデータを処理するために、メモリー節約内部最適化オプションを使用するようにXQSに指示する場合は、 |
|
onError |
値: dynamicError | emptySequence | errorMessage XQSで使用されるエラー処理モードを決定します。「XQS関数のエラー処理の構成」を参照してください。 |
なし
オプション。使用数: 0または1。使用場所: 出現する各親要素の内部。
次の例のように、この要素の値を使用して、データソースとして使用するドキュメントを指定します。
<documentURL>http://host:port/xqsdemos/Repository/pos-2KB.xml</documentURL>
XML以外のドキュメントを指定する場合は、<document-source>の<XMLTranslate>サブ要素を使用して、XQSで使用する変換ツールを指定します。
<documentURL>要素には、属性はありません。
<document-source>、<wsdl-source>または<xqsview-source>
なし
オプション。使用数: 0または1。使用場所: 出現する各親要素の内部。
XQS errorMessageエラー・モード（<document-source>、<wsdl-source>または<xqsview-source>のonError属性で指定）では、データソースから受け取ったメッセージをそのまま転送するかわりに固定エラー・メッセージを事前に定義する場合は、<error-message>要素を使用します。次の例のように、要素値によってメッセージが構成されます。
<error-message>No information available</error-message>
「XQSエラー処理の概要」も参照してください。
<error-message>要素には、属性はありません。
<document-source>、<wsdl-source>または<xqsview-source>
なし
必須。使用数: 1つのみ。使用場所: 出現する各親要素の内部。
この要素を使用して、データソースへのアクセス用にXQSによって実装されるXQuery関数の目的の名前を宣言します。要素値は関数名で、属性の設定によって関数の名前空間が指定されます。（それぞれのXQuery関数は、いずれかの名前空間に属する必要があります。）XQuery式のデフォルトとして特定の名前空間を宣言していないかぎり、XQuery式内で関数を起動するたびに、関数の名前空間を参照する必要があります。
namespace属性を使用して名前空間を直接指定します。すでに、<bind-prefix>要素を介して名前空間の接頭辞を定義している場合は、prefix属性をショートカットとして使用します。namespaceおよびprefixを同時に使用することはできません。必ずどちらか一方のみを使用してください。<output-element>要素の使用に関する情報は、「<output-element>を使用する際の考慮事項」を参照してください。
ここで指定する関数名は、対応するデータソースにアクセスするためにXQuery外部関数宣言で宣言する関数名です。
次に例を示します。
<function-name namespace="http://xmlns.oracle.com/ias/xqs"> customerInfo </function-name>
一方、xqsがXQS名前空間の接頭辞として定義されている場合は、次のようになります。
<function-name prefix="xqs">customerInfo</function-name>
次に、前述の構成に対応する、XQuery関数の宣言の例を示します。
declare namespace xqs="http://xmlns.oracle.com/ias/xqs"; declare function xqs:customerInfo() external;
| 名前 | 説明 |
|---|---|
|
namespace |
デフォルト: なし（ 名前空間を直接指定します。 |
|
prefix |
デフォルト: なし（ 事前定義済の接頭辞を介して名前空間を指定します。 |
なし
親要素が使用されている場合は必須。使用数: 1つのみ。
<cache-properties>要素およびそのサブ要素<in-memory>を使用して、XQSキャッシュのプロパティを設定します。<in-memory>要素の属性により、キャッシング・モードが決定されます。単純なメモリーベースのキャッシングの場合は、useSpoolとuseDiskCacheの両方をfalseに設定します。メモリー不足になると必要に応じてキャッシュ・データをディスクにスプールできるメモリーベースのキャッシングの場合は、useSpoolをtrueに設定し、useDiskCacheをfalseに設定します。ディスクベースのキャッシングの場合は、useDiskCacheをtrueに設定し、useSpoolをfalseに設定します。ディスクベースのキャッシングを使用すると、サーバーに障害が発生しても、キャッシュ・データは失われません。関連する考慮事項は、「XQSキャッシングの対策」を参照してください。
必要に応じてスプーリングを使用する、メモリーベースのキャッシングの例を示します。
<cache-properties time-to-live="600"> <in-memory useSpool="true" useDiskCache="false"/> </cache-properties>
追加情報は、「XQSキャッシングの構成」を参照してください。
<wsdl-source> または <xqsview-source>
必須。使用数: 1つのみ。使用場所: 出現する各親要素の内部。
この要素を使用して、関連するデータソースのXQS関数への入力パラメータを指定します。各パラメータには、<part>サブ要素を使用します。タイプ・マッチングは、WSDLソースについてのみ、type-match属性に基づきます。
この要素は、入力パラメータがない場合でも必須です。その場合は、空の要素を使用します。
なし
オプション。使用数: 0または1。使用場所: 出現する各親要素の内部。
<xquery-sequence>要素を使用して、順序のタイプを（順序の各メンバーのタイプが同じ）XQSビューの入力タイプとして使用する場合は、<itemType>サブ要素を使用してメンバーのタイプを指定できます。XQSによるタイプ・チェックの実行を許可する場合に便利です。
namespace属性を使用して、型を定義する名前空間を直接指定します。すでに、<bind-prefix>要素を介して名前空間の接頭辞を定義している場合は、prefix属性をショートカットとして使用します。namespaceおよびprefixを同時に使用することはできません。必ずどちらか一方のみを使用してください。
親要素が使用されている場合は必須。使用数: 1つ以上。使用場所: 親要素の内部。
JavaまたはEJBのバインディングを伴うWSDLソースでは、<xmlType>サブ要素と併用され、Java型とXML型をマップします。typeClass属性を使用して、Java型を指定します。
| 名前 | 説明 |
|---|---|
|
typeClass |
この属性によって、完全修飾された、XML-Java型マッピングのJavaクラス名が指定されます。このクラスは、OC4Jクラス・パスに含める必要があります。 |
なし
必須。使用数: 1つのみ。使用場所: 出現する各親要素の内部。
実行するWebサービス操作の指定に使用します。指定する操作は、<wsdlURL>要素がポイントするWSDLドキュメント内で定義された操作になります。定義には、WSDLに含まれる<operation>要素のname属性に対応するXQS <operation>要素の値が使用されます。次に例を示します。
<operation>getCustomerByKey</operation>
<operation>要素には、属性はありません。
<document-source>、<wsdl-source>または<xqsview-source>
なし
オプション。使用数: 0または1。使用場所: 出現する各親要素の内部。
この要素の値は、XQS関数の結果である順序の項目タイプを定義します。この要素は必須ではありませんが、この情報は、XQSによるタイプ・チェックおよび最適化に使用されます。この要素は、WSDLvisibility="true"と設定されているXQSビュー・ソースに使用することを特にお薦めします。タイプ情報がなくても、XQSでは有効なWebサービス操作が生成されますが、タイプ情報を持たないWebサービスを本番システムで定義することは好ましくありません。
結果項目の定義方法は2つあります。型による定義、および前に別のスキーマで定義された要素の参照による定義です。このようなインポート済要素の名前は、要素<output-element>のテキスト値として渡されます。たとえば、結果順序内の項目が、スキーマurn:PurchaseOrders名前空間の<po>要素になる場合、<output-element>は次のようになります。
<output-element namespace="urn:purchaseOrders" >po</output-element>
結果順序内の項目が、http://myHost:/mySchemas/PurchaseOrders.xsdにあるスキーマurn:PurchaseOrders名前空間で定義されたタイプPOTypeの要素になる場合、<output-element>は次のようになります。
<output-element prefix="po_ns" location="http://myHost:/mySchemas/PurchaseOrders.xsd" type="POType"/>
namespace属性を使用して名前空間を直接指定します。すでに、<bind-prefix>要素を介して名前空間の接頭辞を定義している場合は、prefix属性をショートカットとして使用します。namespaceおよびprefixを同時に使用することはできません。必ずどちらか一方のみを使用してください。
次に、複合型の例を示します。
<output-element namespace="http://xmlns.oracle.com/ias/xqs/CustomerDemo" location="http://host:port/xqsdemos/Customers.xsd" type="CustomersType"> customers </output-element>
次に、単純型の例を示します。
<output-element prefix="xs">float</output-element>
<schema-type>、<xquery-sequence>
親要素が空の場合は必須。使用数: 入力引数ごとに1つ。
WSDLソースまたはXQSビューについて、入力パラメータごとに1つの<part>要素を使用します。属性を介して、パラメータの名前および位置（順序）を指定します。必要に応じて<schema-type>サブ要素または<xquery-sequence>サブ要素（XQSビューのみ）を使用して、タイプを指定します。タイプの指定は必須ではありませんが、指定すると、XQSによるタイプ・チェックを実行できます。
WSDLソースの場合は、ソースへのアクセスに使用するWSDL操作の入力メッセージの一部分に、各<part>要素が対応している必要があります。XQSの場合は、各<part>要素が、ビューを定義するXQueryの外部変数に対応しているか、ビューを定義するSQL問合せのバインド変数に対応している必要があります。
なし
必須。使用数: 1つのみ。使用場所: 出現する各親要素の内部。
この要素の値は、<wsdlURL>要素がポイントするWSDLドキュメント内で定義されたWebサービス・ポートの名前を指定します。この値は、WSDL内の<port>要素のname属性に対応します。
属性の設定によって名前空間が指定されますが、適用可能なサービスに1つしかポートがない場合は、名前空間を指定する必要はありません。
namespace属性を使用して名前空間を直接指定します。すでに、<bind-prefix>要素を介して名前空間の接頭辞を定義している場合は、prefix属性をショートカットとして使用します。namespaceおよびprefixを同時に使用することはできません。
次に例を示します。
<port namespace="http://customer.myeis.com/">CustomerInfo</port>
別の方法の例を示します。
<bind-prefix> <use-prefix prefix="myeis">http://customer.myeis.com/</use-prefix> </bind-prefix> ... <port prefix="myeis">CustomerInfo</port>
| 名前 | 説明 |
|---|---|
|
namespace |
名前空間を直接指定します。 |
|
prefix |
事前定義済の接頭辞を介して名前空間を指定します。 |
なし
必須の場合あり。使用数: 0または1。使用場所: 出現する各親要素の内部。
この要素の値は、<wsdlURL>要素がポイントするWSDLドキュメント内で定義されたWebサービス・ポート・タイプの名前を指定します。この値は、WSDL内の<portType>要素のname属性に対応します。この要素は、操作に使用するポートのバインディングがWSDLに複数含まれている場合には必須です。
属性の設定により、名前空間が指定されますが、WSDLに含まれるすべてのポート・タイプが同じ名前空間に属する場合は、名前空間を指定する必要はありません。
namespace属性を使用して名前空間を直接指定します。すでに、<bind-prefix>要素を介して名前空間の接頭辞を定義している場合は、prefix属性をショートカットとして使用します。namespaceおよびprefixを同時に使用することはできません。
次に例を示します。
<portType namespace="http://customer.myeis.com/">CustomerInfoType</portType>
| 名前 | 説明 |
|---|---|
|
namespace |
名前空間を直接指定します。 |
|
prefix |
事前定義済の接頭辞を介して名前空間を指定します。 |
なし
オプション。使用数: 0または1。使用場所: 出現する各親要素の内部。
次の例で示すように、この要素の値を使用して、XQSビューが定義されているXQuery式のテキスト・ファイル（.xqまたは.sqlファイル）の名前を指定します。
<queryName>UserByOrderNum.xq</queryName>
ファイル名の拡張子.xqまたは.sqlは、XQSによって自動的に推定されるため、指定しなくてもかまいません。XQSがファイルを検索するディレクトリは、<xqsview-source>の<repository>サブ要素（あるいはデフォルトの場所）に基づきます。
<queryName>要素を使用しない場合、XQSでは、XQSビュー・ファイルの名前は、<xqsview-source>の<function-name>サブ要素で指定した関数名と同じで、ビューのタイプに応じて拡張子は.xqまたは.sqlであるとみなされます。
<queryName>要素には、属性はありません。
なし
オプション。使用数: 0または1。使用場所: 出現する各親要素の内部。
この要素の値は、XQSビューが定義されているXQuery式のテキスト・ファイル（.xqファイル）またはSQL問合せファイル（.sqlファイル）を含むディレクトリへの絶対パスです。<xqsview-source>の<queryName>サブ要素で名前を指定します。
<repository>要素を使用しない場合は、OC4JPackagerの-repositoryオプションを介して指定したディレクトリ内がXQSによって検索されます。XQSのデモ・アプリケーションのデフォルト・ディレクトリを明示的に指定する場合の例を示します。
<repository>/META-INF/xqs/mydir/</repository>
<repository>要素には、属性はありません。
なし
親要素が使用されている場合は必須。使用数: 1つのみ。
ドキュメント・ソースが、XML以外の、D3Lツールによってサポートされている書式である場合は、<XMLTranslate>要素および<schema-file>サブ要素を使用して、そのドキュメントをXMLに変換するための情報をXQSに渡します。（D3Lの詳細は、「XML以外のドキュメント・ソースを使用するための準備」を参照してください。）
<XMLTranslate>要素は、使用する変換ツール（D3L）を指定し、<schema-file>要素は、変換に使用するスキーマ・ファイルを指定します。
次に例を示します。
<documentURL>http://host:port/xqsdemos/paymentInfo.csv</documentURL> <XMLTranslate method="D3L"> <schema-file>http://host:port/xqsdemos/paymentInfoD3L.xml</schema-file> </XMLTranslate>
<schema-file>要素には、属性はありません。
なし
説明を参照。使用数: 1つのみ。
XQSビューの各入力パラメータについて、この要素または<xquery-sequence>要素（入力順序の場合）を使用して、パラメータ・タイプを指定する必要があります。
WSDLソースの各入力パラメータでは、この要素を<part>親要素内で使用することはオプションですが、この要素は、タイプ・チェックに役立つほか、すべてのタイプのリストをXQS構成ファイルに含めるという編成上の目的にも役立ちます。（WSDLソースでは、入力順序は適用されません。）
WSDLソースでタイプ・チェックを実行するには、<input-parameters>要素の属性がtype-match="strict"と設定されている必要があります。
<schema-type>では、要素値によってタイプが指定され、属性設定によって名前空間が指定されます。namespace属性を使用して名前空間を直接指定します。すでに、<bind-prefix>要素を介して名前空間の接頭辞を定義している場合は、prefix属性をショートカットとして使用します。namespaceおよびprefixを同時に使用することはできません。必ずどちらか一方のみを使用してください。
次に例を示します。
<input-parameters> <part position="1" name="empname"> <schema-type namespace="http://www.w3.org/2001/XMLSchema">string</schema-type> </part> </input-parameters>
別の方法として、xsをXML Schemaの名前空間として定義する場合の例を示します。
<bind-prefix> <use-prefix prefix="xs">http://www.w3.org/2001/XMLSchema</use-prefix> </bind-prefix> ... <input-parameters> <part position="1" name="empname"> <schema-type prefix="xs">string</schema-type> </part> </input-parameters>
ユーザー定義の型の場合は、次のようになります。
<input-parameters> <part position="1" name="DBServiceSelect_cust_id_inparameters"> <schema-type namespace= "http://xmlns.oracle.com/pcbpel/adapter/db/top/TestDBAdapter"> DBServiceSelect_cust_id </schema-type> </part> </input-parameters>
ユーザー定義のXML型に加えて、現在、XQSでは、XQuery 1.0およびXPath 2.0データ・モデルで定義されている型のサブセット、すなわちxs:boolean、xs:string、xs:int、xs:long、xs:float、xs:double、xs:decimal、xs:base64Binary、xs:hexBinary、xs:anyURI、xs:dateTime、xs:durationおよびxs:anyTypeをサポートしています。（「サポートされている問合せパラメータのタイプ」も参照してください。）サポート対象外のXQuery/XPath入力タイプを使用する場合は、サポートされている中で、データに最も適したJava表現のタイプを選択し、<input-parameters>要素内でtype-match="none"の設定を使用します。（JavaまたはEJBのバインディングを伴うWSDLソースの場合、このような状況では、<wsdl-source>の<typeMap>サブ要素も使用します。）
| 名前 | 説明 |
|---|---|
|
namespace |
デフォルト: なし（ 名前空間を直接指定します。 |
|
prefix |
デフォルト: なし（ 事前定義済の接頭辞を介して名前空間を指定します。 |
なし
必須の場合あり。使用数: 0または1。使用場所: 出現する各親要素の内部。
この要素の値は、サービスの名前を指定します。指定するサービスは、<wsdlURL>要素がポイントするWSDLドキュメント内で定義されたサービスになります。定義には、WSDLに含まれる<service>要素のname属性に対応するXQS <service>要素の値が使用されます。XQS <service>要素は、WSDLドキュメントで複数のサービスが定義されている場合には必須です。
属性の設定により、名前空間が指定されますが、WSDLに含まれるすべてのサービス要素が同じ名前空間に属する場合は、名前空間を指定する必要はありません。
namespace属性を使用して名前空間を直接指定します。すでに、<bind-prefix>要素を介して名前空間の接頭辞を定義している場合は、prefix属性をショートカットとして使用します。namespaceおよびprefixを同時に使用することはできません。
次に例を示します。
<service namespace="http://customer.myeis.com/">CustomerInfoMYEISService</service>
| 名前 | 説明 |
|---|---|
|
namespace |
名前空間を直接指定します。 |
|
prefix |
事前定義済の接頭辞を介して名前空間を指定します。 |
オプション。使用数: 0または1。使用場所: 出現する各親要素の内部。
JavaまたはEJBのバインディングを伴うWSDLソースでは、必要に応じてこの要素を使用し、XML型をJava型にマップできます。Java型は、<mapping>サブ要素を介して指定し、XML型は、<mapping>の<xmlType>サブ要素を介して指定します。
<typeMap>要素には、属性はありません。
なし
親要素が使用されている場合は必須。使用数: 1つ以上。
特定のXML名前空間を表す接頭辞を使用する場合は、<bind-prefix>要素および<use-prefix>サブ要素を使用します。各<use-prefix>サブ要素は、1つの接頭辞を指定します。使用される要素値は、名前空間を表す接頭辞を指定する、名前空間および接頭辞の属性を指定します。次に例を示します。
<bind-prefix> <use-prefix prefix="xs">http://www.w3.org/2001/XMLSchema</use-prefix> <use-prefix prefix="xqs">http://xmlns.oracle.com/ias/xqs</use-prefix> <use-prefix prefix="myeis">http://customer.myeis.com/</use-prefix> </bind-prefix>
これらの設定により、名前空間を指定する必要があるXQS構成要素では、たとえば、namespace="http://customer.myeis.com/"のかわりにprefix="myeis"を使用できます。
| 名前 | 説明 |
|---|---|
|
prefix |
この属性は、目的の接頭辞を指定します。 |
なし
オプション。使用数: 0または1つ。
この要素は、将来のセキュリティ拡張のために予約されています。
<username>要素には、属性はありません。
<cache-properties>、<error-message>、<function-name>、<input-parameters>、<operation>、<output-element>、<port>、<portType>、<service>、<typeMap>、<wsdlURL>
オプション。使用数: 0以上。
構成するXQS関数のうち、WSDLベースのソースにアクセスするそれぞれの関数に、<wsdl-source>要素および（必要に応じて）そのサブ要素を使用します。（XQSで使用できるWSDLベースのソースの種類は、「データソースのサポート対象カテゴリ」を参照してください。）
| 名前 | 説明 |
|---|---|
|
isCached |
データソースから結果をキャッシュするには、 |
|
largeData |
大量のデータを処理するために、メモリー節約内部最適化オプションを使用するようにXQSに指示する場合は、 |
|
onError |
値: dynamicError | emptySequence | errorMessage XQSで使用されるエラー処理モードを決定します。「XQSエラー処理の概要」を参照してください。 |
なし
必須。使用数: 1つのみ。使用場所: 出現する各親要素の内部。
実行する操作を定義するWSDLドキュメントをポイントするために使用します。WSDLへのアクセスは、実行時行われます。次に例を示します。
<wsdlURL>http://api.mySearch.com/mySearch.wsdl</wsdlURL>
<wsdlURL>要素には、属性はありません。
該当なし（ルート）
必須。使用数: 1つのみ。
これは、xqs-config.xmlのルート要素です。最低限必要な要素は、このルート要素、そのサブ要素<xqs-sources>、および<xqs-sources>のサブ要素（<document-source>、<wsdl-source>、<xqsview-source>）のうち少なくとも1つです。
| 名前 | 説明 |
|---|---|
|
version |
この属性は、 |
<document-source>、<wsdl-source>、<xqsview-source>
必須。使用数: 1つのみ。
これは、構成される全XQS関数のソース要素の親要素です。属性はありません。
<cache-properties>、<error-message>、<function-name>、<input-parameters>、<output-element>、<queryName>、<repository>、<dataSource>
オプション。使用数: 0以上。
構成するXQS関数のうち、XQSビューを使用するそれぞれの関数に、<xqsview-source>要素および（必要に応じて）そのサブ要素を使用します。
| 名前 | 説明 |
|---|---|
|
fetchSize |
この属性は、リレーショナル・データベースに接続するSQLベースのXQSビューにのみ有効です。この属性はオプションです。
この |
|
isCached |
データソースから結果をキャッシュするには、 |
|
largeData |
大量のデータを処理するために、メモリー節約内部最適化オプションを使用するようにXQSに指示する場合は、 |
|
onError |
値: dynamicError | emptySequence | errorMessage XQSで使用されるエラー処理モードを決定します。「XQSエラー処理の概要」を参照してください。 |
|
WSDLvisibility |
アプリケーションのWebサービス・コンポーネントで、XQSをWebサービス操作として公開する場合は、これを |
|
SQLResultType |
この属性は、SQLベースのビューを使用している場合にのみ適用可能です。この属性では、データベース問合せで、データをリレーショナル（表）形式またはXMLのいずれで戻すかを設定します。Oracle XMLデータベースを使用している場合は、 |
|
rowTag |
この属性は、SQLベースのビューを使用している場合にのみ適用可能です。この属性が指定されている場合、データベースの結果のリレーショナルからXMLへの変換で使用された要素のデフォルト名は、この値で上書きされます。この属性は、 「XQSビューを使用するXQS関数の構成」も参照してください。 |
|
rowIdAttr |
この属性は、SQLベースのビューを使用している場合にのみ適用可能です。この属性が指定されている場合、結果に含まれる行要素の番号付けが制御されます。この属性は、
「XQSビューを使用するXQS関数の構成」も参照してください。 |
|
XMLFormat |
この属性は、SQLベースのビューを使用している場合にのみ適用可能です。この属性の値は |
オプション。使用数: 0または1。使用場所: 出現する各親要素の内部。
ドキュメント・ソースが、XML以外の、D3Lツールによってサポートされている書式である場合は、<XMLTranslate>要素および<schema-file>サブ要素を使用して、そのドキュメントをXMLに変換するための情報をXQSに渡します。この要素は、Excelのカンマ区切り（CSV）ファイルなど、別の書式のファイルをXMLに変換する場合に便利です。D3Lの詳細は、「XML以外のドキュメント・ソースを使用するための準備」を参照してください。
<XMLTranslate>のmethod属性は、使用する変換ツールを指定します。現在、XQSでサポートされているのは、D3L変換ツールです。
<schema-file>サブ要素は必須で、変換に使用するスキーマを指定します。
| 名前 | 説明 |
|---|---|
|
method |
XQSで使用する変換ツールを指定します。XQSで現在サポートされているのは、D3Lです。 |
なし
必須。使用数: 1つのみ。使用場所: 出現する各親要素の内部。
JavaまたはEJBのバインディングを伴うWSDLでは、<mapping>親要素と併用され、Java型とXML型をマップします。属性設定を使用してXML型の名前空間を指定します。名前空間を直接指定する場合は、namespace属性を使用します。すでに、<bind-prefix>要素を介して名前空間の接頭辞を定義している場合は、prefix属性をショートカットとして使用します。namespaceおよびprefixを同時に使用することはできません。必ずどちらか一方のみを使用してください。
<mapping>親要素は、Java型を指定します。
次に例を示します。
<typeMap> <mapping typeClass="org.w3c.dom.Node"> <xmlType prefix="myeis">Customer</xmlType> </mapping> ... </typeMap>
| 名前 | 説明 |
|---|---|
|
namespace |
デフォルト: なし（ 名前空間を直接指定します。 |
|
prefix |
デフォルト: なし（ 事前定義済の接頭辞を介して名前空間を指定します。 |
親要素またはXQSビューが出現するたびに、その内部でこの要素または<schema-type>を使用する必要があります。使用数: 1つのみ。
XQSビューの、パラメータ・タイプがXQuery/XPath順序の入力パラメータごとに、<part>親要素内でこの要素を使用して、タイプを指定する必要があります（これに対して、順序以外のタイプには、<schema-type>要素が使用されます）。
WSDLソースでは、入力順序がサポートされていないため、この要素は関係ありません。
<xquery-sequence>要素は、複数のタイプの項目を含む異機種間の順序に使用できます。その場合は、この要素を空にする必要があります。もしくは、<itemType>サブ要素を含めて、異機種間順序の各メンバーの共通タイプを指定できます。
<xquery-sequence>要素には、属性はありません。
この項では、XQSのパッケージ化ユーティリティであるOC4JPackagerのパラメータおよびプロパティに関するリファレンス・ドキュメントを提供します。概要は、「OC4JPackagerの概要」を参照してください。使用方法は、「OC4JPackagerを使用したXQSアプリケーションのパッケージ方法」を参照してください。
この項では、アルファベット順に、OC4JPackagerのパラメータの説明および使用例を示します。OC4JPackagerは、次のように実行します（%はコマンド・プロンプトです）。
% java -jar OC4JPackager.jar -option1 value1 -option2 value2 ... -optionN valueN
必須。ディレクトリ・パスを指定します。
アプリケーションの場所を指定するために使用します。アプリケーションの場所は、EARファイルが含まれているディレクトリ、またはEAR構造のトップレベル・ディレクトリです。
-appArchives /dir1/myappdir
オプション。これは、切替えフラグです。
OC4JPackagerの使用状況およびパラメータ・リストを示すために使用します。その際、その他のパラメータは使用しません。
-help
オプション（XQS JSPタグ・ライブラリを使用する場合は必須）。これは、切替えフラグです。
XQS JSPタグ・ライブラリのJARファイル（xquerytaglib.jar）を出力EARファイルに含めるために使用します。
-jsp
必須。EARファイルの名前を指定します。
出力EARファイルの目的の名前（.ear拡張子の有無は任意）を指定するために使用します。このファイルの場所は、-outputパラメータによって決まります。
-name myxqsapp.ear
オプション。これは、切替えフラグです。
Webサービスを生成しないようにする場合に使用します。
-no_ws
必須。ディレクトリ・パスを指定します。
OC4JPackagerによって作成されるEARファイルの配置場所を指定するために使用します。ファイル名は、-nameパラメータに基づきます。
-output /dir1/mydeployments
オプション。ディレクトリ・パスを指定します。
XQSビューが格納されるXQSリポジトリの場所を指定するために使用します。
-repository ORACLE_HOME/xds/samples/repository
オプション（XQSステートフルEJBクライアントAPIを使用する場合は必須）。これは、切替えフラグです。
XQSステートフルEJBクライアントのJARファイル（xqsclient-stateful.jar）を出力EARファイルに含めるために使用します。
-sf
また、これにより、次の<module>要素がapplication.xmlファイルに追加されます。
<module> <ejb>xqsclient-stateful.jar</ejb> </module>
オプション（XQSステートレスEJBクライアントAPIを使用する場合は必須）。これは、切替えフラグです。
XQSステートレスEJBクライアントのJARファイル（xqsclient-stateless.jar）を出力EARファイルに含めるために使用します。
-sl
また、これにより、次の<module>要素がapplication.xmlファイルに追加されます。
<module> <ejb>xqsclient-stateless.jar</ejb> </module>
必須。ファイルのパスを指定します。
アプリケーションに対して、XQS構成ファイルxqs-config.xmlのパス（ファイル名を含む）を指定するために使用します。
-xqsConfigFile /dir1/subdir/myconfigdir/xqs-config.xml
この項では、アルファベット順に、OC4JPackagerでサポートされているJavaプロパティの説明および使用例を示します。Java -Dオプションは、次のように使用します。
java -Dproperty1=value1 -Dproperty2=value2 -jar OC4JPackager.jar \ -option1 value1 -option2 value2 ... -optionN valueN
オプション。ディレクトリ・パスを指定します。
OC4JPackagerでは、Oracleホーム・ディレクトリを指定するためのoracle.homeがサポートされています。次に例を示します。
-Doracle.home=/myroot/myoraclehome
Oracleホーム・ディレクトリを指定すると、-jsp、-sfおよび-slの各フラグを介して要求されたクライアントJARファイルの検索、およびこれらのファイルのアプリケーションへのバンドルが可能になります。oracle.homeを設定しない場合は、これらのフラグが無視されます。
必須。ディレクトリ・パスを指定します。
OC4JPackagerが作業（JARファイルのバンドル解除やバンドルなど）のためにjavaコマンドを実行する、Javaホーム・ディレクトリへのパスを指定します。
-Djava.home=/dir1/myjavahome
このプロパティを指定しない場合、OC4JPackagerは終了します。
オプション。ファイルのパスを指定します。
Javaロギング・プロパティを指定するファイルへのパス（ファイル名を含む）を示すために使用します。次の例では、myfile.propertiesが現在のディレクトリにあります。
-Djava.util.logging.properties.file=myfile.properties
ロギング・プロパティ・ファイルを指定しない場合は、Javaエラーの出力を確認できません。
OC4JPackagerでは、次の場所で示されるように、標準のJ2SEロギング・フレームワークを使用して、メッセージがログに記録されます。
http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/
OC4JPackagerにより、プロパティ・ファイル内では、OC4JPackagerからのメッセージのロギング・レベルを指定できるプロパティoracle.xds.tools.OC4JPackager.levelがサポートされています。指定できるレベルは、SEVERE、WARNING、INFOまたはFINEです。高レベルの進捗メッセージにはINFO、低レベルのデバッグ・メッセージにはFINEを使用します。
メッセージをコンソールに送り、OC4JPackagerからのメッセージにINFOレベルを使用する場合の、ロギング・プロパティ・ファイルのエントリの例を示します。
# output to console handlers= java.util.logging.ConsoleHandler ... # set packager level to INFO oracle.xds.tools.OC4JPackager.level=INFO
オプション。ディレクトリ・パスを指定します。
これを使用して、EARファイルのバンドル解除および再作成の際にOC4JPackagerが使用する、作業ディレクトリを指定します。
-Dxds.packager.work.dir=/some/dir
デフォルトの場所は、user.homeディレクトリです。
この項では、OC4Jロギングを有効化する方法を説明し、XQSアプリケーションに関する様々なトラブルシューティングのヒントを提供します。
Javaプロパティjava.util.logging.properties.fileを使用して、OC4Jロギングを有効化し、ロギング・プロパティ・ファイルを指定できます。このファイルでは、OC4JPackagerのロギング・レベルを含む、Javaロギング設定を指定できます。ロギング・プロパティは、次の場所で指定されているように、標準のJ2SEロギングによって定義されます。
http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/
ロギングの詳細は、「java.util.logging.properties.file」、『Oracle Containers for J2EE構成および管理ガイド』の「OC4Jでのロギング」の章、および『Oracle Containers for J2EE開発者ガイド』の「ロギング実装のガイドライン」を参照してください。
この項では、XQSアプリケーションで発生する潜在的な問題およびその解決方法を説明します。
サイズの大きいXML文書をメモリーにロードできない場合は、largeDataフラグを有効化すると処理が可能になることがあります。「ラージ・データ用のXQSドキュメント・ソースの構成」を参照してください。
次のような内容のエラー・メッセージが表示されます（ここで、arityは関数が取る引数の数を表し、nsおよびfuncnameは関数の名前空間および名前に置き換えられます）。
XP0017: It is a static error if the expanded QName and number of arguments in a function call do not match the name and arity of an in-scope function in the static context. Detail: unknown function 'ns:funcname'
重要なのは、XQueryによって関数が認識されなかったということです。これは、関数が正しく構成されていなかったために、関数がXQSによって正常にロードされなかった可能性があることを示しています。OC4Jエラー・ログ・ファイル（ORACLE_HOME/j2ee/home/log/oc4j/log.xmlなど）で、この関数で発生した問題の詳細な説明を検索してください。
次のようなエラーが発生したとします。
external function "Foo" has inconsistent signatures: the one defined in function library framework is different from the one declared in function declaration prolog
XQSとの関係において、function library framework（関数ライブラリ・フレームワーク）という用語は、XQS構成ファイルの<input-parameters>要素内で定義されたシグネチャを表すことに注意してください。<input-parameters>要素の下にある<part>定義は、必ずXQueryプロローグ内の関数のシグネチャと一致する必要があります。
XQueryシグネチャを構成と一致させることができない場合は、使用するXML型がサポートされていない可能性があります。（「サポートされている問合せパラメータのタイプ」を参照してください。）対応策として、XQueryパラメータまたはXQueryの戻り値について、プロローグでの型の宣言をすべて回避できます。たとえば、次のように完全に型が指定された関数の宣言があるとします。
declare function xqs:Foo ($s as element()) as xs:positiveInteger external;
型を指定せずにこの関数を宣言するには、次のようにします。
declare function xqs:Foo ($s) external;
ただし、XQS構成を介して、入力パラメータの数を常に指定する必要があります。
XQSの例は、Oracle Technology Networkの次のWebサイトで、XQSを検索してください。
http://www.oracle.com/technology/tech/java/oc4j/1013/how_to/index.html
|
 Copyright © 2006 Oracle Corporation. All Rights Reserved. |
|