From 3e81a786d17313bc300777b4b759f012d1c7e6c2 Mon Sep 17 00:00:00 2001 From: Matti Tahvonen Date: Thu, 17 Dec 2009 08:31:42 +0000 Subject: [PATCH] fixes #3859, documented why some of the methods are deprecated svn changeset:10369/svn branch:6.2 --- src/com/vaadin/Application.java | 249 ++++++++++++++++---------------- 1 file changed, 124 insertions(+), 125 deletions(-) diff --git a/src/com/vaadin/Application.java b/src/com/vaadin/Application.java index 5d10b215e4..67bc5e9da6 100644 --- a/src/com/vaadin/Application.java +++ b/src/com/vaadin/Application.java @@ -41,7 +41,7 @@ import com.vaadin.ui.Window; * and manipulation of the user, {@link com.vaadin.ui.Window windows} and * themes, and starting and stopping the application. *

- * + * *

* As mentioned, all Vaadin applications must inherit this class. However, this * is almost all of what one needs to do to create a fully functional @@ -55,23 +55,23 @@ import com.vaadin.ui.Window; * windows correspond to a URL gotten by catenating the window's name to the * application URL. *

- * + * *

* See the class com.vaadin.demo.HelloWorld for a simple example of * a fully working application. *

- * + * *

* Window access. Application provides methods to * list, add and remove the windows it contains. *

- * + * *

* Execution control. This class includes method to start and * finish the execution of the application. Being finished means basically that * no windows will be available from the application anymore. *

- * + * *

* Theme selection. The theme selection process allows a theme * to be specified at three different levels. When a window's theme needs to be @@ -81,7 +81,7 @@ import com.vaadin.ui.Window; * the {@link com.vaadin.terminal.Terminal terminal} is used. The terminal * always defines a default theme. *

- * + * * @author IT Mill Ltd. * @version * @VERSION@ @@ -188,20 +188,20 @@ public abstract class Application implements URIHandler, * Gets a window by name. Returns null if the application is * not running or it does not contain a window corresponding to the name. *

- * + * *

* All windows can be referenced by their names in url * http://host:port/foo/bar/ where * http://host:port/foo/ is the application url as returned by * getURL() and bar is the name of the window. *

- * + * *

* One should note that this method can, as a side effect create new windows * if needed by the application. This can be achieved by overriding the * default implementation. *

- * + * *

* If for some reason user opens another window with same url that is * already open, name is modified by adding "_12345678" postfix to the name, @@ -210,7 +210,7 @@ public abstract class Application implements URIHandler, * If the user has two browser windows pointing to the same window-object on * server, synchronization errors are likely to occur. *

- * + * *

* If no browser-level windowing is used, all defaults are fine and this * method can be left as is. In case browser-level windows are needed, it is @@ -233,16 +233,16 @@ public abstract class Application implements URIHandler, } return w; *

- * + * *

* Note that all returned Window objects must be added to * this application instance. - * + * *

* The method should return null if the window does not exists (and is not * created as a side-effect) or if the application is not running anymore. *

- * + * * @param name * the name of the window. * @return the window associated with the given URI or null @@ -262,12 +262,12 @@ public abstract class Application implements URIHandler, /** * Adds a new window to the application. - * + * *

* This implicitly invokes the * {@link com.vaadin.ui.Window#setApplication(Application)} method. *

- * + * *

* Note that all application-level windows can be accessed by their names in * url http://host:port/foo/bar/ where @@ -277,7 +277,7 @@ public abstract class Application implements URIHandler, * inside other windows - these windows show as smaller windows inside those * windows. *

- * + * * @param window * the new Window to add. If the name of the window * is null, an unique name is automatically given @@ -350,7 +350,7 @@ public abstract class Application implements URIHandler, /** * Send information to all listeners about new Windows associated with this * application. - * + * * @param window */ private void fireWindowAttachEvent(Window window) { @@ -366,18 +366,18 @@ 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. */ @@ -414,13 +414,13 @@ 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() { @@ -443,7 +443,7 @@ public abstract class Application implements URIHandler, * getter and setter methods for convenience. The user reference stored to * the application can be read with {@link #getUser()}. *

- * + * * @param user * the new user. */ @@ -467,7 +467,7 @@ 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 ( @@ -475,7 +475,7 @@ public abstract class Application implements URIHandler, * can also be shown by navigating to the window url ( * {@link com.vaadin.ui.Window#getURL()}). *

- * + * * @return the application's URL. */ public URL getURL() { @@ -484,7 +484,7 @@ public abstract class Application implements URIHandler, /** * 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 @@ -501,21 +501,21 @@ public abstract class Application implements URIHandler, /** * 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. * @param applicationProperties @@ -523,7 +523,7 @@ public abstract class Application implements URIHandler, * configuration. * @param context * the context application will be running in. - * + * */ public void start(URL applicationUrl, Properties applicationProperties, ApplicationContext context) { @@ -536,13 +536,13 @@ 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. */ @@ -552,11 +552,11 @@ 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() { @@ -578,7 +578,7 @@ public abstract class Application implements URIHandler, * theme used by all the windows in it that do not explicitly specify a * theme. If the application theme is not explicitly set, the * null is returned. - * + * * @return the name of the application's theme. */ public String getTheme() { @@ -593,7 +593,7 @@ public abstract class Application implements URIHandler, * to be null selects the default theme. For the available * theme names, see the contents of the VAADIN/themes directory. *

- * + * * @param theme * the new theme for this application. */ @@ -622,7 +622,7 @@ 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. @@ -630,7 +630,7 @@ public abstract class Application implements URIHandler, *

* Note that each application must have at least one main window. *

- * + * * @return the main window. */ public Window getMainWindow() { @@ -643,7 +643,7 @@ public abstract class Application implements URIHandler, * window defaults to first created window. Setting window as a main window * of this application also adds the window to this application. *

- * + * * @param mainWindow * the mainWindow to set. */ @@ -655,15 +655,15 @@ 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. - * + * */ public Enumeration getPropertyNames() { return properties.propertyNames(); @@ -672,10 +672,10 @@ public abstract class Application implements URIHandler, /** * Searches for the property with the specified name in this application. * This method returns null if the property is not found. - * + * * See {@link #start(URL, Properties, ApplicationContext)} how properties * are defined. - * + * * @param name * the name of the property. * @return the value in this property list with the specified key value. @@ -687,7 +687,7 @@ public abstract class Application implements URIHandler, /** * Adds new resource to the application. The resource can be accessed by the * user of the application. - * + * * @param resource * the resource to add. */ @@ -708,7 +708,7 @@ public abstract class Application implements URIHandler, /** * Removes the resource from the application. - * + * * @param resource * the resource to remove. */ @@ -721,21 +721,23 @@ public abstract class Application implements URIHandler, } /** - * Gets the relative uri of the resource. + * Gets the relative uri of the resource. This method is intended to be + * called only be the terminal implementation. * * This method can only be called from within the processing of a UIDL * request, not from a background thread. - * + * * @param resource * the resource to get relative location. * @return the relative uri of the resource or null if called in a * background thread + * + * @deprecated this method is intended to be used by the terminal only. It + * may be removed or moved in the future. */ @Deprecated public String getRelativeLocation(ApplicationResource resource) { - // FIXME Move to ApplicationContext? - // Gets the key final String key = resourceKeyMap.get(resource); @@ -749,34 +751,31 @@ 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)

+ * + * @deprecated this method is called be the terminal implementation only and + * might be removed or moved in the future. Instead of + * overriding this method, add your {@link URIHandler} to a top + * level {@link Window} (eg. + * getMainWindow().addUriHanler(handler) instead. */ @Deprecated public DownloadStream handleURI(URL context, String relativeUri) { - // FIXME Move to ApplicationContext? - public API, need to leave hook - // here - if (this.context.isApplicationResourceURL(context, relativeUri)) { // Handles the resource request - final String key = this.context.getURLKey(context, - relativeUri); - final ApplicationResource resource = keyResourceMap - .get(key); + final String key = this.context.getURLKey(context, relativeUri); + final ApplicationResource resource = keyResourceMap.get(key); if (resource != null) { DownloadStream stream = resource.getStream(); if (stream != null) { @@ -796,10 +795,10 @@ 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() { @@ -811,13 +810,13 @@ 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. - * + * */ public void setLocale(Locale locale) { this.locale = locale; @@ -829,7 +828,7 @@ public abstract class Application implements URIHandler, *

* Application user change event sent when the setUser is called to change * the current user of the application. - * + * * @version * @VERSION@ * @since 3.0 @@ -848,7 +847,7 @@ public abstract class Application implements URIHandler, /** * Constructor for user change event. - * + * * @param source * the application source. * @param newUser @@ -865,7 +864,7 @@ public abstract class Application implements URIHandler, /** * Gets the new user of the application. - * + * * @return the new User. */ public Object getNewUser() { @@ -874,7 +873,7 @@ public abstract class Application implements URIHandler, /** * Gets the previous user of the application. - * + * * @return the previous Vaadin user, if user has not changed ever on * application it returns null */ @@ -884,7 +883,7 @@ public abstract class Application implements URIHandler, /** * Gets the application where the user change occurred. - * + * * @return the Application. */ public Application getApplication() { @@ -895,7 +894,7 @@ public abstract class Application implements URIHandler, /** * The UserChangeListener interface for listening application * user changes. - * + * * @version * @VERSION@ * @since 3.0 @@ -905,7 +904,7 @@ public abstract class Application implements URIHandler, /** * The applicationUserChanged method Invoked when the * application user has changed. - * + * * @param event * the change event. */ @@ -914,10 +913,10 @@ 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. */ @@ -930,7 +929,7 @@ public abstract class Application implements URIHandler, /** * Removes the user change listener. - * + * * @param listener * the user change listener to remove. */ @@ -946,7 +945,7 @@ 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)}. */ @@ -956,7 +955,7 @@ public abstract class Application implements URIHandler, /** * Creates a event. - * + * * @param window * the Detached window. */ @@ -967,7 +966,7 @@ public abstract class Application implements URIHandler, /** * Gets the detached window. - * + * * @return the detached window. */ public Window getWindow() { @@ -976,7 +975,7 @@ public abstract class Application implements URIHandler, /** * Gets the application from which the window was detached. - * + * * @return the Application. */ public Application getApplication() { @@ -986,7 +985,7 @@ 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)}. */ @@ -996,7 +995,7 @@ public abstract class Application implements URIHandler, /** * Creates a event. - * + * * @param window * the Attached window. */ @@ -1007,7 +1006,7 @@ public abstract class Application implements URIHandler, /** * Gets the attached window. - * + * * @return the attached window. */ public Window getWindow() { @@ -1016,7 +1015,7 @@ public abstract class Application implements URIHandler, /** * Gets the application to which the window was attached. - * + * * @return the Application. */ public Application getApplication() { @@ -1031,7 +1030,7 @@ public abstract class Application implements URIHandler, /** * Window attached - * + * * @param event * the window attach event. */ @@ -1045,7 +1044,7 @@ public abstract class Application implements URIHandler, /** * Window detached. - * + * * @param event * the window detach event. */ @@ -1054,10 +1053,10 @@ 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. */ @@ -1070,10 +1069,10 @@ 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. */ @@ -1086,7 +1085,7 @@ public abstract class Application implements URIHandler, /** * Removes the window attach listener. - * + * * @param listener * the window attach listener to remove. */ @@ -1101,7 +1100,7 @@ public abstract class Application implements URIHandler, /** * Removes the window detach listener. - * + * * @param listener * the window detach listener to remove. */ @@ -1122,7 +1121,7 @@ public abstract class Application implements URIHandler, * Desktop application just closes the application window and * web-application redirects the browser to application main URL. *

- * + * * @return the URL. */ public String getLogoutURL() { @@ -1135,7 +1134,7 @@ public abstract class Application implements URIHandler, * application running environment: Desktop application just closes the * application window and web-application redirects the browser to * application main URL. - * + * * @param logoutURL * the logoutURL to set. */ @@ -1147,7 +1146,7 @@ public abstract class Application implements URIHandler, * Gets the SystemMessages for this application. SystemMessages are used to * 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}. To "override" this method, re-implement * this method in your application (the class that extends @@ -1155,7 +1154,7 @@ public abstract class Application implements URIHandler, * 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 */ public static SystemMessages getSystemMessages() { @@ -1174,7 +1173,7 @@ public abstract class Application implements URIHandler, * You can safely override this method in your application in order to * direct the errors to some other destination (for example log). *

- * + * * @param event * the change event. * @see com.vaadin.terminal.Terminal.ErrorListener#terminalError(com.vaadin.terminal.Terminal.ErrorEvent) @@ -1230,7 +1229,7 @@ public abstract class Application implements URIHandler, * you are deploying your application as a portlet, context implementation * is {@link PortletApplicationContext}. *

- * + * * @return the application context. */ public ApplicationContext getContext() { @@ -1241,7 +1240,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. By default this returns a string "NONVERSIONED". - * + * * @return version string */ public String getVersion() { @@ -1250,9 +1249,9 @@ public abstract class Application implements URIHandler, /** * Gets the application error handler. - * + * * The default error handler is the application itself. - * + * * @return Application error handler */ public Terminal.ErrorListener getErrorHandler() { @@ -1261,11 +1260,11 @@ public abstract class Application implements URIHandler, /** * Sets the application error handler. - * + * * 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 */ public void setErrorHandler(Terminal.ErrorListener errorHandler) { @@ -1306,7 +1305,7 @@ public abstract class Application implements URIHandler, * Take note of any unsaved data, and click here to re-sync." * *

- * + * */ public static class SystemMessages implements Serializable { protected String sessionExpiredURL = null; @@ -1360,7 +1359,7 @@ public abstract class Application implements URIHandler, } /** - * @return + * @return * "Take note of any unsaved data, and click here to continue." */ public String getSessionExpiredMessage() { @@ -1392,7 +1391,7 @@ public abstract class Application implements URIHandler, } /** - * @return + * @return * "Take note of any unsaved data, and click here to continue." */ public String getCommunicationErrorMessage() { @@ -1508,7 +1507,7 @@ public abstract class Application implements URIHandler, /** * Sets the URL to go to when the session has expired. - * + * * @param sessionExpiredURL * the URL to go to, or null to reload current */ @@ -1520,7 +1519,7 @@ public abstract class Application implements URIHandler, * Enables or disables the notification. If disabled, the set URL (or * current) is loaded directly when next transaction between server and * client happens. - * + * * @param sessionExpiredNotificationEnabled * true = enabled, false = disabled */ @@ -1534,7 +1533,7 @@ public abstract class Application implements URIHandler, * both caption and message are null, client automatically forwards to * sessionExpiredUrl after timeout timer expires. Timer uses value read * from HTTPSession.getMaxInactiveInterval() - * + * * @param sessionExpiredCaption * the caption */ @@ -1547,7 +1546,7 @@ public abstract class Application implements URIHandler, * both caption and message are null, client automatically forwards to * sessionExpiredUrl after timeout timer expires. Timer uses value read * from HTTPSession.getMaxInactiveInterval() - * + * * @param sessionExpiredMessage * the message */ @@ -1557,7 +1556,7 @@ public abstract class Application implements URIHandler, /** * Sets the URL to go to when there is a communication error. - * + * * @param communicationErrorURL * the URL to go to, or null to reload current */ @@ -1568,7 +1567,7 @@ public abstract class Application implements URIHandler, /** * Enables or disables the notification. If disabled, the set URL (or * current) is loaded directly. - * + * * @param communicationErrorNotificationEnabled * true = enabled, false = disabled */ @@ -1580,7 +1579,7 @@ public abstract class Application implements URIHandler, /** * Sets the caption of the notification. Set to null for no caption. If * both caption and message is null, the notification is disabled; - * + * * @param communicationErrorCaption * the caption */ @@ -1592,7 +1591,7 @@ public abstract class Application implements URIHandler, /** * Sets the message of the notification. Set to null for no message. If * both caption and message is null, the notification is disabled; - * + * * @param communicationErrorMessage * the message */ @@ -1603,7 +1602,7 @@ public abstract class Application implements URIHandler, /** * Sets the URL to go to when an internal error occurs. - * + * * @param internalErrorURL * the URL to go to, or null to reload current */ @@ -1614,7 +1613,7 @@ public abstract class Application implements URIHandler, /** * Enables or disables the notification. If disabled, the set URL (or * current) is loaded directly. - * + * * @param internalErrorNotificationEnabled * true = enabled, false = disabled */ @@ -1626,7 +1625,7 @@ public abstract class Application implements URIHandler, /** * Sets the caption of the notification. Set to null for no caption. If * both caption and message is null, the notification is disabled; - * + * * @param internalErrorCaption * the caption */ @@ -1637,7 +1636,7 @@ public abstract class Application implements URIHandler, /** * Sets the message of the notification. Set to null for no message. If * both caption and message is null, the notification is disabled; - * + * * @param internalErrorMessage * the message */ @@ -1647,7 +1646,7 @@ public abstract class Application implements URIHandler, /** * Sets the URL to go to when the client is out-of-sync. - * + * * @param outOfSyncURL * the URL to go to, or null to reload current */ @@ -1658,7 +1657,7 @@ public abstract class Application implements URIHandler, /** * Enables or disables the notification. If disabled, the set URL (or * current) is loaded directly. - * + * * @param outOfSyncNotificationEnabled * true = enabled, false = disabled */ @@ -1670,7 +1669,7 @@ public abstract class Application implements URIHandler, /** * Sets the caption of the notification. Set to null for no caption. If * both caption and message is null, the notification is disabled; - * + * * @param outOfSyncCaption * the caption */ @@ -1681,7 +1680,7 @@ public abstract class Application implements URIHandler, /** * Sets the message of the notification. Set to null for no message. If * both caption and message is null, the notification is disabled; - * + * * @param outOfSyncMessage * the message */ @@ -1693,7 +1692,7 @@ 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. -- 2.39.5