com.vaadin
Class Application

java.lang.Object
  com.vaadin.Application

All Implemented Interfaces:

Terminal.ErrorListener, Serializable

Direct Known Subclasses:

Application.LegacyApplication

public class Application
extends Object
implements Terminal.ErrorListener, Serializable

Base class required for all Vaadin applications. This class provides all the basic services required by Vaadin. These services allow external discovery and manipulation of the user, 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 application. The only thing a class inheriting the Application needs to do is implement the init method where it creates the windows it needs to perform its function. Note that all applications must have at least one window: the main window. The first unnamed window constructed by an application automatically becomes the main window which behaves just like other windows with one exception: when accessing windows using URLs the main window corresponds to the application URL whereas other 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 found out, the window itself is queried for a preferred theme. If the window does not prefer a specific theme, the application containing the window is queried. If neither the application prefers a theme, the default theme for the terminal is used. The terminal always defines a default theme.

Since:

3.0

Version:

7.0.0.alpha3

Author:

Vaadin Ltd.

See Also:

Serialized Form

Nested Class Summary

class	Application.ApplicationError Application error is an error message defined on the application level.
static class	Application.ApplicationStartEvent An event sent to start(ApplicationStartEvent) when a new Application is being started.
static class	Application.CustomizedSystemMessages Contains the system messages used to notify the user about various critical situations that can occur.
static class	Application.LegacyApplication Deprecated. This class is only intended to ease migration and should not be used for new projects.
static class	Application.SystemMessages Contains the system messages used to notify the user about various critical situations that can occur.
class	Application.UserChangeEvent An event that characterizes a change in the current selection.
static interface	Application.UserChangeListener The UserChangeListener interface for listening application user changes.
class	Application.WindowAttachEvent Window attach event.
static interface	Application.WindowAttachListener Window attach listener interface.
class	Application.WindowDetachEvent Window detach event.
static interface	Application.WindowDetachListener Window detach listener interface.

Field Summary

static String

ROOT_PARAMETER The name of the parameter that is by default used in e.g.

Constructor Summary

Application()

Method Summary

void	addListener(Application.UserChangeListener listener) Adds the user change listener.
void	addRequestHandler(RequestHandler handler) Adds a request handler to this application.
void	addResource(ApplicationResource resource) Adds new resource to the application.
void	close() Ends the Application.
String	createConnectorId(ClientConnector connector) Generate an id for the given Connector.
ApplicationContext	getContext() Gets the application context.
ConverterFactory	getConverterFactory() Gets the ConverterFactory used to locate a suitable Converter for fields in the application.
static Application	getCurrent() Gets the currently used application.
Terminal.ErrorListener	getErrorHandler() Gets the application error handler.
Locale	getLocale() Gets the default locale for this application.
String	getLogoutURL() Returns the URL user is redirected to on application close.
String	getProperty(String name) Searches for the property with the specified name in this application.
Enumeration<?>	getPropertyNames() Returns an enumeration of all the names in this application.
String	getRelativeLocation(ApplicationResource resource) Deprecated. this method is intended to be used by the terminal only. It may be removed or moved in the future.
Collection<RequestHandler>	getRequestHandlers() Gets the request handlers that are registered to the application.
ApplicationResource	getResource(String key) Find an application resource with a given key.
protected Root	getRoot(WrappedRequest request) Gets a root for a request for which no root is already known.
Root	getRootById(int rootId) Returns a Root with the given id.
protected String	getRootClassName(WrappedRequest request) Provides the name of the Root class that should be used for a request.
Root	getRootForRequest(WrappedRequest request) Finds the Root to which a particular request belongs.
Collection<Root>	getRoots() Gets all the roots of this application.
static Application.SystemMessages	getSystemMessages() Gets the SystemMessages for this application.
String	getThemeForRoot(Root root) Finds the theme to use for a specific root.
URL	getURL() Gets the URL of the application.
Object	getUser() Gets the user of the application.
String	getVersion() Override this method to return correct version number of your Application.
String	getWidgetsetForRoot(Root root) Finds the widgetset to use for a specific root.
boolean	handleRequest(WrappedRequest request, WrappedResponse response) Handles a request by passing it to each registered RequestHandler in turn until one produces a response.
void	init() Main initializer of the application.
boolean	isProductionMode() Check whether this application is in production mode.
boolean	isRootInitPending(int rootId) Checks whether there's a pending initialization for the root with the given id.
boolean	isRootPreserved() Checks whether the same Root state should be reused if the framework can detect that the application is opened in a browser window where it has previously been open.
boolean	isRunning() Tests if the application is running or if it has been finished.
void	removeListener(Application.UserChangeListener listener) Removes the user change listener.
void	removeRequestHandler(RequestHandler handler) Removes a request handler from the application.
void	removeResource(ApplicationResource resource) Removes the resource from the application.
void	setConverterFactory(ConverterFactory converterFactory) Sets the ConverterFactory used to locate a suitable Converter for fields in the application.
static void	setCurrent(Application application) Sets the thread local for the current application.
void	setErrorHandler(Terminal.ErrorListener errorHandler) Sets the application error handler.
void	setLocale(Locale locale) Sets the default locale for this application.
void	setLogoutURL(String logoutURL) Sets the URL user is redirected to on application close.
void	setRootPreserved(boolean rootPreserved) Sets whether the same Root state should be reused if the framework can detect that the application is opened in a browser window where it has previously been open.
void	setUser(Object user) Sets the user of the application instance.
void	start(Application.ApplicationStartEvent event) Starts the application on the given URL.
void	terminalError(Terminal.ErrorEvent event) Invoked by the terminal on any exception that occurs in application and is thrown by the setVariable to the terminal.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ROOT_PARAMETER

public static final String ROOT_PARAMETER

The name of the parameter that is by default used in e.g. web.xml to define the name of the default Root class.

See Also:

Constant Field Values

Constructor Detail

Application

public Application()

Method Detail

getUser

public Object getUser()

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 setUser(Object).

Returns:

the User of the application.

setUser

public void setUser(Object user)

Sets the user of the application instance. An application instance may have a user associated to it. This can be set in login procedure or application initialization.

A component performing the user login procedure can assign the user 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 getUser().

Parameters:

user - the new user.

getURL

public URL getURL()

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 ( #getMainWindow()) of the application. Note that the main window can also be shown by navigating to the window url ( com.vaadin.ui.Window#getURL()).

Returns:

the application's URL.

close

public void close()

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 setLogoutURL(String). If the logout url has not been set, the browser window is reloaded and the application is restarted.

.

start

public void start(Application.ApplicationStartEvent event)

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 ServletConfig and they are overridden by context-wide initialization parameters ServletContext.

Parameters:

event - the application start event containing details required for starting the application.

isRunning

public boolean isRunning()

Tests if the application is running or if it has been finished.

Application starts running when its #start(URL, Properties, ApplicationContext) method has been called and stops when the close() is called.

Returns:

true if the application is running, false if not.

init

public void init()

Main initializer of the application. The init method is called by the framework when the application is started, and it should perform whatever initialization operations the application needs.

getPropertyNames

public Enumeration<?> getPropertyNames()

Returns an enumeration of all the names in this application.

See #start(URL, Properties, ApplicationContext) how properties are defined.

Returns:

an enumeration of all the keys in this property list, including the keys in the default property list.

getProperty

public String getProperty(String name)

Searches for the property with the specified name in this application. This method returns null if the property is not found. See #start(URL, Properties, ApplicationContext) how properties are defined.

Parameters:

name - the name of the property.

Returns:

the value in this property list with the specified key value.

addResource

public void addResource(ApplicationResource resource)

Adds new resource to the application. The resource can be accessed by the user of the application.

Parameters:

resource - the resource to add.

removeResource

public void removeResource(ApplicationResource resource)

Removes the resource from the application.

Parameters:

resource - the resource to remove.

getRelativeLocation

@Deprecated
public String getRelativeLocation(ApplicationResource resource)

Deprecated. this method is intended to be used by the terminal only. It may be removed or moved in the future.

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.

Parameters:

resource - the resource to get relative location.

Returns:

the relative uri of the resource or null if called in a background thread

getLocale

public Locale getLocale()

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.

Returns:

the locale of this application.

setLocale

public void setLocale(Locale locale)

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.

Parameters:

locale - the Locale object.

addListener

public void addListener(Application.UserChangeListener listener)

Adds the user change listener. This allows one to get notification each time setUser(Object) is called.

Parameters:

listener - the user change listener to add.

removeListener

public void removeListener(Application.UserChangeListener listener)

Removes the user change listener.

Parameters:

listener - the user change listener to remove.

getLogoutURL

public String getLogoutURL()

Returns the URL user is redirected to on application close. If the URL is null, the application is closed normally as defined by the application running environment.

Desktop application just closes the application window and web-application redirects the browser to application main URL.

Returns:

the URL.

setLogoutURL

public void setLogoutURL(String logoutURL)

Sets the URL user is redirected to on application close. If the URL is null, the application is closed normally as defined by the application running environment: Desktop application just closes the application window and web-application redirects the browser to application main URL.

Parameters:

logoutURL - the logoutURL to set.

getSystemMessages

public static Application.SystemMessages getSystemMessages()

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 Application.CustomizedSystemMessages. To "override" this method, re-implement this method in your application (the class that extends Application.LegacyApplication). Even though overriding static methods is not possible in Java, Vaadin selects to call the static method from the subclass instead of the original getSystemMessages() if such a method exists.

Returns:

the SystemMessages for this application

terminalError

public void terminalError(Terminal.ErrorEvent event)

Invoked by the terminal on any exception that occurs in application and is thrown by the setVariable to the terminal. The default implementation sets the exceptions as ComponentErrors to the component that initiated the exception and prints stack trace to standard error stream.

You can safely override this method in your application in order to direct the errors to some other destination (for example log).

Specified by:

terminalError in interface Terminal.ErrorListener

Parameters:

event - the change event.

See Also:

Terminal.ErrorListener.terminalError(com.vaadin.terminal.Terminal.ErrorEvent)

getContext

public ApplicationContext getContext()

Gets the application context.

The application context is the environment where the application is running in. The actual implementation class of may contains quite a lot more functionality than defined in the ApplicationContext interface.

By default, when you are deploying your application to a servlet container, the implementation class is 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 PortletApplicationContext.

Returns:

the application context.

getVersion

public String getVersion()

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".

Returns:

version string

getErrorHandler

public Terminal.ErrorListener getErrorHandler()

Gets the application error handler. The default error handler is the application itself.

Returns:

Application error handler

setErrorHandler

public void setErrorHandler(Terminal.ErrorListener errorHandler)

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).

Parameters:

errorHandler -

getConverterFactory

public ConverterFactory getConverterFactory()

Gets the ConverterFactory used to locate a suitable Converter for fields in the application. See setConverterFactory(ConverterFactory) for more details

Returns:

The converter factory used in the application

setConverterFactory

public void setConverterFactory(ConverterFactory converterFactory)

Sets the ConverterFactory used to locate a suitable Converter for fields in the application.

The ConverterFactory is used to find a suitable converter when binding data to a UI component and the data type does not match the UI component type, e.g. binding a Double to a TextField (which is based on a String).

The Converter for an individual field can be overridden using AbstractField.setConverter(Converter) and for individual property ids in a Table using Table.setConverter(Object, Converter).

The converter factory must never be set to null.

Parameters:

converterFactory - The converter factory used in the application

getRoot

protected Root getRoot(WrappedRequest request)
                throws RootRequiresMoreInformationException

Gets a root for a request for which no root is already known. This method is called when the framework processes a request that does not originate from an existing root instance. This typically happens when a host page is requested.

Subclasses of Application may override this method to provide custom logic for choosing how to create a suitable root or for picking an already created root. If an existing root is picked, care should be taken to avoid keeping the same root open in multiple browser windows, as that will cause the states to go out of sync.

If WrappedRequest.BrowserDetails are required to create a Root, the implementation can throw a RootRequiresMoreInformationException exception. In this case, the framework will instruct the browser to send the additional details, whereupon this method is invoked again with the browser details present in the wrapped request. Throwing the exception if the browser details are already available is not supported.

The default implementation in Application.LegacyApplication creates a new instance of the Root class returned by getRootClassName(WrappedRequest), which in turn uses the "root" parameter from web.xml. If DeploymentConfiguration.getClassLoader() for the request returns a ClassLoader, it is used for loading the Root class. Otherwise the ClassLoader used to load this class is used.

Parameters:

request - the wrapped request for which a root is needed

Returns:

a root instance to use for the request

Throws:

RootRequiresMoreInformationException - may be thrown by an implementation to indicate that WrappedRequest.BrowserDetails are required to create a root

Since:

7.0

See Also:

getRootClassName(WrappedRequest), Root, RootRequiresMoreInformationException, WrappedRequest.getBrowserDetails()

getRootClassName

protected String getRootClassName(WrappedRequest request)

Provides the name of the Root class that should be used for a request. The class must have an accessible no-args constructor.

The default implementation uses the "root" parameter from web.xml.

This method is mainly used by the default implementation of getRoot(WrappedRequest). If you override that method with your own functionality, the results of this method might not be used.

Parameters:

request - the request for which a new root is required

Returns:

the name of the root class to use

Since:

7.0

getThemeForRoot

public String getThemeForRoot(Root root)

Finds the theme to use for a specific root. If no specific theme is required, null is returned. TODO Tell what the default implementation does once it does something.

Parameters:

root - the root to get a theme for

Returns:

the name of the theme, or null if the default theme should be used

Since:

7.0

getWidgetsetForRoot

public String getWidgetsetForRoot(Root root)

Finds the widgetset to use for a specific root. If no specific widgetset is required, null is returned. TODO Tell what the default implementation does once it does something.

Parameters:

root - the root to get a widgetset for

Returns:

the name of the widgetset, or null if the default widgetset should be used

Since:

7.0

handleRequest

public boolean handleRequest(WrappedRequest request,
                             WrappedResponse response)
                      throws IOException

Handles a request by passing it to each registered RequestHandler in turn until one produces a response. This method is used for requests that have not been handled by any specific functionality in the terminal implementation (e.g. AbstractApplicationServlet).

The request handlers are invoked in the revere order in which they were added to the application until a response has been produced. This means that the most recently added handler is used first and the first request handler that was added to the application is invoked towards the end unless any previous handler has already produced a response.

Parameters:

request - the wrapped request to get information from

response - the response to which data can be written

Returns:

returns true if a RequestHandler has produced a response and false if no response has been written.

Throws:

IOException

Since:

7.0

See Also:

addRequestHandler(RequestHandler), RequestHandler

addRequestHandler

public void addRequestHandler(RequestHandler handler)

Adds a request handler to this application. Request handlers can be added to provide responses to requests that are not handled by the default functionality of the framework.

Handlers are called in reverse order of addition, so the most recently added handler will be called first.

Parameters:

handler - the request handler to add

Since:

7.0

See Also:

handleRequest(WrappedRequest, WrappedResponse), removeRequestHandler(RequestHandler)

removeRequestHandler

public void removeRequestHandler(RequestHandler handler)

Removes a request handler from the application.

Parameters:

handler - the request handler to remove

Since:

7.0

getRequestHandlers

public Collection<RequestHandler> getRequestHandlers()

Gets the request handlers that are registered to the application. The iteration order of the returned collection is the same as the order in which the request handlers will be invoked when a request is handled.

Returns:

a collection of request handlers, with the iteration order according to the order they would be invoked

Since:

7.0

See Also:

handleRequest(WrappedRequest, WrappedResponse), addRequestHandler(RequestHandler), removeRequestHandler(RequestHandler)

getResource

public ApplicationResource getResource(String key)

Find an application resource with a given key.

Parameters:

key - The key of the resource

Returns:

The application resource corresponding to the provided key, or null if no resource is registered for the key

Since:

7.0

getCurrent

public static Application getCurrent()

Gets the currently used application. The current application is automatically defined when processing requests to the server. In other cases, (e.g. from background threads), the current application is not automatically defined.

Returns:

the current application instance if available, otherwise null

Since:

7.0

See Also:

setCurrent(Application)

setCurrent

public static void setCurrent(Application application)

Sets the thread local for the current application. This method is used by the framework to set the current application whenever a new request is processed and it is cleared when the request has been processed.

The application developer can also use this method to define the current application outside the normal request handling, e.g. when initiating custom background threads.

Parameters:

application -

Since:

7.0

See Also:

getCurrent(), ThreadLocal

isProductionMode

public boolean isProductionMode()

Check whether this application is in production mode. If an application is in production mode, certain debugging facilities are not available.

Returns:

the status of the production mode flag

Since:

7.0

getRootForRequest

public Root getRootForRequest(WrappedRequest request)
                       throws RootRequiresMoreInformationException

Finds the Root to which a particular request belongs. If the request originates from an existing Root, that root is returned. In other cases, the method attempts to create and initialize a new root and might throw a RootRequiresMoreInformationException if all required information is not available.

Please note that this method can also return a newly created Root which has not yet been initialized. You can use isRootInitPending(int) with the root's id ( Root.getRootId() to check whether the initialization is still pending.

Parameters:

request - the request for which a root is desired

Returns:

a root belonging to the request

Throws:

RootRequiresMoreInformationException - if no existing root could be found and creating a new root requires additional information from the browser

Since:

7.0

See Also:

getRoot(WrappedRequest), RootRequiresMoreInformationException

setRootPreserved

public void setRootPreserved(boolean rootPreserved)

Sets whether the same Root state should be reused if the framework can detect that the application is opened in a browser window where it has previously been open. The framework attempts to discover this by checking the value of window.name in the browser.

NOTE that you should avoid turning this feature on/off on-the-fly when the UI is already shown, as it might not be retained as intended.

Parameters:

rootPreserved - trueif the same Root instance should be reused e.g. when the browser window is refreshed.

isRootPreserved

public boolean isRootPreserved()

Checks whether the same Root state should be reused if the framework can detect that the application is opened in a browser window where it has previously been open. The framework attempts to discover this by checking the value of window.name in the browser.

Returns:

trueif the same Root instance should be reused e.g. when the browser window is refreshed.

isRootInitPending

public boolean isRootInitPending(int rootId)

Checks whether there's a pending initialization for the root with the given id.

Parameters:

rootId - root id to check for

Returns:

true of the initialization is pending, false if the root id is not registered or if the root has already been initialized

See Also:

getRootForRequest(WrappedRequest)

getRoots

public Collection<Root> getRoots()

Gets all the roots of this application. This includes roots that have been requested but not yet initialized. Please note, that roots are not automatically removed e.g. if the browser window is closed and that there is no way to manually remove a root. Inactive roots will thus not be released for GC until the entire application is released when the session has timed out (unless there are dangling references). Improved support for releasing unused roots is planned for an upcoming alpha release of Vaadin 7.

Returns:

a collection of roots belonging to this application

Since:

7.0

createConnectorId

public String createConnectorId(ClientConnector connector)

Generate an id for the given Connector. Connectors must not call this method more than once, the first time they need an id.

Parameters:

connector - A connector that has not yet been assigned an id.

Returns:

A new id for the connector

getRootById

public Root getRootById(int rootId)

Returns a Root with the given id.

This is meant for framework internal use.

Parameters:

rootId - The root id

Returns:

The root with the given id or null if not found