com.webobjects.foundation
Interface NSKeyValueCoding

All Known Subinterfaces:

EOEnterpriseObject, EOKeyValueCoding, EOKeyValueCodingAdditions, NSKeyValueCodingAdditions

All Known Implementing Classes:

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

public interface NSKeyValueCoding

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.

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's 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.

Note: The default implementations have significant performance optimizations. To benefit from them, NSKeyValueCoding can be implemented on a custom class as shown above by using the methods in NSKeyValueCoding.DefaultImplementation, or if your class inherits from a WebObjects class that implements NSKeyValueCoding, do not 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 do not 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 to not directly access instance variables, implement the static method canAccessFieldsDirectly on your NSKeyValueCoding class to return false.

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 should not.

An NSKeyValueCoding class does not 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 not 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 will not access fields directly.

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

See Also:

takeValueForKey(java.lang.Object, java.lang.String), valueForKey(java.lang.String), NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.Utility

Nested Class Summary

static class	NSKeyValueCoding.DefaultImplementation The NSKeyValueCoding.DefaultImplementation class provides the WebObjects default implementations of the NSKeyValueCoding and NSKeyValueCoding.ErrorHandling interfaces.
static interface	NSKeyValueCoding.ErrorHandling The NSKeyValueCoding.ErrorHandling interface declares an API for handling errors that occur during key-value coding.
static class	NSKeyValueCoding.Null NSKeyValueCoding.Null is a final class that defines a unique object used to represent null values in collection objects, such as NSArrays, which do not allow null values.
static class	NSKeyValueCoding.UnknownKeyException Instances of the NSKeyValueCoding.UnknownKeyException class are created and thrown when an unknown key is encountered during key-value coding.
static class	NSKeyValueCoding.Utility 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.
static class	NSKeyValueCoding.ValueAccessor NSKeyValueCoding.ValueAccessor is an abstract class that establishes a mechanism by which NSKeyValueCoding can operate on object's package access instance variables.

Field Summary

static NSKeyValueCoding.Null

NullValue A constant used to represent null in places which do not handle raw null.

Method Summary

void	takeValueForKey(Object value, String key) Sets the value for the property identified by key to value.
Object	valueForKey(String key) Retrieves the value of the property named by key.

Field Detail

NullValue

public static final NSKeyValueCoding.Null NullValue

A constant used to represent null in places which do not handle raw null.

Method Detail

takeValueForKey

public void takeValueForKey(Object value,
                            String key)

Sets the value for the property identified by key to value.

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

1. Searches for a public accessor method of the form setKey, and invokes it if there is one.
2. If a public accessor method is not found, searches for a private accessor method of the form _setKey, and invokes it if there is one.
3. If an accessor method is not found and the static method canAccessFieldsDirectly returns true, searches for a field based on key and sets its value directly. For the key "lastName", this would be _lastName, _isLastName, lastName, or isLastName.
4. If the type of the value argument is not compatible with the underlying field or method parameter, the default implementation will make an effort to convert between different Java numeric types (Integer, Double, BigDecimal, etc) as well as between Boolean and Number (true = 1, false = 0). If any other conversion would be necessary, an exception is thrown.
5. If neither an accessor method nor a field is found, it is an error condition. It invokes handleTakeValueForUnboundKey if the object implements NSKeyValueCoding.ErrorHandling or throws NSKeyValueCoding.UnknownKeyException if the object does not.

Note: : 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, do not override the inherited implementation. Using a custom implementation incurs significant performance penalties.

Parameters:

value - the new value for the property named by key

key - identifies the property to change

Throws:

NSKeyValueCoding.UnknownKeyException - if key cannot be found on the object this method was invoked upon.

See Also:

NullValue, valueForKey(java.lang.String), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleTakeValueForUnboundKey(java.lang.Object, java.lang.String)

valueForKey

public Object valueForKey(String key)

Retrieves the value of the property named by key.

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

1. Searches for a public accessor method based on key. For example, with a key of "lastName", the method looks for a method named getLastName, lastName, or isLastName.
2. If a public accessor method is not 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, _lastName, or _isLastName
3. If an accessor method is not found and the static method canAccessFieldsDirectly returns true, the method searches for a field based on key and returns its value directly. For the key "lastName", this would be _lastName, _isLastName, lastName, or isLastName.
4. If neither an accessor method nor a field is found, the method invokes handleQueryWithUnboundKey (defined in NSKeyValueCoding.ErrorHandling).

Note: 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, do not override the inherited implementation. Using a custom implementation incurs significant performance penalties.

Parameters:

key - identifies the property to retrieve

Returns:

the value of the property identified by key. Depending on the object you invoke this method upon, null may be replaced with NullValue

Throws:

NSKeyValueCoding.UnknownKeyException - if key cannot be found on the object this method was invoked upon.

See Also:

NullValue, takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleQueryWithUnboundKey(java.lang.String)