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

[ntimofeev]

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

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


The following commit(s) were added to refs/heads/master by this push:
     new 5bb9ad566 Improve javadocs for map() methods of SQLSelect and 
ColumnSelect
5bb9ad566 is described below

commit 5bb9ad566d1e63b904b83ab434ea996197278789
Author: Nikita Timofeev <stari...@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 994e65345..dd74e6063 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
@@ -605,10 +605,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 2e5fda6ec..f069c5a43 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
@@ -603,6 +603,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 448ac88f8..d8ff323f6 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;