EODocumentController

Inherits from:
EOEntityController : EOComponentController : EOController

Implements:
EODocument
EOEditable
EOAssociationConnector (Inherited from EOEntityController)
EOComponentController.EndEditing (Inherited from EOEntityController)
EOObserving (Inherited from EOEntityController)
EOObjectDisplay (Inherited from EOEntityController)
NSInlineObservable (Inherited from EOController)
NSDisposable (Inherited from EOController)
EOKeyValueCodingAdditions (Inherited from EOController)
EOAction.Enabling (Inherited from EOController)
EOKeyValueCoding (Inherited from EOKeyValueCodingAdditions)
NSKeyValueCoding (Inherited from EOKeyValueCoding)

Package:
com.webobjects.eoapplication

Class Description

The EODocumentController class provides behavior for displaying and editing enterprise objects in a user interface. EODocumentController's API is mostly specified by the interfaces EODocument and EOEditable. Additionally, much of the way that EODocumentController works is set up by its superclass, EOEntityController. Since EOEntityControllers use EOEditingContexts and EODisplayGroups to manage and display a set of enterprise objects; EODocumentControllers use them as well. However, in addition to displaying enterprise objects, document controllers can also edit their objects. You can insert, update, and delete enterprise objects; undo and redo unsaved changes; and save and revert.

EODocumentController provides several methods that interact with a user. For example, the methods revert and saveIfUserConfirms open dialogs to confirm that a user wants to revert or save before performing the action. Also, many of the methods open dialogs when an error occurs, telling the user what happened.

Root Document Controller Responsibilities

EODocumentController defines the concept of a root document controller. A document controller is the root if none of its ancestors are EODocuments. A root document controller usually provides the editing context for all its descendent document controllers-they typically don't have their own. Consequently, the root document controller has responsibilities that non-root document controllers don't have. For example, only the root document controller provides save and revert behavior.

Rule System and XML Description

The following tables identify the controllerType, XML tag, and XML attributes used by the rule system and EOXMLUnarchiver to generate a controller hierarchy. For more information, see the section "Rule System and XML Description" (page 8) in the package introduction.

Default Rule System Controller Type

entityController

XML Tag

DOCUMENTCONTROLLER

XML Attribute	Value	Description
`editability`	string	One of "Never", "Always", or "IfSupercontroller". See the EOEditable interface specification for more information on these settings.

Interfaces Implemented

EODocument
isDocumentForGlobalID
isEdited
save
saveIfUserConfirms
setEdited

EOEditable
editability
isEditable
setEditability
supercontrollerEditabilityDidChange
takeResponsibilityForEditabilityOfAssociation

EOAssociationConnector (Inherited from EOEntityController)

EOComponentController.EndEditing (Inherited from EOEntityController)

EOObserving (Inherited from EOEntityController)

EOObjectDisplay (Inherited from EOEntityController)

NSInlineObservable (Inherited from EOController)

NSDisposable (Inherited from EOController)
dispose

EOKeyValueCodingAdditions (Inherited from EOController)

EOAction.Enabling (Inherited from EOController)
canPerformActionNamed

EOKeyValueCoding (Inherited from EOKeyValueCodingAdditions)

NSKeyValueCoding (Inherited from EOKeyValueCoding)

Method Types

Constructors
EODocumentController
Inserting, updating, and deleting
insertObject
deleteSelectedObjects
wasEdited
Saving
canSave
saveChanges
saveAndMakeInvisible
saveIfUserConfirms
saveIfUserConfirmsAndMakeInvisible
saveIfUserConfirmsAndMakeInvisible
saveFailed
Reverting
canRevert
revert
revertAndMakeInvisible
revertChanges
revertFailed
Undoing and Redoing
canUndo
undo
canRedo
redo
Determining the root document controller
isRootDocumentController
Methods inherited from EOEntityController
handleEditingContextNotification
Methods inherited from EOController
connectionWasEstablished
defaultActions
prepareForNewTask
Methods inherited from Object
toString

Constructors

EODocumentController

public EODocumentController()

public EODocumentController(EOXMLUnarchiver unarchiver)

Creates a new document controller. For information on how these constructors are used and on what they do, see the method description for the EOController constructors in the EOController class specification.

Instance Methods

canPerformActionNamed

public boolean canPerformActionNamed(String actionName)

Conformance to EOAction.Enabling. EODocumentController's implementation uses the methods canRedo, canRevert, canSave, and canUndo to determine the enabling state of the corresponding actions.

See Also: canPerformActionNamed (EOAction.Enabling)

canRedo

public boolean canRedo()

Returns true if the receiver can redo, false otherwise. A document controller can redo as long as its editing context's undo manager can redo and as long as it (or one of its subcontrollers) is editable.

canRevert

public boolean canRevert()

Returns true if the receiver can revert, false otherwise. A document controller can revert only if it's been edited and only if it's the root document controller.

canSave

public boolean canSave()

Returns true if the receiver can save, false otherwise. A document controller can save only if it's been edited and only if it's the root document controller.

canUndo

public boolean canUndo()

Returns true if the receiver can undo, false otherwise. A document controller can undo as long as its editing context's undo manager can undo and as long as it (or one of its subcontrollers) is editable.

connectionWasEstablished

protected void connectionWasEstablished()

See the method description for connectionWasEstablished in the EOController class specification. EODocumentController's implementation additionally updates its editability.

defaultActions

protected NSArray defaultActions()

Adds actions for handling editing to the default actions defined by the superclass, EOEntityController. More specifically, it adds save and revert actions. However, note that defaultActions only adds save and revert if the receiver is the root document controller, if it's editable, and if it's not modal.

deleteSelectedObjects

public void deleteSelectedObjects()

Deletes the objects selected in the receiver's display group and then sets the receiver's edited state to true.

dispose

public void dispose()

Conformance to NSDisposable. See the method description of dispose in the interface specification for NSDisposable.

editability

public int editability()

Conformance to EOEditable. See the method description of editability in the interface specification for EOEditable.

handleEditingContextNotification

public void handleEditingContextNotification(NSNotification notification)

See the method description for handleEditingContextNotification in the EOEntityController class specification. EODocumentController's implementation additionally updates its edited state if the receiver is a root document controller.

insertObject

public void insertObject()

Creates a new enterprise object, inserts it into the receiver's display group, and sets the receiver's edited status to true.

isDocumentForGlobalID

public boolean isDocumentForGlobalID( com.webobjects.eocontrol.EOGlobalID globalID, String entityName)

Conformance to EODocument. See the method description of isDocumentForGlobalID in the interface specification for EODocument.

isEditable

public boolean isEditable()

Conformance to EOEditable. See the method description of isEditable in the interface specification for EOEditable.

isEdited

public boolean isEdited()

Conformance to EODocument. See the method description of isEdited in the interface specification for EODocument.

isRootDocumentController

public boolean isRootDocumentController()

Returns true if none of the supercontrollers are EODocuments, false otherwise.

prepareForNewTask

public void prepareForNewTask(boolean flag)

See the method description for prepareForNewTask in the EOController class specification. EODocumentController's implementation additionally sets its edited state to false.

redo

public void redo()

Tells the receiver's editing context to redo.

revert

public boolean revert()

Reverts the receiver's unsaved changes upon user confirmation. If the receiver has been edited, opens a dialog to verify that the user wants to revert. Upon confirmation, invokes revertChanges requesting an error dialog upon failure. Returns true on success, false upon failure or if the user cancels the revert.

revertAndMakeInvisible

public boolean revertAndMakeInvisible()

Reverts the receiver's unsaved changes and makes the receiver invisible. Reverts by invoking revertChanges, requesting an error dialog upon failure Returns true if changes are successfully reverted, false if the receiver can't be reverted or if the revert fails.

revertChanges

public boolean revertChanges(boolean showErrorDialog)

Tells the receiver's editing context to revert, refetches if necessary, and sets the receiver's editing state to false. If the revert fails, catches the exception and, if showErrorDialog is true, invokes revertFailed to show the reason for failure. Returns true if the revert succeeds, false otherwise.

revertFailed

protected void revertFailed( Exception exception, boolean showErrorDialog)

If showErrorDialog is true, brings the receiver's user interface to the front and opens a dialog displaying exception's class name and exception message. Invoked from revertChanges.

save

public boolean save()

Saves the receiver's changes. Saves by invoking saveChanges, requesting an error dialog upon failure Returns true if changes are successfully saved, false if the receiver can't save or if the save fails.

saveAndMakeInvisible

public boolean saveAndMakeInvisible()

Saves the receiver's changes and makes the receiver invisible. Saves by invoking saveChanges, requesting an error dialog upon failure Returns true if changes are successfully reverted, false if the receiver can't be reverted or if the revert fails.

saveChanges

public boolean saveChanges( boolean showErrorDialog, String saveOperationTitle)

Tells the receiver's editing context to save changes and sets the receiver's editing state to false. If the save fails, catches the exception and, if showErrorDialog is true, invokes saveFailed to show the reason for failure. Returns true if the save succeeds, false otherwise.

saveFailed

protected void saveFailed( Exception showErrorDialog, boolean showErrorDialog, String saveOperationTitle)

If showErrorDialog is true, brings the receiver's user interface to the front and opens a dialog displaying exception's class name and exception message. Invoked from saveChanges.

saveIfUserConfirms

public boolean saveIfUserConfirms( String operationTitle, String message)

public boolean saveIfUserConfirms()

Saves the receiver's unsaved changes upon user confirmation. If the receiver has been edited, opens a dialog to verify that the user wants to save. If operationTitle and message are provided, they are used as the dialog title and message; otherwise, "Save" and "Save Changes?" are used. Upon confirmation, invokes saveChanges requesting an error dialog upon failure. Returns true on success, false upon failure or if the user cancels the save.

saveIfUserConfirmsAndMakeInvisible

public boolean saveIfUserConfirmsAndMakeInvisible( String operationTitle, String message)

public boolean saveIfUserConfirmsAndMakeInvisible()

Saves the receiver's unsaved changes upon user confirmation and makes the receiver invisible. Saves by invoking saveIfUserConfirms, requesting an error dialog upon failure. The arguments operationTitle and message are used as the title and message of the confirmation panel. "Save" and "Save changes?" are substituted for null. If the no-argument form of this method is invoked, then the title of the confirmation dialog is "Close" and the dialog has no message. Returns true if changes are successfully saved, false if the receiver can't be saved or if the save fails.