Package org.jdesktop.application

# Class Application

java.lang.Object
org.jdesktop.application.AbstractBean
org.jdesktop.application.Application

Direct Known Subclasses:
  `SingleFrameApplication`

@ProxyActions({"cut","copy","paste","delete"}) public abstract class Application extends AbstractBean
The base class for Swing applications.

This class defines a simple lifecyle for Swing applications: `initialize`, `startup`, `ready`, and `shutdown`. The `Application's` `startup` method is responsible for creating the initial GUI and making it visible, and the `shutdown` method for hiding the GUI and performing any other cleanup actions before the application exits. The `initialize` method can be used configure system properties that must be set before the GUI is constructed and the `ready` method is for applications that want to do a little bit of extra work once the GUI is "ready" to use. Concrete subclasses must override the `startup` method.

Applications are started with the static `launch` method. Applications use the `ApplicationContext` `getContext()` to find resources, actions, local storage, and so on.

All `Application` subclasses must override `startup` and they should call `exit()` (which calls `shutdown`) to exit. Here's an example of a complete "Hello World" Application:

     public class MyApplication extends Application {
         JFrame mainFrame = null;
         @Override protected void startup() {
             mainFrame = new JFrame("Hello World");
             mainFrame.add(new JLabel("Hello World"));
             mainFrame.addWindowListener(new MainFrameListener());
             mainFrame.setDefaultCloseOperation(JFrame.DO_NOTHING_ON_CLOSE);
             mainFrame.pack();
             mainFrame.setVisible(true);
         }
         @Override protected void shutdown() {
             mainFrame.setVisible(false);
         }
         private class MainFrameListener extends WindowAdapter {
             public void windowClosing(WindowEvent e) {
                exit();
             }
         }
         public static void main(String[] args) {
             Application.launch(MyApplication.class, args);
         }
     }

The `mainFrame's` `defaultCloseOperation` is set to `DO_NOTHING_ON_CLOSE` because we're handling attempts to close the window by calling `ApplicationContext` `exit()`.

Simple single frame applications like the example can be defined more easily with the `SingleFrameApplication` `Application` subclass.

All of the Application's methods are called (must be called) on the EDT.

All but the most trivial applications should define a ResourceBundle in the resources subpackage with the same name as the application class (like `resources/MyApplication.properties`). This ResourceBundle contains resources shared by the entire application and should begin with the following the standard Application resources:

     Application.name = A short name, typically just a few words
     Application.id = Suitable for Application specific identifiers, like file names
     Application.title = A title suitable for dialogs and frames
     Application.version = A version string that can be incorporated into messages
     Application.vendor = A proper name, like Sun Microsystems, Inc.
     Application.vendorId = suitable for Application-vendor specific identifiers, like file names.
     Application.homepage = A URL like http://www.javadesktop.org
     Application.description =  One brief sentence
     Application.lookAndFeel = either system, default, or a LookAndFeel class name

The `Application.lookAndFeel` resource is used to initialize the `UIManager lookAndFeel` as follows:

- `system` - the system (native) look and feel
- `default` - use the JVM default, typically the cross platform look and feel
- `nimbus` - use the modern cross platform look and feel Nimbus
- a LookAndFeel class name - use the specified class

Author:
  Hans Muller (Hans.Muller@Sun.COM)
See Also:
  - `SingleFrameApplication`
  - `ApplicationContext`
  - `UIManager.setLookAndFeel(javax.swing.LookAndFeel)`

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static interface`
`Application.ExitListener`
Gives the Application a chance to veto an attempt to exit/quit.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`KEY_APPLICATION_ICON`
`static final String`
`KEY_APPLICATION_TITLE`
`static final String`
`KEY_APPLICATION_VENDOR_ID`
`protected boolean`
`ready`

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`Application()`
Not to be called directly, see `launch`.

## Method Summary

Modifier and Type
Method
Description
`void`
`addExitListener(Application.ExitListener listener)`
Adds an `ExitListener` to the list.
`protected void`
`end()`
Called by `exit` to terminate the application.
`final void`
`exit()`
Gracefully shutdowns the application, calls `exit(null)` This version of exit() is convenient if the decision to exit the application wasn't triggered by an event.
`void`
`exit(EventObject event)`
Gracefully shutdowns the application.
`final ApplicationContext`
`getContext()`
The ApplicationContext for this Application.
`Application.ExitListener[]`
`getExitListeners()`
All of the `ExitListeners` added so far.
`static Application`
`getInstance()`
The `Application` singleton.
`static <T extends Application>
T`
`getInstance(Class<T> applicationClass)`
The `Application` singleton.
`boolean`
`handleQuit()`
Handles quit even on Mac Os X Developer should not use it directly
`void`
`hide(View view)`
Hides the application `View`
`protected void`
`initialize(String[] args)`
Responsible for initializations that must occur before the GUI is constructed by `startup`.
`boolean`
`isReady()`
The state of the initial UI.
`static <T extends Application>
void`
`launch(Class<T> applicationClass, String[] args)`
Creates an instance of the specified `Application` subclass, sets the `ApplicationContext` `application` property, and then calls the new `Application's` `initialize` and `startup` methods.
`void`
`quit(ActionEvent e)`
The default `Action` for quitting an application, `quit` just exits the application by calling `exit(e)`.
`protected void`
`ready()`
Called after the startup() method has returned and there are no more events on the `system event queue`.
`void`
`removeExitListener(Application.ExitListener listener)`
Removes an `ExitListener` from the list.
`void`
`show(View view)`
Shows the application `View`
`protected void`
`shutdown()`
Called when the application `exits`.
`protected abstract void`
`startup()`
Responsible for starting the application; for creating and showing the initial GUI.

### Methods inherited from class org.jdesktop.application.AbstractBean

`addPropertyChangeListener, addPropertyChangeListener, firePropertyChange, firePropertyChange, getPropertyChangeListeners, removePropertyChangeListener, removePropertyChangeListener`

### Methods inherited from class java.lang.Object

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

## Field Details

### KEY_APPLICATION_TITLE

public static final String KEY_APPLICATION_TITLE

See Also:
  - Constant Field Values

### KEY_APPLICATION_ICON

public static final String KEY_APPLICATION_ICON

See Also:
  - Constant Field Values

### KEY_APPLICATION_VENDOR_ID

public static final String KEY_APPLICATION_VENDOR_ID

See Also:
  - Constant Field Values

### ready

protected boolean ready

## Constructor Details

### Application

protected Application()
Not to be called directly, see `launch`.

Subclasses can provide a no-args construtor to initialize private final state however GUI initialization, and anything else that might refer to public API, should be done in the `startup` method.

## Method Details

### launch

public static <T extends Application> void launch(Class<T> applicationClass, String[] args)
Creates an instance of the specified `Application` subclass, sets the `ApplicationContext` `application` property, and then calls the new `Application's` `initialize` and `startup` methods. When UI is ready, method `ready` is called. The `launch` method is typically called from the Application's `main`:

         public static void main(String[] args) {
             Application.launch(MyApplication.class, args);
         }

The `applicationClass` constructor and `startup` methods run on the event dispatching thread.

Parameters:
  `applicationClass` - the `Application` class to launch
  `args` - `main` method arguments
See Also:
  - `shutdown()`
  - `ApplicationContext.getApplication()`

### initialize

protected void initialize(String[] args)
Responsible for initializations that must occur before the GUI is constructed by `startup`.

This method is called by the static `launch` method, before `startup` is called. Subclasses that want to do any initialization work before `startup` must override it. The `initialize` method runs on the event dispatching thread.

By default initialize() does nothing.

Parameters:
  `args` - the main method's arguments.
See Also:
  - `launch(java.lang.Class<T>, java.lang.String[])`
  - `startup()`
  - `shutdown()`

### startup

protected abstract void startup()
Responsible for starting the application; for creating and showing the initial GUI.

This method is called by the static `launch` method, subclasses must override it. It runs on the event dispatching thread.

See Also:
  - `launch(java.lang.Class<T>, java.lang.String[])`
  - `initialize(java.lang.String[])`
  - `shutdown()`

### ready

protected void ready()
Called after the startup() method has returned and there are no more events on the `system event queue`. When this method is called, the application's GUI is ready to use.

It's usually important for an application to start up as quickly as possible. Applications can override this method to do some additional start up work, after the GUI is up and ready to use.

See Also:
  - `launch(java.lang.Class<T>, java.lang.String[])`
  - `startup()`
  - `shutdown()`

### shutdown

protected void shutdown()
Called when the application `exits`. Subclasses may override this method to do any cleanup tasks that are necessary before exiting. Obviously, you'll want to try and do as little as possible at this point. This method runs on the event dispatching thread.

See Also:
  - `startup()`
  - `ready`
  - `exit()`
  - `addExitListener(org.jdesktop.application.Application.ExitListener)`

### exit

public final void exit()
Gracefully shutdowns the application, calls `exit(null)` This version of exit() is convenient if the decision to exit the application wasn't triggered by an event.

See Also:
  - `exit(EventObject)`

### handleQuit

public boolean handleQuit()
Handles quit even on Mac Os X Developer should not use it directly

Returns:
  always `true`

### exit

public void exit(EventObject event)
Gracefully shutdowns the application.

If none of the `ExitListener.canExit()` methods return false, calls the `ExitListener.willExit()` methods, then `shutdown()`, and then exits the Application with `end`. Exceptions thrown while running willExit() or shutdown() are logged but otherwise ignored.

If the caller is responding to an GUI event, it's helpful to pass the event along so that ExitListeners' canExit methods that want to popup a dialog know on which screen to show the dialog. For example:

     class ConfirmExit implements Application.ExitListener {
         public boolean canExit(EventObject e) {
             Object source = (e != null) ? e.getSource() : null;
             Component owner = (source instanceof Component) ? (Component)source : null;
             int option = JOptionPane.showConfirmDialog(owner, "Really Exit?");
             return option == JOptionPane.YES_OPTION;
         }
         public void willExit(EventObejct e) {}
     }
     myApplication.addExitListener(new ConfirmExit());

The `eventObject` argument may be null, e.g. if the exit call was triggered by non-GUI code, and `canExit`, `willExit` methods must guard against the possibility that the `eventObject` argument's `source` is not a `Component`.

Parameters:
  `event` - the EventObject that triggered this call or null
See Also:
  - `addExitListener(org.jdesktop.application.Application.ExitListener)`
  - `removeExitListener(org.jdesktop.application.Application.ExitListener)`
  - `shutdown()`
  - `end()`

### end

protected void end()
Called by `exit` to terminate the application. Calls `Runtime.getRuntime().exit(0)`, which halts the JVM.

See Also:
  - `exit()`

### addExitListener

public void addExitListener(Application.ExitListener listener)
Adds an `ExitListener` to the list.

Parameters:
  `listener` - the `ExitListener`
See Also:
  - `removeExitListener(org.jdesktop.application.Application.ExitListener)`
  - `getExitListeners()`

### removeExitListener

public void removeExitListener(Application.ExitListener listener)
Removes an `ExitListener` from the list.

Parameters:
  `listener` - the `ExitListener`
See Also:
  - `addExitListener(org.jdesktop.application.Application.ExitListener)`
  - `getExitListeners()`

### getExitListeners

public Application.ExitListener[] getExitListeners()
All of the `ExitListeners` added so far.

Returns:
  all of the `ExitListeners` added so far.

### quit

@Action public void quit(ActionEvent e)
The default `Action` for quitting an application, `quit` just exits the application by calling `exit(e)`.

Parameters:
  `e` - the triggering event
See Also:
  - `exit(EventObject)`

### getContext

public final ApplicationContext getContext()
The ApplicationContext for this Application.

Returns:
  the Application's ApplicationContext

### getInstance

public static <T extends Application> T getInstance(Class<T> applicationClass)
The `Application` singleton.

This method is only called after an Application has been launched.

Parameters:
  `applicationClass` - this Application's subclass
Returns:
  the launched Application singleton.
See Also:
  - `launch(java.lang.Class<T>, java.lang.String[])`

### getInstance

public static Application getInstance()
The `Application` singleton.

This method is only called after an Application has been launched.

Returns:
  the Application singleton or a placeholder
See Also:
  - `launch(java.lang.Class<T>, java.lang.String[])`
  - `getInstance(Class)`

### show

public void show(View view)
Shows the application `View`

Parameters:
  `view` - - View to show
See Also:
  - `View`

### hide

public void hide(View view)
Hides the application `View`

Parameters:
  `view` -
See Also:
  - `View`

### isReady

public boolean isReady()
The state of the initial UI.

Returns:
  true if the initial UI is ready