MMRecordRepresentation Class Reference
Inherits from | NSObject |
Declared in | MMRecordRepresentation.h MMRecordRepresentation.m |
Overview
This class encapsulates the representation an MMRecord entity. A representation contains all of the information required to build a full record of this type of entity. MMRecordRepresentation is closely tied to CoreData’s NSEntityDescription. The representation is composed of all of the attributes and relationships for the given entity. It’s job is to keep track of all the possible keys that could ‘represent’ that attribute or relationship in a response dictionary. If you’re trying to figure out what keyPath might map to a record attribute, this class can help.
Default Representation
The default representation is, as described above, very closely tied to the core data model. An entity is composed of a list of properties – typically attributes and relationships. The default representation will attempt to relate each attribute on an entity to a given dictionary. It will use two means to relate them: name, and alternate name. The name of the attribute or relationship will be used as a key to search the dictionary for a value to populate it with. In addition, you can define a key on the attribute or relationship’s user info dictionary that allows you to specify an alternate key path that will be used for searching the dictionary. More information about that can be found on the MMRecord header documentation on model configuration.
Marshalling
This class is closely related to the MMRecordMarshaler class. Generally speaking, if you subclass this class, you will probably also want to subclass the marshaler, and vic versa. While this class controls the representation of an entity, the marshaler controls how it is populated. Those two things tend to go hand in hand, which is also why this class provides the subclass of Marshaler to be used when populating an entity using this representation.
Subclassing Notes
This class is designed to be subclassed. While you don’t have to override the designated initializer, you must remember to call super if you do decide to override it. All of the other methods are optional. With many of them, you will want to call super. Most of the time, subclassers will probably only want to modify behavior slightly, such as to allow other ways to specify alternate attributes. You can, of course, choose to override every method, and provide a completely different form of representation. That will still work, but in that case, you MUST override every single method if you wish to drastically change the way the default representation works.
Every method on the class except for one is part of the public interface and called by another piece of the default MMRecord implementation. The only method which is not is the setupMappingForProperty: method, which is documented below. In depth subclasses should choose to override EVERY method except that one.
Tasks
Other Methods
-
entity
The entity that this object is representing.
property
Designated Initializer
-
– initWithEntity:
This method is the
MMRecordRepresentation
designated initializer.
Marshalling
-
– marshalerClass
This is an optional method that a subclass can override to supply a different marshalling class. The marshalling class is responsible for populating a protorecord based on input from the representation. The default marshal class is MMRecordMarshaler. A subclass may want to use a different marshaler to provide custom behavior for how attributes and relationships are established.
Date Formatting
-
– dateFormatter
This method returns the date formatter used for populating date objects for this entity type.
Attribute Mapping Methods
-
– attributeDescriptions
This method returns all of the attribute descriptions for the entity.
-
– keyPathsForMappingAttributeDescription:
This method returns the possible key paths to search for in order to populate the given attribute description.
Relationship Mapping Methods
-
– relationshipDescriptions
This method returns all of the relationship descriptions for the entity.
-
– keyPathsForMappingRelationshipDescription:
This method returns all of the possible key paths to search for in order to populate the given relationship description.
Optional Mapping Configuration Methods
-
– additionalKeyPathsForMappingPropertyDescription:
This is an optional method meant for overriding subclasses to define their own key path mappings for a property. A basic representation would only look for the name of a property when attempting to populate it. More advanced representations may use this to return alternate keys that they may wish to also use.
-
– setupMappingForProperty:
This method is called to set up the internal mapping system for the given property. This can be a convenient method to override if you wish to take additional action when configuring this property. For example, you may wish to add your own configuration for other methods to use when populating this property. Overriding this method allows you to do that.
Unique Identification Methods
-
– primaryKeyPropertyName
This method returns the name of the primary key property for this entity.
-
– primaryKeyPropertyNameForEntityDescription:
This method is responsible for determining the name of the primary key property given the entity description for this instance of an MMRecordRepresentation.
-
– primaryAttributeDescription
This method returns the primary key attribute description for this entity. This method will return nil if the entity uses a relationship for its primary key.
-
– primaryKeyValueFromDictionary:
This method should return either a number or string that represents the primary key value as obtained from the given dictionary. It should return nil if this entity is using a relationship as its primary key.
-
– hasRelationshipPrimaryKey
This method is used to check if this entity has a relationship as it’s primary key.
-
– primaryRelationshipDescription
This method returns the primary relationship representation if the entity uses a relationship as a primary key
Instance Methods
additionalKeyPathsForMappingPropertyDescription:
This is an optional method meant for overriding subclasses to define their own key path mappings for a property. A basic representation would only look for the name of a property when attempting to populate it. More advanced representations may use this to return alternate keys that they may wish to also use.
- (NSArray *)additionalKeyPathsForMappingPropertyDescription:(NSPropertyDescription *)propertyDescription
Parameters
- propertyDescription
The property description to be used to return additional key paths for.
Return Value
Any additional key paths that should be used for mapping on the given property description.
Discussion
This is an optional method meant for overriding subclasses to define their own key path mappings for a property. A basic representation would only look for the name of a property when attempting to populate it. More advanced representations may use this to return alternate keys that they may wish to also use.
Declared In
MMRecordRepresentation.h
attributeDescriptions
This method returns all of the attribute descriptions for the entity.
- (NSArray *)attributeDescriptions
Return Value
An NSArray containing every NSAttributeDescription
for this entity.
Discussion
This method returns all of the attribute descriptions for the entity.
Declared In
MMRecordRepresentation.h
dateFormatter
This method returns the date formatter used for populating date objects for this entity type.
- (NSDateFormatter *)dateFormatter
Discussion
This method returns the date formatter used for populating date objects for this entity type.
@discussion This date formatter will be used for populating attributes of type Date.
Declared In
MMRecordRepresentation.h
hasRelationshipPrimaryKey
This method is used to check if this entity has a relationship as it’s primary key.
- (BOOL)hasRelationshipPrimaryKey
Return Value
YES if the entity’s primary key is a relationship
Discussion
This method is used to check if this entity has a relationship as it’s primary key.
Declared In
MMRecordRepresentation.h
initWithEntity:
This method is the MMRecordRepresentation
designated initializer.
- (instancetype)initWithEntity:(NSEntityDescription *)entity
Parameters
- entity
The entity that this object is representing.
Discussion
This method is the MMRecordRepresentation
designated initializer.
Declared In
MMRecordRepresentation.h
keyPathsForMappingAttributeDescription:
This method returns the possible key paths to search for in order to populate the given attribute description.
- (NSArray *)keyPathsForMappingAttributeDescription:(NSAttributeDescription *)attributeDescription
Parameters
- attributeDescription
The attribute description we are mapping key paths for.
Return Value
An NSArray containing the key paths for mapping this attribute description.
Discussion
This method returns the possible key paths to search for in order to populate the given attribute description.
Declared In
MMRecordRepresentation.h
keyPathsForMappingRelationshipDescription:
This method returns all of the possible key paths to search for in order to populate the given relationship description.
- (NSArray *)keyPathsForMappingRelationshipDescription:(NSRelationshipDescription *)relationshipDescription
Parameters
- relationshipDescription
The relationship description we are mapping key paths for.
Return Value
An NSArray containing the key paths for mapping this relationship description.
Discussion
This method returns all of the possible key paths to search for in order to populate the given relationship description.
Declared In
MMRecordRepresentation.h
marshalerClass
This is an optional method that a subclass can override to supply a different marshalling class. The marshalling class is responsible for populating a protorecord based on input from the representation. The default marshal class is MMRecordMarshaler. A subclass may want to use a different marshaler to provide custom behavior for how attributes and relationships are established.
- (Class)marshalerClass
Return Value
A subclass of MMRecordMarshaler that implements all required methods of that class’s interface. @discussion The default implementation of this class returns MMRecordMarshaler.
Discussion
This is an optional method that a subclass can override to supply a different marshalling class. The marshalling class is responsible for populating a protorecord based on input from the representation. The default marshal class is MMRecordMarshaler. A subclass may want to use a different marshaler to provide custom behavior for how attributes and relationships are established.
Declared In
MMRecordRepresentation.h
primaryAttributeDescription
This method returns the primary key attribute description for this entity. This method will return nil if the entity uses a relationship for its primary key.
- (NSAttributeDescription *)primaryAttributeDescription
Discussion
This method returns the primary key attribute description for this entity. This method will return nil if the entity uses a relationship for its primary key.
Declared In
MMRecordRepresentation.h
primaryKeyPropertyName
This method returns the name of the primary key property for this entity.
- (NSString *)primaryKeyPropertyName
Discussion
This method returns the name of the primary key property for this entity.
Declared In
MMRecordRepresentation.h
primaryKeyPropertyNameForEntityDescription:
This method is responsible for determining the name of the primary key property given the entity description for this instance of an MMRecordRepresentation.
- (NSString *)primaryKeyPropertyNameForEntityDescription:(NSEntityDescription *)entity
Parameters
- entity
The entity description for this representation.
Return Value
The name of the primary key property for this entity. @discussion This method is designed to be subclassed if the user wishes to provide a different way of determining which property to use as the primary key for a given type of entity.
Discussion
This method is responsible for determining the name of the primary key property given the entity description for this instance of an MMRecordRepresentation.
Warning: This method is called once per entity or superentity until a primary key is found, or no further superentity exists for a given entity. It is in this way that this class supports entity inheritance, meaning that if no primary key property is designated on an entity then the class will go through the chain of superentities to see if a primary key exists there.
Declared In
MMRecordRepresentation.h
primaryKeyValueFromDictionary:
This method should return either a number or string that represents the primary key value as obtained from the given dictionary. It should return nil if this entity is using a relationship as its primary key.
- (id)primaryKeyValueFromDictionary:(NSDictionary *)dictionary
Parameters
- dictionary
The dictionary that contains the primary key value.
Return Value
The primary key value from the given dictionary.
Discussion
This method should return either a number or string that represents the primary key value as obtained from the given dictionary. It should return nil if this entity is using a relationship as its primary key.
Declared In
MMRecordRepresentation.h
primaryRelationshipDescription
This method returns the primary relationship representation if the entity uses a relationship as a primary key
- (NSRelationshipDescription *)primaryRelationshipDescription
Return Value
The `NSRelationshipDescription for the entity’s primary key relationship.
Discussion
This method returns the primary relationship representation if the entity uses a relationship as a primary key
Declared In
MMRecordRepresentation.h
relationshipDescriptions
This method returns all of the relationship descriptions for the entity.
- (NSArray *)relationshipDescriptions
Return Value
An NSArray containing every NSRelationshipDescription
for this entity.
Discussion
This method returns all of the relationship descriptions for the entity.
Declared In
MMRecordRepresentation.h
setupMappingForProperty:
This method is called to set up the internal mapping system for the given property. This can be a convenient method to override if you wish to take additional action when configuring this property. For example, you may wish to add your own configuration for other methods to use when populating this property. Overriding this method allows you to do that.
- (void)setupMappingForProperty:(NSPropertyDescription *)property
Parameters
- property
The property description.
Discussion
This method is called to set up the internal mapping system for the given property. This can be a convenient method to override if you wish to take additional action when configuring this property. For example, you may wish to add your own configuration for other methods to use when populating this property. Overriding this method allows you to do that.
Warning: You MUST call super when overriding this method. @discussion This method is not part of the “public interface” of this class. It is called internally by the default implementation, and is meant as an override point for inserting logic. If you completely override every other method on this class, then you do not need to override this one.
Declared In
MMRecordRepresentation.h