From 35581370b2140cb79966f233aa356afaadf03d53 Mon Sep 17 00:00:00 2001
From: Kazuki Shimizu <kazuki43zoo@gmail.com>
Date: Sun, 22 Mar 2020 02:52:22 +0900
Subject: [PATCH] Update documentation for gh-1771

---
 .../java/org/apache/ibatis/annotations/Many.java     |  1 +
 src/main/java/org/apache/ibatis/annotations/One.java |  1 +
 src/site/es/xdoc/java-api.xml                        |  8 +++++---
 src/site/ja/xdoc/java-api.xml                        | 10 +++++++---
 src/site/ko/xdoc/java-api.xml                        |  8 ++++++--
 src/site/xdoc/java-api.xml                           | 10 +++++++---
 src/site/zh/xdoc/java-api.xml                        | 12 ++++++++++--
 7 files changed, 37 insertions(+), 13 deletions(-)

diff --git a/src/main/java/org/apache/ibatis/annotations/Many.java b/src/main/java/org/apache/ibatis/annotations/Many.java
index 7bae885bfbb..f15b994b3ce 100644
--- a/src/main/java/org/apache/ibatis/annotations/Many.java
+++ b/src/main/java/org/apache/ibatis/annotations/Many.java
@@ -44,6 +44,7 @@
    * Returns the result map id used to map collection.
    *
    * @return the result map id
+   * @since 3.5.5
    */
   String resultMap() default "";
 
diff --git a/src/main/java/org/apache/ibatis/annotations/One.java b/src/main/java/org/apache/ibatis/annotations/One.java
index 142bd2a1742..53be73131e0 100644
--- a/src/main/java/org/apache/ibatis/annotations/One.java
+++ b/src/main/java/org/apache/ibatis/annotations/One.java
@@ -44,6 +44,7 @@
    * Returns the result map id used to map single object.
    *
    * @return the result map id
+   * @since 3.5.5
    */
   String resultMap() default "";
 
diff --git a/src/site/es/xdoc/java-api.xml b/src/site/es/xdoc/java-api.xml
index 58823e116e9..8f6543e5d6e 100644
--- a/src/site/es/xdoc/java-api.xml
+++ b/src/site/es/xdoc/java-api.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 
-       Copyright 2009-2019 the original author or authors.
+       Copyright 2009-2020 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.
@@ -389,16 +389,18 @@ void rollback(boolean force)</source>
         <td>N/A</td>
         <td><code>&lt;association&gt;</code></td>
         <td>
-        Un mapeo a una propiedad que contiene un tipo complejo. Atributos: select, que contiene el nombre completamente cualificado de un mapped statement (o un método de mapper) que puede cargar la instancia del tipo indicado,
+        Un mapeo a una propiedad que contiene un tipo complejo. Atributos: select, que contiene el nombre completamente cualificado de un mapped statement (o un método de mapper) que puede cargar la instancia del tipo indicado.
         <code>fetchType</code>, que sobrescribe el parámetro global de configuración <code>lazyLoadingEnabled</code> para este mapeo.
+        <code>resultMap</code>(available since 3.5.5), which is the fully qualified name of a result map that map to a single container object from select result.
         Nota: Habrás visto que el mapeo de tipo join no se soporta mediante el API de anotaciones. Esto es debido a las limitaciones de las anotaciones en Java que no permiten referencias circulares.</td>
       </tr>
       <tr>
         <td><code>@Many</code></td>
         <td>N/A</td>
         <td><code>&lt;collection&gt;</code></td>
-        <td>Un mapeo a una propiedad que contiene una colección de tipos complejos. Atributos: select, que contiene el nombre completamente cualificado de un mapped statement (o un método de mapper) que puede cargar la instancia del tipo indicado,
+        <td>Un mapeo a una propiedad que contiene una colección de tipos complejos. Atributos: select, que contiene el nombre completamente cualificado de un mapped statement (o un método de mapper) que puede cargar la instancia del tipo indicado.
         <code>fetchType</code>, que sobrescribe el parámetro global de configuración <code>lazyLoadingEnabled</code> para este mapeo.
+        <code>resultMap</code>(available since 3.5.5), which is the fully qualified name of a result map that map to collection object from select result.
         Nota: Habrás visto que el mapeo de tipo join no se soporta mediante el API de anotaciones. Esto es debido a las limitaciones de las anotaciones en Java que no permiten referencias circulares.</td>
       </tr>
       <tr>
diff --git a/src/site/ja/xdoc/java-api.xml b/src/site/ja/xdoc/java-api.xml
index 6c13aa79c42..69caa5d0b4c 100644
--- a/src/site/ja/xdoc/java-api.xml
+++ b/src/site/ja/xdoc/java-api.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 
-       Copyright 2009-2019 the original author or authors.
+       Copyright 2009-2020 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.
@@ -397,16 +397,20 @@ void rollback(boolean force)</source>
         <td><code>@One</code></td>
         <td>N/A</td>
         <td><code>&lt;association&gt;</code></td>
-        <td>複雑型のプロパティのマッピング情報を定義します。属性: <code>select</code>, <code>fetchType</code>. select は適切な型を読み込むことができるマップドステートメント（Mapper メソッド）の完全修飾名です。
+        <td>複雑型のプロパティのマッピング情報を定義します。属性: <code>select</code>, <code>fetchType</code>, <code>resultMap</code>(3.5.5以降で利用可能).
+        select は適切な型を読み込むことができるマップドステートメント（Mapper メソッド）の完全修飾名です。
         fetchType はグローバルな設定 <code>lazyLoadingEnabled</code> をオーバーライドする場合に指定します。
+        resultMap は結果列を単一のコンテナオブジェクト(JavaBeanなど)へマッピングするための結果マップの完全修飾名を指定します。
         <span class="label important">NOTE</span> アノテーション API では結合マッピングがサポートされていません。これは Java アノテーションでは循環参照が許可されないためです。</td>
       </tr>
       <tr>
         <td><code>@Many</code></td>
         <td>N/A</td>
         <td><code>&lt;collection&gt;</code></td>
-        <td>複雑型のプロパティのマッピング情報を定義します。属性: <code>select</code>, <code>fetchType</code>. select は適切な型のコレクションを読み込むことができるマップドステートメント（Mapper メソッド）の完全修飾名です。
+        <td>複雑型のプロパティのマッピング情報を定義します。属性: <code>select</code>, <code>fetchType</code>, <code>resultMap</code>(3.5.5以降で利用可能).
+        select は適切な型のコレクションを読み込むことができるマップドステートメント（Mapper メソッド）の完全修飾名です。
         fetchType はグローバルな設定 <code>lazyLoadingEnabled</code> をオーバーライドする場合に指定します。
+        resultMap は結果列をコレクションオブジェクト(JavaBeanのリストなど)へマッピングするための結果マップの完全修飾名を指定します。
         <span class="label important">NOTE</span> アノテーション API では結合マッピングがサポートされていません。これは Java アノテーションでは循環参照が許可されないためです。</td>
       </tr>
       <tr>
diff --git a/src/site/ko/xdoc/java-api.xml b/src/site/ko/xdoc/java-api.xml
index ddff7f06f07..82fd1214170 100644
--- a/src/site/ko/xdoc/java-api.xml
+++ b/src/site/ko/xdoc/java-api.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 
-       Copyright 2009-2019 the original author or authors.
+       Copyright 2009-2020 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.
@@ -503,7 +503,9 @@ void rollback(boolean force)</source>
         <td>N/A</td>
         <td><code>&lt;association&gt;</code></td>
         <td>복잡한 타입의 한개의 프로퍼티를 위한 매핑이다.
-		사용가능한 속성들 : select(매핑 구문의 이름, 예를들어 매퍼 메소드)
+		사용가능한 속성들 : select(매핑 구문의 이름, 예를들어 매퍼 메소드).
+		<code>fetchType</code>, which supersedes the global configuration parameter <code>lazyLoadingEnabled</code> for this mapping.
+		<code>resultMap</code>(available since 3.5.5), which is the fully qualified name of a result map that map to a single container object from select result.
 		Note: 조인 매핑은 애노테이션 API 를 통해서는 지원되지 않는다는 것을 알아야 한다.
 		순환(circular) 참조를 허용하지 않는 자바 애노테이션의 제약사항때문이다.</td>
       </tr>
@@ -513,6 +515,8 @@ void rollback(boolean force)</source>
         <td><code>&lt;collection&gt;</code></td>
         <td>복잡한 타입의 collection 프로퍼티를 위한 매핑이다.
 		사용가능한 속성들 : select(매핑 구문의 이름, 예를들어 매퍼 메소드)
+		<code>fetchType</code>, which supersedes the global configuration parameter <code>lazyLoadingEnabled</code> for this mapping.
+		<code>resultMap</code>(available since 3.5.5), which is the fully qualified name of a result map that map to collection object from select result.
 		Note: 조인 매핑은 애노테이션 API 를 통해서는 지원되지 않는다는 것을 알아야 한다.
 		순환(circular) 참조를 허용하지 않는 자바 애노테이션의 제약사항때문이다.</td>
       </tr>
diff --git a/src/site/xdoc/java-api.xml b/src/site/xdoc/java-api.xml
index 2f257faa824..922c7ab3ad2 100644
--- a/src/site/xdoc/java-api.xml
+++ b/src/site/xdoc/java-api.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 
-       Copyright 2009-2019 the original author or authors.
+       Copyright 2009-2020 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.
@@ -418,9 +418,11 @@ void rollback(boolean force)</source>
         <td>N/A</td>
         <td><code>&lt;association&gt;</code></td>
         <td>A mapping to a single property value of a complex type. Attributes: <code>select</code>, which is the fully
-        qualified name of a mapped statement (i.e. mapper method) that can load an instance of the appropriate type,
+        qualified name of a mapped statement (i.e. mapper method) that can load an instance of the appropriate type.
         <code>fetchType</code>, which supersedes the global configuration parameter <code>lazyLoadingEnabled</code> for this
         mapping.
+        <code>resultMap</code>(available since 3.5.5), which is the fully qualified name of a result map that map to
+        a single container object from select result.
         <span class="label important">NOTE</span> You will notice that join mapping is not supported via the Annotations API.
         This is due to the limitation in Java Annotations that does not allow for circular references.</td>
       </tr>
@@ -430,8 +432,10 @@ void rollback(boolean force)</source>
         <td><code>&lt;collection&gt;</code></td>
         <td>A mapping to a collection property of a complex type. Attributes: <code>select</code>, which is the fully
         qualified name of a mapped statement (i.e. mapper method) that can load a collection of instances of the appropriate
-        types, <code>fetchType</code>, which supersedes the global configuration parameter <code>lazyLoadingEnabled</code> for this
+        types. <code>fetchType</code>, which supersedes the global configuration parameter <code>lazyLoadingEnabled</code> for this
         mapping.
+        <code>resultMap</code>(available since 3.5.5), which is the fully qualified name of a result map that map to
+        collection object from select result.
         <span class="label important">NOTE</span> You will notice that join mapping is not supported via the
         Annotations API. This is due to the limitation in Java Annotations that does not allow for circular references.</td>
       </tr>
diff --git a/src/site/zh/xdoc/java-api.xml b/src/site/zh/xdoc/java-api.xml
index a943e09bf17..66eaca3ecc4 100644
--- a/src/site/zh/xdoc/java-api.xml
+++ b/src/site/zh/xdoc/java-api.xml
@@ -385,13 +385,21 @@ try (SqlSession session = sqlSessionFactory.openSession()) {
         <td><code>@One</code></td>
         <td>N/A</td>
         <td><code>&lt;association&gt;</code></td>
-        <td>复杂类型的单个属性映射。属性：<code>select</code>，指定可加载合适类型实例的映射语句（也就是映射器方法）全限定名；<code>fetchType</code>，指定在该映射中覆盖全局配置参数 <code>lazyLoadingEnabled</code>。<span class="label important">提示</span> 注解 API 不支持联合映射。这是由于 Java 注解不允许产生循环引用。</td>
+        <td>复杂类型的单个属性映射。属性：
+        <code>select</code>，指定可加载合适类型实例的映射语句（也就是映射器方法）全限定名；
+        <code>fetchType</code>，指定在该映射中覆盖全局配置参数 <code>lazyLoadingEnabled</code>；
+        <code>resultMap</code>(available since 3.5.5), which is the fully qualified name of a result map that map to a single container object from select result。
+        <span class="label important">提示</span> 注解 API 不支持联合映射。这是由于 Java 注解不允许产生循环引用。</td>
       </tr>
       <tr>
         <td><code>@Many</code></td>
         <td>N/A</td>
         <td><code>&lt;collection&gt;</code></td>
-        <td>复杂类型的集合属性映射。属性：<code>select</code>，指定可加载合适类型实例集合的映射语句（也就是映射器方法）全限定名；<code>fetchType</code>，指定在该映射中覆盖全局配置参数 <code>lazyLoadingEnabled</code>。<span class="label important">提示</span> 注解 API 不支持联合映射。这是由于 Java 注解不允许产生循环引用。</td>
+        <td>复杂类型的集合属性映射。属性：
+        <code>select</code>，指定可加载合适类型实例集合的映射语句（也就是映射器方法）全限定名；
+        <code>fetchType</code>，指定在该映射中覆盖全局配置参数 <code>lazyLoadingEnabled</code>
+        <code>resultMap</code>(available since 3.5.5), which is the fully qualified name of a result map that map to collection object from select result。
+        <span class="label important">提示</span> 注解 API 不支持联合映射。这是由于 Java 注解不允许产生循环引用。</td>
       </tr>
       <tr>
         <td><code>@MapKey</code></td>