Documentation

Author: harawata

src/site/es/xdoc/java-api.xml

@@ -245,13 +245,13 @@ public interface ResultHandler<T> {
   <p>There is method for flushing(executing) batch update statements that stored in a JDBC driver class at any timing. This method can be used when you use the <code>ExecutorType.BATCH</code> as <code>ExecutorType</code>.</p>
   <source><![CDATA[List<BatchResult> flushStatements()]]></source>
 
-  <h5>Métodos de control de transacción</h5>
+  <h5 id="transaction-control-methods">Métodos de control de transacción</h5>
   <p>El parámetro ResultContext te da acceso al objeto resultado en sí mismo, un contador del número de objetos creados y un método booleano stop() que te permite indicar a MyBatis que pare la carga de datos.</p>
   <source>void commit()
 void commit(boolean force)
 void rollback()
 void rollback(boolean force)</source>
-  <p>Por defecto MyBatis no hace un commit a no ser que haya detectado que la base de datos ha sido modificada por una insert, update o delete. Si has realizado cambios sin llamar a estos métodos, entonces puedes pasar true en al método de commit() y rollback() para asegurar que se realiza el commit (ten en cuenta que aun así no puedes forzar el commit() en modo auto-commit o cuando se usa un gestor de transacciones externo). La mayoría de las veces no tendrás que llamar a rollback() dado que MyBatis lo hará por ti en caso de que no hayas llamado a commit(). Sin embargo, si necesitas un control más fino sobre la sesión, donde puede que haya varios commits, tienes esta opción para hacerlo posible.</p>
+  <p>Por defecto MyBatis no hace un commit a no ser que haya detectado que la base de datos ha sido modificada por una insert, update, delete o select con <code>affectData</code> habilitado. Si has realizado cambios sin llamar a estos métodos, entonces puedes pasar true en al método de commit() y rollback() para asegurar que se realiza el commit (ten en cuenta que aun así no puedes forzar el commit() en modo auto-commit o cuando se usa un gestor de transacciones externo). La mayoría de las veces no tendrás que llamar a rollback() dado que MyBatis lo hará por ti en caso de que no hayas llamado a commit(). Sin embargo, si necesitas un control más fino sobre la sesión, donde puede que haya varios commits, tienes esta opción para hacerlo posible.</p>
   <p><span class="label important">NOTA</span> MyBatis-Spring y MyBatis-Guice proporcionan gestión de transacción declarativa. Por tanto si estás usando MyBatis con Spring o Guice consulta sus manuales específicos.</p>
 
   <h5>Local Cache</h5>

src/site/es/xdoc/sqlmap-xml.xml

@@ -201,6 +201,11 @@ ps.setInt(1,id);]]></source>
                 <code>false</code>.
               </td>
             </tr>
+            <tr>
+              <td><code>affectData</code></td>
+              <td>Set this to true when writing a INSERT, UPDATE or DELETE statement that returns data so that the transaction is controlled properly. Also see <a href="./java-api.html#transaction-control-methods">Transaction Control Method</a>. Default: <code>false</code> (since 3.5.12)
+              </td>
+            </tr>
           </tbody>
         </table>
       </subsection>
@@ -405,6 +410,18 @@ Por ejemplo, si la columna id de la tabla Author del ejemplo siguiente fuera aut
             </tr>
           </tbody>
         </table>
+
+        <p>
+          As an irregular case, some databases allow INSERT, UPDATE or DELETE statement to return result set (e.g. <code>RETURNING</code> clause of PostgreSQL and MariaDB or <code>OUTPUT</code> clause of MS SQL Server). This type of statement must be written as <code><![CDATA[<select>]]></code> to map the returned data.
+        </p>
+
+        <source><![CDATA[<select id="insertAndGetAuthor" resultType="domain.blog.Author"
+      affectData="true" flushCache="true">
+  insert into Author (username, password, email, bio)
+  values (#{username}, #{password}, #{email}, #{bio})
+  returning id, username, password, email, bio
+</select>]]></source>
+
       </subsection>
 
       <subsection name="sql">

src/site/ja/xdoc/java-api.xml

@@ -249,13 +249,13 @@ public interface ResultHandler<T> {
   <p>バッチ更新用に JDBC ドライバ内に蓄積されたステートメントを任意のタイミングでデータベースへフラッシュ(実行)するメソッドがあります。このメソッドは、 <code>ExecutorType</code> として <code>ExecutorType.BATCH</code> を使用している場合に使用することができます。</p>
   <source><![CDATA[List<BatchResult> flushStatements()]]></source>
 
-  <h5>トランザクションを制御するメソッド</h5>
+  <h5 id="transaction-control-methods">トランザクションを制御するメソッド</h5>
   <p>トランザクションのスコープを制御するメソッドは４つあります。当然ですが、auto-commit を使用する場合や、外部のトランザクションマネージャーを使っている場合、これらのメソッドは効果がありません。しかし、Connection のインスタンスによって管理されている JDBC トランザクションマネージャーを利用している場合は便利なメソッドです。</p>
   <source>void commit()
 void commit(boolean force)
 void rollback()
 void rollback(boolean force)</source>
-  <p>デフォルトでは、データベースが insert, update, delete メソッドの実行によって変更されない限り MyBatis は commit を実行しません。何らかの理由でこれらのメソッドを使わずにデータを変更した場合は確実にコミットされるように commit メソッドに引数 true を渡してください（ただし、auto-commit モードのセッションや外部のトランザクションマネージャーを使っている場合は true を渡してもコミットされません）。commit が実行されない場合、MyBatis がロールバックを実行するので、通常明示的に rollback() メソッドを呼び出す必要はありません。しかし、一つのセッションの中で複数のコミットやロールバックが必要とされるようなケースでは、rollback() メソッドを使ってより細かい制御を行うことが可能です。</p>
+  <p>デフォルトでは、データベースの変更を伴うメソッド insert, update, delete, <code>affectData</code> を有効化した select が実行されない限り MyBatis は commit を実行しません。何らかの理由でこれらのメソッドを使わずにデータを変更した場合は確実にコミットされるように commit メソッドに引数 true を渡してください（ただし、auto-commit モードのセッションや外部のトランザクションマネージャーを使っている場合は true を渡してもコミットされません）。commit が実行されない場合、MyBatis がロールバックを実行するので、通常明示的に rollback() メソッドを呼び出す必要はありません。しかし、一つのセッションの中で複数のコミットやロールバックが必要とされるようなケースでは、rollback() メソッドを使ってより細かい制御を行うことが可能です。</p>
   <p><span class="label important">NOTE</span> Mybatis-Spring と MyBatis-Guice では宣言的トランザクションがサポートされています。詳細は各サブプロジェクトのドキュメントを参照してください。</p>
 
   <h5>ローカルキャッシュ</h5>

src/site/ja/xdoc/sqlmap-xml.xml

@@ -233,6 +233,11 @@ ps.setInt(1,id);]]></source>
               <td>複数の ResultSet を利用する場合にのみ有効です。ステートメントが返す ResultSet にそれぞれ任意の名前を付けてリストアップします。名前はカンマで区切ります。
               </td>
             </tr>
+            <tr>
+              <td><code>affectData</code></td>
+              <td>ResultSet を返す INSERT, UPDATE, DELETE 文を記述する場合に true をセットします。これによりトランザクション制御が正しく実行されるようになります。<a href="./java-api.html#transaction-control-methods">トランザクションを制御するメソッド</a> も参照してください。 デフォルト： <code>false</code> （3.5.12 以降）
+              </td>
+            </tr>
           </tbody>
         </table>
       </subsection>
@@ -453,6 +458,18 @@ ps.setInt(1,id);]]></source>
             </tr>
           </tbody>
         </table>
+
+        <p>
+          例外として、INSERT, UPDATE, DELETE 文から ResultSet を返す SQL 文（PostgreSQL, MariaDB の <code>RETURNING</code> , MS SQL Server の <code>OUTPUT</code> など）で結果をマップするためには <code><![CDATA[<select />]]></code> を使用する必要があります。
+        </p>
+
+        <source><![CDATA[<select id="insertAndGetAuthor" resultType="domain.blog.Author"
+      affectData="true" flushCache="true">
+  insert into Author (username, password, email, bio)
+  values (#{username}, #{password}, #{email}, #{bio})
+  returning id, username, password, email, bio
+</select>]]></source>
+
       </subsection>
 
       <subsection name="sql">

src/site/ko/xdoc/java-api.xml

@@ -316,15 +316,15 @@ public interface ResultHandler<T> {
   이 방법은 <code>ExecutorType</code>을 <code>ExecutorType.BATCH</code>로 설정한 경우 사용가능하다. </p>
   <source><![CDATA[List<BatchResult> flushStatements()]]></source>
 
-  <h5>트랙잭션 제어 메소드</h5>
+  <h5 id="transaction-control-methods">트랙잭션 제어 메소드</h5>
   <p>트랜잭션을 제어하기 위해 4개의 메소드가 있다.
   물론 자동커밋을 선택하였거나 외부 트랜잭션 관리자를 사용하면 영향이 없다.
   어쨌든 Connection인스턴스에 의해 관리되고 JDBC 트랜잭션 관리자를 사용하면 이 4개의 메소드를 사용할 수 있다.</p>
   <source>void commit()
 void commit(boolean force)
 void rollback()
 void rollback(boolean force)</source>
-  <p>기본적으로 마이바티스는 insert, update 또는 delete 를 호출하여 데이터베이스가 변경된 것으로 감지하지 않는 한 실제로 커밋하지 않는다.
+  <p>기본적으로 마이바티스는 insert, update, delete 또는 <code>affectData</code>가 활성화된select 를 호출하여 데이터베이스가 변경된 것으로 감지하지 않는 한 실제로 커밋하지 않는다.
   이러한 메소드 호출없이 변경되면 커밋된 것으로 보장하기 위해 commit 와 rollback 메소드에 true 값을 전달한다.</p>
   <p><span class="label important">참고</span> MyBatis-Spring 과 MyBatis-Guice는 선언적인 트랜잭션 관리기법을 제공한다.
   그래서 스프링이나 쥬스와 함께 마이바티스를 사용한다면 해당되는 메뉴얼을 꼭 참고하길 바란다. </p>

src/site/ko/xdoc/sqlmap-xml.xml

@@ -188,6 +188,11 @@ ps.setInt(1,id);]]></source>
               디폴트값은 <code>false</code> 이다.
               </td>
             </tr>
+            <tr>
+              <td><code>affectData</code></td>
+              <td>Set this to true when writing a INSERT, UPDATE or DELETE statement that returns data so that the transaction is controlled properly. Also see <a href="./java-api.html#transaction-control-methods">Transaction Control Method</a>. Default: <code>false</code> (since 3.5.12)
+              </td>
+            </tr>
           </tbody>
         </table>
       </subsection>
@@ -392,6 +397,18 @@ ps.setInt(1,id);]]></source>
             </tr>
           </tbody>
         </table>
+
+        <p>
+          As an irregular case, some databases allow INSERT, UPDATE or DELETE statement to return result set (e.g. <code>RETURNING</code> clause of PostgreSQL and MariaDB or <code>OUTPUT</code> clause of MS SQL Server). This type of statement must be written as <code><![CDATA[<select>]]></code> to map the returned data.
+        </p>
+
+        <source><![CDATA[<select id="insertAndGetAuthor" resultType="domain.blog.Author"
+      affectData="true" flushCache="true">
+  insert into Author (username, password, email, bio)
+  values (#{username}, #{password}, #{email}, #{bio})
+  returning id, username, password, email, bio
+</select>]]></source>
+
       </subsection>
 
       <subsection name="sql">

src/site/xdoc/java-api.xml

@@ -251,13 +251,13 @@ public interface ResultHandler<T> {
   <p>There is method for flushing (executing) batch update statements that are stored in a JDBC driver class at any time. This method can be used when the <code>ExecutorType</code> is <code>ExecutorType.BATCH</code>.</p>
   <source><![CDATA[List<BatchResult> flushStatements()]]></source>
 
-  <h5>Transaction Control Methods</h5>
+  <h5 id="transaction-control-methods">Transaction Control Methods</h5>
   <p>There are four methods for controlling the scope of a transaction. Of course, these have no effect if you've chosen to use auto-commit or if you're using an external transaction manager. However, if you're using the JDBC transaction manager, managed by the <code>Connection</code> instance, then the four methods that will come in handy are:</p>
   <source>void commit()
 void commit(boolean force)
 void rollback()
 void rollback(boolean force)</source>
-  <p>By default MyBatis does not actually commit unless it detects that the database has been changed by a call to <code>insert</code>, <code>update</code> or <code>delete</code>. If you've somehow made changes without calling these methods, then you can pass <code>true</code> into the <code>commit</code> and <code>rollback</code> methods to guarantee that they will be committed (note, you still can't force a session in auto-commit mode, or one that is using an external transaction manager). Most of the time you won't have to call <code>rollback()</code>, as MyBatis will do that for you if you don't call commit. However, if you need more fine-grained control over a session where multiple commits and rollbacks are possible, you have the rollback option there to make that possible.</p>
+  <p>By default MyBatis does not actually commit unless it detects that the database has been changed by a call to <code>insert</code>, <code>update</code>, <code>delete</code> or <code>select</code> with <code>affectData</code> enabled. If you've somehow made changes without calling these methods, then you can pass <code>true</code> into the <code>commit</code> and <code>rollback</code> methods to guarantee that they will be committed (note, you still can't force a session in auto-commit mode, or one that is using an external transaction manager). Most of the time you won't have to call <code>rollback()</code>, as MyBatis will do that for you if you don't call commit. However, if you need more fine-grained control over a session where multiple commits and rollbacks are possible, you have the rollback option there to make that possible.</p>
   <p><span class="label important">NOTE</span> MyBatis-Spring and MyBatis-Guice provide declarative transaction handling. So if you are using MyBatis with Spring or Guice please refer to their specific manuals.</p>
 
   <h5>Local Cache</h5>

src/site/xdoc/sqlmap-xml.xml

@@ -245,6 +245,11 @@ ps.setInt(1,id);]]></source>
                 be returned by the statement and gives a name to each one. Names are separated by commas.
               </td>
             </tr>
+            <tr>
+              <td><code>affectData</code></td>
+              <td>Set this to true when writing a INSERT, UPDATE or DELETE statement that returns data so that the transaction is controlled properly. Also see <a href="./java-api.html#transaction-control-methods">Transaction Control Method</a>. Default: <code>false</code> (since 3.5.12)
+              </td>
+            </tr>
           </tbody>
         </table>
       </subsection>
@@ -491,6 +496,18 @@ ps.setInt(1,id);]]></source>
             </tr>
           </tbody>
         </table>
+
+        <p>
+          As an irregular case, some databases allow INSERT, UPDATE or DELETE statement to return result set (e.g. <code>RETURNING</code> clause of PostgreSQL and MariaDB or <code>OUTPUT</code> clause of MS SQL Server). This type of statement must be written as <code><![CDATA[<select>]]></code> to map the returned data.
+        </p>
+
+        <source><![CDATA[<select id="insertAndGetAuthor" resultType="domain.blog.Author"
+      affectData="true" flushCache="true">
+  insert into Author (username, password, email, bio)
+  values (#{username}, #{password}, #{email}, #{bio})
+  returning id, username, password, email, bio
+</select>]]></source>
+
       </subsection>
 
       <subsection name="sql">

src/site/zh/xdoc/java-api.xml

@@ -245,15 +245,15 @@ public interface ResultHandler<T> {
   <p>当你将 <code>ExecutorType</code> 设置为 <code>ExecutorType.BATCH</code> 时，可以使用这个方法清除（执行）缓存在 JDBC 驱动类中的批量更新语句。</p>
   <source><![CDATA[List<BatchResult> flushStatements()]]></source>
 
-  <h5>事务控制方法</h5>
+  <h5 id="transaction-control-methods">事务控制方法</h5>
   <p>
     有四个方法用来控制事务作用域。当然，如果你已经设置了自动提交或你使用了外部事务管理器，这些方法就没什么作用了。然而，如果你正在使用由 Connection 实例控制的 JDBC 事务管理器，那么这四个方法就会派上用场：
   </p>
   <source>void commit()
 void commit(boolean force)
 void rollback()
 void rollback(boolean force)</source>
-  <p>默认情况下 MyBatis 不会自动提交事务，除非它侦测到调用了插入、更新或删除方法改变了数据库。如果你没有使用这些方法提交修改，那么你可以在 commit 和 rollback 方法参数中传入 true 值，来保证事务被正常提交（注意，在自动提交模式或者使用了外部事务管理器的情况下，设置 force 值对 session 无效）。大部分情况下你无需调用 rollback()，因为 MyBatis 会在你没有调用 commit 时替你完成回滚操作。不过，当你要在一个可能多次提交或回滚的 session 中详细控制事务，回滚操作就派上用场了。</p>
+  <p>默认情况下 MyBatis 不会自动提交事务，除非它侦测到调用了插入、更新、删除或 select with <code>affectData</code> enabled 方法改变了数据库。如果你没有使用这些方法提交修改，那么你可以在 commit 和 rollback 方法参数中传入 true 值，来保证事务被正常提交（注意，在自动提交模式或者使用了外部事务管理器的情况下，设置 force 值对 session 无效）。大部分情况下你无需调用 rollback()，因为 MyBatis 会在你没有调用 commit 时替你完成回滚操作。不过，当你要在一个可能多次提交或回滚的 session 中详细控制事务，回滚操作就派上用场了。</p>
   <p><span class="label important">提示</span> MyBatis-Spring 和 MyBatis-Guice 提供了声明式事务处理，所以如果你在使用 Mybatis 的同时使用了 Spring 或者 Guice，请参考它们的手册以获取更多的内容。</p>
 
 <h5>本地缓存</h5>