When I first started programming on the iPhone, I was concerned about servers or Web sites that required a password to access them — how the heck do you do that? Although I don't use it in the example, this functionality is available to you in the URL loading system as well.

The URL loading system provides classes that you can use for credentials as well as providing secure credential persistence (or storage of the credentials). Credentials can be specified to persist for a single request, for the duration of an application's launch, or permanently in the user's keychain. As I said, although you don't need to use it here, I show you an example a bit later of how to deal with servers that require a username and password.

As you may be aware, cookies are often used to provide storage of data across URL requests. The URL loading system provides interfaces to create and manage cookies as well as sending and receiving cookies from Web servers.

If you're unfamiliar with what it means, a protocol is a convention that defines a set of rules that computers follow to communicate with each other across a network. It includes rules for connection, communication, and data transfer between two computers. The URL loading system natively supports http, https, file, and ftp protocols, and also allows you to extend the protocols that are supported for transferring data.

NSURLConnection provides the most flexible method of downloading the contents of a URL, so of course you'll be using it. (Only the best for my readers.) It provides a simple interface for creating and canceling a connection, and it does that by using delegate methods to control what happens during the process.

Although this may appear daunting at first, it actually isn't much more complex than the table views you've been using. In fact, all you need to do is create the connection and then implement a few delegate methods, such as

To implement asynchronous loading in the RoadTrip application, you need to create a new class: ServerManager.

By now you know the drill.

@class Trip;

@interface ServerManager : NSObject
                                   <UIAlertViewDelegate> {

  NSURLConnection *currentConnection;
  id               delegate;
  NSMutableData   *rxData;
  Trip            *trip;
  SEL              sucessful;
  SEL              connectionError;
}
- (id) initWithModel:(Trip*)theModel delegate:receiver
     sucessfulSelector:(SEL)sucessfulSelector
     connectionErrorSelector:(SEL)connectionErrorSelector;
- (BOOL) get:(NSString*)urlString;
- (void) cancelConnection;
- (void) cancel;
@end

I'll be explaining all the instance variables and methods as I go along, but I want to start with the get: method that creates the NSURLConnection I just spoke of.

Enter the code in Listing 3-2 to ServerManager.m.

- (BOOL)get:(NSString *)urlString{

  [urlString retain];

  NSURLRequest *theRequest=[NSURLRequest
      requestWithURL:[NSURL URLWithString:urlString]
      cachePolicy:
      NSURLRequestReloadIgnoringLocalAndRemoteCacheData
      timeoutInterval:60.0];
  currentConnection=[[NSURLConnection alloc]
   initWithRequest:theRequest delegate:self];
  if (currentConnection) {
    rxData = [[NSMutableData alloc] init];
    return YES;
  }
  else {
    NSLog(@"request error ");
    [self cancel];
    return NO;
  }
}

The get: method in Listing 3-2 shows you how to initiate a connection for a URL, the first step in the downloading process. This connection links you to the server or Web site you want to download data from. It begins by creating an NSURLRequest instance for the URL, specifying the cache access policy and timeout interval for the connection.

You'll use NSURLRequestReloadIgnoringLocalAndRemoteCacheData, which specifies that not only should the local cache data be ignored, but that everyone else who might have been doing any data caching (proxies and other intermediates) should ignore their caches so far as the protocol allows. You do have a few other choices:

NSURLRequestUseProtocolCachePolicy
NSURLRequestReloadIgnoringLocalCacheData
NSURLRequestReturnCacheDataElseLoad
NSURLRequestReturnCacheDataDontLoad
NSURLRequestReloadRevalidatingCacheData

I leave you to explore these on your own.

Stepping through the code in Listing 3-2, you'll note that your next task is to specify a timeout of 60 seconds. Then you create an NSURLConnection instance using the NSURLRequest and specifying the delegate.

currentConnection=[[NSURLConnection alloc]
   initWithRequest:theRequest delegate:self];

If the connection is successful, you create an instance of NSMutableData to store the data that will be provided to the delegate incrementally.

if (currentConnection) {
    rxData = [[NSMutableData alloc] init];
    return YES;
}

If NSURLConnection can't create a connection for the request, initWithRequest:delegate: returns nil, logs the errors, and cancels the connection — [self cancel].

else {
    NSLog(@"request error ");
    [self cancel];
    return NO;
  }

As I said, if things don't work out, you send yourself the cancel message. To set that up, enter the code in Listing 3-3 into ServerManager.m.

- (void)cancel {
  if (currentConnection) {
    [self cancelConnection];
  }
  if (rxData) {
    [rxData release];
    rxData = nil;
  }
}

cancel releases rxdata (the buffer you are using to hold the downloaded data) if it has been allocated and sends itself the cancelConnection message. Enter the code in Listing 3-4 to ServerManager.m to get that message set up for you.

- (void)cancelConnection {

  [currentConnection cancel];
  [currentConnection release];
  currentConnection = nil;
}

All this method does is cancel and release the connection and set the instance variable to nil;.

- (void)connection:(NSURLConnection *)connection didReceiveRe
   sponse:(NSURLResponse *)response {

  [rxData setLength:0];
}

- (void)connection:(NSURLConnection *)connection
                           didReceiveData:(NSData *)data {

  [rxData appendData:data];
}

- (void)connection:(NSURLConnection *)connection
                       didFailWithError:(NSError *)error {
  [self cancel];
  [delegate performSelectorOnMainThread:connectionError
   withObject:error waitUntilDone:YES];

}

- (void)connectionDidFinishLoading:(NSURLConnection *)
                                              connection {

//RoadTripAppDelegate *appDelegate =
//                  RoadTripAppDelegate *) [[UIApplication
//                           sharedApplication] delegate];
//UIApplication* application = [UIApplication
//                                     sharedApplication];
//[appDelegate.activityIndicator stopAnimating];
//application.networkActivityIndicatorVisible = NO;
  [delegate performSelectorOnMainThread:sucessful
   withObject:rxData waitUntilDone:YES];
  [self cancelConnection];
}

- (id) initWithModel:(Trip*)theModel  delegate:receiver
     sucessfulSelector:(SEL)sucessfulSelector
     connectionErrorSelector:(SEL)connectionErrorSelector{

  if (self = [super init]) {
    sucessful = sucessfulSelector;
    connectionError = connectionErrorSelector;
    delegate = [receiver retain];
    trip = theModel;
//  RoadTripAppDelegate *appDelegate = (RoadTripAppDelegate*)
    [[UIApplication sharedApplication] delegate];
//  UIApplication* application =
                       [UIApplication sharedApplication];
//  [appDelegate.activityIndicator startAnimating];
//  application.networkActivityIndicatorVisible = YES;
  }
  return self;
}

RoadTripAppDelegate *appDelegate = (RoadTripAppDelegate *)
             [[UIApplication sharedApplication] delegate];
UIApplication* application = [UIApplication
                                       sharedApplication];
[appDelegate.activityIndicator startAnimating];
application.networkActivityIndicatorVisible = YES;

What I've been highlighting so far in this chapter with regard to dealing with downloads represents the simplest implementation of an application using NSURLConnection. There are some more delegate methods that provide the ability to customize the handling of server redirects, authorization requests, and caching of the response. But as I said, I don't use them here.

But one more thing I do want to explain is handling authentication challenges.

Although the server you are using for RoadTrip doesn't require a user name and password, there will probably be times when the server you want to use will in fact make that request of you. Although I have no need to implement that functionality here, Listing 3-10 shows an example of how you'd do that.

- (void)connection:(NSURLConnection *)connection
   didReceiveAuthenticationChallenge:
                  (NSURLAuthenticationChallenge *)challenge {

  if ([challenge previousFailureCount] != 0) {
    [connection cancel];
    UIAlertView *alert =
           [[UIAlertView alloc] initWithTitle:@"Yo!"

   message:NSLocalizedString (@" Your User Name
              and/or Password is incorrect",
                              @"No user name or password")
           delegate:self
           cancelButtonTitle:NSLocalizedString
                                    (@"Thanks", @"Thanks")
           otherButtonTitles:nil];
    [alert show];
    [alert release];
  }
  else {
    NSURLCredential *credential = [[NSURLCredential alloc]
       initWithUser:[[NSUserDefaults standardUserDefaults]
          stringForKey:kUserNamePreference]
          password:[[NSUserDefaults standardUserDefaults]
          stringForKey:kPasswordPreference]
          persistence:NSURLCredentialPersistenceNone];

[[challenge sender] useCredential:
           credential forAuthenticationChallenge:challenge];
      [credential release];
    }
  }

If a request requires authentication, your delegate receives a connection:didReceiveAuthenticationChallenge: message. At that point, you need to do one of the following:

In the case of Listing 3-10, the delegate has created an NSURLCredential object with the user name and password that are in the application's preferences as well as the type of persistence to use for the credentials, and then sends the [challenge sender] a useCredential:forAuthenticationChallenge: message:

NSURLCredential *credential = [[NSURLCredential alloc]
       initWithUser:[[NSUserDefaults standardUserDefaults]
          stringForKey:kUserNamePreference]
          password:[[NSUserDefaults standardUserDefaults]
          stringForKey:kPasswordPreference]
          persistence:NSURLCredentialPersistenceNone];
[[challenge sender] useCredential:
         credential forAuthenticationChallenge:challenge];
[credential release];

If the authentication has failed previously, it cancels the authentication challenge and informs the user:

if ([challenge previousFailureCount] != 0) {
  [connection cancel];
  UIAlertView *alert =
    [[UIAlertView alloc] initWithTitle:@"Yo!"
      message:NSLocalizedString (@" Your User Name
      and/or Password is incorrect",
                              @"No user name or password")
      delegate:self
      cancelButtonTitle:NSLocalizedString
                                    (@"Thanks", @"Thanks")
      otherButtonTitles:nil];
  [alert show];
  [alert release];
}

Now you can put things in gear by tackling the code behind the saveData:. message. Add what you see in Listing 3-13 to Sight.m.

- (void)saveData:(NSMutableData *) rxData {

    receivedData = rxData;
    [receivedData retain];
    NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocu
     mentDirectory, NSUserDomainMask, YES);
    NSString *documentsDirectory = [paths objectAtIndex:0];
    NSString *filePath = [documentsDirectory stringByAppendingP
     athComponent:sightName];
    NSURL* theFileURL = [[NSURL alloc]
     initFileURLWithPath:(NSString *)filePath];
    [receivedData writeToURL:theFileURL atomically:YES];
    NSURLRequest* theNSURLRequest = [NSURLRequest
                                 requestWithURL:theFileURL];
    [viewController performSelectorOnMainThread:processMethod
               withObject:theNSURLRequest waitUntilDone:NO];

[theFileURL release];
  [receivedData  release];
}

This method more or less does what saveCarServicingData: did in Chapter 4 of Book V.

In Book V, you get the path to the Documents directory.

NSArray *paths =
  NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,
                                   NSUserDomainMask, YES);
NSString *documentsDirectory = [paths objectAtIndex:0];
NSString *filePath = [documentsDirectory
                stringByAppendingPathComponent:fileName];

On the iPhone, you really don't have much choice about where the file goes. Although there's a /tmp directory, I'm going to place this file in the Documents directory — because this is part of my application's sandbox (the part of the iPhone storage I can modify), so it's the natural home for all the app's files.

NSSearchPathForDirectoriesInDomains: returns an array of directories; because I'm only interested in the Documents directory, I use the constant NSDocumentDirectory — and because I'm restricted to my home directory/sandbox, the constant NSUserDomainMask limits the search to that domain. There will be only one directory in the domain, so the one I want will be the first one returned.

Continuing with the tour of Listing 3-13, you'll see that the next big step is creating the complete path by appending the path filename to the directory.

NSString *filePath = [documentsDirectory
                   stringByAppendingPathComponent:fileName];

stringByAppendingPathComponent; precedes the filename with a path separator (/) if necessary.

When you implemented the method in saveCarServicingData: in Book V you wrote the data to the file using :

[dataLoaded writeToFile:filePath atomically:YES];

writeToFile: is an NSData method and does what it implies. I am actually telling the array here to write itself to a file, which is why I decided to save the location in this way in the first place.

A number of other classes can implement the writeToFile: method, including NSDate, NSNumber, NSString, and NSDictionary. (You can also add this behavior to your own objects, and they could save themselves — but I won't get into that here.) The atomically parameter first writes the data to an auxiliary file, and when that's successful, it's renamed to the path you've specified. This situation guarantees that the file won't be corrupted even if the system crashes during the write operation.

In this new implementation, things are pretty much the same, except you use

[receivedData writeToURL:theFileURL atomically:YES];

Because at present only file URLs are supported, there's no difference between this method and writeToFile:atomically:, except for the type of the first argument. You do this because it's the preferred method to use in the URL loading system and is likely to keep you compatible for some time in the future.

Finally saveData: continues to create an NSURLRequest and then perform the selector:

[viewController performSelectorOnMainThread:processMethod
             withObject:theNSURLRequest waitUntilDone:NO];

This final line of code completes the circle by performing the selector (which was passed in at ServerManager initialization in Listing 3-12 and saved in the processMethod instance variable) which results in the loadWebView: message (just as you did previously), passing in the NSURLRequest.

Next you need to implement the getData method if the user is in stored data mode. To do that, enter the code in Listing 3-14.

- (void)getData {

  NSArray *paths = NSSearchPathForDirectoriesInDomains
  (NSDocumentDirectory, NSUserDomainMask, YES);
  NSString *documentsDirectory = [paths objectAtIndex:0];
  NSString *filePath = [documentsDirectory
               stringByAppendingPathComponent:sightName];
  NSURL* theFileURL = [[NSURL alloc]
               initFileURLWithPath:(NSString *)filePath];
  NSURLRequest* theNSURLRequest = [NSURLRequest
                              requestWithURL:theFileURL];
  [viewController performSelectorOnMainThread:processMethod
   withObject:theNSURLRequest waitUntilDone:NO];
  [theFileURL release];
}

getData is essentially the same as saveData:, except it does not first save the data it received from the ServerManager download. Instead, it uses data that was previously saved in saveData:.

Just like what you see in saveData:, getData creates an NSURLRequest and then performs the selector.

[viewController performSelectorOnMainThread:processMethod
             withObject:theNSURLRequest waitUntilDone:NO];

Now you need to take care of the connectionError:: business. Enter the code in Listing 3-15 to Sight.m.

- (void) connectionError:(NSError *)error {

  NSLog(@"Download NSURLConnection failed:%@ %@",
       [error localizedDescription], [[error userInfo]
                objectForKey:NSErrorFailingURLStringKey]);
  UIAlertView *alert = [[UIAlertView alloc]
        initWithTitle:@"There's been a connection failure"
         message:NSLocalizedString
           (@"Couldn't get data to display ",
           @"Couldn't get data to display")
         delegate:self
         cancelButtonTitle:NSLocalizedString
         (@"Thanks", @"Thanks") otherButtonTitles:nil];
  [alert show];
  [alert release];
}

This code logs the error and presents an alert to inform the user of a connection failure. Depending on your application, there might be other things you would want to do here as well.

Finally, you need to do some housekeeping. You have to import the ServerManager. So add

#import "ServerManager.h"

to Sight.m.

You'll also have to declare the methods you have added in the Sight interface. So add the following to Sight.h:

- (void) webViewController:(WebViewController*) controller
          nsurlRequestProcessMethod:(SEL)theProcessMethod;
- (void) downloadData:(NSString*) urlString;
- (void) saveData:(NSMutableData *) rxData;
- (void) getData;

Because the model objects themselves are delegates, there's much less involvement in this generic controller implementation for Trip. Trip's sole job now is to return the delegate object depending on the user's selection. However, you should be aware that a user selection no longer takes place just in RootViewController, but will also take place after SightListController.

Make the modifications to Trip.h you see in Listing 3-16. (Remember that you add the bold and delete the strikethrough.)

#import <MapKit/MapKit.h>
#import <Foundation/Foundation.h>
#import "WebViewController.h"


@class Weather;
@class CarServicing;
@class CarInformation;

@interface Trip :NSObject  <WebViewControllerDelegate>{

  NSString       *tripName;
  CarServicing   *carServicing;
  CarInformation *carInformation;
  Weather        *weather;
  NSMutableArray *sights;

}

@property (nonatomic, retain) NSMutableArray * sights;


- (id) initWithName:(NSString*) theTripName;
//- (void) returnWeather:(id) theViewController;
//- (void) returnCarServicingInformation:(id)
   theViewController;
//- (void) returnCarInformation:(id) theViewController;
- (CLLocationCoordinate2D) initialCoordinate;
- (NSString*) mapTitle;
- (NSArray*) createAnnotations;

- (id) returnSightDelegate:(int) index;
- (id) returnWeatherDelegate;
- (id) returnCarInformationDelegate;
- (id) returnCarServicingDelegate;

@end

As you can see, you'll be deleting the selectors you previously used and instead creating methods that return the right delegate to the WebViewController.

In Listing 3-17, make the changes to Trip.m to implement these new methods.

- (id) returnSightDelegate:(int) index{

  return [sights objectAtIndex:index];
}
- (id) returnWeatherDelegate {

  return weather;
}

- (id) returnCarInformationDelegate {

  return carInformation;
}

- (id) returnCarServicingDelegate {

  return carServicing;
}


/*
- (void) returnWeather:(id) theViewController {
  [theViewController loadWebView:[weather
   weatherRealtime]];
}

- (void) returnCarServicingInformation:(id)
   theViewController {

  [theViewController performSelectorOnMainThread:@
   selector(loadWebView:) withObject:[carServicing
   returnCarServicingInformation] waitUntilDone:NO];
}

- (void) returnCarInformation:(id) theViewController {
  [theViewController performSelectorOnMainThread:@
   selector(loadWebView:) withObject:[carInformation
   returnCarInformation] waitUntilDone:NO];
}
*/

Finally, there's the last remaining method you need in the SightListController — the one you did not implement in Chapter 1 of this minibook. Here's where you respond to the user selecting a particular sight (the Golden Gate Bridge, for example) by sending the Trip the message for the Sight selector and then passing it in when you initialize the WebViewController. Pay particular attention to the code I have highlighted in bold, which does that. Add all of the code in Listing 3-18 to SightListController.m.

- (void)tableView:(UITableView *)tableView
       didSelectRowAtIndexPath:(NSIndexPath *) indexPath {

  [tableView deselectRowAtIndexPath:indexPath
                                            animated:YES];
  UIViewController *targetController ;
  targetController = [[WebViewController alloc]
        initWithTrip:trip
       delegate:[trip returnSightDelegate:indexPath.row]
        webControl:YES
        title:NSLocalizedString(@"Sights", @"Sights") ];
  if (targetController) [[self navigationController] pushView
   Controller:targetController animated:YES];
  [targetController release];
}

Notice you've solved your problem of which Sight object to use, because the SightListController knows what Sight object was chosen in its tableView:didSelectRowAtIndexPath: method.

If you were to compile and build your project at this point, you'd find that any selection in the Sights list would work just fine.

However, if you were to select something like Servicing, you would be thrown into the debugger. That's because, to finish things up, you need to make the changes to CarServicing, CarInformation, and Weather that implement the delegate mechanism now used by the WebViewController (as well as implement the way you now access data in Sight). Read on to find out how to do that.