From 2d1dc9fbdb9189765f35ea9925bf474fe925f578 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Petter=20Holmstr=C3=B6m?= Date: Tue, 17 Nov 2009 11:20:34 +0000 Subject: [PATCH] Merge with 6.2 svn changeset:9834/svn branch:portlet_2.0 --- src/com/vaadin/Application.java | 224 +++++++++++++++++++++++++++----- 1 file changed, 191 insertions(+), 33 deletions(-) diff --git a/src/com/vaadin/Application.java b/src/com/vaadin/Application.java index 4dcab2f36d..b0872fff7c 100644 --- a/src/com/vaadin/Application.java +++ b/src/com/vaadin/Application.java @@ -29,6 +29,8 @@ import com.vaadin.terminal.Terminal; import com.vaadin.terminal.URIHandler; import com.vaadin.terminal.VariableOwner; import com.vaadin.terminal.gwt.server.ChangeVariablesErrorEvent; +import com.vaadin.terminal.gwt.server.PortletApplicationContext; +import com.vaadin.terminal.gwt.server.WebApplicationContext; import com.vaadin.ui.AbstractComponent; import com.vaadin.ui.Window; @@ -455,6 +457,17 @@ public abstract class Application implements URIHandler, /** * Removes the specified window from the application. * + *

+ * 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. + *

+ * * @param window * the window to be removed. */ @@ -492,6 +505,12 @@ public abstract class Application implements URIHandler, /** * Gets the user of the application. * + *

+ * 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)}. + *

+ * * @return the User of the application. */ public Object getUser() { @@ -509,6 +528,11 @@ public abstract class Application implements URIHandler, * property of the application and make the user object available to other * components of the application. *

+ *

+ * 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. @@ -534,6 +558,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() { @@ -541,22 +573,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. @@ -579,6 +627,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. + *

+ * * @return true if the application is running, * false if not. */ @@ -589,6 +643,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() { @@ -620,8 +678,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. *

* * @param theme @@ -653,6 +713,14 @@ public abstract class Application implements URIHandler, /** * Gets the mainWindow of the application. * + *

+ * 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() { @@ -678,8 +746,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. @@ -764,13 +834,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)

*/ @Deprecated public DownloadStream handleURI(URL context, String relativeUri) { @@ -804,6 +882,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() { @@ -816,6 +897,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. * @@ -916,6 +1000,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. */ @@ -944,6 +1031,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 { @@ -981,6 +1071,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 { @@ -1047,6 +1140,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. */ @@ -1060,6 +1156,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. */ @@ -1134,8 +1233,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 */ @@ -1200,7 +1304,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. @@ -1212,7 +1325,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 */ @@ -1234,7 +1347,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 */ @@ -1246,15 +1361,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: + *

*

* */ public static class SystemMessages implements Serializable { protected String sessionExpiredURL = null; protected boolean sessionExpiredNotificationEnabled = true; - protected String sessionExpiredCaption = "Session Expired"; + protected String sessionExpiredCaption = ""; protected String sessionExpiredMessage = "Take note of any unsaved data, and click here to continue."; protected String communicationErrorURL = null; @@ -1264,7 +1406,7 @@ public abstract class Application implements URIHandler, protected String internalErrorURL = null; protected boolean internalErrorNotificationEnabled = true; - protected String internalErrorCaption = "Internal Error"; + protected String internalErrorCaption = "Internal error"; protected String internalErrorMessage = "Please notify the administrator.
Take note of any unsaved data, and click here to continue."; protected String outOfSyncURL = null; @@ -1280,21 +1422,22 @@ public abstract class Application implements URIHandler, } /** - * @return the URL to load on null for restart + * @return null to indicate that the application will be restarted after + * session expired message has been shown. */ public String getSessionExpiredURL() { return sessionExpiredURL; } /** - * @return true = notification enabled, false = notification disabled + * @return true to show session expiration message. */ public boolean isSessionExpiredNotificationEnabled() { return sessionExpiredNotificationEnabled; } /** - * @return the notification caption, or null for no caption + * @return "" to show no caption. */ public String getSessionExpiredCaption() { return (sessionExpiredNotificationEnabled ? sessionExpiredCaption @@ -1302,7 +1445,8 @@ public abstract class Application implements URIHandler, } /** - * @return the notification message, or null for no message + * @return + * "Take note of any unsaved data, and click here to continue." */ public String getSessionExpiredMessage() { return (sessionExpiredNotificationEnabled ? sessionExpiredMessage @@ -1310,21 +1454,22 @@ public abstract class Application implements URIHandler, } /** - * @return the URL to load on null for restart + * @return null to reload the application after communication error + * message. */ public String getCommunicationErrorURL() { return communicationErrorURL; } /** - * @return true = notification enabled, false = notification disabled + * @return true to show the communication error message. */ public boolean isCommunicationErrorNotificationEnabled() { return communicationErrorNotificationEnabled; } /** - * @return the notification caption, or null for no caption + * @return "Communication problem" */ public String getCommunicationErrorCaption() { return (communicationErrorNotificationEnabled ? communicationErrorCaption @@ -1332,7 +1477,8 @@ public abstract class Application implements URIHandler, } /** - * @return the notification message, or null for no message + * @return + * "Take note of any unsaved data, and click here to continue." */ public String getCommunicationErrorMessage() { return (communicationErrorNotificationEnabled ? communicationErrorMessage @@ -1340,21 +1486,22 @@ public abstract class Application implements URIHandler, } /** - * @return the URL to load on null for restart + * @return null to reload the current URL after internal error message + * has been shown. */ public String getInternalErrorURL() { return internalErrorURL; } /** - * @return true = notification enabled, false = notification disabled + * @return true to enable showing of internal error message. */ public boolean isInternalErrorNotificationEnabled() { return internalErrorNotificationEnabled; } /** - * @return the notification caption, or null for no caption + * @return "Internal error" */ public String getInternalErrorCaption() { return (internalErrorNotificationEnabled ? internalErrorCaption @@ -1362,7 +1509,9 @@ public abstract class Application implements URIHandler, } /** - * @return the notification message, or null for no message + * @return "Please notify the administrator.
+ * Take note of any unsaved data, and click here to + * continue." */ public String getInternalErrorMessage() { return (internalErrorNotificationEnabled ? internalErrorMessage @@ -1370,28 +1519,30 @@ public abstract class Application implements URIHandler, } /** - * @return the URL to load on null for restart + * @return null to reload the application after out of sync message. */ public String getOutOfSyncURL() { return outOfSyncURL; } /** - * @return true = notification enabled, false = notification disabled + * @return true to enable showing out of sync message */ public boolean isOutOfSyncNotificationEnabled() { return outOfSyncNotificationEnabled; } /** - * @return the notification caption, or null for no caption + * @return "Out of sync" */ public String getOutOfSyncCaption() { return (outOfSyncNotificationEnabled ? outOfSyncCaption : null); } /** - * @return the notification message, or null for no message + * @return "Something has caused us to be out of sync with the server.
+ * Take note of any unsaved data, and click here to + * re-sync." */ public String getOutOfSyncMessage() { return (outOfSyncNotificationEnabled ? outOfSyncMessage : null); @@ -1625,6 +1776,13 @@ public abstract class Application implements URIHandler, } + /** + * Application error is an error message defined on the application level. + * + * When an error occurs on the application level, this error message type + * should be used. This indicates that the problem is caused by the + * application - not by the user. + */ public class ApplicationError implements Terminal.ErrorEvent { private final Throwable throwable; -- 2.39.5