WebObjects 5.2.3

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

Last updated Thu Oct 21 15:04:16 PDT 2004.

Copyright © 2004 Apple Computer, Inc.