Overview

MMRecord provides a pattern for interfacing with a server to retrieve records. A record is an object that lives on a server. MMRecord depends on the interface from MMServer for making requests of various types. MMRecord also inherits from NSManagedObject and it is assumed that each type of record also corresponds to a certain type of Entity in a managed object model.

Configuration – Primary Keys

You must configure your Core Data model correctly for MMRecord to work effectively. There are two main parts to consider in configuring your data model. The first is that all record types should have a primary key identified by the MMRecordEntityPrimaryAttributeKey key in the Entity’s userInfo dictionary. This will be used to uniquely identify records in the event of an update. Typically this will be an integer or a string attribute.

Configuration – Primary Key Relationships

The primary key property can also be a relationship. The way the relationship primary key works is by establishing the existence of the parent relationship. In order to do that, the root parent relationship must have a primary key itself in order to be fetchable from Core Data. If the root parent object exists, then MMRecord will traverse the relationships of that existing object to see if the child which we are trying to uniquely identify exists, and if so it will update that object rather than create a duplicate entry in the database. While this is supported for to-many relationships, it is INTENDED for to-one relationships. It’s much easier to reliably identify a unique to-one relationship than a to-many relationship. As such, while to-many relationships are supported, they are ONLY supported if the fields in the Entity directly map to the fields in the response object. If you cannot depend on these fields matching exactly then you should look for ways to refactor the API or your data model, possibly through the use of value transformers or keyPaths.

Configuration – Alternate Name Keys

You can also configure your data model through the use of altername attribute name keys. There is more information on their use above, but these are generally used when the name of an object’s key in the response changes, or when the name is undesirable to use, such as if it is restricted by Core Data, or includes underscores.

Configuration – NSValueTransformers

MMRecord will also respect the NSValueTransformer subclass defined on a transformable attribute. If a value transformer is set on an attribute description, then MMRecord will use that transformer to transform the value for that attribute. If no value transformer is set, then NSKeyedArchiver will be used.

Configuration – Parsing and Population

The parsing and population system of MMRecord can be configured to handle special cases as well. The entry point for customizing this system is the MMRecordRepresentation class, and corresponding MMRecordMarshaler class – which is defined by the representation. You can declare a custom representation on a subclass of MMRecord. For more information about custom representations and marshalers please see those corresponding header files.

Configuration – Dates

The parsing and population can support dates in either date format string form, or unix time stamp number form. If the date from your request is a unix time stamp that is returned in the form of a number, then the date attribute will be populated with a date created from that unix time stamp. No action is required by you.If the value returned is a date format string, then you must override the dateFormatter method in your MMRecord subclass to provide a dateFormatter that can parse that given date format string. That formatter will then be used to populate date attributes for that class of record.

Server

You must create your own version of MMServer that implements the methods in it’s interface. Your server class must make a request and call the response/failure blocks with a response object or error. You must also associate a MMServer subclass with MMRecord or your base subclass of MMRecord that all of your individual records inherit from.

Requests

Each MMRecord subclass has access to methods to start a request. The most basic version of these methods simply takes a URN, data, a context, and a result/failure block. There are other methods for initiating a paged request, and for asking an instance of a record to obtain it’s detail object from the server. All of these methods handle the parsing of the response for you. They use data contained in the object model to know how to create record instances from the response. This is explained in more detail below.

Subclassing Notes

You must create a subclass of MMRecord for every entity in your data model that you wish to support this pattern. There is only one method that you must override: keyPathForResponseObject. One strategy for subclassing is to implement this method, and dateFormatter, in a base subclass for common API responses. You may override additional methods such as recordWithDictionary if you need to, but the idea is that you shouldn’t have to. You should override recordDetailURN if you wish to support detail requests.

Methods to Override

To allow date attribute parsing you must override the dateFormatter method and return a date formatter configured for your server’s date format. To support detail requests you must override recordDetailURN.

Object Construction

Everything needed to populate your records should be defined in your Managed Object Model. By default MMRecord will iterate through the record’s entity’s properties and look for response items with matching names. You can customize the names it searches for using various keys in the entity’s UserInfo dictionary. This method works just as well for relationships and transformable attributes as for normal attributes. If an entity’s inverse relationship entity is also of type MMRecord then instances of that record will be created for a relationship property. Transformable attributes will be created by using the NSValueTransformer class specified in the data model.

Custom Requests

The intended use of this class is that you will create methods on your own record subclasses such as +tweetsForUser: which will call super’s startRequestWithURN method and pass through a context, resultBlock and failureBlock parameters to super. The only parameters that would be determined inside of tweetsForUser would be the request URN and the data parameters required to make that request. This accomplishes the goal of encapsulating request-making logic inside of the data model in a way where it only needs to be defined once for an entire project, as well as taking advantage of the data parsing functionality of MMRecord so that every server call doesn’t need to roll it’s own parsing code.

Custom Request Handlers

You may wish to create and use request methods that include more information than just the generated objects that are supplied by the request’s response. Support for this is supplied through the Custom Request Handler block, which is a block passed into an advanced version of the -startRequestWithURN: method. This block will be called with the full response object in a decoded JSON form to allow you to glean additional information and return it in the form of an object. This works best with data which is not intended to be stored in the database. That object will then be passed to the actual resultBlock for you to use there as well. As a best practice, I recommend creating a custom NSObject subclass to encapsulate whatever piece of information you intend on taking from that response and passing on to the resultBlock. One example of where this may be useful is for driving a list request. You may need to be able to tell how many objects are in the list even if you only received back a few of them. If the request has that information in the meta, or somewhere else, then grab it out, put it in an object and return it. The total result count isn’t something you need stored access to, because it’s really only relevant in that one UI use-case. As such it’s a perfect candidate for this type of system. Another example is MMServerPageManager support. There’s a category on MMRecord for supporting pagination which includes a method called -startPagedRequestWithURN: that uses a Custom Request Handler in it’s implementation. Please look at that as a starting point for implementing this functionality for yourself.

Caching

In general, the best way to implement caching is through the use of NSURLCache and the server’s implementation of the HTTP Cache Control headers. In the event that this is not enough, MMRecord does provide an additional level of caching support. The caching provided by MMRecord is in accordance with the cache control headers and augments the system provided by NSURLCache. If caching is enabled then MMRecord will store the object IDs for each request/response pair that were parsed as part of the last response in a separate SQLite persistent store. It’s important to note that these are stored UNENCRYPTED. IF DATA SECURITY IS A REQUIREMENT CACHING SHOULD NOT BE USED! The methods required to support caching are listed below in the optional subclass methods. The primary one is isRecordLevelCachingEnabled, which should return YES if caching is desired. In addition, the optional method +requestWithURN:data: on MMServer must be implemented as a NSURLRequest object is required for accessing information in NSURLCache.

Queues

All MMRecord resultBlocks and failureBlocks are called on the Main Queue. Support for specific callback queues will be added in a future version.

This extenion to MMRecord enables the user to set various options to customize the behavior of a specific MMRecord request.

This category adds support for running a fetch request alongside the URL request. It is meant for when data is likely to exist in some form, stale or otherwise, in the persistent store and it would be useful to return the existing data as quickly as possible and then follow up soon thereafter with the latest data from a web service.

This category adds improved support for custom handling of pagination within requests. It uses the customResponseBlock functionality documented above to achieve this goal, and is intended both as a great tool for implementing paginated HTTP requests, as well as a reference implementation for how to use the customResponseBlock feature.