net.sf.jguiraffe.gui.app
Class Application

java.lang.Object
  net.sf.jguiraffe.gui.app.Application

public class Application
extends java.lang.Object

The main startup class of the GUI application framework.

With this class a Java GUI application can be started. This works as follows:

1. The class uses the values of system properties to find out the name of the application's configuration file.
2. This configuration file is loaded using commons-configuration.
3. From properties defined in the application's configuration the ApplicationContext is created and initialized. This includes setting up a resource manager.
4. The name of the application's main GUI builder script is also determined by configuration properties. This script is executed, and the resulting main window is made visible.

Per default the application's configuration file is expected to be located in the class path and has the name config.xml. This can be changed using system properties: The property net.sf.jguiraffe.configName allows to change the name of the configuration file. If defined, a file with this name will be searched in the class path. If the property net.sf.jguiraffe.configURL is provided, the class tries to load this file directly from this URL.

A bunch of configuration properties is evaluated by this class to perform the correct setup. All of these must be placed in a section called framework. The following table lists the available properties:

Property	Description	Optional
appctx	In this section some properties of the application context are defined: locale Here the locale to be set at startup can be specified. If the property is missing, the system's default locale will be used. defaultResourceGroup Allows to define a default resource group that is used by the resource manager when no specific resource group is specified.	Yes
builder	This section contains some setting related to the builders used for processing bean definitions and GUI scripts. All properties in this section are optional - meaningful default values are applied if a value is not set. The following sub elements are supported: beanBuilderFactory Specifies the full qualified name of the BeanBuilderFactory implementation that is used to obtain bean builder instances. Here the implementation class and additional initialization properties can be specified. beandefinitions In this subsection an arbitrary number of beandefinition elements can be specified. Each beandefinition element points to a script with bean definitions. These scripts will be processed by the default bean builder. menuIcon An optional boolean flag that determines whether menu items should be rendered with an icon if one is defined. Note that this may not work on all platforms. The default value for this flag is false. toolbarText An optional boolean flag that determines whether toolbar buttons should display their text. Note that this may not be supported by all platforms. The default value of this flag is false. mainScript With this property the name of the main builder script can be specified. If defined, the script will be executed using the application's builder. If this results in a window, this window will be displayed.	Yes
frame	In this section some properties of the application's main window can be defined, especially its location and size. The idea is that this information will be stored in a user configuration so that the last settings can be set again on next application start. The following properties can be defined in this section: xpos Defines the x position of the main window. ypos Defines the y position of the main window. width Defines the width position of the main window. height Defines the height position of the main window.	Yes
storeuserconfig	A boolean property that determines whether the user specific configuration should be stored when the application terminates. Defaults to false.	Yes
userconfigname	Defines the name of the user configuration in the configuration definition file. (The configuration definition file can include an arbitrary number of configuration sources. To determine, which of these is the user configuration, its name must be specified. If no name is specified, the default userConfig will be used.	Yes

A major part of the configuration of the application is defined in terms of bean definitions. Here many helper classes used by the application are defined (e.g. the resource manager, the message output object, the GUI builder, and many more). At start up, the application creates a BeanContext that provides access to these beans and creates the required instances. There is a default bean definition file (defaultbeans.jelly) with default bean definitions for all available helper classes. It is loaded first. Concrete applications can override some or all of these beans. This is a powerful means of customizing the application.

To override bean definitions, use the framework.builder.beandefinitions section in the application's main configuration file (see above). In this section the names of an arbitrary number of bean definition files can be specified (the files will be loaded from the class path). Using the predefined names for the default beans in these scripts causes the beans to be replaced by the custom ones. Have a look at the defaultbeans.jelly script for more information; in this file all available default beans are listed with a documentation for each.

Version:

$Id: Application.java 171 2009-11-21 20:30:28Z oheger $

Author:

Oliver Heger

Field Summary

static java.lang.String	BEAN_APPLICATION Constant for the name of the bean with the current application instance.
static java.lang.String	BEAN_APPLICATION_CONTEXT Constant for the name of the bean with the application context.
static java.lang.String	BEAN_BINDING_STRATEGY Constant for the name of the binding strategy bean.
static java.lang.String	BEAN_BUILDER Constant for the name of the builder bean.
static java.lang.String	BEAN_CLASS_LOADER_PROVIDER Constant for the name of the bean for the class loader provider.
static java.lang.String	BEAN_COMMAND_QUEUE Constant for the name of the command queue bean.
static java.lang.String	BEAN_CONFIGURATION Constant for the name of the bean with the global configuration.
static java.lang.String	BEAN_DEF_RES_GROUP Constant for the name of the bean with the default resource group.
static java.lang.String	BEAN_GLOBAL_CONTEXT Constant for the name of the bean with the global bean context.
static java.lang.String	BEAN_GUI_SYNCHRONIZER Constant for the name of the GUI synchronizer bean.
static java.lang.String	BEAN_LOCALE Constant for the name of the bean with the locale.
static java.lang.String	BEAN_PREFIX Constant for the prefix for bean definitions used by the framework.
static java.lang.String	BUILDER_SECTION Constant for the section with the builder information.
static java.lang.String	CONFIG_SECTION Constant for the configuration section for the framework.
static java.lang.String	DEF_CONFIG_NAME Constant for the default name of the configuration file.
static java.lang.String	FRAME_SECTION Constant for the frame section in the configuration file.
protected org.apache.commons.logging.Log	log The logger to use.
static java.lang.String	PROP_APPCTX Constant for the application context property in the config file.
static java.lang.String	PROP_BEAN_BUILDER_FACTORY Constant for the bean builder factory property.
static java.lang.String	PROP_BEAN_DEFS Constant for the bean definitions property.
static java.lang.String	PROP_BUILDER_FACTORY Constant for the builder factory property.
static java.lang.String	PROP_BUILDER_MAIN_SCRIPT Constant for the builder main script property.
static java.lang.String	PROP_BUILDER_MENU_ICON Constant for the builder menu icon property.
static java.lang.String	PROP_BUILDER_TOOLBAR_TEXT Constant for the builder toolbar text property.
static java.lang.String	PROP_CONFIG_NAME Constant for the system property with the resource name of the configuration file.
static java.lang.String	PROP_CONFIG_URL Constant for the system property with the URL to the configuration file.
static java.lang.String	PROP_DEFRESGROUP Constant for the default resource group property in the config file.
static java.lang.String	PROP_HEIGHT Constant for the height property in the config file.
static java.lang.String	PROP_LOCALE Constant for the locale property in the config file.
static java.lang.String	PROP_USRCONF Constant for the storeuserconfig property in the config file.
static java.lang.String	PROP_USRCONFNAME Constant for the userconfigname property in the config file.
static java.lang.String	PROP_WIDTH Constant for the width property in the config file.
static java.lang.String	PROP_XPOS Constant for the xpos property in the config file.
static java.lang.String	PROP_YPOS Constant for the ypos property in the config file.
static java.lang.String	USRCONF_NAME Constant for the name of the user configuration.

Constructor Summary

Application()
Creates a new instance of Application.

Method Summary

void	addShutdownListener(ApplicationShutdownListener l) Registers the specified object as a shutdown listeners.
protected ApplicationContext	createApplicationContext() Creates and initializes the application context.
protected BeanBuilderFactory	createBeanBuilderFactory(org.apache.commons.configuration.Configuration config) Creates the factory for the bean builder.
protected CommandQueue	createCommandQueue(ApplicationContext appCtx) Creates and initializes the application's command queue.
protected org.apache.commons.configuration.HierarchicalConfiguration	createConfiguration() Creates the configuration for this application.
protected org.apache.commons.configuration.HierarchicalConfiguration	createConfiguration(java.net.URL configURL) Reads the application's configuration from the specified URL.
protected MutableBeanStore	createRootStore(org.apache.commons.configuration.Configuration config) Creates the root bean store.
void	execute(Command cmd) Executes the given command.
protected void	exitApplication(int exitCode) Terminates this application.
protected java.net.URL	fetchConfigURL() Returns the URL to the configuration file.
protected java.util.Collection<Locator>	findBeanDefinitions(org.apache.commons.configuration.Configuration config) Returns a collection with additional bean definition files to process.
protected boolean	fireCanShutdown() Calls the canShutdown() method on all registered shutdown listeners.
protected void	fireShutdown() Notifies all registered shutdown listeners about the shutdown of this application.
ApplicationContext	getApplicationContext() Returns a reference to the actual application context.
BeanBuilderFactory	getBeanBuilderFactory() Returns the BeanBuilderFactory for obtaining a bean builder.
CommandQueue	getCommandQueue() Returns a reference to the command queue that is used for executing commands in another thread.
java.lang.String	getConfigResourceName() Returns the resource name of the configuration file.
java.lang.String	getConfigURL() Returns the URL from which the configuration file is to be loaded.
GUISynchronizer	getGUISynchronizer() Returns the GUISynchronizer object used by this application.
static Application	getInstance(BeanContext context) Obtains the central Application instance from the specified BeanContext.
org.apache.commons.configuration.Configuration	getUserConfiguration() Returns the configuration object with user specific settings.
protected BeanContext	initBeans(org.apache.commons.configuration.Configuration config) Initializes the application's bean definitions.
protected ClassLoaderProvider	initClassLoaderProvider(ClassLoaderProvider clp) Initializes the global ClassLoaderProvider.
protected void	initGUI(ApplicationContext appCtx) Initializes the application's main GUI.
protected void	initMainWindow(Window window, org.apache.commons.configuration.Configuration config) Initializes the application's main window object.
protected Locator	locatorForMainScript(org.apache.commons.configuration.Configuration config) Returns the locator object for the application's main build script.
static void	main(java.lang.String[] args) A main method for applications based on this framework.
protected void	onShutdown() A hook for shutdown.
void	processCommandLine(java.lang.String[] args) Hook method for processing the command line arguments.
protected BeanBuilderResult	readBeanDefinition(Locator script, MutableBeanStore rootStore, ClassLoaderProvider loaderProvider) A convenience method for processing a file with bean definitions.
protected void	releaseBeanBuilderResults(java.util.Collection<BeanBuilderResult> results) Releases the results of bean builder operations that were created during initialization of this application.
void	removeShutdownListener(ApplicationShutdownListener l) Removes the specified shutdown listener.
static java.net.URL	resolveResourceURL(java.lang.String url, java.lang.String name) Helper method for locating a resource.
void	run() The main execute method of this application.
void	saveUserConfiguration() Stores the configuration with user specific settings.
void	setApplicationContext(ApplicationContext context) Sets the application context.
static void	setApplicationReference(java.lang.Object target, Application ref) Tries to the set a reference to the global Application object in the target object.
void	setBeanBuilderFactory(BeanBuilderFactory beanBuilderFactory) Allows to set the BeanBuilderFactory.
void	setCommandQueue(CommandQueue q) Sets the command queue that is used for executing commands.
void	setConfigResourceName(java.lang.String configResourceName) Sets the resource name under which the configuration file can be loaded.
void	setConfigURL(java.lang.String configURL) Sets the URL to the configuration file.
void	setGUISynchronizer(GUISynchronizer sync) Sets the GUISynchronizer object to be used by this application.
protected void	showMainWindow(Window window) Shows the application's main window.
void	shutdown(java.lang.Object msgres, java.lang.Object titleres) Shuts down this application.
static void	startup(Application application, java.lang.String[] args) Starts an application.
protected void	updateUserConfiguration() Updates the user configuration.

Methods inherited from class java.lang.Object

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

Field Detail

PROP_CONFIG_URL

public static final java.lang.String PROP_CONFIG_URL

Constant for the system property with the URL to the configuration file.

See Also:

Constant Field Values

PROP_CONFIG_NAME

public static final java.lang.String PROP_CONFIG_NAME

Constant for the system property with the resource name of the configuration file.

See Also:

Constant Field Values

DEF_CONFIG_NAME

public static final java.lang.String DEF_CONFIG_NAME

Constant for the default name of the configuration file.

See Also:

Constant Field Values

BEAN_PREFIX

public static final java.lang.String BEAN_PREFIX

Constant for the prefix for bean definitions used by the framework.

See Also:

Constant Field Values

BEAN_CONFIGURATION

public static final java.lang.String BEAN_CONFIGURATION

Constant for the name of the bean with the global configuration.

See Also:

Constant Field Values

BEAN_APPLICATION

public static final java.lang.String BEAN_APPLICATION

Constant for the name of the bean with the current application instance.

See Also:

Constant Field Values

BEAN_APPLICATION_CONTEXT

public static final java.lang.String BEAN_APPLICATION_CONTEXT

Constant for the name of the bean with the application context.

See Also:

Constant Field Values

BEAN_GLOBAL_CONTEXT

public static final java.lang.String BEAN_GLOBAL_CONTEXT

Constant for the name of the bean with the global bean context.

See Also:

Constant Field Values

BEAN_BUILDER

public static final java.lang.String BEAN_BUILDER

Constant for the name of the builder bean.

See Also:

Constant Field Values

BEAN_COMMAND_QUEUE

public static final java.lang.String BEAN_COMMAND_QUEUE

Constant for the name of the command queue bean.

See Also:

Constant Field Values

BEAN_GUI_SYNCHRONIZER

public static final java.lang.String BEAN_GUI_SYNCHRONIZER

Constant for the name of the GUI synchronizer bean.

See Also:

Constant Field Values

BEAN_BINDING_STRATEGY

public static final java.lang.String BEAN_BINDING_STRATEGY

Constant for the name of the binding strategy bean.

See Also:

Constant Field Values

BEAN_LOCALE

public static final java.lang.String BEAN_LOCALE

Constant for the name of the bean with the locale.

See Also:

Constant Field Values

BEAN_DEF_RES_GROUP

public static final java.lang.String BEAN_DEF_RES_GROUP

Constant for the name of the bean with the default resource group.

See Also:

Constant Field Values

BEAN_CLASS_LOADER_PROVIDER

public static final java.lang.String BEAN_CLASS_LOADER_PROVIDER

Constant for the name of the bean for the class loader provider.

See Also:

Constant Field Values

CONFIG_SECTION

public static final java.lang.String CONFIG_SECTION

Constant for the configuration section for the framework.

See Also:

Constant Field Values

PROP_APPCTX

public static final java.lang.String PROP_APPCTX

Constant for the application context property in the config file.

See Also:

Constant Field Values

PROP_LOCALE

public static final java.lang.String PROP_LOCALE

Constant for the locale property in the config file.

See Also:

Constant Field Values

PROP_DEFRESGROUP

public static final java.lang.String PROP_DEFRESGROUP

Constant for the default resource group property in the config file.

See Also:

Constant Field Values

BUILDER_SECTION

public static final java.lang.String BUILDER_SECTION

Constant for the section with the builder information.

See Also:

Constant Field Values

PROP_BUILDER_FACTORY

public static final java.lang.String PROP_BUILDER_FACTORY

Constant for the builder factory property.

See Also:

Constant Field Values

PROP_BEAN_BUILDER_FACTORY

public static final java.lang.String PROP_BEAN_BUILDER_FACTORY

Constant for the bean builder factory property.

See Also:

Constant Field Values

PROP_BEAN_DEFS

public static final java.lang.String PROP_BEAN_DEFS

Constant for the bean definitions property.

See Also:

Constant Field Values

PROP_BUILDER_MENU_ICON

public static final java.lang.String PROP_BUILDER_MENU_ICON

Constant for the builder menu icon property.

See Also:

Constant Field Values

PROP_BUILDER_TOOLBAR_TEXT

public static final java.lang.String PROP_BUILDER_TOOLBAR_TEXT

Constant for the builder toolbar text property.

See Also:

Constant Field Values

PROP_BUILDER_MAIN_SCRIPT

public static final java.lang.String PROP_BUILDER_MAIN_SCRIPT

Constant for the builder main script property.

See Also:

Constant Field Values

FRAME_SECTION

public static final java.lang.String FRAME_SECTION

Constant for the frame section in the configuration file.

See Also:

Constant Field Values

PROP_XPOS

public static final java.lang.String PROP_XPOS

Constant for the xpos property in the config file.

See Also:

Constant Field Values

PROP_YPOS

public static final java.lang.String PROP_YPOS

Constant for the ypos property in the config file.

See Also:

Constant Field Values

PROP_WIDTH

public static final java.lang.String PROP_WIDTH

Constant for the width property in the config file.

See Also:

Constant Field Values

PROP_HEIGHT

public static final java.lang.String PROP_HEIGHT

Constant for the height property in the config file.

See Also:

Constant Field Values

PROP_USRCONF

public static final java.lang.String PROP_USRCONF

Constant for the storeuserconfig property in the config file.

See Also:

Constant Field Values

PROP_USRCONFNAME

public static final java.lang.String PROP_USRCONFNAME

Constant for the userconfigname property in the config file.

See Also:

Constant Field Values

USRCONF_NAME

public static final java.lang.String USRCONF_NAME

Constant for the name of the user configuration.

See Also:

Constant Field Values

log

protected final org.apache.commons.logging.Log log

The logger to use.

Constructor Detail

Application

public Application()

Creates a new instance of Application.

Method Detail

getConfigURL

public java.lang.String getConfigURL()

Returns the URL from which the configuration file is to be loaded.

Returns:

the URL to the configuration file

setConfigURL

public void setConfigURL(java.lang.String configURL)

Sets the URL to the configuration file. The configuration file can either be loaded directly from a URL or as a resource from the class path. If this property is defined, it is loaded directly from the URL specified here.

Parameters:

configURL - the URL to the configuration file

getConfigResourceName

public java.lang.String getConfigResourceName()

Returns the resource name of the configuration file.

Returns:

the resource name of the configuration file

setConfigResourceName

public void setConfigResourceName(java.lang.String configResourceName)

Sets the resource name under which the configuration file can be loaded. If no configuration URL is provided, this property is used to look up the configuration file from the class path.

Parameters:

configResourceName - the resource name of the configuration file

getApplicationContext

public ApplicationContext getApplicationContext()

Returns a reference to the actual application context.

Returns:

the ApplicationContext

setApplicationContext

public void setApplicationContext(ApplicationContext context)

Sets the application context.

Parameters:

context - the new context

getBeanBuilderFactory

public BeanBuilderFactory getBeanBuilderFactory()

Returns the BeanBuilderFactory for obtaining a bean builder. This method can be used when a bean definition file is to be processed.

Returns:

the BeanBuilderFactory

setBeanBuilderFactory

public void setBeanBuilderFactory(BeanBuilderFactory beanBuilderFactory)

Allows to set the BeanBuilderFactory. Normally it is not necessary to set this property. When the application is initialized it creates a default factory.

Parameters:

beanBuilderFactory - the new BeanBuilderFactory

addShutdownListener

public void addShutdownListener(ApplicationShutdownListener l)

Registers the specified object as a shutdown listeners.

Parameters:

l - the listener to register

removeShutdownListener

public void removeShutdownListener(ApplicationShutdownListener l)

Removes the specified shutdown listener.

Parameters:

l - the listener to remove

resolveResourceURL

public static java.net.URL resolveResourceURL(java.lang.String url,
                                              java.lang.String name)

Helper method for locating a resource. The resource can either be specified by a full URL, in which case it is directly loaded, or by a resource name. In the latter case the class loader is used to find the resource.

Parameters:

url - a URL to the resource; this can be a full qualified URL or the name of a file (either relative or absolute)

name - the resource name

Returns:

the URL to the resource or null if it cannot be found

setApplicationReference

public static void setApplicationReference(java.lang.Object target,
                                           Application ref)

Tries to the set a reference to the global Application object in the target object. If the target object implements the ApplicationClient interface, the reference can be set.

Parameters:

target - the target object

ref - the application reference to set

getUserConfiguration

public org.apache.commons.configuration.Configuration getUserConfiguration()
                                                                    throws ApplicationRuntimeException

Returns the configuration object with user specific settings. This configuration can be used to store personalization settings that override the default configuration. For this method to work the system's main configuration definition file must include an entry for the user configuration that is identified by its name. Per default the name is "userConfig", but can be altered with the userconfigname property. The following example fragment from the application's configuration definition file demonstrates how the user configuration should be declared:

 <configuration>
   ...
   <xml fileName="${user.home}/myAppConfig.xml" config-name="userConfig"
     config-optional="true" config-forceCreate="true"/>
   <!-- Further configuration sources to load -->
   ...
 

In this example the attributes starting with config- are of special importance. With config-name the configuration's name is specified, which is necessary for the framework to retrieve the correct user configuration. config-optional declares this configuration source as optional. This means that it won't cause an error when this source cannot be loaded (which will probably be the case when a user starts this application for the first time). The config-forceCreate attribute finally tells the configuration framework to create an empty configuration when loading of the configuration file fails. This will cause the configuration to be automatically created for the new user. If the user customizes the application, these settings can be stored in this configuration. When the application terminates it checks the value of the storeuserconfig property. If this is set to true, the user configuration will be stored. So the next time the application starts it will be found there and override the values in all other configuration sources.

Returns:

the configuration with user specific settings

Throws:

ApplicationRuntimeException - if the user configuration cannot be obtained

saveUserConfiguration

public void saveUserConfiguration()
                           throws ApplicationException

Stores the configuration with user specific settings. This method obtains the user configuration by calling the getUserConfiguration() method. It expects that the user configuration implements the FileConfiguration interface. If a different configuration type is used as user configuration, this method should also be adapted.

Throws:

ApplicationException - if an error occurs

createApplicationContext

protected ApplicationContext createApplicationContext()

Creates and initializes the application context. Loads the configuration, too.

Returns:

the application context

Throws:

ApplicationRuntimeException - if an error occurs during initialization

fetchConfigURL

protected java.net.URL fetchConfigURL()

Returns the URL to the configuration file. This URL is determined by the properties configURL and configResourceName.

Returns:

the URL to the application's main configuration file

Throws:

ApplicationRuntimeException - if the configuration file cannot be located

createConfiguration

protected org.apache.commons.configuration.HierarchicalConfiguration createConfiguration()
                                                                                  throws ApplicationRuntimeException

Creates the configuration for this application. This method calls fetchConfigURL() to determine the URL to the main configuration file. Then this file is loaded with commons-configuration.

Returns:

the configuration to use

Throws:

ApplicationException - if the configuration file cannot be located

ApplicationRuntimeException

createConfiguration

protected org.apache.commons.configuration.HierarchicalConfiguration createConfiguration(java.net.URL configURL)

Reads the application's configuration from the specified URL. The DefaultConfigurationBuilder of Commons Configuration is used for reading the configuration. Occurring exceptions are re-thrown as runtime exceptions.

Parameters:

configURL - the configuration URL

Returns:

the application's main configuration

Throws:

ApplicationRuntimeException - if the configuration cannot be loaded

createRootStore

protected MutableBeanStore createRootStore(org.apache.commons.configuration.Configuration config)

Creates the root bean store. This bean store will contain the fundamental bean definitions required by the framework. Because it is at the top level the contained bean definitions can be used or even overridden by child stores. This implementation creates a default store and populates it with the configuration and the application instance itself.

Parameters:

config - the configuration object

Returns:

the initialized root bean store

createBeanBuilderFactory

protected BeanBuilderFactory createBeanBuilderFactory(org.apache.commons.configuration.Configuration config)

Creates the factory for the bean builder. This method is called during initialization phase. It tries to obtain the factory implementation from the main configuration file. If this fails, a default factory instance will be returned.

Parameters:

config - the main configuration

Returns:

the BeanBuilderFactory to be used

initBeans

protected BeanContext initBeans(org.apache.commons.configuration.Configuration config)

Initializes the application's bean definitions. This implementation will first process the framework-internal bean definition file, which defines the standard beans. After that findBeanDefinitions() is called for obtaining a list of additional definition files to be evaluated. Finally a bean context is created allowing access to all beans defined this way. This algorithm allows concrete applications to define their own beans in an easy way and also to override standard beans used by the framework.

Parameters:

config - the main configuration source

Returns:

the global bean context

initClassLoaderProvider

protected ClassLoaderProvider initClassLoaderProvider(ClassLoaderProvider clp)

Initializes the global ClassLoaderProvider. This method is called by initBeans(Configuration) after the default beans have been loaded. The ClassLoaderProvider passed to this method was obtained from the default beans. A derived class can override this method to perform specific initialization of the passed in ClassLoaderProvider. It can even create a completely new object (the ClassLoaderProvider returned by this method will become the global ClassLoaderProvider; it need not be the same object as was passed to this method). This base implementation simply returns the passed in argument without any modifications.

Parameters:

clp - the ClassLoaderProvider as obtained from the default beans

Returns:

the new global ClassLoaderProvider (must never be null)

readBeanDefinition

protected BeanBuilderResult readBeanDefinition(Locator script,
                                               MutableBeanStore rootStore,
                                               ClassLoaderProvider loaderProvider)

A convenience method for processing a file with bean definitions. A new bean builder will be created, which processes the passed in script. The defined beans are stored in the specified root store. Occurring builder exceptions are re-thrown as runtime exceptions.

Parameters:

script - defines the script with the bean definitions

rootStore - the root store for storing the results

loaderProvider - the optional class loader provider

Returns:

the result object returned by the builder

Throws:

java.lang.IllegalArgumentException - if required parameters are missing

ApplicationRuntimeException - if an error occurs

findBeanDefinitions

protected java.util.Collection<Locator> findBeanDefinitions(org.apache.commons.configuration.Configuration config)

Returns a collection with additional bean definition files to process. This method is called when the application context is created. All files contained in the returned list will be processed by the bean builder. This base implementation obtains the value(s) of the framework.builder.beandefinitions.beandefinition configuration property. The values are interpreted as names of bean definition files, which can be read from the class path. If an application has different requirements for specifying additional bean definition files, this method can be overridden.

Parameters:

config - the main configuration source

Returns:

a list with locators to bean definition files to be processed (can be null)

initGUI

protected void initGUI(ApplicationContext appCtx)

Initializes the application's main GUI. This method checks whether a script for the main GUI is defined in the application's configuration. If this is the case, the script is executed, and the resulting main window is stored.

Parameters:

appCtx - the application context

Throws:

ApplicationRuntimeException - if an error occurs

locatorForMainScript

protected Locator locatorForMainScript(org.apache.commons.configuration.Configuration config)

Returns the locator object for the application's main build script. This implementation checks if a script is specified in the configuration. If this is the case, a class path locator will be returned. Derived classes can use different mechanisms to determine the build script. A return value of null means that no script should be executed.

Parameters:

config - the configuration

Returns:

the locator for the main builder script

initMainWindow

protected void initMainWindow(Window window,
                              org.apache.commons.configuration.Configuration config)

Initializes the application's main window object. This method is called after the main window has been created by the main build script. Here the passed in configuration object can be used to initialize properties on this object. This implementation deals with the window's bounds, which can be initialized from the configuration.

Parameters:

window - the new main window object

config - the actual configuration

showMainWindow

protected void showMainWindow(Window window)

Shows the application's main window. This method is called after the main window has been fully initialized. All other parts of the application have also been initialized.

Parameters:

window - the main window

createCommandQueue

protected CommandQueue createCommandQueue(ApplicationContext appCtx)

Creates and initializes the application's command queue. This implementation obtains the command queue from the global bean context managed by the application context.

Parameters:

appCtx - the application context

Returns:

the new command queue

Throws:

InjectionException - if the command queue cannot be created

getCommandQueue

public CommandQueue getCommandQueue()

Returns a reference to the command queue that is used for executing commands in another thread.

Returns:

the command queue

setCommandQueue

public void setCommandQueue(CommandQueue q)

Sets the command queue that is used for executing commands.

Parameters:

q - the new command queue (must not be null)

Throws:

java.lang.IllegalArgumentException - if the command queue is null

getGUISynchronizer

public GUISynchronizer getGUISynchronizer()

Returns the GUISynchronizer object used by this application. This object can be used to deal with the event dispatch thread.

Returns:

the GUI synchronizer

setGUISynchronizer

public void setGUISynchronizer(GUISynchronizer sync)

Sets the GUISynchronizer object to be used by this application. This object can be used for safe GUI updates that need to take place at the event dispatch thread. It will also set at the application's command queue, so that always the same synchronizer is used.

Parameters:

sync - the GUI synchronizer

execute

public void execute(Command cmd)

Executes the given command. The command is put into the internal command queue. It is then executed in another thread. If the passed in command implements the ApplicationClient interface, a reference to this application will be automatically set before execution.

Parameters:

cmd - the command to be executed

shutdown

public void shutdown(java.lang.Object msgres,
                     java.lang.Object titleres)

Shuts down this application. This method should always be called by the main window class when the application is to be terminated. This implementation checks if commands are still running. If this is the case, a message is displayed (using the message output object) to the user asking if the application should be ended anyway. The resource for this message is defined by the passed in parameter, which can be a resource ID or an ApplicationResourceDef object. Only if the user confirms this, the application will be ended.

Parameters:

msgres - defines the resource of the message to be displayed

titleres - defines the resource of the title of the message

onShutdown

protected void onShutdown()

A hook for shutdown. This method is called by the default implementation of the shutdown() method. Here application specific cleanup can be placed. Note: if this method is overloaded in a derived class, the inherited method should be called. This implementation cares for storing the user specific configuration if the storeuserconfig property is true. Before that the {@link #updateUserConfiguration() updateUserConfiguration() method is called.

updateUserConfiguration

protected void updateUserConfiguration()

Updates the user configuration. This method is called during shutdown if the storeuserconfig configuration property is set. Here actual settings can be written in the user configuration object so that they can be restored the next time the application is started again. This implementation stores the actual bounds of the main frame in the user config.

fireCanShutdown

protected boolean fireCanShutdown()

Calls the canShutdown() method on all registered shutdown listeners. If one of them returns false , the remaining listeners are not invoked and shutdown process is canceled.

Returns:

a flag whether to proceed with the shutdown process

fireShutdown

protected void fireShutdown()

Notifies all registered shutdown listeners about the shutdown of this application.

releaseBeanBuilderResults

protected void releaseBeanBuilderResults(java.util.Collection<BeanBuilderResult> results)

Releases the results of bean builder operations that were created during initialization of this application. The results of all bean builder operations performed by initBeans(Configuration) are stored so that they can be released when the application shuts down. This is exactly the task of this method. It is called by shutdown().

Parameters:

results - the collection with the builder results to be released

exitApplication

protected void exitApplication(int exitCode)

Terminates this application. This method is called by shutdown() at the very end. It simply calls System.exit() with the passed in exit code to end this application.

Parameters:

exitCode - the exit code

run

public void run()
         throws ApplicationException

The main execute method of this application. Performs all initialization steps and displays the application's main window. This method starts it all.

Throws:

ApplicationException - if an error occurs during initialization

processCommandLine

public void processCommandLine(java.lang.String[] args)
                        throws ApplicationException

Hook method for processing the command line arguments. Here a derived class can place some logic to evaluate passed in parameters. This base implementation is empty.

Parameters:

args - the command line arguments

Throws:

ApplicationException - if a command line error occurs

startup

public static void startup(Application application,
                           java.lang.String[] args)
                    throws ApplicationException

Starts an application. This method performs all steps to initialize and startup an Application object. First the system properties are checked if the configuration file is specified. Then the application is given the opportunity of processing its command line. Finally its run() method is invoked, which starts the application. A typical use case for this method is to create an Application instance (which also can be of a derived class) and pass it to this method together with the command line array. The rest is done by this method.

Parameters:

application - the application to start

args - the command line arguments

Throws:

ApplicationException - if an error occurs

main

public static void main(java.lang.String[] args)
                 throws ApplicationException

A main method for applications based on this framework. This method tries to determine the name of the configuration file from system properties. Then it creates an instance of this class, initializes it, and calls the startup() method.

Parameters:

args - command line arguments

Throws:

ApplicationException - if an error occurs

getInstance

public static Application getInstance(BeanContext context)

Obtains the central Application instance from the specified BeanContext. This method provides an easy way for obtaining the Application when only the ApplicationContext is known: just call Application myApp = Application.getInstance(appCtx.getBeanContext());. If the application cannot be found in the given bean context, an exception is thrown.

Parameters:

context - the bean context

Returns:

the Application object defined in this bean context

Throws:

InjectionException - if the application bean cannot be found

java.lang.IllegalArgumentException - if the passed in context is null