NSKeyValueCodingAdditions

Implements:
NSKeyValueCoding

Package:
com.webobjects.foundation

Interface Description

The NSKeyValueCodingAdditions interface defines an extension to the basic NSKeyValueCoding interface. The pair of methods in NSKeyValueCodingAdditions- takeValueForKeyPath and valueForKeyPath-give access to properties across relationships with key paths of the form relationship.property; for example, "department.name". For more information on the basic key-value coding, see the NSKeyValueCoding interface specification.

The NSKeyValueCodingAdditions interface contains two inner classes, NSKeyValueCodingAdditions. DefaultImplementation and NSKeyValueCodingAdditions.Utility. The former provides a default implementation of the interface, making it easy to implement on your own custom classes. The latter is a convenience that allows you to access the properties of NSKeyValueCodingAdditions objects and non-NSKeyValueCodingAdditions objects using the same code.

Default Implementation

The methods in the NSKeyValueCodingAdditions. DefaultImplementation class are just like the methods defined by the NSKeyValueCodingAdditions interface, except they are static methods and they take an extra argument-the object on which the default implementation should operate.

For example, suppose you want to implement an Employee class that implements NSKeyValueCodingAdditions using NSKeyValueCodingAdditions. DefaultImplementation. Employee's valueForKeyPath method would then look like this:


public Object valueForKeyPath(String keyPath) {
    return NSKeyValueCodingAdditions.DefaultImplementation.valueForKeyPath(
        this,
        keyPath);
}

Utility

Recall that the NSKeyValueCodingAdditions.Utility class is a convenience that allows you to access the properties of NSKeyValueCodingAdditions objects and non-NSKeyValueCodingAdditions objects using the same code.

Utility's methods are similar to DefaultImplementation's methods in that they are static methods and they take an extra argument-the object on which the method should operate. However, Utility's methods simply check to see if the object on which they operate is an NSKeyValueCodingAdditions object and invoke the corresponding NSKeyValueCodingAdditions method on the object if it is. Otherwise, they invoke the corresponding DefaultImplementation method, passing the object on which to operate.

For example, suppose that you want to access an object with the NSKeyValueCodingAdditions API but you don't know if the object is an NSKeyValueCodingAdditions object. To do so, you simply use the corresponding Utility API, as in the following line of code:


theValue = NSKeyValueCodingAdditions.Utility.valueForKeyPath(object, keyPath);

The above line of code is essentially a short-cut for the following:


if (object instanceof NSKeyValueCodingAdditions) {
    theValue = ((NSKeyValueCodingAdditions)object).valueForKeyPath(keyPath);
} else {
    theValue = NSKeyValueCodingAdditions.DefaultImplementation.valueForKeyPath(
            object, keyPath);
}

Constants

NSKeyValueCodingAdditions defines the following constant:

Constant	Type	Description
`KeyPathSeparator`	String	The string used to separate components of a key path-a period (.).

Instance Methods

takeValueForKeyPath

public void takeValueForKeyPath( Object value, String keyPath)

Sets the value for the property identified by keyPath to value. A key path has the form relationship.property (with one or more relationships); for example "movieRole.roleName" or "movieRole.talent.lastName". The default implementation of this method (provided by NSKeyValueCodingAdditions. DefaultImplementation) gets the destination object for each relationship using valueForKey, and sends the final object a takeValueForKey message with value and property.

valueForKeyPath

public Object valueForKeyPath(String keyPath)

Returns the value for the derived property identified by keyPath. A key path has the form relationship.property (with one or more relationships); for example "movieRole.roleName" or "movieRole.talent.lastName". The default implementation of this method (provided by NSKeyValueCodingAdditions. DefaultImplementation) gets the destination object for each relationship using valueForKey, and returns the result of a valueForKey message to the final object.