PATH  Documentation > WebObjects 4.5 > EOControl Reference

Table of Contents

EOKeyValueCoding


Implemented by:
EOKeyValueCodingAdditions
EOEnterpriseObject
EOCustomObject
EOGenericRecord
Implements:
(com.apple.client.eocontrol only) NSKeyValueCoding
Package:
com.apple.client.eocontrol
com.apple.yellow.eocontrol

Interface Description


The EOKeyValueCoding interface 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. Thus, all of an object's properties can be accessed in a consistent manner. EOCustomObject and EOGenericRecord provide default implementations of EOKeyValueCoding, which are sufficient for most purposes.

The basic methods for accessing an object's values are takeValueForKey, which sets the value for the property identified by the specified key, and valueForKey, which returns the value for the property identified by the specified key. The default implementations provided by EOCustomObject use the accessor methods normally implemented by objects (or to access instance variables directly if need be), so that you don't have to write special code simply to integrate your objects into the Enterprise Objects Framework.

The corresponding methods takeStoredValueForKey and storedValueForKey are similar, but they're considered to be a private API, for use by the Framework for transporting 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 to values provided by a user or other business logic. How these methods work and how they're used by the framework is discussed in more detail in the section "Stored Value Methods".

The remaining methods, handleQueryWithUnboundKey, handleTakeValueForUnboundKey, and unableToSetNullForKey, are provided to handle error conditions. The default versions of handleQueryWithUnboundKey and handleTakeValueForUnboundKey throw an exception.

For more information on EOKeyValueCoding, see the sections:



Constants


EOKeyValueCoding defines the following int constants to be used as possible arguments for the createKeyValueBindingForKey and keyValueBindingForKey methods. The argument indicates whether the return value, a EOKeyValueCoding.KeyBinding object, binds a class/key pair to a mechanism to set the value for a key or to retrieve it.


ConstantDescription
SetKeyBindingMaskDesignates a binding as one responsible for setting an object's value.
StoredKeyBindingMaskDesignates a binding as one responsible for retrieving an object's value.



Interfaces Implemented


NSKeyValueCoding (com.apple.client.eocontrol only)
takeValueForKey
valueForKey


Method Types


Accessing values
storedValueForKey
takeStoredValueForKey
takeValueForKey
valueForKey
Handling error conditions
handleQueryWithUnboundKey
handleTakeValueForUnboundKey
unableToSetNullForKey


Instance Methods



handleQueryWithUnboundKey

public abstract Object handleQueryWithUnboundKey(String key)

Invoked from valueForKey when it finds no property binding for key. EOCustomObject's implementation throws an exception. Subclasses can override this method to handle the query in some other way.

handleTakeValueForUnboundKey

public abstract void handleTakeValueForUnboundKey( Object value, String key)

Invoked from takeValueForKey when it finds no property binding for key. EOCustomObject's implementation throws an exception. Subclasses can override it to handle the request in some other way.

storedValueForKey

public abstract Object storedValueForKey(String key)

Returns the property identified by key. This method is used when the value is retrieved for storage in an object store (generally, this is ultimately in a database) or for inclusion in a snapshot. The default implementation provided by EOCustomObject is similar to the implementation of valueForKey, but it resolves key with a different method-instance variable search order:
  1. Searches for a private accessor method based on key (a method preceded by an underbar). For example, with a key of "lastName", storedValueForKey looks for a method named _getLastName or _lastName.
  2. If a private accessor isn't found, searches for an instance variable based on key and returns its value directly. For example, with a key of "lastName", storedValueForKey looks for an instance variable named _lastName or lastName.
  3. If neither a private accessor or an instance variable is found, storedValueForKey searches for a public accessor method based on key. For the key "lastName", this would be getLastName or lastName.
  4. If key is unknown, storedValueForKey calls handleTakeValueForUnboundKey.

This different search order allows an object to bypass processing that is performed before returning a value through public API. However, if you always want to use the search order in valueForKey, you can implement the static method useStoredAccessor to return false. And as with valueForKey, you can prevent direct access of an instance variable with the method the static method accessInstanceVariablesDirectly.



takeStoredValueForKey

public abstract void takeStoredValueForKey( Object value, String key)

Sets the property identified by key to value. This method is used to initialize the receiver with values from an object store (generally, this is ultimately from a database) or to restore a value from a snapshot. The default implementation provided by EOCustomObject is similar to the implementation of takeValueForKey, but it resolves key with a different method-instance variable search order:
  1. Searches for a private accessor method based on key (a method preceded by an underbar). For example, with a key of "lastName", takeStoredValueForKey looks for a method named _setLastName.
  2. If a private accessor isn't found, searches for an instance variable based on key and sets its value directly. For example, with a key of "lastName", takeStoredValueForKey looks for an instance variable named _lastName or lastName.
  3. If neither a private accessor or an instance variable is found, takeStoredValueForKey searches for a public accessor method based on key. For the key "lastName", this would be setLastName.
  4. If key is unknown, takeStoredValueForKey calls handleTakeValueForUnboundKey.

This different search order allows an object to bypass processing that is performed before setting a value through public API. However, if you always want to use the search order in takeValueForKey, you can implement the static method useStoredAccessor to return false. And as with valueForKey, you can prevent direct access of an instance variable with the method the static method accessInstanceVariablesDirectly.



takeValueForKey

public abstract void takeValueForKey( Object value, String key)

Sets the value for the property identified by key to value, invoking handleTakeValueForUnboundKey if the receiver doesn't recognize key and unableToSetNullForKey if value is null and key identifies a scalar property.

The default implementation provided by EOCustomObject works as follows:

  1. Searches for a public accessor method of the form set Key , invoking it if there is one.
  2. If a public accessor method isn't found, searches for a private accessor method of the form _set Key , invoking it if there is one.
  3. If an accessor method isn't found and the static method accessInstanceVariablesDirectly returns true, takeValueForKey searches for an instance variable based on key and sets the value directly. For the key "lastName", this would be _lastName or lastName.
  4. If neither an accessor method nor an instance variable is found, the default implementation invokes handleTakeValueForUnboundKey.


unableToSetNullForKey

public abstract void unableToSetNullForKey(String key)

Invoked from takeValueForKey (and takeStoredValueForKey) when it's given a null value for a scalar property (such as an int or a float). EOCustomObject's implementation throws an exception. Subclasses can override it to handle the request in some other way, such as by substituting zero or a sentinel value and invoking takeValueForKey again.

valueForKey

public abstract Object valueForKey(String key)

Returns the value for the property identified by key, invoking handleQueryWithUnboundKey if the receiver doesn't recognize key.

The default implementation provided by EOCustomObject works as follows:

  1. Searches for a public accessor method based on key. For example, with a key of "lastName", valueForKey looks for a method named getLastName or lastName.
  2. If a public accessor method isn't found, searches for a private accessor method based on key (a method preceded by an underbar). For example, with a key of "lastName", valueForKey looks for a method named _getLastName or _lastName.
  3. If an accessor method isn't found and the static method accessInstanceVariablesDirectly returns true, valueForKey searches for an instance variable based on key and returns its value directly. For the key "lastName", this would be _lastName or lastName.
  4. If neither an accessor method nor an instance variable is found, the default implementation invokes handleQueryWithUnboundKey.



Table of Contents