org.millstone.base
Class Application

java.lang.Object
  |
  +--org.millstone.base.Application

All Implemented Interfaces:

URIHandler

public abstract class Application

extends java.lang.Object

implements URIHandler

Abstract base class required for all MillStone applications. This class provides all the basic services required by the MillStone framework. These services allow external discovery and manipulation of the user, windows and themes, and starting and stopping the application.

As mentioned, all MillStone applications must inherit this class. However, this is almost all of what one needs to do to create a fully functional MillStone 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 MillStone 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 org.millstone.examples.HelloWorld for a simple example of a fully working MillStone 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 MillStone 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:

3.0.3

Author:

IT Mill Ltd.

Nested Class Summary

class	Application.UserChangeEvent Application user change event sent when the setUser is called to change the current user of the application.
static interface	Application.UserChangeListener Public 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

Constructor Summary

Application()

Method Summary

void	addListener(Application.UserChangeListener listener) Add user change listener
void	addListener(Application.WindowAttachListener listener) Add window attach listener
void	addListener(Application.WindowDetachListener listener) Add window detach listener
void	addResource(ApplicationResource resource) Add new resource to the application.
void	addWindow(Window window) Adds a new window to the application.
void	close() Ends the Application.
java.util.Locale	getLocale() Get thed default locale for this application
java.lang.String	getLogoutURL() Returns the URL user is redirected to on application close.
Window	getMainWindow() Returns the mainWindow of the application.
java.lang.String	getProperty(java.lang.String name) Searches for the property with the specified name in this application.
java.util.Enumeration	getPropertyNames() Returns an enumeration of all the names in this application.
java.lang.String	getRelativeLocation(ApplicationResource resource) Get relative uri of the resource
java.lang.String	getTheme() Gets the application's theme.
java.net.URL	getURL() Gets the URL of the application.
java.lang.Object	getUser() Gets the user of the application.
Window	getWindow(java.lang.String name) Gets a window by name.
java.util.Collection	getWindows() Gets the set of windows contained by the application.
DownloadStream	handleURI(java.net.URL context, java.lang.String relativeUri) Handle uri.
abstract void	init() Main initializer of the application.
boolean	isRunning() Tests if the application is running or if it has it been finished.
void	removeListener(Application.UserChangeListener listener) Remove user change listener
void	removeListener(Application.WindowAttachListener listener) Remove window attach listener
void	removeListener(Application.WindowDetachListener listener) Remove window detach listener
void	removeResource(ApplicationResource resource) Remove resource from the application.
void	removeWindow(Window window) Removes the specified window from the application.
void	setLocale(java.util.Locale locale) Set the default locale for this application
void	setLogoutURL(java.lang.String logoutURL) Sets the URL user is redirected to on application close.
void	setMainWindow(Window mainWindow) Sets the mainWindow.
void	setTheme(java.lang.String theme) Sets the application's theme.
void	setUser(java.lang.Object user) Sets the user of the application instance.
void	start(java.net.URL applicationUrl, java.util.Properties applicationProperties) Starts the application on the given URL.

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(java.lang.String name)

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

Parameters:

name - The name of the window.

Returns:

The window associated with the given URI or null

addWindow

public void addWindow(Window window)
               throws java.lang.IllegalArgumentException,
                      java.lang.NullPointerException

Adds a new window to the application.

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

Parameters:

window - the new Window to add

Throws:

java.lang.IllegalArgumentException - if a window with the same name as the new window already exists in the application

java.lang.NullPointerException - if the given Window or its name is null

removeWindow

public void removeWindow(Window window)

Removes the specified window from the application.

Parameters:

window - The window to be removed

getUser

public java.lang.Object getUser()

Gets the user of the application.

Returns:

User of the application.

setUser

public void setUser(java.lang.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 java.net.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(java.net.URL applicationUrl,
                  java.util.Properties applicationProperties)

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.

Parameters:

applicationUrl - The URL the application should respond to

applicationProperties - Application properties as specified by the adapter.

isRunning

public boolean isRunning()

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

Returns:

true if the application is running, false if not

getWindows

public java.util.Collection getWindows()

Gets the set of windows contained by the application.

Returns:

Unmodifiable collection of windows

init

public abstract void 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.

getTheme

public java.lang.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(java.lang.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()

Returns the mainWindow of the application.

Returns:

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 java.util.Enumeration getPropertyNames()

Returns an enumeration of all the names in this application.

Returns:

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

getProperty

public java.lang.String getProperty(java.lang.String name)

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

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)

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

removeResource

public void removeResource(ApplicationResource resource)

Remove resource from the application.

getRelativeLocation

public java.lang.String getRelativeLocation(ApplicationResource resource)

Get relative uri of the resource

handleURI

public DownloadStream handleURI(java.net.URL context,
                                java.lang.String relativeUri)

Description copied from interface: URIHandler

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.

Specified by:

handleURI in interface URIHandler

getLocale

public java.util.Locale getLocale()

Get thed default locale for this application

setLocale

public void setLocale(java.util.Locale locale)

Set the default locale for this application

addListener

public void addListener(Application.UserChangeListener listener)

Add user change listener

removeListener

public void removeListener(Application.UserChangeListener listener)

Remove user change listener

addListener

public void addListener(Application.WindowAttachListener listener)

Add window attach listener

addListener

public void addListener(Application.WindowDetachListener listener)

Add window detach listener

removeListener

public void removeListener(Application.WindowAttachListener listener)

Remove window attach listener

removeListener

public void removeListener(Application.WindowDetachListener listener)

Remove window detach listener

getLogoutURL

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

Returns:

URL

setLogoutURL

public void setLogoutURL(java.lang.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: Desctop application just closes the application window and web-application redirects the browser to application main URL.

Parameters:

logoutURL - The logoutURL to set