Add event originator information to Sort Events (#13334)

Change-Id: I9f8a295d6944807ccf89ea535d5500fac013e127

9 files changed, 142 insertions, 25 deletions

diff --git a/client/src/com/vaadin/client/ui/grid/Grid.java b/client/src/com/vaadin/client/ui/grid/Grid.java
index a2bb0d3f09..22c3604bf8 100644
--- a/client/src/com/vaadin/client/ui/grid/Grid.java
+++ b/client/src/com/vaadin/client/ui/grid/Grid.java
@@ -87,6 +87,7 @@ import com.vaadin.shared.ui.grid.HeightMode;
 import com.vaadin.shared.ui.grid.Range;
 import com.vaadin.shared.ui.grid.ScrollDestination;
 import com.vaadin.shared.ui.grid.SortDirection;
+import com.vaadin.shared.ui.grid.SortEventOriginator;
 
 /**
  * A data grid view that supports columns and lazy loading of data rows from a
@@ -622,8 +623,8 @@ public class Grid<T> extends Composite implements
                 }
             }
 
-            // Perform sorting
-            Grid.this.sort(sorting);
+            // Perform sorting; indicate originator as user
+            Grid.this.setSortOrder(sorting.build(), SortEventOriginator.USER);
         }
     }
 
@@ -2376,11 +2377,16 @@ public class Grid<T> extends Composite implements
      *            a sort order list. If set to null, the sort order is cleared.
      */
     public void setSortOrder(List<SortOrder> order) {
+        setSortOrder(order, SortEventOriginator.API);
+    }
+
+    private void setSortOrder(List<SortOrder> order,
+            SortEventOriginator originator) {
         sortOrder.clear();
         if (order != null) {
             sortOrder.addAll(order);
         }
-        sort();
+        sort(originator);
     }
 
     /**
@@ -2505,9 +2511,9 @@ public class Grid<T> extends Composite implements
     /**
      * Apply sorting to data source.
      */
-    private void sort() {
+    private void sort(SortEventOriginator originator) {
         refreshHeader();
         fireEvent(new SortEvent<T>(this,
-                Collections.unmodifiableList(sortOrder)));
+                Collections.unmodifiableList(sortOrder), originator));
     }
 }
diff --git a/client/src/com/vaadin/client/ui/grid/GridConnector.java b/client/src/com/vaadin/client/ui/grid/GridConnector.java
index 9d93c81d82..73440232b1 100644
--- a/client/src/com/vaadin/client/ui/grid/GridConnector.java
+++ b/client/src/com/vaadin/client/ui/grid/GridConnector.java
@@ -224,8 +224,8 @@ public class GridConnector extends AbstractHasComponentsConnector {
                 if (!Arrays.equals(columnIds, getState().sortColumns)
                         || !Arrays.equals(directions, getState().sortDirs)) {
                     // Report back to server if changed
-                    getRpcProxy(GridServerRpc.class)
-                            .sort(columnIds, directions);
+                    getRpcProxy(GridServerRpc.class).sort(columnIds,
+                            directions, event.getOriginator());
                 }
             }
         });
diff --git a/client/src/com/vaadin/client/ui/grid/sort/SortEvent.java b/client/src/com/vaadin/client/ui/grid/sort/SortEvent.java
index baa12ae224..edbd84c4a5 100644
--- a/client/src/com/vaadin/client/ui/grid/sort/SortEvent.java
+++ b/client/src/com/vaadin/client/ui/grid/sort/SortEvent.java
@@ -20,6 +20,7 @@ import java.util.List;
 import com.google.gwt.event.shared.GwtEvent;
 import com.vaadin.client.data.DataSource;
 import com.vaadin.client.ui.grid.Grid;
+import com.vaadin.shared.ui.grid.SortEventOriginator;
 
 /**
  * A sort event, fired by the Grid when it needs its data source to provide data
@@ -34,6 +35,7 @@ public class SortEvent<T> extends GwtEvent<SortEventHandler<?>> {
 
     private final Grid<T> grid;
     private final List<SortOrder> order;
+    private final SortEventOriginator originator;
 
     /**
      * Creates a new Sort Event. All provided parameters are final, and passed
@@ -41,14 +43,16 @@ public class SortEvent<T> extends GwtEvent<SortEventHandler<?>> {
      *
      * @param grid
      *            a grid reference
-     * @param datasource
-     *            a reference to the grid's data source
      * @param order
      *            an array dictating the desired sort order of the data source
+     * @param originator
+     *            a value indicating where this event originated from
      */
-    public SortEvent(Grid<T> grid, List<SortOrder> order) {
+    public SortEvent(Grid<T> grid, List<SortOrder> order,
+            SortEventOriginator originator) {
         this.grid = grid;
         this.order = order;
+        this.originator = originator;
     }
 
     @Override
@@ -103,6 +107,18 @@ public class SortEvent<T> extends GwtEvent<SortEventHandler<?>> {
         return order;
     }
 
+    /**
+     * Gets a value describing the originator of this event, i.e. what actions
+     * resulted in this event being fired.
+     * 
+     * @return a sort event originator value
+     * 
+     * @see SortEventOriginator
+     */
+    public SortEventOriginator getOriginator() {
+        return originator;
+    }
+
     @SuppressWarnings("unchecked")
     @Override
     protected void dispatch(SortEventHandler<?> handler) {
diff --git a/server/src/com/vaadin/ui/components/grid/Grid.java b/server/src/com/vaadin/ui/components/grid/Grid.java
index fba6eed462..3c115f9241 100644
--- a/server/src/com/vaadin/ui/components/grid/Grid.java
+++ b/server/src/com/vaadin/ui/components/grid/Grid.java
@@ -49,6 +49,7 @@ import com.vaadin.shared.ui.grid.GridStaticCellType;
 import com.vaadin.shared.ui.grid.HeightMode;
 import com.vaadin.shared.ui.grid.ScrollDestination;
 import com.vaadin.shared.ui.grid.SortDirection;
+import com.vaadin.shared.ui.grid.SortEventOriginator;
 import com.vaadin.ui.AbstractComponent;
 import com.vaadin.ui.Component;
 import com.vaadin.ui.HasComponents;
@@ -373,7 +374,8 @@ public class Grid extends AbstractComponent implements SelectionChangeNotifier,
             }
 
             @Override
-            public void sort(String[] columnIds, SortDirection[] directions) {
+            public void sort(String[] columnIds, SortDirection[] directions,
+                    SortEventOriginator originator) {
                 assert columnIds.length == directions.length;
 
                 List<SortOrder> order = new ArrayList<SortOrder>(
@@ -383,7 +385,7 @@ public class Grid extends AbstractComponent implements SelectionChangeNotifier,
                     order.add(new SortOrder(propertyId, directions[i]));
                 }
 
-                setSortOrder(order);
+                setSortOrder(order, originator);
             }
         });
     }
@@ -439,7 +441,7 @@ public class Grid extends AbstractComponent implements SelectionChangeNotifier,
                 }
             }
 
-            sort();
+            sort(SortEventOriginator.INTERNAL);
         } else {
 
             // If the new container is not sortable, we'll just re-set the sort
@@ -1126,7 +1128,7 @@ public class Grid extends AbstractComponent implements SelectionChangeNotifier,
      */
     public void clearSortOrder() {
         sortOrder.clear();
-        sort();
+        sort(false);
     }
 
     /**
@@ -1140,6 +1142,11 @@ public class Grid extends AbstractComponent implements SelectionChangeNotifier,
      *            a sort order list.
      */
     public void setSortOrder(List<SortOrder> order) {
+        setSortOrder(order, SortEventOriginator.API);
+    }
+
+    private void setSortOrder(List<SortOrder> order,
+            SortEventOriginator originator) {
         if (!(getContainerDatasource() instanceof Container.Sortable)) {
             throw new IllegalStateException(
                     "Attached container is not sortable (does not implement Container.Sortable)");
@@ -1164,7 +1171,7 @@ public class Grid extends AbstractComponent implements SelectionChangeNotifier,
         }
 
         sortOrder.addAll(order);
-        sort();
+        sort(originator);
     }
 
     /**
@@ -1179,7 +1186,7 @@ public class Grid extends AbstractComponent implements SelectionChangeNotifier,
     /**
      * Apply sorting to data source.
      */
-    private void sort() {
+    private void sort(SortEventOriginator originator) {
 
         Container c = getContainerDatasource();
         if (c instanceof Container.Sortable) {
@@ -1215,7 +1222,7 @@ public class Grid extends AbstractComponent implements SelectionChangeNotifier,
             cs.sort(propertyIds, directions);
 
             fireEvent(new SortOrderChangeEvent(this, new ArrayList<SortOrder>(
-                    sortOrder)));
+                    sortOrder), originator));
 
             getState().sortColumns = columnKeys;
             getState(false).sortDirs = stateDirs;
diff --git a/server/src/com/vaadin/ui/components/grid/SortOrderChangeEvent.java b/server/src/com/vaadin/ui/components/grid/SortOrderChangeEvent.java
index 71afa10a9b..690fcdf1c4 100644
--- a/server/src/com/vaadin/ui/components/grid/SortOrderChangeEvent.java
+++ b/server/src/com/vaadin/ui/components/grid/SortOrderChangeEvent.java
@@ -17,6 +17,7 @@ package com.vaadin.ui.components.grid;
 
 import java.util.List;
 
+import com.vaadin.shared.ui.grid.SortEventOriginator;
 import com.vaadin.ui.Component;
 import com.vaadin.ui.components.grid.sort.SortOrder;
 
@@ -31,6 +32,7 @@ import com.vaadin.ui.components.grid.sort.SortOrder;
 public class SortOrderChangeEvent extends Component.Event {
 
     private final List<SortOrder> sortOrder;
+    private final SortEventOriginator originator;
 
     /**
      * Creates a new sort order change event for a grid and a sort order list.
@@ -39,10 +41,15 @@ public class SortOrderChangeEvent extends Component.Event {
      *            the grid from which the event originates
      * @param sortOrder
      *            the new sort order list
+     * @param wasInitiatedByUser
+     *            should be set to true if this event results from end-user
+     *            interaction instead of an API call or side effect
      */
-    public SortOrderChangeEvent(Grid grid, List<SortOrder> sortOrder) {
+    public SortOrderChangeEvent(Grid grid, List<SortOrder> sortOrder,
+            SortEventOriginator originator) {
         super(grid);
         this.sortOrder = sortOrder;
+        this.originator = originator;
     }
 
     /**
@@ -54,4 +61,16 @@ public class SortOrderChangeEvent extends Component.Event {
         return sortOrder;
     }
 
+    /**
+     * Gets a value describing the originator of this event, i.e. what actions
+     * resulted in this event being fired.
+     * 
+     * @return a sort event originator value
+     * 
+     * @see SortEventOriginator
+     */
+    public SortEventOriginator getOriginator() {
+        return originator;
+    }
+
 }
diff --git a/shared/src/com/vaadin/shared/ui/grid/GridServerRpc.java b/shared/src/com/vaadin/shared/ui/grid/GridServerRpc.java
index 9ce094b092..fd671e30a7 100644
--- a/shared/src/com/vaadin/shared/ui/grid/GridServerRpc.java
+++ b/shared/src/com/vaadin/shared/ui/grid/GridServerRpc.java
@@ -28,5 +28,6 @@ import com.vaadin.shared.communication.ServerRpc;
 public interface GridServerRpc extends ServerRpc {
     void selectionChange(List<String> newSelection);
 
-    void sort(String[] columnIds, SortDirection[] directions);
+    void sort(String[] columnIds, SortDirection[] directions,
+            SortEventOriginator originator);
 }
diff --git a/shared/src/com/vaadin/shared/ui/grid/SortEventOriginator.java b/shared/src/com/vaadin/shared/ui/grid/SortEventOriginator.java
new file mode 100644
index 0000000000..acdd46ea5b
--- /dev/null
+++ b/shared/src/com/vaadin/shared/ui/grid/SortEventOriginator.java
@@ -0,0 +1,41 @@
+/*
+ * 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.shared.ui.grid;
+
+/**
+ * Identifier for the originator of a sort event or sort order change event.
+ * 
+ * @since
+ * @author Vaadin Ltd
+ */
+public enum SortEventOriginator {
+
+    /**
+     * This event was the result of an API call.
+     */
+    API,
+
+    /**
+     * This event was the result of a user interacting with the UI.
+     */
+    USER,
+
+    /**
+     * This event resulted as a side-effect of an internal event.
+     */
+    INTERNAL
+
+}
diff --git a/uitest/src/com/vaadin/tests/components/grid/basicfeatures/GridBasicFeatures.java b/uitest/src/com/vaadin/tests/components/grid/basicfeatures/GridBasicFeatures.java
index 031ebf7fa5..d54b1838ea 100644
--- a/uitest/src/com/vaadin/tests/components/grid/basicfeatures/GridBasicFeatures.java
+++ b/uitest/src/com/vaadin/tests/components/grid/basicfeatures/GridBasicFeatures.java
@@ -168,7 +168,24 @@ public class GridBasicFeatures extends AbstractComponentTest<Grid> {
         grid.addSortOrderChangeListener(new SortOrderChangeListener() {
             @Override
             public void sortOrderChange(SortOrderChangeEvent event) {
-                log("Sort order: " + event.getSortOrder());
+
+                String origin;
+                switch (event.getOriginator()) {
+                case API:
+                    origin = "API";
+                    break;
+                case INTERNAL:
+                    origin = "INTERNAL";
+                    break;
+                case USER:
+                    origin = "USER";
+                    break;
+                default:
+                    origin = "!!! ERROR !!!";
+                    break;
+                }
+
+                log("Sort order: " + event.getSortOrder() + " by " + origin);
             }
         });
 
diff --git a/uitest/src/com/vaadin/tests/components/grid/basicfeatures/server/GridSortingTest.java b/uitest/src/com/vaadin/tests/components/grid/basicfeatures/server/GridSortingTest.java
index a5a83c156e..024be65e83 100644
--- a/uitest/src/com/vaadin/tests/components/grid/basicfeatures/server/GridSortingTest.java
+++ b/uitest/src/com/vaadin/tests/components/grid/basicfeatures/server/GridSortingTest.java
@@ -42,6 +42,11 @@ public class GridSortingTest extends GridBasicFeaturesTest {
         // First cells for first 3 rows are (9, 0), (99, 0) and (999, 0)
         sortBy("Column 9, DESC");
 
+        // Verify that programmatic sorting calls are identified as originating
+        // from API
+        assertEquals("3. Sort order: [Column 9 DESCENDING] by API",
+                getLogRow(0));
+
         assertTrue("Column 9 should have the sort-desc stylename", grid
                 .getHeaderCell(0, 9).getAttribute("class")
                 .contains("sort-desc"));
@@ -119,14 +124,17 @@ public class GridSortingTest extends GridBasicFeaturesTest {
                     "(" + row + ", 0)", grid.getCell(i, 0).getText());
         }
 
-        assertEquals("2. Sort order: [Column 9 ASCENDING]", getLogRow(2));
-        assertEquals("4. Sort order: [Column 9 DESCENDING]", getLogRow(0));
+        assertEquals("2. Sort order: [Column 9 ASCENDING] by USER",
+                getLogRow(2));
+        assertEquals("4. Sort order: [Column 9 DESCENDING] by USER",
+                getLogRow(0));
 
         // Column 10 is random numbers from Random with seed 13334
         // Click header to sort ascending
         grid.getHeaderCell(0, 10).click();
 
-        assertEquals("6. Sort order: [Column 10 ASCENDING]", getLogRow(0));
+        assertEquals("6. Sort order: [Column 10 ASCENDING] by USER",
+                getLogRow(0));
 
         // Not cleaning up correctly causes exceptions when scrolling.
         grid.scrollToRow(50);
@@ -153,8 +161,10 @@ public class GridSortingTest extends GridBasicFeaturesTest {
                     grid.getCell(GridBasicFeatures.ROWS - (i + 1), 0).getText());
         }
 
-        assertEquals("9. Sort order: [Column 7 ASCENDING]", getLogRow(3));
-        assertEquals("11. Sort order: [Column 7 DESCENDING]", getLogRow(1));
+        assertEquals("9. Sort order: [Column 7 ASCENDING] by USER",
+                getLogRow(3));
+        assertEquals("11. Sort order: [Column 7 DESCENDING] by USER",
+                getLogRow(1));
     }
 
     @Test