Rename runSafely() to access() (#11756)

Change-Id: I640244732fb561d9f55da58f8ba94fd02875c191

13 files changed, 66 insertions, 37 deletions

diff --git a/server/src/com/vaadin/server/RequestHandler.java b/server/src/com/vaadin/server/RequestHandler.java
index e04b223904..873752c5f2 100644
--- a/server/src/com/vaadin/server/RequestHandler.java
+++ b/server/src/com/vaadin/server/RequestHandler.java
@@ -37,8 +37,7 @@ public interface RequestHandler extends Serializable {
      * using VaadinSession or anything inside the VaadinSession you must ensure
      * the session is locked. This can be done by extending
      * {@link SynchronizedRequestHandler} or by using
-     * {@link VaadinSession#runSafely(Runnable)} or
-     * {@link UI#runSafely(Runnable)}.
+     * {@link VaadinSession#access(Runnable)} or {@link UI#access(Runnable)}.
      * </p>
      * 
      * @param session
diff --git a/server/src/com/vaadin/server/VaadinService.java b/server/src/com/vaadin/server/VaadinService.java
index c6fdca35f0..f6b520d4b0 100644
--- a/server/src/com/vaadin/server/VaadinService.java
+++ b/server/src/com/vaadin/server/VaadinService.java
@@ -407,12 +407,12 @@ public abstract class VaadinService implements Serializable {
      */
     public void fireSessionDestroy(VaadinSession vaadinSession) {
         final VaadinSession session = vaadinSession;
-        session.runSafely(new Runnable() {
+        session.access(new Runnable() {
             @Override
             public void run() {
                 ArrayList<UI> uis = new ArrayList<UI>(session.getUIs());
                 for (final UI ui : uis) {
-                    ui.runSafely(new Runnable() {
+                    ui.access(new Runnable() {
                         @Override
                         public void run() {
                             /*
@@ -1087,7 +1087,7 @@ public abstract class VaadinService implements Serializable {
     private void removeClosedUIs(final VaadinSession session) {
         ArrayList<UI> uis = new ArrayList<UI>(session.getUIs());
         for (final UI ui : uis) {
-            ui.runSafely(new Runnable() {
+            ui.access(new Runnable() {
                 @Override
                 public void run() {
                     if (ui.isClosing()) {
@@ -1245,7 +1245,7 @@ public abstract class VaadinService implements Serializable {
         if (session != null) {
             final VaadinSession finalSession = session;
 
-            session.runSafely(new Runnable() {
+            session.access(new Runnable() {
                 @Override
                 public void run() {
                     cleanupSession(finalSession);
@@ -1254,7 +1254,7 @@ public abstract class VaadinService implements Serializable {
 
             final long duration = (System.nanoTime() - (Long) request
                     .getAttribute(REQUEST_START_TIME_ATTRIBUTE)) / 1000000;
-            session.runSafely(new Runnable() {
+            session.access(new Runnable() {
                 @Override
                 public void run() {
                     finalSession.setLastRequestDuration(duration);
diff --git a/server/src/com/vaadin/server/VaadinSession.java b/server/src/com/vaadin/server/VaadinSession.java
index 57e9076342..fe786ad52b 100644
--- a/server/src/com/vaadin/server/VaadinSession.java
+++ b/server/src/com/vaadin/server/VaadinSession.java
@@ -766,13 +766,12 @@ public class VaadinSession implements HttpSessionBindingListener, Serializable {
      * Locks this session to protect its data from concurrent access. Accessing
      * the UI state from outside the normal request handling should always lock
      * the session and unlock it when done. The preferred way to ensure locking
-     * is done correctly is to wrap your code using
-     * {@link UI#runSafely(Runnable)} (or
-     * {@link VaadinSession#runSafely(Runnable)} if you are only touching the
+     * is done correctly is to wrap your code using {@link UI#access(Runnable)}
+     * (or {@link VaadinSession#access(Runnable)} if you are only touching the
      * session and not any UI), e.g.:
      * 
      * <pre>
-     * myUI.runSafely(new Runnable() {
+     * myUI.access(new Runnable() {
      *     &#064;Override
      *     public void run() {
      *         // Here it is safe to update the UI.
@@ -1064,23 +1063,27 @@ public class VaadinSession implements HttpSessionBindingListener, Serializable {
     }
 
     /**
-     * Performs a safe update of this VaadinSession.
+     * Provides exclusive access to this session from outside a request handling
+     * thread.
      * <p>
-     * This method runs the runnable code so that it is safe to update session
-     * variables. It also ensures that all thread locals are set correctly when
-     * executing the runnable.
+     * The given runnable is executed while holding the session lock to ensure
+     * exclusive access to this session. The session and related thread locals
+     * are set properly before executing the runnable.
      * </p>
      * <p>
-     * Note that using this method for a VaadinSession which has been detached
-     * from its underlying HTTP session is not necessarily safe. Exclusive
-     * access is provided through locking which is done using the underlying
-     * session.
+     * RPC handlers for components inside this session do not need this method
+     * as the session is automatically locked by the framework during request
+     * handling.
      * </p>
      * 
      * @param runnable
-     *            The runnable which updates the session
+     *            the runnable which accesses the session
+     * 
+     * @see #lock()
+     * @see #getCurrent()
+     * @see UI#access(Runnable)
      */
-    public void runSafely(Runnable runnable) {
+    public void access(Runnable runnable) {
         Map<Class<?>, CurrentInstance> old = null;
         lock();
         try {
@@ -1096,6 +1099,15 @@ public class VaadinSession implements HttpSessionBindingListener, Serializable {
     }
 
     /**
+     * @deprecated As of 7.1.0.beta1, use {@link #access(Runnable)} instead.
+     *             This method will be removed before the final 7.1.0 release.
+     */
+    @Deprecated
+    public void runSafely(Runnable runnable) {
+        access(runnable);
+    }
+
+    /**
      * Gets the CSRF token (aka double submit cookie) that is used to protect
      * against Cross Site Request Forgery attacks.
      * 
diff --git a/server/src/com/vaadin/server/communication/FileUploadHandler.java b/server/src/com/vaadin/server/communication/FileUploadHandler.java
index 1f5011a42e..e875a4e861 100644
--- a/server/src/com/vaadin/server/communication/FileUploadHandler.java
+++ b/server/src/com/vaadin/server/communication/FileUploadHandler.java
@@ -632,7 +632,7 @@ public class FileUploadHandler implements RequestHandler {
 
     private void cleanStreamVariable(VaadinSession session,
             final ClientConnector owner, final String variableName) {
-        session.runSafely(new Runnable() {
+        session.access(new Runnable() {
             @Override
             public void run() {
                 owner.getUI()
diff --git a/server/src/com/vaadin/ui/LoginForm.java b/server/src/com/vaadin/ui/LoginForm.java
index 20ad392679..d06882927e 100644
--- a/server/src/com/vaadin/ui/LoginForm.java
+++ b/server/src/com/vaadin/ui/LoginForm.java
@@ -68,7 +68,7 @@ public class LoginForm extends CustomComponent {
         }
         final StringBuilder responseBuilder = new StringBuilder();
 
-        getUI().runSafely(new Runnable() {
+        getUI().access(new Runnable() {
             @Override
             public void run() {
                 String method = VaadinServletService.getCurrentServletRequest()
diff --git a/server/src/com/vaadin/ui/UI.java b/server/src/com/vaadin/ui/UI.java
index 442edfebb1..f260a6af79 100644
--- a/server/src/com/vaadin/ui/UI.java
+++ b/server/src/com/vaadin/ui/UI.java
@@ -1092,20 +1092,29 @@ public abstract class UI extends AbstractSingleComponentContainer implements
     }
 
     /**
-     * Performs a safe update of this UI.
+     * Provides exclusive access to this UI from outside a request handling
+     * thread.
      * <p>
-     * This method runs the runnable code so that it is safe to update UI and
-     * session variables. It also ensures that all thread locals are set
-     * correctly when executing the runnable.
+     * The given runnable is executed while holding the session lock to ensure
+     * exclusive access to this UI and its session. The UI and related thread
+     * locals are set properly before executing the runnable.
+     * </p>
+     * <p>
+     * RPC handlers for components inside this UI do not need this method as the
+     * session is automatically locked by the framework during request handling.
      * </p>
      * 
      * @param runnable
-     *            The runnable which updates the UI
+     *            the runnable which accesses the UI
      * @throws UIDetachedException
      *             if the UI is not attached to a session (and locking can
      *             therefore not be done)
+     * 
+     * @see #getCurrent()
+     * @see VaadinSession#access(Runnable)
+     * @see VaadinSession#lock()
      */
-    public void runSafely(Runnable runnable) throws UIDetachedException {
+    public void access(Runnable runnable) throws UIDetachedException {
         Map<Class<?>, CurrentInstance> old = null;
 
         VaadinSession session = getSession();
@@ -1118,7 +1127,7 @@ public abstract class UI extends AbstractSingleComponentContainer implements
         try {
             if (getSession() == null) {
                 // UI was detached after fetching the session but before we
-                // acquiried the lock.
+                // acquired the lock.
                 throw new UIDetachedException();
             }
             old = CurrentInstance.setThreadLocals(this);
@@ -1133,6 +1142,15 @@ public abstract class UI extends AbstractSingleComponentContainer implements
     }
 
     /**
+     * @deprecated As of 7.1.0.beta1, use {@link #access(Runnable)} instead.
+     *             This method will be removed before the final 7.1.0 release.
+     */
+    @Deprecated
+    public void runSafely(Runnable runnable) throws UIDetachedException {
+        access(runnable);
+    }
+
+    /**
      * Retrieves the object used for configuring tooltips.
      * 
      * @return The instance used for tooltip configuration
diff --git a/uitest/src/com/vaadin/tests/applicationcontext/CloseUI.java b/uitest/src/com/vaadin/tests/applicationcontext/CloseUI.java
index 47d53c8f52..bec8c0a10f 100644
--- a/uitest/src/com/vaadin/tests/applicationcontext/CloseUI.java
+++ b/uitest/src/com/vaadin/tests/applicationcontext/CloseUI.java
@@ -119,7 +119,7 @@ public class CloseUI extends AbstractTestUI {
 
         @Override
         public void run() {
-            ui.runSafely(new Runnable() {
+            ui.access(new Runnable() {
 
                 @Override
                 public void run() {
diff --git a/uitest/src/com/vaadin/tests/applicationcontext/UIRunSafelyThread.java b/uitest/src/com/vaadin/tests/applicationcontext/UIRunSafelyThread.java
index 0048cbd741..ddc0f28664 100644
--- a/uitest/src/com/vaadin/tests/applicationcontext/UIRunSafelyThread.java
+++ b/uitest/src/com/vaadin/tests/applicationcontext/UIRunSafelyThread.java
@@ -11,7 +11,7 @@ public abstract class UIRunSafelyThread extends Thread {
 
     @Override
     public void run() {
-        ui.runSafely(new Runnable() {
+        ui.access(new Runnable() {
 
             @Override
             public void run() {
diff --git a/uitest/src/com/vaadin/tests/components/ui/UIPolling.java b/uitest/src/com/vaadin/tests/components/ui/UIPolling.java
index a7add63801..48671191ca 100644
--- a/uitest/src/com/vaadin/tests/components/ui/UIPolling.java
+++ b/uitest/src/com/vaadin/tests/components/ui/UIPolling.java
@@ -39,7 +39,7 @@ public class UIPolling extends AbstractTestUIWithLog {
                 } catch (InterruptedException e) {
                 }
                 final int iteration = i;
-                runSafely(new Runnable() {
+                access(new Runnable() {
                     @Override
                     public void run() {
                         log.log((iteration * SLEEP_TIME) + "ms has passed");
diff --git a/uitest/src/com/vaadin/tests/minitutorials/broadcastingmessages/BroadcasterUI.java b/uitest/src/com/vaadin/tests/minitutorials/broadcastingmessages/BroadcasterUI.java
index 88ab4af967..06ead20db3 100644
--- a/uitest/src/com/vaadin/tests/minitutorials/broadcastingmessages/BroadcasterUI.java
+++ b/uitest/src/com/vaadin/tests/minitutorials/broadcastingmessages/BroadcasterUI.java
@@ -43,7 +43,7 @@ public class BroadcasterUI extends UI implements BroadcastListener {
 
     @Override
     public void receiveBroadcast(final String message) {
-        runSafely(new Runnable() {
+        access(new Runnable() {
             @Override
             public void run() {
                 Notification n = new Notification("Message received", message,
diff --git a/uitest/src/com/vaadin/tests/push/BasicPush.java b/uitest/src/com/vaadin/tests/push/BasicPush.java
index 43f8236999..b80d287a1d 100644
--- a/uitest/src/com/vaadin/tests/push/BasicPush.java
+++ b/uitest/src/com/vaadin/tests/push/BasicPush.java
@@ -27,7 +27,7 @@ public class BasicPush extends AbstractTestUI {
 
         @Override
         public void run() {
-            runSafely(new Runnable() {
+            access(new Runnable() {
                 @Override
                 public void run() {
                     counter2.setValue(counter2.getValue() + 1);
diff --git a/uitest/src/com/vaadin/tests/push/PushFromInit.java b/uitest/src/com/vaadin/tests/push/PushFromInit.java
index c43739ec04..4b442de499 100644
--- a/uitest/src/com/vaadin/tests/push/PushFromInit.java
+++ b/uitest/src/com/vaadin/tests/push/PushFromInit.java
@@ -11,7 +11,7 @@ public class PushFromInit extends AbstractTestUIWithLog {
         new Thread() {
             @Override
             public void run() {
-                runSafely(new Runnable() {
+                access(new Runnable() {
                     @Override
                     public void run() {
                         log("Logged from background thread started in init");
diff --git a/uitest/src/com/vaadin/tests/push/TogglePush.java b/uitest/src/com/vaadin/tests/push/TogglePush.java
index 8e9eafeabb..24358e648a 100644
--- a/uitest/src/com/vaadin/tests/push/TogglePush.java
+++ b/uitest/src/com/vaadin/tests/push/TogglePush.java
@@ -52,7 +52,7 @@ public class TogglePush extends AbstractTestUI {
                         new Timer().schedule(new TimerTask() {
                             @Override
                             public void run() {
-                                runSafely(new Runnable() {
+                                access(new Runnable() {
                                     @Override
                                     public void run() {
                                         updateCounter();