Java 6 SE Platform
6.0
Home

com.woven_media.colorsafe
Class Application

java.lang.Object
  extended by com.woven_media.colorsafe.Application
All Implemented Interfaces:
java.lang.Thread.UncaughtExceptionHandler
Direct Known Subclasses:
App

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

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

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.
static java.lang.String getResourceAsString(java.lang.String key)
          Convenience method to return a resource from the Application as a String.
 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.
static boolean isOSX()
          Returns true if running on Apple's OS X.
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

getResourceAsString

public static java.lang.String getResourceAsString(java.lang.String key)
Convenience method to return a resource from the Application as a String.

Parameters:
key - the key identifying the resource to obtain
Returns:
the resource as a String

isOSX

public static boolean isOSX()
Returns true if running on Apple's OS X.

Returns:
true if running on Apple's OS X

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

Java 6 SE Platform
6.0
Home

JavaDoc API documentation written, prepared and compiled by Brent Allen Parrish, woven-media.com, 20 SEPT 2009