Rename isViewChangeAllowed()/navigatorViewChanged() to beforeViewChange()/afterViewChange() (#9511)

2 files changed, 29 insertions, 23 deletions

diff --git a/server/src/com/vaadin/navigator/Navigator.java b/server/src/com/vaadin/navigator/Navigator.java
index f05d3678a5..157a97ac0e 100644
--- a/server/src/com/vaadin/navigator/Navigator.java
+++ b/server/src/com/vaadin/navigator/Navigator.java
@@ -475,7 +475,7 @@ public class Navigator implements Serializable {
     protected void navigateTo(View view, String viewName, String parameters) {
         ViewChangeEvent event = new ViewChangeEvent(this, currentView, view,
                 viewName, parameters);
-        if (!isViewChangeAllowed(event)) {
+        if (!fireBeforeViewChange(event)) {
             return;
         }
 
@@ -496,15 +496,16 @@ public class Navigator implements Serializable {
             display.showView(view);
         }
 
-        fireViewChange(event);
+        fireAfterViewChange(event);
     }
 
     /**
-     * Check whether view change is allowed.
-     * 
-     * All related listeners are called. The view change is blocked if any of
-     * them wants to block the navigation operation.
-     * 
+     * Fires an event before an imminent view change.
+     * <p>
+     * Listeners are called in registration order. If any listener returns
+     * <code>false</code>, the rest of the listeners are not called and the view
+     * change is blocked.
+     * <p>
      * The view change listeners may also e.g. open a warning or question dialog
      * and save the parameters to re-initiate the navigation operation upon user
      * action.
@@ -514,9 +515,9 @@ public class Navigator implements Serializable {
      * @return true if the view change should be allowed, false to silently
      *         block the navigation operation
      */
-    protected boolean isViewChangeAllowed(ViewChangeEvent event) {
+    protected boolean fireBeforeViewChange(ViewChangeEvent event) {
         for (ViewChangeListener l : listeners) {
-            if (!l.isViewChangeAllowed(event)) {
+            if (!l.beforeViewChange(event)) {
                 return false;
             }
         }
@@ -545,14 +546,16 @@ public class Navigator implements Serializable {
     }
 
     /**
-     * Fire an event when the current view has changed.
+     * Fires an event after the current view has changed.
+     * <p>
+     * Listeners are called in registration order.
      * 
      * @param event
      *            view change event (not null)
      */
-    protected void fireViewChange(ViewChangeEvent event) {
+    protected void fireAfterViewChange(ViewChangeEvent event) {
         for (ViewChangeListener l : listeners) {
-            l.navigatorViewChanged(event);
+            l.afterViewChange(event);
         }
     }
 
@@ -661,7 +664,7 @@ public class Navigator implements Serializable {
      * The listener will get notified after the view has changed.
      * 
      * @param listener
-     *            Listener to invoke after view changes.
+     *            Listener to invoke during a view change.
      */
     public void addViewChangeListener(ViewChangeListener listener) {
         listeners.add(listener);
diff --git a/server/src/com/vaadin/navigator/ViewChangeListener.java b/server/src/com/vaadin/navigator/ViewChangeListener.java
index aa09f64ad8..f3671821a5 100644
--- a/server/src/com/vaadin/navigator/ViewChangeListener.java
+++ b/server/src/com/vaadin/navigator/ViewChangeListener.java
@@ -102,29 +102,32 @@ public interface ViewChangeListener extends Serializable {
     }
 
     /**
-     * Check whether changing the view is permissible.
-     * 
-     * This method may also e.g. open a "save" dialog or question about the
-     * change, which may re-initiate the navigation operation after user action.
-     * 
+     * Invoked before the view is changed.
+     * <p>
+     * This method may e.g. open a "save" dialog or question about the change,
+     * which may re-initiate the navigation operation after user action.
+     * <p>
      * If this listener does not want to block the view change (e.g. does not
      * know the view in question), it should return true. If any listener
-     * returns false, the view change is not allowed.
+     * returns false, the view change is not allowed and
+     * <code>afterViewChange()</code> methods are not called.
      * 
      * @param event
      *            view change event
      * @return true if the view change should be allowed or this listener does
      *         not care about the view change, false to block the change
      */
-    public boolean isViewChangeAllowed(ViewChangeEvent event);
+    public boolean beforeViewChange(ViewChangeEvent event);
 
     /**
-     * Invoked after the view has changed. Be careful for deadlocks if you
-     * decide to change the view again in the listener.
+     * Invoked after the view is changed. If a <code>beforeViewChange</code>
+     * method blocked the view change, this method is not called. Be careful of
+     * unbounded recursion if you decide to change the view again in the
+     * listener.
      * 
      * @param event
      *            view change event
      */
-    public void navigatorViewChanged(ViewChangeEvent event);
+    public void afterViewChange(ViewChangeEvent event);
 
 }
\ No newline at end of file