式言語 

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) は、@prefix 関数に 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 をキーとしてアノテーションプロセッシングのオプションに指定される
作成したクラスのインスタンスは SQLダイアレクトで使用される (Doma によって提供されるダイアレクトの実装はコンストラクタで ExpressionFunctions を受け取ることができる)

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

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