com.itmill.toolkit
Class Application

java.lang.Object
  extended by com.itmill.toolkit.Application
All Implemented Interfaces:
Terminal.ErrorListener, URIHandler

public abstract class Application
extends Object
implements URIHandler, Terminal.ErrorListener

Base class required for all IT Mill Toolkit applications. This class provides all the basic services required by the toolkit. These services allow external discovery and manipulation of the user, windows and themes, and starting and stopping the application.

As mentioned, all IT Mill Toolkit 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.itmill.toolkit.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:
5.3.0
Author:
IT Mill Ltd.

Nested Class Summary
 class Application.ApplicationError
           
static class Application.CustomizedSystemMessages
          Contains the system messages used to notify the user about various critical situations that can occur.
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.
 
Nested classes/interfaces inherited from interface com.itmill.toolkit.terminal.URIHandler
URIHandler.ErrorEvent
 
Constructor Summary
Application()
           
 
Method Summary
 void addListener(Application.UserChangeListener listener)
          Adds the user change listener.
 void addListener(Application.WindowAttachListener listener)
          Adds the window attach listener.
 void addListener(Application.WindowDetachListener listener)
          Adds the window detach listener.
 void addResource(ApplicationResource resource)
          Adds new resource to the application.
 void addWindow(Window window)
          Adds a new window to the application.
 void close()
          Ends the Application.
 ApplicationContext getContext()
          Gets the application context.
 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.
 Window getMainWindow()
          Gets the mainWindow of the application.
 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)
          Gets the relative uri of the resource.
static Application.SystemMessages getSystemMessages()
          Gets the SystemMessages for this application.
 String getTheme()
          Gets the application's theme.
 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.
 Window getWindow(String name)
           Gets a window by name.
 Collection getWindows()
          Gets the set of windows contained by the application.
 DownloadStream handleURI(URL context, String relativeUri)
          This method gets called by terminal.
abstract  void init()
           Main initializer of the application.
 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 removeListener(Application.WindowAttachListener listener)
          Removes the window attach listener.
 void removeListener(Application.WindowDetachListener listener)
          Removes the window detach listener.
 void removeResource(ApplicationResource resource)
          Removes the resource from the application.
 void removeWindow(Window window)
          Removes the specified window from the 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 setMainWindow(Window mainWindow)
           Sets the mainWindow.
 void setTheme(String theme)
          Sets the application's theme.
 void setUser(Object user)
           Sets the user of the application instance.
 void start(URL applicationUrl, Properties applicationProperties, ApplicationContext context)
          Starts the application on the given URL.After this call the application corresponds to the given URL and it will return windows when asked for them.
 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
 

Constructor Detail

Application

public Application()
Method Detail

getWindow

public Window getWindow(String name)

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, where 12345678 is a random number. One can decide to create another window-object for those windows (recommended) or to discard the postfix. 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 recommended to create new window-objects on this method from their names if the super.getWindow() does not find existing windows. See below for implementation example:

        // If we already have the requested window, use it
        Window w = super.getWindow(name);
        if (w == null) {
            // If no window found, create it
            w = new Window(name);
            // set windows name to the one requested
            w.setName(name);
            // add it to this application
            addWindow(w);
            // add some content
            w.addComponent(new Label("Test window"));
        }
        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.

Parameters:
name - the name of the window.
Returns:
the window associated with the given URI or null

addWindow

public void addWindow(Window window)
               throws IllegalArgumentException,
                      NullPointerException
Adds a new window to the application.

This implicitly invokes the Window.setApplication(Application) method.

Note that all application-level windows can be accessed 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. Also note that not all windows should be added to application - one can also add windows inside other windows - these windows show as smaller windows inside those windows.

Parameters:
window - the new Window to add. If the name of the window is null, an unique name is automatically given for the window.
Throws:
IllegalArgumentException - if a window with the same name as the new window already exists in the application.
NullPointerException - if the given Window is null.

removeWindow

public void removeWindow(Window window)
Removes the specified window from the application.

Parameters:
window - the window to be removed.

getUser

public Object getUser()
Gets the user of the application.

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.

Parameters:
user - the new user.

getURL

public URL getURL()
Gets the URL of the application.

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.


start

public void start(URL applicationUrl,
                  Properties applicationProperties,
                  ApplicationContext context)
Starts the application on the given URL.After this call the application corresponds to the given URL and it will return windows when asked for them. Application properties are defined by servlet configuration object ServletConfig and they are overridden by context-wide initialization parameters ServletContext.

Parameters:
applicationUrl - the URL the application should respond to.
applicationProperties - the Application properties as specified by the servlet configuration.
context - the context application will be running in.

isRunning

public boolean isRunning()
Tests if the application is running or if it has been finished.

Returns:
true if the application is running, false if not.

getWindows

public Collection getWindows()
Gets the set of windows contained by the application.

Returns:
the Unmodifiable collection of windows.

init

public abstract 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, such as creating windows and adding components to them.


getTheme

public String getTheme()
Gets the application's theme. The application's theme is the default 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.

Returns:
the name of the application's theme.

setTheme

public void setTheme(String theme)
Sets the application's theme.

Note that this theme can be overridden by the windows. null implies the default terminal theme.

Parameters:
theme - the new theme for this application.

getMainWindow

public Window getMainWindow()
Gets the mainWindow of the application.

Returns:
the main window.

setMainWindow

public void setMainWindow(Window mainWindow)

Sets the mainWindow. If the main window is not explicitly set, the main window defaults to first created window. Setting window as a main window of this application also adds the window to this application.

Parameters:
mainWindow - the mainWindow to set.

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

public String getRelativeLocation(ApplicationResource resource)
Gets the relative uri of the resource.

Parameters:
resource - the resource to get relative location.
Returns:
the relative uri of the resource.

handleURI

public DownloadStream handleURI(URL context,
                                String relativeUri)
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.

Specified by:
handleURI in interface URIHandler
Parameters:
context - the URl.
relativeUri - the relative uri.
Returns:
the download stream object.
See Also:
URIHandler.handleURI(URL, String)

getLocale

public Locale getLocale()
Gets the default locale for this application.

Returns:
the locale of this application.

setLocale

public void setLocale(Locale locale)
Sets the default locale for this application.

Parameters:
locale - the Locale object.

addListener

public void addListener(Application.UserChangeListener listener)
Adds the user change listener.

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.

addListener

public void addListener(Application.WindowAttachListener listener)
Adds the window attach listener.

Parameters:
listener - the window attach listener to add.

addListener

public void addListener(Application.WindowDetachListener listener)
Adds the window detach listener.

Parameters:
listener - the window detach listener to add.

removeListener

public void removeListener(Application.WindowAttachListener listener)
Removes the window attach listener.

Parameters:
listener - the window attach listener to remove.

removeListener

public void removeListener(Application.WindowDetachListener listener)
Removes the window detach listener.

Parameters:
listener - the window detach 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

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.itmill.toolkit.terminal.Terminal.ErrorEvent)

getContext

public ApplicationContext getContext()
Gets the application context.

The application context is the environment where the application is running in.

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.

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.

Parameters:
errorHandler -


Copyright © 2000-2009 IT Mill Ltd. All Rights Reserved.