Let UI fire PollEvents (#12466)

Change-Id: I7eb5e407b6822f5b3ac8e103ba7c9f676c51648f

5 files changed, 220 insertions, 6 deletions

diff --git a/server/src/com/vaadin/event/UIEvents.java b/server/src/com/vaadin/event/UIEvents.java
new file mode 100644
index 0000000000..321bfc9251
--- /dev/null
+++ b/server/src/com/vaadin/event/UIEvents.java
@@ -0,0 +1,116 @@
+/*
+ * Copyright 2000-2013 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.event;
+
+import java.io.Serializable;
+import java.lang.reflect.Method;
+
+import com.vaadin.ui.Component;
+import com.vaadin.ui.UI;
+import com.vaadin.util.ReflectTools;
+
+/**
+ * A class that contains events, listeners and handlers specific to the
+ * {@link UI} class.
+ * 
+ * @since 7.2
+ * @author Vaadin Ltd
+ */
+public interface UIEvents {
+
+    /**
+     * A {@link PollListener} receives and handles {@link PollEvent PollEvents}
+     * fired by {@link PollNotifier PollNotifiers}.
+     * 
+     * @since 7.2
+     * @author Vaadin Ltd
+     */
+    public interface PollListener extends Serializable {
+        public static final Method POLL_METHOD = ReflectTools.findMethod(
+                PollListener.class, "poll", PollEvent.class);
+
+        /**
+         * A poll request has been received by the server.
+         * 
+         * @param event
+         *            poll event
+         */
+        public void poll(PollEvent event);
+    }
+
+    /**
+     * An event that is fired whenever a client polls the server for
+     * asynchronous UI updates.
+     * 
+     * @since 7.2
+     * @author Vaadin Ltd
+     */
+    public static class PollEvent extends Component.Event {
+        public PollEvent(UI ui) {
+            super(ui);
+        }
+
+        /**
+         * Get the {@link UI} instance that received the poll request.
+         * 
+         * @return the {@link UI} that received the poll request. Never
+         *         <code>null</code>.
+         */
+        public UI getUI() {
+            /*
+             * This cast is safe to make, since this class' constructor
+             * constrains the source to be a UI instance.
+             */
+            return (UI) getComponent();
+        }
+    }
+
+    /**
+     * The interface for adding and removing {@link PollEvent} listeners.
+     * <p>
+     * By implementing this interface, a class publicly announces that it is
+     * able to send {@link PollEvent PollEvents} whenever the client sends a
+     * periodic poll message to the client, to check for asynchronous
+     * server-side modifications.
+     * 
+     * @since 7.2
+     * @see UI#setPollInterval(int)
+     */
+    public interface PollNotifier extends Serializable {
+        /**
+         * Add a poll listener.
+         * <p>
+         * The listener is called whenever the client polls the server for
+         * asynchronous UI updates.
+         * 
+         * @see UI#setPollInterval(int)
+         * @see #removePollListener(PollListener)
+         * @param listener
+         *            the {@link PollListener} to add
+         */
+        public void addPollListener(PollListener listener);
+
+        /**
+         * Remove a poll listener.
+         * 
+         * @see #addPollListener(PollListener)
+         * @param listener
+         *            the listener to be removed
+         */
+        public void removePollListener(PollListener listener);
+    }
+
+}
diff --git a/server/src/com/vaadin/ui/UI.java b/server/src/com/vaadin/ui/UI.java
index 0d2ef4d569..a292e6b829 100644
--- a/server/src/com/vaadin/ui/UI.java
+++ b/server/src/com/vaadin/ui/UI.java
@@ -32,6 +32,9 @@ import com.vaadin.event.Action.Handler;
 import com.vaadin.event.ActionManager;
 import com.vaadin.event.MouseEvents.ClickEvent;
 import com.vaadin.event.MouseEvents.ClickListener;
+import com.vaadin.event.UIEvents.PollEvent;
+import com.vaadin.event.UIEvents.PollListener;
+import com.vaadin.event.UIEvents.PollNotifier;
 import com.vaadin.navigator.Navigator;
 import com.vaadin.server.ClientConnector;
 import com.vaadin.server.ComponentSizeValidator;
@@ -95,7 +98,8 @@ import com.vaadin.util.CurrentInstance;
  * @since 7.0
  */
 public abstract class UI extends AbstractSingleComponentContainer implements
-        Action.Container, Action.Notifier, LegacyComponent, Focusable {
+        Action.Container, Action.Notifier, PollNotifier, LegacyComponent,
+        Focusable {
 
     /**
      * The application to which this UI belongs
@@ -167,10 +171,7 @@ public abstract class UI extends AbstractSingleComponentContainer implements
 
         @Override
         public void poll() {
-            /*
-             * No-op. This is only called to cause a server visit to check for
-             * changes.
-             */
+            fireEvent(new PollEvent(UI.this));
         }
     };
     private DebugWindowServerRpc debugRpc = new DebugWindowServerRpc() {
@@ -1490,6 +1491,17 @@ public abstract class UI extends AbstractSingleComponentContainer implements
         return getState(false).pollInterval;
     }
 
+    @Override
+    public void addPollListener(PollListener listener) {
+        addListener(EventId.POLL, PollEvent.class, listener,
+                PollListener.POLL_METHOD);
+    }
+
+    @Override
+    public void removePollListener(PollListener listener) {
+        removeListener(EventId.POLL, PollEvent.class, listener);
+    }
+
     /**
      * Retrieves the object used for configuring the push channel.
      * 
diff --git a/shared/src/com/vaadin/shared/EventId.java b/shared/src/com/vaadin/shared/EventId.java
index dd30379d41..d669f8fa83 100644
--- a/shared/src/com/vaadin/shared/EventId.java
+++ b/shared/src/com/vaadin/shared/EventId.java
@@ -22,5 +22,5 @@ public interface EventId extends Serializable {
     public static final String FOCUS = "focus";
     public static final String CLICK_EVENT_IDENTIFIER = "click";
     public static final String LAYOUT_CLICK_EVENT_IDENTIFIER = "lClick";
-
+    public static final String POLL = "poll";
 }
diff --git a/uitest/src/com/vaadin/tests/components/ui/PollListenerTest.html b/uitest/src/com/vaadin/tests/components/ui/PollListenerTest.html
new file mode 100644
index 0000000000..ac39d1f03c
--- /dev/null
+++ b/uitest/src/com/vaadin/tests/components/ui/PollListenerTest.html
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head profile="http://selenium-ide.openqa.org/profiles/test-case">
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<link rel="selenium.base" href="http://localhost:8888/" />
+<title>PollListenerTest</title>
+</head>
+<body>
+<table cellpadding="1" cellspacing="1" border="1">
+<thead>
+<tr><td rowspan="1" colspan="3">PollListenerTest</td></tr>
+</thead><tbody>
+<tr>
+	<td>open</td>
+	<td>/run/com.vaadin.tests.components.ui.PollListenerTest?restartApplication</td>
+	<td></td>
+</tr>
+<tr>
+	<td>pause</td>
+	<td>5000</td>
+	<td></td>
+</tr>
+<tr>
+	<td>verifyTextPresent</td>
+	<td>PollEvent received</td>
+	<td></td>
+</tr>
+
+</tbody></table>
+</body>
+</html>
diff --git a/uitest/src/com/vaadin/tests/components/ui/PollListenerTest.java b/uitest/src/com/vaadin/tests/components/ui/PollListenerTest.java
new file mode 100644
index 0000000000..0e5ddaab87
--- /dev/null
+++ b/uitest/src/com/vaadin/tests/components/ui/PollListenerTest.java
@@ -0,0 +1,54 @@
+/*
+ * Copyright 2000-2013 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.components.ui;
+
+import com.vaadin.event.UIEvents.PollEvent;
+import com.vaadin.event.UIEvents.PollListener;
+import com.vaadin.server.VaadinRequest;
+import com.vaadin.tests.components.AbstractTestUI;
+import com.vaadin.ui.Label;
+
+public class PollListenerTest extends AbstractTestUI {
+
+    @Override
+    protected void setup(VaadinRequest request) {
+        final Label statusLabel = new Label("Default Label");
+        addComponent(statusLabel);
+
+        setPollInterval(2000);
+        addPollListener(new PollListener() {
+            @Override
+            public void poll(PollEvent event) {
+                setPollInterval(-1);
+                statusLabel.setValue(event.getClass().getSimpleName()
+                        + " received");
+                removePollListener(this);
+            }
+        });
+    }
+
+    @Override
+    protected String getTestDescription() {
+        return "Polling should fire a PollEvent on the server-side";
+    }
+
+    @Override
+    protected Integer getTicketNumber() {
+        return 12466;
+    }
+
+}