com.webobjects.eoapplication
Class EOApplication

java.lang.Object
  com.webobjects.eoapplication.EOController
      com.webobjects.eoapplication.EOApplication

All Implemented Interfaces:

EOAction.Enabling, NSDisposable, NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions

Direct Known Subclasses:

EODynamicApplication

public class EOApplication

extends EOController

Java Client applications typically execute as a desktop application (often referred to as a "Java application"), launched through Web Start or through a command line or as an applet running in a browser. EOApplication insulates the developer from this distinction by serving as an execution-mode-independent repository for application-level client-side logic. The provided JApplet subclass EOApplet simply invokes EOApplication with the HTML arguments as parameters.

To support different kind of architectures, EOApplication uses an "application support" object which has to be a subclass of the abstract inner class EOApplication.ApplicationSupport. The application support implementation can encapsulate different kind of initialization behavior, for example for three-tier Java Client applications the creation of a distribution channel is taken care of by the EOClientApplicationSupport class. EOApplication does not provide a main function, that is left to the application support class. The main function typically invokes the static startApplication method on EOApplication with an instance of the appropriate application support class.

Each application has a window observer which keeps track of all of the windows in the application, which window is active, and whether all windows have been closed. The window observer has two notifications: ActiveWindowChangedNotification and LastWindowClosedNotification, which the finishInitialization method binds to the activeWindowDidChange and lastWindowDidClose methods, respectively.

Each application also has a defaults manager, an EODefaults object, which maintains two dictionaries for application defaults: a transient dictionary whose values are forgotten when the application exits, and a persistent dictionary whose values are stored on the server. The defaults manager implements valueForKey to read the defaults and setPersistentValueForKey and setTransientValueForKey to store the defaults.

Nested Class Summary

static class

EOApplication.ApplicationSupport EOApplication.ApplicationSupport can encapsulate behavior of Java Client applications used in different architectures.

Nested classes inherited from class com.webobjects.eoapplication.EOController

EOController.Enumeration

Nested classes inherited from class com.webobjects.foundation.NSKeyValueCoding

NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.Utility, NSKeyValueCoding.ValueAccessor

Nested classes inherited from class com.webobjects.foundation.NSKeyValueCodingAdditions

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Field Summary

static String	ApplicationDidStartNotification The name of the notification sent when the application did finish the launch sequence.
static String	ApplicationWillFinishInitializationNotification The name of the notification sent when the application has switched to the final event thread.
static String	ApplicationWillQuitNotification The name of the notification sent when the application is about to quit.
static String	ApplicationWillStartNotification The name of the notification sent when the application is beginning the launch sequence.

Fields inherited from class com.webobjects.eoapplication.EOController

ControllerAndSubcontrollersEnumeration, ControllerAndSupercontrollersEnumeration, SubcontrollersEnumeration, SupercontrollersEnumeration

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

EOApplication()
Creates a new EOApplication object.

Method Summary

void	activeWindowDidChange(NSNotification notification) This method is invoked when the user changes the active window in the receiver (usually by clicking in an inactive window).
String	applicationName() Returns the receiver's application name.
NSDictionary	arguments() Returns all of the application's arguments in a dictionary.
boolean	canQuit() Returns whether or not the application can quit (shows a Quit menu item).
protected NSArray	defaultActions() Returns an NSArray containing the actions (EOAction objects) for the application.
EODefaults	defaults() Returns the receiver's defaults manager (an EODefaults object).
void	dispose() Prepares the receiver so it is disposed when Java performs garbage collection.
NSArray	documents() Returns an array containing the application's visible documents (EODocument controllers).
NSArray	documentsForGlobalID(EOGlobalID globalID, String entityName) Returns an array containing the application's documents (EODocument controllers) that edit enterprise objects with an entity name matching entityName and a global ID matching globalID.
NSArray	editedDocuments() Returns an NSArray containing the application's documents (EODocument controllers) that are edited (and not saved).
protected void	finishInitialization() This method is invoked after the final event thread is guaranteed to be running.
boolean	hasEditedDocuments() Returns whether any of the application's documents (EODocument controllers) are edited (and not saved).
NSArray	languages() Returns an array containing the preferred display language lookup order for the user (in English).
void	lastWindowDidClose(NSNotification notification) This method is invoked when the user closes the last window in the application.
NSArray	localeIndicators() Returns an array of Strings which can be used to identify the preferred locale/language for the user.
NSArray	locales() Returns an array containing the preferred Locale lookup order for the user.
NSArray	platformIndicators() Returns an array of Strings (all lowercase) which can be used to identify the platform the application is running on.
void	quit() Causes the receiver to quit (provided canQuit is true).
boolean	quitsOnLastWindowClose() Returns whether or not the receiver quits when the user closes all of its windows.
void	quitWithMessage(String title, String message) Can be invoked to quit the application after showing a panel with an explanation (for example in case of a Session Time Out error for a three-tier application).
void	refreshData() Updates the client application's enterprise objects to reflect the changes sent to the server from other client applications.
boolean	saveAll() Attempts to save all of the receiver's edited documents.
void	setApplicationName(String applicationName) Sets the receiver's application name.
static void	setArguments(NSDictionary arguments) Sets the application's arguments.
void	setCanQuit(boolean flag) Sets whether or not the application can quit (shows a Quit menu item).
void	setDefaults(EODefaults defaults) Sets the receiver's defaults manager (an EODefaults object).
void	setQuitsOnLastWindowClose(boolean flag) Sets whether or not the receiver quits when the user closes all of its windows.
void	setWindowObserver(EOWindowObserver windowObserver) Sets the application's window observer to EOWindowObserver.
static EOApplication	sharedApplication() Returns the shared EOApplication instance initialized in the startApplication method.
static EOApplication	startApplication(NSDictionary parameters, EOComponentController initialTopComponentController, EOApplication.ApplicationSupport applicationSupport) This method is the primary entry point for starting a Java Client application.
String	toString() Returns the receiver as a string describing the state of the application.
EOWindowObserver	windowObserver() Returns the application's window observer.

Methods inherited from class com.webobjects.eoapplication.EOController

actionNames, actions, actionWithName, additionalActions, additionalKeyValuePairs, addSubcontroller, breakConnection, breakConnectionToSubcontrollers, canAccessFieldsDirectly, canBeTransient, canPerformActionNamed, connectionWasBroken, connectionWasEstablished, controllerEnumeration, controllersInEnumeration, controllersWithKeyValuePair, controllersWithKeyValuePairs, controllerWithKeyValuePair, controllerWithKeyValuePairs, disableActionNamed, disposableRegistry, disposeIfTransient, enableActionNamed, enabledActions, establishConnection, establishConnectionToSupercontrollers, handleQueryWithUnboundKey, handleTakeValueForUnboundKey, hierarchicalControllerForKey, hierarchicalValueForKey, invokeMethod, isActionNamedEnabled, isAncestorOfController, isConnected, isSupercontrollerOfController, isTransientExplicitlyForbidden, prepareForNewTask, removeFromSupercontroller, removeSubcontroller, removeTransientSubcontroller, resetActions, setAdditionalActions, setAdditionalKeyValuePair, setAdditionalKeyValuePairs, setConnected, setSupercontroller, setTransientExplicitlyForbidden, setTypeName, subcontrollers, subcontrollerWasAdded, subcontrollerWasRemoved, supercontroller, supercontroller, takeValueForKey, takeValueForKeyPath, typeName, unableToSetNullForKey, valueForKey, valueForKeyPath

Methods inherited from class java.lang.Object

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

Field Detail

ApplicationDidStartNotification

public static final String ApplicationDidStartNotification

The name of the notification sent when the application did finish the launch sequence.

ApplicationWillFinishInitializationNotification

public static final String ApplicationWillFinishInitializationNotification

The name of the notification sent when the application has switched to the final event thread. User interface related initializations should be performed after this notification was sent.

ApplicationWillQuitNotification

public static final String ApplicationWillQuitNotification

The name of the notification sent when the application is about to quit.

ApplicationWillStartNotification

public static final String ApplicationWillStartNotification

The name of the notification sent when the application is beginning the launch sequence.

Constructor Detail

EOApplication

public EOApplication()

Creates a new EOApplication object.

Method Detail

activeWindowDidChange

public void activeWindowDidChange(NSNotification notification)

This method is invoked when the user changes the active window in the receiver (usually by clicking in an inactive window). It is invoked via a notification from the application's window observer.

Parameters:

notification - the window observer notification

applicationName

public String applicationName()

Returns the receiver's application name.

Returns:

the application name

arguments

public NSDictionary arguments()

Returns all of the application's arguments in a dictionary. If the application is a desktop application (and not an applet), the arguments can come from both the command line and the WOJavaClientApplet on the server side.

Returns:

the application's arguments

canQuit

public boolean canQuit()

Returns whether or not the application can quit (shows a Quit menu item). Defaults to true if the application is run as a desktop application and false if it runs as an applet.

Returns:

true if the application can quit; false otherwise

defaultActions

protected NSArray defaultActions()

Returns an NSArray containing the actions (EOAction objects) for the application. The application object's actions are displayed in the main menu of the Java Client application.

Overrides:

defaultActions in class EOController

Returns:

the array of actions

See Also:

EOController.actions(), EOController.resetActions()

defaults

public EODefaults defaults()

Returns the receiver's defaults manager (an EODefaults object). If your application requires the user to log in, you may override this method so it returns null until the user has authenticated.

Returns:

the application's default manager

dispose

public void dispose()

Prepares the receiver so it is disposed when Java performs garbage collection.

Specified by:

dispose in interface NSDisposable

Overrides:

dispose in class EOController

documents

public NSArray documents()

Returns an array containing the application's visible documents (EODocument controllers).

Returns:

an array of the application's visible documents

documentsForGlobalID

public NSArray documentsForGlobalID(EOGlobalID globalID,
                                    String entityName)

Returns an array containing the application's documents (EODocument controllers) that edit enterprise objects with an entity name matching entityName and a global ID matching globalID.

Parameters:

globalID - the global ID for the documents

entityName - the entity name for the documents

Returns:

an array of documents matching the entity name and global ID

editedDocuments

public NSArray editedDocuments()

Returns an NSArray containing the application's documents (EODocument controllers) that are edited (and not saved).

Returns:

an array of the application's edited documents

finishInitialization

protected void finishInitialization()

This method is invoked after the final event thread is guaranteed to be running. If you subclass EOApplication, use this method to initialize anything relating to the user interface or event handling. Do not perform such initialization using EOApplication's constructor.

hasEditedDocuments

public boolean hasEditedDocuments()

Returns whether any of the application's documents (EODocument controllers) are edited (and not saved). Otherwise returns false.

Returns:

true if the application has edited documents; false otherwise

languages

public NSArray languages()

Returns an array containing the preferred display language lookup order for the user (in English). Examples for display languages: "English", "German".

Returns:

the application's languages

lastWindowDidClose

public void lastWindowDidClose(NSNotification notification)

This method is invoked when the user closes the last window in the application. It is invoked as a notification from the receiver's window observer. Usually causes the application to quit.

Parameters:

notification - the window observer notification

See Also:

quitsOnLastWindowClose()

localeIndicators

public NSArray localeIndicators()

Returns an array of Strings which can be used to identify the preferred locale/language for the user. The various indicators are a mixture of different representations, for example "en_US", "en", "English".

Returns:

the application's locale indicators

locales

public NSArray locales()

Returns an array containing the preferred Locale lookup order for the user.

Returns:

the application's locales

platformIndicators

public NSArray platformIndicators()

Returns an array of Strings (all lowercase) which can be used to identify the platform the application is running on. Examples: "macos", "windows".

Returns:

the application's platform indicators

quit

public void quit()

Causes the receiver to quit (provided canQuit is true).

See Also:

canQuit()

quitWithMessage

public void quitWithMessage(String title,
                            String message)

Can be invoked to quit the application after showing a panel with an explanation (for example in case of a Session Time Out error for a three-tier application).

Parameters:

title - the title of the panel to be displayed

message - the message to be displayed in the panel

quitsOnLastWindowClose

public boolean quitsOnLastWindowClose()

Returns whether or not the receiver quits when the user closes all of its windows. Defaults to true.

Returns:

true if the application quits if the user closes all windows; false otherwise

refreshData

public void refreshData()

Updates the client application's enterprise objects to reflect the changes sent to the server from other client applications. By default, the application does not automatically update its objects, however, the user can usually update the objects manually from the Document menu.

saveAll

public boolean saveAll()

Attempts to save all of the receiver's edited documents.

Returns:

true if the save was successful; false otherwise

setApplicationName

public void setApplicationName(String applicationName)

Sets the receiver's application name.

Parameters:

applicationName - the application name

setArguments

public static void setArguments(NSDictionary arguments)

Sets the application's arguments. This method might be useful for application support objects when arguments are read in from different locations.

Parameters:

arguments - the application's arguments

setCanQuit

public void setCanQuit(boolean flag)

Sets whether or not the application can quit (shows a Quit menu item).

Parameters:

flag - true if the application can quit; false otherwise

setDefaults

public void setDefaults(EODefaults defaults)

Sets the receiver's defaults manager (an EODefaults object).

Parameters:

defaults - the application's default manager

setQuitsOnLastWindowClose

public void setQuitsOnLastWindowClose(boolean flag)

Sets whether or not the receiver quits when the user closes all of its windows.

Parameters:

flag - true if the application quits if the user closes all windows; false otherwise

setWindowObserver

public void setWindowObserver(EOWindowObserver windowObserver)

Sets the application's window observer to EOWindowObserver. The window observer manages the application's windows: Which window is active, how many there are, etc.

Parameters:

windowObserver - the window observer

sharedApplication

public static EOApplication sharedApplication()

Returns the shared EOApplication instance initialized in the startApplication method.

Returns:

the shared application object

startApplication

public static EOApplication startApplication(NSDictionary parameters,
                                             EOComponentController initialTopComponentController,
                                             EOApplication.ApplicationSupport applicationSupport)

This method is the primary entry point for starting a Java Client application. Together with the finishInitialization method it performs the complete startup sequence (connect to the server, warm up the user interface, determine languages, etc.)

The parameters dictionary contains all client parameters known at the time this method is invoked. For applets, these are all values of the WOJavaClientApplet bindings on the server side, passed in the HTML. For applications, these are all command line arguments.

The initialTopComponentController parameter can specify an EOComponentController in the controller hierarchy which becomes the parent controller for the intial EOInterfaceController if one is specified. For applets, this controller is an EOAppletController. For desktop applications, this is null, which causes a new EOFrameController to be instantiated and used as the top-most EOComponentController.

Parameters:

parameters - the parameters for the application

initialTopComponentController - the parent component controller for initial interface controllers

applicationSupport - the support object handling the details of the startup process

Returns:

the shared application object created while executing this method

toString

public String toString()

Returns the receiver as a string describing the state of the application.

Overrides:

toString in class EOController

Returns:

the String representation of the receiver

windowObserver

public EOWindowObserver windowObserver()

Returns the application's window observer.

Returns:

the application's window observer