com.webobjects.eoapplication
Class EOEntityController

java.lang.Object
  |
  +--com.webobjects.eoapplication.EOController
        |
        +--com.webobjects.eoapplication.EOComponentController
              |
              +--com.webobjects.eoapplication.EOArchiveController
                    |
                    +--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 EOArchiveController

implements EOObjectDisplay, EOAssociationConnector

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.

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 Methods

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. To use a method on a supercontroller, prepend a "^", for example ^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.

Nested Class Summary

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

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

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

EOController.Enumeration

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

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

Nested 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, ControllerAndSupercontrollersEnumeration, 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

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.
protected void	controllerWillLoadArchive() Invoked from loadArchive to notify the receiver that its interface file is about to be loaded.
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() Returns the name of the entity of the enterprise objects displayed in the receiver's display group.
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	isFetchesOnConnectEnabled() Returns whether the receiver should ever fetch its display group content when a connection is established.
boolean	isRootEntityController() Returns whether the receiver is a root entity controller (which is the case if none of the supercontrollers conform to EOObjectDisplay).
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	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	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	setFetchesOnConnectEnabled(boolean flag) Sets whether the receiver should ever fetch its display group content when a connection is established.
void	setObjectsWithFetchSpecification(EOFetchSpecification fetchSpecification) Fetches the objects specified by fetchSpecification into the receiver's display group.
void	setObjectsWithGlobalIDs(NSArray globalIDs) Fetches the objects specified by the global IDs in globalIDs into the receiver's display group.
void	setObjectWithGlobalID(EOGlobalID globalID) Fetches the object 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) Invoked when one of the receiver's subcontrollers is disposed as a transient controller.
String	toString() Returns the receiver as a string describing the state of the controller.

Methods inherited from class com.webobjects.eoapplication.EOArchiveController

archiveName, controllerDisplayGroup, hasControllerDisplayGroup, loadArchive, objectWillChange, prepareComponent, setArchiveName, setControllerDisplayGroup, willChange

Methods inherited from class com.webobjects.eoapplication.EOComponentController

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

Methods inherited from class com.webobjects.eoapplication.EOController

actionNames, actions, actionWithName, additionalActions, additionalKeyValuePairs, 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, setAdditionalActions, setAdditionalKeyValuePair, setAdditionalKeyValuePairs, 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

Methods inherited from interface com.webobjects.eoapplication.EOObjectDisplay

controllerDisplayGroup

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

connectionWasBroken

protected void connectionWasBroken()

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

Overrides:

connectionWasBroken in class 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

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.

Overrides:

controllerDidLoadArchive in class EOArchiveController

Parameters:

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

See Also:

EOArchiveController.loadArchive()

controllerWillLoadArchive

protected void controllerWillLoadArchive()

Invoked from loadArchive to notify the receiver that its interface file is about to be loaded. You can override this method to perform additional preparation for the archive loading process.

Overrides:

controllerWillLoadArchive in class EOArchiveController

See Also:

EOArchiveController.loadArchive()

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.

Specified by:

dispose in interface NSDisposable

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

Overrides:

endEditing in class EOArchiveController

Returns:

true if all uncommitted changes were successfully flushed; false otherwise

entityName

public String entityName()

Description copied from interface: EOObjectDisplay

Returns the name of the entity of the enterprise objects displayed in the receiver's display group.

Specified by:

entityName in interface EOObjectDisplay

Returns:

the name of the entity of the enterprise objects displayed

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

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

isFetchesOnConnectEnabled

public boolean isFetchesOnConnectEnabled()

Returns whether the receiver should ever fetch its display group content when a connection is established.

Returns:

true if the controller will use fetchesOnConnect() to decide whether or not to fetch its display group content next time its connection is established; false if the controller will never fetch its display group content when a connection is established

See Also:

setFetchesOnConnectEnabled(boolean), #fetchesOnConnect(boolean)

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

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:

EOArchiveController.loadArchive()

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

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

setFetchesOnConnectEnabled

public void setFetchesOnConnectEnabled(boolean flag)

Sets whether the receiver should ever fetch its display group content when a connection is established.

Parameters:

flag - true if the controller should use fetchesOnConnect() to decide whether or not to fetch its display group content next time its connection is established; false if the controller should never fetch its display group content when a connection is established

See Also:

fetchesOnConnect(), isFetchesOnConnectEnabled()

setObjectWithGlobalID

public void setObjectWithGlobalID(EOGlobalID globalID)

Fetches the object 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

setObjectsWithGlobalIDs

public void setObjectsWithGlobalIDs(NSArray globalIDs)

Fetches the objects specified by the global IDs in globalIDs into the receiver's display group.

Parameters:

globalIDs - the array of global IDs specifying the object to be fetched

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)

Description copied from interface: EOAssociationConnector

Invoked when one of the receiver's subcontrollers is disposed as a transient controller. Instructs the receiver to assume responsibility for managing the subcontroller's EOAssociation, association.

Specified by:

takeResposibilityForConnectionOfAssociation in interface EOAssociationConnector

Parameters:

association - the transient subcontroller's EOAssociation

toString

public String toString()

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

Overrides:

toString in class EOArchiveController

Returns:

the String representation of the receiver