PATH |
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:
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()
public EOController(EOXMLUnarchiver unarchiver)
Static Methods
canAccessFieldsDirectly
public static boolean canAccessFieldsDirectly()
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()
See Also: "Accessing and Enabling Actions" (page 121)
actionWithName
public EOAction actionWithName(String actionName)
null
.
See Also: "Accessing and Enabling Actions" (page 121)
actions
public NSArray actions()
See Also: "Accessing and Enabling Actions" (page 121)
addSubcontroller
public void addSubcontroller(EOController subcontroller)
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.
See Also: "Building the Controller Hierarchy" (page 120)
breakConnection
public void breakConnection()
EOController's implementation is sufficient for most subclasses, so you don't ordinarily override this method.
See Also: "Connecting Controllers" (page 121)
breakConnectionToSubcontrollers
public void breakConnectionToSubcontrollers()
EOController's implementation is sufficient for most subclasses, so you don't ordinarily override this method.
See Also: "Connecting Controllers" (page 121)
canBeTransient
public boolean canBeTransient()
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)
See Also: isActionNamedEnabled, "Accessing and Enabling Actions" (page 121)
connectionWasBroken
protected void connectionWasBroken()
See Also: "Connecting Controllers" (page 121)
connectionWasEstablished
protected void connectionWasEstablished()
See Also: "Connecting Controllers" (page 121)
controllerEnumeration
public EOController.Enumeration controllerEnumeration( int enumerationType, Class controllerInterface)
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:
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)
See Also: controllerEnumeration
controllersWithKeyValuePair
public NSArray controllersWithKeyValuePair( int enumerationType, Class controllerInterface, String key, Object value)
See Also: "Traversing the Controller Hierarchy" (page 120), controllerEnumeration
controllersWithKeyValuePairs
public NSArray controllersWithKeyValuePairs( int enumerationType, Class controllerInterface, NSDictionary keyValuePairs)
See Also: "Traversing the Controller Hierarchy" (page 120), controllerEnumeration
controllerWithKeyValuePair
public EOController controllerWithKeyValuePair( int enumerationType, Class controllerInterface, String key, Object value)
See Also: "Traversing the Controller Hierarchy" (page 120), controllerEnumeration
controllerWithKeyValuePairs
public EOController controllerWithKeyValuePairs( int enumerationType, Class controllerInterface, NSDictionary keyValuePairs)
See Also: "Traversing the Controller Hierarchy" (page 120), controllerEnumeration
defaultActions
protected NSArray defaultActions()
See Also: "Accessing and Enabling Actions" (page 121)
disableActionNamed
public void disableActionNamed(String actionName)
See Also: "Accessing and Enabling Actions" (page 121)
disposableRegistry
public NSDisposableRegistry disposableRegistry()
dispose
public void dispose()
disposeIfTransient
protected boolean disposeIfTransient()
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.
See Also: "Transience" (page 122), removeTransientSubcontroller
enableActionNamed
public void enableActionNamed(String actionName)
See Also: "Accessing and Enabling Actions" (page 121)
enabledActions
public NSArray enabledActions()
See Also: "Accessing and Enabling Actions" (page 121)
establishConnection
public void establishConnection()
EOController's implementation is sufficient for most subclasses, so you don't ordinarily override this method.
See Also: "Connecting Controllers" (page 121)
establishConnectionToSupercontrollers
public void establishConnectionToSupercontrollers()
EOController's implementation is sufficient for most subclasses, so you don't ordinarily override this method.
See Also: "Connecting Controllers" (page 121)
handleQueryWithUnboundKey
public Object handleQueryWithUnboundKey(String key)
handleTakeValueForUnboundKey
public void handleTakeValueForUnboundKey( Object value, String key)
hierarchicalControllerForKey
public EOController hierarchicalControllerForKey( Class controllerInterface, String key)
null
value for key. Returns that controller or null
if none of the controllers have a non-null
value for key.
See Also: "Traversing the Controller Hierarchy" (page 120), controllerEnumeration
hierarchicalValueForKey
public Object hierarchicalValueForKey( Class controllerInterface, String key)
null
value for key. Returns the value or null
if none of the controllers have a non-null
value for key.
See Also: "Traversing the Controller Hierarchy" (page 120), controllerEnumeration
invokeMethod
public void invokeMethod( int enumerationType, Class controllerInterface, String methodName, Class[] parameterTypes[], Object[] parameters[])
See Also: "Traversing the Controller Hierarchy" (page 120), controllerEnumeration
isActionNamedEnabled
public boolean isActionNamedEnabled(String actionName)
true
if the action specified by actionName isn't specifically disabled, false
otherwise.
See Also: "Accessing and Enabling Actions" (page 121)
isAncestorOfController
public boolean isAncestorOfController(EOController controller)
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()
true
if the receiver is connected, false
otherwise.
See Also: "Connecting Controllers" (page 121)
isSupercontrollerOfController
public boolean isSupercontrollerOfController(EOController controller)
true
if controller is an immediate subcontroller of the receiver, false
otherwise.
prepareForNewTask
public void prepareForNewTask(boolean prepareSubcontrollersForNewTask)
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()
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.
See Also: "Building the Controller Hierarchy" (page 120)
removeSubcontroller
protected void removeSubcontroller(EOController subcontroller)
See Also: "Building the Controller Hierarchy" (page 120)
removeTransientSubcontroller
protected boolean removeTransientSubcontroller(EOController subcontroller)
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()
See Also: "Accessing and Enabling Actions" (page 121)
setConnected
protected void setConnected(boolean flag)
See Also: "Connecting Controllers" (page 121)
setSupercontroller
protected boolean setSupercontroller(EOController controller)
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.
See Also: "Building the Controller Hierarchy" (page 120)
setTypeName
public void setTypeName(String typeName)
See Also: "Rule System and XML Description" (page 122)
subcontrollers
public NSArray subcontrollers()
subcontrollerWasAdded
protected void subcontrollerWasAdded(EOController subcontroller)
See Also: "Building the Controller Hierarchy" (page 120)
subcontrollerWasRemoved
protected void subcontrollerWasRemoved(EOController subcontroller)
See Also: "Building the Controller Hierarchy" (page 120)
supercontroller
public EOController supercontroller()
null
if the receiver has no supercontroller.
public EOController supercontroller(Class controllerInterface)
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)
takeValueForKeyPath
public void takeValueForKeyPath( Object value, String keyPath)
toString
public String toString()
typeName
public String typeName()
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.
See Also: "Rule System and XML Description" (page 122)
unableToSetNullForKey
public void unableToSetNullForKey(String key)
valueForKey
public Object valueForKey(String key)
valueForKeyPath
public Object valueForKeyPath(String keyPath)
© 2001 Apple Computer, Inc. (Last Published April 14, 2001)