EOController

Inherits from:
Object

Implements:
NSDisposable
NSKeyValueCodingAdditions
EOAction.Enabling
NSKeyValueCoding.ErrorHandling
NSKeyValueCoding

Package:
com.webobjects.eoapplication

Class Description

The EOController class defines basic behavior for controller objects that are responsible for managing and sometimes generating the user interface for the client side of a Java Client application. An application's controllers are arranged in a hierarchy, which describes the complete functionality of an application.

The controller hierarchy mirrors the hierarchy of windows and widgets that make up the client application's user interface. The root of the hierarchy is an EOApplication object. The EOApplication's subcontrollers are usually window or applet controllers, which themselves have subcontrollers.

The most significant functionality provided by the EOController class is managing the controller hierarchy (building, connecting, and traversing the hierarchy) and handling actions.

Building the Controller Hierarchy

EOController defines methods for building the controller hierarchy. You can add and remove controllers ( addSubcontroller, removeFromSupercontroller), be notified when the controller hierarchy changes ( subcontrollerWasAdded and subcontrollerWasRemoved), and inquire about the relationships controllers have to one another ( subcontrollers, supercontroller, isAncestorOfController, and isSupercontrollerOfController).

You might need to directly invoke the methods addSubcontroller and removeFromSupercontroller to programmatically manipulate the controller hierarchy. The base implementations of these methods are sufficient for most subclasses. They set and unset a controller's supercontroller ( setSupercontroller) and notify that supercontroller that a subcontroller was added or removed.

If you write a custom controller and you need to do something special when a subcontroller is added to or removed from the controller hierarchy, override the methods subcontrollerWasAdded and subcontrollerWasRemoved to put your customizations there. Taking this approach, you shouldn't have to override the add and remove methods.

Traversing the Controller Hierarchy

EOController defines numerous methods for traversing the controller hierarchy, but a single method provides the basic traversal functionality. The method controllerEnumeration creates and returns an enumeration that includes all the descendents of a controller (not including the controller), all the ancestors of a controller (not including the controller), or a controller and its descendants. You can further restrict the controllers included in an enumeration by specifying an interface the controllers must implement in order to be included. For more information, see the EOController.Enumeration interface specification and the method description for controllerEnumeration.

Other methods that traverse the controller hierarchy use a controller enumeration to perform the traversal. There are methods that return controllers in an enumeration that match one or more key-value pairs. Methods that use key-value coding on the controllers in an enumeration, returning the first controller that has a specified key or returning the value for that key. Also, there's a method ( invokeMethod) that invokes a particular method on the controllers in an enumeration.

Connecting Controllers

A controller in the controller hierarchy can be connected to its supercontroller or not. Controllers are connected when they're performing their duties, and they are disconnected when they become idle. Generally controllers are connected only when their user interface is visible. For example, the controllers associated with a window are connected when the window is visible, and they're disconnected when the window becomes invisible.

When a controller connects to its supercontroller, it gets from its supercontroller whatever resources or information it needs, and it prepares itself in whatever way necessary to perform its duties (for example, setting delegates). Similarly, when a controller breaks its connection to its supercontroller, it cleans up its resources for an idle period.

The EOController class defines methods for connecting controllers. There are methods for connecting and disconnecting a controller from its supercontroller ( establishConnection and breakConnection), and also methods that make connections all the way up the controller hierarchy ( establishConnectionToSupercontrollers) and break connections all the way down ( breakConnectionToSubcontrollers). Generally you use the latter methods that connect or disconnect an entire branch of a tree. EOController's implementations of all these methods is generally sufficient for subclasses. They set the connection status of a controller ( setConnected), and notify the controller that its connection has been established or broken. You shouldn't have to override these methods.

If you do need to do something when a controller is connected or disconnected, you should override the methods connectionWasEstablished and connectionWasBroken. These methods are invoked automatically by establishConnection and breakConnection.

Accessing and Enabling Actions

Controllers define actions that users can perform (such as quitting the application) and they know how to respond to those actions when they're performed. EOController defines methods that manage a controllers actions.

A controller has a set of actions. It also keeps track of which of those actions are enabled and which are disabled. For performance reasons, EOController's method implementations cache some of this information. Thus, whenever you do something that changes a controller's actions (such as adding a new subcontroller or enabling or disabling an action), the caches must be reset. Most of the time they're reset automatically, but subclasses might need to explicitly reset them with the method resetActions.

To specify the actions a subclass understands, override the method defaultActions. However, to find out what actions a controller understands, use actions. This method simply manages and returns a cache of the methods returned by defaultActions. Some implementations of a defaultActions method are potentially costly to invoke over and over again, because they dynamically build their collections of actions. The actions method is simply an optimization. EOController's implementation of actions should be sufficient for subclasses; you should never need to override it.

To find out what actions a controller can perform at a specific point in time, use the method enabledActions. This method returns only the controller's actions that aren't explicitly disabled. As with actions, enabledActions manages and returns a cache of methods, and EOController's implemenation should be sufficient for subclasses.

Transience

Some controllers are needed only to dynamically generate the user interface and don't serve any purpose after the user interface has been created and connected. For example, an EOTextFieldController creates a widget and a corresponding association and then is no longer needed. Controllers such as EOTextFieldController can be transient, because after their work is done, they can sometimes be removed from the controller hierarchy and disposed of (with disposeIfTransient). This keeps the controller hierarchy simple, which makes user interface management more efficient.

Controllers specify whether or not they can be transient by overriding the method canBeTransient. Some controllers can be transient sometimes and not other times, so not all implementations simply return true or false. For example, an EOTableController can be transient if the double click action is unassigned. If the action is assigned, however, the controller must listen for a double click and react when one occurs.

Subclasses that can be transient should invoke the method disposeIfTransient as soon as their work is done and they can be disposed of. Sometimes a controller's supercontroller doesn't allow the controller to be disposed of. For example, the EOTabSwitchComponent doesn't allow its subcontrollers to be disposed of even if they're transient.

Rule System and XML Description

The following tables identify the controllerType, XML tag, and XML attributes used by the rule system and EOXMLUnarchiver to generate a controller hierarchy. For more information, see the section "Rule System and XML Description" (page 8) in the package introduction.

Default Rule System Controller Type

None

XML Tag

None

XML Attribute	Value	Description
`className`	string	Name of a class to instantiate instead of the default class.
`disabledActionNames`	array of strings	Names of actions to explicitly disable.
`typeName`	string	This is usually a textual representation of the specification used to generate the controller, for example "question = window, task = query". The type name is used by the controller factory to identify which windows are the same so that it can reuse resources. The typeName is also used by the defaults system to specify per-window defaults.

Constants

EOController defines the following int constants to identify types of enumerations returned by the method controllerEnumeration:

Constant	Description
`SubcontrollersEnumeration`	An enumeration object that enumerates over a controller's subcontrollers, not including the controller itself.
`SupercontrollersEnumeration`	An enumeration object that enumerates over a controller's supercontrollers, not including the controller itself.
`ControllerAndSubcontrollersEnumeration`	An enumeration object that enumerates over a controller and its subcontrollers.

Interfaces Implemented

NSDisposable
dispose

NSKeyValueCoding (Inherited from EOKeyValueCoding)
takeValueForKey
valueForKey

EOKeyValueCoding (Inherited from EOKeyValueCodingAdditions)
handleQueryWithUnboundKey
handleTakeValueForUnboundKey
unableToSetNullForKey

EOKeyValueCodingAdditions
takeValueForKeyPath
valueForKeyPath

EOAction.Enabling
canPerformActionNamed

Method Types

Constructors
EOController
Managing the controller hierarchy
addSubcontroller
subcontrollerWasAdded
removeFromSupercontroller
removeSubcontroller
subcontrollerWasRemoved
setSupercontroller
removeTransientSubcontroller
canBeTransient
subcontrollers
supercontroller
isAncestorOfController
isSupercontrollerOfController
Traversing the controller hierarchy
controllerEnumeration
controllersInEnumeration
controllerWithKeyValuePair
controllerWithKeyValuePairs
controllersWithKeyValuePair
controllersWithKeyValuePairs
hierarchicalControllerForKey
hierarchicalValueForKey
invokeMethod
Connecting controllers
establishConnectionToSupercontrollers
establishConnection
connectionWasEstablished
breakConnectionToSubcontrollers
breakConnection
connectionWasBroken
setConnected
isConnected
Accessing and enabling actions
actions
defaultActions
enabledActions
actionWithName
actionNames
disableActionNamed
enableActionNamed
isActionNamedEnabled
resetActions
Reusing controllers
prepareForNewTask
Accessing the type name
typeName
setTypeName
Accessing keys
canAccessFieldsDirectly
Disposing
disposeIfTransient
disposableRegistry
Methods inherited from Object
toString

Constructors

EOController

public EOController()

Description forthcoming.

public EOController(EOXMLUnarchiver unarchiver)

Creates and returns a new controller. The no argument constructor is used when you create a controller programmatically, whereas the version taking an unarchiver is used in a Direct to Java Client applications to create controllers from an XML description. Controller subclasses should implement both constructors. Most commonly, controllers are created with the assistance of an unarchiver. For more information on this unarchiving, see the book Getting Started with Direct to Java Client.

Static Methods

canAccessFieldsDirectly

public static boolean canAccessFieldsDirectly()

Returns true if the receiver accesses its instance variables directly or false otherwise.By default, controllers don't access instance variables directly and return false.

See Also: accessInstanceVariablesDirectly (EOCustomObject)

Instance Methods

actionNames

public NSArray actionNames()

Returns an array of strings naming the actions the controller defines and responds to.

actionWithName

public EOAction actionWithName(String actionName)

If the receiver has an action named actionName, this method returns that action; otherwise, the method returns null.

actions

public NSArray actions()

Returns an array containing the receiver's actions. EOController's implementation caches the result of defaultActions and returns that. The cache is cleared with the method resetActions.

addSubcontroller

public void addSubcontroller(EOController subcontroller)

Adds controller as a subcontroller of the receiver and sets the receiver as controller's supercontroller (first removing controller from it's supercontroller if it already has one). Invoke this method to programmatically add a subcontroller to the hierarchy.

EOController's implementation sets subcontroller's supercontroller and notifies the receiver that a subcontroller was added. It does nothing if controller is a supercontroller of the receiver. The default implantation of this method should be sufficient for most subclasses; you shouldn't have to override it. If you need to do something special when a subcontroller is added, override subcontrollerWasAdded.

breakConnection

public void breakConnection()

Breaks the receiver's connection to its supercontroller. Invokes connectionWasBroken to give the receiver a chance to clean up, and informs all its ancestors that a subcontroller's connections have changed so the ancestors can respond appropriately. Use this method to programmatically disconnect a single controller (and not its subcontrollers).

EOController's implementation is sufficient for most subclasses, so you don't ordinarily override this method.

breakConnectionToSubcontrollers

public void breakConnectionToSubcontrollers()

Breaks the connections the receiver's subcontrollers have to their subcontrollers, and then breaks the receiver's connections to its subcontrollers. This method is invoked recursively down the subcontroller chain until the receiver and all its subcontrollers are disconnected. Use this method to programmatically disconnect a branch of the controller hierarchy from a particular controller down.

EOController's implementation is sufficient for most subclasses, so you don't ordinarily override this method.

canBeTransient

public boolean canBeTransient()

Returns true if the controller can be transient, false otherwise. EOController's implementation returns false.

See Also: "Transience" (page 122)

canPerformActionNamed

public boolean canPerformActionNamed(String actionName)

Conformance to EOAction.Enabling. See the method description of canPerformActionNamed in the interface specification for EOAction.Enabling.

connectionWasBroken

protected void connectionWasBroken()

Invoked from breakConnection to notify the receiver that its connection to its supercontroller has been broken, giving the receiver the opportunity to clean up after its become idle.

connectionWasEstablished

protected void connectionWasEstablished()

Invoked from establishConnection to notify the receiver that its connection to the controller hierarchy has been established, giving the receiver the opportunity to prepare itself (for example, setting delegates).

controllerEnumeration

public EOController.Enumeration controllerEnumeration( int enumerationType, Class controllerInterface)

Returns an enumeration object of the specified type and interface. For example, invoking this method with SubcontrollersEnumeration as the enumerationType and with MyControllerInterface as the controllerInterface returns an enumeration object that returns the receiver's subcontrollers that implement the interface MyControllerInterface. The enumerationType argument can be one of:

SubcontrollersEnumeration
SupercontrollersEnumeration
ControllerAndSubcontrollersEnumeration

The controllerInterface argument can be the name of an interface or null to specify no interface, which returns all the controllers specified by enumerationType.

See Also: "Traversing the Controller Hierarchy" (page 120), EOController.Enumeration interface specification

controllersInEnumeration

public NSArray controllersInEnumeration( int enumerationType, Class controllerInterface)

Returns the controllers in an enumeration specified by enumerationType and controllerInterface.

See Also: controllerEnumeration

controllersWithKeyValuePair

public NSArray controllersWithKeyValuePair( int enumerationType, Class controllerInterface, String key, Object value)

Traverses the controller hierarchy, and returns the controllers in the hierarchy whose values for key match value. This method uses a controller enumeration specified by enumerationType and controllerInterface to find the controllers. The method tests the controllers returned by the enumeration for matches and returns them. Matches are determined with the method valueForKeyPath.

controllersWithKeyValuePairs

public NSArray controllersWithKeyValuePairs( int enumerationType, Class controllerInterface, NSDictionary keyValuePairs)

Traverses the controller hierarchy, and returns the controllers in the hierarchy whose key-value pairs match those specified in keyValuePairs. This method uses a controller enumeration specified by enumerationType and controllerInterface to find the controllers. The method tests the controllers returned by the enumeration for matches and returns them. Matches are determined with the method valueForKeyPath.

controllerWithKeyValuePair

public EOController controllerWithKeyValuePair( int enumerationType, Class controllerInterface, String key, Object value)

Traverses the controller hierarchy, and returns the first controller in the hierarchy whose value for key matches value. This method uses a controller enumeration specified by enumerationType and controllerInterface to find the controller. The method tests the controllers returned by the enumeration for a match and returns the first that it matches. Matches are determined with the method valueForKeyPath.

controllerWithKeyValuePairs

public EOController controllerWithKeyValuePairs( int enumerationType, Class controllerInterface, NSDictionary keyValuePairs)

Traverses the controller hierarchy, and returns the first controller in the hierarchy whose key-value pairs match those specified in keyValuePairs. This method uses a controller enumeration specified by enumerationType and controllerInterface to find the controller. The method tests the controllers returned by the enumeration for a match and returns the first that it matches. Matches are determined with the method valueForKeyPath.

defaultActions

protected NSArray defaultActions()

Returns an array of the receiver's default actions (EOAction objects). A subclass of EOController should override this method to return the action it defines merged with the actions of its supercclass. Never invoke this method directly. Instead, invoke actions, which caches the results of defaultActions and is therefore more efficient.

disableActionNamed

public void disableActionNamed(String actionName)

Disables the action specified by the name actionName and resets the receiver's actions.

disposableRegistry

public NSDisposableRegistry disposableRegistry()

Returns the receiver's disposable registry. This registry contains objects that will be disposed of together with the receiver. Subclasses can use the registry to register objects that should be disposed when their controller is disposed.

dispose

public void dispose()

Conformance to NSDisposable. See the method description of dispose in the interface specification for NSDisposable.

disposeIfTransient

protected boolean disposeIfTransient()

Disposes the receiver if it's transient, first removing it from its supercontroller with removeTransientSubcontroller. Returns true if the receiver is transient and has been disposed, false otherwise. If the receiver's supercontroller is non-null, this method also attempts to dispose of the supercontroller if it's transient.

enableActionNamed

public void enableActionNamed(String actionName)

Enables the action named actionName and resets the receiver's actions.

enabledActions

public NSArray enabledActions()

Returns an array of the receiver's enabled actions-those of the receiver's EOAction objects that aren't explicitly disabled. This method caches the enabled actions to enhance performance. The cache is cleared with the method resetActions.

establishConnection

public void establishConnection()

Connects the receiver to the controller hierarchy. Invokes connectionWasEstablished to give the receiver a chance to ready the user interface. After connecting the receiver, this method disposes of it if it's transient and is therefore no longer needed. Use this method to programmatically connect a single controller (and not its ancestors).

EOController's implementation is sufficient for most subclasses, so you don't ordinarily override this method.

establishConnectionToSupercontrollers

public void establishConnectionToSupercontrollers()

Connects the receiver's supercontroller to the controller hierarchy, and then establishes the receiver's connection to the controller hierarchy. This method is invoked recursively up the supercontroller chain until the receiver and all its ancestors are connected. Use this method to programmatically prepare a branch of the controller hierarchy from a controller up to the root controller.

EOController's implementation is sufficient for most subclasses, so you don't ordinarily override this method.

handleQueryWithUnboundKey

public Object handleQueryWithUnboundKey(String key)

Conformance to EOKeyValueCoding. See the method description of handleQueryWithUnboundKey in the interface specification for EOKeyValueCoding.

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey( Object value, String key)

Conformance to EOKeyValueCoding. See the method description of handleTakeValueForUnboundKey in the interface specification for EOKeyValueCoding.

hierarchicalControllerForKey

public EOController hierarchicalControllerForKey( Class controllerInterface, String key)

Starting at the receiver, searches up the controller hierarchy for the first controller that implements controllerInterface and has a non-null value for key. Returns that controller or null if none of the controllers have a non-null value for key.

hierarchicalValueForKey

public Object hierarchicalValueForKey( Class controllerInterface, String key)

Starting at the receiver, searches up the controller hierarchy for the first controller that implements controllerInterface and has a non-null value for key. Returns the value or null if none of the controllers have a non-null value for key.

invokeMethod

public void invokeMethod( int enumerationType, Class controllerInterface, String methodName, Class[] parameterTypes[], Object[] parameters[])

Traverses the controller hierarchy, invoking the method specified by methodName and parameterTypes on the appropriate controllers. This method uses a controller enumeration specified by enumerationType and controllerInterface to find the controllers on which to invoke the specified method. For each controller in the enumeration, this method invokes the methodName method with the values in parameters as arguments to the method.

isActionNamedEnabled

public boolean isActionNamedEnabled(String actionName)

Returns true if the action specified by actionName isn't specifically disabled, false otherwise.

isAncestorOfController

public boolean isAncestorOfController(EOController controller)

Returns true if controller is a subcontroller of the receiver, of the receiver's subcontrollers, or their subcontrollers, and so on; false otherwise.

isConnected

public boolean isConnected()

Returns true if the receiver is connected, false otherwise.

isSupercontrollerOfController

public boolean isSupercontrollerOfController(EOController controller)

Returns true if controller is an immediate subcontroller of the receiver, false otherwise.

prepareForNewTask

public void prepareForNewTask(boolean prepareSubcontrollersForNewTask)

Prepares the receiver for performing a new task by resetting any data. If prepareSubcontrollersForNewTask is true, this method also sends prepareForNewTask to each of the receiver's subcontrollers. This method is invoked to prepare a branch of the controller hierarchy to be reused. Subclasses should override this method to get rid of data and perform any additional clean up.

removeFromSupercontroller

public void removeFromSupercontroller()

Removes the receiver from its supercontroller's set of subcontrollers. Invoke this method when you need to programmatically remove a controller from the controller hierarchy.

EOController's implementation simply invokes removeSubcontroller on the receiver's supercontroller. This method is a convenience so you don't have to look up a controller's supercontroller. The default implementation should be sufficient for subclasses; you shouldn't have to override it.

removeSubcontroller

protected void removeSubcontroller(EOController subcontroller)

Removes subcontroller from the controller hierarchy. EOController's implementation disconnects subcontroller from the controller hierarchy, and invokes subcontrollerWasRemoved on the receiver to give the receiver a chance to respond appropriately. Never invoke this method directly; use removeFromSupercontroller instead. The default implementation should be sufficient for subclasses; you shouldn't have to override it. If you need to do something when a subcontroller is removed, implement subcontrollerWasRemoved.

removeTransientSubcontroller

protected boolean removeTransientSubcontroller(EOController subcontroller)

Removes subcontroller from the controller hierarchy if subcontroller can be transient and if the receiver allows it. Returns true if the subcontroller could be removed, false otherwise. This method is invoked from disposeIfTransient, which is invoked in various situations to remove controllers as soon as they can become transient.

See Also: "Transience" (page 122)

resetActions

public void resetActions()

Destroys the receiver's cache of actions and enabled actions, and destroys the action caches of the receiver's supercontrollers. This method is generally invoked automatically when the receiver's set of actions changes or when an action's enabled state is changed, but you can invoke it yourself to clear the caches as needed. EOController's implementation of this method is sufficient for most subclasses. You shouldn't have to override it.

setConnected

protected void setConnected(boolean flag)

Sets the receiver's connected status according to flag. EOController's implementation is sufficient for most subclasses; you don't normally override this method. Nor should you ever need to invoke it; establishConnection and breakConnection set the controller's connection status automatically.

setSupercontroller

protected boolean setSupercontroller(EOController controller)

Sets the receiver's supercontroller to controller and resets the receiver's actions. Returns true on success or false otherwise. It fails if controller is unacceptable as the receiver's supercontroller. Also, controller can be null to unset the receiver's supercontroller.

EOController's implementation is sufficient for most subclasses; you don't normally override this method. Nor should you ever need to invoke it; addSubcontroller sets the supercontroller automatically.

setTypeName

public void setTypeName(String typeName)

Sets the receiver's type name to typeName.

subcontrollers

public NSArray subcontrollers()

Returns the receiver's immediate subcontrollers. Use controllerEnumeration of controllersInEnumeration to return all the controllers in the hierarchy under the receiver.

subcontrollerWasAdded

protected void subcontrollerWasAdded(EOController subcontroller)

Invoked from addSubcontroller to notify the receiver that its subcontroller subcontroller has been added to the controller hierarchy, giving the receiver the opportunity to prepare the subcontroller for use.

subcontrollerWasRemoved

protected void subcontrollerWasRemoved(EOController subcontroller)

Invoked from removeSubcontroller to notify the receiver that its subcontroller subcontroller has been removed from the controller hierarchy, giving the receiver the opportunity to perform any necessary clean up.

supercontroller

public EOController supercontroller()

Returns the receiver's supercontroller, or null if the receiver has no supercontroller.

public EOController supercontroller(Class controllerInterface)

Searching from the receiver's immediate supercontroller, returns the first supercontroller that implements the interface controllerInterface. Returns null if the receiver has no supercontroller or if none of the supercontrollers implement controllerInterface. Returns the receiver's immediate supercontroller if controllerInterface is null.

takeValueForKey

public void takeValueForKey( Object value, String key)

Conformance to NSKeyValueCoding. See the method description of valueForKey in the interface specification for NSKeyValueCoding.

takeValueForKeyPath

public void takeValueForKeyPath( Object value, String keyPath)

Conformance to EOKeyValueCodingAdditions (com.webobjects.eocontrol). See the method description of takeValueForKeyPath in the interface specification for EOKeyValueCodingAdditions.

toString

public String toString()

Returns the receiver as a string that states the receiver's class name and type name, whether the receiver is connected, and the number of subcontrollers.

typeName

public String typeName()

Returns the receiver's type name-a string that uniquely identifies the receiver as a node in the controller hierarchy. EOController's implementation returns null. The type name is used to identify controllers that have the same task. It is used to configure a controller with user defaults and also to reuse controllers when possible.