WebObjects 5.2.3

com.webobjects.eoapplication
Class EOEntityController

java.lang.Object
  extended bycom.webobjects.eoapplication.EOController
      extended bycom.webobjects.eoapplication.EOComponentController
          extended bycom.webobjects.eoapplication.EOArchiveController
              extended bycom.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()

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

Last updated Thu Oct 21 15:04:16 PDT 2004.

Copyright © 2004 Apple Computer, Inc.