PATH |
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 set
Key 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()
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)
The default implementation provided by NSKeyValueCoding. DefaultImplementation works as follows:
- Searches for a public accessor method of the form
set
Key, 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.
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. |
valueForKey
public Object valueForKey(String 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).
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. |
© 2001 Apple Computer, Inc. (Last Published April 17, 2001)