WebObjects 5.4.2

com.webobjects.eoapplication
Class EOApplication

java.lang.Object
  extended by com.webobjects.eoapplication.EOController
      extended by 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/interfaces inherited from class com.webobjects.eoapplication.EOController
EOController.Enumeration
 
Nested classes/interfaces inherited from interface 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.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

ApplicationWillStartNotification

public static final String ApplicationWillStartNotification
The name of the notification sent when the application is beginning the launch sequence.

See Also:
Constant Field Values

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.

See Also:
Constant Field Values

ApplicationDidStartNotification

public static final String ApplicationDidStartNotification
The name of the notification sent when the application did finish the launch sequence.

See Also:
Constant Field Values

ApplicationWillQuitNotification

public static final String ApplicationWillQuitNotification
The name of the notification sent when the application is about to quit.

See Also:
Constant Field Values
Constructor Detail

EOApplication

public EOApplication()
Creates a new EOApplication object.

Method Detail

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

sharedApplication

public static EOApplication sharedApplication()
Returns the shared EOApplication instance initialized in the startApplication method.

Returns:
the shared application object

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

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

saveAll

public boolean saveAll()
Attempts to save all of the receiver's edited documents.

Returns:
true if the save was successful; false otherwise

quit

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

See Also:
EOApplication.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

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.


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

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

setDefaults

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

Parameters:
defaults - the application's default manager

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

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

locales

public NSArray locales()
Returns an array containing the preferred Locale lookup order for the user.

Returns:
the application's locales

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

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

documents

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

Returns:
an array of the application's visible documents

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

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

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

setApplicationName

public void setApplicationName(String applicationName)
Sets the receiver's application name.

Parameters:
applicationName - the application name

applicationName

public String applicationName()
Returns the receiver's application name.

Returns:
the application name

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

windowObserver

public EOWindowObserver windowObserver()
Returns the application's window observer.

Returns:
the application's window observer

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.


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

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

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

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

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

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:
EOApplication.quitsOnLastWindowClose()

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

Last updated June 2008

Copyright © 2000-2008 Apple Inc.