式言語 

SQL ディレクティブで簡単な式を書くことができます。文法はJavaに非常に似ていますが、すべてのJavaの機能がサポートされているわけではありません。

注釈

オプション型 (例: java.util.Optional) の扱いには重要な違いがあります。式の中では、Optional 型の値はその要素型の値に自動的に変換されます。例えば、Optional<String> の値は String として扱われます。その結果、Optional オブジェクト自体のメソッドを呼び出すことはできず、また、Optional パラメータを取るメソッドを呼び出すこともできません。

オプションの値が存在するかどうかを確認する場合は、/*%if optional.isPresent() */ ではなく、/*%if optional != null */ を使用してください。

この挙動は、java.util.OptionalInt、java.util.OptionalDouble、および java.util.OptionalLong を含むすべてのオプショナル型に適用されます。

リテラル 

次のリテラルを使用できます。

リテラル	型
null	void
true	boolean
false	boolean
10	int
10L	long
0.123F	float
0.123D	double
0.123B	java.math.BigDecimal
'a'	char
"a"	java.lang.String

数値の種類は、リテラルの末尾にある L や F などの接尾辞によって区別されます。接尾辞は大文字である必要があります。

select * from employee where
/*%if employeeName != null && employeeName.length() > 10 */
    employee_name = /* employeeName */'smith'
/*%end*/

比較演算子 

次の比較演算子を使用できます。

演算子	説明
==	等値演算子
!=	不等値演算子
<	小なり演算子
<=	小なりイコール演算子
>	大なり演算子
>=	大なりイコール演算子

比較演算子を使用するには、被演算子で java.lang.Comparable を実装する必要があります。

<, <=, >, >= の被演算子は null であってはなりません。

select * from employee where
/*%if employeeName.indexOf("s") > -1 */
    employee_name = /* employeeName */'smith'
/*%end*/

論理演算子 

次の論理演算子を使用できます。

演算子	説明
!	論理否定演算子
&&	論理積演算子
\|\|	論理和演算子

括弧を使用して、演算子の優先順位を制御できます。

select * from employee where
/*%if (departmentId == null || managerId == null) and employee_name != null */
    employee_name = /* employeeName */'smith'
/*%end*/

算術演算子 

次の算術演算子を使用できます。

演算子	説明
+	加法演算子
-	減算演算子
*	乗算演算子
/	除算演算子
%	剰余演算子

すべてのオペランドは数値型でなければなりません。

select * from employee where
    salary = /* salary + 1000 */0

文字列連結演算子 

連結演算子 + を使用して文字列を連結できます。

被演算子は次のいずれかのタイプである必要があります。

java.lang.String
java.lang.Character
char

select * from employee where
   employee_name like /* employeeName + "_" */'smith'

インスタンスメソッドの呼び出し 

インスタンスメソッドはドット表記（.）を使用して呼び出すことができます。呼び出されたメソッドは公開されている必要があります。

select * from employee where
/*%if employeeName.startsWith("s") */
    employee_name = /* employeeName */'smith'
/*%end*/

メソッドに引数がない場合は、メソッド名の後に () を指定します。

select * from employee where
/*%if employeeName.length() > 10 */
    employee_name = /* employeeName */'smith'
/*%end*/

インスタンスフィールドへのアクセス 

インスタンスフィールドにはドット記法 (.) を使用してアクセスできます。フィールドは、その可視性に関係なく、プライベートであってもアクセス可能です。

select * from employee where
    employee_name = /* employee.employeeName */'smith'

静的メソッドの呼び出し 

静的メソッドを呼び出すには、 @ で囲んだ完全修飾クラス名をメソッド名に続けます。メソッドの可視性はパブリックである必要があります。

select * from employee where
/*%if @java.util.regex.Pattern@matches("^[a-z]*$", employeeName) */
    employee_name = /* employeeName */'smith'
/*%end*/

静的フィールドへのアクセス 

静的フィールドにアクセスするには、フィールド名に @ で囲まれた完全修飾クラス名を添えます。可視性に関係なく、仮にそれが非公開であってもアクセスできます。

select * from employee where
/*%if employeeName.length() < @java.lang.Byte@MAX_VALUE */
  employee_name = /* employeeName */'smith'
/*%end*/

組み込み関数の使用 

組み込み関数は、主に SQL にバインドする前にバインド変数の値を変更するためのユーティリティです。

たとえば、LIKE 句を使用して前方検索を実行する場合は、次のように記述できます。

select * from employee where
    employee_name like /* @prefix(employee.employeeName) */'smith' escape '$'

@prefix(employee.employeeName) は、 employee.employeeName の値を @prefix 関数に渡します。この関数は受け取った文字列を前方一致検索に適した文字列に変換し、特殊文字をエスケープします。例えば、employee.employeeName の値が ABC の場合、これは ABC% に変換されます。employee.employeeName の値に % が含まれている場合、例え AB%C のように、% はデフォルトのエスケープシーケンス $ によってエスケープされ、そのため値は AB$%C% に変換されます。

次の関数シグネチャを使用できます。

String @escape(CharSequence text, char escapeChar = '$'): LIKE 操作の文字シーケンスをエスケープします。戻り値は文字列をエスケープした結果の文字列です。 escapeChar が指定されていない場合、デフォルトのエスケープシーケンスとして $ が使用されます。パラメータとして null を渡すと null を返します。
String @prefix(CharSequence prefix, char escapeChar = '$'): 前方一致検索用の文字列へ変換します。戻り値は、文字シーケンスをエスケープし、末尾にワイルドカード文字を追加した結果の文字列です。 escapeChar が指定されていない場合、デフォルトのエスケープシーケンスとして $ が使用されます。パラメータとして null を渡すと null を返します。
String @infix(CharSequence infix, char escapeChar = '$'): 中置検索用の文字列へ変換します。戻り値は、文字シーケンスをエスケープし、先頭と末尾にワイルドカード文字を追加した結果の文字列です。 escapeChar が指定されていない場合、デフォルトのエスケープシーケンスとして $ が使用されます。パラメータとして null を渡すと null を返します。
String @suffix(CharSequence suffix, char escapeChar = '$'): 接尾辞検索用の文字列へ変換します。戻り値は、文字シーケンスをエスケープし、先頭にワイルドカード文字を追加した結果の文字列です。 escapeChar が指定されていない場合、デフォルトのエスケープシーケンスとして $ が使用されます。パラメータとして null を渡すと null を返します。
java.util.Date @roundDownTimePart(java.util.Date date): 時刻部分を切り捨てます。戻り値は、時刻部分を切り捨てた新しい日付です。パラメータとして null を渡すと null を返します。
java.sql.Date @roundDownTimePart(java.sql.Date date): 時刻部分を切り捨てます。戻り値は、時刻部分を切り捨てた新しい日付です。パラメータとして null を渡すと null を返します。
java.sql.Timestamp @roundDownTimePart(java.sql.Timestamp timestamp): 時刻部分を切り捨てます。戻り値は、時刻部分を切り捨てた新しいタイムスタンプです。パラメータとして null を渡すと null を返します。
java.time.LocalDateTime @roundDownTimePart(java.time.LocalDateTime localDateTime): 時刻部分を切り捨てます。戻り値は、時刻部分を切り捨てた新しい LocalDateTime です。パラメータとして null を渡すと null を返します。
java.util.Date @roundUpTimePart(java.util.Date date): 時刻部分を切り上げます。戻り値は、時刻部分を切り上げた新しい日付です。パラメータとして null を渡すと null を返します。
java.sql.Date @roundUpTimePart(java.sql.Date date): 時刻部分を切り上げます。戻り値は、時刻部分を切り上げた新しい日付です。パラメータとして null を渡すと null を返します。
java.sql.Timestamp @roundUpTimePart(java.sql.Timestamp timestamp): 時刻部分を切り上げます。戻り値は、時刻部分を切り上げた新しいタイムスタンプです。パラメータとして null を渡すと null を返します。
java.time.LocalDateTime @roundUpTimePart(java.time.LocalDateTime localDateTime): 時間部分を切り上げます。戻り値は、時刻部分を切り上げた新しい LocalDateTime です。パラメータとして null を渡すと null を返します。
java.time.LocalDate @roundUpTimePart(java.time.LocalDate localDate): 翌日返却。戻り値は、引数の次の新しい LocalDate です。パラメータとして null を渡すと null を返します。
boolean @isEmpty(CharSequence charSequence): 文字シーケンスが null または長さが 0 の場合は true を返します。
boolean @isNotEmpty(CharSequence charSequence): 文字シーケンスが null でなく、長さが 0 でない場合は true を返します。
boolean @isBlank(CharSequence charSequence): 文字シーケンスが null であるか、長さが 0 であるか、または文字シーケンスが空白のみで形成されている場合にのみ true を返します。
boolean @isNotBlank(CharSequence charSequence): 文字列が null でなく、長さが 0 でなく、文字列が空白だけで形成されていない場合は true を返します。

これらの関数は org.seasar.doma.expr.ExpressionFunctions のメソッドに対応します。

カスタム関数の使用 

独自の関数を定義して使用できます。

定義したカスタム関数を利用するには、次の手順に従います。

関数はorg.seasar.doma.expr.ExpressionFunctionsを実装するクラスのメソッドとして定義します。
このメソッドはパブリックインスタンスメソッドである必要があります。
アノテーション処理設定でクラスをオプションとして登録します。オプションキーには doma.expr.functions を使用してください。
構成クラス内でRDBMS方言のクラスのインスタンスを使用します（Doma の RDBMS 方言の実装は、コンストラクタに ExpressionFunctions パラメータを受け入れます）。

カスタム関数を呼び出す場合は、組み込み関数と同様に関数名の先頭に @ を付けます。たとえば、次のように myfunc 関数を呼び出すことができます。

select * from employee where
    employee_name = /* @myfunc(employee.employeeName) */'smith'