The simplest network application architecture consists of a database and an interface. Architects refer to this design as two-tier or client-server architecture. You can see this design in Figure 11-1. In this design, the client application resides on the mobile device or computer, and implements the application interface. Additionally, the client software includes the implementation of the business rules that govern the functionality of the application. The server tier is generally an enterprise database such as Oracle, SQLServer, or MySQL, which can share its data with many connected clients.

Figure 11.1. Two-tier architecture

You see this type of client-server architecture when you look at web servers, particularly web servers that serve simple HTML web pages. The client in this design is your web browser and the server is the web server. Many clients connect to the same web server to get data. The client web browser hosts the user interface and the logic to display the HTML data.

This architecture is most appropriate for simple applications. However, as the business rules for your application become more complex, you will likely outgrow this design. In order to maintain encapsulation of functionality, the client should be responsible for displaying data and the server for storing it. If there are minimal rules that govern the logic and data of the application, you could implement them either in the database or on the client.

As the number and complexity of the rules that define the functionality of your application increase, you will need to decide where you want to implement those rules. You could implement them on the client. If your client software were a "thick" desktop application, changing rules would mean re-deploying your application to your clients. If the client is a "thin" web-browser based client, you are constrained by the capabilities and performance of the browser and client-side languages such as JavaScript.

As the business rules of your application get more complex, you will often need to add a third tier to your application architecture. It is in this tier where the business rules reside. In this design, you can decouple your business rules from both the display logic of the client software and the storage system of the database.

As you learned in the last section, you need to consider your application's ability to maintain a complex set of business rules in your design. As you design your system, you need to consider the complexity of the rules that govern your application and the likelihood that these rules could change. For instance, if you are building an order entry system, you need to consider the fact that customer discount percentages could change. You may not want to code these percentages into the user interface layer of your application because any changes to this data would require a redeployment of your software. In instances like this, it is common for the designer to pull these business rules out of the interface and place them in their own logical software layer. The client-server design then evolves into a three-tier (or n-tier if more than one business layer is necessary) architecture (see Figure 11-2).

Figure 11.2. Three-tier architecture

In a three-tier design, the application architect moves the business logic in to its own logical and perhaps physical process. You can therefore decouple the business rules from the user interface and the database. This gives the designer more flexibility when it comes to designing the database, the interface, and the business logic. It also effectively encapsulates each of these important features of a system. It is easier to manage the business logic of your system if you do not tightly couple this code to the database or the user interface. This simplifies making changes to any one of the layers of the design without affecting any of the other layers. In this design, all of the rules that govern what data can be added to the database and specific calculations that are performed on that data are moved out of the interface layer into their own tier. Many commercial application servers such as WebLogic, Apache Tomcat, and WebSphere perform this function.

Client applications need to be able to talk to the business tier or application server and the application server needs to be able to talk to the database.

Typically, the application server and database reside on the same local network, although this is not necessary. These two layers generally communicate through an interface layer that knows how to call functions in the database. A common interface API for database communication is Open Database Connectivity (ODBC). Most programming languages provide support APIs for connecting to databases as well. The Microsoft .NET platform provides an API called ADO.NET while the Java system provides JDBC.

For the client to business-tier communication, the designer can implement connectivity using a variety of methods depending on the languages and operating systems used in the implementation.

In the past, designers of Windows systems would have used DCOM or Distributed Component Object Model. This technology allowed components on different computers to talk to each other. In a Java-based system, the designer could choose a similar technology called Java Remote Method Invocation (RMI). In this system, objects running in one Java virtual machine can call methods on objects in another virtual machine. CORBA, or Common Object Request Broker Architecture, is another technology that enables remote machines to execute methods and share data with one another. The advantage of CORBA is that it is language independent. There are CORBA implementations for most major computer languages and operating systems.

A more current technology enables the designer to implement the functionality of the business tier as a web service. With this technology, the designer can expose the business logic of the application using a web server. Client software can then use well-known methods of the HTTP protocol to access the services exposed by the application server.

There are two predominant protocols used for exchanging data with web services: SOAP and REST. You will look at SOAP in this section and examine REST in the next.

Microsoft originally developed SOAP (Simple Object Access Protocol) in the late 90s and the W3C standards body has standardized the protocol. The designers built SOAP to be platform- and language-agnostic in order to replace technologies such as CORBA and DCOM. The designers chose XML as the format for the messages in an effort to avoid some of the problems associated with the binary-based messaging systems that SOAP would replace.

Unlike CORBA and DCOM, the designers of SOAP decided to send messages using the HTTP protocol, which makes network configuration easy. If users could see each other over the Web using a browser, they could send messages to each other using SOAP.

SOAP messages share a common element with other messaging formats such as HTML in that the message contains a header and a body. The header contains details about the type of message, format of the data, and so on. The body holds the "payload" or the data that the user intends to transmit.

One issue with using SOAP is the complexity of the messages. In order to transmit a little bit of data, users of SOAP often need to transmit long messages. For example, here is the SOAP request message that you would send to the eBay SOAP API to obtain the official eBay time (from eBay.com: using the eBay API to get the official eBay time):

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header>
    <RequesterCredentials soapenv:mustUnderstand="0"
        xmlns="urn:ebay:apis:eBLBaseComponents">
       <eBayAuthToken>ABC...123</eBayAuthToken>
       <ns:Credentials xmlns:ns="urn:ebay:apis:eBLBaseComponents">
        <ns:DevId>someDevId</ns:DevId>
        <ns:AppId>someAppId</ns:AppId>
        <ns:AuthCert>someAuthCert</ns:AuthCert>
       </ns:Credentials>
    </RequesterCredentials>
  </soapenv:Header>
  <soapenv:Body>
    <GeteBayOfficialTimeRequest xmlns="urn:ebay:apis:eBLBaseComponents">

<ns1:Version xmlns:ns1="urn:ebay:apis:eBLBaseComponents">405</ns1:Version>
    </GeteBayOfficialTimeRequest>
  </soapenv:Body>
</soapenv:Envelope>

This is quite a verbose message, especially considering that you are not even passing in any parameters. Although the API simply returns a timestamp that represents the current time, it is also quite verbose:

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <GeteBayOfficialTimeResponse xmlns="urn:ebay:apis:eBLBaseComponents">
      <Timestamp>2005-05-02T00:07:22.895Z</Timestamp>
      <Ack>Success</Ack>
      <CorrelationID>
        00000000-00000000-00000000-00000000-00000000-00000000-0000000000
      </CorrelationID>
      <Version>405</Version>
      <Build>20050422132524</Build>
    </GeteBayOfficialTimeResponse>
  </soapenv:Body>
</soapenv:Envelope>

While SOAP offers far more functionality than simple method calling, you can see why developers often mock the name "Simple" Object Access Protocol. Designers that simply needed to pass data between application layers or make basic method calls found that SOAP was overkill. This led to the development of a simpler messaging protocol called REST.

REST stands for REpresentational State Transfer. The designers of REST wanted to be able to call web service functions using the simple and well-known methods exposed by the HTTP protocol: GET and POST. The goal was to make it easy to invoke remote functions and provide response data in a more manageable format.

REST uses a simple URI scheme to communicate with web services. Developers who are comfortable using HTTP to make requests over the Web already know how to call REST services. Typically, a client application can simply issue an HTTP GET request to a URL to make a method call. The developer can pass parameters to the call using querystring parameters as if simply passing parameters to a regular web site.

Because REST is not standardized, it is possible that the client will receive response data from a REST-based service in an arbitrary format. However, XML is commonly used. Typically, REST-based web services can also return data using the JSON format instead of XML. This is preferable if you are developing Web-based applications.

In order to be able to easily determine the intent of a call, the HTTP GET method is used to query for data, and the HTTP POST method is used when you want to modify data such as in an INSERT or UPDATE to a database. This makes it easy to determine if the caller intends to simply query the service for data or make changes to the data managed by the service.

It is very easy to build simple web services using REST. If you already know how to implement server-side web scripts, REST implementations are typically straightforward. Both of the examples in this chapter will call web services based on the REST protocol. All of the concepts in this chapter are equally applicable if your application needs to call a SOAP-based service. The only real difference is the format of the message that you are sending and the format of the response message.

Now that you have an idea of what the application will do and how it will look, let's get started. The first step, as always, is to open Xcode and create a new project. Because there will be only one view, you should create a new View-based application. Call the new application LocationSearch.

You will be using the Core Location and MapKit frameworks in this example. These frameworks are not included in iPhone projects by default, so you will have to add references to the frameworks to the project. Right-click on the Frameworks folder in the Groups & Files pane in Xcode. From the pop-up menu, select Add

Figure 11.3. Completed LocationSearch application

You will be using these frameworks in your LocationSearchViewController class. Therefore, you will need to import the headers for these frameworks in the LocationSearchViewController.h header. Add the following import statements to the LocationSearchViewController.h header file:

#import <MapKit/MapKit.h>
#import <CoreLocation/CoreLocation.h>
                                                         

The user interface for the application consists of a search bar to accept the search criteria from the user and a map view that you will use to display the search results. Because you need access to both of these interface items in your code, you will need to add instance variables and outlets for these elements.

In the LocationSearchViewController.h header, add instance variables for an MKMapView* called mapView and a UISearchBar* called searchBar to the interface definition:

MKMapView* mapView;
    UISearchBar *searchBar;
                                                         

Now that you have declared your instance variables, declare IBOutlet properties for these UI elements so that you have access to them in Interface Builder:

@property (nonatomic, retain) IBOutlet MKMapView* mapView;
@property (nonatomic, retain) IBOutlet UISearchBar *searchBar;
                                                         

Next, you will move into the implementation file LocationSearchViewController.m. You first need to synthesize your two new properties. Add a line to synthesize the mapView and searchBar properties to the implementation:

@synthesize mapView,searchBar;

Finally, any time that you use a property that retains its value, you need to clean up the memory used by the property in the dealloc and viewDidUnload methods. Add the code to set the outlet properties to nil in the viewDidUnload method:

- (void)viewDidUnload {
    // Release any retained subviews of the main view.
    // e.g. self.myOutlet = nil;
    self.mapView = nil;
    self.searchBar = nil;
}
                                                         

Also, add the code to release the instance variables in the dealloc method:

- (void)dealloc {
    [mapView release];
    [searchBar release];
    [super dealloc];
}
                                                         

This application will have two elements in the interface, an MKMapView and a UISearchBar. Double-click on the LocationSearchViewController.xib file in the Resources folder of the Groups & Files pane in Xcode. This launches Interface Builder and opens the LocationSearchViewController.xib file.

In Interface Builder, make sure that you have the Library palette open. If you don't, you can open it from the menu bar by selecting Tools

Next, locate the map view under Library

Now that you have visually defined your user interface, you need to connect the user interface elements to the code. Hook up the UISearchBar to the searchBar outlet in File's Owner. Likewise, hook up the MKMapView to the mapView outlet in File's Owner.

That's all that you will need to do in Interface Builder so, you can close the LocationSearchViewController.xib file and quit Interface Builder.

Figure 11.4. LocationSearchViewController in Interface Builder

The key ingredient in building a location-based application is getting the location of the user. Apple has built the Core Location framework to enable your applications to interface with the GPS hardware in the device. Using this framework, you can obtain the current location or heading of the device.

@interface LocationSearchViewController
: UIViewController <CLLocationManagerDelegate>
                                                         

CLLocation* currentLocation;

@property (nonatomic, retain) CLLocation* currentLocation;

@synthesize mapView,searchBar, currentLocation;

- (void)viewDidUnload {
    // Release any retained subviews of the main view.
    // e.g. self.myOutlet = nil;
    self.mapView = nil;
    self.searchBar = nil;
    self.currentLocation=nil;
}


- (void)dealloc {
    [mapView release];
    [searchBar release];
    [currentLocation release];
    [super dealloc];
}
                                                         

- (void)viewDidLoad {
    [super viewDidLoad];

    // Create the Core Location CLLocationManager
    CLLocationManager *locationManager = [[CLLocationManager alloc] init];
    // Set the delegate to self
    [locationManager setDelegate:self];
    // Tell the location manager to start updating the location
    [locationManager startUpdatingLocation];

}
                                                         

// Called when the location manager determines that there is a new location
- (void)locationManager:(CLLocationManager *)manager
    didUpdateToLocation:(CLLocation *)newLocation
           fromLocation:(CLLocation *)oldLocation {
    self.currentLocation = newLocation;

}

// Called when an error occurs
- (void)locationManager:(CLLocationManager *)manager
       didFailWithError:(NSError *)error {
    NSLog (@"locationManager:didFailWithError");
}
                                                         

You will be using the Yahoo! local search service API to get your search results. This is a REST-based API. The URL for the web service is: http://local.yahooapis.com/LocalSearchService/V3/localSearch.

This service enables you to search for businesses near a given location. The results include the name of the business, latitude and longitude, and Yahoo! user ratings for the business.

The search API can accept many different parameters to help you narrow and filter your search. These include the radius from the base point to search for results, a route along which to search, or a specific category in which to search. To keep this sample simple, you will only pass in the latitude and longitude of the device as the location to search and the query search terms that you are looking for.

The XML that you get in response to a query request will look something like this:

<?xml version="1.0"?>
<ResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="urn:yahoo:lcl"
    xsi:schemaLocation="urn:yahoo:lcl
    http://local.yahooapis.com/LocalSearchService/V3/LocalSearchResponse.xsd"
    totalResultsAvailable="2501" totalResultsReturned="10"
    firstResultPosition="1">
    <ResultSetMapUrl>
        http://maps.yahoo.com/broadband/?tt=pizza&amp;tp=1
    </ResultSetMapUrl>
    <Result id="21566059">
        <Title>Ciceros Pizza</Title>
        <Address>20010 Stevens Creek Blvd</Address>
        <City>Cupertino</City>
        <State>CA</State>
        <Phone>(408) 253-2226</Phone>
        <Latitude>37.322724</Latitude>
        <Longitude>-122.023665</Longitude>
        <Rating>
            <AverageRating>4.5</AverageRating>
            <TotalRatings>9</TotalRatings>
            <TotalReviews>5</TotalReviews>
            <LastReviewDate>1266107776</LastReviewDate>
            <LastReviewIntro>
                My favorite pizza in the world. I understand that everybody has
                personal preferences when it comes to pizza, but for me Cicero's
                is the best. I've had pizza in Italy, many places in Europe,
                New York and everywhere else I've traveled to. For me, the best
                pizza in the world is in Cupertino, Ca..
            </LastReviewIntro>
        </Rating>
        <Distance>0.73</Distance>
        <Url>http://local.yahoo.com/info-21566059-ciceros-pizza-cupertino</Url>
        <ClickUrl>
            http://local.yahoo.com/info-21566059-ciceros-pizza-cupertino
        </ClickUrl>
        <MapUrl>
            http://maps.yahoo.com/maps_result?q1=20010+Stevens+Creek+Blvd
            +Cupertino+CA&amp;gid1=21566059
        </MapUrl>
        <Categories>
            <Category id="96926234">Carry Out &amp; Take Out</Category>
            <Category id="96926236">Restaurants</Category>
            <Category id="96926243">Pizza</Category>
        </Categories>
    </Result>
</ResultSet>

In this instance, you sent a query for "pizza" with the latitude and longitude of Apple headquarters in Cupertino, CA. This XML represents the first result returned from the web service. You can see that the response includes relevant information such as the name and address of the business, the phone number, the latitude and longitude, and the distance from the origin of the query. The response also contains review information submitted to Yahoo! by users of their web search services. Finally, you can see that there are several URLs if you wanted to use this information to allow a user to click on a link in your application to bring up a map or to directly link to the site of the establishment.

If you look at the ResultSet element at the top of the XML, you will notice that it has a few attributes of interest: totalResultsAvailable, totalResultsReturned, and firstResultPosition. Because there may be a very large number of results for a query, the service returns the result set in batches. You can specify the batch size, up to 20 results at a time. You can also specify the start position of the results that you want to retrieve. In this particular case, there were 2,501 results, of which you received the first 10. Your application will only handle the first batch of results. However, in a production application, you will probably want to write some code to resend the query more than once, in order to retrieve more results. It is up to you to keep track of the result position and to send back the next starting position to the service. Keep in mind that web services are stateless. They typically do not maintain any state on the server regarding your last request. It is up to you to implement whatever paging functionality meets the requirements of your application.

You can find complete documentation of the API at http://developer.yahoo.com/search/local/V3/localSearch.html.

This example added a UISearchBar control to your application. You will use this widget to get the search criteria from the user. Unlike the other user interface elements that you have used thus far, the search bar works using the delegation pattern. Therefore, you need to declare your class as the delegate for the search bar and implement the UISearchBarDelegate protocol. Then, when the search bar text changes or the user presses buttons, the search bar will call your code through the delegate methods.

In your LocationSearchViewController.h header file, you need to declare that you will implement the UISearchBarDelegate protocol. Change the interface declaration to include this protocol:

@interface LocationSearchViewController
: UIViewController <CLLocationManagerDelegate,UISearchBarDelegate>
                                                         

Now, you need to tell the searchBar property that you want the LocationSearchViewController to be its delegate. Add the following code to the viewDidLoad method:

// Set the delegate for the searchbar
    [self.searchBar setDelegate:self];
                                                         

Next, you will write some code to handle the delegate events you are interested in. When a user taps the search button, you will take the text of the search bar and pass it to the location search web service. After submitting the request, you will receive callbacks from the NSURLConnection using its delegate methods. In order to hold on to the response data that you receive from the connection, you will set up an instance variable and property called responseData. Add an instance variable called responseData of type NSMutableData* to your LocationSearchViewController.h header file:

NSMutableData *responseData;

Now, add a corresponding property:

@property (nonatomic, retain) NSMutableData *responseData;

Synthesize the new property in the implementation file:

@synthesize mapView,searchBar, currentLocation,responseData;

You are now ready to implement your searchBar delegate methods. The search bar calls the first method, searchBarSearchButtonClicked:, when the user clicks the Search button. In this method, you will create a request using the text in the search bar and send it off to the web service for processing. Here is the code:

- (void)searchBarSearchButtonClicked:(UISearchBar *)localSearchBar {
    NSLog (@"searchBarSearchButtonClicked");

    // Construct the URL to call
    // Note that you have to add percent escapes to the string to pass it
    // via a URL
    NSString *urlString = [NSString
        stringWithFormat:
            @"http://local.yahooapis.com/LocalSearchService/V3/localSearch?"
              "appid=YOUR_ID_GOES_HERE&query=%@&latitude=%f&longitude=%f",
        [localSearchBar.text
         stringByAddingPercentEscapesUsingEncoding:NSASCIIStringEncoding],
        self.currentLocation.coordinate.latitude,
                           self.currentLocation.coordinate.longitude];

    // Log the string that we plan to send
    NSLog (@"sending: %@",urlString);

    NSURL *serviceURL = [NSURL
                         URLWithString:urlString];

    // Create the Request.
    NSURLRequest *request = [NSURLRequest
                             requestWithURL:serviceURL
                             cachePolicy:NSURLRequestUseProtocolCachePolicy
                             timeoutInterval: 30.0];

    // Create the connection and send the request
    NSURLConnection *connection =

[[NSURLConnection alloc] initWithRequest:request delegate:self];

    // Make sure that the connection is good
    if (connection) {
        // Instantiate the responseData data structure to store to response
        self.responseData = [NSMutableData data];

    }
    else {
        NSLog (@"The connection failed");
    }

    [localSearchBar resignFirstResponder];
}
                                                         

You are using the same technique to send a request and receive a response from a web server, as I introduced in the previous chapter. I will point out a few minor differences.

First, you create a string that represents the URL that you will be calling. You are using the stringWithFormat method because you will be plugging the search query text, latitude, and longitude in dynamically at runtime. Notice that you are using the standard HTTP method for passing parameters on the querystring. That is, you give the name of the URL (http://local.yahooapis.com/LocalSearchService/V3/localSearch) and append a question mark (?) to indicate that parameters follow. Parameters are then passed as name-value pairs using the format parameterName=value. You separate your parameter pairs using the ampersand (&) character.

You can see from your URL string that you are passing four parameters: appid, query, latitude, and longitude. The latitude and longitude are the coordinates around which you want to center your search. The query is the item for which you want to search. The appid is a token that you receive from Yahoo! when you sign up to be able to use their web service. You can obtain a token to use the Local Search Service by going to https://developer.apps.yahoo.com/wsregapp/. Make sure that you replace the text, YOUR_ID_GOES_HERE in the definition of the urlString variable in the preceding code with the appid that you receive from Yahoo!, or you will not be able to access the web service.

Another important thing to notice when examining your URL string is that you call the method stringByAddingPercentEscapesUsingEncoding on the text string that you obtain from the search bar. The HTTP protocol uses characters such as & and % in very specific ways. If your text contains those (and several other) characters, they need to be "URL encoded." Calling this method on your string ensures that you are properly formatting the string to be able to pass it as a querystring parameter.

The last part of constructing your string is to get the latitude and longitude from your currentLocation object and replace them in the URL.

The next line simply logs the string to the console so that you can verify that you are creating the request URL string properly.

Next, you go on to create the objects that you need to submit your query to the web service. You create an NSURL using the URL string that you built earlier. Then, you create an NSURLRequest with the NSURL and specify the cache policy and timeout that you want. Finally, you create your NSURLConnection with the request, setting the delegate of the connection object to self.

Once you validate that the connection object is good, you instantiate the responseData property. Finally, you send the resignFirstResponder message to the search bar. This tells the search bar to dismiss the associated keyboard.

The next bit of code you will write will implement the searchBar:textDidChange: delegate method. The search bar calls this method any time the text in the search bar changes. Later on, you will implement this function to remove the annotations from the MapView if the search is changing. For now, you will simply log a message indicating that someone called the method:

// Called when the searchbar text changes
- (void)searchBar:(UISearchBar *)searchBar textDidChange:(NSString *)searchText{
    NSLog (@"textDidChange");

}
                                                         

In this section, you will take a look at the code that you need to write to handle the response from the web service. First, you will implement the NSURLConnection delegate methods to deal with the raw data that you receive from the web service. Then, you will define a new Result class that will hold data about each result returned from the service. Next, you will parse the XML and generate an array of Result objects. Finally, you will use the MapKit API to plot the results on a map.

- (void)connection:(NSURLConnection *)connection
didReceiveResponse:(NSURLResponse *)response {

NSLog (@"connection:didReceiveResponse:");

    [self.responseData setLength:0];

}
                                                         

- (void)connection:(NSURLConnection *)connection didReceiveData:(NSData *)data
{
    NSLog (@"connection:didReceiveData:");

    // Append the received data to our responseData property
    [self.responseData appendData:data];

}
                                                         

- (void)connectionDidFinishLoading:(NSURLConnection *)connection
{
    NSLog (@"connectionDidFinishLoading:");

    // Convert the data to a string and log the response string
    NSString *responseString = [[NSString alloc]
                                initWithData:self.responseData
                                encoding:NSUTF8StringEncoding];
    NSLog(@"Response String: 
%@", responseString);

    [responseString release];

    [connection release];

    [self parseXML];
}
                                                         

- (void)connection:(NSURLConnection *)connection
  didFailWithError:(NSError *)error
{
    NSLog (@"connection:didFailWithError:");
    NSLog (@"%@",[error localizedDescription]);

    [connection release];

}
                                                         

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

@interface Result : NSObject <MKAnnotation>{
    NSString *title;
    NSString *address;
    NSString *city;
    NSString *state;
    NSString *phone;
    double latitude;
    double longitude;
    float rating;
}

@property (nonatomic, retain) NSString *title;
@property (nonatomic, retain) NSString *address;
@property (nonatomic, retain) NSString *city;
@property (nonatomic, retain) NSString *state;
@property (nonatomic, retain) NSString *phone;
@property (nonatomic) double latitude;

@property (nonatomic) double longitude;
@property (nonatomic) float rating;

@end
                                                         

#import "Result.h"

@implementation Result
@synthesize title,address,city,state,phone,latitude,longitude,rating;

- (void)dealloc {
    [title release];
    [address release];
    [city release];
    [state release];
    [phone release];
    [super dealloc];
}

-(CLLocationCoordinate2D) coordinate
{
    CLLocationCoordinate2D retVal;
    retVal.latitude = self.latitude;
    retVal.longitude = self.longitude;

    return retVal;
}

- (NSString *)subtitle {
    NSString *retVal = [[NSString alloc] initWithFormat:@"%@",phone];

    [retVal autorelease];

    return retVal;

}

@end
                                                         

#import "Result.h"

- (void) parseXML;

Result *aResult;
    NSMutableArray *results;
    NSMutableString *capturedCharacters;

@property (nonatomic, retain) NSMutableArray *results;

@synthesize mapView,searchBar, currentLocation,responseData,results ;

- (void)viewDidUnload {
    // Release any retained subviews of the main view.
    // e.g. self.myOutlet = nil;
    self.mapView = nil;

self.searchBar = nil;
    self.results = nil;
    self.currentLocation=nil;
}


- (void)dealloc {
    [mapView release];
    [searchBar release];
    [currentLocation release];
    [results release];
    [super dealloc];
}
                                                         

- (void) parseXML {
    NSLog (@"parseXML");

    // Initialize the parser with our NSData from the RSS feed
    NSXMLParser *xmlParser = [[NSXMLParser alloc]
                              initWithData:self.responseData];

    // Set the delegate to self
    [xmlParser setDelegate:self];

    // Start the parser
    if (![xmlParser parse])
    {
        NSLog (@"An error occurred in the parsing");
    }

    // Clean up the parser
    [xmlParser release];


}
                                                         

- (void) parser:(NSXMLParser *)parser
didStartElement:(NSString *)elementName
   namespaceURI:(NSString *)namespaceURI
  qualifiedName:(NSString *)qualifiedName
     attributes:(NSDictionary *)attributeDict {
    NSLog (@"didStartElement");

    // Check to see which element we have found
    if ([elementName isEqualToString:@"Result"]) {
        // Create a new Result object
        aResult = [[Result alloc] init];


    }
    else if ([elementName isEqualToString:@"Title"]||
             [elementName isEqualToString:@"Address"]||
             [elementName isEqualToString:@"City"]||
             [elementName isEqualToString:@"State"]||
             [elementName isEqualToString:@"Phone"]||
             [elementName isEqualToString:@"Latitude"]||
             [elementName isEqualToString:@"Longitude"]||
             [elementName isEqualToString:@"AverageRating"])

    {
        // Initialize the capturedCharacters instance variable
        capturedCharacters = [[NSMutableString alloc] initWithCapacity:100];
    }
}
                                                         

- (void)parser:(NSXMLParser *)parser foundCharacters:(NSString *)string {
    if (capturedCharacters != nil) {
        [capturedCharacters appendString:string];
    }
}
                                                         

- (void)parser:(NSXMLParser *)parser didEndElement:(NSString *)elementName
  namespaceURI:(NSString *)namespaceURI qualifiedName:(NSString *)qName {

    NSLog (@"didEndElement");

    // Check to see which element we have ended
    if ([elementName isEqualToString:@"Result"]) {

        // Add the result to the array
        [results addObject:aResult];

        // release the Result object
        [aResult release];
        aResult=nil;
    }
    else if ([elementName isEqualToString:@"Title"] && aResult!=nil) {
        // Set the appropriate property
        aResult.title = capturedCharacters;

    }
    else if ([elementName isEqualToString:@"Address"] && aResult!=nil) {
        // Set the appropriate property
        aResult.address = capturedCharacters;

    }
    else if ([elementName isEqualToString:@"City"] && aResult!=nil) {
        // Set the appropriate property
        aResult.city = capturedCharacters;

    }
    else if ([elementName isEqualToString:@"State"] && aResult!=nil) {
        // Set the appropriate property
        aResult.state = capturedCharacters;

    }
    else if ([elementName isEqualToString:@"Phone"] && aResult!=nil) {
        // Set the appropriate property
        aResult.phone = capturedCharacters;

    }
    else if ([elementName isEqualToString:@"Latitude"] && aResult!=nil) {
        // Set the appropriate property
        aResult.latitude = [capturedCharacters doubleValue];

    }
    else if ([elementName isEqualToString:@"Longitude"] && aResult!=nil) {
        // Set the appropriate property

aResult.longitude = [capturedCharacters doubleValue];

    }
    else if ([elementName isEqualToString:@"AverageRating"] && aResult!=nil) {
        // Set the appropriate property
        aResult.rating = [capturedCharacters floatValue];
    }


    // So we don't have to release capturedCharacters in every else if block
    if ([elementName isEqualToString:@"Title"]||
        [elementName isEqualToString:@"Address"]||
        [elementName isEqualToString:@"City"]||
        [elementName isEqualToString:@"State"]||
        [elementName isEqualToString:@"Phone"]||
        [elementName isEqualToString:@"Latitude"]||
        [elementName isEqualToString:@"Longitude"]||
        [elementName isEqualToString:@"AverageRating"])
    {
        // Release the capturedCharacters instance variable
        [capturedCharacters release];
        capturedCharacters = nil;
    }

}
                                                         

- (void)parserDidEndDocument:(NSXMLParser *)parser {
    NSLog (@"parserDidEndDocument");


    // Plot the results on the map
    [self plotResults];
}
                                                         

@interface LocationSearchViewController
: UIViewController <CLLocationManagerDelegate,UISearchBarDelegate,
    MKMapViewDelegate>
                                                         

- (void) plotResults;

#import <UIKit/UIKit.h>
#import <MapKit/MapKit.h>
#import <CoreLocation/CoreLocation.h>
#import "Result.h"

@interface LocationSearchViewController
: UIViewController <CLLocationManagerDelegate,UISearchBarDelegate,
    MKMapViewDelegate> {

    MKMapView* mapView;
    UISearchBar *searchBar;
    CLLocation* currentLocation;
    NSMutableData *responseData;
    NSMutableString *capturedCharacters;
    Result *aResult;
    NSMutableArray *results;
}

@property (nonatomic, retain) IBOutlet MKMapView* mapView;
@property (nonatomic, retain) IBOutlet UISearchBar *searchBar;
@property (nonatomic, retain) CLLocation* currentLocation;

@property (nonatomic, retain) NSMutableData *responseData;
@property (nonatomic, retain) NSMutableArray *results;


- (void) parseXML;
- (void) plotResults;


@end
                                                         

- (void)locationManager:(CLLocationManager *)manager
    didUpdateToLocation:(CLLocation *)newLocation
           fromLocation:(CLLocation *)oldLocation {
    self.currentLocation = newLocation;

    // Create a mapkit region based on the location
    // Span defines the area covered by the map in degrees
    MKCoordinateSpan span;
    span.latitudeDelta = 0.05;
    span.longitudeDelta = 0.05;

    // Region struct defines the map to show based on center coordinate and span
    MKCoordinateRegion region;
    region.center = newLocation.coordinate;
    region.span = span;

    // Update the map to display the current location
    [mapView setRegion:region animated:YES];

    // Stop core location services to conserve battery
    [manager stopUpdatingLocation];

}
                                                         

- (void)viewDidLoad {
    [super viewDidLoad];


    // Create the results array
    self.results = [[NSMutableArray alloc] init];


    // Create the Core Location CLLocationManager
    CLLocationManager *locationManager = [[CLLocationManager alloc] init];
    // Set the delegate to self
    [locationManager setDelegate:self];
    // Tell the location manager to start updating the location
    [locationManager startUpdatingLocation];

    // Set the delegate for the searchbar
    [self.searchBar setDelegate:self];

    // Set the delegate for the mapView
    [self.mapView setDelegate:self];

    // Use Core Location to find the user's location and display it on the map
    // Be careful when using this because it causes the mapview to continue to
    // use Core Location to keep the user's position on the map up to date
    self.mapView.showsUserLocation = YES;

}
                                                         

// Called when the searchbar text changes
- (void)searchBar:(UISearchBar *)searchBar textDidChange:(NSString *)searchText{
    NSLog (@"textDidChange");

    // If the text was cleared, clear the map annotations
    if ([searchText isEqualToString:@""])
    {
        // Clear the annotations
        [self.mapView removeAnnotations:self.mapView.annotations];

        // Clear the results array
        [self.results removeAllObjects];
    }

}
                                                         

- (MKAnnotationView *)mapView:(MKMapView *)mapView
            viewForAnnotation:(id <MKAnnotation>)annotation
{

    // If we are displaying the user's location, return nil
    //  to use the default view
    if ([annotation isKindOfClass:[MKUserLocation class]]) {
           return nil;
    }

    // Try to dequeue an existing pin
    MKPinAnnotationView *pinAnnotationView =
        (MKPinAnnotationView *)
        [self.mapView dequeueReusableAnnotationViewWithIdentifier:@"location"];

    if (!pinAnnotationView) {
        // We could not get a pin from the queue
        pinAnnotationView=[[[MKPinAnnotationView alloc]
                            initWithAnnotation:annotation

reuseIdentifier:@"location"] autorelease];

        pinAnnotationView.animatesDrop=TRUE;
        pinAnnotationView.canShowCallout = YES;

    }

    // We need to get the rating from the annotation object
    //  to color the pin based on rating
    Result *resultAnnotation = (Result*) annotation;

    if (resultAnnotation.rating > 4.5) {
        pinAnnotationView.pinColor = MKPinAnnotationColorGreen;
    }
    else if (resultAnnotation.rating > 3.5) {
        pinAnnotationView.pinColor = MKPinAnnotationColorPurple;
    }
    else {
        pinAnnotationView.pinColor = MKPinAnnotationColorRed;
    }


    return pinAnnotationView;

}
                                                         

To get started, open Xcode and create a new View-based application called TermExtract. In the TermExtractViewController.h header file, add instance variables for two UITextView variables:

UITextView *textToExtractTextView;
UITextView *extractedTermsTextView;

Next, add properties for these UITextViews:

@property (nonatomic, retain) IBOutlet UITextView *textToExtractTextView;
@property (nonatomic, retain) IBOutlet UITextView *extractedTermsTextView;

Also, add instance variables for the response data that you will receive from the server in response to your request, and the characters that you will capture during XML parsing:

NSMutableData *responseData;
NSMutableString *capturedCharacters;

Now, add a property for the responseData:

@property (nonatomic, retain) NSMutableData *responseData;

Next, add an IBAction method called extractTerms that you will call after the user enters the text to send to the service. Finally, add an instance method called parseXML that you will invoke to start the XML processing:

- (IBAction) extractTerms:(id)sender;
- (void) parseXML;

The complete header should look like this:

#import <UIKit/UIKit.h>

@interface TermExtractViewController : UIViewController {
    UITextView *textToExtractTextView;
    UITextView *extractedTermsTextView;
    NSMutableData *responseData;
    NSMutableString *capturedCharacters;

}

@property (nonatomic, retain) IBOutlet UITextView *textToExtractTextView;
@property (nonatomic, retain) IBOutlet UITextView *extractedTermsTextView;
@property (nonatomic, retain) NSMutableData *responseData;

- (IBAction) extractTerms:(id)sender;
- (void) parseXML;

@end
                                                         

In the implementation file, synthesize the textToExtractTextView,extractedTermsTextView,responseData properties:

@synthesize textToExtractTextView,extractedTermsTextView,responseData;

Then, add the code to clean up the properties in the viewDidUnload method:

- (void)viewDidUnload {
    // Release any retained subviews of the main view.
    // e.g. self.myOutlet = nil;
    self.textToExtractTextView=nil;
    self.extractedTermsTextView=nil;
    self.responseData=nil;
}
                                                         

Finally, release your instance variables and call the superclass's dealloc method in dealloc:

- (void)dealloc {
    [textToExtractTextView release];
    [extractedTermsTextView release];
    [responseData release];

    [super dealloc];
}
                                                         

You will now build the user interface for the application using Interface Builder. Double-click on the TermExtractViewController.xib file in Xcode to open the file in Interface Builder. Once the interface view is open, add two UITextViews, two UILabels, and a UIButton, as shown in Figure 11-6.

Figure 11.6. Term extract user interface

Change the title attribute of the UIButton to read "Extract Terms." Change the text of the top UILabel to read "Text to extract:" and the bottom UILabel to "Extracted Terms:".

As default text in the "Text to extract:" TextView, I set the text to the Declaration of Independence. I have included a text file containing the declaration, or you could use your own text or just provide text at runtime. Delete the default text from the extracted terms TextView.

Next, you need to hook up the TextViews to the proper outlets in Interface Builder. Hook up the Extract Terms button to the IBAction extractTerms in File's Owner. In the TermExtractViewController.m implementation file, implement a stub extractTerms method to log when someone calls the method. You will use this to verify that you have correctly wired up the button in Interface Builder. Here is the stub code:

- (IBAction) extractTerms:(id)sender
{
    NSLog (@"extractTerms");
}

Build and run the application. Click the extractTerms button and verify that you see the log message in the console. This shows that you have correctly wired the button to the method. If you do not see the message in the console, make sure that you have properly wired the button to the message in Interface Builder.

You are finished with the user interface, so you can close Interface Builder.

You will implement the extractTerms method to POST the request to the web service.

The first thing that you do in this method is to dismiss the keyboard by calling the resignFirstResponder method on the TextView. Next, you clear the list of extracted terms to eliminate old results:

- (IBAction) extractTerms:(id)sender
{
    NSLog (@"extractTerms");

    // Hide the keyboard
    [self.textToExtractTextView resignFirstResponder];

    // Clear the old extracted terms
    self.extractedTermsTextView.text = @"";
                                                         

Now, you create a string to hold the URL that you plan to call. This is the address of the Yahoo! Term Extraction web service. Next, you create an NSURL object with this string:

// Create a string for the URL
    NSString *urlString =
        @"http://search.yahooapis.com/ContentAnalysisService/V1/termExtraction";

    // Create the NSURL
    NSURL *url = [NSURL URLWithString:urlString];
                                                         

The next line is where using the POST method differs from using GET. If you recall, when using the GET method, you simply set the URL string, set the parameter values inline, and sent the request off through the NSURLConnection. When using the POST method, you need to do things a little differently. After you create the NSURLRequest, you will need to modify some of its properties. Therefore, you must use an NSMutableURLRequest instead:

// Create a mutable request because we will append data to it.
    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url
        cachePolicy:NSURLRequestUseProtocolCachePolicy
        timeoutInterval: 30.0];
                                                         

The first change that you will make to the request is to set the HTTP method that you plan to use. Remember that you are using the POST method. The default method is GET, so you have to change this in the request to POST using the setHTTPMethod method:

// Set the HTTP method of the request to POST
    [request setHTTPMethod:@"POST"];
                                                         

Next, you will build a string to hold your parameters. In this example, there is only one parameter, but many parameters can optionally be passed using the POST method. You should note that parameters must be passed using the HTML parameter passing syntax name=value just like when using the GET method. In your implementation, make sure that you replace the appid with the actual appid that you receive from Yahoo! after you register your application. Here is your parameter string:

// Build a string for the parameters
    NSString *parameters = [[NSString alloc] initWithFormat:
        @"appid=YOUR_ID_GOES_HERE&context=%@",
        self.textToExtractTextView.text];
                                                         

When you use the GET method to call a web service, you pass the parameters in the query string of the HTTP request. However, when you use POST, you pass those parameters in the body of the HTTP message. Therefore, you have to set the HTTP body using the setHTTPBody method:

// Set the body of the request
    [request setHTTPBody:[parameters dataUsingEncoding:NSUTF8StringEncoding]];
                                                         

The rest of the code for the method is the same as you have seen before. First, you create the NSURLConnection:

NSURLConnection *connection =
    [[NSURLConnection alloc] initWithRequest:request delegate:self];
                                                         

Next, you instantiate your responseData property:

// Make sure that the connection is good
    if (connection) {
        // Instantiate the responseData data structure to store to response
        self.responseData = [NSMutableData data];

    }

else {
        NSLog (@"The connection failed");
    }
                                                         

Finally, you need to clean up your local variables:

// Clean up our local variables
    [urlString release];
    [parameters release];
                                                         

Here is the complete method implementation:

- (IBAction) extractTerms:(id)sender
{
    NSLog (@"extractTerms");

    // Hide the keyboard
    [self.textToExtractTextView resignFirstResponder];

    // Clear the old extracted terms
    self.extractedTermsTextView.text = @"";

    // Create a string for the URL
    NSString *urlString =
        @"http://search.yahooapis.com/ContentAnalysisService/V1/termExtraction";

    // Create the NSURL
    NSURL *url = [NSURL URLWithString:urlString];


    // Create a mutable request because we will append data to it.
    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url
        cachePolicy:NSURLRequestUseProtocolCachePolicy
        timeoutInterval: 30.0];


    // Set the HTTP method of the request to POST
    [request setHTTPMethod:@"POST"];

    // Build a string for the parameters
    NSString *parameters = [[NSString alloc] initWithFormat:
        @"appid=YOUR_ID_GOES_HERE&context=%@",
        self.textToExtractTextView.text];

    // Set the body of the request
    [request setHTTPBody:[parameters dataUsingEncoding:NSUTF8StringEncoding]];

    // Create the connection and send the request

NSURLConnection *connection =
    [[NSURLConnection alloc] initWithRequest:request delegate:self];

    // Make sure that the connection is good
    if (connection) {
        // Instantiate the responseData data structure to store to response
        self.responseData = [NSMutableData data];

    }
    else {
        NSLog (@"The connection failed");
    }

    // Clean up our local variables
    [urlString release];
    [parameters release];
}
                                                         

In order to receive the response from the web service, you need to implement the NSURLConnection delegate methods as you did in the previous example.

First, you will implement the connection:didReceiveResponse: method. This delegate method is called when the NSURLConnection creates the response. The connection could call this method multiple times, so you need to reset your response data by setting its length to zero each time this method runs. Here is the implementation:

// Called when the connection has enough data to create an NSURLResponse
- (void)connection:(NSURLConnection *)connection
didReceiveResponse:(NSURLResponse *)response {
    NSLog (@"connection:didReceiveResponse:");
    NSLog(@"expectedContentLength: %qi", [response expectedContentLength] );
    NSLog(@"textEncodingName: %@", [response textEncodingName]);

    [self.responseData setLength:0];

}
                                                         

Next, you need to implement the connection:didReceiveData: delegate method. The connection calls this method each time it receives data so you need to append the received data to your responseData buffer:

// Called each time the connection receives a chunk of data
- (void)connection:(NSURLConnection *)connection didReceiveData:(NSData *)data
{

NSLog (@"connection:didReceiveData:");

    // Append the received data to our responseData property
    [self.responseData appendData:data];

}
                                                         

Now you need to implement connectionDidFinishLoading. The delegate calls this method when the connection has completed loading the requested data. In this method, you convert the response data to a string, clean up the connection, and call the method to parse the XML:

// Called when the connection has successfully received the complete response
- (void)connectionDidFinishLoading:(NSURLConnection *)connection
{
    NSLog (@"connectionDidFinishLoading:");

    // Convert the data to a string and log the response string
    NSString *responseString = [[NSString alloc]
                                initWithData:self.responseData
                                encoding:NSUTF8StringEncoding];
    NSLog(@"Response String: 
%@", responseString);

    [responseString release];
    [connection release];

    [self parseXML];
}
                                                         

Finally, you should implement the connection:didFailWithError: method. Here you will log that an error occurred. In a production application, you would want to provide more robust error handling. Here is the implementation:

// Called when an error occurs in loading the response
- (void)connection:(NSURLConnection *)connection
  didFailWithError:(NSError *)error
{
    NSLog (@"connection:didFailWithError:");
    NSLog (@"%@",[error localizedDescription]);

    [connection release];

}
                                                         

After you submit your request, you will receive an XML response from the web service. The response will contain the most relevant words and phrases from the text that you sent into the service, in order of relevance. The response that I received when I sent the declaration to the web service looked like this:

<?xml version="1.0"?>
<ResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns="urn:yahoo:cate" xsi:schemaLocation="urn:yahoo:cate
 http://search.yahooapis.com/ContentAnalysisService/V1/
 TermExtractionResponse.xsd">
    <Result>life liberty and the pursuit of happiness</Result>
    <Result>powers of the earth</Result>
    <Result>liberty and the pursuit of happiness</Result>
    <Result>pursuit of happiness</Result>
    <Result>certain unalienable rights</Result>
    <Result>absolute despotism</Result>
    <Result>political bands</Result>
    <Result>transient causes</Result>
    <Result>decent respect</Result>
    <Result>long train</Result>
    <Result>direct object</Result>
    <Result>usurpations</Result>
    <Result>sufferance</Result>
    <Result>laws of nature</Result>
    <Result>one people</Result>
    <Result>form of government</Result>
    <Result>when in the course of human events</Result>
    <Result>evils</Result>
    <Result>prudence</Result>
    <Result>mankind</Result>
</ResultSet>

You need to implement the parseXML function, just as you did in the previous example, to parse this response XML:

- (void) parseXML {
    NSLog (@"parseXML");

    // Initialize the parser with our NSData from the RSS feed
    NSXMLParser *xmlParser = [[NSXMLParser alloc]
                              initWithData:self.responseData];

    // Set the delegate to self
    [xmlParser setDelegate:self];

    // Start the parser
    if (![xmlParser parse])
    {
        NSLog (@"An error occurred in the parsing");
    }

// Release the parser because we are done with it
    [xmlParser release];
}
                                                         

In this method, you first declare an instance of an NSXMLParser and initialize it with the response data that you received from the web service. Next, you set the parser's delegate to self. Then, you tell the parser to start parsing the XML. Finally, you release the parser.

Finally, you will implement your NSXMLParser delegate methods:

// Called when the parser encounters a start element
- (void) parser:(NSXMLParser *)parser
didStartElement:(NSString *)elementName
   namespaceURI:(NSString *)namespaceURI
  qualifiedName:(NSString *)qualifiedName
     attributes:(NSDictionary *)attributeDict {

    // Check to see which element we have found
    if ([elementName isEqualToString:@"Result"]) {
        // Initialize the capturedCharacters instance variable
        capturedCharacters = [[NSMutableString alloc] initWithCapacity:100];
    }
}

// Called when the parser encounters an end element

- (void)parser:(NSXMLParser *)parser didEndElement:(NSString *)elementName
  namespaceURI:(NSString *)namespaceURI qualifiedName:(NSString *)qName {

    NSLog (@"didEndElement");

    // Check to see which element we have ended

    // We ended a Result element
    if ([elementName isEqualToString:@"Result"]) {
        NSLog (@"capturedCharacters: %@", capturedCharacters);

        self.extractedTermsTextView.text = [self.extractedTermsTextView.text
            stringByAppendingFormat:@"%@
",capturedCharacters];

        // Release the capturedCharacters instance variable
        [capturedCharacters release];
        capturedCharacters = nil;
    }



}

// Called when the parser finds characters contained within an element
- (void)parser:(NSXMLParser *)parser foundCharacters:(NSString *)string {
    if (capturedCharacters != nil) {
        [capturedCharacters appendString:string];
    }
}
                                                         

Because you are only interested in Result elements, this code is straightforward. If you encounter the start of a Result element, you initialize your capturedCharacters instance variable in the didStartElement method. In didEndElement, you check to see that you ended a Result element. Then, you append the capturedCharacters string to the extractedTermsTextView.

The application is now complete. You should be able to successfully build and run the program. When you tap the Extract Terms button, you will send the query to the web service. If you have an active Internet connection, and you have properly configured your own appid, you should receive an XML result set back that contains the extracted terms. You can verify this in the console log. The code will take the text contained in each Result element, parse it, and append it to the extractedTermsTextView in the user interface. Feel free to paste in any block of text that you find interesting to see what the Yahoo! service feels are the most significant words or phrases in the document.