From: Matti Tahvonen
* 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. Returnsnull
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 ornull
@@ -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.
*
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. *
- * + * * @returntrue
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 Collectionnull
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 returnsnull
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 returnsnull
*/
@@ -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.