XQuery 開発者ガイド

     Previous  Next    Open TOC in new window     
Content starts here

AquaLogic Data Services Platform アノテーションについて

この章では、データ サービス内の BEA AquaLogic Data Services Platform アノテーションの構文とセマンティクス、および XQuery 関数ライブラリ (XQuery Function Library:XFL) ドキュメントについて説明します。 データ サービスと XQuery 関数ライブラリ ドキュメントでは、XQuery 関数のコレクションを定義します。アノテーションとは、XQuery プラグマの文字コンテンツを構成する XML フラグメントです。

アノテーションには 2 つの種類があります。

この章の内容は以下のとおりです。

アノテーションの XML スキーマについては、「アノテーション リファレンス」を参照してください。

 


XDS アノテーション

データ サービス ドキュメントごとに 1 つの XDS アノテーションがあり、すべての関数アノテーションより前に現れます。XDS アノテーションが含まれるプラグマの識別子は xds です。XDS アノテーションに対応する、XML フラグメントの最上位レベルにある要素の修飾名には、ローカル名 xds とネームスペース URI urn:annotations.ld.bea.com が含まれます。

各データ サービスは固有の対象の型に関連付けられています。あらゆる読み取り関数において戻り値の型のうちプライマリの型は、対象の型と一致する必要があります。データ サービスの対象の型は要素型であり、その修飾名は xds 要素の targetType 属性によって指定されます。これは、そのデータ サービスに関連付けられたスキーマ ファイル内に定義されます。

最上位レベルの xds 要素の中には、以下のようなプロパティ ブロックのシーケンスが含まれています。

XDS アノテーションの例を以下に示します。この場合、対象の型 t:CUSTOMER は、データ サービスをスキーマ ファイル内にある t:CUSTOMER 型に関連付けます。

(::pragma xds <x:xds xmlns:x="urn:annotations.ld.bea.com" targetType="t:CUSTOMER" xmlns:t="ld:oracleDS/CUSTOMER">

<author>Joe Public</author>
<relationalDB name="OracleDS"/>

<field type="xs:string" xpath="FIRST_NAME">
<extension nativeFractionalDigits="0" nativeSize="64"
nativeTypeCode="12" nativeType="VARCHAR2"
nativeXpath="FIRST_NAME"/>
<properties nullable="false"/>
</field>
<field type="xs:string" xpath="LAST_NAME">
<extension nativeFractionalDigits="0" nativeSize="64"
nativeTypeCode="12" nativeType="VARCHAR2"
nativeXpath="LAST_NAME"/>
<properties nullable="false"/>
</field>

<field type="xs:string" xpath="CUSTOMER_ID">
<extension nativeFractionalDigits="0" nativeSize="64"
nativeTypeCode="12" nativeType="VARCHAR2"
nativeXpath="CUSTOMER_ID"/>
<properties nullable="false"/>
</field>

<field type="xs:dateTime" xpath="CUSTOMER_SINCE">
<extension nativeFractionalDigits="0" nativeSize="7"
nativeTypeCode="93" nativeType="DATE"
nativeXpath="CUSTOMER_SINCE"/>
<properties nullable="false"/>
</field>

<field type="xs:string" xpath="EMAIL_ADDRESS">
<extension nativeFractionalDigits="0" nativeSize="32"
nativeTypeCode="12" nativeType="VARCHAR2"
nativeXpath="EMAIL_ADDRESS"/>
<properties nullable="false"/>
</field>

<key name="CUSTOMER_PK11015727676593">
<field xpath="CUSTOMER_ID">
<extension nativeXpath="CUSTOMER_ID"/>
</field>
</key>

<relationshipTarget roleName="CUSTOMER_ORDER" roleNumber="2"
XDS="ld:oracleDS/CUSTOMER_ORDER.xds" minOccurs="0"
maxOccurs="unbounded" opposite="CUSTOMER"/>
</x:xds>::)

標準プロパティ

標準XDS プロパティには 2 つの種類があります。

標準ドキュメント プロパティ

ドキュメントの作成者、作成日、バージョンに関する情報を含む、オプションの XML 要素で構成される標準ドキュメント プロパティのセットを指定できます。また、関連ドキュメントを指定するために、「documentation」 という名前のオプション要素を使用することもできます。標準ドキュメント プロパティ ブロックに含まれる要素の名前と型を、使用例と一緒に表 6-1 に示します。

表 6-1 標準ドキュメント プロパティ
要素名
要素型
省略の可否
author
xs:string
<author>J. Public</author>
creationDate
xs:date
<creationDate>2004-05-31</creationDate>
version
xs:decimal
<version>2.2<version>
documentation
xs:string
<documentation> Models an online Customer </documentation>

ユーザ定義プロパティ

標準プロパティに加えて、0 個以上の property 要素のシーケンスを使用して、データ サービス ドキュメント全体に対するカスタム プロパティを指定することもできます。 各プロパティ要素の名前は、name 属性を使用して指定する必要があり、任意の文字列コンテンツを含むことできます。例えば、次のように指定します。

<property name="data-refresh-rate">week</property> 

データ アクセス プロパティ

各データ サービス ドキュメントでは、データ プロバイダまたはデータ トランスデューサのいずれかとして機能する 1 つまたは複数の XQuery 関数を定義します。データ プロバイダ、つまりはデータ ソースは、external として宣言された関数です。この関数を呼び出すと、外部ソースからシステムにデータが取り込まれます。データ トランスデューサ、つまりデータ ビューは、XQuery で定義され、通常はデータ ソースまたは他のデータ ビューからのデータを変換します。

データ アクセス プロパティ ブロックを使用すると、各データ サービスは、読み取り関数にデータ ソースが含まれるかどうかを定義できます。データ ソースが含まれている場合、データ アクセス アノテーションでは、外部の関数 (データ サービスごとに 1 つの外部ソースが存在する場合がある) とその接続プロパティによってアクセスされる外部ソースの型を記述します。データ ソースが含まれていない場合、データ サービスはユーザ定義ビューとして指定され、接続情報は必要ありません。

データ サービスではまた、プライベート関数と呼ばれる他の形式の XQuery 関数も定義されることがあります。以下のデータ ソース データ サービスがサポートされます。

以降の節では、各データ サービス タイプのためのデータ アクセス アノテーションと、ユーザ定義ビューとして指定されるデータ サービスについて説明します。各データ サービスに指定できるアノテーションは 1 つだけです。アノテーションが指定されていない場合、データ サービスはユーザ定義ビューと見なされます。

リレーショナル データ サービス アノテーション

リレーショナル データ サービス用のデータ アクセス アノテーションでは、空の relationalDB 要素に唯一の必須属性である name を指定します。name 属性の値として、外部のリレーショナル ソースがアプリケーション サーバに登録されるときに使用した JNDI 名を設定する必要があります。例えば、次のように指定します。

<relationalDB name="OracleDS"/>

さらに、relationalDB 要素には、以下のオプション部分を指定することもできます。

ネイティブのリレーショナル プロパティ

properties 要素は、複数の属性を持つ空の要素です。表 6-2 に省略可能と明記されていない限り、すべての属性が必要です。

表 6-2 properties 要素の属性
属性
説明
catalogSeparator
RDBMS がカタログとテーブル名の区切り文字として使用する文字列を指定する。必須。
identifierQuote
RDBMS が SQL 識別子を引用するために使用する文字列を指定する。必須。
catalogQuote
RDBMS がデータベース カタログの識別子を引用するために使用する文字列を指定する。省略可能。
schemaQuote
RDBMS がデータベース スキーマ識別子を引用するために使用する文字列を指定する。省略可能。
tableQuote
RDBMS がテーブル識別子を引用するために使用する文字列を指定する。省略可能。
columnQuote
RDBMS がカラムの識別子を引用するために使用する文字列を指定する。省略可能。
nullSortOrder
RDBMS がどのように null 値をソートするかを指定する文字列。値は high, low, unknown のいずれかを指定する。必須。
supportsCatalogsInDataManipulation
RDBMS が Data Manipulation Language (DML) SQL ステートメント内でカタログ名をサポートするかどうかを指定するブール。必須。
supportsLikeEscapeClause
RDBMS が LIKE エスケープ句をサポートするかどうかを指定するブール。必須。
supportsSchemasInDataManipulation
RDBMS が DML SQL ステートメント内でスキーマ名をサポートするかどうかを指定するブール。必須

ソース バインディング プロバイダ

オプションの sourceBindingProviderClassName 属性の値は、com.bea.ld.bindings.SourceBindingProvider インターフェースを実装するユーザ定義 Java クラスの完全修飾名にバインドする必要があります。これは次のように定義します。

package com.bea.ld.bindings;
public interface SourceBindingProvider
{
public String getBinding(String genericLocator, boolean isUpdate);
}

ユーザ定義の実装では、静的に設定されたリレーショナル ソース名 (パラメータ genericLocator) と、リレーショナル ソースへのアクセスがクエリからなのか、更新モード (パラメータ isUpdate) なのかを示すブール フラグをもとに、システムが実行時に使用するリレーショナル ソース名を決定する変換を行う必要があります。

こうした変換メカニズムを使用して資格マッピングを行うことができます。この場合、静的に設定された 1 つのリレーショナル ソース R0 に対して異なる 2 人のユーザ U1 と U2 によって実行される 1 組のクエリまたは更新操作は、異なる 2 つのリレーショナル ソース R1 と R2 に対してそれぞれ実行されます (ここでは、R0、R1、R2 のすべてのソースが同じ RDBMS を表し、R1 と R2 に使用された接続資格に適用されたセキュリティ ポリシは、ユーザ U1 と U2 のアプリケーション資格に適用されたセキュリティ ポリシにそれぞれ対応します)。

注意 : ソース バインディング プロバイダ名は、同じリレーショナル ソース JNDI 名を共有するすべてのリレーショナル データ サービスで一律に設定する必要があります。この制限は強制ではありませんが、違反すると実行時に予測できない結果を招くおそれがあります。

Web サービス データ サービス アノテーション

Web サービスに基づくデータ サービス用のデータ アクセス アノテーションは、表 6-3 で説明する 2 つの必須属性を持つ空の webService 要素で構成されます。

表 6-3 webService 要素の必須属性
属性
説明
wsdl
外部の Web サービス ソースの定義が含まれる WSDL ファイルの場所を示す有効な http: または ld: URI。
targetNamespace
WSDL の targetNamespace URI と同一の有効な URI。

例えば、次のように指定します。

<webService targetNamespace="urn:GoogleSearch"
wsdl="ld:google/GoogleSearch.wsdl"/>

Java 関数 データ サービス アノテーション

Java 関数データ サービス用のデータ アクセス アノテーションは、 唯一の必須属性「class」を持つ空の javaFunction 要素で構成されます。この属性には、外部ソースとして機能する Java クラスの完全修飾名をセットする必要があります。例えば、次のように指定します。

<javaFunction class="com.example.Test"/>

区切り文字付きコンテンツ データ サービス アノテーション

区切り文字付きデータ サービス用のデータ アクセス アノテーションは、空の要素 delimitedFile であり、表 6-4 で説明するオプション属性をその中に指定できます。

表 6-4 delimitedFile 要素のオプション属性
属性
説明
file
区切り文字付きファイルの場所を示す有効な URI。
schema
区切り文字付きコンテンツのタイプ (構造) を定義する XML スキーマ ファイルの場所を示す有効な URI。指定されていない場合は、スキーマはコンテンツに基づいて導き出される。
inferredSchema
スキーマが推定されたものか、またはユーザが提供したものかを指定する。デフォルト値は false。
delimiter
区切り記号として使用する文字列。指定されていない場合は、fixedLength 属性が指定されていなければならない。
fixedLength
固定長コンテンツに含まれるトークンの固定長。指定されていない場合は、delimiter 属性が指定されていなければならない。
hasHeader
コンテンツの第 1 行目をヘッダーとして解釈する必要があるかどうかを示すブール フラグ。デフォルト値は false。

例えば、次のように指定します。

<delimitedFile schema="ld:df/schemas/ALL_TYPES.xsd" hasHeader="true"
delimiter="," file="ld:df/ALL_TYPES.csv"/>

XML コンテンツ データ サービス アノテーション

XML コンテンツ データ サービス用のデータ アクセス アノテーションは、空の xmlFile要素であり、表 6-5 に説明する属性をその中に指定できます。

表 6-5 xmlFile 要素の属性
属性
説明
file
(省略可能) XML ファイルの場所を示す有効な URI。
schema
XML コンテンツのタイプ (構造) を定義する XML スキーマ ファイルの場所を示す有効な URI。

例えば、次のように指定します。

<xmlFile schema="ld:xml/somewhere/CUSTOMER.xsd"
file="ld:xml/CUSTOMER_NESTED.xml"/>

ユーザ定義ビュー XDS アノテーション

ユーザ定義ビュー データ サービス用のデータ アクセス アノテーションは、論理データ サービスとも呼ばれています。1 つの空の userDefinedView 要素で構成されます。例えば、次のように指定します。

<userDefinedView/>

対象の型プロパティ

オプションの対象の型プロパティ ブロックによって、次のようなネイティブ タイプ情報について、データ サービスの対象の型に含まれる単純な値のフィールドにアノテーションを付けることができます。

field 要素定義の例を次に示します。

<field type="xs:string" xpath="FIRST_NAME">
<extension nativeSize="64" nativeTypeCode="12" nativeType="VARCHAR2"
nativeXpath="FIRST_NAME"/>
<properties nullable="false"/>
</field>

ネイティブ タイプ プロパティ

各 field 要素には、オプションの extension 要素を指定できます。extension 要素には、表 6-7 で説明するオプション属性を指定できます。

表 6-7 extension 要素のオプション属性
属性
説明
nativeXpath
外部ソース内の対応するネイティブ フィールドを指すネイティブ XPath 値。
nativeType
外部ソースに認識されている、対応するネイティブ フィールドのネイティブ タイプのネイティブ名。
nativeTypeCode
外部ソースに認識されている、対応するネイティブ フィールドのネイティブ タイプのネイティブ タイプ コード。リレーショナル ソースの場合、JDBC によって報告されたタイプ コードになる。
nativeSize
外部ソースに認識されている、対応するネイティブ フィールドのネイティブ タイプのネイティブ サイズ。リレーショナル ソースの場合、JDBC によって報告されたサイズになる。
nativeFractionalDigits
外部ソースに認識されている、対応するネイティブ フィールドのネイティブ タイプのネイティブ スケール。リレーショナル ソースの場合、JDBC によって報告されたスケールになる。

更新関連のタイプ プロパティ

各 field 要素にはオプションの properties 要素も指定できます。 properties 要素の中には、表 6-8 で説明するオプション属性を指定できます。

表 6-8 properties 要素のオプション属性
属性
説明
immutable
フィールドが不変(読み取り専用)かどうかを指定するブール値。デフォルト値は false。
nullable
フィールドが null 値を受け入れるかどうかを指定するブール値。デフォルト値は false。

キー プロパティ

オプションのキー プロパティ ブロックによって、データ サービスの対象の型上にある ID 制約 (キー) のセットを指定できます。各キーは、key 要素によって表されます。key 要素には、キーの識別子となる値を持つ「name」という名前のオプション属性を指定できます。

各 key 要素には、1 つまたは複数の field 要素のシーケンスが含まれます。このシーケンス全体で、キーを構成する、単純な値を持つ対象の型フィールドを指定します。キーは、単純 (フィールドが 1 つだけ) または複合(フィールドが複数) のいずれかになります。各 field 要素は、必須の xpath 属性の値によって識別されます (この属性は、「対象の型プロパティ」で説明した xpath 属性と同様に動作します)。

さらに、各 field 要素には、nativeXpath 属性を持つ拡張要素をオプションとして指定できます (この属性は、「ネイティブ プロパティ」で説明した nativeXpath 属性と同様に動作します)。

key 要素定義の例を次に示します。

<key name="CUSTOMER_PK11015727676593">
<field xpath="CUSTOMER_ID">
<extension nativeXpath="CUSTOMER_ID"/>
</field>
</key>

関係プロパティ

オプションの関係プロパティ ブロックによって、関係の対象のセットを指定できます。データ サービスの関係の対象とは、最初のサービスが一方向または両方向の関係を維持するために使用するデータ サービスです。一方向の関係は、最初のデータ サービス内にある 1 つまたは複数の ナビゲート関数を介して実現されます。 このナビゲート関数は、2 番目のサービス対象の型のオブジェクト インスタンスを 1 つまたは複数戻します。両方向の関係では、相反関数が 2 番目のデータ サービスにも存在する必要があります。

関係の対象は relationshipTarget 要素で表されます。 この要素には、表 6-9 に説明する属性を指定できます。

表 6-9 relationshipTarget 要素の属性
属性
説明
roleName
データ サービス内部にある関係の対象を一意に識別する文字列。
roleNumber
(省略可能) 1 または 2 (デフォルト値は 1)。roleNumber は、関係内にある関係の対象のインデックスを指定する。
XDS
関係の対象として機能するデータ サービスの AquaLogic Data Services Platform URI。
minOccurs
(省略可能) この関係に参加する関係の対象のインスタンスにおける最小カーディナリティ。有効値は、負以外の整数と空の文字列。デフォルト値は空の文字列。
maxOccurs
(省略可能) この関係に参加する関係の対象のインスタンスにおける最大カーディナリティ。有効値は、すべての正の整数、バインドされていない文字列、および空の文字列。デフォルト値は空の文字列。
opposite
(省略可能) 両方向の関係の場合、相互関係の対象を示す文字列属性。この属性の値は、XDS 属性の値によって識別されるデータ サービス内の関係の対象としてこのデータ サービスを識別するために使用される識別子。

さらに、relationshipTarget 要素そのものに relationship 要素を指定し、その中で、ネストした description 要素によって関係についての人間が読み取り可能な説明を指定することができます。

relationshipTarget 要素定義の例を次に示します。

<relationshipTarget roleName="CUSTOMER_ORDER" roleNumber="2"
XDS="ld:oracleDS/CUSTOMER_ORDER.xds" minOccurs="0"
maxOccurs="unbounded" opposite="CUSTOMER"/>

更新プロパティ

オプションの更新プロパティ ブロックによって、データ サービスの基になるソースの更新について特定のポリシを設定するプロパティのセットを指定できます。特に、以下のポリシを指定できます。

更新分解のための関数

データ サービス読み取り関数を使用して取得したデータを SOD オブジェクトとして公開し、後で更新することができます。変更が元のデータ ソース内で維持されるようにするため、データ サービスはデータ系統解析の実行に使用される読み取り関数を指定する必要があります。この解析で作成されるプランによって、更新を、基になる各ソースに適用可能なサブプランに分解できます。この機能は主に論理データ サービスで使用されます。

更新分解の関数は functionForDecomposition 要素によって表されます。 この要素には、表 6-10 に説明する必須属性を指定できます。

表 6-10 functionForDecomposition 要素の必須属性
属性
説明
name
更新分解に使用する読み取り関数の修飾名
arity
name 属性で指定した読み取りのパラメータ数

functionForDecomposition 要素が指定されていない場合、データ サービス ドキュメント内の最初の読み取り関数が更新分解関数として指定されます。

functionForDecomposition 要素定義の例を次に示します。

<functionForDecomposition xmlns:f="ld:view/myView"
name="f:firstNameFilter" arity="0"/>

Java 更新終了

自動的に更新できないデータ ソース データ サービス (すべての非リレーショナル XDS)、またはデータビュー XDS では、更新に使用する外部関数を指定することできます。サポートされる外部メカニズムには、SDO 更新仕様で指定されている特別のインターフェースを実装する Java クラスが組み込まれています。

更新終了点として使用する Java クラスは、空の javaUpdateExit 要素によって表されます。この要素には、表 6-11 で説明する属性を指定できます。

表 6-11 javaUpdateExit 要素の属性
属性
説明
className
Java クラスの完全修飾名
classFile
(省略可能) クラスの Java ファイルへの LD URI

functionForDecomposition 要素定義の例を次に示します。

<javaUpdateExit className="com.example.Exit"/> 

オプティミスティック ロック フィールド

SDO 更新は、オプティミスティック ロック トランザクションのセマンティクスを前提としています。更新中のデータ サービスでは、空の optimisticLockingFields 要素を使用して、途中で更新があるかどうかをチェックするフィールドを指定できます。空の optimisticLockingFields 要素の中には、以下のいずれかを指定できます。

functionForDecomposition 要素定義の例を次に示します。

<optimisticLockingFields>
<updated/>
</optimisticLockingFields>

読み取り専用データ サービス

データ サービスは読み取り専用として指定できます。 この場合、サービスの読み取り関数から取得した結果に対する更新はできません。空の readOnly 要素を使用すると、データ サービスを読み取り専用として指定できます。例えば、次のように指定します。

<readOnly/>

セキュリティ プロパティ

データ サービスを使用して、ユーザ定義による保護される論理リソースを 1 つまたは複数定義できます。このために、文字列値を持つ secureResource という名前の要素が 1 つまたは複数含まれる secureResources 要素を使用できます。

例えば、次のように指定します。

<secureResources>
<secureResource>MyResource</secureResource/>
<secureResource>MyOtherResource</secureResource/>
</secureResources>

この構文を使用して定義した論理リソースを、AquaLogic Data Services Console を使用してユーザ定義のセキュリティ ポリシにリンクできます。クエリ コンテンツによって、ユーザが組み込みの isAccessAllowed() 関数を使用して論理リソースにアクセスできるかどうかを照会できます。

 


関数アノテーション

データ サービスまたは XFL 関数ごとに 1 つの関数アノテーションがあり、ドキュメント内では関数宣言よりも前に現れます。関数アノテーションを持つプラグマの識別子は function です。XDS または XFL アノテーションに対応する、XML フラグメントの最上位レベルにある要素の修飾名には、ローカル名関数とネームスペース URI urn:annotations.ld.bea.com が含まれます。

各データ サービス関数は、次のいずれかのカテゴリに分類されます。

データ サービス関数の分類は、関数要素内の必須属性の値の種類によって決まります。この中には、read、navigate、private、hasSideEffects のいずれかの値を指定して、対応するカテゴリを示します。各 XFL 関数はライブラリ関数と見なされます。

読み取り関数において戻り値の型のうちプライマリの型は、データ サービスの対象の型と一致する必要があります。また、ナビゲート関数の関数要素には文字列値属性の戻り値を保持し、その値はデータ サービス内に定義された関係の対象のロール名と一致する必要があります。さらに、ナビゲート関数において戻り値の型のうちプライマリの型は、関係の対象として機能するデータ サービスの対象の型と一致する必要があります。

プライベート関数は、関数が定義されているデータ サービスによってのみ使用できます。

プロシージャとして指定された関数には、一般的に副作用があります。つまり、関数を呼び出すと、影響されるデータ ソースの状態が更新されてしまいます。このため、プロシージャを直接呼び出す可能性があるのは、AquaLogic Data Services Platform メディエータ クライアントのみです。特に、プロシージャは、他の AquaLogic Data Services Platform 関数またはアドホック クエリから参照できません。

リレーショナル データベース XFL ファイル内のライブラリ関数は常に外部関数です。クライアントから直接呼び出すことはできません。代わりに、他のデータ サービス関数または アドホック クエリによって参照する必要があります。

さらに、データ サービスまたは XFL 内の全関数の修飾名のネームスペース URI では、LD リポジトリ内のデータ サービスまたは XFL ドキュメントの場所を位置を指定する必要があります。例えば、次のように指定します。

ld:{データ サービス フォルダへのディレクトリ パス} / {拡張子なしのデータ サービス ファイル名}

または

lib:{XFL フォルダへのディレクトリ パス} / {拡張子なしの XFL ファイル名}

function 要素には、表 6-12 で説明する追加のオプション属性を指定できます。

表 6-12 function 要素のオプション属性
属性
説明
nativeName
データ ソース関数に適用可能。nativeName は外部ソースに認識されている関数名。例えば、リレーショナル ソースの場合、テーブル名に相当する。
nativeLevel1Container
階層包含スキームを採用している外部ソースを表すデータソース関数に適用可能。nativeLevel1Container は、外部ソースに認識されている最上位レベルのネイティブ コンテナの名前。
例えば、リレーショナル ソースの場合、カタログ名に相当する。一方、Web サービス ソースの場合、サービス名に相当する。
nativeLevel2Container
階層包含方式を採用している外部ソースを表すデータソース関数に適用可能。nativeLevel2Container は、外部ソースに認識されている第 2 レベルのネイティブ コンテナの名前。例えば、リレーショナル ソースの場合、スキーマ名に相当する。Web サービス ソースの場合、ポート名に相当する。
nativeLevel3Container
階層包含方式を採用している外部ソースを表すデータソース関数に適用可能。nativeLevel3Container は、外部ソースに認識されている最上位レベルのネイティブ コンテナの名前。例えば、リレーショナル ソースの場合、ストアド プロシージャ パッケージ名に相当する。
style
データ ソース関数に適用可能。style は、外部ソース (リレーショナル ソースではテーブル、ビュー、storedProcedure、または sqlQuery。Web サービスでは rpc または ドキュメント)が関数を認識するために使用するネイティブな修飾子。
roleName
ナビゲート関数に適用可能。roleName は関数によって実装される関係の対象の roleName 属性の値と一致する必要がある。

最上位レベルの関数要素には、以下のプロパティ ブロックのシーケンスが含まれます。

関数アノテーションの例を次に示します。

(::pragma function <f:function xmlns:f="urn:annotations.ld.bea.com" kind="read" nativeName="CUSTOMER" nativeLevel2Container="RTL" style="table">
<nonCacheable/>
</f:function>::)

標準プロパティ

「標準ドキュメント プロパティ」および「ユーザ定義プロパティ」 で定義した標準ドキュメント プロパティおよびユーザ定義プロパティのすべてが関数アノテーションに適用できます。

UI プロパティ

ユーザ インタフェース プロパティのセットが、式を表すグラフィカル コンポーネントに関する場所情報を関数の本文内に保持するために、XQuery エディタによって追加される場合があります。UI プロパティは uiProperties 要素によって表されます。 この要素の中には、component という名前の 1 つまたは複数の要素からなるシーケンスを指定できます。各 component 要素には、表 6-13 で説明する属性を指定できます。

表 6-13 component 要素の属性
属性
説明
identifier
UI コンポーネントの識別子
minimized
UI コンポーネントが最小化されたかどうかを示すブール フラグ
x
UI コンポーネントの X 座標
y
UI コンポーネントの Y 座標
w
UI コンポーネントの幅
h
UI コンポーネントの高さ
viewPosX
コンポーネントのスクロールバー位置の X 座標
viewPosY
コンポーネントのスクロールバー位置の Y 座標

さらに、各 component 要素には、コンポーネントに関係するタイプのツリー表示に関する情報が指定された 1 つまたは複数の treeInfo 要素がオプションで含まれる場合があります。上記プロパティが指定されていない場合、クエリ エディタはデフォルト レイアウトを使用します。

キャッシュ プロパティ

オプションのキャッシュ プロパティ ブロックを使用して、関数がキャッシュできるかどうかを指定できます。同じ引数のセットに対する関数の結果の揮発性が本質的に高い場合、その関数をキャッシュ対象外として指定する必要があります。一方、同じ引数のセットに対する関数の結果が固定か、または一定期間変化しない場合、その関数はキャッシュ可能として指定する必要があります。

関数のこうしたプロパティは、空の nonCacheable 要素で表されます。nonCacheable 要素が指定されていない場合、関数は潜在的にキャッシュ可能であると見なされます。次に例を示します。

<nonCacheable/>

動作プロパティ

オプションの動作プロパティ ブロックによって、関数の入力と出力の間、または複数の関数間の既知の関連付けに関する情報を提供することができます。特に、以下を指定できます。

逆関数

XQuery 関数 f があるとして、オプションの逆関数ブロックが、関数 g を示すために使用される場合があります。この関数は、f の範囲に対して定義され、f と組み合わせると (つまり、g(f))、fのパラメータの 1 つを示します。f に複数のパラメータがある場合、パラメータごとに逆関数が定義される場合があります。

逆関数ブロックは、inverseFunctions という名前のオプション要素によって表されます。この要素の中に、inverseFunction という名前の空の要素のシーケンスを指定できます。各 inverseFunction 要素には以下の属性を指定できます。

注意 : アノテーションを付けた関数と逆関数はどちらも組み込み関数か外部 XQuery 関数でなければなりません。

inverseFunctions 要素定義の例を次に示します。

<inverseFunctions>
  <inverseFunction parameterIndex="2" name="p:MyInverse" xmlns:p="urn:test"/>
</inverseFunctions>

等価変換

XQuery 関数 f があるとして、オプションの等価変換ブロックが、同じシグネチャとセマンティクスを持ち、パラメータの 1 つとして f を指定可能な関数 CC' のペアを表すために使用される場合があります。簡単に言うと、等価性は、C(...,f,...) の各出例が C'(...,f,...) によって安全に代替できるという意味であると解釈されます。

等価変換ブロックは、equivalentTransforms という名前のオプション要素によって表されます。この要素の中には、空の pair という名前の要素のシーケンスを指定できます。各 pair 要素には次のような必須属性を指定できます。

注意 : ソース変換は、組み込み関数または外部関数のどちらかである場合があります。ソース変換とターゲット変換はどちらも逆関数として定義してはいけません。

equivalentTransforms 要素定義の例を次に示します。

<equivalentTransforms>
 <pair source="p:sourceFunction_1" target="p:targetFunction_1"   arity="1" xmlns:p="urn:test1"/>
 <pair source="q:sourceFunction_2" target="q:targetFunction_2"   arity="3" xmlns:q="urn:test2"/>
</equivalentTransforms>

多相関数

リレーショナル データベース XFL にあるライブラリ関数は、実際の戻り値の型がいずれかのパラメータの実際の型から判断できる場合には、多相と指定される場合があります。多相関数は、isPolymorphic という名前のオプション要素によって示されます。 この要素の中には、 parameter という名前の空の要素を指定できます。parameter 要素には、以下のオプション属性を指定できます。

equivalentTransforms 要素定義の例を次に示します。

<sPolymorphic>
     <parameter index = "2"/>
</sPolymorphic>

シグネチャ プロパティ

オプションのシグネチャ プロパティ ブロックを使用し、関数シグネチャが提供する追加情報でデータ サービスまたは XFL 関数のパラメータにアノテーションを付けることができます。こうしたプロパティは、データ ソース (データ サービスまたは XFL) 関数に適用されます。

シグネチャ プロパティ ブロックは、params 要素によって表されます。この要素の中には、1 つまたは複数の param という名前の要素のシーケンスを指定できます。各 param 要素は、空の要素であり、表 6-14 に説明するオプション属性を指定できます。

表 6-14 param 要素のオプション属性
属性
説明
name
外部ソースに認識されているパラメータの名前
nativeType
外部ソースに認識されているパラメータのネイティブ タイプ
nativeTypeCode
外部ソースに認識されているパラメータのネイティブ タイプ コード
xqueryType
パラメータに使用される XML スキーマまたは XQuery タイプの修飾名
kind
unknown、in、inout、out、return、result のいずれかの値 (ストアド プロシージャに適用可能)。

params 要素定義の例を次に示します。

<params>
<param nativeType="java.lang.String"/>
<param nativeType="java.lang.int"/>
</params>

ネイティブ プロパティ

ネイティブ プロパティを使用して、データ ソース関数が表す外部ソースのタイプに基づいて、そのデータ ソース関数にアノテーションを追加することができます。ネイティブ プロパティには、それぞれがリレーショナルまたは Web サービス ソースに関する 2 つの種類があります。

SQL クエリ プロパティ

関数のアノテーション要素 function は、ユーザ定義 SQL クエリを表します。 また、sqlQuery に設定された style 属性を持ち、「sql」という名前のネストした要素を指定できます。sql 要素の中には、関数が表す (おそらくパラメータ化されている) SQL クエリのステートメントに対応する文字列を指定できます。

必要ならば、ステートメントを CDATA セクション内でエスケープし、予約済み XML 文字 (<、>、& など) を無効にすることができます。sql 要素にはまた、オプションの isSubquery 属性を指定できます。これはブール値で、SQL ステートメントをネストされた SQL サブ クエリとして使用できるかどうかを示します。属性が指定されていない場合、デフォルト値は true です。

sqlQuery 要素定義の例を次に示します。

<sql isSubquery="true">
SELECT t.FIRST_NAME FROM RTLALL.dbo.CUSTOMER t</sql>

SOAP ハンドラ プロパティ

Web サービス呼び出しを表す関数の function アノテーション要素には、interceptorConfiguration という名前のネストされた要素を指定できます。interceptorConfiguration 要素には、表 6-15 に説明する 2 つの必須属性を指定できます。

表 6-15 interceptorConfiguration 要素の必須属性
属性
説明
fileName
Web サービスに適用可能な SOAP ハンドラ チェーンのコンフィグレーションを含むファイルの場所
aliasName
SOAP ハンドラ チェーンの設定に使用されているエリアス名

 


XFL アノテーション

XFL ドキュメントごとに 1 つの XFL アノテーションがあります。これはドキュメント内のどの関数アノテーションよりも前に現れます。XFL アノテーションを持つプラグマの識別子は「xfl」です。XFL アノテーションに対応する、XML フラグメントの最上位レベルにある要素の修飾名には、ローカル名 xfl とネームスペース URI urn:annotations.ld.bea.com が含まれます。

最上位レベルの xfl 要素の中には、以下のようなプロパティ ブロックのシーケンスが含まれています。

以降の節では、プロパティの各ブロックについて詳細に説明します。また、参考として以下に XFL アノテーションの例を示します。

(::pragma xfl <x:xfl xmlns:x="urn:annotations.ld.bea.com">
<creationDate>2005-03-09T17:48:58</creationDate>
<webService targetNamespace="urn:GoogleSearch"
wsdl="ld:google/GoogleSearch.wsdl"/>
</x:xfl>::)

標準プロパティ

XFL ドキュメントに適用可能な標準プロパティは、「標準プロパティ」 で説明したデータ サービス ドキュメントの標準プロパティと同じです。

データ アクセス プロパティ

各 XFL ドキュメントでは、1 つまたは複数 のXQuery 関数を定義します。 この関数は、データ サービス ドキュメント内で読み取り、ナビゲート、またはプライベート関数を定義するか、または他の XFL ドキュメント内で他のライブラリ関数を指定するために使用可能なライブラリ関数として機能します。

XFL ドキュメントは対象の型を持たないため、これらのドキュメント内にあるライブラリ関数の戻り値の型はそれぞれ異なる場合があります。特に、XFL ドキュメント内の関数は、単純型 (または他の任意の型) を持つ値を戻す場合があります。XFL 関数は、外部データ ソース関数またはユーザ定義関数である場合があります。

以下のようなタイプの XFL ドキュメントがサポートされています。

各 XFL 内に指定できるアノテーションは 1 つだけです。アノテーションが指定されていない場合、XFL はユーザ定義ビューと見なされます。

リレーショナル、Web サービス、Java 関数、およびユーザ定義ビューの XFL ドキュメントのデータ アクセス プロパティは、上記のようなデータ サービス ドキュメントの対応するプロパティと同じです。

リレーショナル データベース関数 XFL にはネイティブ関数が含まれています。このネイティブ関数は、1 つまたは複数のリレーショナル データ ソースから、データベース内にベンダが提供したか、またはユーザが定義したもので、外部 XQuery 関数としてモデル化されています。

リレーショナルデ ータベース XFL のデータ アクセス アノテーションは、customNativeFunctions という名前の要素と、relational という名前を持つ 1 つの子要素で構成されています。 子要素の中には、dataSource という名前の 1 つまたは複数の要素のシーケンスが含まれます。各 dataSource 要素には、1 つのテキスト値が含まれています。これには、外部リレーショナル データ ソースがアプリケーション サーバに登録されるときに使用する JNDI 名を設定する必要があります。

以下に例を示します。

<customNativeFunctions>
<relational>
<dataSource>oracleDS1</dataSource>
<dataSource>oracleDS2</dataSource>
</relational>
</customNativeFunctions>

  Back to Top       Previous  Next