Implement Grid server-side Sorting API (#13334)

Change-Id: Ie85cdaab8b942ed1bb60edac6b20bc1b9c47b445

4 files changed, 541 insertions, 4 deletions

diff --git a/server/src/com/vaadin/ui/components/grid/Grid.java b/server/src/com/vaadin/ui/components/grid/Grid.java
index bb5ff23da1..1d9cb8ef10 100644
--- a/server/src/com/vaadin/ui/components/grid/Grid.java
+++ b/server/src/com/vaadin/ui/components/grid/Grid.java
@@ -1,12 +1,12 @@
 /*
  * 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
@@ -22,6 +22,7 @@ import java.util.Collection;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.HashSet;
+import java.util.Iterator;
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
@@ -47,6 +48,7 @@ import com.vaadin.shared.ui.grid.GridState;
 import com.vaadin.shared.ui.grid.GridState.SharedSelectionMode;
 import com.vaadin.shared.ui.grid.HeightMode;
 import com.vaadin.shared.ui.grid.ScrollDestination;
+import com.vaadin.shared.ui.grid.SortDirection;
 import com.vaadin.ui.AbstractComponent;
 import com.vaadin.ui.components.grid.selection.MultiSelectionModel;
 import com.vaadin.ui.components.grid.selection.NoSelectionModel;
@@ -55,6 +57,8 @@ import com.vaadin.ui.components.grid.selection.SelectionChangeListener;
 import com.vaadin.ui.components.grid.selection.SelectionChangeNotifier;
 import com.vaadin.ui.components.grid.selection.SelectionModel;
 import com.vaadin.ui.components.grid.selection.SingleSelectionModel;
+import com.vaadin.ui.components.grid.sort.Sort;
+import com.vaadin.ui.components.grid.sort.SortOrder;
 import com.vaadin.util.ReflectTools;
 
 /**
@@ -139,6 +143,11 @@ public class Grid extends AbstractComponent implements SelectionChangeNotifier {
     private final List<ColumnGroupRow> columnGroupRows = new ArrayList<ColumnGroupRow>();
 
     /**
+     * The current sort order
+     */
+    private final List<SortOrder> sortOrder = new ArrayList<SortOrder>();
+
+    /**
      * Property listener for listening to changes in data source properties.
      */
     private final PropertySetChangeListener propertyListener = new PropertySetChangeListener() {
@@ -338,6 +347,36 @@ public class Grid extends AbstractComponent implements SelectionChangeNotifier {
         }
 
         datasource = container;
+
+        //
+        // Adjust sort order
+        //
+
+        if (container instanceof Container.Sortable) {
+
+            // If the container is sortable, go through the current sort order
+            // and match each item to the sortable properties of the new
+            // container. If the new container does not support an item in the
+            // current sort order, that item is removed from the current sort
+            // order list.
+            Collection<?> sortableProps = ((Container.Sortable) getContainerDatasource())
+                    .getSortableContainerPropertyIds();
+
+            Iterator<SortOrder> i = sortOrder.iterator();
+            while (i.hasNext()) {
+                if (!sortableProps.contains(i.next().getPropertyId())) {
+                    i.remove();
+                }
+            }
+
+            sort();
+        } else {
+
+            // If the new container is not sortable, we'll just re-set the sort
+            // order altogether.
+            clearSortOrder();
+        }
+
         datasourceExtension = new RpcDataProviderExtension(container);
         datasourceExtension.extend(this);
 
@@ -379,7 +418,6 @@ public class Grid extends AbstractComponent implements SelectionChangeNotifier {
                 column.setHeaderCaption(String.valueOf(propertyId));
             }
         }
-
     }
 
     /**
@@ -1081,4 +1119,128 @@ public class Grid extends AbstractComponent implements SelectionChangeNotifier {
     void addRenderer(Renderer<?> renderer) {
         addExtension(renderer);
     }
+
+    /**
+     * Sets the current sort order using the fluid Sort API. Read the
+     * documentation for {@link Sort} for more information.
+     * 
+     * @param s
+     *            a sort instance
+     */
+    public void sort(Sort s) {
+        setSortOrder(s.build());
+    }
+
+    /**
+     * Sort this Grid in ascending order by a specified property.
+     * 
+     * @param propertyId
+     *            a property ID
+     */
+    public void sort(Object propertyId) {
+        sort(propertyId, SortDirection.ASCENDING);
+    }
+
+    /**
+     * Sort this Grid in user-specified {@link SortOrder} by a property.
+     * 
+     * @param propertyId
+     *            a property ID
+     * @param direction
+     *            a sort order value (ascending/descending)
+     */
+    public void sort(Object propertyId, SortDirection direction) {
+        sort(Sort.by(propertyId, direction));
+    }
+
+    /**
+     * Clear the current sort order, and re-sort the grid.
+     */
+    public void clearSortOrder() {
+        sortOrder.clear();
+        sort();
+    }
+
+    /**
+     * Sets the sort order to use. This method throws
+     * {@link IllegalStateException} if the attached container is not a
+     * {@link Container.Sortable}, and {@link IllegalArgumentException} if a
+     * property in the list is not recognized by the container, or if the
+     * 'order' parameter is null.
+     * 
+     * @param order
+     *            a sort order list.
+     */
+    public void setSortOrder(List<SortOrder> order) {
+        if (!(getContainerDatasource() instanceof Container.Sortable)) {
+            throw new IllegalStateException(
+                    "Attached container is not sortable (does not implement Container.Sortable)");
+        }
+
+        if (order == null) {
+            throw new IllegalArgumentException("Order list may not be null!");
+        }
+
+        sortOrder.clear();
+
+        Collection<?> sortableProps = ((Container.Sortable) getContainerDatasource())
+                .getSortableContainerPropertyIds();
+
+        for (SortOrder o : order) {
+            if (!sortableProps.contains(o.getPropertyId())) {
+                throw new IllegalArgumentException(
+                        "Property "
+                                + o.getPropertyId()
+                                + " does not exist or is not sortable in the current container");
+            }
+        }
+
+        sortOrder.addAll(order);
+        sort();
+    }
+
+    /**
+     * Get the current sort order list.
+     * 
+     * @return a sort order list
+     */
+    public List<SortOrder> getSortOrder() {
+        return Collections.unmodifiableList(sortOrder);
+    }
+
+    /**
+     * Apply sorting to data source.
+     */
+    private void sort() {
+
+        Container c = getContainerDatasource();
+        if (c instanceof Container.Sortable) {
+            Container.Sortable cs = (Container.Sortable) c;
+
+            final int items = sortOrder.size();
+            Object[] propertyIds = new Object[items];
+            boolean[] directions = new boolean[items];
+
+            for (int i = 0; i < items; ++i) {
+                SortOrder order = sortOrder.get(i);
+                propertyIds[i] = order.getPropertyId();
+                switch (order.getDirection()) {
+                case ASCENDING:
+                    directions[i] = true;
+                    break;
+                case DESCENDING:
+                    directions[i] = false;
+                    break;
+                default:
+                    throw new IllegalArgumentException("getDirection() of "
+                            + order + " returned an unexpected value");
+                }
+            }
+
+            cs.sort(propertyIds, directions);
+        } else {
+            throw new IllegalStateException(
+                    "Container is not sortable (does not implement Container.Sortable)");
+        }
+    }
 }
diff --git a/server/src/com/vaadin/ui/components/grid/sort/Sort.java b/server/src/com/vaadin/ui/components/grid/sort/Sort.java
new file mode 100644
index 0000000000..54831378b6
--- /dev/null
+++ b/server/src/com/vaadin/ui/components/grid/sort/Sort.java
@@ -0,0 +1,153 @@
+/*
+ * 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.ui.components.grid.sort;
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.List;
+
+import com.vaadin.shared.ui.grid.SortDirection;
+
+/**
+ * Fluid Sort API. Provides a convenient, human-readable way of specifying
+ * multi-column sort order.
+ * 
+ * @since 7.4
+ * @author Vaadin Ltd
+ */
+public class Sort implements Serializable {
+
+    private final Sort previous;
+    private final SortOrder order;
+
+    /**
+     * Initial constructor, called by the static by() methods.
+     * 
+     * @param propertyId
+     *            a property ID, corresponding to a property in the data source
+     * @param direction
+     *            a sort direction value
+     */
+    private Sort(Object propertyId, SortDirection direction) {
+        previous = null;
+        order = new SortOrder(propertyId, direction);
+    }
+
+    /**
+     * Chaining constructor, called by the non-static then() methods. This
+     * constructor links to the previous Sort object.
+     * 
+     * @param previous
+     *            the sort marker that comes before this one
+     * @param propertyId
+     *            a property ID, corresponding to a property in the data source
+     * @param direction
+     *            a sort direction value
+     */
+    private Sort(Sort previous, Object propertyId, SortDirection direction) {
+        this.previous = previous;
+        order = new SortOrder(propertyId, direction);
+
+        Sort s = previous;
+        while (s != null) {
+            if (s.order.getPropertyId() == propertyId) {
+                throw new IllegalStateException(
+                        "Can not sort along the same property (" + propertyId
+                                + ") twice!");
+            }
+            s = s.previous;
+        }
+
+    }
+
+    /**
+     * Start building a Sort order by sorting a provided column in ascending
+     * order.
+     * 
+     * @param propertyId
+     *            a property id, corresponding to a data source property
+     * @return a sort object
+     */
+    public static Sort by(Object propertyId) {
+        return by(propertyId, SortDirection.ASCENDING);
+    }
+
+    /**
+     * Start building a Sort order by sorting a provided column.
+     * 
+     * @param propertyId
+     *            a property id, corresponding to a data source property
+     * @param direction
+     *            a sort direction value
+     * @return a sort object
+     */
+    public static Sort by(Object propertyId, SortDirection direction) {
+        return new Sort(propertyId, direction);
+    }
+
+    /**
+     * Continue building a Sort order. The provided property is sorted in
+     * ascending order if the previously added properties have been evaluated as
+     * equals.
+     * 
+     * @param propertyId
+     *            a property id, corresponding to a data source property
+     * @return a sort object
+     */
+    public Sort then(Object propertyId) {
+        return then(propertyId, SortDirection.ASCENDING);
+    }
+
+    /**
+     * Continue building a Sort order. The provided property is sorted in
+     * specified order if the previously added properties have been evaluated as
+     * equals.
+     * 
+     * @param propertyId
+     *            a property id, corresponding to a data source property
+     * @param direction
+     *            a sort direction value
+     * @return a sort object
+     */
+    public Sort then(Object propertyId, SortDirection direction) {
+        return new Sort(this, propertyId, direction);
+    }
+
+    /**
+     * Build a sort order list, ready to be passed to Grid
+     * 
+     * @return a sort order list.
+     */
+    public List<SortOrder> build() {
+
+        int count = 1;
+        Sort s = this;
+        while (s.previous != null) {
+            s = s.previous;
+            ++count;
+        }
+
+        List<SortOrder> order = new ArrayList<SortOrder>(count);
+
+        s = this;
+        do {
+            order.add(0, s.order);
+            s = s.previous;
+        } while (s != null);
+
+        return order;
+    }
+}
diff --git a/server/src/com/vaadin/ui/components/grid/sort/SortOrder.java b/server/src/com/vaadin/ui/components/grid/sort/SortOrder.java
new file mode 100644
index 0000000000..f186333e0a
--- /dev/null
+++ b/server/src/com/vaadin/ui/components/grid/sort/SortOrder.java
@@ -0,0 +1,73 @@
+/*
+ * 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.ui.components.grid.sort;
+
+import java.io.Serializable;
+
+import com.vaadin.shared.ui.grid.SortDirection;
+
+/**
+ * Sort order descriptor. Links together a {@link SortDirection} value and a
+ * Vaadin container property ID.
+ *
+ * @since 7.4
+ * @author Vaadin Ltd
+ */
+public class SortOrder implements Serializable {
+
+    private final Object propertyId;
+    private final SortDirection direction;
+
+    /**
+     * Create a SortOrder object. Both arguments must be non-null.
+     *
+     * @param propertyId
+     *            id of the data source property to sort by
+     * @param direction
+     *            value indicating whether the property id should be sorted in
+     *            ascending or descending order
+     */
+    public SortOrder(Object propertyId, SortDirection direction) {
+        if (propertyId == null) {
+            throw new IllegalArgumentException("Property ID can not be null!");
+        }
+        if (direction == null) {
+            throw new IllegalArgumentException(
+                    "Direction value can not be null!");
+        }
+        this.propertyId = propertyId;
+        this.direction = direction;
+    }
+
+    /**
+     * Returns the property ID.
+     *
+     * @return a property ID
+     */
+    public Object getPropertyId() {
+        return propertyId;
+    }
+
+    /**
+     * Returns the {@link SortDirection} value.
+     *
+     * @return a sort direction value
+     */
+    public SortDirection getDirection() {
+        return direction;
+    }
+
+}
diff --git a/server/tests/src/com/vaadin/tests/server/component/grid/sort/SortTest.java b/server/tests/src/com/vaadin/tests/server/component/grid/sort/SortTest.java
new file mode 100644
index 0000000000..844292265d
--- /dev/null
+++ b/server/tests/src/com/vaadin/tests/server/component/grid/sort/SortTest.java
@@ -0,0 +1,149 @@
+/*
+ * 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.tests.server.component.grid.sort;
+
+import org.junit.After;
+import org.junit.Assert;
+import org.junit.Before;
+import org.junit.Test;
+
+import com.vaadin.data.util.IndexedContainer;
+import com.vaadin.shared.ui.grid.SortDirection;
+import com.vaadin.ui.components.grid.Grid;
+import com.vaadin.ui.components.grid.sort.Sort;
+
+public class SortTest {
+
+    class DummySortingIndexedContainer extends IndexedContainer {
+
+        private Object[] expectedProperties;
+        private boolean[] expectedAscending;
+        private boolean sorted = true;
+
+        @Override
+        public void sort(Object[] propertyId, boolean[] ascending) {
+            Assert.assertEquals(
+                    "Different amount of expected and actual properties,",
+                    expectedProperties.length, propertyId.length);
+            Assert.assertEquals(
+                    "Different amount of expected and actual directions",
+                    expectedAscending.length, ascending.length);
+            for (int i = 0; i < propertyId.length; ++i) {
+                Assert.assertEquals("Sorting properties differ",
+                        expectedProperties[i], propertyId[i]);
+                Assert.assertEquals("Sorting directions differ",
+                        expectedAscending[i], ascending[i]);
+            }
+            sorted = true;
+        }
+
+        public void expectedSort(Object[] properties, SortDirection[] directions) {
+            assert directions.length == properties.length : "Array dimensions differ";
+            expectedProperties = properties;
+            expectedAscending = new boolean[directions.length];
+            for (int i = 0; i < directions.length; ++i) {
+                expectedAscending[i] = (directions[i] == SortDirection.ASCENDING);
+            }
+            sorted = false;
+        }
+
+        public boolean isSorted() {
+            return sorted;
+        }
+    }
+
+    private DummySortingIndexedContainer container;
+    private Grid grid;
+
+    @Before
+    public void setUp() {
+        container = createContainer();
+        container.expectedSort(new Object[] {}, new SortDirection[] {});
+        grid = new Grid(container);
+    }
+
+    @After
+    public void tearDown() {
+        Assert.assertTrue("Container was not sorted after the test.",
+                container.isSorted());
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testInvalidSortDirection() {
+        Sort.by("foo", null);
+    }
+
+    @Test(expected = IllegalStateException.class)
+    public void testSortOneColumnMultipleTimes() {
+        Sort.by("foo").then("bar").then("foo");
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testSortingByUnexistingProperty() {
+        grid.sort("foobar");
+    }
+
+    @Test(expected = IllegalArgumentException.class)
+    public void testSortingByUnsortableProperty() {
+        container.addContainerProperty("foobar", Object.class, null);
+        grid.sort("foobar");
+    }
+
+    @Test
+    public void testGridDirectSortAscending() {
+        container.expectedSort(new Object[] { "foo" },
+                new SortDirection[] { SortDirection.ASCENDING });
+        grid.sort("foo");
+    }
+
+    @Test
+    public void testGridDirectSortDescending() {
+        container.expectedSort(new Object[] { "foo" },
+                new SortDirection[] { SortDirection.DESCENDING });
+        grid.sort("foo", SortDirection.DESCENDING);
+    }
+
+    @Test
+    public void testGridSortBy() {
+        container.expectedSort(new Object[] { "foo", "bar", "baz" },
+                new SortDirection[] { SortDirection.ASCENDING,
+                        SortDirection.ASCENDING, SortDirection.DESCENDING });
+        grid.sort(Sort.by("foo").then("bar")
+                .then("baz", SortDirection.DESCENDING));
+    }
+
+    @Test
+    public void testChangeContainerAfterSorting() {
+        container.expectedSort(new Object[] { "foo", "bar", "baz" },
+                new SortDirection[] { SortDirection.ASCENDING,
+                        SortDirection.ASCENDING, SortDirection.DESCENDING });
+        grid.sort(Sort.by("foo").then("bar")
+                .then("baz", SortDirection.DESCENDING));
+        container = new DummySortingIndexedContainer();
+        container.addContainerProperty("baz", String.class, "");
+        container.expectedSort(new Object[] { "baz" },
+                new SortDirection[] { SortDirection.DESCENDING });
+        grid.setContainerDataSource(container);
+    }
+
+    private DummySortingIndexedContainer createContainer() {
+        DummySortingIndexedContainer container = new DummySortingIndexedContainer();
+        container.addContainerProperty("foo", Integer.class, 0);
+        container.addContainerProperty("bar", Integer.class, 0);
+        container.addContainerProperty("baz", Integer.class, 0);
+        return container;
+    }
+}