Application (JGUIraffe BOM 1.3.1 API)

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

Direct Known Subclasses:: Main

public class Application
extends Object

The main startup class of the GUI application framework.

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

The class uses the values of system properties to find out the name of the application's configuration file.
This configuration file is loaded using commons-configuration.
From properties defined in the application's configuration the ApplicationContext is created and initialized. This includes setting up a resource manager.
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 211 2012-07-10 19:49:13Z oheger $
Author:: Oliver Heger

Field Summary

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

Constructor Summary

Constructors
Constructor and Description

Application()
Creates a new instance of Application.

Constructors
Constructor and Description
`Application()` Creates a new instance of `Application`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`protected void`	`addBeanDuringApplicationStartup(String name, Object bean)` Adds a bean to the application's global root bean store while the application starts up.
`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(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 URL`	`fetchConfigURL()` Returns the URL to the configuration file.
`protected Collection<Locator>`	`findBeanDefinitions(org.apache.commons.configuration.Configuration config)` Deprecated. This method is replaced by `findBeanDefinitions(Configuration, BeanContext)`. It is still called during application initialization to keep backwards compatibility, but this base implementation simply returns an empty collection.
`protected Collection<Locator>`	`findBeanDefinitions(org.apache.commons.configuration.Configuration config, BeanContext beanCtx)` 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.
`String`	`getConfigResourceName()` Returns the resource name of the configuration file.
`String`	`getConfigURL()` Returns the URL from which the configuration file is to be loaded.
`int`	`getExitCode()` Returns the current exit code for this application.
`Runnable`	`getExitHandler()` Returns the current exit handler of this application.
`GUISynchronizer`	`getGUISynchronizer()` Returns the `GUISynchronizer` object used by this application.
`static Application`	`getInstance(BeanContext context)` Obtains the central `Application` instance from the specified `BeanContext`.
`BeanContext`	`getMainWindowBeanContext()` Returns the `BeanContext` that was created when processing the builder script for the main window.
`protected Locator`	`getPlatformBeansLocator()` Returns a `Locator` object pointing to a file with bean declarations related to the platform or UI toolkit.
`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(String[] args)` A main method for applications based on this framework.
`protected void`	`onShutdown()` A hook for shutdown.
`void`	`processCommandLine(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(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 URL`	`resolveResourceURL(String url, String name)` Deprecated. This method does not make sense in the public interface of this class. It will be removed in later versions. Use corresponding functionality from the `LocatorUtils` class instead.
`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(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(String configResourceName)` Sets the resource name under which the configuration file can be loaded.
`void`	`setConfigURL(String configURL)` Sets the URL to the configuration file.
`void`	`setExitHandler(Runnable handler)` Sets the exit handler for this application.
`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()` Shuts down this application unconditionally.
`void`	`shutdown(Object msgres, Object titleres)` Shuts down this application.
`static void`	`startup(Application application, 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 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 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 String DEF_CONFIG_NAME
```
    Constant for the default name of the configuration file.
    
    See Also:
    
    Constant Field Values
  - BEAN_PREFIX
```
public static final String BEAN_PREFIX
```
    Constant for the prefix for bean definitions used by the framework.
    
    See Also:
    
    Constant Field Values
  - BEAN_CONFIGURATION
```
public static final String BEAN_CONFIGURATION
```
    Constant for the name of the bean with the global configuration.
    
    See Also:
    
    Constant Field Values
  - BEAN_APPLICATION
```
public static final 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 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 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 String BEAN_BUILDER
```
    Constant for the name of the builder bean.
    
    See Also:
    
    Constant Field Values
  - BEAN_COMMAND_QUEUE
```
public static final String BEAN_COMMAND_QUEUE
```
    Constant for the name of the command queue bean.
    
    See Also:
    
    Constant Field Values
  - BEAN_GUI_SYNCHRONIZER
```
public static final String BEAN_GUI_SYNCHRONIZER
```
    Constant for the name of the GUI synchronizer bean.
    
    See Also:
    
    Constant Field Values
  - BEAN_BINDING_STRATEGY
```
public static final String BEAN_BINDING_STRATEGY
```
    Constant for the name of the binding strategy bean.
    
    See Also:
    
    Constant Field Values
  - BEAN_LOCALE
```
public static final 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 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 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 String CONFIG_SECTION
```
    Constant for the configuration section for the framework.
    
    See Also:
    
    Constant Field Values
  - PROP_APPCTX
```
public static final String PROP_APPCTX
```
    Constant for the application context property in the config file.
    
    See Also:
    
    Constant Field Values
  - PROP_LOCALE
```
public static final String PROP_LOCALE
```
    Constant for the locale property in the config file.
    
    See Also:
    
    Constant Field Values
  - PROP_DEFRESGROUP
```
public static final String PROP_DEFRESGROUP
```
    Constant for the default resource group property in the config file.
    
    See Also:
    
    Constant Field Values
  - BUILDER_SECTION
```
public static final String BUILDER_SECTION
```
    Constant for the section with the builder information.
    
    See Also:
    
    Constant Field Values
  - PROP_BUILDER_FACTORY
```
public static final String PROP_BUILDER_FACTORY
```
    Constant for the builder factory property.
    
    See Also:
    
    Constant Field Values
  - PROP_BEAN_BUILDER_FACTORY
```
public static final String PROP_BEAN_BUILDER_FACTORY
```
    Constant for the bean builder factory property.
    
    See Also:
    
    Constant Field Values
  - PROP_BEAN_DEFS
```
public static final String PROP_BEAN_DEFS
```
    Constant for the bean definitions property.
    
    See Also:
    
    Constant Field Values
  - PROP_BUILDER_MENU_ICON
```
public static final String PROP_BUILDER_MENU_ICON
```
    Constant for the builder menu icon property.
    
    See Also:
    
    Constant Field Values
  - PROP_BUILDER_TOOLBAR_TEXT
```
public static final String PROP_BUILDER_TOOLBAR_TEXT
```
    Constant for the builder toolbar text property.
    
    See Also:
    
    Constant Field Values
  - PROP_BUILDER_MAIN_SCRIPT
```
public static final String PROP_BUILDER_MAIN_SCRIPT
```
    Constant for the builder main script property.
    
    See Also:
    
    Constant Field Values
  - FRAME_SECTION
```
public static final String FRAME_SECTION
```
    Constant for the frame section in the configuration file.
    
    See Also:
    
    Constant Field Values
  - PROP_XPOS
```
public static final String PROP_XPOS
```
    Constant for the xpos property in the config file.
    
    See Also:
    
    Constant Field Values
  - PROP_YPOS
```
public static final String PROP_YPOS
```
    Constant for the ypos property in the config file.
    
    See Also:
    
    Constant Field Values
  - PROP_WIDTH
```
public static final String PROP_WIDTH
```
    Constant for the width property in the config file.
    
    See Also:
    
    Constant Field Values
  - PROP_HEIGHT
```
public static final String PROP_HEIGHT
```
    Constant for the height property in the config file.
    
    See Also:
    
    Constant Field Values
  - PROP_USRCONF
```
public static final String PROP_USRCONF
```
    Constant for the storeuserconfig property in the config file.
    
    See Also:
    
    Constant Field Values
  - PROP_USRCONFNAME
```
public static final String PROP_USRCONFNAME
```
    Constant for the userconfigname property in the config file.
    
    See Also:
    
    Constant Field Values
  - USRCONF_NAME
```
public static final String USRCONF_NAME
```
    Constant for the name of the user configuration.
    
    See Also:
    
    Constant Field Values
  - CLASS_LOADER
```
public static final String CLASS_LOADER
```
    Constant for the name of the class loader which loaded the application class. This class loader is set as the default class loader at the ClassLoaderProvider created at startup.
    
    Since:
    
    1.2
    
    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 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(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 String getConfigResourceName()
```
    Returns the resource name of the configuration file.
    
    Returns:
    
    the resource name of the configuration file
  - setConfigResourceName
```
public void setConfigResourceName(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
```
@Deprecated
public static URL resolveResourceURL(String url,
                                                  String name)
```
    Deprecated. This method does not make sense in the public interface of this class. It will be removed in later versions. Use corresponding functionality from the LocatorUtils class instead.
    
    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(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"/>
   
   ...
 
```
    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 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()
```
    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:
    
    ApplicationRuntimeException - if the configuration file cannot be located
  - createConfiguration
```
protected org.apache.commons.configuration.HierarchicalConfiguration createConfiguration(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
  - addBeanDuringApplicationStartup
```
protected void addBeanDuringApplicationStartup(String name,
                                               Object bean)
```
    Adds a bean to the application's global root bean store while the application starts up. This method can be called by derived classes that need to create beans dynamically Sometimes it is not sufficient to define beans in additional definition scripts. For instance, objects may have to be looked up from different sources, or complex logic is required for creating the beans. In such cases, this method can be used to make the beans created by a derived application class globally available via the bean context. As the name implies, this method can be called only during application startup phase - after the invocation of initBeans(Configuration) and before the global bean context is accessed. Calling this method to a later point of time is not guaranteed to have the desired effect!
    
    Parameters:
    
    name - the name of the bean
    
    bean - the bean itself
    
    Since:
    
    1.3.1
  - 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 registers the class loader which has loaded the concrete Application sub class and makes it the default class loader.
    
    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:
    
    IllegalArgumentException - if required parameters are missing
    
    ApplicationRuntimeException - if an error occurs
  - findBeanDefinitions
```
@Deprecated
protected Collection<Locator> findBeanDefinitions(org.apache.commons.configuration.Configuration config)
```
    Deprecated. This method is replaced by findBeanDefinitions(Configuration, BeanContext). It is still called during application initialization to keep backwards compatibility, but this base implementation simply returns an empty collection.
    
    Returns a collection with additional bean definition files to process.
    
    Parameters:
    
    config - the main configuration source
    
    Returns:
    
    a list with locators to bean definition files to be processed (can be null)
  - findBeanDefinitions
```
protected Collection<Locator> findBeanDefinitions(org.apache.commons.configuration.Configuration config,
                                                  BeanContext beanCtx)
```
    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 textual representations of Locator objects which can be converted using the LocatorConverter class. Strings that do not contain a locator type prefix (e.g. classpath: or url: are expected to be names of bean definition files, which can be read from the class path. In addition, the getPlatformBeansLocator() method is called to obtain a Locator for a file with platform-specific bean declarations; if this method returns a non-null value, this Locator is added to the list, too. If an application has different requirements for specifying additional bean definition files, this method can be overridden.
    
    Parameters:
    
    config - the main configuration source
    
    beanCtx - the current BeanContext
    
    Returns:
    
    a list with locators to bean definition files to be processed (can be null)
    
    Since:
    
    1.2
  - getPlatformBeansLocator
```
protected Locator getPlatformBeansLocator()
```
    Returns a Locator object pointing to a file with bean declarations related to the platform or UI toolkit. This method is called when additional bean declaration files to be loaded during application initialization are detected. The base implementation returns a locator pointing to a class path resource with the name platformbeans.jelly. This file contains declarations for beans like the platform-specific component manager, window manager, etc. In a standard JGUIraffe application a single file with this name exists which contains definitions compatible to the supported platform. A derived class may override this method and return a different Locator. Result can be null, then no additional bean declaration file is loaded.
    
    Returns:
    
    a Locator pointing to platform-specific bean declarations
    
    Since:
    
    1.3
  - 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:
    
    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(Object msgres,
                     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
  - shutdown
```
public void shutdown()
```
    Shuts down this application unconditionally. This version of the shutdown() method does not check for tasks still running in the background. It directly invokes the registered shutdown listeners and exits the application if none vetos.
  - getExitHandler
```
public Runnable getExitHandler()
```
    Returns the current exit handler of this application. This is the object called during a shutdown() operation. This method never returns null. If no exit handler has been set, a default one is returned. The default exit handler terminates this application by calling System.exit() with the current exit code.
    
    Returns:
    
    the exit handler of this application
    
    Since:
    
    1.2
  - setExitHandler
```
public void setExitHandler(Runnable handler)
```
    Sets the exit handler for this application. The exit handler is called eventually by shutdown(). Its task is to ultimately terminate this application, e.g. by calling System.exit().
    
    Parameters:
    
    handler - the exit handler for this application (may be null)
    
    Since:
    
    1.2
  - getExitCode
```
public int getExitCode()
```
    Returns the current exit code for this application. This value is only defined during a shutdown() operation. This method is intended to be called by an exit handler to find out the exit status of the application.
    
    Returns:
    
    this application's exit status
    
    Since:
    
    1.2
    
    See Also:
    
    setExitHandler(Runnable)
  - getMainWindowBeanContext
```
public BeanContext getMainWindowBeanContext()
```
    Returns the BeanContext that was created when processing the builder script for the main window. This context may be useful because it contains some central objects defined by the builder script for the main window, e.g. global actions. If this application does not define a builder script for the main window, this method returns null.
    
    Returns:
    
    the BeanContext created when the main window was constructed
    
    Since:
    
    1.3.1
  - 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 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(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(Object, Object) at the very end. It calls the exit handler. This object is responsible for actually terminating this application.
    
    Parameters:
    
    exitCode - the exit code
    
    See Also:
    
    setExitHandler(Runnable)
  - 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(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,
                           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(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
    
    IllegalArgumentException - if the passed in context is null

Class Application

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PROP_CONFIG_URL

PROP_CONFIG_NAME

DEF_CONFIG_NAME

BEAN_PREFIX

BEAN_CONFIGURATION

BEAN_APPLICATION

BEAN_APPLICATION_CONTEXT

BEAN_GLOBAL_CONTEXT

BEAN_BUILDER

BEAN_COMMAND_QUEUE

BEAN_GUI_SYNCHRONIZER

BEAN_BINDING_STRATEGY

BEAN_LOCALE

BEAN_DEF_RES_GROUP

BEAN_CLASS_LOADER_PROVIDER

CONFIG_SECTION

PROP_APPCTX

PROP_LOCALE

PROP_DEFRESGROUP

BUILDER_SECTION

PROP_BUILDER_FACTORY

PROP_BEAN_BUILDER_FACTORY

PROP_BEAN_DEFS

PROP_BUILDER_MENU_ICON

PROP_BUILDER_TOOLBAR_TEXT

PROP_BUILDER_MAIN_SCRIPT

FRAME_SECTION

PROP_XPOS

PROP_YPOS

PROP_WIDTH

PROP_HEIGHT

PROP_USRCONF

PROP_USRCONFNAME

USRCONF_NAME

CLASS_LOADER

log

Constructor Detail

Application

Method Detail

getConfigURL

setConfigURL

getConfigResourceName

setConfigResourceName

getApplicationContext

setApplicationContext

getBeanBuilderFactory

setBeanBuilderFactory

addShutdownListener

removeShutdownListener

resolveResourceURL

setApplicationReference

getUserConfiguration

saveUserConfiguration

createApplicationContext

fetchConfigURL

createConfiguration

createConfiguration

createRootStore

createBeanBuilderFactory

initBeans

addBeanDuringApplicationStartup

initClassLoaderProvider

readBeanDefinition

findBeanDefinitions

findBeanDefinitions

getPlatformBeansLocator

initGUI

locatorForMainScript

initMainWindow

showMainWindow

createCommandQueue

getCommandQueue

setCommandQueue

getGUISynchronizer