Interstage Application Server/Interstage Web Server J2EE ユーザーズガイド

10.2.7 EJB QL

　EJB QLとは、finderメソッドまたはejbSelectメソッドなど検索メソッドのクエリ文を定義するためのSQL92ベースの言語です。
　一般的に使用するSQLとの最大の違いは、SELECT型にEntity Beanの識別子だけが単独で指定されている場合に指定するOBJECTキーワードです。

　EJB QLは抽象スキーマ名に基づいて記述されるので、特定のデータベースに依存しない互換性があります。抽象スキーマ名は、CMP/CMRフィールドに並んで抽象永続スキーマを構成する重要な構成要素です。
　注) 抽象スキーマ名は、ejb-jar内で一意になるようにしてください。

　EJB QLを使用するには、deployment descriptor内の<query>タグにEJB QL文を記述します。
　EJBアプリケーションのdeployment descriptorの情報が定義されているファイル(ejb-jar.xml)は、XML形式で記述する必要があります。このため、ejb-jar.xmlを編集する場合は、XML形式の仕様に従ってください。
　特に以下の文字については、定義済み実体参照(暗黙定義エンティティ)で記述してください。
　EJB QLが使用できるのは、CMP2.0のEntity Beanです。

ejb-jar.xmlを編集する場合

編集する文字	定義済み実体参照
<	&lt;
>	&gt;
&	&amp;
'	&apos;
"	&quot;

　EJB QLでは、EJB規約に準拠した以下が使用できます。

• EJB2.0で規定しているEJB QL(EJB QL基本)
• EJB2.1で規定しているEJB QL(EJB QL拡張)

　EJB QL文とは、SELECT句、FROM句、WHERE句を使用して1つまたは複数のEJBオブジェクトを検索するクエリ文であり、SELECT句とFROM句の定義は必須です。このEJB QL文はコンテナによって解析され、適切なデータベースクエリ言語に翻訳されます。

• SELECT句

  返却値の値としてOBJECT(Entity Bean)、またはパス式を使ってCMF、CMRフィールドを指定します。

• FROM句

  EJBアプリケーションのクラス名ではなく、Entity Bean内に記述された一意の“抽象スキーマ名”を指定します。

• WHERE句

  検索条件の指定を行います。例えば ?1は、検索メソッドのパラメタの1番目を意味します。
  Entity Beanの検索メソッドにはfinderメソッド、またはejbSelectメソッドがあります。それぞれの検索メソッドにおいてメソッド名、パラメタの型を指定してください。
  また、メソッドの返却値の型をマッピングするために、結果のタイプにLocalまたはRemote要素を指定します。デフォルト値はLocalです。

　EJB QLおよびEJB QL拡張で使用できる機能は、以下です。

EJB QL構文			基本	拡張	説明
データ操作文	SELECT句		○	○	クエリに返却するオブジェクトまたは値を指定します。
	FROM句		○	○	SELECT句およびWHERE句内で指定した値の取得場所を指定します。
	WHERE句		○	○	クエリによって返却される値を制限するための条件を指定します。
	ORDER BY句		×	○	クエリによって返却される結果をソートします。
SELECT句の返却値	パス式(CMF/CMR)		○	○	単一またはコレクションの値を持つ式です。
	OBJECT(Entity Bean)		○	○	SELECT句にEntity Beanの識別子だけが単独で指定されている場合に指定します。
	集合関数	MAX	×	○	集合で一番大きな値を返却します。
		MIN	×	○	集合で一番小さな値を返却します。
		SUM	×	○	集合の合計値を返却します。
		AVG	×	○	集合の平均値を返却します。
		COUNT	×	○	集合の要素数を返却します。
条件式	比較式		○	○	指定した2つの値を比較して評価します。
	BETWEEN式		○	○	値が指定した範囲内に含まれるかを評価します。
	LIKE式		○	○	LIKEに続く文字列が合致するかを評価します。
	IN式		○	○	値が含まれているかどうかを評価します。
	NULL比較式		○	○	値がNULL値かを評価します。
	空コレクション比較式 (EMPTY比較式)		○	○	コレクション値を持つパス式が要素をもつかを評価します。
	コレクションメンバ式 (MEMBER式)		○	○	値がコレクションのメンバであるかを評価します。
演算子	ナビゲーション演算子	. (ピリオド)	○	○	関係を辿るシンボルです。
	算術演算子	+ - (単項)	○	○	+ : 指定した値は正の値です。 - : 指定した値は負の値です。
		* / (乗算 除算)	○	○	* : 指定した値を乗算します。 / : 指定した値を除算します。
		+ - (加算 減算)	○	○	+ : 指定した値を加算します。 - : 指定した値を減算します。
	比較演算子	=	○	○	“=”の左辺の値と右辺の値が等しい場合に真となり、等しくない場合に偽となります。
		<>	○	○	“<>”の左辺の値と右辺の値が等しくない場合に真となり、等しい場合に偽となります。
		<	○	○	“<”の左辺の値が右辺の値より小さい場合に真となり、大きいまたは等しい場合に偽となります。
		>	○	○	“>”の左辺の値が右辺の値より大きい場合に真となり、小さいまたは等しい場合に偽となります。
		<=	○	○	“<=”の左辺の値が右辺の値より小さいまたは等しい場合に真となり、大きい場合に偽となります。
		>=	○	○	“>=”の左辺の値が右辺の値より大きいまたは等しい場合に真となり、小さい場合に偽となります。
	論理演算子	NOT	○	○	“NOT”に導かれる式が真の場合に偽となり、偽の場合には真となります。
		AND	○	○	“AND”の左辺および右辺が真の場合に真となり、そうでない場合には偽となります。
		OR	○	○	“OR”の左辺または右辺のいずれかが真の場合に真となり、左辺および右辺が偽の場合には偽となります。
関数式	文字列式	CONCAT	○	○	引数で与えられた文字列を結合した値を求めます。
		SUBSTRING	○	○	指定した文字列の部分列を求めます。
		LOCATE	○	○	条件に指定した文字列の位置を求めます。
		LENGTH	○	○	文字数またはバイト数を求めます。
	算術式	ABS	○	○	引数に指定した値に対する“絶対値”を求ます。
		SQRT	○	○	検索条件に指定した値の平方根を求めます。
		MOD	×	○	検索条件に指定した値の余剰を求めます。

　○：指定可能　　×：指定不可

• 使用するDBMSがSymfowareの場合、以下に注意してください。
  • SQRT関数、MOD関数は使用できません。
  • LOCATE関数の第三引数は指定できません。
  • LENGTH関数に、入力パラメタを指定することはできません。
  • SUBSTRING関数の第一引数に、入力パラメタを指定することはできません。
  • NULL比較式に、入力パラメタを指定することはできません。
• 使用するDBMSがPostgreSQLの場合、以下に注意してください。
  • LOCATE関数の第三引数は指定できません。
  • LIKE述語のエスケープ文字に、“\”の指定はできません。

■EJB QL基本

　EJB QL基本ではSELECT句、FROM句、WHERE句を使用したデータ操作ができます。また、データを編集して返却する演算子が使用できます。
　より詳細なEJB QLの使用方法については、EJB2.0の規約を参照してください。

　以下に演算子を使用したEJB QL文の例を示します。

• SELECT句
  • 例 SELECT句-1) 単純なEJB QL文
  • 例 SELECT句-2) パス式を使用したEJB QL文
• WHERE句
  FROM句で検索された値に対しWHERE句を使用して、いろいろな条件テストが指定できます。
  • 例 WHERE句-1) リテラルを使用したEJB QL文
  • 例 WHERE句-2) パラメタを使用したEJB QL文
  • 例 WHERE句-3) 比較式を使用したEJB QL文
  • 例 WHERE句-4) BETWEEN式を使用したEJB QL文
  • 例 WHERE句-5) NULL比較式を使用したEJB QL文

例 SELECT句-1) 単純なEJB QL文

SELECT OBJECT(c) FROM Customer AS c

　すべてのCustomerのCollectionを返します。
　WHERE句がなく識別子が抽象スキーマ1つしか使われないもので、上記のEJB QLの例では、Customerという抽象スキーマから検索します。FROM句の後に抽象スキーマ名(Customer)を指定して、ASの後のcはCustomerをあらわす識別子です(ASは省略可)。
　上記のようにSELECT型にEntity Beanの識別子だけが単独で指定されている場合は、OBJECT()演算子が必須です。

例 SELECT句-2) パス式を使用したEJB QL文

SELECT c.lastName FROM Customer AS c

　全Customerの姓の、Collectionを返します。
　Customerという抽象スキーマよりCustomerすべての姓を検索するEJB QLの記述です。この例では、OBJECT()演算子は不要です。
　SELECT句はCMPフィールドまたはCMRフィールドも返却できます。

例 WHERE句-1) リテラルを使用したEJB QL文

SELECT OBJECT(c) FROM Customer AS c
WHERE c.name = 'Fujitsu'

　'Fujitsu'という名前のCustomerを返します。
　WHERE句で指定されたリテラル(定数)に一致するBeanを検索するためのEJB QLの記述です。指定したリテラルが文字列リテラルの場合は、シングルクォーテーション(')で囲みます。上記のは、名前がFujitsuであるCustomerを検索するEJB QLの記述です。

【留意事項】

• EJB QLでは文字列リテラル、数値リテラルおよびboolean型のリテラルが指定できます。
• 日時型など他のデータ型を指定する場合は、リテラルではなくパラメタを使用してください。
• EJBアプリケーションのdeployment descriptorの情報が定義されているファイル(ejb-jar.xml)を直接編集する場合は、“ejb-jar.xmlを編集する場合”を参照して、XML形式の仕様に従った記述をしてください。

例 WHERE句-2) パラメタを使用したEJB QL文

SELECT OBJECT(c) FROM Customer AS c
WHERE c.name = ?1

　パラメタに指定された名前のCustomer Collectionを返します。
　WHERE句の後に指定したパラメタに対して、疑問符(?)とパラメタが最初(1)から数えて何番目になるかを指定します。上記は、Customerという抽象スキーマからパラメタの名前に指定されたCustomerから検索するEJB QLの記述です。

例 WHERE句-3) 比較式を使用したEJB QL文

SELECT OBJECT(c) FROM Customer AS c
WHERE c.age >= 25

　WHERE句では比較式が使用できます。上記の例では比較式(>=)を使用して年齢が25歳以上のCustomerを検索するEJB QLの例を記述します。

【留意事項】

• 左辺にリテラルおよびパラメタの指定はできません。
• 以下のデータ型を比較する場合、左辺および右辺に指定するデータ型は同じ型を指定してください。
  • java.lang.String
  • charまたはjava.lang.Character
  • booleanまたはjava.lang.Boolean
  • java.sql.Date
  • java.sql.Time
  • java.sql.Timestamp
• 以下のデータ型は比較できません。
  • byte配列
  • Serializableオブジェクト

例 WHERE句-4) BETWEEN式を使用したEJB QL文

SELECT OBJECT(c) FROM Customer AS c
WHERE c.id BETWEEN 100 and 200

　idが100〜200のCustomerのCollectionを返します。
　BETWEEN式(NOT BETWEEN)の使用方法は、SQLと同様です。BETWEEN演算子の指定区間について検索できます。例ではIDが100〜200のCustomerを検索するEJB QLです。

【留意事項】

• 以下のデータ型を比較する場合、指定するデータ型は同じデータ型を指定してください。
  • java.lang.String
  • charまたはjava.lang.Character
  • booleanまたはjava.lang.Boolean
  • java.sql.Date
  • java.sql.Time
  • java.sql.Timestamp
• 以下のデータ型は比較できません。
  • byte配列
  • Serializableオブジェクト

例 WHERE句-5) NULL比較式を使用したEJB QL文

SELECT OBJECT(c) FROM Customer AS c
WHERE c.age IS NOT NULL

　年齢情報があるCustomerのCollectionを返します。
　NULL比較式演算子は、NULL値の検索に使用します。例えば年齢がNULL値ではないCustomerを検索するEJB QLは上記のように記述します。

■EJB QL拡張

　EJB QL拡張は、EJB2.0で使用できる機能に加えて以下が拡張されています。

• ORDER BY句の指定ができる
• 関数式MODが指定できる
• LIKE式のパターンに変数が指定できる
• LIKE式のエスケープ文字に変数が指定できる
• NULL比較式に変数が指定できる
• IN式に変数と数値が指定できる
• 集合関数の以下が指定できる
  • MIN、MAX、AVG、SUM、COUNT

　より詳細なEJB QL拡張の使用方法については、EJB2.1の規約を参照してください。

　以下に演算子を使用したEJB QL文の例を示します。

• 例1) ORDER BY句を使用した基本的なEJB QL文
• 例2) 集合関数を使用したEJB QL文
• 例3) 関数式MODを使用したEJB QL文
• 例4) LIKE式を使用したEJB QL文
• 例5) IN式を使用したEJB QL文

例1) ORDER BY句を使用した基本的なEJB QL文

SELECT c.address.city FROM Customer c
ORDER BY c.address.city DESC

　ORDER BY句を使用して値式にCMFを指定すると、検索結果がソートされます。ORDER BY句には昇順「ASC」か、降順「DESC」を指定できます。省略された場合、昇順になります。
　上記の例では、返却される値をc.address.cityの降順で返却します。

【留意事項】

• 以下のデータ型のCMFは指定できません。
  • booleanまたはjava.lang.Boolean
  • byte配列
  • Serializableオブジェクト

例2) 集合関数を使用したEJB QL文

SELECT SUM(c.employeeCount)
FROM Company c WHERE c.type = 'IT'

　集合関数は、値の合計や平均などの集計を行う関数です。
　上記の例では、c.typeが'IT'のものをc.employeeCountの値を合計して返却します。

【留意事項】

• 集合関数はejbSelectメソッドのクエリ文だけに指定可能であり、SELECT句の返却値としてだけ指定できます。
• 集合関数のMAXおよびMINに以下のデータ型は指定できません。
  • booleanまたはjava.lang.Boolean
  • byte配列
  • Serializableオブジェクト
• 集合関数のSUMおよびAVGに以下のデータ型は指定できません。
  • java.lang.String
  • charまたはjava.lang.Character
  • booleanまたはjava.lang.Boolean
  • java.sql.Date
  • java.sql.Time
  • java.sql.Timestamp
  • byte配列
  • Serializableオブジェクト

例3) 関数式MODを使用したEJB QL文

SELECT OBJECT(c) FROM Customer c
WHERE MOD(c.age, 10) = 0

　MODを使用すると剰余を得ることができます。年齢を10で割った余りを返却します。

【留意事項】

• 関数式MODに指定可能なデータ型は以下です。
  • byteまたはjava.lang.Byte
  • shortまたはjava.lang.Short
  • intまたはjava.lang.Integer

例4) LIKE式を使用したEJB QL文

SELECT OBJECT(c) FROM Customer AS c
WHERE c.name LIKE ?1 ESCAPE ?2

　LIKE式の使用方法はSQLと同様です。上記の例では、名前がパターン('Fujitsu_'から始まる)文字列に合致するCustomerを検索するEJB QLの例を記述します。
　パターン文字列は'Fujitsu\_'を指定します。また、エスケープ文字は'\'を指定します。

【留意事項】

• パターン文字列に指定可能なデータ型は以下です。
  • java.lang.String
• エスケープ文字に指定可能なデータ型は以下です。
  • charまたはjava.lang.Character

例5) IN式を使用したEJB QL文

SELECT OBJECT(c) FROM Customer AS c
WHERE c.age IN (?1, ?2, ?3)

　IN式の使用方法は、SQLと同様です。上記の例では年齢がパラメタで指定した値に合致するCustomerを検索するEJB QLの例を記述します。

【留意事項】

• IN式に指定可能なデータ型は以下です。
  • byteまたはjava.lang.Byte
  • shortまたはjava.lang.Short
  • intまたはjava.lang.Integer
  • floatまたはjava.lang.Float
  • doubleまたはjava.lang.Double
  • java.lang.BigDecimal
  • java.lang.String
• IN式の左辺および右辺に指定するデータ型は、同じデータ型を指定してください。