Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

NSEntityDescription Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/CoreData.framework
Availability
Available in Mac OS X v10.4 and later.
Declared in
NSEntityDescription.h
Companion guides

Overview

Instances of NSEntityDescription are used to describe entities in terms of their name, their properties—attributes and relationships as expressed by NSAttributeDescription and NSRelationshipDescription—and the class by which they are represented. Entities are to managed objects what Class is to id, or—to use a database analogy—what tables are to rows.

An NSEntityDescription object is associated with a specific class whose instances are used to represent entries in a persistent store in applications using the Core Data Framework. Minimally, an entity description should have:

You usually define entities in an NSManagedObjectModel using the data modeling tool in Xcode. NSEntityDescription objects are primarily used by the Core Data Framework for mapping entries in the persistent store to managed objects in the application. You are not likely to interact with them directly unless you are specifically working with models. Like the other major modeling classes, NSEntityDescription provides you with a user dictionary in which you can store any application-specific information related to the entity.

Editing Entity Descriptions

Entity descriptions are editable until they are used by an object graph manager. This allows you to create or modify them dynamically. However, once a description is used (when the managed object model to which it belongs is associated with a persistent store coordinator), it must not (indeed cannot) be changed. This is enforced at runtime: any attempt to mutate a model or any of its sub-objects after the model is associated with a persistent store coordinator causes an exception to be thrown. If you need to modify a model that is in use, create a copy, modify the copy, and then discard the objects with the old model.

If you want to create an entity hierarchy, you need to consider the relevant API. You can only set an entity’s sub-entities (see setSubentities:), you cannot set an entity’s super-entity directly. To set a super-entity for a given entity, you must therefore set an array of subentities on that super entity and include the current entity in that array. So, the entity hierarchy needs to be built top-down.

Using Entity Descriptions in Dictionaries

NSEntityDescription’s copy method returns an entity such that

[[entity copy] isEqual: entity] == NO

Since NSDictionary copies its keys and requires that keys both conform to the NSCopying protocol and have the property that copy returns an object for which [[object copy] isEqual:object] is true, you should not use entities as keys in a dictionary. Instead, you should either use the entity’s name as the key, or use a map table (NSMapTable) with retain callbacks.

Fast Enumeration

In Mac OS X v10.5 and later, NSEntityDescription supports the NSFastEnumeration protocol. You can use this to enumerate over an entity’s properties, as illustrated in the following example:

NSEntityDescription *anEntity = ...;
for (NSPropertyDescription *property in anEntity)
{
    // property is each instance of NSPropertyDescription in anEntity in turn
}

Tasks

Information About an Entity Description

Managing Inheritance

Working with Properties

Retrieving an Entity with a Given Name

Creating a New Managed Object

Supporting Versioning

Copying Entity Descriptions

Class Methods

entityForName:inManagedObjectContext:

Returns the entity with the specified name from the managed object model associated with the specified managed object context’s persistent store coordinator.

+ (NSEntityDescription *)entityForName:(NSString *)entityName inManagedObjectContext:(NSManagedObjectContext *)context

Parameters
entityName

The name of an entity.

context

The managed object context to use.

Return Value

The entity with the specified name from the managed object model associated with the context’s persistent store coordinator.

Discussion

This method is functionally equivalent to the following code example.

NSManagedObjectModel *managedObjectModel = [[context persistentStoreCoordinator] managedObjectModel];
NSEntityDescription *entity = [[managedObjectModel entitiesByName]  objectForKey:entityName];
return entity;
Availability
See Also
Declared In
NSEntityDescription.h

insertNewObjectForEntityForName:inManagedObjectContext:

Creates, configures, and returns a new autoreleased instance of the class for the entity with a given name.

+ (id)insertNewObjectForEntityForName:(NSString *)entityName inManagedObjectContext:(NSManagedObjectContext *)context

Parameters
entityName

The name of an entity.

context

The managed object context to use.

Return Value

A new, autoreleased, fully configured instance of the class for the entity named entityName. The instance has its entity description set and is inserted it into context.

Discussion

Note that despite the word “new” in the method name, the object returned is autoreleased (“new” is not the first word in the method name—see Memory Management Rules)

This method makes it easier for you to create instances of a given entity without having to know the class used to represent the entity, which may be particularly useful early in the development life-cycle when classes and class names are volatile. It also takes care of the details of managed object creation.

This method makes it easier for you to create instances of a given entity without worrying about the details of managed object creation when there is no need to explicitly assign a new managed object to a specific persistent store.

This is particularly useful on Mac OS  X v10.4 as you can use this method to create a new managed object without having to know the class used to represent the entity, especially early in the development life-cycle when classes and class names are volatile. The method is conceptually similar to the following code example.

NSManagedObjectModel *managedObjectModel =
        [[context persistentStoreCoordinator] managedObjectModel];
NSEntityDescription *entity =
        [[managedObjectModel entitiesByName] objectForKey:entityName];
NSString *className = [entity managedObjectClassName];
Class entityClass = [[NSBundle mainBundle] classNamed:className];
id newObject = [[entityClass alloc]
           initWithEntity:entity insertIntoManagedObjectContext:context];
return [newObject autorelease];

On Mac OS  X v10.5 and later, initWithEntity:insertIntoManagedObjectContext: returns an instance of the appropriate class for the entity. The equivalent code for Mac OS  X v10.5 is as follows:

NSManagedObjectModel *managedObjectModel =
        [[context persistentStoreCoordinator] managedObjectModel];
NSEntityDescription *entity =
        [[managedObjectModel entitiesByName] objectForKey:entityName];
NSManagedObject *newObject = [[NSManagedObject alloc]
            initWithEntity:entity insertIntoManagedObjectContext:context];
return [newObject autorelease];
Availability
See Also
Declared In
NSEntityDescription.h

Instance Methods

attributesByName

Returns the attributes of the receiver in a dictionary, where the keys in the dictionary are the attribute names.

- (NSDictionary *)attributesByName

Return Value

The attributes of the receiver in a dictionary, where the keys in the dictionary are the attribute names and the values are instances of NSAttributeDescription. .

Availability
See Also
Declared In
NSEntityDescription.h

copy

Returns a copy of the receiver

- (id)copy

Return Value

A copy of the receiver.

Special Considerations

NSEntityDescription‘s implementation of copy returns an entity such that:

[[entity copy] isEqual:entity] == NO

You should not, therefore, use an entity as a key in a dictionary (see “Using Entity Descriptions in Dictionaries”).

isAbstract

Returns a Boolean value that indicates whether the receiver represents an abstract entity.

- (BOOL)isAbstract

Return Value

YES if the receiver represents an abstract entity, otherwise NO.

Discussion

An abstract entity might be Shape, with concrete sub-entities such as Rectangle, Triangle, and Circle.

Availability
See Also
Declared In
NSEntityDescription.h

isKindOfEntity:

Returns a Boolean value that indicates whether the receiver is a subentity of another given entity.

- (BOOL)isKindOfEntity:(NSEntityDescription *)entity

Parameters
entity

An entity.

Return Value

YES if the receiver is a sub-entity of entity, otherwise NO.

Availability
Declared In
NSEntityDescription.h

managedObjectClassName

Returns the name of the class that represents the receiver's entity.

- (NSString *)managedObjectClassName

Return Value

The name of the class that represents the receiver's entity.

Availability
See Also
Declared In
NSEntityDescription.h

managedObjectModel

Returns the managed object model with which the receiver is associated.

- (NSManagedObjectModel *)managedObjectModel

Return Value

The managed object model with which the receiver is associated.

Availability
See Also
Declared In
NSEntityDescription.h

name

Returns the entity name of the receiver.

- (NSString *)name

Return Value

The entity name of receiver.

Availability
See Also
Declared In
NSEntityDescription.h

properties

Returns an array containing the properties of the receiver.

- (NSArray *)properties

Return Value

An array containing the properties of the receiver. The elements in the array are instances of NSAttributeDescription, NSRelationshipDescription, and/or NSFetchedPropertyDescription.

Availability
See Also
Declared In
NSEntityDescription.h

propertiesByName

Returns a dictionary containing the properties of the receiver.

- (NSDictionary *)propertiesByName

Return Value

A dictionary containing the receiver's properties, where the keys in the dictionary are the property names and the values are instances of NSAttributeDescription and/or NSRelationshipDescription.

Availability
See Also
Declared In
NSEntityDescription.h

relationshipsByName

Returns the relationships of the receiver in a dictionary, where the keys in the dictionary are the relationship names.

- (NSDictionary *)relationshipsByName

Return Value

The relationships of the receiver in a dictionary, where the keys in the dictionary are the relationship names and the values are instances of NSRelationshipDescription.

Availability
See Also
Declared In
NSEntityDescription.h

relationshipsWithDestinationEntity:

Returns an array containing the relationships of the receiver where the entity description of the relationship is a given entity.

- (NSArray *)relationshipsWithDestinationEntity:(NSEntityDescription *)entity

Parameters
entity

An entity description.

Return Value

An array containing the relationships of the receiver where the entity description of the relationship is entity. Elements in the array are instances of NSRelationshipDescription.

Availability
See Also
Declared In
NSEntityDescription.h

setAbstract:

Sets whether the receiver represents an abstract entity.

- (void)setAbstract:(BOOL)flag

Parameters
flag

A Boolean value indicating whether the receiver is abstract (YES) or not (NO).

Special Considerations

This method raises an exception if the receiver’s model has been used by an object graph manager.

Availability
See Also
Declared In
NSEntityDescription.h

setManagedObjectClassName:

Sets the name of the class that represents the receiver's entity.

- (void)setManagedObjectClassName:(NSString *)name

Parameters
name

The name of the class that represents the receiver's entity.

Discussion

The class specified by name must either be, or inherit from, NSManagedObject.

Special Considerations

This method raises an exception if the receiver’s model has been used by an object graph manager.

Availability
See Also
Declared In
NSEntityDescription.h

setName:

Sets the entity name of the receiver.

- (void)setName:(NSString *)name

Parameters
name

The name of the entity the receiver describes.

Special Considerations

This method raises an exception if the receiver’s model has been used by an object graph manager.

Availability
See Also
Declared In
NSEntityDescription.h

setProperties:

Sets the properties array of the receiver.

- (void)setProperties:(NSArray *)properties

Parameters
properties

An array of properties (instances of NSAttributeDescription, NSRelationshipDescription, and NSFetchedPropertyDescription).

Special Considerations

This method raises an exception if the receiver’s model has been used by an object graph manager.

Availability
See Also
Declared In
NSEntityDescription.h

setSubentities:

Sets the subentities of the receiver.

- (void)setSubentities:(NSArray *)array

Parameters
array

An array containing sub-entities for the receiver. Objects in the array must be instances of NSEntityDescription.

Special Considerations

This method raises an exception if the receiver’s model has been used by an object graph manager.

Availability
See Also
Declared In
NSEntityDescription.h

setUserInfo:

Sets the user info dictionary of the receiver.

- (void)setUserInfo:(NSDictionary *)dictionary

Parameters
dictionary

A user info dictionary.

Special Considerations

This method raises an exception if the receiver’s model has been used by an object graph manager.

Availability
See Also
Declared In
NSEntityDescription.h

setVersionHashModifier:

Sets the version hash modifier for the receiver.

- (void)setVersionHashModifier:(NSString *)modifierString

Parameters
modifierString

The version hash modifier for the receiver.

Discussion

This value is included in the version hash for the entity. You use it to mark or denote an entity as being a different “version” than another even if all of the values which affect persistence are equal. (Such a difference is important in cases where, for example, the structure of an entity is unchanged but the format or content of data has changed.)

Availability
See Also
Declared In
NSEntityDescription.h

subentities

Returns an array containing the sub-entities of the receiver.

- (NSArray *)subentities

Return Value

An array containing the receiver's sub-entities. The sub-entities are instances of NSEntityDescription.

Availability
See Also
Declared In
NSEntityDescription.h

subentitiesByName

Returns the sub-entities of the receiver in a dictionary.

- (NSDictionary *)subentitiesByName

Return Value

A dictionary containing the receiver's sub-entities. The keys in the dictionary are the sub-entity names, the corresponding values are instances of NSEntityDescription.

Availability
See Also
Declared In
NSEntityDescription.h

superentity

Returns the super-entity of the receiver.

- (NSEntityDescription *)superentity

Return Value

The receiver's super-entity. If the receiver has no super-entity, returns nil.

Availability
See Also
Declared In
NSEntityDescription.h

userInfo

Returns the user info dictionary of the receiver.

- (NSDictionary *)userInfo

Return Value

The receiver's user info dictionary.

Availability
See Also
Declared In
NSEntityDescription.h

versionHash

Returns the version hash for the receiver.

- (NSData *)versionHash

Return Value

The version hash for the receiver.

Discussion

The version hash is used to uniquely identify an entity based on the collection and configuration of properties for the entity. The version hash uses only values which affect the persistence of data and the user-defined versionHashModifier value. (The values which affect persistence are: the name of the entity, the version hash of the superentity (if present), if the entity is abstract, and all of the version hashes for the properties.) This value is stored as part of the version information in the metadata for stores which use this entity, as well as a definition of an entity involved in an NSEntityMapping object.

Availability
See Also
Declared In
NSEntityDescription.h

versionHashModifier

Returns the version hash modifier for the receiver.

- (NSString *)versionHashModifier

Return Value

The version hash modifier for the receiver.

Discussion

This value is included in the version hash for the entity. See setVersionHashModifier: for a full discussion.

Availability
See Also
Declared In
NSEntityDescription.h

Next Page > Hide TOC

Last updated: 2008-02-08

Did this document help you?
Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.
Get information on Apple products.
Visit the Apple Store online or at retail locations.
1-800-MY-APPLE

Copyright © 2007 Apple Inc.
All rights reserved. | Terms of use | Privacy Notice