Translate a SQL statement with multiple conditions into an NSPredicate for use with Core Data

BACKGROUND

The Rade | Eccles team is hard at work to release another fantastic financial utility app very soon that EVERYONE who spends money can use.  This app is using Core Data to manage the data store.  As a developer I have been using SQL for roughly 20 years.  SQL and databases are second nature to me.  Core Data has a fantastic ability to abstract out the complexities of dealing with a specific database product or even the use of raw SQL statements which is great for those who don’t have much database experience.

But I found myself, as many others who have used Core Data, needing to set aside my database and SQL knowledge and learn how to perform what would be a simple SQL statement using a Core Data NSPredicate. In other words, an old dog needed to learn a new trick.

After reviewing the documentation provided by Apple, looking at some sample programs, and searching StackOverflow.com I still couldn’t quite find what I was looking for.  Ultimately I ended up doing what any developer does when a problem presents itself which needs to be resolved… I dove in and used the trial and error method until I figured out what I needed.

I needed to build a Core Data predicate with multiple conditions.  If I were using SQL I would have written something like the following (pseudo-SQL):

SELECT * FROM TRANSACTIONS
WHERE CATEGORY IN (categoryList)
AND LOCATION IN (locationList)
AND TYPE IN (typeList)
AND NOTE contains[cd] "some text"
AND DATE >= fromDate
AND DATE <= toDate

IMPLEMENTATION

The first concept to understand was that I needed to build each condition as its own NSPredicate then use NSCompoundPredicate and pass it an array of all the individual predicates for each condition.  Since all of my conditions are AND conditions I can use
the following statement to build a single NSPredicate from multiple predicates:

predicate = [NSCompoundPredicate andPredicateWithSubpredicates:predicates];

It was obvious how I needed to create the date range condition and “Note” text field condition.  What took a bit more research was using the IN clause to specify a list of values to be substituted.  I found the Apple documentation a bit misleading in this area. In the end it turned out to be quite simple.  I could use the IN clause in the following manner:

predicate = [NSPredicate predicateWithFormat:@"Category.Name IN %@", reportCategories];

In this case reportCategories is simply an array of string values.

SOLUTION

When I put all this together I ended up with a method like this:

NOTE: In this example Category, Location, and Type are Core Data entities
with an attribute called Name.  The resulting predicate is used against a
Core Data entity called Transactions which contains:
NSDate's for both the "fromDate" and "toDate" attributes
Relationships to the Category, Location, and Type entities
An NSString for the "note" attribute.

- (NSPredicate *)buildCustomReportPredicate {
NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
 NSString *documentsDirectory = [paths objectAtIndex:0]; // Get documents folder

 NSMutableArray *predicates = [[NSMutableArray alloc] initWithCapacity:5];

 // date predicate
 NSPredicate *predicate = [NSPredicate predicateWithFormat:@"(Date >= %@) AND (Date <= %@)", self.periodFromDate, self.periodToDate];
 [predicates addObject:predicate];

 // categories predicate
 NSMutableArray *reportCategories = [NSMutableArray arrayWithContentsOfFile:[documentsDirectory stringByAppendingPathComponent:@"ReportCategories"]];
 if ([reportCategories count] > 0) {
 predicate = [NSPredicate predicateWithFormat:@"Category.Name IN %@", reportCategories];
 [predicates addObject:predicate];
 }

 // locations predicate
 NSMutableArray *reportLocations = [NSMutableArray arrayWithContentsOfFile:[documentsDirectory stringByAppendingPathComponent:@"ReportLocations"]];
 if ([reportLocations count] > 0) {
 predicate = [NSPredicate predicateWithFormat:@"Location.Name IN %@", reportLocations];
 [predicates addObject:predicate];
 }

 // types predicate
 NSMutableArray *reportTypes = [NSMutableArray arrayWithContentsOfFile:[documentsDirectory stringByAppendingPathComponent:@"ReportTypes"]];
 if ([reportTypes count] > 0) {
 predicate = [NSPredicate predicateWithFormat:@"Type.Name IN %@", reportTypes];
 [predicates addObject:predicate];
 }

 // note predicate
 NSString *note = [[NSUserDefaults standardUserDefaults] objectForKey:@"ReportNote"];
 if (![note isEqualToString:@""]) {
 predicate = [NSPredicate predicateWithFormat:@"Note contains[cd] %@", note];
 [predicates addObject:predicate];
 }

 // build the compound predicate
 predicate = [NSCompoundPredicate andPredicateWithSubpredicates:predicates];

 [predicates release];
 return predicate;

}

http://www.icab.de/blog/2009/11/15/moving-objects-within-an-nsmutablearray/

Provide an Objective C example of implementing the Disqus API.

BACKGROUND

Recently Rade | Eccles developed a blog reader app for a website which uses Disqus as a commenting platform. We had a requirement to allow users to post comments from the app directly to the website’s Disqus sytem.

What is Disqus? (http://www.disqus.com)

“Disqus (dis·cuss • dĭ-skŭs’) is all about changing the way people think about discussion on the web. We’re big believers in the conversations and communities that form on blogs and other sites. Disqus Comments is for bloggers and publishers who wish to use Disqus on their sites, while Disqus Profile is for the rest of us who are commenting on sites powered by Disqus.”

Disqus provides some online API documentation; however, it is language agnostic.  The Disqus API documentation can be found here: http://wiki.disqus.net/API

DISQUS API INTRO

There are three types of Disqus objects that this API provides access to: forums, threads, and posts. A post is any comment written by a Disqus user. Each post belongs to a thread, which represents a particular topic of conversation. Each thread belongs to a forum. A forum represents a website that is using Disqus. For example, your blog might constitute a single forum, and each blog post would have its own thread.

The API is executed over HTTP using the http://disqus.com/api/(method_name)/ endpoint.  Some methods are a GET request and some are a POST.  All responses are returned using JSON.

IMPLEMENTATION

To speed up the development process we will leverage two publicly available frameworks used by many other developers.  You will need to download both frameworks and integrate them into your project before proceeding.

1. ASIHTTPRequest – An excellent, easy to use wrapper around the CFNetwork API that makes some of the more tedious aspects of communicating with web servers easier. It is written in Objective-C and works in both Mac OS X and iPhone applications. You can download the code and view the documentation here: http://allseeing-i.com/ASIHTTPRequest/
2. JSON Framework – This framework implements a strict JSON parser and generator in Objective-C. You can download the code and view the documentation here: http://code.google.com/p/json-framework/

To post a comment to Disqus we need to use the “create_post” API at the http://disqus.com/api/create_post/ endpoint.  This method is an HTTP POST and requires the following parameters:

• Thread ID
• Message
• Author Name
• Author Email

The message, author name, and author email will come from our app but we need to ask Disqus what the correct thread ID is before we can successfully post a comment.

Our process flow is as follows:

1. User enters a comment, provides a user name and email address, and presses a “Submit” button
2. Request the thread ID from Disqus based on the URL of the thread using the “get_thread_by_url” method (GET)
3. Parse the JSON response to access the thread ID
4. POST the comment using the “create_post” method

STEP 1

For step one we will assume an AddCommentViewController.m exists in our project and the following three headers have been imported:

#import "ASIFormDataRequest.h"
#import "ASIHTTPRequest.h"
#import "SBJSON.h"

There should also be some instance variables for a user name, email address, the comment text itself, and a submit button.

STEP 2

After the user presses the submit button we want to construct our call to “get_thread_by_url”. This method requires two parameters: the forum key and the URL of the thread in which to post a comment. A forum key can be shared among trusted moderators of a forum, and is used to perform actions associated with that forum. The creator of a forum (an administrator or website owner) can get the forum’s key through the API (see below). The API documentation provides instructions on how the administrator can obtain the forum key if necessary.

- (IBAction)submit {
    NSString *DisqusForumKey = [[NSUserDefaults standardUserDefaults] objectForKey:self.feed.forumKey];

    NSString *urlString = [[[NSString alloc] initWithString:@"http://disqus.com/api/get_thread_by_url/"] autorelease];
    urlString = [urlString stringByAppendingFormat:@"?api_version=1.1&url=%@&forum_api_key=%@", blogPostURL, DisqusForumKey];
    NSURL *url = [[NSURL alloc] initWithString:urlString];

    ASIHTTPRequest *request = [ASIHTTPRequest requestWithURL:url];
    [request setDelegate:self];
    [request setDidFinishSelector:@selector(requestDidFinishForThreadID:)];
    [request startAsynchronous];
}

Let’s take a closer look at the code above. In line two we are setting a variable which contains the forum key for the current thread.  You may or not be able to simply hard code the forum key into your code.  In our case we were dealing with multiple distinct and separate forums (databases) each with their own set of threads.

In line four we construct a string with our method endpoint.

In line five we add to that string an optional api version parameter, the URL of the thread, and the forum key.

In line six we construct an NSURL object from our new URL string.

In line eight we construct an ASIHTTPRequest object using our NSURL object.

In line nine we set the delegate to self so we can handle the callback when a response is received.

In line 10 we need to specify a custom callback method because we will be handling two different types of JSON responses in our view controller since we are making two different API calls.  If we didn’t specify a custom didFinishSelector the default callback method would be  - (void)requestFinished:(ASIHTTPRequest *)request. Here we will set requestDidFinishForThreadID as our desired callback.

Finally in line eleven we kick off the asynchronous HTTP request.

STEP 3

Now we need to parse the thread ID out of the JSON response in our custom callback method. All responses are JSON objects with three fields:

• succeeded: Indicates whether the call completed successfully or encountered an error.
• code: “ok” if succeeded, otherwise an short description of the error that occurred.
• message: The body of the response, which will depend on the method being used. In case of error, contains a longer description of the error that occurred.

- (void)requestDidFinishForThreadID:(ASIHTTPRequest *)request {
     NSString *responseString = [request responseString];
     SBJSON *jsonParser = [SBJSON new];
     NSDictionary *dict = (NSDictionary*)[jsonParser objectWithString:responseString];
     [jsonParser release];

     // get thread id
     NSDictionary *messageDictionary = (NSDictionary *)[dict objectForKey:@"message"];
     NSString *threadID = (NSString *)[messageDictionary objectForKey:@"id"];

}

In line two we extract the response string from the HTTP request.

In line three we create a JSON Parser.

In line four we use the JSON parser to return a dictionary of parameters.

In line eight we get a dictionary from the “message” field of the JSON response. The call to the “get_thread_by_url” method returns a thread object in the message field. This object has several parameters which are documented in the Disqus API; however, we are only interested in the ID parameter.

In line ten we retrieve the actual thread ID for the specified URL from the message dictionary.

STEP 4

After we have parsed the thread ID we are ready to construct the call to the “create_post” method to submit the comment to the Disqus database. Add the code below to the requestDidFinishForThreadID method so it looks like this:

- (void)requestDidFinishForThreadID:(ASIHTTPRequest *)request {
 // Use when fetching text data
 NSString *responseString = [request responseString];

 SBJSON *jsonParser = [SBJSON new];
 NSDictionary *dict = (NSDictionary*)[jsonParser objectWithString:responseString];
 [jsonParser release];

 // get thread by url results
 NSDictionary *messageDictionary = (NSDictionary *)[dict objectForKey:@"message"];
 NSString *threadID = (NSString *)[messageDictionary objectForKey:@"id"];

 // assemble the POST data
 NSString *DisqusForumKey = [[NSUserDefaults standardUserDefaults] objectForKey:self.feed.forumKey];

 NSURL *url = [[NSURL alloc] initWithString:@"http://disqus.com/api/create_post/"];
 ASIFormDataRequest *requestPostComment = [ASIFormDataRequest requestWithURL:url];
 [requestPostComment setPostValue:@"1.1" forKey:@"api_version"];
 [requestPostComment setPostValue:threadID forKey:@"thread_id"];
 [requestPostComment setPostValue:userName.text forKey:@"author_name"];
 [requestPostComment setPostValue:userEmail.text forKey:@"author_email"];
 [requestPostComment setPostValue:userComment.text forKey:@"message"];
 [requestPostComment setPostValue:DisqusForumKey forKey:@"forum_api_key"];
 [requestPostComment setDelegate:self];
 [requestPostComment startAsynchronous];

}

Lines 14 and 16 should be familiar as we are getting the forum key and constructing the POST for the “create_post” method.

In line 17, this time we will use ASIFormDataRequest which is used to make an HTTP POST.

In lines 18-23 we set the required parameters for this method call.

Next, we set the delegate to self to receive the response in the callback method. In this case, since we didn’t specify a didFinishSelector the default requestFinished method will be called. Here we could check for errors/failures an issue an appropriate message to the user if necessary.

Finally we kick off the asynchronous HTTP POST.

SOLUTION

At this point as long as the forum keys and the thread URL is correct you should have posted a comment successfully in Disqus.

LINK SUMMARY

Disqus – http://www.disqus.com

Disqus API – http://wiki.disqus.net/API

ASIHTTPRequest – http://allseeing-i.com/ASIHTTPRequest/

JSON Framework – http://code.google.com/p/json-framework/