NSKeyValueCoding

Package:
com.webobjects.foundation

Interface Description

The NSKeyValueCoding interface defines a 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. The takeValueForKey method sets the value for an object's property, and valueForKey returns the value for an object's property.

The NSKeyValueCoding interface contains an inner interface, NSKeyValueCoding.ErrorHandling, that defines an extension to the basic NSKeyValueCoding interface for handling errors that occur during key-value coding (see the NSKeyValueCoding.ErrorHandling interface specification).

Additionally, NSKeyValueCoding contains two inner classes, NSKeyValueCoding. DefaultImplementation and NSKeyValueCoding.Utility. The former provides a default implementation of the interface, making it easy to implement NSKeyValueCoding on your own custom classes. The latter is a convenience that allows you to access the properties of NSKeyValueCoding objects and non-NSKeyValueCoding objects using the same code. Both the DefaultImplementation class and the Utility class provide NSKeyValueCoding.ErrorHandling API in addition to basic NSKeyValueCoding API.

Default Implementation

The methods in the NSKeyValueCoding. DefaultImplementation class are just like the methods defined by the NSKeyValueCoding interface (and the NSKeyValueCoding.ErrorHandling 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 NSKeyValueCoding using NSKeyValueCoding. DefaultImplementation. Employee's valueForKey method would then look like this:


public Object valueForKey(String key) {
    return NSKeyValueCoding.DefaultImplementation.valueForKey(this, key);
}

The NSKeyValueCoding. DefaultImplementation methods use accessor methods normally implemented by objects (such as setKey and key), or they access instance variables directly if no accessors for a key exist (see "Directly Accessing Instance Variables"). For detailed information, see the takeValueForKey and valueForKey method descriptions, which describe the default behavior provided by NSKeyValueCoding. DefaultImplementation. Additionally, see the method descriptions in the NSKeyValueCoding.ErrorHandling interface specification to see how the DefaultImplementation class handles errors.

Note: Always use the default implementation of NSKeyValueCoding provided by the foundation package. The default implementations have significant performance optimizations. To benefit from them, implement NSKeyValueCoding on a custom class as shown above by using the methods in NSKeyValueCoding. DefaultImplementation; or if your class inherits from an WebObjects class that implements NSKeyValueCoding, don't override the inherited implementation. Using a custom implementation incurs significant performance penalties.

Utility

Recall that the NSKeyValueCoding.Utility class is a convenience that allows you to access the properties of NSKeyValueCoding objects and non-NSKeyValueCoding 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 NSKeyValueCoding object and invoke the corresponding NSKeyValueCoding 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 NSKeyValueCoding API but you don't know if the object is an NSKeyValueCoding object. To do so, you simply use the corresponding Utility API, as in the following line of code:


theValue = NSKeyValueCoding.Utility.valueForKey(object, value, key);

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


if (object instanceof NSKeyValueCoding) {
    theValue = ((NSKeyValueCoding)object).valueForKey(key);
} else {
    theValue = NSKeyValueCoding.DefaultImplementation.valueForKey(object, key);
}

Directly Accessing Instance Variables

By default, key-value coding methods directly access instance variables if there are no accessor methods for setting and retrieving values. However, you can modify this behavior without overriding the default implementation. To instruct the default implementation not to directly access instance variables, implement the static method canAccessFieldsDirectly on your NSKeyValueCoding class to return false.

Constants

NSKeyValueCoding defines the following constant:

Constant	Type	Description
`NullValue`	NSKeyValueCoding.Null	A shared instance of NSKeyValueCoding.Null.

Static Methods

canAccessFieldsDirectly

public static boolean canAccessFieldsDirectly()

Returns true if the key-value coding methods can access the corresponding field value directly on finding no accessor method for a property. Returns false if they shouldn't.

An NSKeyValueCoding class doesn't have to implement this method. It's an optional method that allows a class to tailor key-value coding behavior. By default, the key-value implementation provided by NSKeyValueCoding. DefaultImplementation accesses fields directly if it can't find corresponding accessor methods. An NSKeyValueCoding class can override this behavior by implementing this method to return false, in which case the key-value coding methods don't access fields directly.

This method isn't strictly part of this interface because static methods can't be formally declared in an interface. However, this method is so closely related to the interface as to be considered part of it.

Instance Methods

takeValueForKey

public void takeValueForKey( Object value, String key)

Sets the receiver's value for the property identified by key to value.

The default implementation provided by NSKeyValueCoding. DefaultImplementation works as follows:

Searches for a public accessor method of the form setKey, and invokes it if there is one.
If a public accessor method isn't found, searches for a private accessor method of the form _setKey, and invokes it if there is one.
If an accessor method isn't found and the static method canAccessFieldsDirectly returns true, searches for an instance variable based on key and sets its value directly. For the key "lastName", this would be _lastName or lastName. (See "Directly Accessing Instance Variables".)
If neither an accessor method nor an instance variable is found, it's an error condition. It invokes handleTakeValueForUnboundKey if the object implements NSKeyValueCoding.ErrorHandling or throws NSKeyValueCoding. UnknownKeyException if the object doesn't.

valueForKey

public Object valueForKey(String key)

Returns the receiver's value for the property identified by key.

The default implementation provided by NSKeyValueCoding. DefaultImplementation works as follows:

Searches for a public accessor method based on key. For example, with a key of "lastName", the method looks for a method named getLastName or lastName.
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", the method looks for a method named _getLastName or _lastName.
If an accessor method isn't found and the static method canAccessFieldsDirectly returns true, the method searches for an instance variable based on key and returns its value directly. For the key "lastName", this would be _lastName or lastName. (See "Directly Accessing Instance Variables".)
If neither an accessor method nor an instance variable is found, the method invokes handleQueryWithUnboundKey (defined in NSKeyValueCoding.ErrorHandling).