com.webobjects.eoapplication
Class EOController

java.lang.Object
  |
  +--com.webobjects.eoapplication.EOController

All Implemented Interfaces:

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

Direct Known Subclasses:

EOApplication, EOComponentController

public abstract class EOController

extends Object

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

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.

Constructors

All controller classes need to implement the no-argument constructor. In addition, if they may be instantiated from an XML description, they need to implement a constructor taking a single EOXMLUnarchiver argument. The no-argument constructor is used for all programmatic creation of controllers.

Controllers should avoid complex initialization procedures in the constructor. Instead they should attempt to create all the objects they need to perform their task lazily, only when they are needed. Controllers are usually used in various types of situations and there is no guarantee that they are ever used, even if they are in the controller hierarchy. For example the user interface managed by a controller might be placed in a tab view and never be activated by the user. By creating objects and user interfaces lazily, the response time of average applications gets much better.

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 subcontrollers of a controller (not including the controller), all the supercontrollers of a controller (not including the controller), or a controller and its subcontrollers. 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 and 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 or saving a document) 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 usually 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 become transient.

Inner Class Summary

static interface

EOController.Enumeration EOController.Enumeration is an interface that defines an enumeration that iterates over a set of EOController objects.

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

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

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

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Field Summary

static int	ControllerAndSubcontrollersEnumeration The constant describing enumerations that enumerate over a controller and its subcontrollers.
static int	ControllerAndSupercontrollersEnumeration The constant describing enumerations that enumerate over a controller's supercontrollers, not including the controller itself.
static int	SubcontrollersEnumeration The constant describing enumerations that enumerate over a controller's subcontrollers, not including the controller itself.
static int	SupercontrollersEnumeration The constant describing enumerations that enumerate over a controller's supercontrollers, not including the controller itself.

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

EOController()
Creates a new controller.

EOController(EOXMLUnarchiver unarchiver)
Creates a new controller.

Method Summary

NSArray	actionNames() Returns an array of action method names the controller defines and responds to.
NSArray	actions() Returns a cached array containing the receiver's actions.
EOAction	actionWithName(String actionName) If the receiver has an action for a method with name actionName, this method returns that action; otherwise, the method returns null.
NSArray	additionalActions() Returns actions to be added to the controllers default actions.
NSDictionary	additionalKeyValuePairs() Returns an NSDictionary of additional key-value pairs used by handleQueryWithUnboundKey().
void	addSubcontroller(EOController controller) Adds controller as a subcontroller of the receiver and sets the receiver as controller's supercontroller - first removing controller from its supercontroller if it already has one.
void	breakConnection() Breaks the receiver's connection to its supercontroller.
void	breakConnectionToSubcontrollers() Breaks the connections the receiver's subcontrollers have to their subcontrollers, and then breaks the receiver's connections to its subcontrollers.
static boolean	canAccessFieldsDirectly() Conformance to NSKeyValueCoding.
boolean	canBeTransient() Returns whether the controller can be transient.
boolean	canPerformActionNamed(String actionName) Returns true if the receiver can perform the action method (sent by an EOAction object) named actionName, false otherwise.
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.
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).
EOController.Enumeration	controllerEnumeration(int enumerationType, Class controllerInterface) Returns an EOController.Enumeration object you can use to traverse the controller hierarchy.
NSArray	controllersInEnumeration(int enumerationType, Class controllerInterface) Returns all the controllers in an enumeration as an array.
NSArray	controllersWithKeyValuePair(int enumerationType, Class controllerInterface, String key, Object value) Traverses the controller hierarchy, and returns all controllers in the hierarchy whose value for key matches value.
NSArray	controllersWithKeyValuePairs(int enumerationType, Class controllerInterface, NSDictionary keyValuePairs) Traverses the controller hierarchy, and returns all controllers in the hierarchy which match all key/value pairs in keyValuePairs.
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.
EOController	controllerWithKeyValuePairs(int enumerationType, Class controllerInterface, NSDictionary keyValuePairs) Traverses the controller hierarchy, and returns the first controller in the hierarchy which matches all key-value pairs in keyValuePairs.
protected NSArray	defaultActions() Returns an array of the receiver's default actions (EOAction objects).
void	disableActionNamed(String actionName) Explicitly disables the action method actionName and resets the receiver's actions.
NSDisposableRegistry	disposableRegistry() Returns the receiver's disposable registry.
void	dispose() Prepares the receiver so it is disposed when Java performs garbage collection.
protected boolean	disposeIfTransient() Disposes the receiver if it's transient, first removing it from its supercontroller with removeTransientSubcontroller If the receiver's supercontroller is non-null, this method also attempts to dispose of the supercontroller if it's transient.
void	enableActionNamed(String actionName) Enables the action method actionName and resets the receiver's actions.
NSArray	enabledActions() Returns an array of the receiver's actions which are not explicitly disabled.
void	establishConnection() Connects the receiver to the controller hierarchy.
void	establishConnectionToSupercontrollers() Connects the receiver's supercontroller to the controller hierarchy, and then establishes the receiver's connection to the controller hierarchy.
Object	handleQueryWithUnboundKey(String key) Invoked from valueForKey when it finds no property binding for key.
void	handleTakeValueForUnboundKey(Object value, String key) Invoked from takeValueForKey when it finds no property binding for key.
EOController	hierarchicalControllerForKey(Class controllerInterface, String key) Starting at the receiver, searches up the controller hierarchy for the first controller that implements the interface controllerInterface and has a non-null value for key and returns that controller.
Object	hierarchicalValueForKey(Class controllerInterface, String key) Starting at the receiver, searches up the controller hierarchy for the first controller that implements the interface controllerInterface and has a non-null value for key and returns that value.
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.
boolean	isActionNamedEnabled(String actionName) Returns whether the action method actionName isn't explicitly disabled.
boolean	isAncestorOfController(EOController controller) Returns whether controller is a subcontroller of the receiver, of the receiver's subcontrollers, or their subcontrollers, and so on.
boolean	isConnected() Returns the receiver's connection status.
boolean	isSupercontrollerOfController(EOController controller) Returns whether controller is a direct subcontroller of the receiver.
protected boolean	isTransientExplicitlyForbidden() Returns whether transience is explicitly forbidden for this controller.
void	prepareForNewTask(boolean prepareSubcontrollersForNewTask) Prepares the receiver for performing a new task by resetting any data.
void	removeFromSupercontroller() Removes the receiver from its supercontroller's set of subcontrollers.
protected void	removeSubcontroller(EOController controller) Removes controller from the controller hierarchy.
protected boolean	removeTransientSubcontroller(EOController controller) Removes controller from the controller hierarchy if controller can be transient and if the receiver allows it.
void	resetActions() Destroys the receiver's cache of actions and enabled actions, and destroys the action caches of the receiver's supercontrollers.
void	setAdditionalActions(NSArray additionalActions) Sets actions to be added to the controllers default actions.
void	setAdditionalKeyValuePair(Object value, String key) Adds value to the dictionary of additionalKeyValuePairs with key.
void	setAdditionalKeyValuePairs(NSDictionary dictionary) Sets NSDictionary, dictionary, of key-value pairs for use in handleQueryWithUnboundKey()
protected void	setConnected(boolean flag) Sets the receiver's connection status.
protected boolean	setSupercontroller(EOController controller) Sets the receiver's supercontroller to controller and resets the receiver's actions.
protected void	setTransientExplicitlyForbidden(boolean flag) Sets whether transience is explicitly forbidden for this controller.
void	setTypeName(String typeName) Sets the receiver's type name.
NSArray	subcontrollers() Returns the receiver's direct subcontrollers.
protected void	subcontrollerWasAdded(EOController controller) Invoked from addSubcontroller to notify the receiver that a subcontroller has been added to the controller hierarchy, giving the receiver the opportunity to prepare the subcontroller for use.
protected void	subcontrollerWasRemoved(EOController controller) Invoked from removeSubcontroller to notify the receiver that a subcontroller has been removed from the controller hierarchy, giving the receiver the opportunity to perform any necessary clean up.
EOController	supercontroller() Returns the receiver's supercontroller, or null if the receiver has no supercontroller.
EOController	supercontroller(Class controllerInterface) Searching from the receiver's direct supercontroller, returns the first supercontroller that implements the interface controllerInterface.
void	takeValueForKey(Object value, String key) Conformance to NSKeyValueCoding.
void	takeValueForKeyPath(Object value, String keyPath) Sets the value for the property identified by keyPath to value.
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.
String	typeName() Returns the receiver's type name a string that uniquely identifies the receiver as a node in the controller hierarchy.
void	unableToSetNullForKey(String key) Invoked from takeValueForKey when it is given a null value for a scalar property (such as an int or a float).
Object	valueForKey(String key) Retrieves the value of the property named by key.
Object	valueForKeyPath(String keyPath) Retrieves the value of a property of the object at the end of the key path (a key path is a string of the form "key1.key2").

Methods inherited from class java.lang.Object

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

Field Detail

ControllerAndSubcontrollersEnumeration

public static final int ControllerAndSubcontrollersEnumeration

The constant describing enumerations that enumerate over a controller and its subcontrollers.

ControllerAndSupercontrollersEnumeration

public static final int ControllerAndSupercontrollersEnumeration

The constant describing enumerations that enumerate over a controller's supercontrollers, not including the controller itself.

SubcontrollersEnumeration

public static final int SubcontrollersEnumeration

The constant describing enumerations that enumerate over a controller's subcontrollers, not including the controller itself.

SupercontrollersEnumeration

public static final int SupercontrollersEnumeration

The constant describing enumerations that enumerate over a controller's supercontrollers, not including the controller itself.

Constructor Detail

EOController

public EOController()

Creates a new controller. The no-argument constructor is used when you create a controller programmatically, whereas the version taking an EOXMLUnarchiver argument is used in 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.

EOController

public EOController(EOXMLUnarchiver unarchiver)

Creates a new controller. The constructor taking an EOXMLUnarchiver argument is used when you create a controller from an XML description (in Direct to Java Client), whereas the version taking no arguments is used to create controllers programmatically. Controller subclasses should implement both constructors.

Parameters:

unarchiver - the unarchiver providing XML attributes

Method Detail

actionNames

public NSArray actionNames()

Returns an array of action method names the controller defines and responds to.

Returns:

an array of action method names the controller defines and responds to

actionWithName

public EOAction actionWithName(String actionName)

If the receiver has an action for a method with name actionName, this method returns that action; otherwise, the method returns null.

Parameters:

actionName - the action method name

Returns:

the action object for the specified action method name if one exists; null otherwise

actions

public NSArray actions()

Returns a cached 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.

Returns:

a cached array containing the receiver's actions

See Also:

defaultActions(), enabledActions(), resetActions()

addSubcontroller

public void addSubcontroller(EOController controller)

Adds controller as a subcontroller of the receiver and sets the receiver as controller's supercontroller - first removing controller from its supercontroller if it already has one. Invoke this method to 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 the receiver is already a supercontroller of controller. The default implementation 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.

Parameters:

controller - the controller to be added

See Also:

subcontrollerWasAdded(EOController)

additionalActions

public NSArray additionalActions()

Returns actions to be added to the controllers default actions.

Returns:

the array of additional actions

See Also:

actions()

additionalKeyValuePairs

public NSDictionary additionalKeyValuePairs()

Returns an NSDictionary of additional key-value pairs used by handleQueryWithUnboundKey().

Returns:

an NSDictionary to include as additional key-value pairs

See Also:

#handleQueryWithUnboundKey()

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 supercontrolllers that a subcontroller's connection status has changed so the supercontrolllers can react appropriately. Use this method to programmatically disconnect a single controller (and not its supercontrollers). EOController's implementation is sufficient for most subclasses, so you don't ordinarily override this method.

See Also:

connectionWasBroken(), breakConnectionToSubcontrollers()

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 hierarchy 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.

See Also:

breakConnection()

canAccessFieldsDirectly

public static boolean canAccessFieldsDirectly()

Conformance to NSKeyValueCoding. Returns whether the receiving class and its subclasses access instance variables directly for key-value coding. By default, EOControllers don't access instance variables directly and return false.

Returns:

false

See Also:

NSKeyValueCoding

canBeTransient

public boolean canBeTransient()

Returns whether the controller can be transient. EOController's implementation simply returns false.

Returns:

true if the controller can be transient; false otherwise

canPerformActionNamed

public boolean canPerformActionNamed(String actionName)

Description copied from interface: EOAction.Enabling

Returns true if the receiver can perform the action method (sent by an EOAction object) named actionName, false otherwise. An EOController's implementation of this method generally returns false if the receiver doesn't have an action named actionName or if the actionName action is explicitly disabled.

Specified by:

canPerformActionNamed in interface EOAction.Enabling

Following copied from interface: com.webobjects.eoapplication.EOAction.Enabling

Parameters:

actionName - the name of the EOAction

Returns:

true if the receiver can perform the action; false otherwise

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.

See Also:

breakConnection()

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

See Also:

establishConnection()

controllerEnumeration

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

Returns an EOController.Enumeration object you can use to traverse the controller hierarchy. enumerationType determines how to traverse the hiearchy. The enumeration will only contain controllers implementing the interface controllerInterface. If controllerInterface is null, the enumeration will contain all controllers for the specified enumeration type.

Parameters:

enumerationType - the type of the enumeration, one of EOController.SubcontrollersEnumeration, EOController.SupercontrollersEnumeration, or EOController.ControllerAndSubcontrollersEnumeration

controllerInterface - the interface to filter controllers out

Returns:

the enumeration object.

See Also:

EOController.Enumeration

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 one that matches. Matches are determined with the method valueForKeyPath.

Parameters:

enumerationType - the type of the enumeration, one of EOController.SubcontrollersEnumeration, EOController.SupercontrollersEnumeration, or EOController.ControllerAndSubcontrollersEnumeration

controllerInterface - the interface to filter controllers out

key - the key to match

value - the value to match

Returns:

the first controller in the enumeration which matches the key-value pair

See Also:

controllerWithKeyValuePairs(int, Class, NSDictionary), controllerEnumeration(int, Class), valueForKeyPath(String)

controllerWithKeyValuePairs

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

Traverses the controller hierarchy, and returns the first controller in the hierarchy which matches all key-value pairs 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 one that matches. Matches are determined with the method valueForKeyPath.

Parameters:

enumerationType - the type of the enumeration, one of EOController.SubcontrollersEnumeration, EOController.SupercontrollersEnumeration, or EOController.ControllerAndSubcontrollersEnumeration

controllerInterface - the interface to filter controllers out

keyValuePairs - the key-value pairs to match

Returns:

the first controller in the enumeration which matches the key-value pair

See Also:

controllerWithKeyValuePair(int, Class, String, Object), controllerEnumeration(int, Class), valueForKeyPath(String)

controllersInEnumeration

public NSArray controllersInEnumeration(int enumerationType,
                                        Class controllerInterface)

Returns all the controllers in an enumeration as an array.

Parameters:

enumerationType - the type of the enumeration, one of EOController.SubcontrollersEnumeration, EOController.SupercontrollersEnumeration, or EOController.ControllerAndSubcontrollersEnumeration

controllerInterface - the interface to filter controllers out

Returns:

an array of all controllers in an enumeration

See Also:

controllerEnumeration(int, Class)

controllersWithKeyValuePair

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

Traverses the controller hierarchy, and returns all controllers in the hierarchy whose value for key matches 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 a match and returns all the ones which match the key-value pair. Matches are determined with the method valueForKeyPath.

Parameters:

enumerationType - the type of the enumeration, one of EOController.SubcontrollersEnumeration, EOController.SupercontrollersEnumeration, or EOController.ControllerAndSubcontrollersEnumeration.

controllerInterface - the interface to filter controllers out

key - the key to match

value - the value to match

Returns:

an array of controllers in the enumeration which match the key-value pairs

See Also:

controllersWithKeyValuePairs(int, Class, NSDictionary), controllerEnumeration(int, Class), valueForKeyPath(String)

controllersWithKeyValuePairs

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

Traverses the controller hierarchy, and returns all controllers in the hierarchy which match all key/value pairs 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 a match and returns all the ones which match the key-value pairs. Matches are determined with the method valueForKeyPath.

Parameters:

enumerationType - the type of the enumeration, one of EOController.SubcontrollersEnumeration, EOController.SupercontrollersEnumeration, or EOController.ControllerAndSubcontrollersEnumeration.

controllerInterface - the interface to filter controllers out

keyValuePairs - the key/value pairs to match

Returns:

an array of controllers in the enumeration which match the key-value pairs.

See Also:

controllersWithKeyValuePair(int, Class, String, Object), controllerEnumeration(int, Class), valueForKeyPath(String)

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 actions it defines merged with the actions of its superclass. Never invoke this method directly. Instead, invoke actions, which caches the results of defaultActions and is therefore more efficient.

Returns:

an array of the receiver's default actions

See Also:

actions(), resetActions()

disableActionNamed

public void disableActionNamed(String actionName)

Explicitly disables the action method actionName and resets the receiver's actions.

Parameters:

actionName - the action method name

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.

Returns:

the receiver's disposable registry.

dispose

public void dispose()

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

Specified by:

dispose in interface NSDisposable

disposeIfTransient

protected boolean disposeIfTransient()

Disposes the receiver if it's transient, first removing it from its supercontroller with removeTransientSubcontroller If the receiver's supercontroller is non-null, this method also attempts to dispose of the supercontroller if it's transient. Supercontrollers can prevent a controller from becoming transient, in which case this method returns false. Subclasses should first invoke the super implementation and only continue disposing if the super implementation returns true.

Returns:

true if the receiver can be transient and has been disposed; false otherwise

See Also:

removeTransientSubcontroller(EOController)

enableActionNamed

public void enableActionNamed(String actionName)

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

Parameters:

actionName - the action method name

enabledActions

public NSArray enabledActions()

Returns an array of the receiver's actions which are not explicitly disabled. This method caches the enabled actions to enhance performance. The cache is cleared with the method resetActions.

Returns:

a cached array of the receiver's enabled actions

See Also:

defaultActions(), actions(), resetActions()

establishConnection

public void establishConnection()

Connects the receiver to the controller hierarchy. Invokes connectionWasEstablished to give the receiver a chance to prepare 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 connect a single controller (and not its supercontrollers). EOController's implementation is sufficient for most subclasses, so you don't ordinarily override this method.

See Also:

connectionWasEstablished(), establishConnectionToSupercontrollers()

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 supercontrollers 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.

See Also:

establishConnection()

handleQueryWithUnboundKey

public Object handleQueryWithUnboundKey(String key)

Description copied from interface: NSKeyValueCoding.ErrorHandling

Invoked from valueForKey when it finds no property binding for key. The default implementation throws an NSKeyValueCoding.UnknownKeyException, with the target object(TargetObjectUserInfoKey) and key(UnknownUserInfokey) in the user info. An NSKeyValueCoding.ErrorHandling class can override this method to handle the query in some other way. The method can return a value, in which case that value is returned by the corresponding valueForKey invocation.

Specified by:

handleQueryWithUnboundKey in interface NSKeyValueCoding.ErrorHandling

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding.ErrorHandling

Parameters:

key - the property name which generated this error

Returns:

any Object or null that the custom implementation desires. The default implementation throws an exception instead.

Throws:

NSKeyValueCoding.UnknownKeyException - when it finds no property binding for key

See Also:

NSKeyValueCoding.valueForKey(java.lang.String), NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.DefaultImplementation

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey(Object value,
                                         String key)

Description copied from interface: NSKeyValueCoding.ErrorHandling

Invoked from takeValueForKey when it finds no property binding for key. The default implementation throws an NSKeyValueCoding.UnknownKeyException, with the target object(TargetObjectUserInfoKey) and key(UnknownUserInfoKey) in the user info dictionary of the exception. An NSKeyValueCoding.ErrorHandling class can override this method to handle the error in some other way.

Specified by:

handleTakeValueForUnboundKey in interface NSKeyValueCoding.ErrorHandling

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding.ErrorHandling

Parameters:

value - the new value which could not be set

key - the name of the property which generated this error

Throws:

NSKeyValueCoding.UnknownKeyException - when it finds no property binding for key

See Also:

NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.DefaultImplementation

hierarchicalControllerForKey

public EOController hierarchicalControllerForKey(Class controllerInterface,
                                                 String key)

Starting at the receiver, searches up the controller hierarchy for the first controller that implements the interface controllerInterface and has a non-null value for key and returns that controller. If controllerInterface is null, tests all controllers.

Parameters:

controllerInterface - the interface required by the controllers to be tested

key - the key to look up

Returns:

the closest supercontroller that implements the interface and has a non-null value for the key if one exists; null otherwise

hierarchicalValueForKey

public Object hierarchicalValueForKey(Class controllerInterface,
                                      String key)

Starting at the receiver, searches up the controller hierarchy for the first controller that implements the interface controllerInterface and has a non-null value for key and returns that value. If controllerInterface is null, tests all controllers.

Parameters:

controllerInterface - the interface required by the controllers to be tested

key - the key to look up

Returns:

the value of the closest supercontroller that implements the interface and has a non-null value for the key if one exists; null otherwise

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. 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 method methodName with the values in parameters as arguments.

Parameters:

enumerationType - the type of the enumeration, one of EOController.SubcontrollersEnumeration, EOController.SupercontrollersEnumeration, or EOController.ControllerAndSubcontrollersEnumeration

controllerInterface - the interface to filter controllers out

methodName - the name of the method

parameterTypes - the types of the parameters

parameters - the parameters

See Also:

controllerEnumeration(int, Class)

isActionNamedEnabled

public boolean isActionNamedEnabled(String actionName)

Returns whether the action method actionName isn't explicitly disabled.

Parameters:

actionName - the action method name

Returns:

true if the action isn't explicitly disabled; false otherwise

isAncestorOfController

public boolean isAncestorOfController(EOController controller)

Returns whether controller is a subcontroller of the receiver, of the receiver's subcontrollers, or their subcontrollers, and so on.

Parameters:

controller - the controller to test

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 the receiver's connection status.

Returns:

true if the controller is connected; false otherwise

isSupercontrollerOfController

public boolean isSupercontrollerOfController(EOController controller)

Returns whether controller is a direct subcontroller of the receiver.

Parameters:

controller - the controller to test

Returns:

true if the controller is a direct subcontroller of the receiver; false otherwise

isTransientExplicitlyForbidden

protected boolean isTransientExplicitlyForbidden()

Returns whether transience is explicitly forbidden for this controller.

Returns:

true if the controller cannot be transient; 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 usually invoked to prepare a branch of the controller for reuse. Subclasses should override this method to get rid of data and perform any additional clean up.

Parameters:

prepareSubcontrollersForNewTask - true if the method should be forwarded to all subcontrollers; false otherwise

removeFromSupercontroller

public void removeFromSupercontroller()

Removes the receiver from its supercontroller's set of subcontrollers. Invoke this method when you need to remove a controller from the controller hierarchy. EOController's implementation simply invokes removeSubcontroller on the receiver's supercontroller. This method is mostly 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:

removeSubcontroller(EOController)

removeSubcontroller

protected void removeSubcontroller(EOController controller)

Removes controller from the controller hierarchy. EOController's implementation disconnects controller from the controller hierarchy, and invokes subcontrollerWasRemoved on the receiver to give it a chance to react 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, override subcontrollerWasRemoved.

Parameters:

controller - the controller to be removed

See Also:

subcontrollerWasRemoved(EOController)

removeTransientSubcontroller

protected boolean removeTransientSubcontroller(EOController controller)

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

Parameters:

controller - the controller to remove because it becomes transient

Returns:

true if the controller could be removed; false otherwise

See Also:

disposeIfTransient()

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.

setAdditionalActions

public void setAdditionalActions(NSArray additionalActions)

Sets actions to be added to the controllers default actions.

Parameters:

additionalActions - the array of additional actions

See Also:

actions()

setAdditionalKeyValuePair

public void setAdditionalKeyValuePair(Object value,
                                      String key)

Adds value to the dictionary of additionalKeyValuePairs with key.

Parameters:

value - an Object

key - the String key to store value with

See Also:

#handleQueryWithUnboundKey()

setAdditionalKeyValuePairs

public void setAdditionalKeyValuePairs(NSDictionary dictionary)

Sets NSDictionary, dictionary, of key-value pairs for use in handleQueryWithUnboundKey()

Parameters:

dictionary - the NSDictionary to include as additional key-value pairs

See Also:

additionalKeyValuePairs(), #handleQueryWithUnboundKey()

setConnected

protected void setConnected(boolean flag)

Sets the receiver's connection status. 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.

Parameters:

flag - true if the controller is connected; false otherwise

See Also:

establishConnection(), breakConnection()

setSupercontroller

protected boolean setSupercontroller(EOController controller)

Sets the receiver's supercontroller to controller and resets the receiver's actions. Returns whether the supercontroller accepted the receiver as subcontroller. 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.

Parameters:

controller - the supercontroller

Returns:

true if the supercontroller accepted the controller as subcontroller; false otherwise

See Also:

addSubcontroller(EOController)

setTransientExplicitlyForbidden

protected void setTransientExplicitlyForbidden(boolean flag)

Sets whether transience is explicitly forbidden for this controller.

Parameters:

flag - true if the controller cannot be transient; false otherwise

setTypeName

public void setTypeName(String typeName)

Sets the receiver's type name.

Parameters:

typeName - the controller's type name

subcontrollerWasAdded

protected void subcontrollerWasAdded(EOController controller)

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

Parameters:

controller - the subcontroller just added

See Also:

addSubcontroller(EOController)

subcontrollerWasRemoved

protected void subcontrollerWasRemoved(EOController controller)

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

Parameters:

controller - the subcontroller just removed

See Also:

removeSubcontroller(EOController)

subcontrollers

public NSArray subcontrollers()

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

Returns:

an array of the receiver's direct subcontrollers

See Also:

controllerEnumeration(int, Class), controllersInEnumeration(int, Class)

supercontroller

public EOController supercontroller()

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

Returns:

the receiver's supercontroller

supercontroller

public EOController supercontroller(Class controllerInterface)

Searching from the receiver's direct 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 the interface. Returns receiver's direct supercontroller if controllerInterface is null.

Parameters:

controllerInterface - the controller interface to look for

Returns:

the closest supercontroller that implements the interface if one exists; null otherwise

takeValueForKey

public void takeValueForKey(Object value,
                            String key)

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

Specified by:

takeValueForKey in interface NSKeyValueCoding

See Also:

NSKeyValueCoding

takeValueForKeyPath

public void takeValueForKeyPath(Object value,
                                String keyPath)

Description copied from interface: NSKeyValueCodingAdditions

Sets the value for the property identified by keyPath to value. A key path has the form relationship.property (with one or more relationships); for example "movieRole.roleName" or "movieRole.talent.lastName". The default implementation of this method (provided by NSKeyValueCodingAdditions.DefaultImplementation) gets the destination object for each relationship using valueForKey, and sends the final object a takeValueForKey message with value and property.

Specified by:

takeValueForKeyPath in interface NSKeyValueCodingAdditions

Following copied from interface: com.webobjects.foundation.NSKeyValueCodingAdditions

Parameters:

value - the property identified by keyPath is set to this

keyPath - identifies the property of an object

See Also:

NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.valueForKeyPath(java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation

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.

Overrides:

toString in class Object

Returns:

the String representation of the receiver

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.

Returns:

the controller's type name

unableToSetNullForKey

public void unableToSetNullForKey(String key)

Description copied from interface: NSKeyValueCoding.ErrorHandling

Invoked from takeValueForKey when it is given a null value for a scalar property (such as an int or a float). The default implementation throws an IllegalArgumentException. You might want to implement the method (or override the inherited implementation) to handle the request in some other way, such as by substituting new Integer(0) or a sentinel value and invoking takeValueForKey again.

Specified by:

unableToSetNullForKey in interface NSKeyValueCoding.ErrorHandling

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding.ErrorHandling

Parameters:

key - the name of the property which generated this error

Throws:

IllegalArgumentException - when it is given a null value for a scalar property

See Also:

NSKeyValueCoding.takeValueForKey(Object value, String key), NSKeyValueCoding.DefaultImplementation

valueForKey

public Object valueForKey(String key)

Description copied from interface: NSKeyValueCoding

Retrieves the value of the property named by key.

The default implementation provided by NSKeyValueCoding.DefaultImplementation works as follows:

1. Searches for a public accessor method based on key. For example, with a key of "lastName", the method looks for a method named getLastName, lastName, or isLastName.
2. If a public accessor method is not found, searches for a private accessor method based on key (a method preceded by an underbar). For example, with a key of "lastName", the method looks for a method named _getLastName, _lastName, or _isLastName
3. If an accessor method is not found and the static method canAccessFieldsDirectly returns true, the method searches for a field based on key and returns its value directly. For the key "lastName", this would be _lastName, _isLastName, lastName, or isLastName.
4. If neither an accessor method nor a field is found, the method invokes handleQueryWithUnboundKey (defined in NSKeyValueCoding.ErrorHandling).

Note: The default implementations have significant performance optimizations. To benefit from them, implement NSKeyValueCoding on a custom class as shown above by using the methods in NSKeyValueCoding.DefaultImplementation, or if your class inherits from an WebObjects class that implements NSKeyValueCoding, do not override the inherited implementation. Using a custom implementation incurs significant performance penalties.

Specified by:

valueForKey in interface NSKeyValueCoding

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding

Parameters:

key - identifies the property to retrieve

Returns:

the value of the property identified by key. Depending on the object you invoke this method upon, null may be replaced with NullValue

Throws:

NSKeyValueCoding.UnknownKeyException - if key cannot be found on the object this method was invoked upon.

See Also:

NSKeyValueCoding.NullValue, NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleQueryWithUnboundKey(java.lang.String)

valueForKeyPath

public Object valueForKeyPath(String keyPath)

Description copied from interface: NSKeyValueCodingAdditions

Retrieves the value of a property of the object at the end of the key path (a key path is a string of the form "key1.key2"). A key path has the form relationship.property (with one or more relationships); for example "movieRole.roleName" or "movieRole.talent.lastName". The default implementation of this method (provided by NSKeyValueCodingAdditions.DefaultImplementation) gets the destination object for each relationship using valueForKey, and returns the result of a valueForKey message to the final object.

Specified by:

valueForKeyPath in interface NSKeyValueCodingAdditions

Following copied from interface: com.webobjects.foundation.NSKeyValueCodingAdditions

Parameters:

keyPath - the keypath to evaluate

Returns:

the value for the derived property identified by keyPath

See Also:

NSKeyValueCoding.valueForKey(java.lang.String), NSKeyValueCodingAdditions.takeValueForKeyPath(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation