* and manipulation of the user, {@link com.vaadin.ui.Window windows} and
* themes, and starting and stopping the application.
* </p>
- *
+ *
* <p>
* 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
* windows correspond to a URL gotten by catenating the window's name to the
* application URL.
* </p>
- *
+ *
* <p>
* See the class <code>com.vaadin.demo.HelloWorld</code> for a simple example of
* a fully working application.
* </p>
- *
+ *
* <p>
* <strong>Window access.</strong> <code>Application</code> provides methods to
* list, add and remove the windows it contains.
* </p>
- *
+ *
* <p>
* <strong>Execution control.</strong> 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.
* </p>
- *
+ *
* <p>
* <strong>Theme selection.</strong> The theme selection process allows a theme
* to be specified at three different levels. When a window's theme needs to be
* the {@link com.vaadin.terminal.Terminal terminal} is used. The terminal
* always defines a default theme.
* </p>
- *
+ *
* @author IT Mill Ltd.
* @version
* @VERSION@
* Gets a window by name. Returns <code>null</code> if the application is
* not running or it does not contain a window corresponding to the name.
* </p>
- *
+ *
* <p>
* All windows can be referenced by their names in url
* <code>http://host:port/foo/bar/</code> where
* <code>http://host:port/foo/</code> is the application url as returned by
* getURL() and <code>bar</code> is the name of the window.
* </p>
- *
+ *
* <p>
* 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.
* </p>
- *
+ *
* <p>
* 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,
* If the user has two browser windows pointing to the same window-object on
* server, synchronization errors are likely to occur.
* </p>
- *
+ *
* <p>
* 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
}
return w;</pre></code>
* </p>
- *
+ *
* <p>
* <strong>Note</strong> that all returned Window objects must be added to
* this application instance.
- *
+ *
* <p>
* 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.
* </p>
- *
+ *
* @param name
* the name of the window.
* @return the window associated with the given URI or <code>null</code>
/**
* Adds a new window to the application.
- *
+ *
* <p>
* This implicitly invokes the
* {@link com.vaadin.ui.Window#setApplication(Application)} method.
* </p>
- *
+ *
* <p>
* Note that all application-level windows can be accessed by their names in
* url <code>http://host:port/foo/bar/</code> where
* inside other windows - these windows show as smaller windows inside those
* windows.
* </p>
- *
+ *
* @param window
* the new <code>Window</code> to add. If the name of the window
* is <code>null</code>, an unique name is automatically given
/**
* Send information to all listeners about new Windows associated with this
* application.
- *
+ *
* @param window
*/
private void fireWindowAttachEvent(Window window) {
/**
* Removes the specified window from the application.
- *
+ *
* <p>
* 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)}.
* </p>
- *
+ *
* <p>
* Note that removing window from the application does not close the browser
* window - the window is only removed from the server-side.
* </p>
- *
+ *
* @param window
* the window to be removed.
*/
/**
* Gets the user of the application.
- *
+ *
* <p>
* 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)}.
* </p>
- *
+ *
* @return the User of the application.
*/
public Object getUser() {
* getter and setter methods for convenience. The user reference stored to
* the application can be read with {@link #getUser()}.
* </p>
- *
+ *
* @param user
* the new user.
*/
/**
* Gets the URL of the application.
- *
+ *
* <p>
* 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 (
* can also be shown by navigating to the window url (
* {@link com.vaadin.ui.Window#getURL()}).
* </p>
- *
+ *
* @return the application's URL.
*/
public URL getURL() {
/**
* Ends the Application.
- *
+ *
* <p>
* In effect this will cause the application stop returning any windows when
* asked. When the application is closed, its state is removed from the
/**
* Starts the application on the given URL.
- *
+ *
* <p>
* 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.
* </p>
- *
+ *
* <p>
* 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}.
* </p>
- *
+ *
* @param applicationUrl
* the URL the application should respond to.
* @param applicationProperties
* configuration.
* @param context
* the context application will be running in.
- *
+ *
*/
public void start(URL applicationUrl, Properties applicationProperties,
ApplicationContext context) {
/**
* Tests if the application is running or if it has been finished.
- *
+ *
* <p>
* Application starts running when its
* {@link #start(URL, Properties, ApplicationContext)} method has been
* called and stops when the {@link #close()} is called.
* </p>
- *
+ *
* @return <code>true</code> if the application is running,
* <code>false</code> if not.
*/
/**
* Gets the set of windows contained by the application.
- *
+ *
* <p>
* Note that the returned set of windows can not be modified.
* </p>
- *
+ *
* @return the Unmodifiable collection of windows.
*/
public Collection<Window> getWindows() {
* theme used by all the windows in it that do not explicitly specify a
* theme. If the application theme is not explicitly set, the
* <code>null</code> is returned.
- *
+ *
* @return the name of the application's theme.
*/
public String getTheme() {
* to be <code>null</code> selects the default theme. For the available
* theme names, see the contents of the VAADIN/themes directory.
* </p>
- *
+ *
* @param theme
* the new theme for this application.
*/
/**
* Gets the mainWindow of the application.
- *
+ *
* <p>
* The main window is the window attached to the application URL (
* {@link #getURL()}) and thus which is show by default to the user.
* <p>
* Note that each application must have at least one main window.
* </p>
- *
+ *
* @return the main window.
*/
public Window getMainWindow() {
* window defaults to first created window. Setting window as a main window
* of this application also adds the window to this application.
* </p>
- *
+ *
* @param mainWindow
* the mainWindow to set.
*/
/**
* Returns an enumeration of all the names in this application.
- *
+ *
* <p>
* See {@link #start(URL, Properties, ApplicationContext)} how properties
* are defined.
* </p>
- *
+ *
* @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();
/**
* Searches for the property with the specified name in this application.
* This method returns <code>null</code> 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.
/**
* Adds new resource to the application. The resource can be accessed by the
* user of the application.
- *
+ *
* @param resource
* the resource to add.
*/
/**
* Removes the resource from the application.
- *
+ *
* @param resource
* the resource to remove.
*/
}
/**
- * 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);
/**
* Application URI handling hub.
- *
+ *
* <p>
* This method gets called by terminal. It has lots of duties like to pass
* uri handler to proper uri handlers registered to windows etc.
* </p>
- *
+ *
* <p>
* In most situations developers should NOT OVERRIDE this method. Instead
* developers should implement and register uri handlers to windows.
* </p>
- *
- * <p>
- *
- * @see com.vaadin.terminal.URIHandler#handleURI(URL, String) </p>
+ *
+ * @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) {
/**
* 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() {
/**
* 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;
* </p>
* Application user change event sent when the setUser is called to change
* the current user of the application.
- *
+ *
* @version
* @VERSION@
* @since 3.0
/**
* Constructor for user change event.
- *
+ *
* @param source
* the application source.
* @param newUser
/**
* Gets the new user of the application.
- *
+ *
* @return the new User.
*/
public Object getNewUser() {
/**
* Gets the previous user of the application.
- *
+ *
* @return the previous Vaadin user, if user has not changed ever on
* application it returns <code>null</code>
*/
/**
* Gets the application where the user change occurred.
- *
+ *
* @return the Application.
*/
public Application getApplication() {
/**
* The <code>UserChangeListener</code> interface for listening application
* user changes.
- *
+ *
* @version
* @VERSION@
* @since 3.0
/**
* The <code>applicationUserChanged</code> method Invoked when the
* application user has changed.
- *
+ *
* @param event
* the change event.
*/
/**
* 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.
*/
/**
* Removes the user change listener.
- *
+ *
* @param listener
* the user change listener to remove.
*/
/**
* Window detach event.
- *
+ *
* This event is sent each time a window is removed from the application
* with {@link com.vaadin.Application#removeWindow(Window)}.
*/
/**
* Creates a event.
- *
+ *
* @param window
* the Detached window.
*/
/**
* Gets the detached window.
- *
+ *
* @return the detached window.
*/
public Window getWindow() {
/**
* Gets the application from which the window was detached.
- *
+ *
* @return the Application.
*/
public Application getApplication() {
/**
* Window attach event.
- *
+ *
* This event is sent each time a window is attached tothe application with
* {@link com.vaadin.Application#addWindow(Window)}.
*/
/**
* Creates a event.
- *
+ *
* @param window
* the Attached window.
*/
/**
* Gets the attached window.
- *
+ *
* @return the attached window.
*/
public Window getWindow() {
/**
* Gets the application to which the window was attached.
- *
+ *
* @return the Application.
*/
public Application getApplication() {
/**
* Window attached
- *
+ *
* @param event
* the window attach event.
*/
/**
* Window detached.
- *
+ *
* @param event
* the window detach event.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* Removes the window attach listener.
- *
+ *
* @param listener
* the window attach listener to remove.
*/
/**
* Removes the window detach listener.
- *
+ *
* @param listener
* the window detach listener to remove.
*/
* Desktop application just closes the application window and
* web-application redirects the browser to application main URL.
* </p>
- *
+ *
* @return the URL.
*/
public String getLogoutURL() {
* 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.
*/
* 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
* 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() {
* You can safely override this method in your application in order to
* direct the errors to some other destination (for example log).
* </p>
- *
+ *
* @param event
* the change event.
* @see com.vaadin.terminal.Terminal.ErrorListener#terminalError(com.vaadin.terminal.Terminal.ErrorEvent)
* you are deploying your application as a portlet, context implementation
* is {@link PortletApplicationContext}.
* </p>
- *
+ *
* @return the application context.
*/
public ApplicationContext getContext() {
* 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() {
/**
* Gets the application error handler.
- *
+ *
* The default error handler is the application itself.
- *
+ *
* @return Application error handler
*/
public Terminal.ErrorListener getErrorHandler() {
/**
* 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) {
* Take note of any unsaved data, and <u>click here</u> to re-sync."</li>
* </ul>
* </p>
- *
+ *
*/
public static class SystemMessages implements Serializable {
protected String sessionExpiredURL = null;
}
/**
- * @return
+ * @return
* "Take note of any unsaved data, and <u>click here</u> to continue."
*/
public String getSessionExpiredMessage() {
}
/**
- * @return
+ * @return
* "Take note of any unsaved data, and <u>click here</u> to continue."
*/
public String getCommunicationErrorMessage() {
/**
* Sets the URL to go to when the session has expired.
- *
+ *
* @param sessionExpiredURL
* the URL to go to, or null to reload current
*/
* 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
*/
* 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
*/
* 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
*/
/**
* Sets the URL to go to when there is a communication error.
- *
+ *
* @param communicationErrorURL
* the URL to go to, or null to reload current
*/
/**
* Enables or disables the notification. If disabled, the set URL (or
* current) is loaded directly.
- *
+ *
* @param communicationErrorNotificationEnabled
* true = enabled, false = disabled
*/
/**
* 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
*/
/**
* 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
*/
/**
* Sets the URL to go to when an internal error occurs.
- *
+ *
* @param internalErrorURL
* the URL to go to, or null to reload current
*/
/**
* Enables or disables the notification. If disabled, the set URL (or
* current) is loaded directly.
- *
+ *
* @param internalErrorNotificationEnabled
* true = enabled, false = disabled
*/
/**
* 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
*/
/**
* 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
*/
/**
* 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
*/
/**
* Enables or disables the notification. If disabled, the set URL (or
* current) is loaded directly.
- *
+ *
* @param outOfSyncNotificationEnabled
* true = enabled, false = disabled
*/
/**
* 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
*/
/**
* 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
*/
/**
* 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.
projects / vaadin-framework.git / commitdiff