EOEnterpriseObject

(informal interface)

Implemented by:
EOCustomObject
EOGenericRecord

Implements:
EOKeyValueCodingAdditions
EORelationshipManipulation
EOValidation
EODeferredFaultingSerializable

Package: com.webobjects.eocontrol

Interface Description

The EOEnterpriseObject interface identifies basic enterprise object behavior, defining methods for supporting operations common to all enterprise objects. Among these are methods for initializing instances, announcing changes, setting and retrieving property values, and performing validation of state. Some of these methods are for enterprise objects to implement or override, and some are meant to be used as defined by the Framework. Many methods are used internally by the Framework and rarely invoked by application code.

Many of the functional areas are defined in smaller, more specialized interfaces and incorporated in the over arching EOEnterpriseObject interface:

• EOKeyValueCoding defines Enterprise Objects Framework's main data transport mechanism, in which the properties of an object are accessed indirectly by name (or "key"), rather than directly through invocation of an accessor method or as instance variables.
• EOKeyValueCodingAdditions defines extensions to the basic EOKeyValueCoding interface, giving access to groups of properties and to properties across relationships.
• EORelationshipManipulation builds on the basic EOKeyValueCoding interface to allow you to modify to-many relationship properties.
• EOValidation defines the way that enterprise objects validate their values.
• EOFaulting and EODeferredFaulting define mechanisms for postponing an object's initialization until its actually needed.

The remaining methods are introduced in the EOEnterpriseObject interface itself and can be broken down into three functional groups discussed in the following sections:

• "Initialization" (page 363)
• "Change Notification" (page 364)
• "Object and Class Metadata Access" (page 364)
• "Snapshots" (page 365)

You rarely need to implement the EOEnterpriseObject interface from scratch. The Framework provides default implementations of the methods in EOCustomObject and EOGenericRecord. Use EOGenericRecords to represent enterprise objects that don't require custom behavior, and create subclasses of EOCustomObject to represent enterprise objects that do. The section "Writing an Enterprise Object Class" (page 366) highlights the methods that you typically provide or override in a custom enterprise object class.

Method Types

Initializing enterprise objects
awakeFromFetchawakeFromInsertion

Announcing changes
willChange

Getting an object's EOEditingContext
editingContext

Getting class description information
allPropertyKeys
attributeKeys
classDescription
classDescriptionForDestinationKey
deleteRuleForRelationshipKey
entityName
inverseForRelationshipKey
isToManyKey
ownsDestinationObjectsForRelationshipKey
toManyRelationshipKeys
toOneRelationshipKeys

Modifying relationships
propagateDeleteWithEditingContext
clearProperties

Working with snapshots
snapshot
updateFromSnapshot

Merging values
changesFromSnapshot
reapplyChangesFromDictionary

Invoking behavior on the server
invokeRemoteMethod

Getting descriptions
eoDescription
eoShallowDescription
userPresentableDescription

Instance Methods

allPropertyKeys

public abstract NSArray allPropertyKeys()

Returns all of the receiver's property keys. EOCustomObject's implementation returns the union of the keys returned by attributeKeys, toOneRelationshipKeys, and toManyRelationshipKeys.

attributeKeys

public abstract NSArray attributeKeys()

Returns the names of the receiver's attributes (not relationship properties). EOCustomObject's implementation simply invokes attributeKeys in the object's EOClassDescription and returns the results. You might wish to override this method to add keys for attributes not defined by the EOClassDescription. The access layer's subclass of EOClassDescription, EOEntityClassDescription, returns the names of attributes designated as class properties.

See Also: toOneRelationshipKeys, toManyRelationshipKeys

awakeFromClientUpdate

public abstract void awakeFromClientUpdate(EOEditingContext anEditingContext)

Description forthcoming.

awakeFromFetch

public abstract void awakeFromFetch(EOEditingContext anEditingContext)

Overridden by subclasses to perform additional initialization on the receiver upon its being fetched from the external repository into anEditingContext. EOCustomObject's implementation merely sends an awakeObjectFromFetch to the receiver's EOClassDescription. Subclasses should invoke super's implementation before performing their own initialization.

awakeFromInsertion

public abstract void awakeFromInsertion(EOEditingContext anEditingContext)

Overridden by subclasses to perform additional initialization on the receiver upon its being inserted into anEditingContext. This is commonly used to assign default values or record the time of insertion. EOCustomObject's implementation merely sends an awakeObjectFromInsertion to the receiver's EOClassDescription. Subclasses should invoke super's implementation before performing their own initialization.

changesFromSnapshot

public abstract NSDictionary changesFromSnapshot(NSDictionary snapshot)

Returns a dictionary whose keys correspond to the receiver's properties with uncommitted changes relative to snapshot, and whose values are the uncommitted values. In both snapshot and the returned dictionary, where a key represents a to-many relationship, the corresponding value is an NSArray containing two other NSArrays: the first is an array of objects to be added to the relationship property, and the second is an array of objects to be removed.

See Also: reapplyChangesFromDictionary

classDescription

public abstract EOClassDescription classDescription()

Returns the EOClassDescription registered for the receiver's class.EOCustomObject's implementation invokes the EOClassDescription static method a classDescriptionForClass.

classDescriptionForDestinationKey

public abstract EOClassDescription classDescriptionForDestinationKey(String key)

Returns the EOClassDescription for the destination objects of the relationship identified by key. EOCustomObject's implementation sends a classDescriptionForDestinationKey message to the receiver's EOClassDescription.

clearProperties

public abstract void clearProperties()

Sets all of the receiver's to-one and to-many relationships to null. EOEditingContexts use this method to break cyclic references among objects when they're finalized. EOCustomObject's implementation should be sufficient for all purposes. If your enterprise object maintains references to other objects and these references are not to-one or to-many keys, then you should probably subclass this method ensure unused objects can be finalized.

deleteRuleForRelationshipKey

public abstract int deleteRuleForRelationshipKey(String relationshipKey)

Returns a rule indicating how to handle the destination of the receiver's relationship named by relationshipKey when the receiver is deleted. The delete rule is one of:

• DeleteRuleNullify
• DeleteRuleCascade
• DeleteRuleDeny
• DeleteRuleNoAction

For example, an Invoice object might return DeleteRuleNullify for the relationship named "lineItems", since when an invoice is deleted, its line items should be deleted as well. For more information on the delete rules, see the method description for EOClassDescription's deleteRuleForRelationshipKey in the class specification for EOClassDescription, the class in which they're defined.

EOCustomObject's implementation of this method simply sends a deleteRuleForRelationshipKey message to the receiver's EOClassDescription.

See Also: propagateDeleteWithEditingContext, validateForDelete (EOValidation)

editingContext

public abstract EOEditingContext editingContext()

Returns the EOEditingContext that holds the receiver.

entityName

public abstract String entityName()

Returns the name of the receiver's entity, or null if it doesn't have one. EOCustomObject's implementation simply sends an entityName message to the receiver's EOClassDescription.

eoDescription

public abstract String eoDescription()

Returns a string that describes the receiver. EOCustomObject's implementation returns a full description of the receiver's property values by extracting them using the key-value coding methods. An object referenced through relationships is listed with the results of an eoShallowDescription message (to avoid infinite recursion through cyclical relationships).

This method is useful for debugging. You can implement a toString method that invokes this one, and the debugger's print-object command (po on the command line) automatically displays this description. You can also invoke this method directly on the command line of the debugger.

See Also: userPresentableDescription

eoShallowDescription

public abstract String eoShallowDescription()

Similar to eoDescription, but doesn't descend into relationships. eoDescription invokes this method for relationship destinations to avoid infinite recursion through cyclical relationships. EOCustomObject's implementation simply returns a string containing the receiver's class and entity names.

See Also: userPresentableDescription

inverseForRelationshipKey

public abstract String inverseForRelationshipKey(String relationshipKey)

Returns the name of the relationship pointing back to the receiver's class or entity from that named by relationshipKey, or null if there isn't one. With the access layer's EOEntity and EORelationship, for example, reciprocality is determined by the join attributes of the two EORelationships. EOCustomObject's implementation simply sends an inverseForRelationshipKey message to the receiver's EOClassDescription.

You might override this method for reciprocal relationships that aren't defined using the same join attributes. For example, if a Member object has a relationship to CreditCard based on the card number, but a CreditCard has a relationship to Member based on the Member's primary key, both classes need to override this method. This is how Member might implement it:

public String inverseForRelationshipKey(String relationshipKey) {
    if (relationshipKey.equals("creditCard"))
        return "member";
    else
        return super.inverseForRelationshipKey(relationshipKey);
}

invokeRemoteMethod

public abstract Object invokeRemoteMethod( String methodName, Class[] argumentTypes Object[] arguments)

Invokes methodName using arguments. To pass an enterprise object as an argument, use its global ID. This method has the side effect of saving all the changes from the receiver's editing context all the way down to the editing context in the server session.

isToManyKey:

public abstract boolean isToManyKey(String key)

Returns true if the receiver has a to-many relationship identified by key, false otherwise. EOCustomObject's implementation of this method simply checks its toManyRelationshipKeys array for key.

ownsDestinationObjectsForRelationshipKey

public abstract boolean ownsDestinationObjectsForRelationshipKey(String key)

Returns true if the receiver has a relationship identified by key that owns its destination, false otherwise. If an object owns the destination for a relationship, then when that destination object is removed from the relationship, it's automatically deleted. Ownership of a relationship thus contrasts with a delete rule, in that the first applies when the destination is removed and the second applies when the source is deleted. EOCustomObject's implementation of this method simply sends an ownsDestinationObjectsForRelationshipKey message to the receiver's EOClassDescription.

See Also: deleteRuleForRelationshipKey, - ownsDestination (EOAccess' EORelationship)

prepareValuesForClient

public abstract void prepareValuesForClient()

Description forthcoming.

propagateDeleteWithEditingContext

public abstract void propagateDeleteWithEditingContext(EOEditingContext anEditingContext)

Deletes the destination objects of the receiver's relationships according to the delete rule for each relationship. EOCustomObject's implementation simply sends a propagateDeleteForObject message to the receiver's EOClassDescription. For more information on delete rules, see the method description for deleteRuleForRelationshipKey in the EOClassDescription class specification.

See Also: deleteRuleForRelationshipKey

reapplyChangesFromDictionary

public abstract void reapplyChangesFromDictionary(NSDictionary changes)

Similar to takeValuesFromDictionary, but the changes dictionary can contain arrays for to-many relationships. Where a key represents a to-many relationship, the dictionary's value is an NSArray containing two other NSArrays: the first is an array of objects to be added to the relationship property, and the second is an array of objects to be removed. EOCustomObject's implementation should be sufficient for all purposes; you shouldn't have to override this method.

See Also: changesFromSnapshot

snapshot

public abstract NSDictionary snapshot()

Returns a dictionary whose keys are those of the receiver's attributes, to-one relationships, and to-many relationships, and whose values are the values of those properties, with EONullValue substituted for null. For to-many relationships, the dictionary contains shallow copies of the arrays. EOCustomObject's implementation should be sufficient for all purposes; you shouldn't have to override this method.

See Also: updateFromSnapshot

toManyRelationshipKeys

public abstract NSArray toManyRelationshipKeys()

Returns the names of the receiver's to-many relationships. EOCustomObject's implementation simply invokes toManyRelationshipKeys in the object's EOClassDescription and returns the results. You might wish to override this method to add keys for relationships not defined by the EOClassDescription, but it's rarely necessary: The access layer's subclass of EOClassDescription, EOEntityClassDescription, returns the names of to-many relationships designated as class properties.

See Also: attributeKeys, toOneRelationshipKeys

toOneRelationshipKeys

public abstract NSArray toOneRelationshipKeys()

Returns the names of the receiver's to-one relationships. EOCustomObject's implementation simply invokes toOneRelationshipKeys in the object's EOClassDescription and returns the results. You might wish to override this method to add keys for relationships not defined by the EOClassDescription, but it's rarely necessary: The access layer's subclass of EOClassDescription, EOEntityClassDescription, returns the names of to-one relationships designated as class properties.

See Also: attributeKeys, toManyRelationshipKeys

updateFromSnapshot

public abstract void updateFromSnapshot(NSDictionary aSnapshot)

Takes the values from aSnapshot, and sets the receiver's properties to them. EOCustomObject's implementation sets each one using takeStoredValueForKey. In the process, EONullValues are converted to null, and array values are set as shallow mutable copies.

See Also: snapshot

userPresentableDescription

public abstract String userPresentableDescription()

Returns a short (no longer than 60 characters) description of an enterprise object based on its data. EOCustomObject's implementation enumerates the object's attributeKeys and returns the values of all of its properties, separated by commas (applying the default formatter for numbers and dates).

See Also: eoDescription, eoShallowDescription

willChange

public abstract void willChange()

Notifies any observers that the receiver's state is about to change, by sending each an objectWillChange message (see the EOObserverCenter class specification for more information). A subclass should not override this method, but should invoke it prior to altering the subclass's state, most typically in "set" methods such as the following:

public void setRoleName(String value) {
    willChange();
    roleName = value;
}

© 2001 Apple Computer, Inc. (Last Published April 19, 2001)