Renamed Application and UI methods and fields from "Root" to "UI" (#8908).

1 files changed, 151 insertions, 156 deletions

diff --git a/server/src/com/vaadin/Application.java b/server/src/com/vaadin/Application.java
index 582e05d3f4..1827a55b72 100644
--- a/server/src/com/vaadin/Application.java
+++ b/server/src/com/vaadin/Application.java
@@ -57,8 +57,8 @@ import com.vaadin.terminal.ApplicationResource;
 import com.vaadin.terminal.CombinedRequest;
 import com.vaadin.terminal.DeploymentConfiguration;
 import com.vaadin.terminal.RequestHandler;
-import com.vaadin.terminal.RootProvider;
 import com.vaadin.terminal.Terminal;
+import com.vaadin.terminal.UIProvider;
 import com.vaadin.terminal.VariableOwner;
 import com.vaadin.terminal.WrappedRequest;
 import com.vaadin.terminal.WrappedRequest.BrowserDetails;
@@ -74,8 +74,8 @@ import com.vaadin.terminal.gwt.server.WebApplicationContext;
 import com.vaadin.tools.ReflectTools;
 import com.vaadin.ui.AbstractComponent;
 import com.vaadin.ui.AbstractField;
-import com.vaadin.ui.UI;
 import com.vaadin.ui.Table;
+import com.vaadin.ui.UI;
 import com.vaadin.ui.Window;
 
 /**
@@ -136,7 +136,7 @@ public class Application implements Terminal.ErrorListener, Serializable {
      * The name of the parameter that is by default used in e.g. web.xml to
      * define the name of the default {@link UI} class.
      */
-    public static final String ROOT_PARAMETER = "root";
+    public static final String UI_PARAMETER = "UI";
 
     private static final Method BOOTSTRAP_FRAGMENT_METHOD = ReflectTools
             .findMethod(BootstrapListener.class, "modifyBootstrapFragment",
@@ -167,14 +167,14 @@ public class Application implements Terminal.ErrorListener, Serializable {
         private UI.LegacyWindow mainWindow;
         private String theme;
 
-        private Map<String, UI.LegacyWindow> legacyRootNames = new HashMap<String, UI.LegacyWindow>();
+        private Map<String, UI.LegacyWindow> legacyUINames = new HashMap<String, UI.LegacyWindow>();
 
         /**
          * Sets the main window of this application. Setting window as a main
          * window of this application also adds the window to this application.
          * 
          * @param mainWindow
-         *            the root to set as the default window
+         *            the UI to set as the default window
          */
         public void setMainWindow(UI.LegacyWindow mainWindow) {
             if (this.mainWindow != null) {
@@ -201,7 +201,7 @@ public class Application implements Terminal.ErrorListener, Serializable {
          * Note that each application must have at least one main window.
          * </p>
          * 
-         * @return the root used as the default window
+         * @return the UI used as the default window
          */
         public UI.LegacyWindow getMainWindow() {
             return mainWindow;
@@ -215,11 +215,11 @@ public class Application implements Terminal.ErrorListener, Serializable {
          * {@inheritDoc}
          * 
          * @see #getWindow(String)
-         * @see Application#getRoot(WrappedRequest)
+         * @see Application#getUI(WrappedRequest)
          */
 
         @Override
-        public UI.LegacyWindow getRoot(WrappedRequest request) {
+        public UI.LegacyWindow getUI(WrappedRequest request) {
             String pathInfo = request.getRequestPathInfo();
             String name = null;
             if (pathInfo != null && pathInfo.length() > 0) {
@@ -239,8 +239,8 @@ public class Application implements Terminal.ErrorListener, Serializable {
         /**
          * Sets the application's theme.
          * <p>
-         * Note that this theme can be overridden for a specific root with
-         * {@link Application#getThemeForRoot(UI)}. Setting theme to be
+         * Note that this theme can be overridden for a specific UI with
+         * {@link Application#getThemeForUI(UI)}. Setting theme to be
          * <code>null</code> selects the default theme. For the available theme
          * names, see the contents of the VAADIN/themes directory.
          * </p>
@@ -272,30 +272,30 @@ public class Application implements Terminal.ErrorListener, Serializable {
          */
 
         @Override
-        public String getThemeForRoot(UI uI) {
+        public String getThemeForUI(UI uI) {
             return theme;
         }
 
         /**
          * <p>
-         * Gets a root by name. Returns <code>null</code> if the application is
+         * Gets a UI by name. Returns <code>null</code> if the application is
          * not running or it does not contain a window corresponding to the
          * name.
          * </p>
          * 
          * @param name
          *            the name of the requested window
-         * @return a root corresponding to the name, or <code>null</code> to use
+         * @return a UI corresponding to the name, or <code>null</code> to use
          *         the default window
          */
         public UI.LegacyWindow getWindow(String name) {
-            return legacyRootNames.get(name);
+            return legacyUINames.get(name);
         }
 
         /**
          * Counter to get unique names for windows with no explicit name
          */
-        private int namelessRootIndex = 0;
+        private int namelessUIIndex = 0;
 
         /**
          * Adds a new browser level window to this application. Please note that
@@ -303,25 +303,25 @@ public class Application implements Terminal.ErrorListener, Serializable {
          * window you should instead use {@link #addWindow(UI, String)}
          * 
          * @param uI
-         *            the root window to add to the application
+         *            the UI window to add to the application
          * @return returns the name that has been assigned to the window
          * 
          * @see #addWindow(UI, String)
          */
         public void addWindow(UI.LegacyWindow uI) {
             if (uI.getName() == null) {
-                String name = Integer.toString(namelessRootIndex++);
+                String name = Integer.toString(namelessUIIndex++);
                 uI.setName(name);
             }
 
-            legacyRootNames.put(uI.getName(), uI);
+            legacyUINames.put(uI.getName(), uI);
             uI.setApplication(this);
         }
 
         /**
          * Removes the specified window from the application. This also removes
-         * all name mappings for the window (see
-         * {@link #addWindow(UI, String) and #getWindowName(UI)}.
+         * all name mappings for the window (see {@link #addWindow(UI, String)
+         * and #getWindowName(UI)}.
          * 
          * <p>
          * Note that removing window from the application does not close the
@@ -329,13 +329,13 @@ public class Application implements Terminal.ErrorListener, Serializable {
          * </p>
          * 
          * @param uI
-         *            the root to remove
+         *            the UI to remove
          */
         public void removeWindow(UI.LegacyWindow uI) {
-            for (Entry<String, UI.LegacyWindow> entry : legacyRootNames
+            for (Entry<String, UI.LegacyWindow> entry : legacyUINames
                     .entrySet()) {
                 if (entry.getValue() == uI) {
-                    legacyRootNames.remove(entry.getKey());
+                    legacyUINames.remove(entry.getKey());
                 }
             }
         }
@@ -350,7 +350,7 @@ public class Application implements Terminal.ErrorListener, Serializable {
          * @return the unmodifiable collection of windows.
          */
         public Collection<UI.LegacyWindow> getWindows() {
-            return Collections.unmodifiableCollection(legacyRootNames.values());
+            return Collections.unmodifiableCollection(legacyUINames.values());
         }
     }
 
@@ -489,10 +489,10 @@ public class Application implements Terminal.ErrorListener, Serializable {
 
     private LinkedList<RequestHandler> requestHandlers = new LinkedList<RequestHandler>();
 
-    private int nextRootId = 0;
+    private int nextUIId = 0;
     private Map<Integer, UI> uIs = new HashMap<Integer, UI>();
 
-    private final Map<String, Integer> retainOnRefreshRoots = new HashMap<String, Integer>();
+    private final Map<String, Integer> retainOnRefreshUIs = new HashMap<String, Integer>();
 
     private final EventRouter eventRouter = new EventRouter();
 
@@ -500,12 +500,12 @@ public class Application implements Terminal.ErrorListener, Serializable {
      * Keeps track of which uIs have been inited.
      * <p>
      * TODO Investigate whether this might be derived from the different states
-     * in getRootForRrequest.
+     * in getUIForRrequest.
      * </p>
      */
-    private Set<Integer> initedRoots = new HashSet<Integer>();
+    private Set<Integer> initedUIs = new HashSet<Integer>();
 
-    private List<RootProvider> rootProviders = new LinkedList<RootProvider>();
+    private List<UIProvider> uiProviders = new LinkedList<UIProvider>();
 
     /**
      * Gets the user of the application.
@@ -1830,110 +1830,108 @@ public class Application implements Terminal.ErrorListener, Serializable {
     }
 
     /**
-     * Gets a root for a request for which no root is already known. This method
-     * is called when the framework processes a request that does not originate
-     * from an existing root instance. This typically happens when a host page
-     * is requested.
+     * Gets a UI for a request for which no UI is already known. This method is
+     * called when the framework processes a request that does not originate
+     * from an existing UI instance. This typically happens when a host page is
+     * requested.
      * 
      * <p>
      * Subclasses of Application may override this method to provide custom
-     * logic for choosing how to create a suitable root or for picking an
-     * already created root. If an existing root is picked, care should be taken
-     * to avoid keeping the same root open in multiple browser windows, as that
-     * will cause the states to go out of sync.
+     * logic for choosing how to create a suitable UI or for picking an already
+     * created UI. If an existing UI is picked, care should be taken to avoid
+     * keeping the same UI open in multiple browser windows, as that will cause
+     * the states to go out of sync.
      * </p>
      * 
      * <p>
-     * If {@link BrowserDetails} are required to create a UI, the
-     * implementation can throw a {@link UIRequiresMoreInformationException}
-     * exception. In this case, the framework will instruct the browser to send
-     * the additional details, whereupon this method is invoked again with the
-     * browser details present in the wrapped request. Throwing the exception if
-     * the browser details are already available is not supported.
+     * If {@link BrowserDetails} are required to create a UI, the implementation
+     * can throw a {@link UIRequiresMoreInformationException} exception. In this
+     * case, the framework will instruct the browser to send the additional
+     * details, whereupon this method is invoked again with the browser details
+     * present in the wrapped request. Throwing the exception if the browser
+     * details are already available is not supported.
      * </p>
      * 
      * <p>
      * The default implementation in {@link Application} creates a new instance
-     * of the UI class returned by {@link #getRootClassName(WrappedRequest)},
-     * which in turn uses the {@value #ROOT_PARAMETER} parameter from web.xml.
-     * If {@link DeploymentConfiguration#getClassLoader()} for the request
-     * returns a {@link ClassLoader}, it is used for loading the UI class.
-     * Otherwise the {@link ClassLoader} used to load this class is used.
+     * of the UI class returned by {@link #getUIClassName(WrappedRequest)},
+     * which in turn uses the {@value #UI_PARAMETER} parameter from web.xml. If
+     * {@link DeploymentConfiguration#getClassLoader()} for the request returns
+     * a {@link ClassLoader}, it is used for loading the UI class. Otherwise the
+     * {@link ClassLoader} used to load this class is used.
      * </p>
      * 
      * @param request
-     *            the wrapped request for which a root is needed
-     * @return a root instance to use for the request
+     *            the wrapped request for which a UI is needed
+     * @return a UI instance to use for the request
      * @throws UIRequiresMoreInformationException
      *             may be thrown by an implementation to indicate that
-     *             {@link BrowserDetails} are required to create a root
+     *             {@link BrowserDetails} are required to create a UI
      * 
-     * @see #getRootClassName(WrappedRequest)
+     * @see #getUIClassName(WrappedRequest)
      * @see UI
      * @see UIRequiresMoreInformationException
      * @see WrappedRequest#getBrowserDetails()
      * 
      * @since 7.0
      */
-    protected UI getRoot(WrappedRequest request)
+    protected UI getUI(WrappedRequest request)
             throws UIRequiresMoreInformationException {
 
         // Iterate in reverse order - test check newest provider first
-        for (int i = rootProviders.size() - 1; i >= 0; i--) {
-            RootProvider provider = rootProviders.get(i);
+        for (int i = uiProviders.size() - 1; i >= 0; i--) {
+            UIProvider provider = uiProviders.get(i);
 
-            Class<? extends UI> rootClass = provider.getRootClass(this,
-                    request);
+            Class<? extends UI> uiClass = provider.getUIClass(this, request);
 
-            if (rootClass != null) {
-                return provider.instantiateRoot(this, rootClass, request);
+            if (uiClass != null) {
+                return provider.instantiateUI(this, uiClass, request);
             }
         }
 
         throw new RuntimeException(
-                "No root providers available or providers are not able to find root instance");
+                "No UI providers available or providers are not able to find UI instance");
     }
 
     /**
-     * Finds the theme to use for a specific root. If no specific theme is
+     * Finds the theme to use for a specific UI. If no specific theme is
      * required, <code>null</code> is returned.
      * 
      * TODO Tell what the default implementation does once it does something.
      * 
      * @param uI
-     *            the root to get a theme for
+     *            the UI to get a theme for
      * @return the name of the theme, or <code>null</code> if the default theme
      *         should be used
      * 
      * @since 7.0
      */
-    public String getThemeForRoot(UI uI) {
-        Theme rootTheme = getAnnotationFor(uI.getClass(), Theme.class);
-        if (rootTheme != null) {
-            return rootTheme.value();
+    public String getThemeForUI(UI uI) {
+        Theme uiTheme = getAnnotationFor(uI.getClass(), Theme.class);
+        if (uiTheme != null) {
+            return uiTheme.value();
         } else {
             return null;
         }
     }
 
     /**
-     * Finds the widgetset to use for a specific root. If no specific widgetset
-     * is required, <code>null</code> is returned.
+     * Finds the widgetset to use for a specific UI. If no specific widgetset is
+     * required, <code>null</code> is returned.
      * 
      * TODO Tell what the default implementation does once it does something.
      * 
      * @param uI
-     *            the root to get a widgetset for
+     *            the UI to get a widgetset for
      * @return the name of the widgetset, or <code>null</code> if the default
      *         widgetset should be used
      * 
      * @since 7.0
      */
-    public String getWidgetsetForRoot(UI uI) {
-        Widgetset rootWidgetset = getAnnotationFor(uI.getClass(),
-                Widgetset.class);
-        if (rootWidgetset != null) {
-            return rootWidgetset.value();
+    public String getWidgetsetForUI(UI uI) {
+        Widgetset uiWidgetset = getAnnotationFor(uI.getClass(), Widgetset.class);
+        if (uiWidgetset != null) {
+            return uiWidgetset.value();
         } else {
             return null;
         }
@@ -2087,7 +2085,7 @@ public class Application implements Terminal.ErrorListener, Serializable {
      */
     private static final ThreadLocal<Application> currentApplication = new ThreadLocal<Application>();
 
-    private boolean rootPreserved = false;
+    private boolean uiPreserved = false;
 
     /**
      * Gets the currently used application. The current application is
@@ -2139,112 +2137,110 @@ public class Application implements Terminal.ErrorListener, Serializable {
         return configuration.isProductionMode();
     }
 
-    public void addRootProvider(RootProvider rootProvider) {
-        rootProviders.add(rootProvider);
+    public void addUIProvider(UIProvider uIProvider) {
+        uiProviders.add(uIProvider);
     }
 
-    public void removeRootProvider(RootProvider rootProvider) {
-        rootProviders.remove(rootProvider);
+    public void removeUIProvider(UIProvider uIProvider) {
+        uiProviders.remove(uIProvider);
     }
 
     /**
      * Finds the {@link UI} to which a particular request belongs. If the
-     * request originates from an existing UI, that root is returned. In other
-     * cases, the method attempts to create and initialize a new root and might
+     * request originates from an existing UI, that UI is returned. In other
+     * cases, the method attempts to create and initialize a new UI and might
      * throw a {@link UIRequiresMoreInformationException} if all required
      * information is not available.
      * <p>
      * Please note that this method can also return a newly created
      * <code>UI</code> which has not yet been initialized. You can use
-     * {@link #isRootInitPending(int)} with the root's id (
-     * {@link UI#getRootId()} to check whether the initialization is still
-     * pending.
+     * {@link #isUIInitPending(int)} with the UI's id ( {@link UI#getUIId()} to
+     * check whether the initialization is still pending.
      * </p>
      * 
      * @param request
-     *            the request for which a root is desired
-     * @return a root belonging to the request
+     *            the request for which a UI is desired
+     * @return a UI belonging to the request
      * @throws UIRequiresMoreInformationException
-     *             if no existing root could be found and creating a new root
+     *             if no existing UI could be found and creating a new UI
      *             requires additional information from the browser
      * 
-     * @see #getRoot(WrappedRequest)
+     * @see #getUI(WrappedRequest)
      * @see UIRequiresMoreInformationException
      * 
      * @since 7.0
      */
-    public UI getRootForRequest(WrappedRequest request)
+    public UI getUIForRequest(WrappedRequest request)
             throws UIRequiresMoreInformationException {
         UI uI = UI.getCurrent();
         if (uI != null) {
             return uI;
         }
-        Integer rootId = getRootId(request);
+        Integer uiId = getUIId(request);
 
         synchronized (this) {
             BrowserDetails browserDetails = request.getBrowserDetails();
             boolean hasBrowserDetails = browserDetails != null
                     && browserDetails.getUriFragment() != null;
 
-            uI = uIs.get(rootId);
+            uI = uIs.get(uiId);
 
-            if (uI == null && isRootPreserved()) {
-                // Check for a known root
-                if (!retainOnRefreshRoots.isEmpty()) {
+            if (uI == null && isUiPreserved()) {
+                // Check for a known UI
+                if (!retainOnRefreshUIs.isEmpty()) {
 
-                    Integer retainedRootId;
+                    Integer retainedUIId;
                     if (!hasBrowserDetails) {
                         throw new UIRequiresMoreInformationException();
                     } else {
                         String windowName = browserDetails.getWindowName();
-                        retainedRootId = retainOnRefreshRoots.get(windowName);
+                        retainedUIId = retainOnRefreshUIs.get(windowName);
                     }
 
-                    if (retainedRootId != null) {
-                        rootId = retainedRootId;
-                        uI = uIs.get(rootId);
+                    if (retainedUIId != null) {
+                        uiId = retainedUIId;
+                        uI = uIs.get(uiId);
                     }
                 }
             }
 
             if (uI == null) {
-                // Throws exception if root can not yet be created
-                uI = getRoot(request);
+                // Throws exception if UI can not yet be created
+                uI = getUI(request);
 
-                // Initialize some fields for a newly created root
+                // Initialize some fields for a newly created UI
                 if (uI.getApplication() == null) {
                     uI.setApplication(this);
                 }
-                if (uI.getRootId() < 0) {
+                if (uI.getUIId() < 0) {
 
-                    if (rootId == null) {
+                    if (uiId == null) {
                         // Get the next id if none defined
-                        rootId = Integer.valueOf(nextRootId++);
+                        uiId = Integer.valueOf(nextUIId++);
                     }
-                    uI.setRootId(rootId.intValue());
-                    uIs.put(rootId, uI);
+                    uI.setUIId(uiId.intValue());
+                    uIs.put(uiId, uI);
                 }
             }
 
             // Set thread local here so it is available in init
             UI.setCurrent(uI);
 
-            if (!initedRoots.contains(rootId)) {
-                boolean initRequiresBrowserDetails = isRootPreserved()
-                        || !uI.getClass()
-                                .isAnnotationPresent(EagerInit.class);
+            if (!initedUIs.contains(uiId)) {
+                boolean initRequiresBrowserDetails = isUiPreserved()
+                        || !uI.getClass().isAnnotationPresent(EagerInit.class);
                 if (!initRequiresBrowserDetails || hasBrowserDetails) {
                     uI.doInit(request);
 
-                    // Remember that this root has been initialized
-                    initedRoots.add(rootId);
+                    // Remember that this UI has been initialized
+                    initedUIs.add(uiId);
 
                     // init() might turn on preserve so do this afterwards
-                    if (isRootPreserved()) {
-                        // Remember this root
+                    if (isUiPreserved()) {
+                        // Remember this UI
                         String windowName = request.getBrowserDetails()
                                 .getWindowName();
-                        retainOnRefreshRoots.put(windowName, rootId);
+                        retainOnRefreshUIs.put(windowName, uiId);
                     }
                 }
             }
@@ -2254,25 +2250,24 @@ public class Application implements Terminal.ErrorListener, Serializable {
     }
 
     /**
-     * Internal helper to finds the root id for a request.
+     * Internal helper to finds the UI id for a request.
      * 
      * @param request
-     *            the request to get the root id for
-     * @return a root id, or <code>null</code> if no root id is defined
+     *            the request to get the UI id for
+     * @return a UI id, or <code>null</code> if no UI id is defined
      * 
      * @since 7.0
      */
-    private static Integer getRootId(WrappedRequest request) {
+    private static Integer getUIId(WrappedRequest request) {
         if (request instanceof CombinedRequest) {
-            // Combined requests has the rootid parameter in the second request
+            // Combined requests has the uiId parameter in the second request
             CombinedRequest combinedRequest = (CombinedRequest) request;
             request = combinedRequest.getSecondRequest();
         }
-        String rootIdString = request
+        String uiIdString = request
                 .getParameter(ApplicationConstants.ROOT_ID_PARAMETER);
-        Integer rootId = rootIdString == null ? null
-                : new Integer(rootIdString);
-        return rootId;
+        Integer uiId = uiIdString == null ? null : new Integer(uiIdString);
+        return uiId;
     }
 
     /**
@@ -2285,14 +2280,14 @@ public class Application implements Terminal.ErrorListener, Serializable {
      * the UI is already shown, as it might not be retained as intended.
      * </p>
      * 
-     * @param rootPreserved
-     *            <code>true</code>if the same UI instance should be reused
-     *            e.g. when the browser window is refreshed.
+     * @param uiPreserved
+     *            <code>true</code>if the same UI instance should be reused e.g.
+     *            when the browser window is refreshed.
      */
-    public void setRootPreserved(boolean rootPreserved) {
-        this.rootPreserved = rootPreserved;
-        if (!rootPreserved) {
-            retainOnRefreshRoots.clear();
+    public void setUiPreserved(boolean uiPreserved) {
+        this.uiPreserved = uiPreserved;
+        if (!uiPreserved) {
+            retainOnRefreshUIs.clear();
         }
     }
 
@@ -2305,41 +2300,41 @@ public class Application implements Terminal.ErrorListener, Serializable {
      * @return <code>true</code>if the same UI instance should be reused e.g.
      *         when the browser window is refreshed.
      */
-    public boolean isRootPreserved() {
-        return rootPreserved;
+    public boolean isUiPreserved() {
+        return uiPreserved;
     }
 
     /**
-     * Checks whether there's a pending initialization for the root with the
-     * given id.
+     * Checks whether there's a pending initialization for the UI with the given
+     * id.
      * 
-     * @param rootId
-     *            root id to check for
+     * @param uiId
+     *            UI id to check for
      * @return <code>true</code> of the initialization is pending,
-     *         <code>false</code> if the root id is not registered or if the
-     *         root has already been initialized
+     *         <code>false</code> if the UI id is not registered or if the UI
+     *         has already been initialized
      * 
-     * @see #getRootForRequest(WrappedRequest)
+     * @see #getUIForRequest(WrappedRequest)
      */
-    public boolean isRootInitPending(int rootId) {
-        return !initedRoots.contains(Integer.valueOf(rootId));
+    public boolean isUIInitPending(int uiId) {
+        return !initedUIs.contains(Integer.valueOf(uiId));
     }
 
     /**
-     * Gets all the uIs of this application. This includes uIs that have
-     * been requested but not yet initialized. Please note, that uIs are not
+     * Gets all the uIs of this application. This includes uIs that have been
+     * requested but not yet initialized. Please note, that uIs are not
      * automatically removed e.g. if the browser window is closed and that there
-     * is no way to manually remove a root. Inactive uIs will thus not be
-     * released for GC until the entire application is released when the session
-     * has timed out (unless there are dangling references). Improved support
-     * for releasing unused uIs is planned for an upcoming alpha release of
-     * Vaadin 7.
+     * is no way to manually remove a UI. Inactive uIs will thus not be released
+     * for GC until the entire application is released when the session has
+     * timed out (unless there are dangling references). Improved support for
+     * releasing unused uIs is planned for an upcoming alpha release of Vaadin
+     * 7.
      * 
      * @return a collection of uIs belonging to this application
      * 
      * @since 7.0
      */
-    public Collection<UI> getRoots() {
+    public Collection<UI> getUIs() {
         return Collections.unmodifiableCollection(uIs.values());
     }
 
@@ -2367,12 +2362,12 @@ public class Application implements Terminal.ErrorListener, Serializable {
      * This is meant for framework internal use.
      * </p>
      * 
-     * @param rootId
-     *            The root id
-     * @return The root with the given id or null if not found
+     * @param uiId
+     *            The UI id
+     * @return The UI with the given id or null if not found
      */
-    public UI getRootById(int rootId) {
-        return uIs.get(rootId);
+    public UI getUIById(int uiId) {
+        return uIs.get(uiId);
     }
 
     /**