com.jgoodies.uif.application
Class Application

java.lang.Object
  extended by com.jgoodies.binding.beans.Model
      extended by com.jgoodies.uif.application.Application
All Implemented Interfaces:
com.jgoodies.binding.beans.Observable, Serializable
Direct Known Subclasses:
AbstractUIFApplication

public abstract class Application
extends com.jgoodies.binding.beans.Model

A base class for Swing applications. It addresses the following issues:

TODO: Consider registering the application as UncaughtExceptionHandler. If an uncaught exception is encountered, the application shall be able to handle it, for example it could show a message dialog or shut down the application.

Since:
1.8
Version:
$Revision: 1.22 $
Author:
Karsten Lentzsch
See Also:
Serialized Form

Constructor Summary
protected Application()
           
 
Method Summary
 void addExitListener(ExitListener listener)
          Adds an ExitListener that observes changes in the application state.
static void clearActionMap(Object target)
          Clears the ActionMap cache entry for the given target.
protected  void end()
          Called by the exit(EventObject) default implementation to terminate the application.
 void exit()
          Shuts down this application by calling exit(null).
 void exit(EventObject event)
          Notifies registered exit listeners that the application is exiting, then shuts down the application by calling shutdown().
 boolean exitAllowed(EventObject event)
          Checks and answers if the application is allowed to exit.
protected  void fireApplicationExiting()
          Fires an event that indicates that the application is about to exit.
static Action getAction(Object target, String actionName)
          Returns the action named actionName of the given target object.
static ActionMap getActionMap(Object target)
          Returns the ActionMap for the given target.
 WindowListener getApplicationExitOnWindowClosingHandler()
          Lazily creates and returns a handler that invokes Application#exit() on the window closing event.
static ResourceMap getResourceMap(Class<?> type)
          Returns the ResourceMap for the given type.
static void launch(Class<? extends Application> appClass, String... args)
          Instantiates the given Application class, initializes the ApplicationContext by setting the Application instance, then invokes #startup with the given arguments.
 void removeExitListener(ExitListener listener)
          Removes the given ExitListener.
protected  void shutdown()
          Performs cleanup tasks when the application exits.
protected abstract  void startup(String[] args)
          Starts this application when the application is launched.
 
Methods inherited from class com.jgoodies.binding.beans.Model
addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, equals, fireIndexedPropertyChange, fireIndexedPropertyChange, fireIndexedPropertyChange, fireMultiplePropertiesChanged, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, getVetoableChangeListeners, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Application

protected Application()
Method Detail

getAction

public static Action getAction(Object target,
                               String actionName)
Returns the action named actionName of the given target object. Equivalent to: Application.getActionMap(target).get(actionName).

Note: Requesting an Action will create a hard reference to the given target, so it cannot be cleared by the garbage collector until the ActionMap entry is cleared using clearActionMap(Object).

Parameters:
target - the instance that will perform the Action
actionName - used to look up the associated Action method
Returns:
the Action for name actionName of the given target.
Throws:
IllegalArgumentException - if the action is absent.
Since:
1.9.1

getActionMap

public static ActionMap getActionMap(Object target)
Returns the ActionMap for the given target. Equivalent to: ApplicationContext.getInstance().getActionMap(target).

Note: Requesting an ActionMap will create a hard reference to the given target, so it cannot be cleared by the garbage collector until the ActionMap entry is cleared using clearActionMap(Object).

Parameters:
target - the object that shall execute the Actions
Returns:
an ActionMap with Actions that perform the target's action methods.
Since:
1.9.1
See Also:
ApplicationContext.getActionMap(Object)

clearActionMap

public static void clearActionMap(Object target)
Clears the ActionMap cache entry for the given target. Used to avoid memory leaks when the target isn't required anymore.

Parameters:
target - the key in the ActionMap cache
Throws:
NullPointerException - if target is null
Since:
1.9.1

getResourceMap

public static ResourceMap getResourceMap(Class<?> type)
Returns the ResourceMap for the given type. Equivalent to: ApplicationContext.getInstance().getResourceMap(type).

Parameters:
type - a class to lookup resources for
Returns:
the type's class or package resource map - if available and type is not null - otherwise this application's resource map
See Also:
ApplicationContext.getResourceMap(Class)

launch

public static void launch(Class<? extends Application> appClass,
                          String... args)
Instantiates the given Application class, initializes the ApplicationContext by setting the Application instance, then invokes #startup with the given arguments. Typically this method is called from an application's #main method.

Parameters:
appClass - the class of the application to launch
args - optional launch arguments, often the the main method's arguments.
See Also:
shutdown(), ApplicationContext.setApplication(Application)

startup

protected abstract void startup(String[] args)
Starts this application when the application is launched. A typical application creates and shows the GUI in this method. This method runs on the event dispatching thread.

Called by the static launch method.

See Also:
launch(Class, String[]), shutdown()

shutdown

protected void shutdown()
Performs cleanup tasks when the application exits. This default implementation does nothing; subclasses may override. This method runs on the event dispatching thread.

See Also:
startup(String[]), exit(EventObject), addExitListener(ExitListener)

exit

public final void exit()
Shuts down this application by calling exit(null). This version of #exit() is intended if the application exit wasn't triggered by an event. Consequently exit listeners lack the optional event object useful to open dialogs at the right position or screen.

See Also:
exit(EventObject), shutdown(), addExitListener(ExitListener), removeExitListener(ExitListener)

exit

public void exit(EventObject event)
Notifies registered exit listeners that the application is exiting, then shuts down the application by calling shutdown(). If an exit listener vetoes against the exit, this method does nothing.

Exceptions thrown during the exit listener notification and during the shutdown are logged only.

The optional event object is useful for exit listeners that show a dialog; these can use the event object to determine on which screen the dialog shall pop up.

Parameters:
event - an optional EventObject that triggered the shutdown
See Also:
exit(), shutdown(), addExitListener(ExitListener), removeExitListener(ExitListener)

end

protected void end()
Called by the exit(EventObject) default implementation to terminate the application. This default end implementation just invokes System.exit(0), which terminates the currently running Java Virtual Machine.

Subclasses may want to override this default behavior to enable multiple Applications running in a JVM, or to let the JVM continue to run after an Application end, for example if the Application is an IDE plug-in.

Since:
1.9.1
See Also:
exit(EventObject)

exitAllowed

public final boolean exitAllowed(EventObject event)
Checks and answers if the application is allowed to exit. Notifies all exit listeners so they can veto against exiting.

Parameters:
event - an optional event that provides the (event) source that originated the application exit, useful when opening a dialog that asks the user whether the exit is allowed or not
Returns:
true if no one vetoed against the exit, false if someone vetoed against the exit

addExitListener

public final void addExitListener(ExitListener listener)
Adds an ExitListener that observes changes in the application state.

Parameters:
listener - the ExitListener to add
Throws:
IllegalArgumentException - if the listener is null

removeExitListener

public final void removeExitListener(ExitListener listener)
Removes the given ExitListener.

Parameters:
listener - the ExitListener to remove
Throws:
IllegalArgumentException - if the listener is null

fireApplicationExiting

protected final void fireApplicationExiting()
Fires an event that indicates that the application is about to exit. Allows interested parties to perform operations before the shutdown.


getApplicationExitOnWindowClosingHandler

public final WindowListener getApplicationExitOnWindowClosingHandler()
Lazily creates and returns a handler that invokes Application#exit() on the window closing event.

Returns:
a handler that exits the application on the window closing event.


Copyright © 2000-2008 JGoodies Karsten Lentzsch. All Rights Reserved.