com.webobjects.eocontrol
Interface EOKeyValueCodingAdditions

All Superinterfaces:

EOKeyValueCoding, NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions

All Known Subinterfaces:

EOEnterpriseObject

All Known Implementing Classes:

D2WContext, EOCustomObject

public interface EOKeyValueCodingAdditions

extends NSKeyValueCodingAdditions, EOKeyValueCoding

The EOKeyValueCodingAdditions combines (extends) the NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions and EOKeyValueCoding and adds two more methods--takeValuesFromDictionary and valuesForKeys-- which are useful when working with groups of properties.

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

Null Values

Since the WebObjects collections such as NSArray and NSDictionary can't contain null as a value, null must be represented by a special object, NSKeyValueCoding.NullValue. NSKeyValueCoding.NullValue is a single instance of the NSKeyValueCoding.Null class and is used by the key-value coding implementations inside the WebObjects collections.

The default implementations of takeValuesFromDictionary and valuesForKeys translate NSKeyValueCoding.NullValue and null between NSDictionaries and enterprise objects so the objects don't have to explicitly test for NSKeyValueCoding.NullValue.

Default Implementation

The methods in the EOKeyValueCodingAdditions.DefaultImplementation class are just like the methods defined by the EOKeyValueCodingAdditions 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 EOKeyValueCodingAdditions using EOKeyValueCodingAdditions.DefaultImplementation. Employee's valuesForKeys method would then look like this:

  public Object valuesForKeys(NSArray keys) {
      return EOKeyValueCodingAdditions.DefaultImplementation.valuesForKeys(this, keys);
  }
 

Note:Always try to use the default implementation of EOKeyValueCodingAdditions. The default implementations have significant performance optimizations. To benefit from them, EOKeyValueCodingAdditions can be implemented on a custom class as shown above by using the methods in EOKeyValueCodingAdditions.DefaultImplementation; or if your class inherits from an EOF class that implements EOKeyValueCodingAdditions, don't override the inherited implementation. Using a custom implementation incurs significant performance penalties.

Utility

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

  value = EOKeyValueCodingAdditions.Utility.valuesForKeys(keys);
 

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

  if (object instanceof EOKeyValueCodingAdditions) {
      value = ((EOKeyValueCodingAdditions)object).valuesForKeys(keys);
  } else {
      value = EOKeyValueCodingAdditions.DefaultImplementation.valuesForKeys(keys);
  }
 

See Also:

NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions, EOKeyValueCoding, EOKeyValueCodingAdditions.DefaultImplementation, EOKeyValueCodingAdditions.Utility

Nested Class Summary

static class	EOKeyValueCodingAdditions.DefaultImplementation The EOKeyValueCodingAdditions.DefaultImplementation class provides the WebObjects default implementation of the EOKeyValueCodingAdditions interface.
static class	EOKeyValueCodingAdditions.Utility The EOKeyValueCodingAdditions.Utility class is a convenience that allows you to access the properties of EOKeyValueCodingAdditions objects and non-EOKeyValueCodingAdditions objects using the same code.

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

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

Field Summary

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Method Summary

void	takeValuesFromDictionary(NSDictionary dictionary) Sets properties of the receiver with values from dictionary, using its keys to identify the properties.
void	takeValuesFromDictionaryWithMapping(NSDictionary dictionary, NSDictionary mapping) Sets properties of the receiver with values from dictionary, using its keys and mapping to identify the properties.
NSDictionary	valuesForKeys(NSArray keys) Returns a dictionary containing the property values identified by each of keys.
NSDictionary	valuesForKeysWithMapping(NSDictionary mapping) Returns a dictionary containing the property values identified by each of the key-value pairs in mapping.

Methods inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

takeValueForKeyPath, valueForKeyPath

Methods inherited from interface com.webobjects.foundation.NSKeyValueCoding

takeValueForKey, valueForKey

Methods inherited from interface com.webobjects.eocontrol.EOKeyValueCoding

storedValueForKey, takeStoredValueForKey

Methods inherited from interface com.webobjects.foundation.NSKeyValueCoding.ErrorHandling

handleQueryWithUnboundKey, handleTakeValueForUnboundKey, unableToSetNullForKey

Method Detail

takeValuesFromDictionary

public void takeValuesFromDictionary(NSDictionary dictionary)

Sets properties of the receiver with values from dictionary, using its keys to identify the properties. The default implementation invokes takeValueForKey for each key-value pair, substituting null for NSKeyValueCoding.NullValue values in the dictionary.

Parameters:

dictionary - the key-value pairs to be set

See Also:

NSKeyValueCoding.takeValueForKey(Object, String)

takeValuesFromDictionaryWithMapping

public void takeValuesFromDictionaryWithMapping(NSDictionary dictionary,
                                                NSDictionary mapping)

Sets properties of the receiver with values from dictionary, using its keys and mapping to identify the properties. mapping associates the keys of dictionary, which are arbitrary external names for the properties to be set, with the internal or EOModel names for those properties. Each of the keys in dictionary must also be a key in mapping.

The default implementation invokes takeValueForKey for each key-value pair of dictionary, substituting null for NSKeyValueCoding.NullValue values in the dictionary.

Parameters:

dictionary - the key-value pairs to be set

mapping - the dictionary that maps arbitrary external names to internal property names

See Also:

NSKeyValueCoding.takeValueForKey(Object, String)

valuesForKeys

public NSDictionary valuesForKeys(NSArray keys)

Returns a dictionary containing the property values identified by each of keys. The default implementation invokes valueForKey for each key in keys, substituting NSKeyValueCoding.NullValue in the returned dictionary for returned null values.

Parameters:

keys - the array of keys whose values are to be retrieved

Returns:

a dictionary containing the property values identified by each of keys

See Also:

NSKeyValueCoding.valueForKey(String)

valuesForKeysWithMapping

public NSDictionary valuesForKeysWithMapping(NSDictionary mapping)

Returns a dictionary containing the property values identified by each of the key-value pairs in mapping. The keys of the mapping dictionary represent arbitrary external names for properties of an Enterprise Object and the values are the internal or EOModel names for these properties. The default implementation invokes valueForKey for each value in mapping, substituting NSKeyValueCoding.NullValue in the returned dictionary for returned null values.

Parameters:

mapping - the dictionary that maps arbitrary external names to internal property names

Returns:

a dictionary containing the property values identified by each of keys

See Also:

NSKeyValueCoding.valueForKey(String)