com.webobjects.eoapplication
Class EODocumentController

java.lang.Object
  com.webobjects.eoapplication.EOController
      com.webobjects.eoapplication.EOComponentController
          com.webobjects.eoapplication.EOArchiveController
              com.webobjects.eoapplication.EOEntityController
                  com.webobjects.eoapplication.EODocumentController

All Implemented Interfaces:

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

Direct Known Subclasses:

EOEditingController, EOInterfaceController

public class EODocumentController

extends EOEntityController

implements EOObjectDisplayDocument, EOEditable

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 also edit the displayed objects. You can insert, update, and delete enterprise objects; undo and redo unsaved changes; and save and revert.

EODocumentController provides several action methods to 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.

EODocumentController defines the concept of a root document controller. A document controller is the root document controller if none of its supercontrollers conform to EODocument. A root document controller usually provides the editing context for all its descendent document controllers -- the subcontrollers typically don't create 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.

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

Fields inherited from class com.webobjects.eoapplication.EOEntityController

NestedEditingContextProviderMethodName, NewDisplayGroupProviderMethodName, NewDisplayGroupUsingOptimisticRefreshProviderMethodName, NewEditingContextProviderMethodName

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.eoapplication.EOEditable

AlwaysEditable, IfSupercontrollerEditable, NeverEditable

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

EODocumentController()
Creates a new document controller.

EODocumentController(EOXMLUnarchiver unarchiver)
Creates a new document controller from an EOXMLUnarchiver.

Method Summary

boolean	canPerformActionNamed(String actionName) Overridden to handle editing-related action enabling and disabling.
boolean	canRedo() Returns whether the receiver can redo.
boolean	canRevert() Returns whether the receiver can revert.
boolean	canSave() Returns whether the receiver can save.
boolean	canUndo() Returns whether the receiver can undo.
protected void	connectionWasEstablished() Reacts to the connection for the receiver being established, taking care of editability issues in addition to the superclass implementation.
protected NSArray	defaultActions() Adds actions for handling editing (like save, revert) the default actions defined by the superclass, EOEntityController (but only if the receiver is a root document controller and if it's not used in a modal dialog.
void	deleteSelectedObjects() Deletes the objects selected in the receiver's display group and updates the edited status to true.
void	dispose() Prepares the receiver so it is disposed when Java performs garbage collection.
int	editability() Returns the editability of the receiver.
void	handleEditingContextNotification(NSNotification notification) In addition to the superclass implementation, updates the edited state of the receiver based on changes that happened in the receiver's editing context.
void	insertObject() Creates a new enterprise object, inserts it into the receiver's display group and updates the edited status to true.
boolean	isDocumentForGlobalID(EOGlobalID globalID, String entityName) Conformance to EODocument.
boolean	isEditable() Returns whether the receiver is currently editable.
boolean	isEdited() Returns the receiver's edited state.
boolean	isRootDocumentController() Returns whether the receiver is a root document controller (which is the case if none of the supercontrollers conform to EODocument).
void	prepareForNewTask(boolean prepareSubcontrollersForNewTask) Prepares the receiver for performing a new task by resetting any data and resetting it's edited state.
void	redo() Tells the receiver's editing context to redo the last editing state.
boolean	revert() Reverts the receiver's editing context changes by invoking revertChanges, requesting an error dialog upon failure.
boolean	revertAndMakeInvisible() Attempts to revert the receiver's editing context changes and makes the receiver's user interface invisible if the revert succeeded (which usually results in a window closing).
boolean	revertChanges(boolean showErrorDialog) Tells the receiver's editing context to revert changes and updates the receiver's editing state on success.
protected void	revertFailed(Exception exception, boolean showErrorDialog) Invoked from revertChanges if the revert failed.
boolean	save() Saves the receiver's editing context changes by invoking saveChanges, requesting an error dialog upon failure.
boolean	saveAndMakeInvisible() Attempts to save the receiver's editing context changes and makes the receiver's user interface invisible if the save succeeded (which usually results in a window closing).
boolean	saveChanges(boolean showErrorDialog, String saveOperationTitle) Tells the receiver's editing context to save changes and updates the receiver's editing state on success.
protected void	saveFailed(Exception exception, boolean showErrorDialog, String saveOperationTitle) Invoked from saveChanges if the save failed.
boolean	saveIfUserConfirms() Invokes saveIfUserConfirms(boolean, String) with default values for a normal save operation.
boolean	saveIfUserConfirms(String operationTitle, String message) Presents an alert panel asking the user whether the receiver's editing context changes should be saved or not (operationTitle is used as a description of the operation, message as the question displayed in the alert panel).
boolean	saveIfUserConfirmsAndMakeInvisible() Invokes saveIfUserConfirmsAndMakeInvisible(String, String) with default values for a normal save & close operation.
boolean	saveIfUserConfirmsAndMakeInvisible(String operationTitle, String message) Invokes saveIfUserConfirms(boolean, String) and makes the receiver's user interface invisible if the save succeeded (which usually results in a window closing).
void	setEditability(int editability) Sets the editability of the receiver to editability.
void	setEdited(boolean flag) Conformance to EODocument.
void	supercontrollerEditabilityDidChange() Invoked to notify the receiver that the editability of its supercontroller changed, giving the receiver the opportunity to update its user interface to match the editability of the supercontroller.
void	takeResponsibilityForEditabilityOfAssociation(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.
void	undo() Tells the receiver's editing context to undo the last editing state.
protected void	wasEdited() Invoked from setEdited to notify the receiver that edited status has changed, giving the receiver the opportunity to react.

Methods inherited from class com.webobjects.eoapplication.EOEntityController

connectionWasBroken, controllerDidLoadArchive, controllerWillLoadArchive, displayGroup, displayGroupProviderMethodName, displayGroupSortOrderings, editingContext, editingContextProviderMethodName, endEditing, entityName, establishConnection, fetchesOnConnect, isFetchesOnConnectEnabled, isRootEntityController, nestedEditingContext, newDataSource, newDisplayGroup, newDisplayGroupUsingOptimisticRefresh, newEditingContext, objectForOutletPath, resetsEditingContextWhenPreparingForNewTask, selectedObject, selectedObjectGlobalID, selectedObjects, selectedObjectsGlobalIDs, setDisplayGroup, setDisplayGroupProviderMethodName, setEditingContext, setEditingContextProviderMethodName, setEntityName, setFetchesOnConnect, setFetchesOnConnectEnabled, setObjectsWithFetchSpecification, setObjectsWithGlobalIDs, setObjectWithGlobalID, setResetsEditingContextWhenPreparingForNewTask, startListeningToDisplayGroup, startListeningToEditingContext, stopListeningToDisplayGroup, stopListeningToEditingContext, takeResposibilityForConnectionOfAssociation

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, controllerEnumeration, controllersInEnumeration, controllersWithKeyValuePair, controllersWithKeyValuePairs, controllerWithKeyValuePair, controllerWithKeyValuePairs, 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, displayGroup, editingContext, entityName

Constructor Detail

EODocumentController

public EODocumentController()

Creates a new document controller.

EODocumentController

public EODocumentController(EOXMLUnarchiver unarchiver)

Creates a new document controller from an EOXMLUnarchiver.

Parameters:

unarchiver - the unarchiver providing XML attributes

Method Detail

canPerformActionNamed

public boolean canPerformActionNamed(String actionName)

Overridden to handle editing-related action enabling and disabling.

Specified by:

canPerformActionNamed in interface EOAction.Enabling

Overrides:

canPerformActionNamed in class EOController

Parameters:

actionName - the action method name

Returns:

true if the action should be enabled; false otherwise

See Also:

EOAction.Enabling

canRedo

public boolean canRedo()

Returns whether the receiver can redo. 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.

Returns:

true if the controller can undo; false otherwise

canRevert

public boolean canRevert()

Returns whether the receiver can revert. A document controller can revert only if it's the root document controller and if it's edited.

Returns:

true if the controller can revert; false otherwise

canSave

public boolean canSave()

Returns whether the receiver can save. A document controller can save only if it's the root document controller and if it's edited.

Returns:

true if the controller can save; false otherwise

canUndo

public boolean canUndo()

Returns whether the receiver can undo. 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.

Returns:

true if the controller can undo; false otherwise

connectionWasEstablished

protected void connectionWasEstablished()

Reacts to the connection for the receiver being established, taking care of editability issues in addition to the superclass implementation.

Overrides:

connectionWasEstablished in class EOEntityController

defaultActions

protected NSArray defaultActions()

Adds actions for handling editing (like save, revert) the default actions defined by the superclass, EOEntityController (but only if the receiver is a root document controller and if it's not used in a modal dialog.

Overrides:

defaultActions in class EOController

Returns:

an array of the receiver's default actions

See Also:

EOController.actions(), EOController.resetActions()

deleteSelectedObjects

public void deleteSelectedObjects()

Deletes the objects selected in the receiver's display group and updates the edited status to true.

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 EOEntityController

editability

public int editability()

Description copied from interface: EOEditable

Returns the editability of the receiver. The default behavior should be to return EOEditable.IfSupercontrollerEditable.

Specified by:

editability in interface EOEditable

Returns:

the editability, one of EOEditable.NeverEditable, EOEditable.AlwaysEditable, or EOEditable.IfSupercontrollerEditable

handleEditingContextNotification

public void handleEditingContextNotification(NSNotification notification)

In addition to the superclass implementation, updates the edited state of the receiver based on changes that happened in the receiver's editing context.

Overrides:

handleEditingContextNotification in class EOEntityController

Parameters:

notification - the editing context notification

See Also:

EOEntityController.startListeningToEditingContext()

insertObject

public void insertObject()

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

isDocumentForGlobalID

public boolean isDocumentForGlobalID(EOGlobalID globalID,
                                     String entityName)

Conformance to EODocument. Returns whether the receiver is a document for the enterprise object associated with globalID and entityName. See the method description of isDocumentForGlobalID in the interface specification for EODocument. EODocumentController's default implementation returns true if the receiver is a root document controller and receiver's display group displays only the specified object. Subclasses might have to override this method to return false, for example list controllers can't really be documents for a single object and should return false.

Specified by:

isDocumentForGlobalID in interface EODocument

Parameters:

globalID - the EOGlobalID of the enterprise object

entityName - the name of the entity of the enterprise object

Returns:

true if the receiver is a root document controller and its display group is displaying only the specified enteprise object; false otherwise

See Also:

EODocument.isDocumentForGlobalID(EOGlobalID, String)

isEditable

public boolean isEditable()

Description copied from interface: EOEditable

Returns whether the receiver is currently editable. A receiver is editable if its editability is EOEditable.AlwaysEditable or its editability is EOEditable.IfSupercontrollerEditable and sending EOEditable.isEditable to the first EOEditable supercontroller of the receiver returns true.

Specified by:

isEditable in interface EOEditable

Returns:

true if the controller is currently editable; false otherwise

isEdited

public boolean isEdited()

Description copied from interface: EODocument

Returns the receiver's edited state.

Specified by:

isEdited in interface EODocument

Returns:

true if the controller is edited (and unsaved); false otherwise

isRootDocumentController

public boolean isRootDocumentController()

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

Returns:

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

prepareForNewTask

public void prepareForNewTask(boolean prepareSubcontrollersForNewTask)

Prepares the receiver for performing a new task by resetting any data and resetting it's edited state.

Overrides:

prepareForNewTask in class EOEntityController

Parameters:

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

redo

public void redo()

Tells the receiver's editing context to redo the last editing state.

revert

public boolean revert()

Reverts the receiver's editing context changes by invoking revertChanges, requesting an error dialog upon failure. Returns whether the revert succeeded.

Returns:

true if the revert succeeded; false otherwise

See Also:

revertChanges(boolean)

revertAndMakeInvisible

public boolean revertAndMakeInvisible()

Attempts to revert the receiver's editing context changes and makes the receiver's user interface invisible if the revert succeeded (which usually results in a window closing). The user is not given the choice to cancel the operation.

Returns:

true if the save succeeded; false if the save failed or the user chose to not save

revertChanges

public boolean revertChanges(boolean showErrorDialog)

Tells the receiver's editing context to revert changes and updates the receiver's editing state on success. If the revert fails, catches the exception and invokes revertFailed to show the reason for failure. Returns whether the revert succeeded.

Parameters:

showErrorDialog - true if the controller should show a dialog if the revert fails; false otherwise

Returns:

true if the revert succeeded; false otherwise

See Also:

revertFailed(Exception, boolean)

revertFailed

protected void revertFailed(Exception exception,
                            boolean showErrorDialog)

Invoked from revertChanges if the revert failed. 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. This method can be overridden by subclasses to handle revert errors in a special way.

Parameters:

exception - the exception causing the save error

showErrorDialog - true if the controller should show an error dialog; false otherwise

See Also:

revertChanges(boolean)

save

public boolean save()

Saves the receiver's editing context changes by invoking saveChanges, requesting an error dialog upon failure. Returns whether the save succeeded.

Specified by:

save in interface EODocument

Returns:

true if the save succeeded; false otherwise

See Also:

saveChanges(boolean, String)

saveAndMakeInvisible

public boolean saveAndMakeInvisible()

Attempts to save the receiver's editing context changes and makes the receiver's user interface invisible if the save succeeded (which usually results in a window closing). The user is not given the choice to cancel the operation.

Returns:

true if the save succeeded; false if the save failed or the user chose to not save

saveChanges

public boolean saveChanges(boolean showErrorDialog,
                           String saveOperationTitle)

Tells the receiver's editing context to save changes and updates the receiver's editing state on success. If the save fails, catches the exception and invokes saveFailed to show the reason for failure. Returns whether the save succeeded.

Some applications need to disable undo operations after a save. You can override this method to do so, for example:

  public boolean saveChanges(boolean showErrorDialog, String saveOperationTitle) {
      if (super.saveChanges(showErrorDialog, saveOperationTitle)) {
          editingContext().undoManager().removeAllActions();
      }
  }
 

Parameters:

showErrorDialog - true if the controller should show a dialog if the save fails; false otherwise

saveOperationTitle - a description of the operation causing the save

Returns:

true if the save succeeded; false otherwise

See Also:

saveFailed(Exception, boolean, String)

saveFailed

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

Invoked from saveChanges if the save failed. 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. This method can be overridden by subclasses to handle save errors in a special way.

Parameters:

exception - the exception causing the save error

showErrorDialog - true if the controller should show an error dialog; false otherwise

saveOperationTitle - a description of the operation causing the save

See Also:

saveChanges(boolean, String)

saveIfUserConfirms

public boolean saveIfUserConfirms(String operationTitle,
                                  String message)

Presents an alert panel asking the user whether the receiver's editing context changes should be saved or not (operationTitle is used as a description of the operation, message as the question displayed in the alert panel). The user can choose to save or not to save. Returns whether the changes were saved successfully.

Specified by:

saveIfUserConfirms in interface EODocument

Parameters:

operationTitle - a description of the operation

message - a message to be displayed to the user

Returns:

true if the save succeeded; false if the save failed or the user chose to not save

See Also:

saveChanges(boolean, String)

saveIfUserConfirms

public boolean saveIfUserConfirms()

Invokes saveIfUserConfirms(boolean, String) with default values for a normal save operation.

Returns:

true if the save succeeded; false if the save failed or the user chose to not save

See Also:

saveIfUserConfirms(String, String)

saveIfUserConfirmsAndMakeInvisible

public boolean saveIfUserConfirmsAndMakeInvisible(String operationTitle,
                                                  String message)

Invokes saveIfUserConfirms(boolean, String) and makes the receiver's user interface invisible if the save succeeded (which usually results in a window closing).

Parameters:

operationTitle - a description of the operation

message - a message to be displayed to the user

Returns:

true if the save succeeded; false if the save failed or the user chose to not save

See Also:

saveIfUserConfirms(String, String), EOComponentController.makeInvisible()

saveIfUserConfirmsAndMakeInvisible

public boolean saveIfUserConfirmsAndMakeInvisible()

Invokes saveIfUserConfirmsAndMakeInvisible(String, String) with default values for a normal save & close operation.

Returns:

true if the save succeeded; false if the save failed or the user chose to not save

See Also:

saveIfUserConfirmsAndMakeInvisible(String, String)

setEditability

public void setEditability(int editability)

Description copied from interface: EOEditable

Sets the editability of the receiver to editability. See the method description of setEditability in the interface specification for EOEditable.

Specified by:

setEditability in interface EOEditable

Parameters:

editability - the editability, one of EOEditable.NeverEditable, EOEditable.AlwaysEditable, or EOEditable.IfSupercontrollerEditable

setEdited

public void setEdited(boolean flag)

Conformance to EODocument. Sets the receiver's edited state. See the method description of setEdited in the interface specification for EODocument. EODocumentController's default implementation only updates the edited state of the receiver if it's a root document controller, otherwise it asks the root document controller to handle the edited state.

Specified by:

setEdited in interface EODocument

Parameters:

flag - true if the controller is edited (and unsaved); false otherwise

See Also:

EODocument.setEdited(boolean)

supercontrollerEditabilityDidChange

public void supercontrollerEditabilityDidChange()

Description copied from interface: EOEditable

Invoked to notify the receiver that the editability of its supercontroller changed, giving the receiver the opportunity to update its user interface to match the editability of the supercontroller. This method is only sent to connected subcontrollers whose editability is EOEditable.IfSupercontrollerEditable.

Specified by:

supercontrollerEditabilityDidChange in interface EOEditable

takeResponsibilityForEditabilityOfAssociation

public void takeResponsibilityForEditabilityOfAssociation(EOAssociation association)

Description copied from interface: EOEditable

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

Specified by:

takeResponsibilityForEditabilityOfAssociation in interface EOEditable

Parameters:

association - the transient subcontroller's association

toString

public String toString()

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

Overrides:

toString in class EOEntityController

Returns:

the String representation of the receiver

undo

public void undo()

Tells the receiver's editing context to undo the last editing state.

wasEdited

protected void wasEdited()

Invoked from setEdited to notify the receiver that edited status has changed, giving the receiver the opportunity to react.

See Also:

setEdited(boolean)