[#1707] Add <K> Map<K, Result<R>> ResultQuery.fetchGroups(Field<K>) and

Result.intoGroups(Field<K>)

jOOQ-test/src/org/jooq/test/_/testcases/FetchTests.java

@@ -182,6 +182,39 @@ extends BaseTest<A, AP, B, S, B2S, BS, L, X, DATE, BOOL, D, T, U, I, IPK, T658,
         catch (InvalidResultException expected) {}
     }
 
+    @Test
+    public void testFetchGroups() throws Exception {
+        // Key -> Record Map
+        // -----------------
+
+        // Grouping by BOOK.ID
+        Map<Integer, Result<B>> map1 = create().selectFrom(TBook()).orderBy(TBook_ID()).fetchGroups(TBook_ID());
+        for (Entry<Integer, Result<B>> entry : map1.entrySet()) {
+            assertEquals(1, entry.getValue().size());
+            assertEquals(entry.getKey(), entry.getValue().get(0).getValue(TBook_ID()));
+        }
+        assertEquals(4, map1.size());
+        assertEquals(BOOK_IDS, new ArrayList<Integer>(map1.keySet()));
+
+        // Grouping by BOOK.AUTHOR_ID
+        Map<Integer, Result<B>> map2 = create().selectFrom(TBook()).orderBy(TBook_ID()).fetchGroups(TBook_AUTHOR_ID());
+        assertEquals(2, map2.size());
+        assertEquals(AUTHOR_IDS, new ArrayList<Integer>(map2.keySet()));
+
+        Iterator<Entry<Integer, Result<B>>> it = map2.entrySet().iterator();
+        Entry<Integer, Result<B>> entry21 = it.next();
+        assertEquals(2, entry21.getValue().size());
+        assertEquals(1, (int) entry21.getValue().get(0).getValue(TBook_ID()));
+        assertEquals(2, (int) entry21.getValue().get(1).getValue(TBook_ID()));
+
+        Entry<Integer, Result<B>> entry22 = it.next();
+        assertEquals(2, entry22.getValue().size());
+        assertEquals(3, (int) entry22.getValue().get(0).getValue(TBook_ID()));
+        assertEquals(4, (int) entry22.getValue().get(1).getValue(TBook_ID()));
+
+        assertFalse(it.hasNext());
+    }
+
     @Test
     public void testFetchArray() throws Exception {
 

jOOQ-test/src/org/jooq/test/jOOQAbstractTest.java

@@ -775,6 +775,11 @@ public abstract class jOOQAbstractTest<
         new FetchTests(this).testFetchMap();
     }
 
+    @Test
+    public void testFetchGroups() throws Exception {
+        new FetchTests(this).testFetchGroups();
+    }
+
     @Test
     public void testFetchArray() throws Exception {
         new FetchTests(this).testFetchArray();

jOOQ/src/main/java/org/jooq/Result.java

@@ -1802,7 +1802,8 @@ public interface Result<R extends Record> extends FieldProvider, List<R>, Attach
      * corresponding records as value.
      * <p>
      * An {@link InvalidResultException} is thrown, if the key turns out to be
-     * non-unique in the result set.
+     * non-unique in the result set. Use {@link #intoGroups(Field)} instead, if
+     * your keys are non-unique
      *
      * @param <K> The key's generic field type
      * @param key The key field. Client code must assure that this field is
@@ -1831,6 +1832,19 @@ public interface Result<R extends Record> extends FieldProvider, List<R>, Attach
      */
     <K, V> Map<K, V> intoMap(Field<K> key, Field<V> value);
 
+    /**
+     * Return a {@link Map} with one of the result's columns as key and a list
+     * of corresponding records as value.
+     * <p>
+     * Unlike {@link #intoMap(Field)}, this method allows for non-unique keys in
+     * the result set.
+     *
+     * @param <K> The key's generic field type
+     * @param key The key field.
+     * @return A Map containing the results
+     */
+    <K> Map<K, Result<R>> intoGroups(Field<K> key);
+
     /**
      * Convert this result into an array of arrays
      * <p>

jOOQ/src/main/java/org/jooq/ResultQuery.java

@@ -462,7 +462,8 @@ public interface ResultQuery<R extends Record> extends Query {
      * columns as key and the corresponding records as value.
      * <p>
      * An exception is thrown, if the key turns out to be non-unique in the
-     * result set.
+     * result set. Use {@link #fetchGroups(Field)} instead, if your keys are
+     * non-unique
      * <p>
      * The resulting records are attached to the original {@link Configuration}
      * by default. Use {@link Settings#isAttachRecords()} to override this
@@ -475,7 +476,7 @@ public interface ResultQuery<R extends Record> extends Query {
      * @throws DataAccessException if something went wrong executing the query
      * @throws InvalidResultException if the key field returned two or more
      *             equal values from the result set.
-     * @see Result#intoMap(Field, Field)
+     * @see Result#intoMap(Field)
      */
     <K> Map<K, R> fetchMap(Field<K> key) throws DataAccessException;
 
@@ -495,9 +496,29 @@ public interface ResultQuery<R extends Record> extends Query {
      * @throws DataAccessException if something went wrong executing the query
      * @throws InvalidResultException if the key field returned two or more
      *             equal values from the result set.
+     * @see Result#intoMap(Field, Field)
      */
     <K, V> Map<K, V> fetchMap(Field<K> key, Field<V> value) throws DataAccessException;
 
+    /**
+     * Execute the query and return a {@link Map} with one of the result's
+     * columns as key and a list of corresponding records as value.
+     * <p>
+     * Unlike {@link #fetchMap(Field)}, this method allows for non-unique keys
+     * in the result set.
+     * <p>
+     * The resulting records are attached to the original {@link Configuration}
+     * by default. Use {@link Settings#isAttachRecords()} to override this
+     * behaviour.
+     *
+     * @param <K> The key's generic field type
+     * @param key The key field.
+     * @return A Map containing the results
+     * @throws DataAccessException if something went wrong executing the query
+     * @see Result#intoGroups(Field)
+     */
+    <K> Map<K, Result<R>> fetchGroups(Field<K> key) throws DataAccessException;
+
     /**
      * Execute the query and return the generated result as an Object matrix
      * <p>

jOOQ/src/main/java/org/jooq/impl/AbstractDelegatingSelect.java

@@ -237,6 +237,11 @@ abstract class AbstractDelegatingSelect<R extends Record>
         return getDelegate().fetchOneMap();
     }
 
+    @Override
+    public final <K> Map<K, Result<R>> fetchGroups(Field<K> key) {
+        return getDelegate().fetchGroups(key);
+    }
+
     @Override
     public final Object[][] fetchArrays() {
         return getDelegate().fetchArrays();
@@ -368,7 +373,7 @@ abstract class AbstractDelegatingSelect<R extends Record>
     }
 
     @Override
-    public final int getIndex(Field<?> field) throws IllegalArgumentException {
+    public final int getIndex(Field<?> field) {
         return getDelegate().asTable().getIndex(field);
     }
 }

jOOQ/src/main/java/org/jooq/impl/AbstractResultQuery.java

@@ -427,6 +427,11 @@ abstract class AbstractResultQuery<R extends Record> extends AbstractQuery imple
         return fetchOne().intoMap();
     }
 
+    @Override
+    public final <K> Map<K, Result<R>> fetchGroups(Field<K> key) {
+        return fetch().intoGroups(key);
+    }
+
     @Override
     public final Object[][] fetchArrays() {
         return fetch().intoArray();

jOOQ/src/main/java/org/jooq/impl/ResultImpl.java

@@ -1314,6 +1314,25 @@ class ResultImpl<R extends Record> implements Result<R>, AttachableInternal {
         return map;
     }
 
+    @Override
+    public final <K> Map<K, Result<R>> intoGroups(Field<K> key) {
+        Map<K, Result<R>> map = new LinkedHashMap<K, Result<R>>();
+
+        for (R record : this) {
+            K value = record.getValue(key);
+            Result<R> result = map.get(value);
+
+            if (result == null) {
+                result = new ResultImpl<R>(configuration, fields);
+                map.put(value, result);
+            }
+
+            result.add(record);
+        }
+
+        return map;
+    }
+
     @Override
     public final Object[][] intoArray() throws MappingException {
         int size = size();