refs mybatis#721 Updated documentation.

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

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 
-       Copyright 2009-2016 the original author or authors.
+       Copyright 2009-2017 the original author or authors.
 
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
@@ -893,31 +893,46 @@ public class User {
 
         <h4>constructor</h4>
 
-        <source><![CDATA[<constructor>
-   <idArg column="id" javaType="int"/>
-   <arg column="username" javaType="String"/>
-</constructor>]]></source>
-
         <p>Aunque las propiedades funcionan bien en clases tipo Data Transfer Object (DTO), y posiblemente en la mayor parte de tu modelo de dominio, hay algunos casos en los que puedes querer clases inmutables. En ocasiones, las tablas que contienen información que nunca o raramente cambia son apropiadas para las clases inmutables. La inyección en el constructor te permite informar valores durante la instanciación de la clase, sin necesidad de exponer métodos públicos. MyBatis tambien soporta propiedades privadas para conseguir esto mismo pero habrá quien prefiera utilizar la inyección de Constructor. El elemento constructor  permite hacer esto.
         </p>
 
         <p>Dado el siguiente constructor:</p>
 
         <source><![CDATA[public class User {
    //...
-   public User(int id, String username) {
+   public User(Integer id, String username, int age) {
      //...
   }
 //...
 }]]></source>
 
-        <p>Para poder inyectar los resultados en el constructor, MyBatis necesita identificar el constructor por el tipo de sus parámetros. Java no tiene forma de obtener los nombres de los parámetros de un constructor por introspección. Por tanto al crear un elemento constructor, debes asegurar que los argumentos están correctamente ordenados y que has informado los tipos de datos.</p>
+        <p>
+          In order to inject the results into the constructor, MyBatis needs to identify the constructor for somehow.
+          In the following example, MyBatis searches a constructor declared with three parameters: <code>java.lang.Integer</code>, <code>java.lang.String</code> and <code>int</code> in this order.
+        </p>
 
         <source><![CDATA[<constructor>
    <idArg column="id" javaType="int"/>
    <arg column="username" javaType="String"/>
+   <arg column="age" javaType="_int"/>
+</constructor>]]></source>
+
+        <p>
+          When you are dealing with a constructor with many parameters, maintaining the order of arg elements is error-prone.<br />
+          Since 3.4.3, by specifying the name of each parameter, you can write arg elements in any order. To reference constructor parameters by their names, you can either add <code>@Param</code> annotation to them or compile the project with '-parameters' compiler option and enable <code>useActualParamName</code> (this option is enabled by default).
+          The following example is valid for the same constructor even though the order of the second and the third parameters does not match with the declared order.
+        </p>
+
+        <source><![CDATA[<constructor>
+   <idArg column="id" javaType="int" name="id" />
+   <arg column="age" javaType="_int" name="age" />
+   <arg column="username" javaType="String" name="username" />
 </constructor>]]></source>
 
+        <p>
+          <code>javaType</code> can be omitted if there is a property with the same name and type.
+        </p>
+
         <p>El resto de atributos son los mismos que los de los elementos id y result.</p>
 
         <table>
@@ -958,6 +973,12 @@ public class User {
               <td>El id de un resultmap que puede mapear los resultados anidados de este argumento al grafo de objetos (object graph) apropiado. Es una alternativa a llamar a otro select statement. Permite hacer join de varias tablas en un solo ResultSet. Un ResultSet de este tipo puede contener bloques repetidos de datos que deben ser descompuestos y mapeados apropiadamente a un árbol de objetos (object graph). MyBatis te permite encadenar RestultMaps para tratar resultados anidados.  Ver el elemento association  para más información.
               </td>
             </tr>
+            <tr>
+              <td><code>name</code></td>
+              <td>
+                The name of the constructor parameter. Specifying name allows you to write arg elements in any order. See the above explanation. Since 3.4.3.
+              </td>
+            </tr>
           </tbody>
         </table>
 

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

@@ -1008,11 +1008,6 @@ public class User {
 
         <h4>constructor</h4>
 
-        <source><![CDATA[<constructor>
-   <idArg column="id" javaType="int"/>
-   <arg column="username" javaType="String"/>
-</constructor>]]></source>
-
         <p>
           ほとんどの DTO (Data Transfer Object) やドメインモデルではプロパティを使って値を設定することができますが、時にはイミュータブルなクラスを使いたい場合もあるかも知れません。
           通常更新されることのない参照用データを含むテーブルなどはイミュータブルクラスに向いています。
@@ -1027,23 +1022,37 @@ public class User {
 
         <source><![CDATA[public class User {
    //...
-   public User(int id, String username) {
+   public User(Integer id, String username, int age) {
   //...
   }
 //...
 }]]></source>
 
-        <p>
-          このコンストラクタに結果をインジェクトするためには、パラメーターの型によってコンストラクタを識別する必要があります。
-          Java では引数の名前を取得する方法がありませんので、constructor 要素を定義する場合は引数を正しい順番に並べ、適切なデータ型を指定するようにしてください。
-        </p>
-
+        <p>コンストラクタ経由で値をマップするためには、指定された引数にマッチするコンストラクタを特定する必要があります。
+          下記の例では、MyBatis は３つの引数 <code>java.lang.Integer</code>, <code>java.lang.String</code>, <code>int</code> をこの順番で持つコンストラクタを探します。</p>
 
         <source><![CDATA[<constructor>
    <idArg column="id" javaType="int"/>
    <arg column="username" javaType="String"/>
+   <arg column="arg" javaType="_int"/>
 </constructor>]]></source>
 
+        <p>
+          上記の指定方法では引数の型を順番通りに並べる必要がありますが、引数の多いコンストラクタを扱うのには向いていません。<br />
+          3.4.3 以降では、引数名を指定することによって arg 要素を順不同で記述できるようになりました。引数を名前で指定するためには、各引数に <code>@Param</code> アノテーションを追加するか、プロジェクトを '-parameters' オプション付きでコンパイルし、<code>useActualParamName</code> に true （デフォルト値です）を設定します。
+          下記の指定では２番めと３番目の引数の順番がコンストラクタの宣言と異なりますが、引数名が指定されているので正しく動作します。
+        </p>
+
+        <source><![CDATA[<constructor>
+   <idArg column="id" javaType="int" name="id" />
+   <arg column="age" javaType="_int" name="age" />
+   <arg column="username" javaType="String" name="username" />
+</constructor>]]></source>
+
+        <p>
+          引数と同じ名前、同じ型を持つプロパティが存在する場合 <code>javaType</code> は省略可能です。
+        </p>
+
         <p>
           それ以外の属性とルールについては通常の id, result 要素と同じです。
         </p>
@@ -1105,6 +1114,13 @@ public class User {
                 詳細は association 要素の説明を参照してください。
               </td>
             </tr>
+            <tr>
+              <td><code>name</code></td>
+              <td>
+                コンストラクタ引数の名前を指定します。引数名を指定することで arg 要素を順不同で記述できるようになります。詳細は上記の説明を参照してください。
+                導入されたバージョン: 3.4.3
+              </td>
+            </tr>
           </tbody>
         </table>
 

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

@@ -889,11 +889,6 @@ public class User {
 
         <h4>constructor</h4>
 
-        <source><![CDATA[<constructor>
-   <idArg column="id" javaType="int"/>
-   <arg column="username" javaType="String"/>
-</constructor>]]></source>
-
         <p>프로퍼티가 데이터 전송 객체(DTO) 타입 클래스로 작동한다. 
 		변하지 않는 클래스를 사용하고자 하는 경우가 있다. 
 		거의 변하지 않는 데이터를 가진 테이블은 종종 이 변하지 않는 클래스에 적합하다. 
@@ -905,21 +900,39 @@ public class User {
 
         <source><![CDATA[public class User {
    //...
-   public User(int id, String username) {
+   public User(Integer id, String username, int age) {
      //...
   }
 //...
 }]]></source>
 
-        <p>결과를 생성자에 주입하기 위해 마이바티스는 파라미터 타입에 일치하는 생성자를 찾을 필요가 있다. 
-		자바는 파라미터 이름에서 타입을 체크할 방법이 없다. 
-		그래서 constructor엘리먼트를 생성할 때 인자의 순서에 주의하고 데이터 타입을 명시해야 한다.</p>
+        <p>
+          In order to inject the results into the constructor, MyBatis needs to identify the constructor for somehow.
+          In the following example, MyBatis searches a constructor declared with three parameters: <code>java.lang.Integer</code>, <code>java.lang.String</code> and <code>int</code> in this order.
+        </p>
 
         <source><![CDATA[<constructor>
    <idArg column="id" javaType="int"/>
    <arg column="username" javaType="String"/>
+   <arg column="age" javaType="_int"/>
+</constructor>]]></source>
+
+        <p>
+          When you are dealing with a constructor with many parameters, maintaining the order of arg elements is error-prone.<br />
+          Since 3.4.3, by specifying the name of each parameter, you can write arg elements in any order. To reference constructor parameters by their names, you can either add <code>@Param</code> annotation to them or compile the project with '-parameters' compiler option and enable <code>useActualParamName</code> (this option is enabled by default).
+          The following example is valid for the same constructor even though the order of the second and the third parameters does not match with the declared order.
+        </p>
+
+        <source><![CDATA[<constructor>
+   <idArg column="id" javaType="int" name="id" />
+   <arg column="age" javaType="_int" name="age" />
+   <arg column="username" javaType="String" name="username" />
 </constructor>]]></source>
 
+        <p>
+          <code>javaType</code> can be omitted if there is a property with the same name and type.
+        </p>
+
         <p>나머지 속성과 규칙은 id와 result엘리먼트와 동일하다.</p>
 
         <table>
@@ -969,6 +982,12 @@ public class User {
 			  가능하게 하기 위해서 내포된 결과를 다루도록 결과맵을 “연결”하자. 
 			  자세히 알기 위해서는 association엘리먼트를 보라.</td>
             </tr>
+            <tr>
+              <td><code>name</code></td>
+              <td>
+                The name of the constructor parameter. Specifying name allows you to write arg elements in any order. See the above explanation. Since 3.4.3.
+              </td>
+            </tr>
           </tbody>
         </table>
 

src/site/xdoc/sqlmap-xml.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 
-       Copyright 2009-2016 the original author or authors.
+       Copyright 2009-2017 the original author or authors.
 
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
@@ -1093,11 +1093,6 @@ public class User {
 
         <h4>constructor</h4>
 
-        <source><![CDATA[<constructor>
-   <idArg column="id" javaType="int"/>
-   <arg column="username" javaType="String"/>
-</constructor>]]></source>
-
         <p>
           While properties will work for most Data Transfer Object (DTO) type classes, and likely most of your
           domain model, there may be some cases where you want to use immutable classes. Often tables that
@@ -1115,25 +1110,39 @@ public class User {
 
         <source><![CDATA[public class User {
    //...
-   public User(int id, String username) {
+   public User(Integer id, String username, int age) {
      //...
   }
 //...
 }]]></source>
 
         <p>
-          In order to inject the results into the constructor, MyBatis needs to identify the constructor by
-          the type of its parameters. Java has no way to introspect (or reflect) on parameter names. So when
-          creating a constructor element, ensure that the arguments are in order, and that the data types are
-          specified.
+          In order to inject the results into the constructor, MyBatis needs to identify the constructor for somehow.
+          In the following example, MyBatis searches a constructor declared with three parameters: <code>java.lang.Integer</code>, <code>java.lang.String</code> and <code>int</code> in this order.
         </p>
 
-
         <source><![CDATA[<constructor>
    <idArg column="id" javaType="int"/>
    <arg column="username" javaType="String"/>
+   <arg column="age" javaType="_int"/>
 </constructor>]]></source>
 
+        <p>
+          When you are dealing with a constructor with many parameters, maintaining the order of arg elements is error-prone.<br />
+          Since 3.4.3, by specifying the name of each parameter, you can write arg elements in any order. To reference constructor parameters by their names, you can either add <code>@Param</code> annotation to them or compile the project with '-parameters' compiler option and enable <code>useActualParamName</code> (this option is enabled by default).
+          The following example is valid for the same constructor even though the order of the second and the third parameters does not match with the declared order.
+        </p>
+
+        <source><![CDATA[<constructor>
+   <idArg column="id" javaType="int" name="id" />
+   <arg column="age" javaType="_int" name="age" />
+   <arg column="username" javaType="String" name="username" />
+</constructor>]]></source>
+
+        <p>
+          <code>javaType</code> can be omitted if there is a property with the same name and type.
+        </p>
+
         <p>
           The rest of the attributes and rules are the same as for the regular id and result elements.
         </p>
@@ -1200,6 +1209,12 @@ public class User {
                 Association element below for more.
               </td>
             </tr>
+            <tr>
+              <td><code>name</code></td>
+              <td>
+                The name of the constructor parameter. Specifying name allows you to write arg elements in any order. See the above explanation. Since 3.4.3.
+              </td>
+            </tr>
           </tbody>
         </table>
 

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

@@ -958,11 +958,6 @@ jdbcType
 
         <h4>构造方法</h4>
 
-        <source><![CDATA[<constructor>
-   <idArg column="id" javaType="int"/>
-   <arg column="username" javaType="String"/>
-</constructor>]]></source>
-
         <p>
 对于大多数数据传输对象(Data Transfer Object,DTO)类型,属性可以起作用,而且像
 你绝大多数的领域模型,
@@ -980,23 +975,39 @@ jdbcType
 
         <source><![CDATA[public class User {
    //...
-   public User(int id, String username) {
+   public User(Integer id, String username, int age) {
      //...
   }
 //...
 }]]></source>
 
         <p>
-为了向这个构造方法中注入结果,MyBatis 需要通过它的参数的类型来标识构造方法。
-Java 没有自查(反射)参数名的方法。所以当创建一个构造方法元素时,保证参数是按顺序
-排列的,而且数据类型也是确定的。
+          In order to inject the results into the constructor, MyBatis needs to identify the constructor for somehow.
+          In the following example, MyBatis searches a constructor declared with three parameters: <code>java.lang.Integer</code>, <code>java.lang.String</code> and <code>int</code> in this order.
         </p>
 
         <source><![CDATA[<constructor>
    <idArg column="id" javaType="int"/>
    <arg column="username" javaType="String"/>
+   <arg column="age" javaType="_int"/>
+</constructor>]]></source>
+
+        <p>
+          When you are dealing with a constructor with many parameters, maintaining the order of arg elements is error-prone.<br />
+          Since 3.4.3, by specifying the name of each parameter, you can write arg elements in any order. To reference constructor parameters by their names, you can either add <code>@Param</code> annotation to them or compile the project with '-parameters' compiler option and enable <code>useActualParamName</code> (this option is enabled by default).
+          The following example is valid for the same constructor even though the order of the second and the third parameters does not match with the declared order.
+        </p>
+
+        <source><![CDATA[<constructor>
+   <idArg column="id" javaType="int" name="id" />
+   <arg column="age" javaType="_int" name="age" />
+   <arg column="username" javaType="String" name="username" />
 </constructor>]]></source>
 
+        <p>
+          <code>javaType</code> can be omitted if there is a property with the same name and type.
+        </p>
+
         <p>
 剩余的属性和规则和固定的 id 和 result 元素是相同的。
         </p>
@@ -1057,6 +1068,12 @@ jdbcType
                 ResultMap的ID，可以将嵌套的结果集映射到一个合适的对象树中，功能和select属性相似，它可以实现将多表连接操作的结果映射成一个单一的<code>ResultSet</code>。这样的<code>ResultSet</code>将会将包含重复或部分数据重复的结果集正确的映射到嵌套的对象树中。为了实现它, MyBatis允许你 “串联” ResultMap,以便解决嵌套结果集的问题。想了解更多内容，请参考下面的Association元素。
               </td>
             </tr>
+            <tr>
+              <td><code>name</code></td>
+              <td>
+                The name of the constructor parameter. Specifying name allows you to write arg elements in any order. See the above explanation. Since 3.4.3.
+              </td>
+            </tr>
           </tbody>
         </table>