PATH Documentation > WebObjects 4.5 > EOControl Reference

EOEnterpriseObject

(informal protocol)

Declared in:
EOControl/EOClassDescription.h

EOControl/EOEditingContext.h

EOControl/EOKeyValueCoding.h

EOControl/EOObserver.h

Protocol Description

The EOEnterpriseObject informal protocol 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 informal protocols and incorporated in the over arching EOEnterpriseObject informal protocol:

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.
EOKeyBindingCreation defines a mechanism for binding class/key pairs with a method for accessing the key, which maximizes the performance of EOKeyValueCoding.
EOKeyValueCodingAdditions defines extensions to the basic EOKeyValueCoding informal protocol, giving access to groups of properties and to properties across relationships.
EORelationshipManipulation builds on the basic EOKeyValueCoding informal protocol to allow you to modify to-many relationship properties.
EOValidation defines the way that enterprise objects validate their values.

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

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

Adopted Protocols

EOKeyValueCoding
+ accessInstanceVariablesDirectly

+ flushAllKeyBindings

+ useStoredAccessor

- handleQueryWithUnboundKey:

- handleTakeValue:forUnboundKey:

- storedValueForKey:

- takeStoredValue:forKey:

- takeValue:forKey:

- unableToSetNullForKey:

- valueForKey:

EOKeyValueCodingAdditions
- takeValue:forKeyPath:

- takeValuesFromDictionary:

- valueForKeyPath:

- valuesForKeys:

EORelationshipManipulation
- addObject:toBothSidesOfRelationshipWithKey:

- addObject:toPropertyWithKey:

- removeObject:fromBothSidesOfRelationshipWithKey:

- removeObject:fromPropertyWithKey:

EOValidation
- validateForDelete

- validateForInsert

- validateForSave

- validateForUpdate

- validateValue:forKey:

Method Types

Initializing enterprise objects

- initWithEditingContext:classDescription:globalID:

- awakeFromFetchInEditingContext:

- awakeFromInsertionInEditingContext:

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:

Getting descriptions

- eoDescription

- eoShallowDescription

- userPresentableDescription

Instance Methods

allPropertyKeys

- (NSArray *)allPropertyKeys

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

attributeKeys

- (NSArray *)attributeKeys

Returns the names of the receiver's attributes (not relationship properties). NSObject'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.

awakeFromFetchInEditingContext:

- (void)awakeFromFetchInEditingContext:(EOEditingContext *)anEditingContext

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

awakeFromInsertionInEditingContext:

- (void)awakeFromInsertionInEditingContext:(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. NSObject's implementation merely sends an awakeObject:fromInsertionInEditingContext: to the receiver's EOClassDescription. Subclasses should invoke super's implementation before performing their own initialization.

changesFromSnapshot

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

- (EOClassDescription *)classDescription

Returns the EOClassDescription registered for the receiver's class.NSObject's implementation invokes the EOClassDescription class method a classDescriptionForClass:.

classDescriptionForDestinationKey:

- (EOClassDescription *)classDescriptionForDestinationKey:(NSString *)key

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

clearProperties

- (void)clearProperties

Sets all of the receiver's to-one and to-many relationships to nil. EOEditingContexts use this method to break cyclic references among objects when they're deallocated. NSObject'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 deallocated.

deleteRuleForRelationshipKey:

- (EODeleteRule)deleteRuleForRelationshipKey:(NSString *)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:

For example, an Invoice object might return EODeleteRuleNullify 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.

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

See Also: - propagateDeleteWithEditingContext:, - validateForDelete (EOValidation)

editingContext

- (EOEditingContext *)editingContext

Returns the EOEditingContext that holds the receiver.

entityName

- (NSString *)entityName

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

eoDescription

- (NSString *)eoDescription

Returns a string that describes the receiver. NSObject'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 description 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

- (NSString *)eoShallowDescription

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

See Also: - userPresentableDescription

initWithEditingContext:classDescription:globalID:

- initWithEditingContext:(EOEditingContext *)anEditingContext classDescription:(EOClassDescription *)aClassDescription globalID:(EOGlobalID *)globalID

Initializes the receiver with the arguments provided. NSObject's implementation simply invokes init, and ignores anEditingContext.

See Also: - createInstanceWithEditingContext:globalID:zone: (EOClassDescription)

inverseForRelationshipKey:

- (NSString *)inverseForRelationshipKey:(NSString *)relationshipKey

Returns the name of the relationship pointing back to the receiver's class or entity from that named by relationshipKey, or nil 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. NSObject'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:

- (NSString *)inverseForRelationshipKey:(NSString *)relationshipKey
{
    if ([relationshipKey isEqual:@"creditCard"]) return @"member";
    return [super inverseForRelationshipKey:relationshipKey];
}

isToManyKey:

- (BOOL)isToManyKey:(NSString *)key

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

ownsDestinationObjectsForRelationshipKey:

- (BOOL)ownsDestinationObjectsForRelationshipKey:(NSString *)key

Returns YES if the receiver has a relationship identified by key that owns its destination, NO 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. NSObject's implementation of this method simply sends an ownsDestinationObjectsForRelationshipKey: message to the receiver's EOClassDescription.

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

propagateDeleteWithEditingContext:

- (void)propagateDeleteWithEditingContext:(EOEditingContext *)anEditingContext

Deletes the destination objects of the receiver's relationships according to the delete rule for each relationship. NSObject's implementation simply sends a propagateDeleteForObject:editingContext: 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:

- (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. NSObject's implementation should be sufficient for all purposes; you shouldn't have to override this method.

See Also: - changesFromSnapshot

snapshot

- (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 EONull substituted for nil. For to-many relationships, the dictionary contains shallow copies of the arrays to preserve the ids of the contents. NSObject's implementation should be sufficient for all purposes; you shouldn't have to override this method.

See Also: - updateFromSnapshot:

toManyRelationshipKeys

- (NSArray *)toManyRelationshipKeys

Returns the names of the receiver's to-many relationships. NSObject'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.

toOneRelationshipKeys

- (NSArray *)toOneRelationshipKeys

Returns the names of the receiver's to-one relationships. NSObject'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.

updateFromSnapshot:

- (void)updateFromSnapshot:(NSDictionary *)aSnapshot

Takes the values from aSnapshot, and sets the receiver's properties to them. NSObject's implementation sets each one using takeStoredValue:forKey:. In the process, EONull values are converted to nil, and array values are set as shallow mutable copies to preserve the ids of the contents.

See Also: - snapshot

userPresentableDescription

- (NSString *)userPresentableDescription

Returns a short (no longer than 60 characters) description of an enterprise object based on its data. NSObject'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

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

- (void)setRoleName:(NSString *)value {
    [self willChange];
    [roleName autorelease];
    roleName = [value retain];
}