NSEntityDescription Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/CoreData.framework |
| Availability | Available in OS X v10.4 and later. |
| Declared in | NSEntityDescription.h |
| Companion guides | |
Overview
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 a managed object modelusing 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
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
Managing Versioning Support
Copying Entity Descriptions
Managing Compound Indexes
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.
Parameters
- entityName
The name of an entity.
- context
The managed object context to use. Must not be
nil.
Return Value
The entity with the specified name from the managed object model associated with context’s persistent store coordinator.
Discussion
Raises NSInternalInconsistencyException if context is nil.
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 OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hinsertNewObjectForEntityForName:inManagedObjectContext:
Creates, configures, and returns an instance of the class for the entity with a given name.
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
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 conceptually similar to the following code example.
NSManagedObjectModel *managedObjectModel = |
[[context persistentStoreCoordinator] managedObjectModel]; |
NSEntityDescription *entity = |
[[managedObjectModel entitiesByName] objectForKey:entityName]; |
NSManagedObject *newObject = [[NSManagedObject alloc] |
initWithEntity:entity insertIntoManagedObjectContext:context]; |
return newObject; |
Availability
- Available in OS X v10.4 and later.
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.
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 OS X v10.4 and later.
Declared In
NSEntityDescription.hcompoundIndexes
Returns the compound indexes for the entity as an array of arrays.
Return Value
An array of arrays.
The arrays contained in the returned array contain instances of NSAttributeDescription, NSRelationshipDescription that represent properties of the entity, or of NSString that match the name of attributes or relationships of the entity.
Discussion
Availability
- Available in OS X v10.8 and later.
See Also
Declared In
NSEntityDescription.hcopy
Returns a copy of the receiver
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.
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 OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hisKindOfEntity:
Returns a Boolean value that indicates whether the receiver is a sub-entity of another given entity.
Parameters
- entity
An entity.
Return Value
YES if the receiver is a sub-entity of entity, otherwise NO.
Availability
- Available in OS X v10.5 and later.
Declared In
NSEntityDescription.hmanagedObjectClassName
Returns the name of the class that represents the receiver’s entity.
Return Value
The name of the class that represents the receiver’s entity.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hmanagedObjectModel
Returns the managed object model with which the receiver is associated.
Return Value
The managed object model with which the receiver is associated.
Availability
- Available in OS X v10.4 and later.
See Also
-
setEntities:(NSManagedObjectModel) -
setEntities:forConfiguration:: (NSManagedObjectModel)
Declared In
NSEntityDescription.hname
Returns the entity name of the receiver.
Return Value
The entity name of receiver.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hproperties
Returns an array containing the properties of the receiver.
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 OS X v10.4 and later.
Declared In
NSEntityDescription.hpropertiesByName
Returns a dictionary containing the properties of the receiver.
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 OS X v10.4 and later.
Declared In
NSEntityDescription.hrelationshipsByName
Returns the relationships of the receiver in a dictionary, where the keys in the dictionary are the relationship names.
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 OS X v10.4 and later.
Declared In
NSEntityDescription.hrelationshipsWithDestinationEntity:
Returns an array containing the relationships of the receiver where the entity description of the relationship is a given 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 OS X v10.4 and later.
Declared In
NSEntityDescription.hrenamingIdentifier
Returns the renaming identifier for the receiver.
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 OS X v10.6 and later.
See Also
Declared In
NSEntityDescription.hsetAbstract:
Sets whether the receiver represents an abstract entity.
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 OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hsetCompoundIndexes:
Sets the compound indexes for the entity as an array of arrays.
Parameters
- value
An array of arrays.
The arrays contained in value must contain instances of
NSAttributeDescription,NSRelationshipDescriptionthat represent properties of the entity, or ofNSStringthat match the name of attributes or relationships of the entity.
Discussion
Compound indexes are only used by stores that natively support compound indices (the setting is thus only advisory). Indexes apply to the entire inheritance hierarchy.
Availability
- Available in OS X v10.8 and later.
See Also
Declared In
NSEntityDescription.hsetManagedObjectClassName:
Sets the name of the class that represents the receiver’s entity.
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 OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hsetName:
Sets the entity name of the receiver.
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 OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hsetProperties:
Sets the properties array of the receiver.
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 OS X v10.4 and later.
Declared In
NSEntityDescription.hsetRenamingIdentifier:
Sets the renaming identifier for the receiver.
Parameters
- value
The renaming identifier for the receiver.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSEntityDescription.hsetSubentities:
Sets the subentities of the receiver.
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 OS X v10.4 and later.
Declared In
NSEntityDescription.hsetUserInfo:
Sets the user info dictionary of the receiver.
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 OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hsetVersionHashModifier:
Sets the version hash modifier for the receiver.
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 OS X v10.5 and later.
See Also
Declared In
NSEntityDescription.hsubentities
Returns an array containing the sub-entities of the receiver.
Return Value
An array containing the receiver’s sub-entities. The sub-entities are instances of NSEntityDescription.
Availability
- Available in OS X v10.4 and later.
Declared In
NSEntityDescription.hsubentitiesByName
Returns the sub-entities of the receiver in a dictionary.
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 OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hsuperentity
Returns the super-entity of the receiver.
Return Value
The receiver’s super-entity. If the receiver has no super-entity, returns nil.
Availability
- Available in OS X v10.4 and later.
Declared In
NSEntityDescription.huserInfo
Returns the user info dictionary of the receiver.
Return Value
The receiver’s user info dictionary.
Availability
- Available in OS X v10.4 and later.
See Also
Declared In
NSEntityDescription.hversionHash
Returns the version hash for the receiver.
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 OS X v10.5 and later.
Declared In
NSEntityDescription.hversionHashModifier
Returns the version hash modifier for the receiver.
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 OS X v10.5 and later.
See Also
Declared In
NSEntityDescription.h© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-04-23)