SQL ステートメント内のパラメーター・マーカー

データベースに対して実行されるメソッド内のパラメーターを参照するために 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 は正整数リテラルを表す) は、位置によってメソッドのパラメーターと一致します。
  • インライン・メソッドで使用する場合、?n は、Object... パラメーターの値が含まれる Object[] 内の (n-1)th 項目と一致します。
  • アノテーション・メソッドで使用する場合、?n はアノテーション付きメソッドの nth パラメーターと一致します。
       @Select(sql="SELECT * FROM Employee WHERE salary>?1")
       Iterator<Customer> getCustomersInRegion(BigDecimal r);
この SQL ステートメントでは、同じ序数のマーカーを複数回に渡って使用できます。
:name
これらのマーカーは、?1.name の短縮版です。
?n.name
これらのマーカーはメソッド・パラメーター ?n を参照します。このパラメーターは、java.util.Map<String> オブジェクトまたは Bean を参照していなければなりません。name は、java.util.Map<String> オブジェクト内または Bean 内のプロパティーを参照している必要があります。
識別されたパラメーターが java.util.Map<String> の場合、pureQuery が呼び出すメソッドは、以下のようにパラメーターの使用方法によって異なります。
  • 入力パラメーター: pureQuery は MapObject get(String) メソッドを呼び出して、SQL ステートメントに渡す値を獲得します。get() メソッドに対する呼び出しの String の値は、?n に続く名前の部分です。
  • 出力パラメーター: pureQuery は MapObject put(String, Object) メソッドを呼び出して、指定されたキーに関連付けられている値を戻します。put() に対する呼び出しのキー String の値は、?n に続く名前の部分です。
  • 入力パラメーターと出力パラメーター: pureQuery は、SQL ステートメントを実行する前に MapObject get(String) メソッドを呼び出します。pureQuery は、SQL ステートメントの実行後に MapObject put(String, Object) メソッドを呼び出します。

キーとして 使用されている String はすべて、(: または ?n が接頭部として付いていても) パラメーター・マーカー内の名前から 取得されているため、名前は、Java をソースとする識別子と見なされ、get() メソッドと mutator メソッドに元々の大/小文字で渡されます。

識別されたパラメーターが Bean である場合、解決プロセスはより複雑になります。
  • パラメーターが入力パラメーターとして使用される場合、pureQuery は以下のプロセスに従います。
    1. Bean インターフェースでは public getXXX() メソッドがないか調べられます。ここで、識別子の XXX 部分は、?n に続く名前から生成されます。この生成前に、その名前の最初の文字がまず大文字に変換されます。そのようなメソッドが存在する場合には、SQL ステートメントに渡す値を獲得するために使用されます。
    2. getXXX() メソッドが見つからない場合には、Bean では、?n に続く名前と一致する名前の public プロパティーがないか調べられます。そのようなプロパティーが存在する場合には、直接アクセスして、SQL ステートメントに渡す値を獲得します。
    3. public プロパティーが見つからない場合には、Bean インターフェースでは public Object get(String) メソッドがないか調べられます。そのようなメソッドが存在する場合には、SQL ステートメントに渡す値を獲得するために使用されます。String パラメーターに渡される値は、?n に続く名前の部分です。
    4. get(String) メソッドが見つからない場合、エラーが報告されます。
  • パラメーターが出力パラメーターとして使用される場合、pureQuery は以下のプロセスに従います。
    1. Bean インターフェースでは public setXXX() メソッドがないか調べられます。ここで、識別子の XXX 部分は、?n に続く名前から生成されます。この生成前に、その名前の最初の文字がまず大文字に変換されます。そのようなメソッドが存在する場合には、Bean パラメーターの関連プロパティーを更新するために使用されます。
    2. setXXX() メソッドが見つからない場合には、Bean では、?n に続く名前と一致する名前の public プロパティーがないか調べられます。そのようなプロパティーが存在する場合には、直接に変更して、その Bean の関連プロパティーを更新します。
    3. public プロパティーが見つからない場合には、Bean インターフェースでは public void set(String, Object) メソッドがないか調べられます。そのようなメソッドが存在する場合には、その Bean の関連プロパティーを更新するために使用されます。String パラメーターに渡される値は、?n に続く名前の部分です。
    4. 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) メソッドを実装または使用する場合、キーとして使用する識別子の大/小文字に注意しなければなりません。


フィードバック