Class Application

Class Application
Prev	Chapter 9. Package com.itmill.toolkit	Next

Class Application

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

Synopsis

VERSION@
Since: 3.0

Inheritance Path. java.lang.Object-> com.itmill.toolkit.Application

addListener(Application.UserChangeListener)

Add user change listener

addListener(Application.WindowAttachListener)

Add window attach listener

addListener(Application.WindowDetachListener)

Add window detach listener

addResource(ApplicationResource)

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

addWindow(Window)

Parameters

window: the new Window to add

Exceptions

IllegalArgumentException: if a window with the same name as the new window already exists in the application
NullPointerException: if the given Window or its name is null

Adds a new window to the application.

This implicitly invokes the setApplication(com.itmill.toolkit.Application) method.

close()

Ends the Application. In effect this will cause the application stop returning any windows when asked.

getContext()

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

getLocale()

Get thed default locale for this application

getLogoutURL()

Parameters

return: URL

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: Desctop application just closes the application window and web-application redirects the browser to application main URL.

getMainWindow()

Parameters

return: Window

Returns the mainWindow of the application.

getProperty(String)

Parameters

name: The name of the property.
return: The value in this property list with the specified key value.

Searches for the property with the specified name in this application. The method returns null if the property is not found.

getPropertyNames()

Parameters

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

Returns an enumeration of all the names in this application.

getRelativeLocation(ApplicationResource)

Get relative uri of the resource

getTheme()

Parameters

return: the name of the application's theme

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.

getToolkitLicense()

Parameters

return: License this application is currently using

Get the license this application is running on. The license is initialized by the ApplicationServlet before application is started. The the license-file can not be found in WEB-INF/itmill-toolkit-license.xml, you can set its source in application init().

getURL()

Parameters

return: the application's URL.

Gets the URL of the application.

getUser()

Parameters

return: User of the application.

Gets the user of the application.

getWindow(String)

Parameters

name: The name of the window.
return: The window associated with the given URI or null

Gets a window by name. Returns null if the application is not running or it does not contain a window corresponding to name .

getWindows()

Parameters

return: Unmodifiable collection of windows

Gets the set of windows contained by the application.

handleURI(URL, String)

Description copied from interface: handleURI

Handle uri. Handle the given relative URI. If the URI handling wants to emit a downloadable stream it can return download stream object. If no emitting stream is necessary, null should be returned instead.

init()

Main initializer of the application. This 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.

isRunning()

Parameters

return: true if the application is running, false if not

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

removeListener(Application.UserChangeListener)

Remove user change listener

removeListener(Application.WindowAttachListener)

Remove window attach listener

removeListener(Application.WindowDetachListener)

Remove window detach listener

removeResource(ApplicationResource)

Remove resource from the application.

removeWindow(Window)

Parameters

window: The window to be removed

Removes the specified window from the application.

setLocale(Locale)

Set the default locale for this application

setLogoutURL(String)

Parameters

logoutURL: The logoutURL to set

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: Desctop application just closes the application window and web-application redirects the browser to application main URL.

setMainWindow(Window)

Parameters

mainWindow: The mainWindow to set

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.

setTheme(String)

Parameters

theme: The new theme for this application

Sets the application's theme. Note that this theme can be overridden by the windows. null implies the default terminal theme.

setToolkitLicense(License)

Parameters

license: New license for this application.

Set the license this application is currently using. The license is initialized by the ApplicationServlet before application is started. Changing the license after application init has no effect.

setUser(Object)

Parameters

user: the new 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.

start(URL, Properties, ApplicationContext)

Parameters

applicationUrl: The URL the application should respond to
applicationProperties: Application properties as specified by the adapter.
context: The context application will be running in

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.

terminalError(Terminal.ErrorEvent)

See Also: terminalError(com.itmill.toolkit.terminal.Terminal.ErrorEvent)

This method is 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. You can safely override this method in your application in order to direct the errors to some other destination (for example log).

Prev	Up	Next
Chapter 9. Package com.itmill.toolkit	Home	Class Application.UserChangeEvent