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

9.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は、検索メソッドのパラメタの１番目を意味します。
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	×	○	検索条件に指定した値の余剰を求めます。

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

■ EJB QL基本

　EJB QL基本ではSELECT句、FROM句、WHERE句を使用したデータ操作ができます。また、データを編集して返却する演算子が使用できます。

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

【使用例】

　演算子を使用したEJB QL文の例です。

• SELECT句
  • 例1）単純なEJB QL文
  • 例2）パス式を使用したEJB QL文
• WHERE句
  • 例1）リテラルを使用したEJB QL文
  • 例2）パラメタを使用したEJB QL文
  • 例3）比較式を使用したEJB QL文
  • 例4）BETWEEN式演算子を使用したEJB QL文
  • 例5）NULL比較式を使用したEJB QL文

SELECT句

• 例1）単純なEJB QL文

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

  SELECT OBJECT(c) FROM Customer AS c

  すべてのCustomerのCollectionを返します。

• 例2）パス式を使用したEJB QL文

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

  SELECT c.lastName FROM Customer AS c

  全Customerの姓の、Collectionを返します。

WHERE句

　FROM句で検索された値に対しWHERE句を使用して、いろいろな条件テストが指定できます。

• 例1）リテラルを使用したEJB QL文

  WHERE句で指定されたリテラル（定数）に一致するBeanを検索するためのEJB QLの記述です。指定したリテラルが文字列リテラルの場合は、シングルクォーテーション（‘）で囲みます。以下のEJB QLの例では名前がFujitsuであるCustomerを検索するEJB QLの記述です。

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

  'Fujitsu'という名前のCustomerを返します。

  【留意事項】

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

• 例2）パラメタを使用したEJB QL文

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

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

  パラメタに指定された名前のCustomer Collectionを返します。

• 例3）比較式を使用したEJB QL文

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

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

  【留意事項】

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

• 例4）BETWEEN式を使用したEJB QL文

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

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

  idが100〜200のCustomerのCollectionを返します。

  【留意事項】

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

• 例5）NULL比較式を使用したEJB QL文

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

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

  年齢情報があるCustomerのCollectionを返します。

■ 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文

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

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

  【留意事項】

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

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

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

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

  【留意事項】

  • 集合関数は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文

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

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

  【留意事項】

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

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

  LIKE式の使用方法はSQLと同様です。以下の例では、名前がパターン('Fujitsu_'から始まる)文字列に合致するCustomerを検索するEJB QLの例を記述します。

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

  パターン文字列は'Fujitsu\_'を指定します。また、エスケープ文字は'\'を指定します。

  【留意事項】

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

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

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

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

  【留意事項】

  • 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式の左辺および右辺に指定するデータ型は、同じデータ型を指定してください。

　使用するDBMSがSymfowareの場合、以下に注意してください。

• SQRT関数、MOD関数は使用できません。
• LOCATE関数の第三引数は指定できません。
• LENGTH関数に、入力パラメタを指定することはできません。
• SUBSTRING関数の第一引数に、入力パラメタを指定することはできません。
• NULL比較式に、入力パラメタを指定することはできません。

　使用するDBMSがPostgreSQLの場合、以下に注意してください。

• LOCATE関数の第三引数は指定できません。
• LIKE述語のエスケープ文字に、“\”の指定はできません。