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.


Nested Class Summary
private  class Application.Handler
           
private  class Application.NotifyingPaintEvent
           
private static class Application.SwingThreadFactory
           
 
Field Summary
private static Application APPLICATION
           
private  java.util.List<ApplicationListener> appListeners
           
private static boolean checkedOS
           
private  java.util.Map<java.lang.Object,java.lang.Object> data
           
private static boolean isOSX
           
private  java.util.prefs.Preferences preferences
           
private  java.util.ResourceBundle resources
           
private static int RUN_POST_INIT_EVENT_QUEUE_EMPTY
           
private static int RUN_START_ON_EDT
           
private static int RUN_WAIT_EVENTS
           
private static int RUN_WAIT_FOR_BACKGROUND_THREADS
           
private  boolean started
           
private  java.util.concurrent.ThreadFactory threadFactory
           
private  java.util.List<java.lang.ref.WeakReference<java.lang.Thread>> threads
           
private  java.lang.Throwable throwable
           
private static int UNCAUGHT_EXCEPTION
           
 
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.
private  void fireApplicationDidInit()
           
private  void fireApplicationExiting()
           
 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.
private  boolean listenersCanExit()
           
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.
private  void startOnEDT()
           
 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.
private  void uncaughtException0()
           
protected  void waitForBackgroundThreadsToExit()
          Blocks until all registered threads have completed.
private  boolean waitForBackgroundThreadsToExit(long maxWaitTime)
           
private  void waitForBackgroundThreadsToExitInBackground(javax.swing.JDialog dialog)
           
private  void waitForEmptyEventQ()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

APPLICATION

private static Application APPLICATION

RUN_POST_INIT_EVENT_QUEUE_EMPTY

private static final int RUN_POST_INIT_EVENT_QUEUE_EMPTY
See Also:
Constant Field Values

RUN_START_ON_EDT

private static final int RUN_START_ON_EDT
See Also:
Constant Field Values

RUN_WAIT_EVENTS

private static final int RUN_WAIT_EVENTS
See Also:
Constant Field Values

UNCAUGHT_EXCEPTION

private static final int UNCAUGHT_EXCEPTION
See Also:
Constant Field Values

RUN_WAIT_FOR_BACKGROUND_THREADS

private static final int RUN_WAIT_FOR_BACKGROUND_THREADS
See Also:
Constant Field Values

checkedOS

private static boolean checkedOS

isOSX

private static boolean isOSX

throwable

private java.lang.Throwable throwable

threadFactory

private java.util.concurrent.ThreadFactory threadFactory

threads

private java.util.List<java.lang.ref.WeakReference<java.lang.Thread>> threads

started

private boolean started

preferences

private java.util.prefs.Preferences preferences

resources

private java.util.ResourceBundle resources

data

private java.util.Map<java.lang.Object,java.lang.Object> data

appListeners

private java.util.List<ApplicationListener> appListeners
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

startOnEDT

private void startOnEDT()

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.


listenersCanExit

private boolean listenersCanExit()

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()

waitForBackgroundThreadsToExitInBackground

private void waitForBackgroundThreadsToExitInBackground(javax.swing.JDialog dialog)

waitForBackgroundThreadsToExit

private boolean waitForBackgroundThreadsToExit(long maxWaitTime)

fireApplicationExiting

private void fireApplicationExiting()

fireApplicationDidInit

private void fireApplicationDidInit()

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)

uncaughtException0

private void uncaughtException0()

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

waitForEmptyEventQ

private void waitForEmptyEventQ()

Java 6 SE Platform
6.0
Home

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