Spring 2008

Programming Project 1, Part 3 (Final Part)

(worth 50% of overall Project 1 grade)

Your team

You will do Part 3 (the final part) of Project 1 with the same team as for Parts 1 and 2. If your team partner dropped the class and you did not submit a contingency plan with your Part 1 submission, then, unfortunately, you will still have to complete the project yourself. If your team partner dropped the class and you did submit a contingency plan with your Part 1 submission, then you are welcome to switch to this reduced version of your project.

Computer accounts

As for Part 2, you will need a CS account to do Part 3 of Project 1.

What you need to do for Part 3 of Project 1

For Part 3 of this project, you will finish building the application that you proposed in Part 1, on top of the database that you created in Part 2. For the final evaluation of Project 1, both team members will meet with one of the TAs together on Thursday March 27 or Friday March 28. A TA will contact you to schedule a 15-minute meeting for one of those days.

Important notes:

· You should make sure that you loaded sufficient data into your database to show off all functionality of your application.

· You can make (hopefully small) changes to the SQL schema that you created in Part 2 (e.g., to add any extra tables that you might need, or modify existing ones). If for some strange reason you feel the need to make any radical changes, please check with the TAs ahead of time to avoid any last-minute surprises.

· Because an entire class of students testing applications could overload the departmental machines, please use your PostgreSQL account on the class servers while developing your project, rather than your own instance of PostgreSQL. As a reminder, the class server that you should use is:

o w4111b.cs.columbia.edu

· If you develop your application using PHP, please use the class web servers for testing.

· If you develop your application using Java, you may run the Resin application server (see below) on any CLIC machine, but you should remember to shut down the server before logging out.

Web front-end for your application

Your application can be written in Java or PHP (your choice), and should have a web interface. Specifically, you have a choice of two technologies for your project:

· Option 1: Java servlets, using Java only and JDBC for database connectivity.

· Option 2: PHP, using PHP only.

The web front-end for your application can be HTML forms in combination with Java servlets or PHP (pick one). The less your web site looks like it is interacting with a relational database, the better. At the very least, the user should be completely shielded from having to type anything resembling SQL.

Option 1: Java and JDBC

If you choose Option 1 for your implementation, you should implement your application using Java servlets. Your implementation will consist of:

1. Java servlet,

2. Servlet engine (Resin), and

3. PostgreSQL backend (your database)

The application you write will use Java servlets, which receive web page requests, interact with the database server by using JDBC, and return HTML. A very friendly short course on Java database programming using JDBC is at http://developer.java.sun.com/developer/onlineTraining/Database/JDBCShortCourse/contents.html. A JDBC database access tutorial is at http://java.sun.com/docs/books/tutorial/jdbc/basics/gettingstarted.html.

In order to access a PostgreSQL database server, you will need the correct JDBC driver. For this, please download the proper JDBC driver from http://jdbc.postgresql.org/download.html.

For a PostgreSQL-specific example using JDBC, please refer to: http://database.sarang.net/database/postgres/aw_pgsql_book/aw_pgsql_book.pdf. You will have to modify the database connection string. You can find a sample servlet here.

You may use Java as your language for CGI scripts. This option is permissible, but will result in extremely slow response times, since the web server will need to load a Java VM for every invocation of your Java program. Instead, follow the directions below to install Resin, a second-tier server. Note: Using Java directly for CGI is an unsupported alternative, so we discourage you from following it.

The following are directions for installing your Java second-tier server, Resin, assuming that you use bash as shell (if you use other shells, please use an appropriately modified version of this; please contact the TA if you have questions):

1. Install Resin: Download Resin at http://www.caucho.com/download/resin-3.0.23.tar.gz, save it in your home directory, and then extract/untar the file, as follows.

~$tar zxvf resin-3.0.23.tar.gz

~$cd resin-3.0.23

~/resin-3.0.23$configure

~/resin-3.0.23$make

~/resin-3.0.23$make install

2. Configure Resin: Add the following lines to your .bashrc or .profile file, or equivalent:

export RESIN_HOME=<directory where you installed resin>

export CLASSPATH=$RESIN_HOME/lib/resin.jar:$RESIN_HOME/lib/servlet.jar:$CLASSPATH

~$cd $RESIN_HOME/conf

Edit file resin.conf to change the value of port from 8080 to the port on which your host (server) will accept incoming connections (http requests). Your team’s port number will be 5090 + (team-number)*2. To find out your team number, check the CourseWorks grade page for the class.

You should also remove or mask the following line:

<cluster> <!-- < srun id="" host="127.0.0.1" port="6802" index="1"/ > -- > < /cluster >.

3. Start the server:

~$cd resin-3.0.23/bin

~/resin-3.0.23/bin$sh httpd.sh &

4. Create servlets: You should put your servlets in the resin-3.0.23/webapps/ROOT/WEB-INF/classes directory. Then, you will be able to access your servlets at http://localhost:portnumber/Javafile.

For example, you can create a Java file as resin-3.0.23/webapps/ROOT/WEB-INF/classes/HelloServlet.java, and then access it as http://helsinki.clic.cs.columbia.edu:7791/HelloServlet, where “helsinki” is the machine where your Resin server is running and 7791 is the port number where your Resin server is listening.

5. Stop the server: Do ps -U <account-name> and kill the first (i.e., lowest-numbered) process that says JAVA next to it.

~$ps –U <account-name>

~$kill <process ID> (the lowest-numbered process that says JAVA next to it)

Important Note: You must stop your Resin server by following the last step above after you’re done testing, etc. and before you logout from the CLIC machine where you were working.

Option 2: PHP

If you choose Option 2 for your implementation and use PHP for this part of the project, please follow these guidelines.

IMPORTANT: Always use the class web server, w4111b.cs.columbia.edu (rather than www.cs.columbia.edu), for all your testing and development related to this project.

Your implementation of your application using PHP will consist of:

· PHP source code, which will provide all database connectivity, and

· PostgreSQL backend (your database).

The application you write will use PHP, which is executed by the web server when a PHP page is requested by a browser. The PHP source code both connects to the backend database and outputs information (HTML) to the web server, which is in turn transmitted for display on the client.

For information on using PHP with PostgreSQL, see: http://www.php.net/pgsql. Documentation for PHP can be found at http://www.php.net/docs.php as well as through the numerous books and websites related to PHP.

Important Note on PHP Security

If you choose to use PHP, please read this section carefully and follow our guidelines to secure your database account.

The PHP source files in your html directory are executed by the web server when accessed by a client. This means that the HTML produced by your PHP files is sent to the client, not the PHP source code. This is a good thing, in terms of security, since some of your PHP files will need to include your database account information (i.e., id, password, db name).

Your password, however, is not totally secure. Anyone with a CS account can still access your files by logging into a CS department machine and examining your directory. To help mitigate any security risks, please do the following:

1. Make sure that your password is not the same as your UNI or CS password, or the password for any other account.

2. Within your html directory, create a subdirectory <new_directory> for this project. While logged in and in your html directory, execute:
chmod 711 <new_directory>
This will prevent anyone other than you from obtaining a listing of this directory.

3. Create your project without using the filenames index.html or index.php. Use somewhat more cryptic, yet useful filenames (e.g. john_db_index.php instead of index.php). The server looks for these index.* files by default, which is nice, but the permissions change in Step 2 cannot prevent CS users from copying a file in your directory whose name they know. You can still test your project by typing the filename in your browser's address box.

What to submit and when

You do not need to submit anything for this (final) part of Project 1. Instead, students will meet with a TA on either Thursday March 27 or Friday March 28.

The TAs will email you to schedule a 15' meeting for either day. (If you haven't received an email from a TA by Monday March 10, please contact the TAs immediately after that day.) During the meeting with the TA, you will show him/her your application over the web using a regular web browser:

1. You should have your application up and running so that you and the TA can access it over the web from the CS department simply by typing a URL (e.g., http://w4111b.cs.columbia.edu/~user123/cs4111/project1/) in a regular browser.

2. The TA should be able to interact with your application and access the functionality that you specified in Part 1, over the database that you created for Part 2.

3. The TA might ask to look at your code during your meeting. You do not need to submit anything to the TAs ahead of time, but you might have to login into your CS account to show your code during the meeting.

4. Your web interface does not need to be fancy. (See Grading below.) However, you should not force users to type SQL. The less your web site looks like it is interacting with a relational database, the better. At the very least, the user should be completely shielded from having to type anything resembling SQL. Most interactions should involve some sort of input values in addition to the user pressing a Submit button. Whenever possible, input values should be specified using menus, radio buttons, checkboxes, scrollers, etc. Text input boxes may also be appropriate.

5. Sophisticated error handling is not necessary; however your web site definitely should not "lock up" regardless of how the user chooses to interact with it.

6. The TAs will either be running Mozilla/Firefox over Linux or Windows XP, or Internet Explorer over Windows XP. (You may use Javascript for some of the browser control, but make sure it is portable and works under Mozilla/Firefox over Linux and Windows XP, and Internet Explorer on Windows XP.) Note: The TA room only has Linux machines just as the CLIC machines.

7. Your database should contain (at least) the data that you entered for Part 2. You can, of course, add extra tuples to your tables if you want to make interaction with your application more interesting and revealing.

8. Your grade will suffer considerably if your application is not running properly when you access it from the TA's machine. It is your responsibility to ensure that your application is not dependent on a specific platform and that is up and running (and accessible over the web) when you meet with the TA.

9. You should have a number of example interactions prepared so that you can use your meeting time efficiently. The more you can impress the TA during the 15-minute meeting, the better your grade is likely to be, so come to the meeting prepared.

Grading for Part 3

Your grade for Part 3 of Project 1 will be a function of how well your application (which should be up and running) matches your specification that you submitted as Part 1, of how well you have incorporated any feedback that the TAs have given you, and of how well you have followed the guidelines above. Your grade will not be influenced by how fancy the web-based user interface to your application is. It is sufficient and perfectly fine for this interface to be plain and simple as long as it supports the functionality that you indicated earlier, following the guidelines above about not having to type SQL commands, etc.

Frequently-asked questions

Q: I don't like Options 1 and 2 above. Can I use a different set of tools or architecture?
A: As much as we would like to be more flexible, we just don't have the staff to handle several diverse systems and platforms. Unfortunately, you cannot use any other set of tools or architecture for this project.