| 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 | |
An NSEntityDescription object describes an entity in Core Data. Entities are to managed objects what Class is to id, or—to use a database analogy—what tables are to rows. An instance specifies an entity’s name, its properties (its attributes and relationships, expressed by instances of NSAttributeDescription and NSRelationshipDescription) and the class by which it is represented.
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.
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.
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.
In Mac OS v10.5 and later and on iOS, 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 |
} |
– name
– setName:
– managedObjectModel
– managedObjectClassName
– setManagedObjectClassName:
– renamingIdentifier
– setRenamingIdentifier:
– isAbstract
– setAbstract:
– userInfo
– setUserInfo:
– propertiesByName
– properties
– setProperties:
– attributesByName
– relationshipsByName
– relationshipsWithDestinationEntity:
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
The name of an entity.
The managed object context to use.
The entity with the specified name from the managed object model associated with context’s persistent store coordinator.
This method is functionally equivalent to the following code example.
NSManagedObjectModel *managedObjectModel = [[context persistentStoreCoordinator] managedObjectModel]; |
NSEntityDescription *entity = [[managedObjectModel entitiesByName] objectForKey:entityName]; |
return entity; |
NSEntityDescription.hCreates, configures, and returns an instance of the class for the entity with a given name.
+ (id)insertNewObjectForEntityForName:(NSString *)entityName inManagedObjectContext:(NSManagedObjectContext *)context
The name of an entity.
The managed object context to use.
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.
This method makes it easy for you to create instances of a given entity without worrying about the details of managed object creation.
The method is particularly useful on Mac OS X v10.4, as you can use it to create a new managed object without having to know the class used to represent the entity. This is especially beneficial 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 iOS, you can instead use initWithEntity:insertIntoManagedObjectContext: which returns an instance of the appropriate class for the entity. The equivalent code for Mac OS X v10.5 and on iOS 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]; |
Important: Despite the presence of the word “€œnew” in the method name, in a reference counted environment you are not responsible for releasing the returned object. ("new” is not the first word in the method name—see Memory Management Rules).
NSEntityDescription.hReturns the attributes of the receiver in a dictionary, where the keys in the dictionary are the attribute names.
- (NSDictionary *)attributesByName
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. .
NSEntityDescription.hReturns a copy of the receiver
- (id)copy
A copy of the receiver.
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”).
Returns a Boolean value that indicates whether the receiver represents an abstract entity.
- (BOOL)isAbstract
YES if the receiver represents an abstract entity, otherwise NO.
An abstract entity might be Shape, with concrete sub-entities such as Rectangle, Triangle, and Circle.
NSEntityDescription.hReturns a Boolean value that indicates whether the receiver is a sub-entity of another given entity.
- (BOOL)isKindOfEntity:(NSEntityDescription *)entity
An entity.
YES if the receiver is a sub-entity of entity, otherwise NO.
NSEntityDescription.hReturns the name of the class that represents the receiver’s entity.
- (NSString *)managedObjectClassName
The name of the class that represents the receiver’s entity.
NSEntityDescription.hReturns the managed object model with which the receiver is associated.
- (NSManagedObjectModel *)managedObjectModel
The managed object model with which the receiver is associated.
setEntities: (NSManagedObjectModel)setEntities:forConfiguration:: (NSManagedObjectModel)NSEntityDescription.hReturns the entity name of the receiver.
- (NSString *)name
The entity name of receiver.
NSEntityDescription.hReturns an array containing the properties of the receiver.
- (NSArray *)properties
An array containing the properties of the receiver. The elements in the array are instances of NSAttributeDescription, NSRelationshipDescription, and/or NSFetchedPropertyDescription.
NSEntityDescription.hReturns a dictionary containing the properties of the receiver.
- (NSDictionary *)propertiesByName
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.
NSEntityDescription.hReturns the relationships of the receiver in a dictionary, where the keys in the dictionary are the relationship names.
- (NSDictionary *)relationshipsByName
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.
NSEntityDescription.hReturns an array containing the relationships of the receiver where the entity description of the relationship is a given entity.
- (NSArray *)relationshipsWithDestinationEntity:(NSEntityDescription *)entity
An entity description.
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.
NSEntityDescription.hReturns the renaming identifier for the receiver.
- (NSString *)renamingIdentifier
The renaming identifier for the receiver.
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.
NSEntityDescription.hSets whether the receiver represents an abstract entity.
- (void)setAbstract:(BOOL)flag
A Boolean value indicating whether the receiver is abstract (YES) or not (NO).
This method raises an exception if the receiver’s model has been used by an object graph manager.
NSEntityDescription.hSets the name of the class that represents the receiver’s entity.
- (void)setManagedObjectClassName:(NSString *)name
The name of the class that represents the receiver’s entity.
The class specified by name must either be, or inherit from, NSManagedObject.
This method raises an exception if the receiver’s model has been used by an object graph manager.
NSEntityDescription.hSets the entity name of the receiver.
- (void)setName:(NSString *)name
The name of the entity the receiver describes.
This method raises an exception if the receiver’s model has been used by an object graph manager.
NSEntityDescription.hSets the properties array of the receiver.
- (void)setProperties:(NSArray *)properties
An array of properties (instances of NSAttributeDescription, NSRelationshipDescription, and/or NSFetchedPropertyDescription).
This method raises an exception if the receiver’s model has been used by an object graph manager.
NSEntityDescription.hSets the renaming identifier for the receiver.
- (void)setRenamingIdentifier:(NSString *)value
The renaming identifier for the receiver.
NSEntityDescription.hSets the subentities of the receiver.
- (void)setSubentities:(NSArray *)array
An array containing sub-entities for the receiver. Objects in the array must be instances of NSEntityDescription.
This method raises an exception if the receiver’s model has been used by an object graph manager.
NSEntityDescription.hSets the user info dictionary of the receiver.
- (void)setUserInfo:(NSDictionary *)dictionary
A user info dictionary.
This method raises an exception if the receiver’s model has been used by an object graph manager.
NSEntityDescription.hSets the version hash modifier for the receiver.
- (void)setVersionHashModifier:(NSString *)modifierString
The version hash modifier for the receiver.
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.)
NSEntityDescription.hReturns an array containing the sub-entities of the receiver.
- (NSArray *)subentities
An array containing the receiver’s sub-entities. The sub-entities are instances of NSEntityDescription.
NSEntityDescription.hReturns the sub-entities of the receiver in a dictionary.
- (NSDictionary *)subentitiesByName
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.
NSEntityDescription.hReturns the super-entity of the receiver.
- (NSEntityDescription *)superentity
The receiver’s super-entity. If the receiver has no super-entity, returns nil.
NSEntityDescription.hReturns the user info dictionary of the receiver.
- (NSDictionary *)userInfo
The receiver’s user info dictionary.
NSEntityDescription.hReturns the version hash for the receiver.
- (NSData *)versionHash
The version hash for the receiver.
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.
NSEntityDescription.hReturns the version hash modifier for the receiver.
- (NSString *)versionHashModifier
The version hash modifier for the receiver.
This value is included in the version hash for the entity. See setVersionHashModifier: for a full discussion.
NSEntityDescription.hLast updated: 2010-04-06