Package net.sf.jguiraffe.gui.app

Class 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:

    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 211 2012-07-10 19:49:13Z oheger $
    Author:
    Oliver Heger

    • 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_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_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"/>
   <!-- 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 if there have been changes. This is equivalent to calling saveUserConfiguration(false);.
        Throws:
        ApplicationException - if an error occurs

      • saveUserConfiguration

        public void saveUserConfiguration​(boolean force)
                           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. With the force flag the behavior can be controlled if the configuration has not been modified: if it is false, no action is taken in this case; otherwise, the configuration is written anyway.
        Parameters:
        force - flag whether an unmodified configuration should be saved
        Throws:
        ApplicationException - if an error occurs
        Since:
        1.4

      • 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. If the application has already been shut down, this invocation has no effect.
        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. If the application has already been shut down, this invocation has no effect.

      • shutdown

        public void shutdown​(boolean force)
        Shuts down this application unconditionally, optionally without asking shutdown listeners for permission. If the force parameter is false, the canShutdown() method of registered shutdown listeners is invoked, so that they can abort the shutdown operation. With the value true, this is not the case; the method then assumes that no shutdown listener has objections against the operation. If the application has already been shut down, this invocation has no effect.
        Parameters:
        force - a flag whether the shutdown should be enforced
        Since:
        1.4

      • 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