com.webobjects.foundation
Interface NSKeyValueCodingAdditions

All Superinterfaces:

NSKeyValueCoding

All Known Subinterfaces:

EOEnterpriseObject, EOKeyValueCodingAdditions

All Known Implementing Classes:

D2WContext, EOController, EOCustomObject, NSArray, NSDictionary, WOApplication, WOComponent, WOContext, WOCookie, WODirectAction, WOHTTPConnection, WOMessage, WOSession, WOStatisticsStore, WOStringKeyMap

public interface NSKeyValueCodingAdditions

extends NSKeyValueCoding

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".

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 custom classes. The latter is a convenience class that allows you to access the properties of NSKeyValueCodingAdditions objects and 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 it is wanted 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 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 do not 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);
 }
 

See Also:

takeValueForKeyPath(java.lang.Object, java.lang.String), valueForKeyPath(java.lang.String), NSKeyValueCoding, NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Nested Class Summary

static class	NSKeyValueCodingAdditions.DefaultImplementation The NSKeyValueCodingAdditions.DefaultImplementation class provides default implementations of the NSKeyValueCodingAdditions interface.
static class	NSKeyValueCodingAdditions.Utility The NSKeyValueCodingAdditions.Utility class is a convenience that allows one to access the properties of NSKeyValueCodingAdditions objects and non-NSKeyValueCodingAdditions objects using the same code.

Nested classes inherited from class com.webobjects.foundation.NSKeyValueCoding

NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.ValueAccessor

Field Summary

static String

KeyPathSeparator The string used to separate components of a key path, "."

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Method Summary

void	takeValueForKeyPath(Object value, String keyPath) Sets the value for the property identified by keyPath to value.
Object	valueForKeyPath(String keyPath) Retrieves the value of a property of the object at the end of the key path (a key path is a string of the form "key1.key2").

Methods inherited from interface com.webobjects.foundation.NSKeyValueCoding

takeValueForKey, valueForKey

Field Detail

KeyPathSeparator

public static final String KeyPathSeparator

The string used to separate components of a key path, "."

Method Detail

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.

Parameters:

value - the property identified by keyPath is set to this

keyPath - identifies the property of an object

See Also:

NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), valueForKeyPath(java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation

valueForKeyPath

public Object valueForKeyPath(String keyPath)

Retrieves the value of a property of the object at the end of the key path (a key path is a string of the form "key1.key2"). 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.

Parameters:

keyPath - the keypath to evaluate

Returns:

the value for the derived property identified by keyPath

See Also:

NSKeyValueCoding.valueForKey(java.lang.String), takeValueForKeyPath(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation