TweetFollow Us on Twitter

EOKeyValueCoding Volume Number: 16 (2000)
Issue Number: 12
Column Tag: WebObjects

EOKeyValueCoding

By Sam Krishna and Patrick Taylor

Throughout this series we've asserted that programming in WebObjects is a richer, more mature experience than any competing web application development environment. A major reason for this superior programming experience can be laid at the feet of EOKeyValueCoding.

EOKeyValueCoding is simultaneously a powerful protocol (in Objective C) and interface (in Java). When the EOControl framework is imported, all Objective C classes that inherit from NSObject receive EOKeyValueCoding behavior. (The EOControl framework is imported automatically into WebObjects apps and frameworks. You do not have to explicitly import it in to your WebObjects app or framework project.) In Java, when the developer creates a subclass of EOEnterpriseObject, EOCustomObject, EOGenericRecord or WOComponent, then EOKeyValueCoding is available.

What is remarkable about EOKeyValueCoding is how universally powerful it is. With this protocol/interface, the WebObjects and EOF frameworks know how to access custom instance variables (ivars) from within your subclass. Using the methods valueForKey() and takeValueForKey() (in Objective C valueForKey: and takeValue:forKey:) WOF and EOF can access your ivars through standard API. In addition, EOKeyValueCoding provides the bridge within EOF for effective entity-relationship mapping.

In valueForKey(), this standard method allows a lookup of an ivar from both WOF and EOF classes. Consider a WOComponent subclass that needs to fill in the value of a String object in the dynamic WOString element. The WOString is bound to lastName of an EnterpriseObject (EO) which represent the employees of a corporation.

Order of Access

  1. The component subclass searches for a public accessor method based on the key name. With a key of "lastName", valueForKey() looks for a method named getLastName() or lastName(). In Objective C, it looks for a method named getLastName or -lastName.
  2. If a public accessor method isn't found, the component subclass searches for a private accessor method based on key. Note that traditionally in the Apple frameworks, a private method is distinguished by a preceding underbar. In this case, valueForKey() looks for a method named _getLastName() or _lastName(). In Objective C, it looks for a method named _getLastName or -_lastName.
  3. If an accessor method isn't found and the class method accessInstanceVariablesDirectly returns true (in Java) or YES (in Objective C), valueForKey() searches for an ivar based on the key name and returns its value directly. For the key "lastName", this would be _lastName or lastName.
  4. If neither an accessor method or an ivar is found, the default implementation invokes handleQueryWithUnboundKey() in Java or handleQueryWithUnboundKey: in Objective C. The default implementation of this method will raise an NSException.

Sometimes exceptions are raised because although ivars have changed or been deleted for some reason the component subclass or the frameworks still expect the ivar to exist unchanged. In these situations after 10-15 minutes of proverbial pounding sand, we would override handleQueryWithUnboundKey() and check to see if the disputed ivar is being looked up, and if so, return nil or null.

EOKeyValueCoding API to Access Instance Variables

For another example, suppose that you have an EO using a BigDecimal or NSDecimalNumber with "someDecimal" as one of its ivars.

Java

(BigDecimal)myEO.valueForKey("someDecimal");
note: you must always downcast your objects when using valueForKey() in Java

Objective C

[myEO valueForKey:@"someDecimal"];
Here is the operational order for takeValueForKey() (takeValue:forKey: in Objective C)
  1. The EOKeyValueCoding methods search for a public accessor method of the form setKey (setKey: in Objective C)
  2. If a public accessor method isn't found, EOKeyValueCoding searches for a private accessor method of the form _setKey (Objective C _setKey:) invoking it if such a method exists
  3. If an accessor method isn't found and the class method accessInstanceVariablesDirectly returns true or YES, takeValueForKey() searches for an ivar based on the expected key name and sets the value directly in Java. In Objective C, the old value is autoreleased and the new one is retained. For the key "lastName", this would be _lastName or lastName.
  4. If neither an accessor method or an ivar is found, the default implementation invokes handleTakeValueForUnboundKey in Java and handleTakeValue:forUnboundKey: in Objective C.

It is important that while this method has been very well debugged, sometimes phantom keys can be looked up long after they "died". It is prudent to override handleTakeValueForUnboundKey in this situation to check if the phantom key is being looked up and, if so, do nothing.

What are Protocols and Interfaces?

Objective-C protocols and Java interfaces represent essentially the same object-oriented concept: the ability to declare methods that are independent of a particular class and can be implemented by classes in any heirarchy. Any Objective-C class that declares itself to conform to a particular protocol or Java class that implements a particular interface must, by default, implement the methods declared by that protocol/interface. The approaches taken are different with the Objective C approach being arguably more flexible.

Confused? Don't worry — maybe an analogy can make things clearer. Imagine you're writing a nature simulation program which requires that various "animals" have a swimming behavior. Since entirely different kinds of animals can share behaviors even if they come from entirely different species, phyla or families, not every swimming creature inherits from the same class (whales, trout, dogs and humans are all "swimmers" even though they inherit from different classes of "animal": whales do not inherit from trout because whales are mammals while trout are fish, dogs do not inherit from humans because dogs are canines while humans are primates, etc).

In your swimming simulation, you need to have your objects implement a specific type of behavior, but not necessarily the same way. You also want to show what happens when certain types of animals are not able to swim in water (like most species of birds, for example). So, if you are writing an Objective C program, you declare a 'Swimming' protocol. Correspondingly, if you are writing a Java program, you declare a 'Swimming' interface.

The Objective-C protocol declaration may look like this:

@protocol Swimming

- (void)treadWater;
- (void)swimFreestyle;
- (void)breathe;
....

@end

The Java interface declaration may look like this:

public interface Swimming {
    public void treadWater();
    public void swimFreestyle();
    public void breathe();
    ....
}

In the swimming simulation, dogs, humans, whales, trout and ducks implement the Swimming protocol or interface method declarations and would swim in ways unique to those species. A hummingbird, on the other hand, would probably not implement the Swimming protocol or interface, and therefore drown if left in water for a prolonged period of time.

To set the ivar 'someDecimal' to a BigDecimal object of value '1', you would:

Java

myEO.takeValueForKey(new BigDecimal("1"), "someDecimal);

Objective C

[myEO takeValue:[NSDecimalNumber decimalNumberWithString:@"1"] forKey:@"someDecimal"]

What happens when your code accesses ivars that no longer exist?

This is an interesting situation. Most often, this occurs when a developer has removed an ivar from his EO without deleting all references to it from the code. EOF's default behavior is to invoke handleQueryWithUnboundKey in Java and handleQueryWithUnboundKey: in Objective C which throws an exception. Developers can override this if they desire some other behavior or have it fail gracefully (not at all recommended but if it is absolutely necessary ... ).

Corollary behavior occurs when using takeValueForKey (Objective C takeValue:forKey:)on an ivar that doesn't exist. EOF automatically invokes the method handleTakeValueForUnboundKey (Objective C handleTakeValue:forUnboundKey:). There are methods used as private API within EOF that are publicly exposed. storedValueForKey and takeStoredValueForKey in Java (storedValueForKey: and takeStoredValue:forKey: in Objective C) are used to access and/or initialize the receiver's values as they are stored in the database.

Making Life Easier

There are some methods in EOKeyValueCoding that make life considerably easier to get things done. And in the case of Objective C, it provides a very convenient way to implement the NSCoding protocol within a class.

valueForKeyPath (Objective C valueForKeyPath:) allows you to return the value at the end of a relationship path's property. For example, if you wanted to find the name of anEmployee's department, you would:

Java

(String)anEmployee.valueForKeyPath("department.name");

Objective C

[anEmployee valueForKeyPath:@"department.name"];

The relationship from anEmployee to its department was traversed and the department's name accessed. Having done this, you can use another method takeValueForKeyPath (Objective C takeValue:forKeyPath:) to set the name of a relationship's property. To change the name of anEmployee's department:

Java

anEmployee.takeValueForKeyPath("Data Processing","department.name");

ObjectiveC

[anEmployee takeValue:@"Data Processing: forKeyPath:@"department.name"];

valuesForKeys (Objective C valuesForKeys:) returns an NSDictionary of the key-value pairs of an object. It's corollary method takeValuesFromDictionary (Objective C takeValuesFromDictionary:) sets the ivars of an object to the values of the NSDictionary passed as an argument.

What are Ivars/Instance Variables?

Instance variables (also known as ivars) are the specific variables of data for an object instance. What does that mean?

Let's say you have an Employee class which generically defines what an employee looks like. An Employee has a first name, a last name, and a Social Security number. In Objective C, an Employee would look like this:

@interface Employee : NSObject
{
    NSString *firstName;
    NSString *lastName;
    NSString *ssn;
}
....
@end

And in Java, an Employee would look like this:

public class Employee extends Object {
    protected String firstName;
    protected String lastName;
    protected String ssn;
    ....
}

Employee objects, like the employees that represent the CEO and the vice-president, would have a firstName, lastName, and an ssn instance variable. For the CEO, her instance variables might look like this: firstName = "Jane", lastName = "Smith", ssn = "555-12-1234". For the vice-president, his instance variables may look like this: firstName = "John", lastName = "Brown", ssn = "555-12-9876". For the CEO Employee object, its variables contain unique data, and likewise for the vice-president Employee object as well.

EOKeyValueCoding provides a consistent API for the frameworks to access the ivars for the retrieval and modification of data. Whenever a firstName is displayed on a web page in a WebObjects app, it is retrieved through EOKeyValueCoding's APIs. The corresponding modification of ivars occurs through EOKeyValueCoding's APIs on all objects. This consistency allows developers to create applications and frameworks faster because they don't have to think about how the ivars need to be accessed.

These methods can be used to quickly implement the NSCoding protocol in Objective C. The NSCoding protocol can be used to make an object archivable to disk. It consists of two methods encodeWithCoder: and initWithCoder:. Imagining a situation where a developer wished to implement an Employee class that didn't use EOF. Some form of persistence needs to be created for the Employee objects by implementing the NSCoder protocol.

Implementing persistence

Employee.h
#import <Foundation/Foundation.h>
@interface Employee : NSObject <NSCoding>
{
    NSString *firstName;
    NSString *lastName;
    NSString *ssn;
    NSString *streetAddressOne;
    NSString *streetAddressTwo;
    NSString *city;
    NSString *state;
    NSString *zipCode;
    NSDecimalNumber *salary;
}

//  Skip the accessors....

//  EOKeyValueCoding-based methods
- (NSDictionary *)objectAsDictionary;
- (NSArray *)attributeNames;

//  NSCoding methods (which we declare for this example...)
- (id)initWithCoder:(NSCoder *)coder;
- (void)encodeWithCoder:(NSCoder *)coder;

@end

Employee.m
#import "Employee.h"
#import <EOControl/EOKeyValueCoding.h>

@implementation Employee

//  EOKeyValueCoding-based methods
- (NSArray *)attributeNames
{
    //  Return the ivar 'keys' in an NSArray
    return [NSArray arrayWithObjects:
         @"firstName",
         @"lastName",
         @"ssn",
         @"streetAddressOne",
         @"streetAddressTwo",
         @"city",
         @"state",
         @"zipCode",
         @"salary",
        nil];
}

- (NSDictionary *)objectAsDictionary
{
    //  Return the object as an NSDictionary, using the -attributeNames
    //  method to define the keys of the object
    return [self valuesForKeys:[self attributeNames]];
}

- (NSString *)description
{
    //  Inherited from NSObject
    //  Represent the object as an NSDictionary
    return [[self objectAsDictionary] description];
}

//  NSCoding methods
- (void)encodeWithCoder:(NSCoder *)coder
{
    //  NSDictionary already conforms to the NSCoding protocol,  as
    //  well as NSString and NSDecimalNumber
    [super encodeWithCoder:coder];
    [coder encodeObject:[self objectAsDictionary]];
    
    return;
}

- (id)initWithCoder:(NSCoder *)coder
{
    NSDictionary *newSelf;
    
    self = [super initWithCoder:coder];
    newSelf = [coder decodeObject];
    
    //  Since we've already archived ourselves as an NSDictionary,
    //  we can probably take our values from the decoded NSDictionary
    [self takeValuesFromDictionary:newSelf];
    
    return self;
}

@end

This is a simpler (and faster) way of implementing NSCoder, particularly as the number of ivars increasses. In our example, the traditional approach would have required 10-12 additional lines of code for dealing with all of the ivars individually. Instead of all that, the object is archived as an NSDictionary and the EOKeyValueCoding protocol takes care of the rest.

Conclusion

EOKeyValueCoding provides a consistent and convenient API to access and manipulate all of your ivars within your objects. It also provides a uniform way to represent all objects as NSDictionaries to WebObjects and EOF. This helps make object-oriented programming within WebObjects much simpler which is beneficial regardless of your level of expertise.

Unsurprisingly, EOKeyValueCoding is too useful to be kept to EOF and WebObjects alone. Apple recognized its potential by migrating it for JavaClient as NSKeyValueCoding. Even more significant, NSKeyValueCoding appears to be moving into Foundation for use with Cocoa programming. Other than some source code #import changes, all the API stays consistent which now means that persistence within classes will become much simpler.


Please feel free to contact the authors with questions or comments on the articles at webobjectseof@mac.com. We may not be able to reply personally to all emails but every one will be read.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Opera 51.0.2830.34 - High-performance We...
Opera is a fast and secure browser trusted by millions of users. With the intuitive interface, Speed Dial and visual bookmarks for organizing favorite sites, news feature with fresh, relevant content... Read more
ffWorks 1.0.6 - Convert multimedia files...
ffWorks (was iFFmpeg), focused on simplicity, brings a fresh approach to the use of FFmpeg, allowing you to create ultra-high-quality movies without the need to write a single line of code on the... Read more
Adobe Photoshop CC 2018 19.1.1 - Profess...
Photoshop CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Photoshop customer). Adobe Photoshop CC 2018, the industry standard... Read more
Google Chrome 64.0.3282.167 - Modern and...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
Adobe Acrobat Reader 18.011.20035 - View...
Adobe Acrobat Reader allows users to view PDF documents. You may not know what a PDF file is, but you've probably come across one at some point. PDF files are used by companies and even the IRS to... Read more
Adobe Acrobat 18.011.20035 - Powerful PD...
Acrobat DC is available only as a part of Adobe Creative Cloud, and can only be installed and/or updated through Adobe's Creative Cloud app. Adobe Acrobat DC with Adobe Document Cloud services is... Read more
Yummy FTP Pro 2.0 - $29.99
Yummy FTP Pro is an advanced Mac file transfer app which provides a full-featured professional toolkit combined with blazing speeds and impeccable reliability, so whether you want to transfer a few... Read more
WebSnapperPro 2.0.5 - $20.00
WebSnapperPro lets you capture full web pages exactly as they appear in your browser, with a single mouse click, without the need to "stitch" or cut-and-paste. Save the page as an image file or as... Read more
Cocktail 11.3.1 - General maintenance an...
Cocktail is a general purpose utility for macOS that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
Fantastical 2.4.6 - Create calendar even...
Fantastical 2 is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event... Read more

Latest Forum Discussions

See All

Our top 5 characters from casual RPG Cre...
Creature Quest definitely lives up to its name with a host of collectible creatures based on fantasy tales and world mythologies. To celebrate Creature Quest’s first birthday, we’re going to lay out what we think are the five best characters in the... | Read more »
Around the Empire: What have you missed...
Did you know that Steel Media has a whole swathe of other sites dedicated to all aspects of mobile gaming? Sure you'll get the very best iPhone news, reviews, and opinions right here at 148Apps, but we don't want you missing out on a single piece... | Read more »
All the best games on sale for iPhone an...
Oh hi there, and welcome to our round-up of the best games that are currently on sale for iPhone and iPad. You thought I didn't see you there, did you, skulking behind the bushes? Trust me though, the bushes aren't where the best deals are. The... | Read more »
The Battle of Polytopia Guide - How to H...
A new update just released for The Battle of Polytopia (formerly Super Tribes), which introduces online multiplayer. For all the fans of Midjiwan’s lite take on Civilization, this is certainly welcome news, but playing online isn’t as easy and... | Read more »
Here are the very best mobile games to p...
It's Valentine's Day! Did you get loads of cards and chocolates and other tacky, simple expressions of human affection? Did you send out tat because you find it almost impossible to express emotion unless there's a section dedicated to it at your... | Read more »
Florence (Games)
Florence 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Florence is an interactive storybook from the award-winning lead designer of Monument Valley about the heart-racing highs and... | Read more »
Purrfect Date (Games)
Purrfect Date 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Cats are a lil’ like marmite. Either you absolutely head-over-heels love’ em, or… nahhh, who are we kidding?! Everyone... | Read more »
More monsters to collect and evolve in C...
A laid-back mix of RPG and TCG, Creature Quest is all about building your deck, evolving your creatures and winning in battle. It’s the creation of VC Mobile, set up by Might and Magic producer Jon Van Caneghem. There are elements of that classic... | Read more »
Check out this awesome hands-on with the...
Well, PlayerUnknown's Battlegrounds has come out on mobile. This isn't a clone, this isn't a riff on the battleroyale mechanics of the game, it's the official mobile port by Tencent. But there's a little bit of a hitch. [Read more] | Read more »
Hostage Negotiator (Entertainment)
Hostage Negotiator 1.1.0 Device: iOS Universal Category: Entertainment Price: $3.99, Version: 1.1.0 (iTunes) Description: Official app of the board game by AJ Porfirio and Van Ryder Games. In Hostage Negotiator, you play the part of... | Read more »

Price Scanner via MacPrices.net

B&H offers $200 discount on Silver 15″ Ma...
B&H Photo has Silver 15″ Apple MacBook Pros on sale for $200 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 15″ 2.8GHz Touch Bar MacBook Pro Silver (... Read more
12″ Apple iPad Pro Sale of the Year! Models u...
B&H Photo has 12″ #iPad Pros on sale for up to $150 off MSRP. Shipping is free, and B&H charges sales tax in NY & NJ only: – 12″ 64GB WiFi iPad Pro: $719 $80 off MSRP – 12″ 256GB WiFi... Read more
Deals on 32GB 9″ iPads: Up to $50 off MSRP, s...
B&H Photo has 2017 9.7″ 32GB iPads on sale for $299 including free shipping plus NY & NJ sales tax only. Their price is $30 off MSRP, and it’s currently the lowest price available for these... Read more
15″ 2.2GHz Retina MacBook Pro available for o...
Apple has Certified Refurbished 15″ 2.2GHz Retina MacBook Pros available for $1699. That’s $300 off MSRP for this model, and it’s the lowest price available for a 15″ MacBook Pro currently offered by... Read more
13″ 3.1GHz/256GB Silver Touch Bar MacBook Pro...
Amazon has the Silver 13″ 3.1GHz/256GB Touch Bar MacBook Pro (MPXX2LL/A) on sale for $1649.99 including free shipping. Their price is $150 off MSRP, and it’s the lowest price available for a new 13″... Read more
Saturday Sale: Amazon offers 13″ 1.8GHz/256GB...
Amazon has the 13″ 1.8GHz/256B Apple MacBook Air on sale today for $250 off MSRP including free shipping: – 13″ 1.8GHz/256GB MacBook Air (MQD42LL/A): $949.99, $250 off MSRP Their price is the lowest... Read more
Roundup of Apple Certified Refurbished 12″ Ma...
Apple has Certified Refurbished 2017 12″ Retina MacBooks available for $200-$240 off the cost of new models. Apple will include a standard one-year warranty with each MacBook, and shipping is free.... Read more
Apple offers Certified Refurbished 10″ and 12...
Apple is now offering Certified Refurbished 2017 10″ and 12″ iPad Pros for $100-$190 off MSRP, depending on the model. An Apple one-year warranty is included with each model, and shipping is free: –... Read more
Apple Canada offers Certified Refurbished Mac...
 Canadian shoppers can save up to $560 on the purchase of a 2017 current-generation MacBook Pro, MacBook, or MacBook Air with Certified Refurbished models at Apple Canada. Apple’s refurbished prices... Read more
Sale! 13″ MacBook Airs for up to $180 off MSR...
B&H Photo has 13″ MacBook Airs on sale for $50-$120 off MSRP. Shipping is free, and B&H charges sales tax for NY & NJ residents only: – 13″ 1.8GHz/128GB MacBook Air (MQD32LL/A): $899, $... Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple,...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Solutions Consultant - Apple (United...
# Apple Solutions Consultant Job Number: 113501424 Norman, Oklahoma, United States Posted: 15-Feb-2018 Weekly Hours: 40.00 **Job Summary** Are you passionate about Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.