PATH Documentation > WebObjects 4.5 > EOControl Reference

EORelationshipManipulation

(informal protocol)

Declared in:
EOControl/EOClassDescription.h

Protocol Description

The EORelationshipManipulation informal protocol builds on the basic EOKeyValueCoding informal protocol to allow you to modify to-many relationship properties. the Framework additions to NSObject provide default implementations of EORelationshipManipulation, which you rarely (if ever) need to override.

The primitive methods addObject:toPropertyWithKey: and removeObject:fromPropertyWithKey: add and remove single objects from to-many relationship arrays. The two other methods in the informal protocol, addObject:toBothSidesOfRelationshipWithKey: and removeObject:fromBothSidesOfRelationshipWithKey:, are implemented in terms of the two primitives to handle reciprocal relationships. These methods find the inverse relationship to the one identified by the specified key (if there is such an inverse relationship) and use addObject:toPropertyWithKey: and removeObject:fromPropertyWithKey: to alter both relationships, whether they're to-one or to-many.

The primitive methods check first for a method you might implement, addToKey or removeFromKey, invoking that method if it's implemented, otherwise using the basic key-value coding methods to do the work. Consequently, you rarely need to provide your own implementations of EORelationshipManipulation. Rather, you can provide relationship accessors (addToKey or removeFromKey) whenever you need to implement custom business logic.

Instance Methods

addObject:toBothSidesOfRelationshipWithKey:

- (void)addObject:(id)anObject toBothSidesOfRelationshipWithKey:(NSString *)key

Sets or adds anObject as the destination for the receiver's relationship identified by key, and also sets or adds the receiver for anObject's reciprocal relationship if there is one. For a to-one relationship, anObject is set using takeValue:forKey:. For a to-many relationship, anObject is added using addObject:toBothSidesOfRelationshipWithKey:.

This method also properly handles removing self and anObject from their previous relationship as needed. For example, if an Employee object belongs to the Research department, invoking this method with the Maintenance department removes the Employee from the Research department as well as setting the Employee's department to Maintenance.

addObject:toPropertyWithKey:

- (void)addObject:(id)anObject toPropertyWithKey:(NSString *)key

Adds anObject to the receiver's to-many relationship identified by key, without setting a reciprocal relationship. Similar to the implementation of takeValue:forKey:, NSObject's implementation of this method first attempts to invoke a method of the form addToKey:. If the receiver doesn't have such a method, this method gets the property array using valueForKey: and operates directly on that. For a to-many relationship, this method adds anObject to the array if it is not already in the array. For a to-one relationship, this method replaces the previous value with anObject.

removeObject:fromBothSidesOfRelationshipWithKey:

- (void)removeObject:(id)anObject fromBothSidesOfRelationshipWithKey:(NSString *)key

Removes anObject from the receiver's relationship identified by key, and also removes the receiver from anObject's reciprocal relationship if there is one. For a to-one relationship, anObject is removed using takeValue:forKey: with nil as the value. For a to-many relationship, anObject is removed using removeObject:fromPropertyWithKey:.

removeObject:fromPropertyWithKey:

- (void)removeObject:(id)anObject fromPropertyWithKey:(NSString *)key

Removes anObject from the receiver's to-many relationship identified by key, without modifying a reciprocal relationship. Similar to the implementation of takeValue:forKey:, NSObject's implementation of this method first attempts to invoke a method of the form removeFromKey:. If the receiver doesn't have such a method, this method gets the property array using valueForKey: and operates directly on that. For a to-many relationship, this method removes anObject from the array. For a to-one relationship, this method replaces anObject with nil.