Skip to content

Commit 5fb7fcd

Browse files
harawataharawata
committed
refs mybatis#721 Updated documentation.
1 parent b0d582b commit 5fb7fcd

File tree

5 files changed

+137
-49
lines changed

5 files changed

+137
-49
lines changed

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

Lines changed: 29 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<?xml version="1.0" encoding="UTF-8"?>
22
<!--
33
4-
Copyright 2009-2016 the original author or authors.
4+
Copyright 2009-2017 the original author or authors.
55
66
Licensed under the Apache License, Version 2.0 (the "License");
77
you may not use this file except in compliance with the License.
@@ -893,31 +893,46 @@ public class User {
893893

894894
<h4>constructor</h4>
895895

896-
<source><![CDATA[<constructor>
897-
<idArg column="id" javaType="int"/>
898-
<arg column="username" javaType="String"/>
899-
</constructor>]]></source>
900-
901896
<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.
902897
</p>
903898

904899
<p>Dado el siguiente constructor:</p>
905900

906901
<source><![CDATA[public class User {
907902
//...
908-
public User(int id, String username) {
903+
public User(Integer id, String username, int age) {
909904
//...
910905
}
911906
//...
912907
}]]></source>
913908

914-
<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>
909+
<p>
910+
In order to inject the results into the constructor, MyBatis needs to identify the constructor for somehow.
911+
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.
912+
</p>
915913

916914
<source><![CDATA[<constructor>
917915
<idArg column="id" javaType="int"/>
918916
<arg column="username" javaType="String"/>
917+
<arg column="age" javaType="_int"/>
918+
</constructor>]]></source>
919+
920+
<p>
921+
When you are dealing with a constructor with many parameters, maintaining the order of arg elements is error-prone.<br />
922+
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).
923+
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.
924+
</p>
925+
926+
<source><![CDATA[<constructor>
927+
<idArg column="id" javaType="int" name="id" />
928+
<arg column="age" javaType="_int" name="age" />
929+
<arg column="username" javaType="String" name="username" />
919930
</constructor>]]></source>
920931

932+
<p>
933+
<code>javaType</code> can be omitted if there is a property with the same name and type.
934+
</p>
935+
921936
<p>El resto de atributos son los mismos que los de los elementos id y result.</p>
922937

923938
<table>
@@ -958,6 +973,12 @@ public class User {
958973
<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.
959974
</td>
960975
</tr>
976+
<tr>
977+
<td><code>name</code></td>
978+
<td>
979+
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.
980+
</td>
981+
</tr>
961982
</tbody>
962983
</table>
963984

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

Lines changed: 27 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1008,11 +1008,6 @@ public class User {
10081008

10091009
<h4>constructor</h4>
10101010

1011-
<source><![CDATA[<constructor>
1012-
<idArg column="id" javaType="int"/>
1013-
<arg column="username" javaType="String"/>
1014-
</constructor>]]></source>
1015-
10161011
<p>
10171012
ほとんどの DTO (Data Transfer Object) やドメインモデルではプロパティを使って値を設定することができますが、時にはイミュータブルなクラスを使いたい場合もあるかも知れません。
10181013
通常更新されることのない参照用データを含むテーブルなどはイミュータブルクラスに向いています。
@@ -1027,23 +1022,37 @@ public class User {
10271022

10281023
<source><![CDATA[public class User {
10291024
//...
1030-
public User(int id, String username) {
1025+
public User(Integer id, String username, int age) {
10311026
//...
10321027
}
10331028
//...
10341029
}]]></source>
10351030

1036-
<p>
1037-
このコンストラクタに結果をインジェクトするためには、パラメーターの型によってコンストラクタを識別する必要があります。
1038-
Java では引数の名前を取得する方法がありませんので、constructor 要素を定義する場合は引数を正しい順番に並べ、適切なデータ型を指定するようにしてください。
1039-
</p>
1040-
1031+
<p>コンストラクタ経由で値をマップするためには、指定された引数にマッチするコンストラクタを特定する必要があります。
1032+
下記の例では、MyBatis は３つの引数 <code>java.lang.Integer</code>, <code>java.lang.String</code>, <code>int</code> をこの順番で持つコンストラクタを探します。</p>
10411033

10421034
<source><![CDATA[<constructor>
10431035
<idArg column="id" javaType="int"/>
10441036
<arg column="username" javaType="String"/>
1037+
<arg column="arg" javaType="_int"/>
10451038
</constructor>]]></source>
10461039

1040+
<p>
1041+
上記の指定方法では引数の型を順番通りに並べる必要がありますが、引数の多いコンストラクタを扱うのには向いていません。<br />
1042+
3.4.3 以降では、引数名を指定することによって arg 要素を順不同で記述できるようになりました。引数を名前で指定するためには、各引数に <code>@Param</code> アノテーションを追加するか、プロジェクトを '-parameters' オプション付きでコンパイルし、<code>useActualParamName</code> に true （デフォルト値です）を設定します。
1043+
下記の指定では２番めと３番目の引数の順番がコンストラクタの宣言と異なりますが、引数名が指定されているので正しく動作します。
1044+
</p>
1045+
1046+
<source><![CDATA[<constructor>
1047+
<idArg column="id" javaType="int" name="id" />
1048+
<arg column="age" javaType="_int" name="age" />
1049+
<arg column="username" javaType="String" name="username" />
1050+
</constructor>]]></source>
1051+
1052+
<p>
1053+
引数と同じ名前、同じ型を持つプロパティが存在する場合 <code>javaType</code> は省略可能です。
1054+
</p>
1055+
10471056
<p>
10481057
それ以外の属性とルールについては通常の id, result 要素と同じです。
10491058
</p>
@@ -1105,6 +1114,13 @@ public class User {
11051114
詳細は association 要素の説明を参照してください。
11061115
</td>
11071116
</tr>
1117+
<tr>
1118+
<td><code>name</code></td>
1119+
<td>
1120+
コンストラクタ引数の名前を指定します。引数名を指定することで arg 要素を順不同で記述できるようになります。詳細は上記の説明を参照してください。
1121+
導入されたバージョン: 3.4.3
1122+
</td>
1123+
</tr>
11081124
</tbody>
11091125
</table>
11101126

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

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -889,11 +889,6 @@ public class User {
889889

890890
<h4>constructor</h4>
891891

892-
<source><![CDATA[<constructor>
893-
<idArg column="id" javaType="int"/>
894-
<arg column="username" javaType="String"/>
895-
</constructor>]]></source>
896-
897892
<p>프로퍼티가 데이터 전송 객체(DTO) 타입 클래스로 작동한다.
898893
변하지 않는 클래스를 사용하고자 하는 경우가 있다.
899894
거의 변하지 않는 데이터를 가진 테이블은 종종 이 변하지 않는 클래스에 적합하다.
@@ -905,21 +900,39 @@ public class User {
905900

906901
<source><![CDATA[public class User {
907902
//...
908-
public User(int id, String username) {
903+
public User(Integer id, String username, int age) {
909904
//...
910905
}
911906
//...
912907
}]]></source>
913908

914-
<p>결과를 생성자에 주입하기 위해 마이바티스는 파라미터 타입에 일치하는 생성자를 찾을 필요가 있다.
915-
자바는 파라미터 이름에서 타입을 체크할 방법이 없다.
916-
그래서 constructor엘리먼트를 생성할 때 인자의 순서에 주의하고 데이터 타입을 명시해야 한다.</p>
909+
<p>
910+
In order to inject the results into the constructor, MyBatis needs to identify the constructor for somehow.
911+
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.
912+
</p>
917913

918914
<source><![CDATA[<constructor>
919915
<idArg column="id" javaType="int"/>
920916
<arg column="username" javaType="String"/>
917+
<arg column="age" javaType="_int"/>
918+
</constructor>]]></source>
919+
920+
<p>
921+
When you are dealing with a constructor with many parameters, maintaining the order of arg elements is error-prone.<br />
922+
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).
923+
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.
924+
</p>
925+
926+
<source><![CDATA[<constructor>
927+
<idArg column="id" javaType="int" name="id" />
928+
<arg column="age" javaType="_int" name="age" />
929+
<arg column="username" javaType="String" name="username" />
921930
</constructor>]]></source>
922931

932+
<p>
933+
<code>javaType</code> can be omitted if there is a property with the same name and type.
934+
</p>
935+
923936
<p>나머지 속성과 규칙은 id와 result엘리먼트와 동일하다.</p>
924937

925938
<table>
@@ -969,6 +982,12 @@ public class User {
969982
가능하게 하기 위해서 내포된 결과를 다루도록 결과맵을 “연결”하자.
970983
자세히 알기 위해서는 association엘리먼트를 보라.</td>
971984
</tr>
985+
<tr>
986+
<td><code>name</code></td>
987+
<td>
988+
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.
989+
</td>
990+
</tr>
972991
</tbody>
973992
</table>
974993

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

Lines changed: 27 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<?xml version="1.0" encoding="UTF-8"?>
22
<!--
33
4-
Copyright 2009-2016 the original author or authors.
4+
Copyright 2009-2017 the original author or authors.
55
66
Licensed under the Apache License, Version 2.0 (the "License");
77
you may not use this file except in compliance with the License.
@@ -1093,11 +1093,6 @@ public class User {
10931093

10941094
<h4>constructor</h4>
10951095

1096-
<source><![CDATA[<constructor>
1097-
<idArg column="id" javaType="int"/>
1098-
<arg column="username" javaType="String"/>
1099-
</constructor>]]></source>
1100-
11011096
<p>
11021097
While properties will work for most Data Transfer Object (DTO) type classes, and likely most of your
11031098
domain model, there may be some cases where you want to use immutable classes. Often tables that
@@ -1115,25 +1110,39 @@ public class User {
11151110

11161111
<source><![CDATA[public class User {
11171112
//...
1118-
public User(int id, String username) {
1113+
public User(Integer id, String username, int age) {
11191114
//...
11201115
}
11211116
//...
11221117
}]]></source>
11231118

11241119
<p>
1125-
In order to inject the results into the constructor, MyBatis needs to identify the constructor by
1126-
the type of its parameters. Java has no way to introspect (or reflect) on parameter names. So when
1127-
creating a constructor element, ensure that the arguments are in order, and that the data types are
1128-
specified.
1120+
In order to inject the results into the constructor, MyBatis needs to identify the constructor for somehow.
1121+
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.
11291122
</p>
11301123

1131-
11321124
<source><![CDATA[<constructor>
11331125
<idArg column="id" javaType="int"/>
11341126
<arg column="username" javaType="String"/>
1127+
<arg column="age" javaType="_int"/>
11351128
</constructor>]]></source>
11361129

1130+
<p>
1131+
When you are dealing with a constructor with many parameters, maintaining the order of arg elements is error-prone.<br />
1132+
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).
1133+
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.
1134+
</p>
1135+
1136+
<source><![CDATA[<constructor>
1137+
<idArg column="id" javaType="int" name="id" />
1138+
<arg column="age" javaType="_int" name="age" />
1139+
<arg column="username" javaType="String" name="username" />
1140+
</constructor>]]></source>
1141+
1142+
<p>
1143+
<code>javaType</code> can be omitted if there is a property with the same name and type.
1144+
</p>
1145+
11371146
<p>
11381147
The rest of the attributes and rules are the same as for the regular id and result elements.
11391148
</p>
@@ -1200,6 +1209,12 @@ public class User {
12001209
Association element below for more.
12011210
</td>
12021211
</tr>
1212+
<tr>
1213+
<td><code>name</code></td>
1214+
<td>
1215+
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.
1216+
</td>
1217+
</tr>
12031218
</tbody>
12041219
</table>
12051220

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

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -958,11 +958,6 @@ jdbcType
958958

959959
<h4>构造方法</h4>
960960

961-
<source><![CDATA[<constructor>
962-
<idArg column="id" javaType="int"/>
963-
<arg column="username" javaType="String"/>
964-
</constructor>]]></source>
965-
966961
<p>
967962
对于大多数数据传输对象(Data Transfer Object,DTO)类型,属性可以起作用,而且像
968963
你绝大多数的领域模型,
@@ -980,23 +975,39 @@ jdbcType
980975

981976
<source><![CDATA[public class User {
982977
//...
983-
public User(int id, String username) {
978+
public User(Integer id, String username, int age) {
984979
//...
985980
}
986981
//...
987982
}]]></source>
988983

989984
<p>
990-
为了向这个构造方法中注入结果,MyBatis 需要通过它的参数的类型来标识构造方法。
991-
Java 没有自查(反射)参数名的方法。所以当创建一个构造方法元素时,保证参数是按顺序
992-
排列的,而且数据类型也是确定的。
985+
In order to inject the results into the constructor, MyBatis needs to identify the constructor for somehow.
986+
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.
993987
</p>
994988

995989
<source><![CDATA[<constructor>
996990
<idArg column="id" javaType="int"/>
997991
<arg column="username" javaType="String"/>
992+
<arg column="age" javaType="_int"/>
993+
</constructor>]]></source>
994+
995+
<p>
996+
When you are dealing with a constructor with many parameters, maintaining the order of arg elements is error-prone.<br />
997+
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).
998+
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.
999+
</p>
1000+
1001+
<source><![CDATA[<constructor>
1002+
<idArg column="id" javaType="int" name="id" />
1003+
<arg column="age" javaType="_int" name="age" />
1004+
<arg column="username" javaType="String" name="username" />
9981005
</constructor>]]></source>
9991006

1007+
<p>
1008+
<code>javaType</code> can be omitted if there is a property with the same name and type.
1009+
</p>
1010+
10001011
<p>
10011012
剩余的属性和规则和固定的 id 和 result 元素是相同的。
10021013
</p>
@@ -1057,6 +1068,12 @@ jdbcType
10571068
ResultMap的ID，可以将嵌套的结果集映射到一个合适的对象树中，功能和select属性相似，它可以实现将多表连接操作的结果映射成一个单一的<code>ResultSet</code>。这样的<code>ResultSet</code>将会将包含重复或部分数据重复的结果集正确的映射到嵌套的对象树中。为了实现它, MyBatis允许你 “串联” ResultMap,以便解决嵌套结果集的问题。想了解更多内容，请参考下面的Association元素。
10581069
</td>
10591070
</tr>
1071+
<tr>
1072+
<td><code>name</code></td>
1073+
<td>
1074+
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.
1075+
</td>
1076+
</tr>
10601077
</tbody>
10611078
</table>
10621079

0 commit comments

Comments
 (0)