|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.itmill.toolkit.Application
public abstract 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
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.
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 |
---|
public Application()
Method Detail |
---|
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.
name
- the name of the window.
null
public void addWindow(Window window) throws IllegalArgumentException, NullPointerException
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.
window
- the new Window
to add. If the name of the window
is null
, an unique name is automatically given
for the window.
IllegalArgumentException
- if a window with the same name as the new window already
exists in the application.
NullPointerException
- if the given Window
is null
.public void removeWindow(Window window)
window
- the window to be removed.public Object getUser()
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.
user
- the new user.public URL getURL()
public void close()
public void start(URL applicationUrl, Properties applicationProperties, ApplicationContext context)
ServletConfig
and they are overridden by
context-wide initialization parameters
ServletContext
.
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.public boolean isRunning()
true
if the application is running,
false
if not.public Collection getWindows()
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.
public String getTheme()
null
is returned.
public void setTheme(String theme)
Note that this theme can be overridden by the windows. null
implies the default terminal theme.
theme
- the new theme for this application.public Window getMainWindow()
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.
mainWindow
- the mainWindow to set.public Enumeration getPropertyNames()
start(URL, Properties, ApplicationContext)
how properties
are defined.
public String getProperty(String name)
null
if the property is not found.
See start(URL, Properties, ApplicationContext)
how properties
are defined.
name
- the name of the property.
public void addResource(ApplicationResource resource)
resource
- the resource to add.public void removeResource(ApplicationResource resource)
resource
- the resource to remove.public String getRelativeLocation(ApplicationResource resource)
resource
- the resource to get relative location.
public DownloadStream handleURI(URL context, String relativeUri)
handleURI
in interface URIHandler
context
- the URl.relativeUri
- the relative uri.
URIHandler.handleURI(URL, String)
public Locale getLocale()
public void setLocale(Locale locale)
locale
- the Locale object.public void addListener(Application.UserChangeListener listener)
listener
- the user change listener to add.public void removeListener(Application.UserChangeListener listener)
listener
- the user change listener to remove.public void addListener(Application.WindowAttachListener listener)
listener
- the window attach listener to add.public void addListener(Application.WindowDetachListener listener)
listener
- the window detach listener to add.public void removeListener(Application.WindowAttachListener listener)
listener
- the window attach listener to remove.public void removeListener(Application.WindowDetachListener listener)
listener
- the window detach listener to remove.public String getLogoutURL()
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.
public void setLogoutURL(String logoutURL)
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.
logoutURL
- the logoutURL to set.public static Application.SystemMessages getSystemMessages()
Application.CustomizedSystemMessages
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).
terminalError
in interface Terminal.ErrorListener
event
- the change event.Terminal.ErrorListener.terminalError(com.itmill.toolkit.terminal.Terminal.ErrorEvent)
public ApplicationContext getContext()
The application context is the environment where the application is running in.
public String getVersion()
public Terminal.ErrorListener getErrorHandler()
public void setErrorHandler(Terminal.ErrorListener errorHandler)
errorHandler
-
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |