Merge pull request #181 from domaframework/sql-processor

SQLテンプレートで組み立てられたSQLを扱うための  `@SqlProcessor` を追加

Author: nakamura-to

docs/sources/query/index.rst

@@ -16,3 +16,4 @@
    procedure
    factory
    script
+   sql-processor

docs/sources/query/sql-processor.rst

@@ -0,0 +1,68 @@
+==================
+SQLプロセッサ
+==================
+
+.. contents:: 目次
+   :depth: 3
+
+SQLテンプレートで組み立てられたSQLをアプリケーションで扱うには、 ``@SqlProcessor`` をDaoのメソッドに注釈します。
+
+.. code-block:: java
+
+  @Config(config = AppConfig.class)
+  public interface EmployeeDao {
+      @SqlProcessor
+      <R> R process(Integer id, BiFunction<Config, PreparedSql, R> handler);
+      ...
+  }
+
+メソッドに対応する :doc:`../sql` が必須です。
+
+.. warning::
+
+  SQLプロセッサを使ってSQLを組み立て実行する場合、潜在的には常にSQLインジェクションのリスクがあります。
+  まずは、他のクエリもしくはクエリビルダを使う方法を検討してください。
+  また、SQLプロセッサでは信頼できない値をSQLの組み立てに使わないように注意してください。
+
+戻り値
+==================
+
+メソッドの戻り値は任意の型にできます。
+ただし、 ``BiFunction`` 型のパラメータの3番目の型パラメータと合わせる必要があります。
+
+なお、戻り値の型を ``void`` にする場合、 ``BiFunction`` 型のパラメータの3番目の型パラメータには ``Void`` を指定します。
+
+.. code-block:: java
+
+  @SqlProcessor
+  void process(Integer id, BiFunction<Config, PreparedSql, Void> handler);
+
+パラメータ
+==================
+
+ ``BiFunction`` 型のパラメータを1つのみ含める必要があります。
+ ``BiFunction`` 型のパラメータはSQLテンプレート処理後のSQLを処理するために使われます。
+
+その他のパラメータはSQLテンプレートで参照できます。
+基本的には、 :doc:`select` の問い合わせ条件に指定できるのと同じ型を使用できます。 
+
+利用例
+==================
+
+例えば、SQLテンプレートで処理したSQLをさらに変形し直接実行することができます。（この例では例外処理を省略しています。）
+
+.. code-block:: java
+
+  EmployeeDao dao = ...
+  dao.process(1, (config, preparedSql) -> {
+    String sql = preparedSql.getRawSql();
+    String anotherSql = createAnotherSql(sql);
+    DataSource dataSource = config.getDataSource()
+    Connection connection = dataSource.getConnection();
+    PreparedStatement statement = connection.prepareStatement(anotherSql);
+    return statement.execute();
+  });
+
+.. code-block:: sql
+
+  select * from employee where id = /*^ id */0

src/main/java/org/seasar/doma/SqlProcessor.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2004-2010 the Seasar Foundation and the Others.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+package org.seasar.doma;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * SQLテンプレートで組み立てられたSQLを扱うことを示します。
+ * <p>
+ * このアノテーションが注釈されるメソッドは、Daoインタフェースのメンバでなければいけません。
+ * 
+ * <h3>例:</h3>
+ * 
+ * <pre>
+ * &#064;Dao(config = AppConfig.class)
+ * public interface EmployeeDao {
+ *     &#64;SqlProcessor
+ *     &lt;R&gt; R process(Integer id, BiFunction&lt;Config, PreparedSql, R&gt; handler);
+ * }
+ * </pre>
+ * 
+ * @author nakamura
+ * @since 2.14.0
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+@DaoMethod
+public @interface SqlProcessor {
+
+}