EORelationshipManipulation

(informal interface)

Implemented by:
EOEnterpriseObject
EOCustomObject
EOGenericRecord

Package:
com.webobjects.eocontrol

Interface Description

The EORelationshipManipulation interface builds on the basic EOKeyValueCoding interface to allow you to modify to-many relationship properties. EOCustomObject and EOGenericRecord provide default implementations of EORelationshipManipulation, which you rarely (if ever) need to override.

The primitive methods addObjectToPropertyWithKey and removeObjectFromPropertyWithKey add and remove single objects from to-many relationship arrays. The two other methods in the interface, addObjectToBothSidesOfRelationshipWithKey and removeObjectFromBothSidesOfRelationshipWithKey, 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 addObjectToPropertyWithKey and removeObjectFromPropertyWithKey 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

addObjectToBothSidesOfRelationshipWithKey

public abstract void addObjectToBothSidesOfRelationshipWithKey( EORelationshipManipulation anObject, String 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 takeValueForKey. For a to-many relationship, anObject is added using addObjectToBothSidesOfRelationshipWithKey.

This method also properly handles removing this 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.

addObjectToPropertyWithKey

public abstract void addObjectToPropertyWithKey( Object anObject, String key)

Adds anObject to the receiver's to-many relationship identified by key, without setting a reciprocal relationship. Similar to the implementation of takeValueForKey, EOCustomObject'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.

removeObjectFromBothSidesOfRelationshipWithKey

public abstract void removeObjectFromBothSidesOfRelationshipWithKey( EORelationshipManipulation anObject, String 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 takeValueForKey with null as the value. For a to-many relationship, anObject is removed using removeObjectFromPropertyWithKey.

removeObjectFromPropertyWithKey

public abstract void removeObjectFromPropertyWithKey( Object anObject, String key)

Removes anObject from the receiver's to-many relationship identified by key, without modifying a reciprocal relationship. Similar to the implementation of takeValueForKey, EOCustomObject'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 null.