Welcome to lab #5. Let's build a webapp! Call it pb (phonebook).

The user starts by visiting the URL

https://www.cse.yorku.ca/~cseXXXXX/pb/pb.cgi

where cseXXXXX is your Red login. At that point, the browser prompts for username and password. Any valid Red user should be able to login. After a successful authentication, the user is presented with the a search page having the following components.

1. A message that says “Welcome X”, where X is the user's username. If the user has visited the webapp before, then the message should say, “Welcome back X. Your last visit was xxx.” The xxx should be the time of the person's last visit.

2. A label, a textbox, and a button entitled “Find”. The user can enter a person's last name — or a part thereof — and click “Find” in order to initiate a database search for the telephone number of that person. The search should be case insensitive.

When the “Find” button is clicked, the entry is looked up in the database. If not found, the search page is re-served with an error message at the top that says “No match!”, and with the textbox pre-filled with whatever the user had entered.

If, however, the search was successful, the user is presented with a detail page which is made up of four label-textbox pairs:

• Last Name

• First Name

• Telephone

• Comments

The textboxes are to be pre-populated with values from the corresponding columns of the matching row in the database. (If several matches were found, then only the first one — in last name order — should be shown.)

Note that the textboxes must be in read-only mode, and that the 4th one must actually be a text area, in order to accommodate large comments. This page must also include a “Back” button to enable the user to return to the search page with its textbox pre-filled.

If it is you who has come to the page, another button should be made available, named “New Contact”, below the Find search bar. (Do not provide this — or make the functionality accessible — to anyone else.) If you click it, it gives you the very same layout as a search result, showing you fields for Last Name, First Name, Telephone, and Comments. However, this time, there is nothing filled in the fields, and they are open for you to enter values. At the bottom should be a “Back” button and a “Save” button. “Save” should add that as an entry into your contact database.

Your webapp consists of five files.

1. pb.cgi

   • A shell script that launches the Java app.

2. PBapp.java

   • An app whose main method contains new PB();.

3. PB.java

   • The PhoneBook Webapp.

4. PBdao.java

   • A class that implements the database connectivity.

5. PBrow.java

   • A simple data structure to represent one row in the Contact table.

Start by developing PBrow. It should have five private attributes — the four mentioned in the requirements plus the ID — a getter and setter for each, and a default constructor that initializes the ID to -1, and the remaining attributes to empty strings.

Next, develop PBdao whose attributes must include a Statement object. Its constructor must connect to your database, and initialize the statement attribute. It must also have the method

public PBrow find(String entry)

This takes the entry made by the user in the search page, looks for it in the database — as described in the requirements — and returns the matching row. (The return should be null, if no match is found.)

The PB class acts as a controller that receives the incoming request, extracts the needed HTTP headers and parameters, and sequences the flow. It also includes methods for serving up the two pages.

Template implementations of some of the needed classes are available at

http://www.cse.yorku.ca/course/2041/lab4/

Start your implementation using these files, rather than start from scratch.

It is recommended that you use Eclipse as an IDE. To use Eclipse, click “Start, Programs, BlackBerry, EclipseEE Blackberry.” Once in Eclipse, create a new “Java Project”. Your home directory is mapped as drive Z, so create your workspace there.

I recommend that you proceed in the following steps.

1. Database

   Set up your contact database.

   Get your app code working for the database connection part for fetching a particular contact record by name.

2. Online

   Get your app working “online”, so one can access it from a web client.

   Just handle the initial “Find” functionality at this point. Do not worry about greeting the person or the “New Contact” yet.

   Implement the HTML of the response pages.

3. Greet

   Implement the greeting functionality to welcome, and to welcome back, a user.

4. New Contact

   Now extend your app to include the “New Contact” functionality.

We have been doing the example of a server-side app in class of a calculator (ParkeCalc is what I called the one I sketched up). The versions are written in Perl, but illustrate much of what we are doing here.

You can poke at these at the following places:

• ParkeCalc.html
• ParkeCalcB.cgi
• ParkeCalcC.cgi

You can look at the code here.

Create a table named Contact. Use the Derby database system from Lab #2 with the CSE “database”, using your Derby user name and password from Lab #2.

The file create_contact.sql describes the schema for the table. Use ij and that file to make your table:

run 'create_contact.sql';

Note that you do not set schema ... This table belongs to you, and so is under your default schema.

We will use just a subset of the columns today. Use phone1 to hold the telephone number. Note that the ID column is an integer that is auto-generated and, hence, is unique for each entry.

Add a few rows to the table so you can test your webapp. E.g.,

insert into Contact (LastName, FirstName, Phone1, Comments) 
    values ('University', 'York', '416-224-1833', 'Alma mater'); 
		

It is recommended that you enter the names — both first and last — in uppercase. This will facilitate search. Do a select to view your inserted rows. Verify that they have different IDs.

Ithe design, PBdao oversees the connection to the Derby database. Any queries that you need to make to the database are implemented as methods here; for example, find.

PBrow is a helper class. It is an object that holds a contact “row” that you retrieved from the database, or set in order to put in the database. It has setters and getters for each of the fields. This just makes the design for the rest of the code simpler.

Get your app connected and running. PBapp has the main method. It is launched by pb.cgi, which is just a little CGI launcher script. (You likely will not have to modify PBapp.)

PB handles the main application logic. It is responsible for handling the CGI requests, and generating the proper HTTP responses and payloads.

It will need to fetch the CGI input parameters. The app is to use the method POST, so these will be on standard input for PB. It will decide what mode of operation it is in, depending on what the parameters are. Accordingly, it will deliver the right HTML payload back to the client, following proper HTTP headers.

At this point, you should handle two modes: welcome and find results. For welcome, you are delivering the basic start page, which has a “Find” search bar. You would deliver this if no parameters came in. For find results, this is delivering the search result of a “Find” request. This page should also provide a “back” button, which would get the client back to welcome.

Now, add the functionality to track the user (client). Since clients have to authenticate to get to your app (and are using HTTPS so the session is confidental), your app can know who it is. All we are doing for this project is welcoming the user, and welcoming back the user, if he or she is coming to the app again.

Who the user is is not passed in as a parameter. Rather, it is part of the environment the web-server sets for your app instance. The environment consists of environment variables with such type of information stored there.

In Java, these can be accessed using the one-parameter method System.getenv(...). This returns a string with the value for that key, if the key is present. So, to fetch the user name is System.getenv("REMOTE_USER"). (If null is returned, the server did not set this key "REMOTE_USER". for instance, maybe the server does not know. This would be the case if your app is accessible by a non-authenticated session.

How will you “remember” whether and when the user used the app last? Set a cookie. This will be stored by the user's client browser, and sent back to the app whenever the client starts a new HTTP session with the app.

Cookies go back and forth as headers in HTTP. In the request from the client, there is a header Cookie: that delivers any cookies to the server that were previously stored from past visits. In the response from the server, there is a header Set-cookie: that asks the client browser to store a cookie on the server's behalf.

Your app wants to set a cookie called pb with the timestamp of now. Use java.util.Date().getTime() to find now. Then you want to print as a header Set-Cookie: pb=1319552311; secure. The number is an example of the timestamp. The secure tells the client only to return the cookie under use of HTTPS.

If a client returns back to your app later, in the request, there will be a header Cookie: ...; pb=1319552311; .... This is the list of cookies being delivered back to you. Likely, in your case, there will be just the one key-value in the list (for pb), but you cannot count on this. In Java, you can get this information from the environment, System.getenv("HTTP_COOKIE").

To welcome back a user, search for the pb cookie. If it is there, you can retrieve its timestamp value, which says when the user last used the app (the last time the cookie was set). You will need to convert the timestamp into a human readable date and time. I recomend java.util.Date().

Next is to extend the functionality of your app. First, go to Lab Report, and check in your code. You are only responsible for parts 1 to 3 for the Lab Report. And save a copy of your code for yourself.

If you get this part done and want to turn in the fuller version later, please do.

Add the functionality of “New Contact” as defined in the Requirements section.

Leave your pb app active. Submit your java files. You only need to have the functionality of parts 1-3 for this.

submit 2041 lab4 PBapp.java PB.java PBdao.java PBrow.java