com.webobjects.eoapplication
Class EOEntityController

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

All Implemented Interfaces:

EOAction.Enabling, EOAssociationConnector, EOComponentController.EndEditing, EOObjectDisplay, EOObserving, NSDisposable, NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions

Direct Known Subclasses:

EODocumentController, EOQueryController

public abstract class EOEntityController

extends EOComponentController

implements EOObserving, EOObjectDisplay, EOAssociationConnector, EOComponentController.EndEditing

The EOEntityController class provides behavior for displaying enterprise objects in a user interface that can optionally be loaded from an interface file archive (a .nib file). EOEntityController's most basic API is specified by the interface EOObjectDisplay, which identifies an implementation strategy that uses EOEditingContexts and EODisplayGroups to manage an entity controller's enterprise objects. An entity controller has an entity name, which identifies the kind of enterprise objects the controller works with. Additionally it has an editing context that manages the controller's enterprise objects, a display group that displays the enterprise objects and manages a selection, and a controller display group that connects controller methods to the user interface.

As a subclass of EOComponentController, EOEntityController manages a user interface component (which by default is just an empty view to hold subcontroller components). However, whereas most component controllers dynamically generate their components, entity controllers have the ability to load their components from an archive (an interface file created in Interface Builder). An entity controller has an archive name, which specifies the archive from which to load the controller's component. If, however, a controller doesn't have an archive name, the controller simply uses its default interface.

Managing the Editing Context

EOEntityController uses an editing context to manage its enterprise objects. By default, an entity controller attempts to get its editing context from a supercontroller. An entity controller looks up the controller hierarchy for the first EOObjectDisplay supercontroller that has an editing context. If it finds one, the entity controller uses that supercontroller's editing context. If it doesn't find one, it creates a new one.

You can change the way an entity controller gets its editing context by specifying a so-called provider method with setEditingContextProviderMethodName. If an entity controller has an editing context provider method, it gets its editing context by invoking that method.

EOEntityController provides two methods you might find useful as editing context provider methods: newEditingContext and nestedEditingContext. The former simply creates a new editing context and is a convenience for setting the provider method. The latter attempts to create a new editing context that is nested inside a supercontroller's editing context. If no supercontroller can provide an editing context to be a parent, nestedEditingContext simply creates a new editing context.

Managing the Display Group

EOEntityController uses a display group to display its enterprise objects. By default, an entity controller attempts to get its display group from a supercontroller. An entity controller looks up the controller hierarchy for the first EOObjectDisplay supercontroller. If that supercontroller has the same entity name and provides a display group, the entity controller uses that supercontroller's display group. If it doesn't find one, it invokes loadArchive to see if a display group is provided in an interface file archive. If the controller still doesn't have a display group, it simply creates a new one.

You can change the way an entity controller gets its display group by specifying a so-called provider method with setDisplayGroupProviderMethodName. If an entity controller has a display group provider method, it gets its display group by invoking that method.

EOEntityController provides two methods you might find useful as display group provider methods: newDisplayGroup and newDisplayGroupUsingOptimisticRefresh. They simply create new display groups and are convenience methods for setting the provider method.

Provider Method

Editing context and display group provider methods are specified as a String, which can be a key path or the name of an arbitrary class's static method. For an example of setting the method name to a key path, consider a subclass of EOEntityController that implements the method customizedEditingContext to return an editing context for the controller to use. In this case, the provider method name could be set to customizedEditingContext.

If the provider method name is the name of a static method, the format of the string is ":". For example, suppose that you've written a subclass CustomApplicationClass of EOApplication that implements a static method, customizedEditingContextForAllControllers, to return an editing context for all an application's controllers to share. Then the editing context provider method name for all entity controllers could be set to CustomApplicationClass:customizedEditingContextForAllControllers.

Inner classes inherited from class com.webobjects.eoapplication.EOComponentController

EOComponentController.ActionCollector, EOComponentController.Activation, EOComponentController.EndEditing, EOComponentController.Modal, EOComponentController.ResetUserInterface

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

EOController.Enumeration

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 String	NestedEditingContextProviderMethodName The constant describing a the nestedEditingContext editing context provider method name.
static String	NewDisplayGroupProviderMethodName The constant describing a the newDisplayGroup display group provider method name.
static String	NewDisplayGroupUsingOptimisticRefreshProviderMethodName The constant describing a the newDisplayGroupUsingOptimisticRefresh display group provider method name.
static String	NewEditingContextProviderMethodName The constant describing a the newEditingContext editing context provider method name.

Fields inherited from class com.webobjects.eoapplication.EOComponentController

Bottom, BottomLeft, BottomRight, Center, Left, Right, Top, TopLeft, TopRight

Fields inherited from class com.webobjects.eoapplication.EOController

ControllerAndSubcontrollersEnumeration, SubcontrollersEnumeration, SupercontrollersEnumeration

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

EOEntityController()
Creates a new entity controller.

EOEntityController(EOXMLUnarchiver unarchiver)
Creates a new entity controller from an EOXMLUnarchiver.

Method Summary

String	archiveName() Returns the name of the interface file archive to be loaded by the controller instead of generating its component dynamically.
protected void	connectionWasBroken() Reacts to the connection for the receiver being broken, taking care of association disconnecting.
protected void	connectionWasEstablished() Reacts to the connection for the receiver being established, taking care of association connecting and fetching if necessary.
protected void	controllerDidLoadArchive(NSDictionary namedObjects) Invoked from loadArchive to notify the receiver that its interface file has been loaded completely.
EODisplayGroup	controllerDisplayGroup() Conformance to EOObjectDisplay.
EODisplayGroup	displayGroup() Conformance to EOObjectDisplay.
String	displayGroupProviderMethodName() Returns the key path which is used to retrieve the display group for the reveiver.
protected NSArray	displayGroupSortOrderings() Returns the sort orderings to be used with the receiver's display group.
void	dispose() Prepares the receiver so it is disposed when Java performs garbage collection.
EOEditingContext	editingContext() Conformance to EOObjectDisplay.
String	editingContextProviderMethodName() Returns the key path which is used to retrieve the editing context for the reveiver.
boolean	endEditing() Ensures that all editors of the receiver's display groups end editing (flush current user edits to the enterprise object graph if necessary).
String	entityName() Conformance to EOObjectDisplay.
void	establishConnection() Overridden from the superclass to ensure that, if an archive name is specified for the receiver, the interface file archive is loaded before the connection is established.
boolean	fetchesOnConnect() Returns whether the receiver should fetch its display group content next time its connection is established.
void	handleEditingContextNotification(NSNotification notification) When starting to listen to an editing context, entity controllers register for several notifications from the editing context.
boolean	hasControllerDisplayGroup() Returns whether the controller already has a controller display group.
boolean	isRootEntityController() Returns whether the receiver is a root entity controller (which is the case if none of the supercontrollers conform to EOObjectDisplay).
protected boolean	loadArchive() If not already loaded, loads the interface file archive specified by the archiveName of the receiver.
EOEditingContext	nestedEditingContext() Creates a new, nested editing context to the editing context from its closest supercontroller conforming to the EOObjectDisplay interface and returning an editing context.
protected EODataSource	newDataSource() Creates and returns a new data source to be used with a display group of the receiver.
EODisplayGroup	newDisplayGroup() Creates a new display group using a data source provided by newDataSource.
EODisplayGroup	newDisplayGroupUsingOptimisticRefresh() Creates a new display group using a data source provided by newDataSource, configured to not use optimistic refresh.
EOEditingContext	newEditingContext() Creates a new editing context with the default parent object store.
Object	objectForOutletPath(EOArchive archive, String outletPath) Returns an object for an outlet path to be substituted in an interface file archive loaded by the receiver.
void	objectWillChange(Object object) Change notification for the controller itself if it's edited through an association of the controller display group.
protected void	prepareComponent() Overridden from the superclass to ensure that -- if an archive name is specified for the receiver -- the interface file archive is loaded before the component is prepared.
void	prepareForNewTask(boolean prepareSubcontrollersForNewTask) Prepares the receiver for performing a new task by resetting any data and refetching objects if necessary.
boolean	resetsEditingContextWhenPreparingForNewTask() Returns whether the receiver should reset its editing context when preparing for a new task in prepareForNewTask(boolean).
EOEnterpriseObject	selectedObject() Returns the first enterprise object selected in the receiver's display group.
EOGlobalID	selectedObjectGlobalID() Returns the global ID of the first enterprise object selected in the receiver's display group.
NSArray	selectedObjects() Returns the enterprise objects selected in the receiver's display group.
NSArray	selectedObjectsGlobalIDs() Returns the global IDs of the enterprise objects selected in the receiver's display group.
void	setArchiveName(String string) Sets the name of the interface file archive to be loaded by the controller instead of generating its component dynamically.
void	setControllerDisplayGroup(EODisplayGroup displayGroup) Sets and prepares the controller display group -- the display group that contains the receiver itself.
void	setDisplayGroup(EODisplayGroup displayGroup) Sets the display group used by this controller.
void	setDisplayGroupProviderMethodName(String string) Sets the provider method which is used to retrieve the display group for the reveiver.
void	setEditingContext(EOEditingContext editingContext) Sets the editing context used by this controller.
void	setEditingContextProviderMethodName(String string) Sets the provider method which is used to retrieve the editing context for the reveiver.
void	setEntityName(String string) Sets the entity name of the enterprise objects displayed by the receiver.
void	setFetchesOnConnect(boolean flag) Sets whether the receiver should fetch its display group content next time its connection is established.
void	setObjectsWithFetchSpecification(EOFetchSpecification fetchSpecification) Fetches the objects specified by fetchSpecification into the receiver's display group.
void	setObjectWithGlobalID(EOGlobalID globalID) Fetches the objects specified by the global ID globalID into the receiver's display group.
void	setResetsEditingContextWhenPreparingForNewTask(boolean flag) Sets whether the receiver should reset its editing context when preparing for a new task in prepareForNewTask(boolean).
protected void	startListeningToDisplayGroup() Invoked from setDisplayGroup whenever a new display group is specified, giving the receiver a chance to react.
protected void	startListeningToEditingContext() Invoked from setEditingContext whenever a new editing context is specified, giving the receiver a chance to react.
protected void	stopListeningToDisplayGroup() Invoked from setDisplayGroup whenever a display group is cleared out (if either a new display group is specified or if the display group is reset to null), giving the receiver a chance to react.
protected void	stopListeningToEditingContext() Invoked from setEditingContext whenever an editing context is cleared out (if either a new editing context is specified or if the editing context is reset to null), giving the receiver a chance to react.
void	takeResposibilityForConnectionOfAssociation(EOAssociation association) Conformance to EOAssociationConnector.
String	toString() Returns the receiver as a string describing the state of the controller.
void	willChange() Triggers EOObserverCenter change notifications for the controller itself.

Methods inherited from class com.webobjects.eoapplication.EOComponentController

addComponentOfSubcontroller, alignmentWidth, alignsComponents, canBeTransient, canResizeHorizontally, canResizeVertically, component, componentDidBecomeInvisible, componentDidBecomeVisible, defaultComponentSize, ensureMinimumComponentSizeWithoutSubcontrollers, ensureMinimumSubcontrollerAreaSize, generateComponent, handleTakeValueForUnboundKey, hideInSupercontroller, hideSubcontroller, icon, integrationComponent, integrationComponentDidBecomeInvisible, integrationComponentDidBecomeVisible, isComponentPrepared, isRootComponentController, isVisible, label, makeInvisible, makeVisible, minimumComponentSize, minimumComponentSizeWithoutSubcontrollers, minimumIntegrationComponentSize, minimumSubcontrollerAreaSize, prefersIconOnly, removeComponentOfSubcontroller, removeTransientSubcontroller, setAlignmentWidth, setAlignsComponents, setCanResizeHorizontally, setCanResizeVertically, setComponent, setDefaultComponentSize, setIcon, setLabel, setPrefersIconOnly, setSubcontrollerArea, setUsesHorizontalLayout, setVisible, showInSupercontroller, showSubcontroller, subcontrollerArea, subcontrollerMinimumSizeDidChange, subcontrollerWasAdded, subcontrollerWasRemoved, usesHorizontalLayout

Methods inherited from class com.webobjects.eoapplication.EOController

actionNames, actions, actionWithName, addSubcontroller, breakConnection, breakConnectionToSubcontrollers, canAccessFieldsDirectly, canPerformActionNamed, controllerEnumeration, controllersInEnumeration, controllersWithKeyValuePair, controllersWithKeyValuePairs, controllerWithKeyValuePair, controllerWithKeyValuePairs, defaultActions, disableActionNamed, disposableRegistry, disposeIfTransient, enableActionNamed, enabledActions, establishConnectionToSupercontrollers, handleQueryWithUnboundKey, hierarchicalControllerForKey, hierarchicalValueForKey, invokeMethod, isActionNamedEnabled, isAncestorOfController, isConnected, isSupercontrollerOfController, isTransientExplicitlyForbidden, removeFromSupercontroller, removeSubcontroller, resetActions, setConnected, setSupercontroller, setTransientExplicitlyForbidden, setTypeName, subcontrollers, supercontroller, supercontroller, takeValueForKey, takeValueForKeyPath, typeName, unableToSetNullForKey, valueForKey, valueForKeyPath

Methods inherited from class java.lang.Object

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

Field Detail

NestedEditingContextProviderMethodName

public static final String NestedEditingContextProviderMethodName

The constant describing a the nestedEditingContext editing context provider method name.

NewDisplayGroupProviderMethodName

public static final String NewDisplayGroupProviderMethodName

The constant describing a the newDisplayGroup display group provider method name.

NewDisplayGroupUsingOptimisticRefreshProviderMethodName

public static final String NewDisplayGroupUsingOptimisticRefreshProviderMethodName

The constant describing a the newDisplayGroupUsingOptimisticRefresh display group provider method name.

NewEditingContextProviderMethodName

public static final String NewEditingContextProviderMethodName

The constant describing a the newEditingContext editing context provider method name.

Constructor Detail

EOEntityController

public EOEntityController()

Creates a new entity controller.

EOEntityController

public EOEntityController(EOXMLUnarchiver unarchiver)

Creates a new entity controller from an EOXMLUnarchiver.

Parameters:

unarchiver - the unarchiver providing XML attributes

Method Detail

archiveName

public String archiveName()

Returns the name of the interface file archive to be loaded by the controller instead of generating its component dynamically.

Returns:

the name of the interface file archive to be loaded by the controller

connectionWasBroken

protected void connectionWasBroken()

Reacts to the connection for the receiver being broken, taking care of association disconnecting.

Overrides:

connectionWasBroken in class EOController

Following copied from class: com.webobjects.eoapplication.EOController

See Also:

EOController.breakConnection()

connectionWasEstablished

protected void connectionWasEstablished()

Reacts to the connection for the receiver being established, taking care of association connecting and fetching if necessary.

Overrides:

connectionWasEstablished in class EOController

Following copied from class: com.webobjects.eoapplication.EOController

See Also:

EOController.establishConnection()

controllerDidLoadArchive

protected void controllerDidLoadArchive(NSDictionary namedObjects)

Invoked from loadArchive to notify the receiver that its interface file has been loaded completely. You can override this method to perform additional initialization for the objects loaded from the interface file archive.

Parameters:

namedObjects - dictionary with all named objects from the interface file archive (keys: names, values: objects)

See Also:

loadArchive()

controllerDisplayGroup

public EODisplayGroup controllerDisplayGroup()

Conformance to EOObjectDisplay. Returns the controller display group -- the display group that contains the receiver itself. The controller display group can be used to connect methods of the controller to the user interface through associations. If the controller is edited through associations of the controller display group, it can receive objectWillChange methods. If the controller display group has not been set so far, creates a new one and returns it.

Specified by:

controllerDisplayGroup in interface EOObjectDisplay

Returns:

the controller display group of the receiver

See Also:

setControllerDisplayGroup(EODisplayGroup), objectWillChange(Object)

displayGroup

public EODisplayGroup displayGroup()

Conformance to EOObjectDisplay. Returns the display group used by this controller. If the display group has so far not been set, attempts to retrieve one from a supercontroller which uses the same entity or creates a new one if no supercontroller can provide one.

Specified by:

displayGroup in interface EOObjectDisplay

Returns:

the display group used by this controller

See Also:

setDisplayGroup(EODisplayGroup), displayGroupSortOrderings()

displayGroupProviderMethodName

public String displayGroupProviderMethodName()

Returns the key path which is used to retrieve the display group for the reveiver. If no provider method name is explicitly specified, the default mechanism is used (which means that the controller attempts to use the display group of an supercontroller or simply creates a new one if no supercontroller can provide a display group). EOEntityController provides two useful methods you can use for the editing context provider method name: newDisplayGroup and newDisplayGroupUsingOptimisticRefresh.

Returns:

string the key path used to retrieve the display group for the receiver

See Also:

setDisplayGroupProviderMethodName(String), displayGroup(), newDisplayGroup(), newDisplayGroupUsingOptimisticRefresh()

displayGroupSortOrderings

protected NSArray displayGroupSortOrderings()

Returns the sort orderings to be used with the receiver's display group. EOEntityController's default implementation returns null. Note that the display group sort orderings might be overridden by table associations unless they are configured to not change the display group sort orderings.

Returns:

an array of sort orderings to be used with the receiver's display group

dispose

public void dispose()

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

Overrides:

dispose in class EOComponentController

editingContext

public EOEditingContext editingContext()

Conformance to EOObjectDisplay. Returns the editing context used by this controller. If the editing context has so far not been set, attempts to retrieve one from a supercontroller or creates a new one if no supercontroller can provide one.

Specified by:

editingContext in interface EOObjectDisplay

Returns:

the editing context used by this controller

See Also:

setEditingContext(EOEditingContext)

editingContextProviderMethodName

public String editingContextProviderMethodName()

Returns the key path which is used to retrieve the editing context for the reveiver. If no provider method name is explicitly specified, the default mechanism is used (which means that the controller attempts to use the editing context of an supercontroller or simply creates a new one if no supercontroller can provide an editing context). EOEntityController provides two useful methods you can use for the editing context provider method name: newEditingContext and nestedEditingContext.

Returns:

string the key path used to retrieve the editing context for the receiver

See Also:

setEditingContextProviderMethodName(String), editingContext(), newEditingContext(), nestedEditingContext()

endEditing

public boolean endEditing()

Ensures that all editors of the receiver's display groups end editing (flush current user edits to the enterprise object graph if necessary). This method is invoked automatically before saving or reverting changes in subclasses.

Specified by:

endEditing in interface EOComponentController.EndEditing

Returns:

true if all uncommitted changes were successfully flushed; false otherwise

entityName

public String entityName()

Conformance to EOObjectDisplay. Returns the entity name of the enterprise objects displayed by the receiver.

Specified by:

entityName in interface EOObjectDisplay

Returns:

the entity name of the enterprise objects displayed by the receiver

establishConnection

public void establishConnection()

Overridden from the superclass to ensure that, if an archive name is specified for the receiver, the interface file archive is loaded before the connection is established.

Overrides:

establishConnection in class EOController

Following copied from class: com.webobjects.eoapplication.EOController

See Also:

EOController.connectionWasEstablished(), EOController.establishConnectionToSupercontrollers()

fetchesOnConnect

public boolean fetchesOnConnect()

Returns whether the receiver should fetch its display group content next time its connection is established. This value changes often: Whenever an entity controller prepares for a new task, it sets this flag to true. Once it retrieves objects explicitly (for example from a global ID) or actually performs the fetch while connecting, it sets this flag to false.

Returns:

true if the controller should fetch its display group content next time its connection is established; false otherwise

See Also:

setFetchesOnConnect(boolean)

handleEditingContextNotification

public void handleEditingContextNotification(NSNotification notification)

When starting to listen to an editing context, entity controllers register for several notifications from the editing context. Whenever one of these notifications is posted, this method is invoked and allows the controller to react to the editing context changes.

Parameters:

notification - the editing context notification

See Also:

startListeningToEditingContext()

hasControllerDisplayGroup

public boolean hasControllerDisplayGroup()

Returns whether the controller already has a controller display group.

Returns:

true if the controller already has a controller display group; false otherwise

isRootEntityController

public boolean isRootEntityController()

Returns whether the receiver is a root entity controller (which is the case if none of the supercontrollers conform to EOObjectDisplay).

Returns:

true if the controller is a root entity controller; false otherwise

loadArchive

protected boolean loadArchive()

If not already loaded, loads the interface file archive specified by the archiveName of the receiver. While loading, controllers can substitute objects in objectForOutletPath. Afterwards, controllers can perform additional initialization for the objects loaded from the archive in controllerDidLoadArchive. If no archiveName is specified, this method returns false.

Returns:

true if the archive was successfully loaded; false otherwise

See Also:

controllerDidLoadArchive(NSDictionary), objectForOutletPath(EOArchive, String)

nestedEditingContext

public EOEditingContext nestedEditingContext()

Creates a new, nested editing context to the editing context from its closest supercontroller conforming to the EOObjectDisplay interface and returning an editing context. If no supercontroller can provide a parent editing context, creates a new one with the default parent object store. This method can be used as editing context provider method.

Returns:

the new (nested) editing context

See Also:

setEditingContextProviderMethodName(String)

newDataSource

protected EODataSource newDataSource()

Creates and returns a new data source to be used with a display group of the receiver. EOEntityController's default implementation creates a new EODistributedDataSource for the entity specified by entityName.

Returns:

the new data source

See Also:

entityName()

newDisplayGroup

public EODisplayGroup newDisplayGroup()

Creates a new display group using a data source provided by newDataSource. This method can be used as display group provider method.

Returns:

the new display group

See Also:

newDisplayGroupUsingOptimisticRefresh(), setDisplayGroupProviderMethodName(String)

newDisplayGroupUsingOptimisticRefresh

public EODisplayGroup newDisplayGroupUsingOptimisticRefresh()

Creates a new display group using a data source provided by newDataSource, configured to not use optimistic refresh. This method can be used as display group provider method.

Returns:

the new display group

See Also:

newDisplayGroup(), setDisplayGroupProviderMethodName(String)

newEditingContext

public EOEditingContext newEditingContext()

Creates a new editing context with the default parent object store. This method can be used as editing context provider method.

Returns:

the new editing context

See Also:

setEditingContextProviderMethodName(String)

objectForOutletPath

public Object objectForOutletPath(EOArchive archive,
                                  String outletPath)

Returns an object for an outlet path to be substituted in an interface file archive loaded by the receiver. This methods allows you to substitute objects for all objects that can be reached through an outlet connection from the file's owner, for example the editingContext of the receiver (which is the file's owner of the archive) or displayGroup.dataSource. If no substitution object is needed, this method returns null.

Parameters:

archive - the archive currently loaded

outletPath - the outlet path to find a substitution object for

Returns:

the substituation object or null if no substitution object is needed

See Also:

loadArchive()

objectWillChange

public void objectWillChange(Object object)

Change notification for the controller itself if it's edited through an association of the controller display group.

Specified by:

objectWillChange in interface EOObserving

Parameters:

object - the changed object (the controller itself)

See Also:

willChange()

prepareComponent

protected void prepareComponent()

Overridden from the superclass to ensure that -- if an archive name is specified for the receiver -- the interface file archive is loaded before the component is prepared.

Overrides:

prepareComponent in class EOComponentController

prepareForNewTask

public void prepareForNewTask(boolean prepareSubcontrollersForNewTask)

Prepares the receiver for performing a new task by resetting any data and refetching objects if necessary.

Overrides:

prepareForNewTask in class EOController

Parameters:

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

resetsEditingContextWhenPreparingForNewTask

public boolean resetsEditingContextWhenPreparingForNewTask()

Returns whether the receiver should reset its editing context when preparing for a new task in prepareForNewTask(boolean). The default is true.

Returns:

true if the controller resets its editing context while preparing for a new task; false otherwise

selectedObject

public EOEnterpriseObject selectedObject()

Returns the first enterprise object selected in the receiver's display group.

Returns:

the first enterprise object selected in the receiver's display group

selectedObjectGlobalID

public EOGlobalID selectedObjectGlobalID()

Returns the global ID of the first enterprise object selected in the receiver's display group.

Returns:

the global ID of the first enterprise object selected in the receiver's display group

selectedObjects

public NSArray selectedObjects()

Returns the enterprise objects selected in the receiver's display group.

Returns:

an array of all selected objects in the receiver's display group

selectedObjectsGlobalIDs

public NSArray selectedObjectsGlobalIDs()

Returns the global IDs of the enterprise objects selected in the receiver's display group.

Returns:

an array of the global IDs of all selected objects in the receiver's display group

setArchiveName

public void setArchiveName(String string)

Sets the name of the interface file archive to be loaded by the controller instead of generating its component dynamically. Throws an IllegalStateException if the receiver's archive is already loaded. In other words, you can only set the archive name before the component is generated.

Parameters:

string - the name of the interface file archive to be loaded by the controller

setControllerDisplayGroup

public void setControllerDisplayGroup(EODisplayGroup displayGroup)

Sets and prepares the controller display group -- the display group that contains the receiver itself. The controller display group can be used to connect methods of the controller to the user interface through associations. This method takes care of placing the receiver in the display group and registering the controller as observer for itself in the EOObserverCenter, so that the controller can receive objectWillChange methods if its values are edited through associations of the controller display group.

Parameters:

displayGroup - the display group to be used as controller display group for the receiver

See Also:

controllerDisplayGroup(), objectWillChange(Object)

setDisplayGroup

public void setDisplayGroup(EODisplayGroup displayGroup)

Sets the display group used by this controller. If the controller used a different display group before, it invokes stopListeningToDisplayGroup first. After setting the new display group, it invokes startListeningToDisplayGroup.

Parameters:

displayGroup - the display group to be used by this controller

See Also:

displayGroup(), startListeningToDisplayGroup(), stopListeningToDisplayGroup()

setDisplayGroupProviderMethodName

public void setDisplayGroupProviderMethodName(String string)

Sets the provider method which is used to retrieve the display group for the reveiver. EOEntityController provides two useful methods you can use for the editing context provider method name: newDisplayGroup and newDisplayGroupUsingOptimisticRefresh. See the EOEntityController class description for how to specify a provider method.

Parameters:

string - the provider method used to retrieve the display group for the receiver

See Also:

displayGroupProviderMethodName(), displayGroup(), newDisplayGroup(), newDisplayGroupUsingOptimisticRefresh()

setEditingContext

public void setEditingContext(EOEditingContext editingContext)

Sets the editing context used by this controller. If the controller used a different editing context before, it invokes stopListeningToEditingContext first. After setting the new editing context, it invokes startListeningToEditingContext.

Parameters:

editingContext - the editing context to be used by this controller

See Also:

editingContext(), startListeningToEditingContext(), stopListeningToEditingContext()

setEditingContextProviderMethodName

public void setEditingContextProviderMethodName(String string)

Sets the provider method which is used to retrieve the editing context for the reveiver. EOEntityController provides two useful methods you can use for the editing context provider method name: newEditingContext and nestedEditingContext. See the EOEntityController class description for how to specify a provider method.

Parameters:

string - the provider method used to retrieve the editing context for the receiver

See Also:

editingContextProviderMethodName(), editingContext(), newEditingContext(), nestedEditingContext()

setEntityName

public void setEntityName(String string)

Sets the entity name of the enterprise objects displayed by the receiver.

Parameters:

string - the entity name of the enterprise objects displayed by the receiver

setFetchesOnConnect

public void setFetchesOnConnect(boolean flag)

Sets whether the receiver should fetch its display group content next time its connection is established. This value changes often: Whenever an entity controller prepares for a new task, it sets this flag to true. Once it retrieves objects explicitly (for example from a global ID) or actually performs the fetch while connecting, it sets this flag to false.

Parameters:

flag - true if the controller should fetch its display group content next time its connection is established; false otherwise

See Also:

fetchesOnConnect()

setObjectWithGlobalID

public void setObjectWithGlobalID(EOGlobalID globalID)

Fetches the objects specified by the global ID globalID into the receiver's display group.

Parameters:

globalID - the global ID specifying the object to be fetched

setObjectsWithFetchSpecification

public void setObjectsWithFetchSpecification(EOFetchSpecification fetchSpecification)

Fetches the objects specified by fetchSpecification into the receiver's display group.

Parameters:

fetchSpecification - the fetch specifiation to fetch objects

setResetsEditingContextWhenPreparingForNewTask

public void setResetsEditingContextWhenPreparingForNewTask(boolean flag)

Sets whether the receiver should reset its editing context when preparing for a new task in prepareForNewTask(boolean). The default is true.

Parameters:

flag - true if the controller resets its editing context while preparing for a new task; false otherwise

startListeningToDisplayGroup

protected void startListeningToDisplayGroup()

Invoked from setDisplayGroup whenever a new display group is specified, giving the receiver a chance to react. EOEntityController's default implementation registers itself as observer for the display group in the EOObserverCenter. When this method is invoked, displayGroup already returns the new display group of the controller.

See Also:

displayGroup(), setDisplayGroup(EODisplayGroup), stopListeningToDisplayGroup()

startListeningToEditingContext

protected void startListeningToEditingContext()

Invoked from setEditingContext whenever a new editing context is specified, giving the receiver a chance to react. EOEntityController's default implementation registers for its handleEditingContextNotification method as receiver for the notifications EOEditingContext.ObjectsChangedInEditingContextNotification and EOEditingContext.EditingContextDidSaveChangesNotification. When this method is invoked, editingContext already returns the new editing context of the controller.

See Also:

editingContext(), setEditingContext(EOEditingContext), stopListeningToEditingContext()

stopListeningToDisplayGroup

protected void stopListeningToDisplayGroup()

Invoked from setDisplayGroup whenever a display group is cleared out (if either a new display group is specified or if the display group is reset to null), giving the receiver a chance to react. EOEntityController's default implementation unregisters itself as observer from the display group (as registered in startListeningToDisplayGroup). When this method is invoked, displayGroup still returns the old display group of the controller.

See Also:

displayGroup(), setDisplayGroup(EODisplayGroup), startListeningToDisplayGroup()

stopListeningToEditingContext

protected void stopListeningToEditingContext()

Invoked from setEditingContext whenever an editing context is cleared out (if either a new editing context is specified or if the editing context is reset to null), giving the receiver a chance to react. EOEntityController's default implementation unregisters the notficiations registered in startListeningToEditingContext. When this method is invoked, editingContext still returns the old editing context of the controller.

See Also:

editingContext(), setEditingContext(EOEditingContext), startListeningToEditingContext()

takeResposibilityForConnectionOfAssociation

public void takeResposibilityForConnectionOfAssociation(EOAssociation association)

Conformance to EOAssociationConnector. Takes responsibility of managing the connection for the association association. See the method description of takeResposibilityForConnectionOfAssociation in the interface specification for EOAssociationConnector.

Specified by:

takeResposibilityForConnectionOfAssociation in interface EOAssociationConnector

Parameters:

association - the association to manage the editability for

See Also:

EOAssociationConnector.takeResposibilityForConnectionOfAssociation(EOAssociation)

toString

public String toString()

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

Overrides:

toString in class EOComponentController

Returns:

the String representation of the receiver

willChange

public void willChange()

Triggers EOObserverCenter change notifications for the controller itself. Invoke this method if you want to receive objectWillChange methods for the controller if it's edited through an association of the controller display group.

See Also:

objectWillChange(Object)