From: Joonas Lehtinen
+ * Removing the main window of the Application also sets the main window to
+ * null. One must another window to be the main window after this with
+ * {@link #setMainWindow(Window)}.
+ *
+ * Note that removing window from the application does not close the browser
+ * window - the window is only removed from the server-side.
+ *
+ * Vaadin doesn't define of use user object in any way - it only provides
+ * this getter and setter methods for convenience. The user is any object
+ * that has been stored to the application with {@link #setUser(Object)}.
+ *
+ * Vaadin doesn't define of use user object in any way - it only provides + * getter and setter methods for convenience. The user reference stored to + * the application can be read with {@link #getUser()}. + *
* * @param user * the new user. @@ -444,6 +468,14 @@ public abstract class Application implements URIHandler, /** * Gets the URL of the application. * + *+ * This is the URL what can be entered to a browser window to start the + * application. Navigating to the application URL shows the main window ( + * {@link #getMainWindow()}) of the application. Note that the main window + * can also be shown by navigating to the window url ( + * {@link com.vaadin.ui.Window#getURL()}). + *
+ * * @return the application's URL. */ public URL getURL() { @@ -451,22 +483,38 @@ public abstract class Application implements URIHandler, } /** - * Ends the Application. In effect this will cause the application stop - * returning any windows when asked. + * Ends the Application. + * + *+ * In effect this will cause the application stop returning any windows when + * asked. When the application is closed, its state is removed from the + * session and the browser window is redirected to the application logout + * url set with {@link #setLogoutURL(String)}. If the logout url has not + * been set, the browser window is reloaded and the application is + * restarted. + *
+ * . */ public void close() { applicationIsRunning = false; } /** - * Starts the application on the given URL.After this call the application - * corresponds to the given URL and it will return windows when asked for - * them. + * Starts the application on the given URL. * + *+ * This method is called by Vaadin framework when a user navigates to the + * application. After this call the application corresponds to the given URL + * and it will return windows when asked for them. There is no need to call + * this method directly. + *
+ * + ** Application properties are defined by servlet configuration object * {@link javax.servlet.ServletConfig} and they are overridden by * context-wide initialization parameters * {@link javax.servlet.ServletContext}. + *
* * @param applicationUrl * the URL the application should respond to. @@ -489,6 +537,12 @@ public abstract class Application implements URIHandler, /** * Tests if the application is running or if it has been finished. * + *+ * Application starts running when its + * {@link #start(URL, Properties, ApplicationContext)} method has been + * called and stops when the {@link #close()} is called. + *
+ * * @returntrue
if the application is running,
* false
if not.
*/
@@ -499,6 +553,10 @@ public abstract class Application implements URIHandler,
/**
* Gets the set of windows contained by the application.
*
+ * + * Note that the returned set of windows can not be modified. + *
+ * * @return the Unmodifiable collection of windows. */ public Collection getWindows() { @@ -530,8 +588,10 @@ public abstract class Application implements URIHandler, /** * Sets the application's theme. *
- * Note that this theme can be overridden by the windows. null
- * implies the default terminal theme.
+ * Note that this theme can be overridden in the the application level
+ * windows with {@link com.vaadin.ui.Window#setTheme(String)}. Setting theme
+ * to be null
selects the default theme. For the available
+ * theme names, see the contents of the VAADIN/themes directory.
*
+ * The main window is the window attached to the application URL ( + * {@link #getURL()}) and thus which is show by default to the user. + *
+ *+ * Note that each application must have at least one main window. + *
+ * * @return the main window. */ public Window getMainWindow() { @@ -588,8 +656,10 @@ public abstract class Application implements URIHandler, /** * Returns an enumeration of all the names in this application. * + ** See {@link #start(URL, Properties, ApplicationContext)} how properties * are defined. + *
* * @return an enumeration of all the keys in this property list, including * the keys in the default property list. @@ -676,13 +746,21 @@ public abstract class Application implements URIHandler, } /** + * Application URI handling hub. + * + ** This method gets called by terminal. It has lots of duties like to pass * uri handler to proper uri handlers registered to windows etc. + *
* + ** In most situations developers should NOT OVERRIDE this method. Instead * developers should implement and register uri handlers to windows. + *
* - * @see com.vaadin.terminal.URIHandler#handleURI(URL, String) + *+ * + * @see com.vaadin.terminal.URIHandler#handleURI(URL, String)
*/ public DownloadStream handleURI(URL context, String relativeUri) { @@ -729,6 +807,9 @@ public abstract class Application implements URIHandler, /** * Gets the default locale for this application. * + * By default this is the preferred locale of the user using the + * application. In most cases it is read from the browser defaults. + * * @return the locale of this application. */ public Locale getLocale() { @@ -741,6 +822,9 @@ public abstract class Application implements URIHandler, /** * Sets the default locale for this application. * + * By default this is the preferred locale of the user using the + * application. In most cases it is read from the browser defaults. + * * @param locale * the Locale object. * @@ -841,6 +925,9 @@ public abstract class Application implements URIHandler, /** * Adds the user change listener. * + * This allows one to get notification each time {@link #setUser(Object)} is + * called. + * * @param listener * the user change listener to add. */ @@ -869,6 +956,9 @@ public abstract class Application implements URIHandler, /** * Window detach event. + * + * This event is sent each time a window is removed from the application + * with {@link com.vaadin.Application#removeWindow(Window)}. */ public class WindowDetachEvent extends EventObject { @@ -906,6 +996,9 @@ public abstract class Application implements URIHandler, /** * Window attach event. + * + * This event is sent each time a window is attached tothe application with + * {@link com.vaadin.Application#addWindow(Window)}. */ public class WindowAttachEvent extends EventObject { @@ -972,6 +1065,9 @@ public abstract class Application implements URIHandler, /** * Adds the window attach listener. * + * Use this to get notifications each time a window is attached to the + * application with {@link #addWindow(Window)}. + * * @param listener * the window attach listener to add. */ @@ -985,6 +1081,9 @@ public abstract class Application implements URIHandler, /** * Adds the window detach listener. * + * Use this to get notifications each time a window is remove from the + * application with {@link #removeWindow(Window)}. + * * @param listener * the window detach listener to add. */ @@ -1059,8 +1158,13 @@ public abstract class Application implements URIHandler, * notify the user of various critical situations that can occur, such as * session expiration, client/server out of sync, and internal server error. * - * You can customize the messages by overriding this method and returning - * {@link CustomizedSystemMessages} + * You can customize the messages by "overriding" this method and returning + * {@link CustomizedSystemMessages}. To "override" this method, re-implement + * this method in your application (the class that extends + * {@link Application}). Even though overriding static methods is not + * possible in Java, Vaadin selects to call the static method from the + * subclass instead of the original {@link #getSystemMessages()} if such a + * method exists. * * @return the SystemMessages for this application */ @@ -1125,7 +1229,16 @@ public abstract class Application implements URIHandler, * Gets the application context. ** The application context is the environment where the application is - * running in. + * running in. The actual implementation class of may contains quite a lot + * more functionality than defined in the {@link ApplicationContext} + * interface. + *
+ *+ * By default, when you are deploying your application to a servlet + * container, the implementation class is {@link WebApplicationContext} - + * you can safely cast to this class and use the methods from there. When + * you are deploying your application as a portlet, context implementation + * is {@link PortletApplicationContext}. *
* * @return the application context. @@ -1137,7 +1250,7 @@ public abstract class Application implements URIHandler, /** * Override this method to return correct version number of your * Application. Version information is delivered for example to Testing - * Tools test results. + * Tools test results. By default this returns a string "NONVERSIONED". * * @return version string */ @@ -1159,7 +1272,9 @@ public abstract class Application implements URIHandler, /** * Sets the application error handler. * - * The default error handler is the application itself. + * The default error handler is the application itself. By overriding this, + * you can redirect the error messages to your selected target (log for + * example). * * @param errorHandler */ @@ -1171,15 +1286,42 @@ public abstract class Application implements URIHandler, * Contains the system messages used to notify the user about various * critical situations that can occur. *- * Customize by overriding the static Application.getSystemMessages() and - * returning {@link CustomizedSystemMessages} + * Customize by overriding the static + * {@link Application#getSystemMessages()} and returning + * {@link CustomizedSystemMessages}. + *
+ *+ * The defaults defined in this class are: + *