Implement GridSortOrder and SortOrderBuilders (#8338)

server/src/main/java/com/vaadin/data/provider/BackEndDataProvider.java

@@ -17,6 +17,7 @@
 
 import java.util.Collections;
 import java.util.List;
+import java.util.Objects;
 
 /**
  * A data provider that lazy loads items from a back end.
@@ -44,6 +45,22 @@ public interface BackEndDataProvider<T, F> extends DataProvider<T, F> {
      */
     void setSortOrders(List<QuerySortOrder> sortOrders);
 
+    /**
+     * Sets the sort order to use, given a {@link QuerySortOrderBuilder}.
+     * Shorthand for {@code setSortOrders(builder.build())}.
+     * 
+     * @see QuerySortOrderBuilder
+     * 
+     * @param builder
+     *            the sort builder to retrieve the sort order from
+     * @throws NullPointerException
+     *             if builder is null
+     */
+    default void setSortOrders(QuerySortOrderBuilder builder) {
+        Objects.requireNonNull("Sort builder cannot be null.");
+        setSortOrders(builder.build());
+    }
+
     /**
      * Sets a single sort order to use as the default sorting for this data
      * provider. This overrides the sorting set by any other method that

server/src/main/java/com/vaadin/data/provider/GridSortOrder.java

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2000-2016 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.data.provider;
+
+import com.vaadin.shared.data.sort.SortDirection;
+import com.vaadin.ui.Grid.Column;
+
+/**
+ * Sorting information for {@link Grid}.
+ *
+ * @param <T>
+ *            the grid type
+ */
+public class GridSortOrder<T> extends SortOrder<Column<T, ?>> {
+
+    /**
+     * Construct sorting information for usage in a {@link Grid}.
+     * 
+     * @param column
+     *            the column to be sorted
+     * @param direction
+     *            sorting direction
+     */
+    public GridSortOrder(Column<T, ?> column, SortDirection direction) {
+        super(column, direction);
+    }
+
+    /**
+     * Gets the column this sorting information is attached to.
+     *
+     * @return the column being sorted
+     */
+    @Override
+    public Column<T, ?> getSorted() {
+        return super.getSorted();
+    }
+
+    /**
+     * Creates a new grid sort builder with given sorting using ascending sort
+     * direction.
+     *
+     * @param by
+     *            the column to sort by
+     * @param <T>
+     *            the grid type
+     *
+     * @return the grid sort builder
+     */
+    public static <T> GridSortOrderBuilder<T> asc(Column<T, ?> by) {
+        return new GridSortOrderBuilder<T>().thenAsc(by);
+    }
+
+    /**
+     * Creates a new grid sort builder with given sorting using descending sort
+     * direction.
+     *
+     * @param by
+     *            the column to sort by
+     * @param <T>
+     *            the grid type
+     *
+     * @return the grid sort builder
+     */
+    public static <T> GridSortOrderBuilder<T> desc(Column<T, ?> by) {
+        return new GridSortOrderBuilder<T>().thenDesc(by);
+    }
+}

server/src/main/java/com/vaadin/data/provider/GridSortOrderBuilder.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2000-2016 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.data.provider;
+
+import com.vaadin.shared.data.sort.SortDirection;
+import com.vaadin.ui.Grid.Column;
+
+/**
+ * Helper classes with fluent API for constructing {@link GridSortOrder} lists.
+ * When the sort order is ready to be passed on, calling {@link #build()} will
+ * create the list of sort orders.
+ * 
+ * @see GridSortOrder
+ * @see #thenAsc(Column)
+ * @see #thenDesc(Column)
+ * @see #build()
+ * 
+ * @param <T>
+ *            the type of the grid
+ */
+public class GridSortOrderBuilder<T>
+        extends SortOrderBuilder<GridSortOrder<T>, Column<T, ?>> {
+
+    @Override
+    public GridSortOrderBuilder<T> thenAsc(Column<T, ?> by) {
+        return (GridSortOrderBuilder<T>) super.thenAsc(by);
+    }
+
+    @Override
+    public GridSortOrderBuilder<T> thenDesc(Column<T, ?> by) {
+        return (GridSortOrderBuilder<T>) super.thenDesc(by);
+    }
+
+    @Override
+    protected GridSortOrder<T> createSortOrder(Column<T, ?> by,
+            SortDirection direction) {
+        return new GridSortOrder<>(by, direction);
+    }
+}

server/src/main/java/com/vaadin/data/provider/QuerySortOrder.java

@@ -45,4 +45,30 @@ public QuerySortOrder(String sorted, SortDirection direction) {
     public String getSorted() {
         return super.getSorted();
     }
+
+    /**
+     * Creates a new query sort builder with given sorting using ascending sort
+     * direction.
+     *
+     * @param by
+     *            the string to sort by
+     *
+     * @return the query sort builder
+     */
+    public static QuerySortOrderBuilder asc(String by) {
+        return new QuerySortOrderBuilder().thenAsc(by);
+    }
+
+    /**
+     * Creates a new query sort builder with given sorting using descending sort
+     * direction.
+     *
+     * @param by
+     *            the string to sort by
+     *
+     * @return the query sort builder
+     */
+    public static QuerySortOrderBuilder desc(String by) {
+        return new QuerySortOrderBuilder().thenDesc(by);
+    }
 }

server/src/main/java/com/vaadin/data/provider/QuerySortOrderBuilder.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2000-2016 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.data.provider;
+
+import com.vaadin.shared.data.sort.SortDirection;
+
+/**
+ * Helper classes with fluent API for constructing {@link QuerySortOrder} lists.
+ * When the sort order is ready to be passed on, calling {@link #build()} will
+ * create the list of sort orders.
+ * 
+ * @see QuerySortOrder
+ * @see #thenDesc(String)
+ * @see #thenDesc(String)
+ * @see #build()
+ */
+public class QuerySortOrderBuilder extends SortOrderBuilder<QuerySortOrder, String> {
+
+    @Override
+    public QuerySortOrderBuilder thenAsc(String by) {
+        return (QuerySortOrderBuilder) super.thenAsc(by);
+    }
+
+    @Override
+    public QuerySortOrderBuilder thenDesc(String by) {
+        return (QuerySortOrderBuilder) super.thenDesc(by);
+    }
+
+    @Override
+    protected QuerySortOrder createSortOrder(String by,
+            SortDirection direction) {
+        return new QuerySortOrder(by, direction);
+    }
+}

server/src/main/java/com/vaadin/data/provider/SortOrderBuilder.java

@@ -0,0 +1,99 @@
+/*
+ * Copyright 2000-2016 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.data.provider;
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+import com.vaadin.shared.data.sort.SortDirection;
+
+/**
+ * Base class for helper classes with fluent API for constructing sort order
+ * lists. When the sort order is ready to be passed on, calling {@link #build()}
+ * will create the list of sort orders.
+ *
+ * @param <T>
+ *            the sort order type
+ * @param <V>
+ *            the sorting type
+ *
+ * @see SortOrderBuilder#thenAsc(Object)
+ * @see SortOrderBuilder#thenDesc(Object)
+ * @see #build()
+ */
+public abstract class SortOrderBuilder<T extends SortOrder<V>, V>
+        implements Serializable {
+
+    private final List<T> sortOrders = new ArrayList<>();
+
+    /**
+     * Appends sorting with ascending sort direction.
+     *
+     * @param by
+     *            the object to sort by
+     * @return this sort builder
+     */
+    public SortOrderBuilder<T, V> thenAsc(V by) {
+        return append(createSortOrder(by, SortDirection.ASCENDING));
+    }
+
+    /**
+     * Appends sorting with descending sort direction.
+     *
+     * @param by
+     *            the object to sort by
+     * @return this sort builder
+     */
+    public SortOrderBuilder<T, V> thenDesc(V by) {
+        return append(createSortOrder(by, SortDirection.DESCENDING));
+    }
+
+    /**
+     * Returns an unmodifiable copy of the list of current sort orders in this
+     * sort builder.
+     *
+     * @return an unmodifiable sort order list
+     */
+    public final List<T> build() {
+        return Collections.unmodifiableList(new ArrayList<>(sortOrders));
+    }
+
+    /**
+     * Creates a sort order object with the given parameters.
+     *
+     * @param by
+     *            the object to sort by
+     * @param direction
+     *            the sort direction
+     *
+     * @return the sort order object
+     */
+    protected abstract T createSortOrder(V by, SortDirection direction);
+
+    /**
+     * Append a sort order to {@code sortOrders}.
+     *
+     * @param sortOrder
+     *            the sort order to append
+     * @return this
+     */
+    private final SortOrderBuilder<T, V> append(T sortOrder) {
+        sortOrders.add(sortOrder);
+        return this;
+    }
+}