データベースに対して実行されるメソッド内のパラメーターを参照するために SQL ステートメントで使用できる数種類のマーカーがあります。
SQL ステートメントは、ステートメントを使用するメソッドのパラメーターに実行時に渡される値を使用できます。SQL ステートメントは、それらのパラメーターをマーカーで示します。
各マーカーは、メソッド内のパラメーターに対応しています。
メソッドが呼び出されると、これらのパラメーターの値は呼び出し元のアプリケーションにより提供される引数から取得され、SQL ステートメントの実行時に使用されます。
以下のように、SQL ステートメントで使用できるマーカーには幾つかのタイプがあります。
- ?
- これらのマーカーは、位置によってメソッドのパラメーターと一致します。
- インライン・メソッドで使用する場合、nth ? マーカーは、Object... パラメーターの値が含まれる Object[] 内の (n-1)th 項目と一致します。
- アノテーション付きメソッドで使用する場合、nth ? マーカーは、アノテーション付きメソッドの nth パラメーターと一致します。
@Select(sql="select DEPTNO, DEPTNAME, MGRNO, ADMRDEPT, LOCATION from DEPARTMENT where DEPTNO = ?")
Iterator<Department> getDepartment(String deptno);
@Update(sql="insert into DEPARTMENT (DEPTNO, DEPTNAME, MGRNO, ADMRDEPT, LOCATION) values( ?, ?, ?, ?, ?)")
int createDepartment(String deptno, String deptname, String mgrno, String admrdept, String location);
@Update(sql="update DEPARTMENT set DEPTNO = ?, DEPTNAME = ?, MGRNO = ?, ADMRDEPT = ?, LOCATION = ? where DEPTNO = ?")
int updateDepartment(String deptno, String deptname, String mgrno, String admrdept, String location, String deptno_K);
- このタイプのマーカーを使用する場合、SQL ステートメント内の他のすべてのマーカーも同じタイプでなければなりません。
- ?n
- これらのマーカー (n は正整数リテラルを表す) は、位置によってメソッドのパラメーターと一致します。
- この SQL ステートメントでは、同じ序数のマーカーを複数回に渡って使用できます。
- :name
- これらのマーカーは、?1.name の短縮版です。
- ?n.name
- これらのマーカーはメソッド・パラメーター ?n を参照します。このパラメーターは、java.util.Map<String> オブジェクトまたは Bean を参照していなければなりません。name は、java.util.Map<String> オブジェクト内または Bean 内のプロパティーを参照している必要があります。
識別されたパラメーターが
java.util.Map<String> の場合、pureQuery が呼び出すメソッドは、以下のようにパラメーターの使用方法によって異なります。
- 入力パラメーター: pureQuery は Map の Object get(String) メソッドを呼び出して、SQL ステートメントに渡す値を獲得します。get() メソッドに対する呼び出しの String の値は、?n に続く名前の部分です。
- 出力パラメーター: pureQuery は Map の Object put(String, Object) メソッドを呼び出して、指定されたキーに関連付けられている値を戻します。put() に対する呼び出しのキー String の値は、?n に続く名前の部分です。
- 入力パラメーターと出力パラメーター: pureQuery は、SQL ステートメントを実行する前に Map の Object get(String) メソッドを呼び出します。pureQuery は、SQL ステートメントの実行後に Map の Object put(String, Object) メソッドを呼び出します。
キーとして使用されている String は、(: または ?n が接頭部に付いていても) パラメーター・マーカーの名前からすべて取られているので、名前は Java をソースとする識別子と見なされ、get() メソッドと mutator メソッドに元々の大/小文字で渡されます。
識別されたパラメーターが Bean である場合、解決プロセスはより複雑になります。
- パラメーターが入力パラメーターとして使用される場合、pureQuery は以下のプロセスに従います。
- Bean インターフェースでは public getXXX() メソッドがないか調べられます。ここで、識別子の XXX 部分は、?n に続く名前から生成されます。この生成前に、その名前の最初の文字がまず大文字に変換されます。そのようなメソッドが存在する場合には、SQL ステートメントに渡す値を獲得するために使用されます。
- getXXX() メソッドが見つからない場合には、Bean では、?n に続く名前と一致する名前の public プロパティーがないか調べられます。そのようなプロパティーが存在する場合には、直接アクセスして、SQL ステートメントに渡す値を獲得します。
- public プロパティーが見つからない場合には、Bean インターフェースでは public Object get(String) メソッドがないか調べられます。そのようなメソッドが存在する場合には、SQL ステートメントに渡す値を獲得するために使用されます。String パラメーターに渡される値は、?n に続く名前の部分です。
- get(String) メソッドが見つからない場合、エラーが報告されます。
- パラメーターが出力パラメーターとして使用される場合、pureQuery は以下のプロセスに従います。
- Bean インターフェースでは public setXXX() メソッドがないか調べられます。ここで、識別子の XXX 部分は、?n に続く名前から生成されます。この生成前に、その名前の最初の文字がまず大文字に変換されます。そのようなメソッドが存在する場合には、Bean パラメーターの関連プロパティーを更新するために使用されます。
- setXXX() メソッドが見つからない場合には、Bean では、?n に続く名前と一致する名前の public プロパティーがないか調べられます。そのようなプロパティーが存在する場合には、直接に変更して、その Bean の関連プロパティーを更新します。
- public プロパティーが見つからない場合には、Bean インターフェースでは public void set(String, Object) メソッドがないか調べられます。そのようなメソッドが存在する場合には、その Bean の関連プロパティーを更新するために使用されます。String パラメーターに渡される値は、?n に続く名前の部分です。
- set(String, Object) メソッドが見つからない場合、エラーが報告されます。
- パラメーターが入力パラメーターと出力パラメーターの両方として使用される場合には、SQL ステートメントの実行前に前述の入力パラメーターの解決プロセスが実行され、SQL ステートメントの実行後に前述の出力パラメーター用のプロセスが実行されます。
この場合も、キーとして使用されている String は、(: または ?n が接頭部に付いていても) パラメーター・マーカーの名前からすべて取られているので、名前は Java をソースとする識別子と見なされ、get(String) メソッドと set(String) メソッドに元々の大/小文字で渡されます。
Map と Bean は、パラメーターのソースとして使用するだけでなく、照会によって選択される行から構成することもできます。pureQuery で行から Map または Bean を構成する場合、get(String) メソッド、set(String,
Object) メソッド、および put(String, Object) メソッドでキーに使用される String 値は、SQL をソースとする識別子 (選択列のラベルに由来) で、小文字になります。Bean のオプションの get(String) メソッドまたは set(String, Object) メソッド、あるいは Map の get(String) および put(String, Object) メソッドを実装または使用する場合、キーとして使用する識別子の大/小文字に注意しなければなりません。