CS580: Assignment 1

	CS 580 Client-Server Spring Semester, 2004 Assignment 1
	Assignment Index © 2004, All Rights Reserved, SDSU & Roger Whitney San Diego State University -- This page last updated 19-Jan-04

Assignment 1 Due: Feb. 3

Purpose of Assignment

Introduce basic client-server concepts
Provide experience with high-level client-server protocol
Client GUI issues
Concurrency issues on client
Client-server separation of concerns
Difference between what server provides client and what client displays to the user

Description
The deliverable for this assignment is a GUI based client that provides information about San Diego restaurants. The client will use XML-RPC to communicate with a server. The server will be set up for you. The client allows the user to search for restaurants by name, city, type and area. The client displays information about restaurants. The client allows the user to add new restaurants into the server’s database. Also the user can add & modify information for an existing restaurant.

The server contains the following information about a restaurant.

id
The server provides a unique id for each restaurant. The id is used to identify a restaurant.

name
Each restaurant has a name. More than one restaurant can have the same name. Each restaurant in a chain has a separate entry on the server. Each entry uses the same name. Two unrelated restaurants may have the same name.

address
Each restaurant has a street address. For example: "123 Maple Street".

city
This is the city in which the restaurant is located.

phone
A phone number is 10 digits long. That is the phone number contains the area code. A client may wish to provide a default area code so users do not have to enter the area code for every restaurant. However the server requires all phone numbers to have 10 digits. The format of the 10 digits does not matter. For example the server accepts 6195943535, 619.594.3535 and (619) 594-3535 as phone numbers. A restaurant has only one phone number.

price
Each restaurant has a price scale. This indicates how expensive the restaurant is. Currently valid values for this scale are the integers 1, 2, 3, 4, and 5. 1 being the least expensive and 5 the most expensive. It is customary for clients to display this information as stars. So a rating of 3 would be indicated by displaying three stars like: ***. If a restaurant has not had its price ranked the server returns a value of 0 for the price.

ratings
Any number of users can rate the quality of a restaurant. Currently valid values for this scale are the integers 1, 2, 3, 4, and 5. 1 being the worst and 5 the best. It is customary for clients to display this information as stars. Then the server reports the rating of a restaurant it provides the average of all the ratings for that restaurant, which will be a XML-RPC double.

comments
Any number of users can provide a comment on a restaurant.

types
A restaurant can have zero or more types associated with it. Example of such types are: Afganistan, Cuban, Cajun and Chinese.

area
The area indicates the general location of a restaurant. Examples of areas are: North Coastal, North Inland, Gold Coast and La Jolla.

Server Methods
The server supports the following methods. The data types are given in terms of XML-RPC types. You need to convert the XML-RPC types into the equivalent data types for your language. For example an XML-RPC int maps to a Java Integer and a Smalltalk SmallInteger.

costRatings
Arguments: none

Returns: an array of int. These ints are the possible values for a restaurant price.

qualityRatings
Arguments: none

Returns: an array of int. These ints are the possible values for a restaurant rating.

areas
Arguments: none
Returns: an array of string. These strings are the possible values for a restaurant area.

types
Arguments: none

Returns: an array of string. These strings are the possible values for a restaurant type.

addType
Argument: string, this string is added to the list of types of a restaurant.

Returns: boolean, which indicates if the string was successfully added. true indicates the string was added.

addRestaurant
Argument: struct, keys and values are strings. Valid keys are given below.

Returns: true if the restaurant was added. If there was a problem adding the restaurant an XmlRpcException is thrown in Java. The exceptions message string (getMessage() ) contains information about the problem the server had. In Smalltalk an XmlRpcFault object is returned. The message description sent to the XmlRpcFault object contains information about the problem on the server.

Keys for addRestaurant struct input. The required keys are:

name, address, city, phone and area

The following is a list of all possible keys:

name, address, city, phone, price, rating, comment, type, types and area

The keys are case sensitive. The following discusses the valid values for each key:

name – a string for the name of the restaurant
address – a string for the street the restaurant is on
city – a string for the city the restaurant is located in
phone – a string
price – an integer
rating – an integer
comment – a string
type – a string
types – an array of string
area – a string

Note it is assumed that either the key type or types will be used but not both.

find
Argument: struct, keys and values are strings and used to find a restaurant. The possible keys are: name, city, area and type. The keys are case sensitive. If the argument does not contain a valid key an exception is returned. One or more of the keys can occur. The value connected to the key indicates what to search for. For example if we wanted to find all restaurants in La Mesa we would use a struct with the follow:

Key	Value
city	La Mesa

If we wish to find all Afganistan restaurants in La Mesa we would use a struct with the following two keys and values:

Key	Value
city	La Mesa
type	Afganistan

When multiple keys and values are given the restaurants that satisfy all the requirements are returned. The values can contain the wild card characters: # and *. The character # matches a single character. The character * matches any number of characters. So the following would find all restaurants in cities that start with ‘La” we would use:

Key	Value
city	La*

Returns: array of arrays. Each restaurant found is returned as an array. The first element of the array is a string, the name of the restaurant. The second element of the array is an int. This is the unique id of the restaurant. A search may match more that one restaurant so an array of such arrays is returned. If no restaurant is found an empty array is returned. If there is an error on the server while processing the request XmlRpcException is thrown in Java and an XmlRpcFault object is returned in Smalltalk.

restaurantById
Argument: int, the id of the restaurant to return

Returns: struct, which contains the information about a restaurant. The struct will have the following keys:

id, name, address, city, phone, price, rating, comments, types and area

The following discusses the values associated with each key.
id - an int
name – a string for the name of the restaurant
address – a string for the street the restaurant is on
city – a string for the city the restaurant is located in
phone – a string
price – an integer
rating – an double
comments – an array of strings. Each string is a different comment
types – an array of strings. Each string is a different type
area – a string

modifyRestaurant
Argument: struct, containing the new information for the restaurant.

Returns: true if successfully modified the data for a restaurant.

The primary use of the method is to add a comment about a restaurant or to add a rating. It can be used to modify other values. Restaurants do move and change chanes, but this is rare. The struct argument must contain the key ‘id’. The value for this key must the correct id of the restaurant to be modified. The struct may also contain any of the following keys:

name, address, city, phone, price, rating, comment, type, and area

All key-value pairs sent (other than id) will be used to modify the given restaurant.

size
Argument: none
Returns: int, the number of restaurants in the database.

deleteRestaurant
Argument: int, the id of the restaurant to delete from the database
Returns: Boolean indicating if the restaurant was deleted. False is returned if restaurant does not exist or the restaurant is locked by another transaction (by modifying the restaurant).

Accessing the Server The server url is:

http://rugby.sdsu.edu:8765/Restaurant

So the following show an example of accessing the server: Smalltalk

client := XmlRpcClient url: 'http://rugby.sdsu.edu:8765/Restaurant'.
client perform: 'types'

Java

import java.util.*;
import org.apache.xmlrpc.*;

public class XmlRpcExample {

    public static void main (String args[]) {
        try
            {
            XmlRpcClient xmlrpc =  new XmlRpcClientLite 
						("http://rugby.sdsu.edu:8765/Restaurant");
			Vector parameters = new Vector ();
                      Vector types = 
					(Vector) xmlrpc.execute ("types", parameters);
			for (int k = 0; k < types.size(); k++ )
				System.out.println( types.elementAt(k) );
            }
        catch (java.net.MalformedURLException badAddress)
            {
            badAddress.printStackTrace( System.out);
            }
        catch (java.io.IOException connectionProblem)
            {
            connectionProblem.printStackTrace( System.out);
            }
        catch (Exception serverProblem)
            {
            serverProblem.printStackTrace( System.out);
            }
        }
    }

visitors since 15-Jan-04