Add javadoc explanation about how to create serializable comparators (#8505)

Also removes the confusing SerializableComparator.asInstance method that
was mainly introduced for internal use.

Fixes #8367

2 files changed, 17 insertions, 21 deletions

diff --git a/server/src/main/java/com/vaadin/server/SerializableComparator.java b/server/src/main/java/com/vaadin/server/SerializableComparator.java
index 448d2e09ba..9819977992 100644
--- a/server/src/main/java/com/vaadin/server/SerializableComparator.java
+++ b/server/src/main/java/com/vaadin/server/SerializableComparator.java
@@ -20,6 +20,15 @@ import java.util.Comparator;
 
 /**
  * A {@link Comparator} that is also {@link Serializable}.
+ * <p>
+ * You can create a serializable comparator from a regular comparator through a
+ * method reference by appending <code>::compare</code>. For example
+ * <code>SerializableComparator&lt;Employee&gt;
+ * comparator = Comparator.comparing(Employee::getFirstName)::compare</code>.
+ * The resulting comparator will in most cases cause exceptions if it is
+ * actually being serialized, but this construct will enable using the
+ * shorthands in {@link Comparator} in applications where session will not be
+ * serialized.
  *
  * @author Vaadin Ltd
  * @param <T>
@@ -29,21 +38,5 @@ import java.util.Comparator;
  */
 @FunctionalInterface
 public interface SerializableComparator<T> extends Comparator<T>, Serializable {
-
-    /**
-     * Returns a {@link SerializableComparator} instance which delegates its
-     * logic to the provided {@code comparator}.
-     *
-     * @param comparator
-     *            comparator to convert
-     * @param <T>
-     *            the type of objects that may be compared by this comparator
-     * @param <C>
-     *            the comparator type
-     * @return a SerializableComparator view of the {@code comparator}
-     */
-    static <C extends Comparator<T> & Serializable, T> SerializableComparator<T> asInstance(
-            C comparator) {
-        return (arg1, arg2) -> comparator.compare(arg1, arg2);
-    }
+    // Relevant methods inherited from Comparator
 }
diff --git a/server/src/main/java/com/vaadin/ui/Grid.java b/server/src/main/java/com/vaadin/ui/Grid.java
index 7842faf503..60dc623374 100644
--- a/server/src/main/java/com/vaadin/ui/Grid.java
+++ b/server/src/main/java/com/vaadin/ui/Grid.java
@@ -15,7 +15,6 @@
  */
 package com.vaadin.ui;
 
-import java.io.Serializable;
 import java.lang.reflect.Method;
 import java.lang.reflect.Type;
 import java.util.ArrayList;
@@ -3726,9 +3725,13 @@ public class Grid<T> extends AbstractListing<T> implements HasComponents,
      */
     protected SerializableComparator<T> createSortingComparator() {
         BinaryOperator<SerializableComparator<T>> operator = (comparator1,
-                comparator2) -> SerializableComparator
-                        .asInstance((Comparator<T> & Serializable) comparator1
-                                .thenComparing(comparator2));
+                comparator2) -> {
+            /*
+             * thenComparing is defined to return a serializable comparator as
+             * long as both original comparators are also serializable
+             */
+            return comparator1.thenComparing(comparator2)::compare;
+        };
         return sortOrder.stream().map(
                 order -> order.getSorted().getComparator(order.getDirection()))
                 .reduce((x, y) -> 0, operator);