/*
 * Copyright 2010 Dave Finster
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *    http://www.apache.org/licenses/LICENSE-2.0
 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

Purpose:
I've developed a few iPhone applications with APIs to operate along-side them. 
As a result, I found myself duplicating large amounts of my code to do with 
network operations across projects. ALl the APIs that I develop are REST 
oriented so that is how I have positioned this library. While some of this 
code is very simple and may not require a library, it addresses three 
challenges that I have faced in my projects.

1. Multi-Part Uploads
	In some of my projects, I've had the need to upload not just text, but 
also images and files. There aren't any in-built methods of doing this on 
the iOS SDK so I wrote my own based on the feedback and suggestions of 
various forums. The RKRequestMultipartBody makes this process simple. 

2. Direct-To-Disk Downloading
	One of my projects involved downloading fairly large files, making it 
impractical to store data in memory during download. As a result, I've 
added this functionality to both RKRequest (the basic REST request) and 
the RKRestFileRequest class which handles the creation and configuration 
of the requests.
	
3. Progress
	Throughout any of the projects which needed intense network activity, 
we developers need to keep our users up to date. I decided to add 
notification generation to the RKRestRequest classes allowing multiple 
objects to observe progress updates in both upstream and downstream 
directions.

4. Central Tracking of Activity
	Using the RKRequestManager class, every single active network operation,
its progress and its controlling object can be easily accessed and tracked. 
This is useful for adding a status page which details exactly what your app 
is doing and potentially allow the user to cancel certain operations.

5. Easy, but manageable Image Download
	Using the RKImageLoader class, you get access to a simple way of 
downloading a large set of images in a controlled manager that won't have 
20 or so separate NSURLConnection objects executing at once. Simply get 
the URL of the image that you want to download and have your object 
implement the RKImageLoaderDelegate protocol and the rest is taken care of 
for you. Since this makes use of the same RKRequest class, all image 
downloads are also trackable within the RKRequestManager. Images that are 
downloaded are also cached for future use.

6. Simple embedding of remote images
	Using the RKRemoteImageView class, a subclass of UIImageView, its easy 
to embed images located on remote servers cleanly in your app. The view is 
initiated with an URL (optionally) and a frame. When supplied with a URL, 
a centrally positioned UIActivityIndicatorView is automatically added and 
animated for the duration of the download. Once the download is complete, 
the image is automatically inserted and the activity indicator is hidden.

Examples:
Say there is a public API somewhere called example.com that complies with REST 
and allows you to interact with an events entity. Restkit makes this a little 
easier to do.

For a GET (eg. get a list of events):
RKRestRequest *rest = [[RKRestRequest alloc] 
						initWithURL:[NSURL URLWithString:@"http://api.example.com/events"] 
						requestBody:nil];
rest.delegate = self;
rest.requestMethod = RKRestRequestGet;
[rest go];

Assuming self conforms to RKRestRequestDelegate, self will receive a callback in 
-(void)requestDidComplete:(RKRequest *)request;
during which self can call rest.receivedData to access what was downloaded.

For a GET which returns an image
RKRestFileRequest *rest = [[RKRestFileRequest alloc]
							initWithURL:[NSURL URLWithString:@"http://api.example.com/events/1/image"] 
							requestBody:nil 
							filePath:pathToImage];
rest.delegate = self;
rest.requestMethod = RKRestRequestGet;
[rest go];

Once the request completes, the delegate will still receive a 
-(void)requestDidComplete:(RKRequest *)request;
callback. The difference here is that instead of request.receivedData containing 
whatever was downloaded, it will be nil. Instead, whichever file the request was 
instructed to download will now be available at the specified file path which can 
be accessed through request.filePath.

For a simple POST (eg. create an event):
RKRequestBody *body = [[RKRequestBody alloc] init];
[body addField:"eventName" text:@"My Awesome Event"];
[body addField:"eventDescription" text:@"..."];
RKRestRequest *rest = [[RKRestRequest alloc] 
						initWithURL:[NSURL URLWithString:@"http://api.example.com/events"] 
						requestBody:body];
rest.delegate = self;
rest.requestMethod = RKRestRequestPost;
[rest go];

As before, once the request is complete, self will receive a callback.

For a complex POST (eg. create an event with an attached image and invitation PDF):
RKRequestMultipartBody *body = [[RKRequestMultipartBody alloc] init];
[body addField:"eventName" text:@"My Awesome Event"];
[body addField:"eventDescription" text:@"..."];
[body addField:"eventImage" image:imageObject fileName:@"awesome_event.jpg"];
[body addField:"eventImage" filePath:pathToPDFFile fileName:@"awesome_event_invitation.pdf"];
[body finalizeBody];
RKRestRequest *rest = [[RKRestRequest alloc] 
						initWithURL:[NSURL URLWithString:@"http://api.example.com/events"] 
						requestBody:body];
rest.delegate = self;
rest.requestMethod = RKRestRequestPost;
[rest go];

As before, once the request is complete, self will receive a callback.

Now, if we are doing a very intense upload operation as above, there are two facilities that we 
can use to keep up to date with the live progress of the request.

1. Implement delegate methods
	In the RKRestRequestDelegate protocol there are two methods:
	-(void)uploadProgressDidUpdate:(RKRequest *)request progress:(double)progress;
	-(void)downloadProgressDidUpdate:(RKRequest *)request progress:(double)progress;
	These methods are optional, however if they are implemented, then the delegate will receive 
	updates regarding the upload and download of the original request/response respectively. The 
	range of values are from 0.0 to 1.0. 

2. Turn Notifications On
	In the above example, by adding:
	rest.generateNotifications = YES
	the request will not only check to see if the delegate methods are implemented (both can be used),
	it will also generate NSNotifications of types:
	RKRestRequestUploadProgressUpdateNotification
	RKRestRequestDownloadProgressUpdateNotification
	through the NSNotificationCenter so that any object in your code which has been registered as an 
	observer can receive the same updates as the delegate object.