Programming Assignment:  TerraClient  program  

CS 130, Dr. Beeson

 

In this assignment, you will build a client program as a C# Windows Application,  that “consumes”  (uses)  a web service.  The web service you will use is called TerraService.

 

Here is a history of this service (taken from an MSDN Web page called The XML Files):

 

  Back in 1998, a group of researchers at Microsoft set up a massive SQL database for storing aerial, satellite, and topographic images of the earth. Microsoft made this database available to the public over the Internet and called it TerraServer (see http://terraservice.net/).
  Users can easily access the images in TerraServer using any Web browser like Microsoft Internet Explorer or Netscape. ... With the advent of Web Services, the researchers realized that the new Web Services platform would provide the right framework for dealing with application integration scenarios. Hence, they implemented a Web Services interface to their imagery database and called it TerraService (see http://terraserver-usa.com/TerraService2.asmx?wsdl )

 

Program Specifications

 

The program must allow the user to specify a “place” (city, state, country),  the desired output (photo or topographical map), and the scale of the map ( a number between 0 and 24 ).   Below are two screen shots showing the desired results.   The button is labeled Get Tile because the data stored in the database is called “tiles”.  A tile is either a photo or a “topo” (topographical map).    Version 2 (which we’ll use) of TerraClient added a new kind of tile, “urban area”.  The reason for the word is the idea that the entire earth is “tiled” with these photos and maps.  (That is a bit over-optimistic as most of the data presently stored is for the US.)   Your form layout does not need to be identical to this one.   

 

 

 



 

When the program first opens, Photo and 12  should be selected in the list boxes.   The text boxes should be empty.  When the user enters a valid place name (in the US)  and selects photo or topo,  and pressed Get Tile,  if there is an open Internet connection the correct image appears.     If invalid data are entered,  or there is no Internet connection,  your program should display a sensible error message rather than crashing.   [You will find that for many places, many supposedly valid values of “tile” do not have any corresponding data!  So you don’t want to crash in that case.]  

 

You are free to design another interface, or to use this one.   You should, however, definitely use text boxes to specify the city, state, and country, and a list box for the scale, since the legal values of scale come from a fixed finite list of numbers.  [However, for many scale values there seems to be no data, so you are not required to list all the scale values that are theoretically legal according to the documentation. Use your discretion as you would if this were a professional assignment.]   It would be nice to explain briefly to the user what the scales mean—I didn’t do that on the sample, because it’s part of the assignment to discover that by reading the documentation of the web service.    As examples of other interfaces you could design, I offer these two:  you could, for example, replace the list box for “photo” and “topo” by using two buttons instead of one;  or, you could display both photo and topo and leave out the list box entirely.

 

Programming Hints

 

1.   Create your project.   Make the title bar display TerraClient2345 using your student ID instead of 2345,  as usual.  It should be a C# Windows application.  

 

2.   Follow the steps in the lecture notes where the Google example is explained.  You will need to know where on the Web to find the WSDL file for TerraService.   The URL is

 

http://terraserver-usa.com/TerraService2.asmx.   

 

Enter this URL as shown in the following screen shot:

 

 

Unlike the Google service, no key is necessary:  access to TerraServer is free, public, and anonymous.   (The data is all in the public domain, having been paid for by the taxpayers.) 

 

3.    Open the Form1.cs  file.   At the top of the file (after the other using commands) you will need to tell it about the namespace for the TerraService class.   That namespace begins with the name of your program;  then it continues with .com because this is a Web service;  after typing that much you should get some help from autocompletion,  showing the namespaces available.  The line of code you will add is this:

 

using TerraClient.com.terraserver_usa;

 

You are also going to use a class MemoryStream from the FCL.  To get that class recognized you will need the following:

 

using System.IO;

 

 

 

4.   Use the Form Designer to add the necessary components to your form.  That would be three text boxes (City, State, and Country), two list boxes (choice of photo, topo,  or urban area, and choice of scale),  some labels, a picture box to hold the output, and the Get Tile button. 

 

5.  The only one of these components that actually needs code is the Get Tile button.  Double-click the button in Form Designer to go to the place to put the code.   Start out like this:

 

TerraService ts = new TerraService();
// specify place
Place place = new Place();
place.City = CityBox.Text;
place.State = StateBox.Text;
place.Country =  CountryBox.Text;
 
// get place facts
PlaceFacts pfacts = ts.GetPlaceFacts(place);
 
You should be able to compile at this point, but of course nothing will actually work yet.   
 
6.  Read and study the documentation for the TerraService web service, at 
 
http://terraserver.homeadvisor.msn.com/about.aspx?n=AboutTerraServiceAPI
 
Note the links in the upper right that lead to Overview, API, Data Structures, and Parameters.   
 
You will eventually want to get the desired image and put it in the picture box as follows:
 
// get tile metadata for place, read theme and scale from form
TileMeta tm = ts.GetTileMetaFromLonLatPt(pfacts.Center, theme, scale);
 
// get tile image
Byte[] imageBytes = ts.GetTile(tm.Id);
MemoryStream ms = new MemoryStream(imageBytes);
pictureBox1.Image = new Bitmap(ms);

 

After adding this code, your program won’t compile because theme and scale are not defined.   They should come from your two list boxes.   What type and values should they have?   You need to discover that by reading the documentation of the web service and put in the appropriate values using the data from your list boxes.  Be careful:  the type of theme changed between versions of TerraClient.   Autocompletion can be very helpful—it is a useful way of presenting documentation.  You need to use the documentation of the FCL list box class to find out how to get that data.

 

Warning:  there is a namespace conflict between Scale in the web service, and Scale in .NET.  You will have to use a fully qualified name to solve this problem.

 

When you have correctly defined scale and theme, the program should work:  if you enter valid data you should get a good image.  Use the default scale of 12 to check this.

 

7.   Now put in code to initialize the list box selection.

8.   Put in exception handling code.  Follow the Google example in lecture.

 

Final Remark:  Observe that the total number of lines of code to write in this assignment is closer to 10 than to 50.   Most of your time will be spent extracting knowledge from documentation.   That is likely to be characteristic of web service programming.  The hard part of the programming has been done by others and is re-usable.   It’s your job to figure out how to reuse it.   

 

Grading criteria:

 

Program delivers photos and maps when valid data is entered:   B

In addition, invalid data results in an error message and not a crash:   A

If the form components are not properly initialized, there is a one-third letter grade penalty, for example from A to A-.

 

For an A+,  make the program find and display the latitude and longitude of the place entered, as well as the photo or map.