passwordstore1
Class Application

java.lang.Object
  passwordstore1.Application

All Implemented Interfaces:

java.lang.Thread.UncaughtExceptionHandler

Direct Known Subclasses:

PasswordStoreApplication

public abstract class Application
extends java.lang.Object
implements java.lang.Thread.UncaughtExceptionHandler

Base Application class for Swing apps. Application provides the following functionality:

• A sequence of methods to override that are invoked as part of starting the application. All methods are invoked on the event dispatch thread.
• Has a ResourceBundle. This is useful for smallish apps that wish to place all their localized resources into a single place.
• Has a Preferences node. This is useful for apps that wish to persist state between sessions.
• Registers itself as the UncaughtExceptionHandler. If an uncaught exception is encountered the application will show a warning dialog and exit.
• Provides a single entry point to call when the user wishes to exit the app. This can be overriden to warn the user about unsaved changes, or provide similar functionality.
• Provides a ThreadFactory that produces background threads suitable for Swing applications. The application will block until all background threads vended from the thread factory have completed.
• An arbitrary set of key/value pairs.

Application provides a handful of methods that are invoked as part of starting the application. Subclasses need only override those they are interested in. The following outlines the order the methods are invoked in as well as what they are intended for. All methods are invoked on the event dispatching thread.

1. preInit is invoked first. preInit is provided for any initialization that needs to be done prior to creating the UI. Application's implementation invokes installLookAndFeel to install the system look and feel.
2. init is invoked after preInit. init is intended for creating the actual UI.
3. ApplicationListeners are notified that the application has initialized (appDidInit).
4. postInit is invoked after the listeners are notified, and is intended for any cleanup that needs to be done.
5. postInitEventQueueEmpty is invoked after postInit and after the event queue has processed all pending events, such as paint events or revalidate requests generated during the earlier stages of initialization. Subclasses that need to do processing after the UI is completely showing should override this method.

Application also provides a sequence of methods for exiting the application. When exit is invoked the following methods are invoked:

1. canExit is invoked, if this returns false the application will not exit.
2. ApplicationListeners are asked if the application can exit. If any ApplicationListener returns false from canApplicationExit the application will not exit.
3. waitForBackgroundThreads is invoked to block until any background threads have completed.
4. All ApplicationListeners are notified that the application is exiting.
5. exiting is invoked.
6. Lastly, System.exit is invoked.

Concrete implementations need only override getName, but will undoubtedly override one of the various init methods as well.

Constructor Summary

Application()
Creates a new Application instance.

Method Summary

void	addApplicationListener(ApplicationListener listener) Adds a listener for application events.
protected boolean	canExit() Returns whether the application should be allowed to exit.
protected javax.swing.JDialog	createBackgroundThreadDialog() Returns the dialog to show when waiting for any background threads to exit.
void	exit() Exits the application.
protected void	exiting() Invoked as part of exiting the application.
java.util.concurrent.ThreadFactory	getBackgroundThreadFactory() Returns a ThreadFactory suitable for threads used within Swing applications.
java.lang.Object	getData(java.lang.Object key) Returns the value for the specified user key.
static Application	getInstance() Returns the single Application instance.
abstract java.lang.String	getName() Returns the name of the application.
java.util.prefs.Preferences	getPreferences() Returns the Preferences object for the Application.
protected java.lang.Class	getPreferencesKey() Returns the Class key used to fetch the Preferences object.
java.util.ResourceBundle	getResourceBundle() Returns the ResourceBundle for the Application.
protected java.lang.String	getResourceBundleName() Returns the key for loading the resources for the Application.
protected javax.swing.JDialog	getUncaughtExceptionDialog() Returns the dialog that is shown when an uncaught exception is encountered.
protected void	init() Invoked as part of starting the application.
protected void	installLookAndFeel() Invoked from preInit to set the look and feel for the Application.
protected void	postInit() Invoked as part of starting the application.
protected void	postInitEventQueueEmpty() Invoked as part of starting the application.
protected void	preInit() Invoked as part of starting the application.
void	putData(java.lang.Object key, java.lang.Object value) Associated the specified value with the specified key.
void	registerThread(java.lang.Thread thread) Registers a background thread with the Application.
void	removeApplicationListener(ApplicationListener listener) Adds a listener for application events.
void	start() Starts the Application.
void	uncaughtException(java.lang.Thread thread, java.lang.Throwable throwable) Invoked when an uncaught exception is encountered.
void	uncaughtException(java.lang.Throwable throwable) Invoked when an uncaught exception is encountered.
protected void	waitForBackgroundThreadsToExit() Blocks until all registered threads have completed.

Methods inherited from class java.lang.Object

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

Constructor Detail

Application

public Application()

Creates a new Application instance. Subclasses very rarely need put any logic in the constructor, especially not code that creates Swing components. Override one of the various init methods instead which are guaranteed to be invoked on the event dispatching thread.

Throws:

java.lang.IllegalStateException - if an Application has already been created

See Also:

init sequence

Method Detail

getInstance

public static Application getInstance()

Returns the single Application instance.

Returns:

the single Application instance

addApplicationListener

public void addApplicationListener(ApplicationListener listener)

Adds a listener for application events.

Parameters:

listener - the ApplicationListener to add

removeApplicationListener

public void removeApplicationListener(ApplicationListener listener)

Adds a listener for application events.

Parameters:

listener - the ApplicationListener to add

putData

public final void putData(java.lang.Object key,
                          java.lang.Object value)

Associated the specified value with the specified key. This is intended for developers to place application specific data in.

Parameters:

key - the key to store the value in

value - the value to associated with key

getData

public final java.lang.Object getData(java.lang.Object key)

Returns the value for the specified user key.

Parameters:

key - the key used to retrieve the specified value

Returns:

the value for the specified user key

getPreferences

public final java.util.prefs.Preferences getPreferences()

Returns the Preferences object for the Application.

Returns:

the Preferences object for the Application

See Also:

getPreferencesKey()

getPreferencesKey

protected java.lang.Class getPreferencesKey()

Returns the Class key used to fetch the Preferences object. This implementation returns the Application class.

Returns:

the key used to fetch the Preferences object

See Also:

getPreferences()

getResourceBundle

public final java.util.ResourceBundle getResourceBundle()

Returns the ResourceBundle for the Application. The ResourceBundle is loaded using the value returned from getResourceBundleName.

Returns:

the ResourceBundle for the Application

See Also:

getResourceBundleName()

getResourceBundleName

protected java.lang.String getResourceBundleName()

Returns the key for loading the resources for the Application. This implementation returns getClass().getName().resources.Resources.

Returns:

the name used to locate the Applications ResourceBundle

getBackgroundThreadFactory

public java.util.concurrent.ThreadFactory getBackgroundThreadFactory()

Returns a ThreadFactory suitable for threads used within Swing applications. Threads created by the returned ThreadFactory are automatically registered with the Application, are not daemon, and have a priority of Thread.MIN_PRIORITY.

When exit is invoked the Application will block until all background threads have exited.

Returns:

a ThreadFactory suitable for background threads

See Also:

registerThread(java.lang.Thread), waitForBackgroundThreadsToExit()

registerThread

public final void registerThread(java.lang.Thread thread)

Registers a background thread with the Application. When the application exits it will block until all background threads have completed.

This method is thread safe.

Parameters:

thread - the Thread to wait for completion on

Throws:

java.lang.IllegalArgumentException - if thread is null

getName

public abstract java.lang.String getName()

Returns the name of the application.

Returns:

the name of the Application

installLookAndFeel

protected void installLookAndFeel()

Invoked from preInit to set the look and feel for the Application. This implementation sets the look and feel to the system look and feel. If setting the look and feel results in throwing an exception it will be ignored.

See Also:

init sequence

preInit

protected void preInit()

Invoked as part of starting the application. This method invokes installLookAndFeel. See init sequence for details on when this is invoked.

See Also:

installLookAndFeel()

init

protected void init()

Invoked as part of starting the application. See init sequence for details on when this is invoked.

postInit

protected void postInit()

Invoked as part of starting the application. See init sequence for details on when this is invoked.

postInitEventQueueEmpty

protected void postInitEventQueueEmpty()

Invoked as part of starting the application. See init sequence for details on when this is invoked.

start

public final void start()

Starts the Application. This method is typically invoked directly from main. Refer to init sequence for details on which methods this invokes.

Throws:

java.lang.IllegalStateException - if start has already been invoked

See Also:

init sequence

canExit

protected boolean canExit()

Returns whether the application should be allowed to exit. This is invoked from exit. A return value of false will stop the application from exiting.

Returns:

whether or not the application should be allowed to exit; this implementation unconditionally returns true

See Also:

exit()

exiting

protected void exiting()

Invoked as part of exiting the application. Refer to exit sequence for details on when this method is invoked.

waitForBackgroundThreadsToExit

protected void waitForBackgroundThreadsToExit()

Blocks until all registered threads have completed. This is invoked from exit. If necessary this method will invoke createBackgroundThreadDialog to create a modal dialog that is shown while waiting for background threads to exit.

See Also:

exit(), createBackgroundThreadDialog()

exit

public final void exit()

Exits the application. Refer to exit sequence for details on which methods this invokes.

See Also:

canExit(), waitForBackgroundThreadsToExit()

uncaughtException

public void uncaughtException(java.lang.Throwable throwable)

Invoked when an uncaught exception is encountered. This invokes the method of the same name with the calling thread as an argument.

Parameters:

throwable - the thrown exception

uncaughtException

public void uncaughtException(java.lang.Thread thread,
                              java.lang.Throwable throwable)

Invoked when an uncaught exception is encountered. This will show a modal dialog alerting the user, and exit the app. This does not invoke exit.

Specified by:

uncaughtException in interface java.lang.Thread.UncaughtExceptionHandler

Parameters:

thread - the thread the exception was thrown on

throwable - the thrown exception

See Also:

getUncaughtExceptionDialog()

getUncaughtExceptionDialog

protected javax.swing.JDialog getUncaughtExceptionDialog()

Returns the dialog that is shown when an uncaught exception is encountered.

Returns:

dialog to show when an uncaught exception is encountered

See Also:

uncaughtException(java.lang.Throwable)

createBackgroundThreadDialog

protected javax.swing.JDialog createBackgroundThreadDialog()

Returns the dialog to show when waiting for any background threads to exit. The returned dialog must be modal.

Returns:

dialog to shown when waiting for background threads to exit