Next Page > Hide TOC

NSClassDescription Class Reference

Overview

NSClassDescription is an abstract class that provides the interface for querying the relationships and properties of a class. Concrete subclasses of NSClassDescription provide the available attributes of objects of a particular class and the relationships between that class and other classes. Defining these relationships between classes allows for more intelligent and flexible manipulation of objects with key-value coding.

It is important to note that there are no class descriptions by default. To use NSClassDescription objects in your code you have to implement them for your model classes. For all concrete subclasses, you must provide implementations for all instance methods of NSClassDescription. (NSClassDescription provides only the implementation for the class methods that maintain the cache of registered class descriptions.) Once created, you must register a class description with the NSClassDescription method registerClassDescription:forClass:.

You can use the NSString objects in the arrays returned by methods such as attributeKeys and toManyRelationshipKeys to access—using key-value coding—the properties of an instance of the class to which a class description object corresponds. For more about attributes and relationships, see Cocoa Fundamentals Guide. For more about key-value coding, see Key-Value Coding Programming Guide.

NSScriptClassDescription, which is used to map the relationships between scriptable classes, is the only concrete subclass of NSClassDescription provided as part of the Cocoa framework.

Tasks

Working with Class Descriptions

• + classDescriptionForClass:
• + invalidateClassDescriptionCache
• + registerClassDescription:forClass:

Attribute Keys

• – attributeKeys

Relationship Keys

• – inverseForRelationshipKey:
• – toManyRelationshipKeys
• – toOneRelationshipKeys

Class Methods

classDescriptionForClass:

Returns the class description for a given class.

+ (NSClassDescription *)classDescriptionForClass:(Class)aClass

Parameters

aClass

The class for which to return a class description.

Return Value

The class description for aClass, or nil if a class description cannot be found.

Discussion

If a class description for aClass is not found, the method posts an NSClassDescriptionNeededForClassNotification on behalf of aClass, allowing an observer to register a class description. The method then checks for a class description again. Returns nil if a class description is still not found.

If you have an instance of the receiver’s class, you can use the NSObject instance method classDescription instead.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

invalidateClassDescriptionCache

Removes all NSClassDescription objects from the cache.

+ (void)invalidateClassDescriptionCache

Discussion

You should rarely need to invoke this method. Use it whenever a registered NSClassDescription object might be replaced by a different version, such as when you have loaded a new provider of NSClassDescription objects, or when you are about to remove a provider of NSClassDescription objects.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

registerClassDescription:forClass:

Registers an NSClassDescription object for a given class in the NSClassDescription cache.

+ (void)registerClassDescription:(NSClassDescription *)description forClass:(Class)aClass

Parameters

description

The class description to register.

aClass

The class for which to register description.

Discussion

You should rarely need to directly invoke this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Instance Methods

attributeKeys

Overridden by subclasses to return the names of attributes of instances of the described class.

- (NSArray *)attributeKeys

Return Value

An array of NSString objects containing the names of attributes of instances of the described class.

Discussion

For example, a class description that describes Movie objects could return the attribute keys title, dateReleased, and rating.

If you have an instance of the class the receiver describes, you can use the NSObject instance method attributeKeys instead.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – toManyRelationshipKeys
• – toOneRelationshipKeys

Declared In

inverseForRelationshipKey:

Overridden by subclasses to return the name of the inverse relationship from a relationship specified by a given key.

- (NSString *)inverseForRelationshipKey:(NSString *)relationshipKey

Return Value

The name of the inverse relationship from the relationship specified by relationshipKey.

Discussion

For a given key that defines the name of the relationship from the receiver’s class to another class, returns the name of the relationship from the other class to the receiver’s class. For example, suppose an Employee class has a relationship named department to a Department class, and that Department has a relationship named employees to Employee. The statement:

[employee inverseForRelationshipKey:@"department"];

returns the string employees.

If you have an instance of the class the receiver describes, you can use the NSObject instance method inverseForRelationshipKey: instead.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

toManyRelationshipKeys

Overridden by subclasses to return the keys for the to-many relationship properties of instances of the described class.

- (NSArray *)toManyRelationshipKeys

Return Value

An array of NSString objects containing the names of the to-many relationship properties of instances of the described class.

Discussion

To-many relationship properties are arrays of objects.

If you have an instance of the class the receiver describes, you can use the NSObject instance method toManyRelationshipKeys instead.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – attributeKeys
• – toOneRelationshipKeys

Declared In

toOneRelationshipKeys

Overridden by subclasses to return the keys for the to-one relationship properties of instances of the described class.

- (NSArray *)toOneRelationshipKeys

Return Value

An array of NSString objects containing the names of the to-one relationship properties of instances of the described class.

Discussion

To-one relationship properties are single objects.

If you have an instance of the class the receiver describes, you can use the NSObject instance method toOneRelationshipKeys instead.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – attributeKeys
• – toManyRelationshipKeys

Declared In

Notifications

NSClassDescriptionNeededForClassNotification

Posted by classDescriptionForClass: when a class description cannot be found for a class.

After the notification is processed, classDescriptionForClass: checks for a class description again. This checking allows an observer to register class descriptions lazily. The notification is posted only once for any given class, even if the class description remains undefined.

The notification object is the class object for which the class description is requested. This notification does not contain a userInfo dictionary.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Next Page > Hide TOC