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 | |
| Related sample code |
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:
A name
The name of a managed object class
(If an entity has no managed object class name, it defaults to
NSManagedObject.)
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 v10.5 and later and on iPhone OS, 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
-
– name
-
– setName:
-
– managedObjectModel
-
– managedObjectClassName
-
– setManagedObjectClassName:
-
– renamingIdentifier
-
– setRenamingIdentifier:
-
– isAbstract
-
– setAbstract:
-
– userInfo
-
– setUserInfo:
Managing Inheritance
Working with Properties
-
– propertiesByName
-
– properties
-
– setProperties:
-
– attributesByName
-
– relationshipsByName
-
– relationshipsWithDestinationEntity:
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 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
- Available in Mac OS X v10.4 and later.
See Also
Related Sample Code
Declared In
NSEntityDescription.hinsertNewObjectForEntityForName: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 and on iPhone OS, initWithEntity:insertIntoManagedObjectContext: returns an instance of the appropriate class for the entity. The equivalent code for Mac OS X v10.5 and on iPhone OS 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
- Available in Mac OS X v10.4 and later.
See Also
Related Sample Code
Declared In
NSEntityDescription.hInstance 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
- Available in Mac OS X v10.4 and later.
See Also
Related Sample Code
Declared In
NSEntityDescription.hcopy
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
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hisKindOfEntity:
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
- Available in Mac OS X v10.5 and later.
Declared In
NSEntityDescription.hmanagedObjectClassName
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
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hmanagedObjectModel
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
- Available in Mac OS X v10.4 and later.
See Also
-
setEntities:(NSManagedObjectModel) -
setEntities:forConfiguration:: (NSManagedObjectModel)
Declared In
NSEntityDescription.hname
Returns the entity name of the receiver.
- (NSString *)name
Return Value
The entity name of receiver.
Availability
- Available in Mac OS X v10.4 and later.
See Also
Related Sample Code
Declared In
NSEntityDescription.hproperties
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
- Available in Mac OS X v10.4 and later.
See Also
Related Sample Code
Declared In
NSEntityDescription.hpropertiesByName
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
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hrelationshipsByName
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
- Available in Mac OS X v10.4 and later.
See Also
Related Sample Code
Declared In
NSEntityDescription.hrelationshipsWithDestinationEntity:
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
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hrenamingIdentifier
Returns the renaming identifier for the receiver.
- (NSString *)renamingIdentifier
Return Value
The renaming identifier for the receiver.
Discussion
The renaming identifier is used to resolve naming conflicts between models. When creating a mapping model between two managed object models, a source entity and a destination entity that share the same identifier indicate that an entity mapping should be configured to migrate from the source to the destination.
If you do not set this value, the identifier will return the entity's name.
Availability
- Available in Mac OS X v10.6 and later.
See Also
Declared In
NSEntityDescription.hsetAbstract:
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
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hsetManagedObjectClassName:
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
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hsetName:
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
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hsetProperties:
Sets the properties array of the receiver.
- (void)setProperties:(NSArray *)properties
Parameters
- properties
An array of properties (instances of
NSAttributeDescription,NSRelationshipDescription, and/orNSFetchedPropertyDescription).
Special Considerations
This method raises an exception if the receiver’s model has been used by an object graph manager.
Availability
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hsetRenamingIdentifier:
Sets the renaming identifier for the receiver.
- (void)setRenamingIdentifier:(NSString *)value
Parameters
- value
The renaming identifier for the receiver.
Availability
- Available in Mac OS X v10.6 and later.
See Also
Declared In
NSEntityDescription.hsetSubentities:
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
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hsetUserInfo:
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
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hsetVersionHashModifier:
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
- Available in Mac OS X v10.5 and later.
See Also
Declared In
NSEntityDescription.hsubentities
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
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hsubentitiesByName
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
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hsuperentity
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
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.huserInfo
Returns the user info dictionary of the receiver.
- (NSDictionary *)userInfo
Return Value
The receiver's user info dictionary.
Availability
- Available in Mac OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hversionHash
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
- Available in Mac OS X v10.5 and later.
See Also
Declared In
NSEntityDescription.hversionHashModifier
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
- Available in Mac OS X v10.5 and later.
See Also
Declared In
NSEntityDescription.h© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-05-01)
