RKEntityMapping Class Reference
Inherits from | RKObjectMapping : RKMapping : NSObject |
Declared in | RKEntityMapping.h |
Overview
RKEntityMapping
objects model an object mapping with a Core Data destination entity.
Entity Identification
One of the fundamental problems when object mapping representations into Core Data entities is determining if a new object should be created or an existing object should be updated. In an entity mapping, one or more attributes can be designated as being used for identification purposes via the identificationAttributes
property. Typically the values of these attributes are populated by attribute mappings. It is common practice to use a single attribute corresponding to the primary key of the remote resource being mapped, but an arbitrary number of attributes may be specified for identification. Identifying attributes have all type transformations support by the mapper applied before the managed object context is searched, supporting such use-cases as using an NSDate
as an identifying attribute whose value is mapped from an NSString
. Identified objects can be further constrained by configuring an identification predicate via the identificationPredicate
property. The predicate is applied after the managed object has been searched.
Identification Inference
The RKEntityMapping
class provides support for inferring identification attributes from the managed object model. When inference is enabled (the default state), the entity is searched for several commonly used identifying attributes and if any is found, the value of the identificationAttributes
property is automatically configured. Inference is performed by the RKIdentificationAttributesInferredFromEntity
function.
When RKIdentificationAttributesInferredFromEntity
is invoked, the entity is first checked for a user info key specifying the identifying attributes. If the user info of the given entity contains a value for the key ‘RKEntityIdentificationAttributes’, then that value is used to construct an array of attributes. The user info key must contain a string or an array of strings specifying the names of attributes that exist in the given entity.
If no attributes are specified in the user info, then the entity is searched for an attribute whose name matches the llama-cased or snake-cased name of the entity. For example, an entity named ‘Article’ would have an inferred identifying attributes of ‘articleID’ and ‘article_id’, and an entity named ‘ApprovedComment’ would be inferred as ‘approvedCommentID’ and ‘approved_comment_id’. If such an attribute is found within the entity, an array is returned containing the attribute. If none is returned, the the attributes are searched for the following names:
- ‘identifier’
- ‘id’
- ‘ID’
- ‘URL’
- ‘url’
If any of these attributes are found, then an array is returned containing the attribute. If all possible inferred attributes are exhausted, then nil
is returned.
Note that inference will only return a single attribute. Compound attributes must be configured manually via the identificationAttributes
property.
Connecting Relationships
When modeling an API into Core Data representation, a common problem is that managed objects that are semantically related are loaded across discrete requests, leaving the Core Data relationships empty. The RKConnectionDescription
class provides a means for expressing a connection between entities using corresponding attribute values or by key path. Please refer to the documentation accompanying the RKConnectionDescription
class and the addConnectionForRelationship:connectedBy:
method of this class.
Tasks
Initializing an Entity Mapping
-
– initWithEntity:
Initializes the receiver with a given entity.
-
+ mappingForEntityForName:inManagedObjectStore:
A convenience initializer that creates and returns an entity mapping for the entity with the given name in the managed object model of the given managed object store.
Accessing the Entity
-
entity
The Core Data entity description used for this object mapping
property
Identifying Managed Objects
-
identificationAttributes
The array of
propertyNSAttributeDescription
objects specifying the attributes of the receiver’s entity that are used during mapping to determine whether an existing object should be updated or a new managed object should be inserted. Please see the “Entity Identification” section of this document for more information. -
identificationPredicate
An optional predicate used to filter identified objects during mapping.
property
Configuring Relationship Connections
-
connections
Returns the array of
propertyRKConnectionDescripton
objects configured for connecting relationships during object mapping. -
– addConnection:
Adds a connection to the receiver.
-
– removeConnection:
Removes a connection from the receiver.
-
– addConnectionForRelationship:connectedBy:
Adds a connection for the specified relationship connected using the attributes specified by the given
NSString
,NSArray
, orNSDictionary
object. -
– connectionForRelationship:
Returns the connection for the specified relationship.
Configuring Validation
-
discardsInvalidObjectsOnInsert
A Boolean value that determines if newly created
propertyNSManagedObject
instances mapped with the receiver should be discarded when they failvalidateForInsert:
.
Flagging Objects for Deletion
-
deletionPredicate
A predicate that identifies objects for the receiver’s entity that are to be deleted from the local store.
property
Retrieving Default Attribute Values
-
– defaultValueForAttribute:
Returns the default value for the specified attribute as expressed in the Core Data entity definition. This value will be assigned if the object mapping is applied and a value for a missing attribute is not present in the payload.
Configuring Entity Identification Inference
-
+ setEntityIdentificationInferenceEnabled:
Enables or disabled entity identification inference.
-
+ isEntityIdentificationInferenceEnabled
Returns a Boolean value that indicates if entity identification inference has been enabled.
Properties
connections
Returns the array of RKConnectionDescripton
objects configured for connecting relationships during object mapping.
@property (nonatomic, copy, readonly) NSArray *connections
Declared In
RKEntityMapping.h
deletionPredicate
A predicate that identifies objects for the receiver’s entity that are to be deleted from the local store.
@property (nonatomic, copy) NSPredicate *deletionPredicate
Discussion
This property provides support for local deletion of managed objects mapped as a ‘tombstone’ record from the source representation.
Declared In
RKEntityMapping.h
discardsInvalidObjectsOnInsert
A Boolean value that determines if newly created NSManagedObject
instances mapped with the receiver should be discarded when they fail validateForInsert:
.
@property (nonatomic, assign) BOOL discardsInvalidObjectsOnInsert
Discussion
This property allows for the deletion of managed objects that fail validation such that NSManagedObjectContext
save will complete successfully. Typically an invalid managed object in the graph will result in a failure to save the NSManagedObjectContext
due to an NSValidation error. In some cases it is desirable to persist only the subset of objects that pass validation and discard the invalid content rather than failing the entire operation. Setting this property to YES
will result in the deletion of in any newly created NSManagedObject
instances that fail to return YES
when sent the validateForInsert:
message.
Default: NO
Declared In
RKEntityMapping.h
entity
The Core Data entity description used for this object mapping
@property (nonatomic, strong) NSEntityDescription *entity
Declared In
RKEntityMapping.h
identificationAttributes
The array of NSAttributeDescription
objects specifying the attributes of the receiver’s entity that are used during mapping to determine whether an existing object should be updated or a new managed object should be inserted. Please see the “Entity Identification” section of this document for more information.
@property (nonatomic, copy) NSArray *identificationAttributes
Return Value
An array of identifying attributes or nil
if none have been configured.
@raises NSInvalidArgumentException Raised if the setter is invoked with the name of an attribute or an NSAttributeDescription
that does not exist in the receiver’s entity. Also raised if the setter is invoked with an empty array.
Discussion
Warning: Note that for convenience, this property may be set with an array containing NSAttributeDescription
objects or NSString
objects specifying the names of attributes that exist within the receiver’s entity. The getter will always return an array of NSAttributeDescription
objects.
Declared In
RKEntityMapping.h
Class Methods
isEntityIdentificationInferenceEnabled
Returns a Boolean value that indicates if entity identification inference has been enabled.
+ (BOOL)isEntityIdentificationInferenceEnabled
Return Value
YES
if entity identification inference is enabled, else NO
.
Declared In
RKEntityMapping.h
mappingForEntityForName:inManagedObjectStore:
A convenience initializer that creates and returns an entity mapping for the entity with the given name in the managed object model of the given managed object store.
+ (instancetype)mappingForEntityForName:(NSString *)entityName inManagedObjectStore:(RKManagedObjectStore *)managedObjectStore
Parameters
- entityName
The name of the entity in the managed object model for which an entity mapping is to be created.
- managedObjectStore
A managed object store containing the managed object model in which an entity with the given name is defined.
Return Value
A new entity mapping for the entity with the given name in the managed object model of the given managed object store.
Discussion
This method is functionally equivalent to the following example code:
NSEntityDescription *entity = [[managedObjectStore.managedObjectModel entitiesByName] objectForKey:entityName];
return [RKEntityMapping mappingForEntity:entity];
Declared In
RKEntityMapping.h
setEntityIdentificationInferenceEnabled:
Enables or disabled entity identification inference.
+ (void)setEntityIdentificationInferenceEnabled:(BOOL)enabled
Parameters
- enabled
A Boolean value indicating if entity identification inference is to be performed.
Discussion
Default: YES
Declared In
RKEntityMapping.h
Instance Methods
addConnection:
Adds a connection to the receiver.
- (void)addConnection:(RKConnectionDescription *)connection
Parameters
- connection
The connection to be added.
Declared In
RKEntityMapping.h
addConnectionForRelationship:connectedBy:
Adds a connection for the specified relationship connected using the attributes specified by the given NSString
, NSArray
, or NSDictionary
object.
- (void)addConnectionForRelationship:(id)relationshipOrName connectedBy:(id)connectionSpecifier
Parameters
- relationshipOrName
The relationship object or name of the relationship object that is to be connected.
- connectionSpecifier
An
NSString
,NSArray
, orNSDictionary
object specifying how the relationship is to be connected by matching attributes.
Discussion
This is a convenience method for flexibly adding a connection to the receiver. The relationship can be specified with by providing an NSRelationshipDescription
object or an NSString
specifying the name of the relationship to be connected. The connection specifier can be provided as an NSString
object, an NSArray
of NSString
object, or an NSDictionary
with NSString
objects for the keys and values. The string objects specify the name of attributes within the entity and destination entity of the specified relationship. The RKConnectionDescription
class models a connection as a dictionary in which the keys are NSString
objects corresponding to the names of attributes in the source entity of the relationship being connected and the values are NSString
objects corresponding to the names of attributes in the destination entity.
When the connectionSpecifier
is an NSString
value, it is interpretted as the name of an attribute in the specified relationship’s entity. The corresponding attribute in the destination entity is determined by invoking the source to destination key transformation block set via [RKObjectMapping setSourceToDestinationKeyTransformationBlock:]
. If no transformation block is configured, then the destination attribute is assumed to have the same name as the source attribute. For example, consider a model in which there entities named ‘User’ and ‘Project’. The ‘User’ entity has a to-many relationship to the ‘Project’ entity named ‘projects’. Both the ‘User’ and the ‘Project’ entities contain an attribute named ‘userID’, which represents the value for the primary key of the ‘User’ in the API the application is communicating with. When the user’s projects are loaded from the ‘/projects’ endpoint, the user ID is sent down in the JSON representation of the Project objects as a numeric value. In order to establish a connection for the ‘projects’ relationship between the ‘User’ and ‘Project’ entities, we could add the connection like so:
// JSON looks like {"project": { "name": "Project Name", "userID": 1234, "projectID": 1 } }
RKEntityMapping *mapping = [RKEntityMapping mappingForEntityForName:@"Project" inManagedObjectStore:managedObjectStore];
[mapping addAttributeMappingsFromArray:@[ @"name", @"userID", @"projectID" ]];
// Find a 'User' whose value for the 'userID' object is equal to the value stored on the 'userID' attribute of the 'Project' and assign it to the relationship
// In other words, "Find the User whose userID == 1234 and assign that object to the 'user' relationship"
[mapping addConnectionForRelationship:@"user" connectedBy:@"userID"];
When the connection is attempted to be established by an instance of RKRelationshipConnectionOperation
, the value for the ‘userID’ attribute will be read from the Project (in this case, @1234) and the managed object context will be searched for a managed object for the ‘User’ entity with a corresponding value for its ‘userID’ attribute.
When the connectionSpecifier
is an NSArray
object, it is interpretted as containing the names of attributes in the specified relationship’s entity. Just as with a stirng value, the corresponding destination attributes are determined by invoking the source to destination key transformation block or they are assumed to have matching names.
When the connectionSpecifier
is an NSDictionary
object, the keys are interpretted as containing the names of attributes on the source entity the values are interpretted as the names of attributes on the destination entity. For example:
// Find the User whose userID is equal to the value stored on the 'createdByUserID' attribute
[mapping addConnectionForRelationship:@"createdByUser" connectedBy:@{ @"createdByUserID": @"userID" }];
See Also
[RKObjectMapping setSourceToDestinationKeyTransformationBlock:]
Declared In
RKEntityMapping.h
connectionForRelationship:
Returns the connection for the specified relationship.
- (RKConnectionDescription *)connectionForRelationship:(id)relationshipOrName
Parameters
- relationshipOrName
The relationship object or name of the relationship object for which to retrieve the connection.
Return Value
The connection object for the specified relationship or nil
if none is configured.
Declared In
RKEntityMapping.h
defaultValueForAttribute:
Returns the default value for the specified attribute as expressed in the Core Data entity definition. This value will be assigned if the object mapping is applied and a value for a missing attribute is not present in the payload.
- (id)defaultValueForAttribute:(NSString *)attributeName
Declared In
RKEntityMapping.h