one.gui
Class Application

java.lang.Object
  |
  +--one.world.core.Component
        |
        +--one.gui.Application

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

Chat, Clock, Counter2, Emcee, Ping, RemoteCounter

public class Application

extends Component

Implementation of an application's main component. This class serves as a userful base class for building one.world applications with a Swing UI.

An application has three states. In the inactive state, it is not running. In the activating state, the application has received an activated, moved, cloned, or restored environment event and is acquiring the resources it requires to run. Finally, in the active state, an application is showing its main window and reacting to user input.

The state transition from the inactive to the activating state is performed by the main exported event handler, which starts the resource acquisition process by invoking acquire(). The state transition from the activating to the active state is performed by the start() method. Finally, the state transition from the active to the inactive state is performed by the stop(boolean) method, which relies on release() to release an application's resources.

Subclasses typically need to override only the acquire() and release() methods to manage an application's resources and the createMainWindow() method to create the application's main window.

Version:

$Revision: 1.11 $

See Also:

Serialized Form

Inner Class Summary

static class

Application.Window Implementation of an application's main window.

Inner classes inherited from class one.world.core.Component

Component.HandlerReference, Component.Importer

Field Summary

static int	ACTIVATING The flag for the activating status.
static int	ACTIVE The flag for the active status.
String	appName The name of this application.
int	height The height of the main window.
static int	INACTIVE The flag for the inactive status.
int	locationX The x coordinate for the main window location.
int	locationY The y coordinate for the main window location.
Object	lock The lock protecting the application's internal state.
EventHandler	main The main exported event handler.
Application.Window	mainWindow The application's main window.
Operation	operation The application's main operation.
Component.Importer	request The request imported event handler.
int	status The application's current status.
Timer	timer The timer for this application.
int	width The width of the main window.

Constructor Summary

Application(Environment env)
Create a new application in the specified environment.

Method Summary

void	acquire() Acquire the resources needed by this application.
EventHandler	createMainHandler() Create the main exported event handler.
Application.Window	createMainWindow() Create the application's main window.
ComponentDescriptor	getDescriptor() Get the component descriptor.
static void	init(Environment env, Object closure) Initialize an application.
void	release() Release all resources.
void	signalError(String msg) Signal an error condition to the user.
void	start() Start the application.
void	stop(boolean notify) Stop the application.

Methods inherited from class one.world.core.Component

declareExported, declareImported, equals, eventHandlers, getDescriptor, getEnvironment, getLinkedHandlers, getLinkedNumber, getTimer, hasEventHandler, hashCode, isFullyLinked, isLinked, isSealed, link, link, run, seal, unbox, undeclare, unlink, wrap

Methods inherited from class java.lang.Object

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

Field Detail

INACTIVE

public static final int INACTIVE

The flag for the inactive status.

ACTIVATING

public static final int ACTIVATING

The flag for the activating status.

ACTIVE

public static final int ACTIVE

The flag for the active status.

appName

public String appName

The name of this application. This field is initialized to the application's class name (without the package name).

main

public final EventHandler main

The main exported event handler. This field is automatically initialized when the application is created.

request

public final Component.Importer request

The request imported event handler. This field is automatically initialized when the application is created.

timer

public final Timer timer

The timer for this application. This field is automatically initialized to the environment's timer when the application is created.

locationX

public volatile int locationX

The x coordinate for the main window location. This field is automatically updated as the application's main window is moved across the screen.

locationY

public volatile int locationY

The y coordinate for the main window location. This field is automatically updated as the application's main window is moved across the screen.

width

public volatile int width

The width of the main window. This field is automatically updated as the application's main window is resized.

height

public volatile int height

The height of the main window. This field is automatically updated as the application's main window is resized.

status

public transient int status

The application's current status. The value of this field must be either INACTIVE, ACTIVATING, or ACTIVE. Access to this field must be synchronized by the application's lock. Upon deserialization of an application, this field is restored to the inactive state.

lock

public transient Object lock

The lock protecting the application's internal state. This field is automatically initialized when the application is created and when it is deserialized.

See Also:

status

mainWindow

public transient Application.Window mainWindow

The application's main window. This field is initialized to the application's main window by start() and set to null again by stop(boolean).

operation

public transient Operation operation

The application's main operation.

Constructor Detail

Application

public Application(Environment env)

Create a new application in the specified environment.

Parameters:

env - The environment.

Method Detail

createMainHandler

public EventHandler createMainHandler()

Create the main exported event handler.

The default implementation returns an event handler that handles activated, restored, moved, cloned, and stop environment events. On an activated, restored, moved, or cloned environment event, the returned event handler enters the activating state and then invokes acquire(). On a stop environment event, the returned event handler, invokes stop(false) and then responds to the stop environment event with a stopped environment event.

Returns:

The main exported event handler

See Also:

EnvironmentEvent

getDescriptor

public ComponentDescriptor getDescriptor()

Get the component descriptor.

This method returns a component descriptor suitable for thread-safe applications. Subclasses are encouraged to overwrite this method, as the descriptor returned by this method uses the name of this component. However, they need not do so, because the component name is not currently utilized. Note that UI-based applications must be thread-safe, because Swing UI events are generated by a thread separate from all one.world threads.

Overrides:

getDescriptor in class Component

Following copied from class: one.world.core.Component

Returns:

The component descriptor for this component.

acquire

public void acquire()

Acquire the resources needed by this application. This method starts the process of acquiring the resources needed by this application and is usually invoked by the main exported event handler after entering the activating state.

An application must be prepared to stop while it is still acquiring the resources it needs. It can detect whether it has been concurrently stopped by checking for the inactive state.

The default implementation directly transitions to the active state by calling start().

start

public void start()

Start the application. This method completes the process of resource acquisition and displays the application's main window at the current location.

The default implementation creates a new main window, transitions to the active state, and then displays the window (if it is not null). Calling this method has no effect, if this application is not in the activating state or already has a main window.

Applications typically need not override this method.

See Also:

locationX, locationY, createMainWindow()

stop

public void stop(boolean notify)

Stop the application. This method stops the application by closing the application's main window and by releasing its resources.

The default implementation transitions to the inactive state, closes the application's main window, releases all resources by calling release(), and, if specified, notifies the application's environment of having stopped, all while holding the application's lock. Calling this method has no effect, if the application already is in the inactive state.

Applications typically need not override this method.

Parameters:

notify - The flag for whether to notify this application's environment of having stopped.

release

public void release()

Release all resources. This method releases all resources held by this application and is typically invoked by stop(boolean) after transitioning to the inactive state and closing the main window, while holding the application's lock.

An application must be prepared for the fact that not all of its resource have been acquired.

The default implementation does nothing.

createMainWindow

public Application.Window createMainWindow()

Create the application's main window. This method is called by start() to create the application's main window. It can return null if the application does not have a main window. This method should only create the main window, but not make it visible.

The default implementation creates an empty window, titled "Main Window", with the current width and height.

Returns:

The application's main window, or null if the application does not have a main window.

signalError

public void signalError(String msg)

Signal an error condition to the user. This method displays an error dialog box with the specified message to the user, if the application is not inactive. It only returns after the user has dismissed the dialog box. This method is thread-safe and must be called outside the application's lock.

Parameters:

msg - The error message.

init

public static void init(Environment env,
                        Object closure)

Initialize an application. The resulting application handles environment events and displays an empty, resizable window.

Parameters:

env - The environment.

closure - The closure, which is ignored.