[cayenne] branch STABLE-4.2 updated: Improve javadocs for map() methods of SQLSelect and ColumnSelect

[nt...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ntimofeev pushed a commit to branch STABLE-4.2
in repository https://gitbox.apache.org/repos/asf/cayenne.git


The following commit(s) were added to refs/heads/STABLE-4.2 by this push:
     new 9a0c69b94 Improve javadocs for map() methods of SQLSelect and ColumnSelect
9a0c69b94 is described below

commit 9a0c69b948cac89e7af56e1da1b3c9f85d008d6e
Author: Nikita Timofeev <st...@gmail.com>
AuthorDate: Fri Jul 15 15:24:58 2022 +0300

    Improve javadocs for map() methods of SQLSelect and ColumnSelect
---
 .../main/java/org/apache/cayenne/query/ColumnSelect.java   | 11 ++++++++---
 .../src/main/java/org/apache/cayenne/query/SQLSelect.java  | 14 ++++++++++++++
 .../main/java/org/apache/cayenne/reflect/PojoMapper.java   | 12 ++++++++++--
 .../test/java/org/apache/cayenne/query/ColumnSelectIT.java |  1 -
 4 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/cayenne-server/src/main/java/org/apache/cayenne/query/ColumnSelect.java b/cayenne-server/src/main/java/org/apache/cayenne/query/ColumnSelect.java
index bc34d0d63..a4fc807f9 100644
--- a/cayenne-server/src/main/java/org/apache/cayenne/query/ColumnSelect.java
+++ b/cayenne-server/src/main/java/org/apache/cayenne/query/ColumnSelect.java
@@ -625,10 +625,15 @@ public class ColumnSelect<T> extends FluentSelect<T> {
     }
 
     /**
-     * Wrap result to given class.  Wrapper class should be public and have public constructor with no args.
-     * Columns order in the query should corespond to fields defined in that class.
+     * Maps result of this query by processing with a given function.
+     * <br/>
+     * Could be used to map plain Object[] to some domain-specific object.
+     * <br/>
+     * <b>Note:</b> this method could be called multiple time, result will be mapped by all functions in the call order.
+     * @param mapper function that maps result to the required type.
+     * @return this query with changed result type
+     * @param <E> new result type
      *
-     * @param mapper function that maps result to required form.
      * @since 4.2
      */
     @SuppressWarnings("unchecked")
diff --git a/cayenne-server/src/main/java/org/apache/cayenne/query/SQLSelect.java b/cayenne-server/src/main/java/org/apache/cayenne/query/SQLSelect.java
index 3278036fd..cd9f10943 100644
--- a/cayenne-server/src/main/java/org/apache/cayenne/query/SQLSelect.java
+++ b/cayenne-server/src/main/java/org/apache/cayenne/query/SQLSelect.java
@@ -687,6 +687,20 @@ public class SQLSelect<T> extends IndirectQuery implements Select<T> {
 		return this;
 	}
 
+	/**
+	 * Map result of this query by processing with a given function.
+	 * <br/>
+	 * Could be used to map plain Object[] to some domain-specific object.
+	 * <br/>
+	 * <b>Note:</b> this method could be called multiple time, result will be mapped by all functions in the call order.
+	 * @param mapper function that maps result to the required type.
+	 * @return this query with changed result type
+	 * @param <E> new result type
+	 *
+	 * @see ColumnSelect#map(Function)
+	 *
+	 * @since 4.2
+	 */
 	@SuppressWarnings("unchecked")
 	public <E> SQLSelect<E> map(Function<T, E> mapper) {
 		this.resultMapper = mapper;
diff --git a/cayenne-server/src/main/java/org/apache/cayenne/reflect/PojoMapper.java b/cayenne-server/src/main/java/org/apache/cayenne/reflect/PojoMapper.java
index c0abf6e19..7739c8c6d 100644
--- a/cayenne-server/src/main/java/org/apache/cayenne/reflect/PojoMapper.java
+++ b/cayenne-server/src/main/java/org/apache/cayenne/reflect/PojoMapper.java
@@ -27,13 +27,21 @@ import java.util.function.Function;
 import org.apache.cayenne.CayenneRuntimeException;
 
 /**
- * Simple mapper of Object[] to POJO class. This class relies on field order, so use with caution.
+ * Simple mapper of Object[] to a POJO class.
+ * Target class must have default constructor and at least as many fields as a processed array.
+ * <br/>
+ * <b>Note:</b> Current implementation relies on the field order,
+ * so use with caution as this order may vary on different JDK platforms.
  * @param <T> type of object to produce
+ *
+ * @see org.apache.cayenne.query.ColumnSelect#map(Function)
+ * @see org.apache.cayenne.query.SQLSelect#map(Function)
+ *
  * @since 4.2
  */
 public class PojoMapper<T> implements Function<Object[], T> {
 
-    private static MethodHandles.Lookup lookup = MethodHandles.lookup();
+    private static final MethodHandles.Lookup lookup = MethodHandles.lookup();
 
     private final Class<T> type;
     private final MethodHandle constructor;
diff --git a/cayenne-server/src/test/java/org/apache/cayenne/query/ColumnSelectIT.java b/cayenne-server/src/test/java/org/apache/cayenne/query/ColumnSelectIT.java
index eb79b6f4d..f9496e020 100644
--- a/cayenne-server/src/test/java/org/apache/cayenne/query/ColumnSelectIT.java
+++ b/cayenne-server/src/test/java/org/apache/cayenne/query/ColumnSelectIT.java
@@ -41,7 +41,6 @@ import org.apache.cayenne.exp.property.EntityProperty;
 import org.apache.cayenne.exp.property.NumericProperty;
 import org.apache.cayenne.exp.property.PropertyFactory;
 import org.apache.cayenne.exp.property.StringProperty;
-import org.apache.cayenne.reflect.PojoMapper;
 import org.apache.cayenne.test.jdbc.DBHelper;
 import org.apache.cayenne.test.jdbc.TableHelper;
 import org.apache.cayenne.testdo.testmap.Artist;