ParameterBeanのプロパティオプション

曖昧検索や日付範囲など、ParameterBeanのプロパティに付けるオプションについてのページです。

ParameterBean

プロパティオプションの概要
プロパティオプションの付け方
LikeSearch条件のオプション
DateFromTo条件のオプション
- DateFromToの基本
- FromToOptionの指定
区分値条件のオプション
参照カラムのオプション
プロパティのコメント
- プロパティ宣言のときのコメント
- プロパティ自動判別のときのコメント
同時に二つ以上のオプションを指定する

プロパティオプションの概要

プロパティのオプションは必須ではありませんが、利用できるものは積極的に利用しましょう。

LikeSearch条件のオプション: :like, :likeContain, :likePrefix, ... ※もしくは自動判別
DateFromTo条件のオプション: :fromDate, :toDate, :fromDate(option), ...
区分値条件のオプション: :ref(MEMBER.MEMBER_STATUS_CODE), ref(MEMBER)
参照カラムのオプション: :ref(MEMBER.MEMBER_STATUS_CODE), ref(MEMBER)
プロパティのコメント: -- !!...!! // ..., :comment(...)

プロパティオプションの付け方

オプションをどこに付けるかは、自動判別か明示的宣言かで大きく分かれます。

自動判別プロパティ: バインド変数コメントに付与 ※一部、テスト値から自動判別
明示的宣言のプロパティ: 宣言部分に付与

いずれにせよ、プロパティ名の後ろに ":" (コロン) を付けて、それに続いて指定します。

e.g. 自動判別の場合のオプション付与 @OutsideSql
-- !df:pmb!
-- !!AutoDetect!!

select ...
  from MEMBER
 where MEMBER_NAME like /*pmb.memberName*/'S%' -- テスト値の "%" の場所で決まる
   and FORMALIZED_DATETIME >= /*pmb.fromFormalizedDate:fromDate*/'2013-10-20'
   and FORMALIZED_DATETIME < /*pmb.toFormalizedDate:toDate*/'2013-11-01'
   and MEMBER_STATUS_CODE = /*pmb.memberStatusCode:ref(MEMBER)*/'WDL'

e.g. 明示的宣言の場合のオプション付与 @OutsideSql
-- !df:pmb!
-- !!String memberId!!                     // プロパティのコメントはここに書く
-- !!String memberName:likeContain!!       // 会員名称で部分一致
-- !!Date fromFormalizedDate:fromDate!!    // 正式会員日時でfrom検索
-- !!Date toFormalizedDate:toDate!!        // 正式会員日時でto検索
-- !!String memberStatusCode:ref(MEMBER)!! // 会員ステータスの等値

select ...
  from MEMBER
 where MEMBER_NAME like /*pmb.memberName*/'S%'
   and FORMALIZED_DATETIME >= /*pmb.fromFormalizedDate*/'2013-10-20'
   and FORMALIZED_DATETIME < /*pmb.toFormalizedDate*/'2013-11-01'
   and MEMBER_STATUS_CODE = /*pmb.memberStatusCode*/'WDL'

LikeSearch条件のオプション

外だしSQLでも "LikeSearch条件" を利用できます。検索条件の中でも曖昧検索の条件はちょっと特別な存在です。一致の方向やエスケープ処理の考慮などの要素があります。 ParameterBeanのオプションとして指定することで、それら処理を自動で解決することができます。

現場フィット - LikeSearch条件

LikeSearchMatchDirection (LikeSearch条件の一致の方向)

LikeSearchEscape (LikeSearch条件のエスケープ)

LikeSearch条件の基本

自動判別の場合は、テスト値にワイルドカード "%" が入っていれば LikeSearch になります。ワイルドカード "%" の位置によって、前方一致か部分一致かが決まります。

ParameterBeanの自動判別 - オプションの導出

プロパティ定義のプロパティ名の後ろに ":[like-search-option]" と追加することで、ParameterBeanでLikeSearch条件を指定することができます。文字列型のプロパティを利用するバインド変数コメントと埋め込み変数コメントに対して有効です。 (like-search オプションと呼びます)

バインド変数コメント

埋め込み変数コメント

利用できるオプションは以下の通りです。

like: (プログラム上で)LikeSearchOptionを指定 '%fo%oo%'
likePrefix: 固定でエスケープ付きの前方一致 'foo%'
likeContain: 固定でエスケープ付きの部分一致 '%foo%'
likeSuffix: 固定でエスケープ付きの後方一致 '%foo'

e.g. 会員名で固定でエスケープ付きの部分一致 (自動判別) @OutsideSql
-- !df:pmb!
-- !!AutoDetect!!
 ...
 where MEMBER_NAME like /*pmb.memberName*/'%foo%'

e.g. 会員名で固定でエスケープ付きの部分一致 (明示的宣言) @OutsideSql
-- !df:pmb!
-- !!String memberName:likeContain!!
 ...
 where MEMBER_NAME like /*pmb.memberName*/'foo'

"like" 指定は、動的に一致の方向を変える要件がある場合に有効です。一致の方向が固定の場合は、"likePrefix" や "likeContain" などの固定の指定がお奨めです。

Example: 固定でエスケープ付きの前方一致

e.g. 会員名でエスケープ付きの前方一致検索 (自動判別) @OutsideSql
-- !df:pmb!
-- !!AutoDetect!!
 ...
 where MEMBER_NAME like /*pmb.memberName*/'foo%'

e.g. 会員名でエスケープ付きの前方一致検索 (明示的宣言) @OutsideSql
-- !df:pmb!
-- !!String memberName:likePrefix!!
 ...
 where MEMBER_NAME like /*pmb.memberName*/'foo'

e.g. likePrefix指定：会員名が 'S' で始まっていること(エスケープ付き) @Java
SimpleMemberPmb pmb = new SimpleMemberPmb();
pmb.setMemberName_PrefixSearch("S");

Example: LikeSearchOptionを指定

e.g. 会員名でLikeSearchOptionの利用 (自動判別) @OutsideSql
-- !df:pmb!
-- !!AutoDetect!!
 ...
 where MEMBER_NAME like /*pmb.memberName*/'%f%oo%'

e.g. 会員名でLikeSearchOptionの利用 (明示的宣言) @OutsideSql
-- !df:pmb!
-- !!String memberName:like!!
 ...
 where MEMBER_NAME like /*pmb.memberName*/'foo'

e.g. like指定：会員名が 'S' で始まっていること(エスケープ付き) @Java
SimpleMemberPmb pmb = new SimpleMemberPmb();
pmb.setMemberName_LikeSearch("S", new LikeSearchOption().likePrefix());

細かい補足仕様

LikeSearchOptionのスコープ: ConditionBeanで利用する LikeSearchOption と同じクラスですが、ここで利用出来るのは 一致の方向の指定 と エスケープ処理のOFF だけです。その他の機能(メソッド)は利用できません。
DBFluteランタイム - LikeSearchOption
エスケープ処理の仕様: ConditionBeanのエスケープ処理と同じ仕様です。
ConditionBean - Escape
テスト値の中のワイルドカード: 明示的宣言の場合は、バインド変数コメントのテスト値の中にワイルドカードがあってもなくても関係ありません。一方で、自動判別の場合は、バインド変数コメントのテスト値のワイルドカードが一致の方向の判断要素となります。
オプションの適用法則: 文字列型のプロパティだけでなく、ネストしたプロパティに反映させることを前提にリスト型やDTO型などのプロパティにも指定できます。
バインド変数コメント - LikeSearch条件のオプション
オプションを利用しない(外だしSQLでの)曖昧検索: オプションを利用しなくても曖昧検索は可能ですが、エスケープ処理の考慮漏れなどが発生するリスクがありますので、オプションを利用するやり方をお奨めします。

DateFromTo条件のオプション

外だしSQLでも "DateFromTo条件" を利用できます。

現場フィット - 日付範囲の条件指定を定型化(安全に)

DateFromToの基本

プロパティ定義のプロパティ名の後ろに ":[from-to-option]" と追加することで、ParameterBeanにてFromTo条件を指定することができます。(from-to オプションと呼びます)

fromDate: DateFromTo条件 (from に対応)
toDate: DateFromTo条件 (to に対応)
fromDate(option): FromToOption指定の条件 (from に対応) @since 0.9.9.2C
toDate(option): FromToOption指定の条件 (to に対応) @since 0.9.9.2C

よく利用される DateFromTo をデフォルトとし、それ以外の範囲条件を指定する場合は (option) を付与して FromToOption で明示的に指定することで柔軟な範囲条件が表現できます。

e.g. 正式会員になった日時に対して日付範囲で検索 (26日から29日まで) (自動判別) @OutsideSql
-- !df:pmb!
-- !!AutoDetect!!
 ...
 where FORMALIZED_DATETIME >= /*pmb.fromFormalizedDate:fromDate*/'...'
   and FORMALIZED_DATETIME < /*pmb.toFormalizedDate:toDate*/'...'

e.g. 正式会員になった日時に対して日付範囲で検索 (26日から29日まで) (明示的宣言) @OutsideSql
-- !df:pmb!
-- !!Date fromFormalizedDate:fromDate!!
-- !!Date toFormalizedDate:toDate!!
 ...
 where FORMALIZED_DATETIME >= /*pmb.fromFormalizedDate*/'...'
   and FORMALIZED_DATETIME < /*pmb.toFormalizedDate*/'...'

e.g. 正式会員になった日時に対して日付範囲で検索 (26日から29日まで) @Java
SimpleMemberPmb pmb = new SimpleMemberPmb();
pmb.setFromFormalizedDate_FromDate(toDate("2009-10-26 12:34:56"));
pmb.setToFormalizedDate_ToDate(toDate("2009-10-29 12:34:56"));

e.g. 正式会員になった日時に対して日付範囲で検索 (26日から29日まで) @DisplaySQL
 where FORMALIZED_DATETIME >= '2009-10-26 00:00:00'
   and FORMALIZED_DATETIME < '2009-10-30 00:00:00'

FromToOptionの指定

FromToOption の明示的指定の場合は、第二引数に FromToOption が指定できるようになります。

e.g. 正式会員になった日時に対して年月範囲で検索 (10月から12月まで) (自動判別) @OutsideSql
-- !df:pmb!
-- !!AutoDetect!!
 ...
 where FORMALIZED_DATETIME >= /*pmb.fromFormalizedDate:fromDate(option)*/'...'
   and FORMALIZED_DATETIME < /*pmb.toFormalizedDate:toDate(option)*/'...'

e.g. 正式会員になった日時に対して年月範囲で検索 (10月から12月まで) (明示的宣言) @OutsideSql
-- !df:pmb!
-- !!Date fromFormalizedDate:fromDate(option)!!
-- !!Date toFormalizedDate:toDate(option)!!
 ...
 where FORMALIZED_DATETIME >= /*pmb.fromFormalizedDate*/'...'
   and FORMALIZED_DATETIME < /*pmb.toFormalizedDate*/'...'

e.g. 正式会員になった日時に対して年月範囲で検索 (10月から12月まで) @Java
SimpleMemberPmb pmb = new SimpleMemberPmb();
FromToOption option = new FromToOption().compareAsMonth();
pmb.setFromFormalizedDate_FromDate(toDate("2009-10-03"), option);
pmb.setToFormalizedDate_ToDate(toDate("2009-12-14"), option);

e.g. 正式会員になった日時に対して年月範囲で検索 (10月から12月まで) @DisplaySQL
 where FORMALIZED_DATETIME >= '2009-10-01 00:00:00'
   and FORMALIZED_DATETIME < '2010-01-01 00:00:00'

区分値条件のオプション

外だしSQLでも "区分値" を利用できます。

現場フィット - 区分値

区分値条件の基本

対応する区分値を ":cls([classification-name])" (cls オプションと呼びます) にて指定すると、ParameterBeanに区分値メソッドが生成されます。

e.g. paymentCompleteFlg を Flg に関連付け (プロパティの自動判別) @OutsideSql
-- !df:pmb!
-- !!AutoDetect!!
 ...
 where PAYMENT_COMPLETE_FLG = /*pmb.paymentCompleteFlg:cls(Flg)*/0

e.g. paymentCompleteFlg を Flg に関連付け (プロパティの明示的宣言) @OutsideSql
-- !df:pmb!
-- !!String paymentCompleteFlg:cls(Flg)!!
 ...
 where PAYMENT_COMPLETE_FLG = /*pmb.paymentCompleteFlg*/0

リスト型の区分値

リスト型に関しては、区分値を関連付けても区分値メソッドは生成されませんので、少なくとも cls オプションを付ける意味はありません。代わりにリストの要素型を対応する CDef の区分値クラスにして、CDef を使って複数の区分値要素を指定するようにすると良いでしょう。

this - プログラム型のパッケージ解決 - CDefのパッケージ解決

e.g. memberStatusCodeを複数指定するためにリスト型のプロパティを指定 (明示的宣言) @OutsideSql
-- !df:pmb!
-- !!List<$$CDef$$.MemberStatus> statusList!!
 ...
 where MEMBER_STATUS_CODE in /*pmb.statusList*/('FML')

CDef型のプロパティを自動判別することはできないので、この場合は明示的宣言をお奨めします。 (厳密にはできなくないのですが、バインド変数コメントの宣言がごちゃごちゃしてしまってあまり見た目がよくないので)

固定の区分値

固定の区分値を条件値にするような場合は、cls オプションで区分要素まで指定することで固定の区分値を指定することができます(@since 0.9.9.0D)。これを利用することで、外だしSQLの中で区分値をハードコードする必要がなくなり、タイプミスによる区分値コードの間違いの心配はなくなります。ハードコードよりも少し書くことが多くなりますが、安全性を優先するならば積極的に利用した方が良いでしょう。

普通に区分値を関連付けてプログラム上で固定値を設定しても同じことが実現できますが、固定の区分値を利用することでプログラム上での値の設定は必要はなくなり、さらに外だしSQL上でその固定値が何なのか判断することができるためSQLの可読性を保つことができます。また、固定値であるため、ParameterBeanではこのプロパティに対する設定メソッド(Setter)は生成されません。

e.g. paymentCompleteFlg の True を固定に関連付け (自動判別) @OutsideSql
-- !df:pmb!
-- !!AutoDetect!!
 ...
 where PAYMENT_COMPLETE_FLG = /*pmb.paymentCompleteTrue:cls(Flg.True)*/0

e.g. paymentCompleteFlg の True を固定に関連付け (明示的宣言) @OutsideSql
-- !df:pmb!
-- !!String paymentCompleteTrue:cls(Flg.True)!!
 ...
 where PAYMENT_COMPLETE_FLG = /*pmb.paymentCompleteTrue*/0

InScope に対して固定の(複数の)区分値を指定することもできます。区分要素を "," で追加します。(@since 1.2.1 :: それまでコンパイルエラーになってしまっていました)

e.g. memberStatusCode で Formalized と Provisional を固定に関連付け (自動判別) @OutsideSql
-- !df:pmb!
-- !!AutoDetect!!
 ...
 where MEMBER_STATUS_CODE in
     /*pmb.validStatusList:cls(MemberStatus.Formalized, Provisional)*/('FML')

e.g. memberStatusCode で Formalized と Provisional を固定に関連付け (明示的宣言) @OutsideSql
-- !df:pmb!
-- !!List<String> validStatusList:cls(MemberStatus.Formalized, Provisional)!!
 ...
 where MEMBER_STATUS_CODE in /*pmb.validStatusList*/('FML')

参照カラムによる区分値の関連付け

clsオプションではなく、参照カラムのオプションでも、区分値を関連付けることができます。

対応するカラムを参照カラムのオプション ":ref([table-name].[column-name])" にて指定すると、ParameterBean にて区分値メソッドが利用できます。対応するカラムが区分値であれば、この紐付けから自動的に区分値が認識されます。(ref オプションと呼びます)

this - 参照カラムのオプション

また、プロパティ名と対応するカラム名が、FlexibleName (大文字小文字、アンダースコアを無視) として一致する場合は、カラム名の指定は省略できます。

e.g. memberStatusCodeを会員ステータス(区分値)に関連付け (自動判別) @OutsideSql
-- !df:pmb!
-- !!AutoDetect!!
 ...
 where MEMBER_STATUS_CODE = /*pmb.memberStatusCode:ref(MEMBER)*/'FML'

e.g. memberStatusCodeを会員ステータス(区分値)に関連付け (明示的宣言) @OutsideSql
-- !df:pmb!
-- !!String memberStatusCode:ref(MEMBER)!!
 ...
 where MEMBER_STATUS_CODE = /*pmb.memberStatusCode*/'FML'

e.g. 会員ステータス(区分値)が正式会員であること(検索条件) @Java
SimpleMemberPmb pmb = new SimpleMemberPmb();
pmb.setMemberStatusCode_Formalized();

区分値は、何かしらのカラムに関連付いているはずなので、実は ref オプションを使う方がドキュメント上のメリットがある分だけ得です。 (ただし、"固定の区分値" においては必ず cls オプションを使う必要があります)

参照カラムのオプション

参照カラムの基本

ParameterBeanのプロパティの "参照カラム" を定義して、プロパティのJavaDocコメントなどでカラムの情報を利用することができます。そのプロパティがどのカラムに対するパラメータなのか、実装しながら情報を得ることができます。また、参照カラムの区分値の設定も継承されるので、同時に 区分値の紐付けオプション にも、自動判別プロパティにプログラム型ヒント にもなります。

ドキュメントの継承: JavaDocコメントに、参照カラムのコメントも
区分値設定の継承: 参照カラムの区分値の設定をそのまま継承
自動判別の型ヒント: 自動判別プロパティのプログラム型判別のヒントに

プロパティ定義のプロパティ名の後ろに ":ref([table-name].[column-name])" と追加することで、そのプロパティの参照カラムを定義できます。(ref オプションと呼びます)

e.g. 会員名称を参照するプロパティ (自動判別) @OutsideSql
-- !df:pmb!
-- !!AutoDetect!!
 ...
 where MEMBER_NAME = /*pmb.name:ref(MEMBER.MEMBER_NAME)*/'S%'

e.g. 会員名称を参照するプロパティ (明示的宣言) @OutsideSql
-- !df:pmb!
-- !!String name:ref(MEMBER.MEMBER_NAME)!!
 ...
 where MEMBER_NAME = /*pmb.name*/'S%'

プロパティ名とカラム名を FlexibleName (大文字小文字、アンダースコア区別せず) として同名になるのであれば、":ref([table-name])" というようにカラム名は省略できます。リスト型のプロパティでプロパティ名が List で終わっている場合は、最後の List を除去した名前で比較されます(@since 0.9.8.0)。

FlexibleName

e.g. プロパティと参照カラムが同名の場合 (自動判別) @OutsideSql
-- !df:pmb!
-- !!AutoDetect!!
 ...
 where MEMBER_NAME = /*pmb.memberName:ref(MEMBER)*/'S%'

e.g. プロパティと参照カラムが同名の場合 (明示的宣言) @OutsideSql
-- !df:pmb!
-- !!String memberName:ref(MEMBER)!!
 ...
 where MEMBER_NAME = /*pmb.memberName*/'S%'

他のオプションと併用する場合

他のオプションと組み合わせる場合は、オプション表記の中で "|" を区切り文字として利用することで、複数のオプションが指定できます。

e.g. 他のオプションと併用する場合 (fromDate と ref オプション) @OutsideSql
-- !df:pmb!
-- !!String fromBirthdate:fromDate|ref(MEMBER.BIRTHDATE)!!

ShortCharHandlingで必要

この機能は、基本的にカラム情報の参照などによるささやかな実装支援のためのものですが、ShortCharHandling の機能をParameterBeanで利用する場合には、このオプションが必須となります。

現場フィット - char型の桁数不足の取扱い

プロパティのコメント

プロパティ宣言のときのコメント

それぞれのプロパティにコメントを付けることができます。決まった形式でコメントを書くことで、単に外だしSQL上で業務的な意味がわかりやすくなるというだけでなく、自動生成された ParameterBean のプロパティのメソッドの JavaDoc コメントにそのコメントに転記され、実装しながらそのコメントを読むことができます。特に利用方法が特殊なものには、積極的にコメントを書いていくと他の人が見たときにわかりやすくなります。 @since 0.9.8.4

プロパティ項目の宣言の後に、"//" というマークの後に一行コメントを書きます。

e.g. プロパティにコメントを書く @OutsideSql
-- !df:pmb!
-- !!String memberId!!   // それぞれのプロパティの説明や補足などを書く
-- !!String memberName!! // このように書いておけば JavaDoc で読める
-- !!Date birthdate!!    // なのでJavaDocで利用できない文字は使えない
-- !!String statusCode!! // スラスラ(//)ってなんか Java っぽい
select ...
  from ...

プロパティ自動判別のときのコメント

プロパティの自動判別を利用した場合は、同じ行に -- // 形式で書くとコメントとみなされます。こちら、ぜひ積極的に活用して、後から見た人がパラメーターのことで迷わないようにしましょう。

プロパティの自動判別

e.g. 自動判別されるプロパティにコメントを書く @OutsideSql
-- !df:pmb!
-- !!AutoDetect!!
select ...
  from ...
 where MEMBER_ID = /*pmb.memberId*/3 -- // ここにコメントを書く

内部的には、こういう風に書いているのと同じです。

e.g. 自動判別されるプロパティにコメントを書く @OutsideSql
-- !df:pmb!
-- !!AutoDetect!!
select ...
  from ...
 where MEMBER_ID = /*pmb.memberId:comment(ここにコメントを書く)*/3

CustomizeEntityの検索カラムでも同じようなことができます。合わせて利用すると良いでしょう。

CustomizeEntity - 検索カラムのコメント

同時に二つ以上のオプションを指定する

連結文字として "|" を使うことで、二つ以上のオプションを指定できます。

e.g. 他のオプションと併用する場合 (fromDate と ref オプション) @OutsideSql
-- !df:pmb!
-- !!String fromBirthdate:fromDate|ref(MEMBER.BIRTHDATE)!!