DataSource backend sorting

Change-Id: Ic9e12534cf85f7793a57436e63bd67b6f920f722

documentation/datamodel/datamodel-datasources.asciidoc

@@ -152,7 +152,7 @@ Information about which items to fetch as well as some additional details are ma
 
 [source, java]
 ----
-DataSource<Person> dataSource = new DataSource<>(
+DataSource<Person> dataSource = new BackendDataSource<>(
   // First callback fetches items based on a query
   query -> {
     // The index of the first item to load
@@ -197,7 +197,7 @@ public interface PersonService {
 
   int getPersonCount();
 
-  static PersonSort createSort(
+  PersonSort createSort(
     String propertyName,
     boolean descending);
 }
@@ -208,19 +208,19 @@ The sorting options set through the component will be available through [interfa
 
 [source, java]
 ----
-DataSource<Person> dataSource = new DataSource<>(
+DataSource<Person> dataSource = new BackEndDataSource<>(
   query -> {
     List<PersonSort> sortOrders = new ArrayList<>();
     for(SortOrder<String> queryOrder : query.getSortOrders()) {
-      PersonSort sort = PersonService.createSort(
+      PersonSort sort = getPersonService().createSort(
         // The name of the sorted property
         queryOrder.getSorted(),
         // The sort direction for this property
         queryOrder.getDirection() == SortDirection.DESCENDING);
       sortOrders.add(sort);
     }
 
-    return service.fetchPersons(
+    return getPersonService().fetchPersons(
         query.getOffset(),
         query.getLimit(),
         sortOrders
@@ -329,7 +329,7 @@ We can create a helper method for handling the filter since the same logic is ne
 
 [source, java]
 ----
-DataSource<Person> dataSource = new DataSource<>(
+DataSource<Person> dataSource = new BackEndDataSource<>(
   query -> {
 
     BackendFilter filter = query.getFilter();

server/src/main/java/com/vaadin/server/data/BackEndDataSource.java

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2000-2014 Vaadin Ltd.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ * 
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.server.data;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+import java.util.function.Function;
+import java.util.stream.Stream;
+
+/**
+ * A {@link DataSource} for any back end.
+ *
+ * @param <T>
+ *            data source data type
+ */
+public class BackEndDataSource<T> implements
+        DataSource<T> {
+
+    private Function<Query, Stream<T>> request;
+    private Function<Query, Integer> sizeCallback;
+
+    /**
+     * Constructs a new DataSource to request data from an arbitrary back end
+     * request function.
+     *
+     * @param request
+     *            function that requests data from back end based on query
+     * @param sizeCallback
+     *            function that return the amount of data in back end for query
+     */
+    public BackEndDataSource(Function<Query, Stream<T>> request,
+            Function<Query, Integer> sizeCallback) {
+        Objects.requireNonNull(request, "Request function can't be null");
+        Objects.requireNonNull(sizeCallback, "Size callback can't be null");
+        this.request = request;
+        this.sizeCallback = sizeCallback;
+    }
+
+    @Override
+    public Stream<T> apply(Query t) {
+        return request.apply(t);
+    }
+
+    @Override
+    public int size(Query t) {
+        return sizeCallback.apply(t);
+    }
+
+    /**
+     * Sets a default sorting order to the data source.
+     *
+     * @param sortOrders
+     *            a list of sorting information containing field ids and directions
+     * @return new data source with modified sorting
+     */
+    public BackEndDataSource<T> sortingBy(List<SortOrder<String>> sortOrders) {
+        return new BackEndDataSource<>(query -> {
+            List<SortOrder<String>> queryOrder = new ArrayList<>(
+                    query.getSortOrders());
+            queryOrder.addAll(sortOrders);
+            return request.apply(new Query(query.getLimit(), query.getOffset(),
+                    queryOrder, query.getFilters()));
+        }, sizeCallback);
+    }
+
+    @Override
+    public boolean isInMemory() {
+        return false;
+    }
+
+}

server/src/main/java/com/vaadin/server/data/DataSource.java

@@ -15,43 +15,42 @@
  */
 package com.vaadin.server.data;
 
+import java.io.Serializable;
 import java.util.Arrays;
 import java.util.Collection;
-import java.util.Objects;
 import java.util.function.Function;
 import java.util.stream.Stream;
 
 /**
- * A generic data source for any back end and Listing UI components.
- * 
+ * Minimal DataSource API for communication between the DataProvider and a back
+ * end service.
+ *
+ * @since
  * @param <T>
- *            data source data type
+ *            data type
+ *
+ * @see InMemoryDataSource
+ * @see BackEndDataSource
  */
-public class DataSource<T> implements
-        Function<Query, Stream<T>>, java.io.Serializable {
-
-    protected Function<Query, Stream<T>> request;
-    protected Function<Query, Integer> sizeCallback;
+public interface DataSource<T> extends Function<Query, Stream<T>>,
+        Serializable {
 
-    protected DataSource() {
-    }
+    /**
+     * Gets whether the DataSource content all available in memory or does it
+     * use some external backend.
+     *
+     * @return {@code true} if all data is in memory; {@code false} if not
+     */
+    boolean isInMemory();
 
     /**
-     * Constructs a new DataSource to request data from an arbitrary back end
-     * request function.
-     * 
-     * @param request
-     *            function that requests data from back end based on query
-     * @param sizeCallback
-     *            function that return the amount of data in back end for query
+     * Gets the amount of data in this DataSource.
+     *
+     * @param t
+     *            query with sorting and filtering
+     * @return the size of the data source
      */
-    public DataSource(Function<Query, Stream<T>> request,
-            Function<Query, Integer> sizeCallback) {
-        Objects.requireNonNull(request, "Request function can't be null");
-        Objects.requireNonNull(sizeCallback, "Size callback can't be null");
-        this.request = request;
-        this.sizeCallback = sizeCallback;
-    }
+    int size(Query t);
 
     /**
      * This method creates a new {@link InMemoryDataSource} from a given
@@ -79,18 +78,4 @@ public static <T> InMemoryDataSource<T> create(Collection<T> data) {
     public static <T> InMemoryDataSource<T> create(T... data) {
         return new InMemoryDataSource<>(Arrays.asList(data));
     }
-
-    @Override
-    public Stream<T> apply(Query t) {
-        return request.apply(t);
-    }
-
-    public int size(Query t) {
-        return sizeCallback.apply(t);
-    }
-
-    public boolean isInMemory() {
-        return false;
-    }
-
-}
+}

server/src/main/java/com/vaadin/server/data/InMemoryDataSource.java

@@ -17,6 +17,7 @@
 
 import java.util.ArrayList;
 import java.util.Collection;
+import java.util.Comparator;
 import java.util.List;
 import java.util.function.Function;
 import java.util.stream.Stream;
@@ -28,14 +29,15 @@
  * @param <T>
  *            data type
  */
-public class InMemoryDataSource<T> extends DataSource<T> {
+public class InMemoryDataSource<T> implements DataSource<T> {
 
+    private Function<Query, Stream<T>> request;
     private int size;
 
     /**
      * Constructs a new ListDataSource. This method makes a protective copy of
      * the contents of the Collection.
-     * 
+     *
      * @param collection
      *            initial data
      */
@@ -49,12 +51,44 @@ public InMemoryDataSource(Collection<T> collection) {
      * Chaining constructor for making modified {@link InMemoryDataSource}s.
      * This Constructor is used internally for making sorted and filtered
      * variants of a base data source with actual data.
-     * 
+     *
      * @param request
      *            request for the new data source
      */
     protected InMemoryDataSource(Function<Query, Stream<T>> request) {
-        super(request,null);
+        this.request = request;
+    }
+
+    @Override
+    public Stream<T> apply(Query query) {
+        return request.apply(query);
+    }
+
+    /**
+     * Sets a default sorting order to the data source.
+     *
+     * @param sortOrder
+     *            a {@link Comparator} providing the needed sorting order
+     * @return new data source with modified sorting
+     */
+    public InMemoryDataSource<T> sortingBy(Comparator<T> sortOrder) {
+        return new InMemoryDataSource<>(q -> request.apply(q)
+                .sorted(sortOrder));
+    }
+
+    /**
+     * Sets a default sorting order to the data source. This method is a
+     * short-hand for {@code sortingBy(Comparator.comparing(sortOrder))}.
+     *
+     * @param sortOrder
+     *            function to sort by
+     * @param <U>
+     *            the type of the Comparable sort key
+     * @return new data source with modified sorting
+     */
+    public <U extends Comparable<? super U>> InMemoryDataSource<T> sortingBy(
+            Function<T, U> sortOrder) {
+        return sortingBy(Comparator.comparing(sortOrder));
     }
 
     @Override

server/src/main/java/com/vaadin/server/data/SortOrder.java

@@ -19,20 +19,43 @@
 
 import com.vaadin.shared.data.sort.SortDirection;
 
+/**
+ * Sorting information for one field.
+ *
+ * @see Query
+ */
 public class SortOrder<T> implements Serializable {
 
-    private T sorted;
-    private SortDirection direction;
+    private final T sorted;
+    private final SortDirection direction;
 
+    /**
+     * Constructs a field sorting information
+     *
+     * @param sorted
+     *         sorting information, usually field id or {@link java.util.Comparator}
+     * @param direction
+     *         sorting direction
+     */
     public SortOrder(T sorted, SortDirection direction) {
         this.sorted = sorted;
         this.direction = direction;
     }
 
+    /**
+     * Sorting information
+     *
+     * @return sorting entity, usually field id or {@link java.util.Comparator}
+     */
     public T getSorted() {
         return sorted;
     }
 
+    /**
+     * Sorting direction
+     *
+     * @return sorting direction
+     */
     public SortDirection getDirection() {
         return direction;
     }