---

Accessing an Enterprise Object’s Data

In implementing your enterprise object classes, you want to focus on the code that’s unique to your application, not on the code that deals with fitting your objects into the framework of Enterprise Objects. To help with this, Enterprise Objects provides key-value coding, a standard interface for accessing an enterprise object’s properties ( key-value coding was introduced in “Key-Value Coding”).

Key-value coding specifies that an object’s properties are accessed indirectly by name or key rather than directly through invocation of an accessor method or as fields. This provides a consistent way to access an object’s data, regardless if the object provides accessor methods or fields to its data. The EOEnterpriseObject interface implements the EOKeyValueCoding and NSKeyValueCoding interfaces, so custom enterprise object classes automatically inherit key-value coding behavior.

The basic methods for accessing an object’s values are takeValueForKey and valueForKey, which set or return the value for the specified key, respectively. Key-value coding uses the first accessor it finds when both setting and getting the value for a given key. The following lists describe the lookup order of accessors.

The order of lookup when retrieving a value is:

• getKeyname() method

• keyname() method

• _getKeyname() method

• _keyname() method

• keyname field

• _keyname field

• handleQueryWithUnboundKey("keyname") method, if none of the above accessors are found

In the Listing entity described in “Reference Entity,” an invocation of valueForKey("bedrooms") on a Listing enterprise object looks up the value of the bedrooms property by invoking accessor methods and fields in the following order:

• getBedrooms() method

• bedrooms() method

• _getbedrooms() method

• _bedrooms() method

• bedrooms field

• _bedrooms field

• handleQueryWithUnboundKey("bedrooms") method, if none of the above accessors are found

The order of lookup when setting a value is:

• setKeyname(value) method

• _setKeyname(value) method

• keyname field

• _keyname field

• handleTakeValueForUnboundKey(value, "keyname") method, if none of the above accessors are found

In the Listing entity described in “Reference Entity,” an invocation of takeValueForKey(new Integer(4),"bedrooms") on a Listing enterprise object attempts to set the value of the bedrooms property by invoking accessor methods and setting fields in the following order:

• setBedrooms(new Integer(4))

• _setBedrooms(new Integer(4))

• bedrooms = new Integer(4)

• _bedrooms = new Integer(4)

• handleTakeValueForUnboundKey(new Integer(4), "bedrooms") method, if none of the above accessors are found

There is another set of methods defined by the EOKeyValueCoding interface, takeStoredValueForKey and storedValueForKey. You never explicitly invoke these methods, but you may implement them in enterprise object classes. The stored value methods are used internally to transport data to and from trusted sources. For example, takeStoredValueForKey is used to initialize an object’s properties with values fetched from the database, whereas takeValueForKey is used to modify an object’s properties from values provided by a user.

The default lookup order for the stored value methods for retrieving the value of a property is:

• _getKeyname() and _keyname() methods

• _keyname and keyname fields

• getkeyname() and keyname() methods

The default lookup order for the stored value methods for setting the value of a property is:

• _setKeyname() method

• _keyname, and keyname fields

• setKeyname() method

Refer to the API reference for com.webobjects.eocontrol.EOKeyValueCoding and for com.webobjects.foundation.NSKeyValueCoding for complete information about accessor lookup order.

EOGenericRecord adds some additional behavior to key-value coding. When takeStoredValueForKey or storedValueForKey is invoked in an EOGenericRecord object, a corresponding willChange or willRead invocation is sent automatically, before the accessor is looked up. This supports the requirement that enterprise object instances notify other instances when they’re about to change the state of their data. This requirement is described in “Change Notification.”

Error Handling for Accessors

As introduced in “Accessing an Enterprise Object’s Data,” the public key-value coding accessors valueForKey and takeValueForKey have a default lookup order of accessors. The final lookup key for valueForKey is handleQueryWithUnboundKey("keyName") and for takeValueForKey is handleTakeValueForUnboundKey(value, "keyName"). That is, the default implementation of key-value coding invokes these methods when they receive a key for which they can find no accessor methods or fields. The default implementations throw exceptions, but you can override them to handle the error more gracefully.

---