diff --git a/Source/MMRecord/MMRecordCache.h b/Source/MMRecord/MMRecordCache.h index 4d67b8d..dfd1698 100644 --- a/Source/MMRecord/MMRecordCache.h +++ b/Source/MMRecord/MMRecordCache.h @@ -22,7 +22,7 @@ #import -/* +/** This class encapsulates the functionality for caching managed objects in correspondence to a particular NSURLRequest's NSCachedURLResponse. It is meant to be a private class used by MMRecord should you wish to enable caching support for a given entity type. However, it could be used as a @@ -46,29 +46,41 @@ @interface MMRecordCache : NSObject -/* +/** This method returns YES if there are cached results for a given key. The key is typically the absolute URL for a given NSURLRequest. You can specify the key using the cacheRecords method below. + @param cacheKey The key used to identify cached results. + @return BOOL YES for has results, NO otherwise. */ + (BOOL)hasResultsForKey:(NSString *)cacheKey; -/* +/** This method retrieves cached results in a given context. If results are cached, it will fetch those objectIDs from the internal caching persistent store and attempt to obtain records matching those object IDs in the provided managed object context. Those records, along with the cached response object (if any) will be returned in the cache result block. This method will also respect the caching policy of the NSURLCache and of this NSURLRequest. If the response for that request is not cached, no results will be returned - regardless of what is found in the cache persistent store. + @param request Request object to obtain cached results for. + @param cacheKey Key used to identify the cached results. + @param metaKeyPath Key used to identify metadata that may have been returned in the response. + @param context managed object context to return cached results in. + @param cacheResultBlock Result block that will be executed when this method finishes checking for + cached results. */ + (void)getCachedResultsForRequest:(NSURLRequest *)request cacheKey:(NSString *)cacheKey metaKeyPath:(NSString *)metaKeyPath context:(NSManagedObjectContext *)context cacheResultBlock:(void(^)(NSArray *cachedResults, id responseObject))cacheResultBlock; -/* +/** This method caches the objectIDs of the given records. Those records should be subclasses of - NSManagedObjectContext. The key provided will be used to locate those records later if a subsequent + NSManagedObject. The key provided will be used to locate those records later if a subsequent request is made for a certain NSURLRequest which you wish to associate with that key. + @param records An array of records that should be cached. + @param metadata Metadata contained in the response that should also be cached. + @param key A key that will be associated with and used to identify cached results. + @param context A managed object context where these records exist. */ + (void)cacheRecords:(NSArray *)records withMetadata:(NSDictionary *)metadata diff --git a/Source/MMRecord/MMRecordDebugger.h b/Source/MMRecord/MMRecordDebugger.h index 8417811..f0ee501 100644 --- a/Source/MMRecord/MMRecordDebugger.h +++ b/Source/MMRecord/MMRecordDebugger.h @@ -157,7 +157,6 @@ typedef NS_ENUM(NSInteger, MMRecordErrorCode) { This message will be handled in a stateless fashion, and will leverage the current logging level set on MMRecord itself. @param description The message you want to display in the log. - @param loggingLevel The minimum logging level for the log message. @warning Messages sent to this method will ONLY be logged if the logging level from MMRecord is set to MMRecordLoggingLevelAll. @discussion This method will only log messages when the logging level is set to ALL in order to diff --git a/Source/MMRecord/MMRecordProtoRecord.h b/Source/MMRecord/MMRecordProtoRecord.h index 849f86f..7428869 100644 --- a/Source/MMRecord/MMRecordProtoRecord.h +++ b/Source/MMRecord/MMRecordProtoRecord.h @@ -27,7 +27,8 @@ @class MMRecord; @class MMRecordRepresentation; -/* This class represents a record in its prototype state before it hatches into a full living breathing +/** + This class represents a record in its prototype state before it hatches into a full living breathing MMRecord. Proto records are typically created to match the contents of a request's response object. If your response object contains an array of 20 records of type "user", then you would create 20 proto records for the user entity. A proto record contains the entity whose type it represents and the @@ -47,36 +48,120 @@ @interface MMRecordProtoRecord : NSObject -// Population +///---------------------------- +/// @name Population Properties +///---------------------------- + +/** + The record instance represented by this proto record. + */ @property (nonatomic, strong) MMRecord *record; + +/** + The dictionary being used to populate this proto record. + */ @property (nonatomic, copy) NSDictionary *dictionary; + +/** + The entity type for this proto record. + */ @property (nonatomic, strong, readonly) NSEntityDescription *entity; + +/** + The representation used to describe this type of proto record. + */ @property (nonatomic, strong, readonly) MMRecordRepresentation *representation; -// Relationships -// Relationship protos and descriptions are returned in no particular order. + +///------------------------------ +/// @name Relationship Properties +///------------------------------ + +/** + An array of relationship proto records that define the objects that will be associated as + relationships on this proto record. + */ @property (nonatomic, strong, readonly) NSArray *relationshipProtos; + +/** + The relationship descriptions for this proto record's type of entity. + */ @property (nonatomic, strong, readonly) NSArray *relationshipDescriptions; -// Uniquing + +///-------------------------- +/// @name Uniquing Properties +///-------------------------- + +/** + The primary key value for this proto record. Typically a string or number. + @warning This will be nil if the proto record uses a relationship as its primary key. + */ @property (nonatomic, strong) id primaryKeyValue; + +/** + The primary key attribute description for this proto record. + @warning This will be nil if the proto record uses a relationship as its primary key. + */ @property (nonatomic, strong) NSAttributeDescription *primaryAttributeDescription; + +/** + The relationship primary key proto is used to reference the proto that can uniquely identify this + record using one of its relationships. + @warning This will be nil if the proto record does not use a relationship as its primary key. + */ @property (nonatomic, weak) MMRecordProtoRecord *relationshipPrimaryKeyProto; + +/** + Property for defining whether or not this record has a relationship as its primary key. + @return YES if the proto record has a relationship as its primary key. + */ @property (nonatomic) BOOL hasRelationshipPrimarykey; -// Designated Initializer +/** + Designated Initializer + + This method is used to instantiate a base proto record. The proto record is configured with a + dictionary that is used to populate the record, an entity to describe the type of record, and a + representation that describes how the record can be populated from that dictionary. This method + should always be used to instantiate a proto record. + + @param dictionary The dictionary used to populate the proto record. + @param entity The type of record this describes. + @param representation The representation used to describe this proto record. + */ + (MMRecordProtoRecord *)protoRecordWithDictionary:(NSDictionary *)dictionary entity:(NSEntityDescription *)entity representation:(MMRecordRepresentation *)representation; -// Associate another proto as having a relationship to this one + +///--------------------------- +/// @name Relationship Methods +///--------------------------- + +/** + This method is used to associate another proto as having a relationship to this one. + @param relationshipProto The proto record representing the relationship. + @param relationshipDescription The relationship on this proto to associate the proto with. + */ - (void)addRelationshipProto:(MMRecordProtoRecord *)relationshipProto forRelationshipDescription:(NSRelationshipDescription *)relationshipDescription; -// Returns YES if there is already a valid relationshipProtoRecord for a given relationshipDescription +/** + This method can be used to tell whether or not there is already a valid relationshipProtoRecord for + a given relationship description. This returns NO if there is already a relationshipProtoRecord for + that relationship. In the case of to-many relationships this will always return YES. + @param relationshipDescription The relationship to determine accomodations for. + @return NO if there is already a valid relationshipProtoRecord for a given relationshipDescription + @discussion In the case of to-many relationships this will always return YES. + */ - (BOOL)canAccomodateAdditionalProtoRecordForRelationshipDescription:(NSRelationshipDescription *)relationshipDescription; -// Returns the proto records for a given relationship description +/** + Returns the proto records for a given relationship description. + @param relationshipDescription The relationship to request proto records for. + @return An array of proto records for the given relationship. + */ - (NSArray *)relationshipProtoRecordsForRelationshipDescription:(NSRelationshipDescription *)relationshipDescription; @end diff --git a/Source/MMRecord/MMRecordResponse.h b/Source/MMRecord/MMRecordResponse.h index 40dba9d..a6d5a5e 100644 --- a/Source/MMRecord/MMRecordResponse.h +++ b/Source/MMRecord/MMRecordResponse.h @@ -1,4 +1,4 @@ -// MMRecordResponseDescription.h +// MMRecordResponse.h // // Copyright (c) 2013 Mutual Mobile (http://www.mutualmobile.com/) // @@ -25,23 +25,58 @@ #import "MMRecord.h" -/* This class describes the response from a request started by MMRecord. It contains the array of objects - obtained from the response object which should be converted into MMRecords. It also contains the initial - entity, which all of the objects in the response object array should be a type of. This class has only - one instance method, -records, which returns an array of MMRecord objects created from the response object. - As such, this class is responsible for building records from the response object based on information from - the inital entity and storing them in the given context. +/** + This class describes the response from a request started by MMRecord. It contains the array of objects + obtained from the response object which should be converted into MMRecords. It also contains the initial + entity, which all of the objects in the response object array should be a type of. This class has only + one instance method, -records, which returns an array of MMRecord objects created from the response object. + As such, this class is responsible for building records from the response object based on information from + the inital entity and storing them in the given context. + + This class represents the entry point for initiating the parsing/population response for MMRecord. + As such, it can be used in a standalone fashion to provide the MMRecord population/parsing support + to other classes and frameworks. An example of how this could be done is the AFMMRecordResponseSerializer, + which uses MMRecordResponse on its own to provide similar behavior in the form of an AFNetworking + response serializer. */ @interface MMRecordResponse : NSObject -// Designated Initializer +/** + Designated Initializer + + This method creates an MMRecordResponse from a response object array, initial entity, and other + information. If a user whiches to initiate the population process with only a single object, then + that object should be inserted into an array to instantiate this class. + + Calling this method and creating an MMRecordResponse configures this class completely in order to + call the records method below and return an array of saturated and populated records. + + @param responseObjectArray An array of objects intended to be used for creating MMRecord instances. + @param initialEntity The initial Core Data entity that will be returned by the records method. + @param context A managed object context to fetch existing records from and store new records to. + @param options A MMRecordOptions object to customize the response handling behaviors. + */ + (MMRecordResponse *)responseFromResponseObjectArray:(NSArray *)responseObjectArray initialEntity:(NSEntityDescription *)initialEntity context:(NSManagedObjectContext *)context options:(MMRecordOptions *)options; -// Records from Response Description +/** + This method is used to launch the entire parsing process. Execution of this method is synchronous. + If you wish to provide asynchronous support (and you probably do), you should call this method from + within an asynchronous block or operation. + + A great way to call this method is from within the managed object context's performBlock or + performBlockAndWait method. + + Its also important to remember to call save on your context after using this method. This method + will not call save for you. It will only insert or update objects in that context. Its up to you + to save those changes. + + @return An array of records of the same type as (or sub-entity of) the initial entity provided + above. + */ - (NSArray *)records; @end diff --git a/Source/MMRecord/MMRecordResponse.m b/Source/MMRecord/MMRecordResponse.m index 90ec590..367928f 100644 --- a/Source/MMRecord/MMRecordResponse.m +++ b/Source/MMRecord/MMRecordResponse.m @@ -1,4 +1,4 @@ -// MMRecordResponseDescription.m +// MMRecordResponse.m // // Copyright (c) 2013 Mutual Mobile (http://www.mutualmobile.com/) //