CISC474, Spring 2005, Individual Homework H02

The following homework assignment should be completed after P02, your resin installation.

What you need to read before you start

In the textbook (Head First Servlets and JSP), first:

What you need to do before you start

Before you start, modify your "path" (the one that tells unix where to look for executables) so that $JAVA_HOME/bin is early enough in your path so that when you type in:

> which javac

the output is

/usr/local/j2sdk1.4.0_01/bin/javac

If you don't know how to do this, consult a Unix textbook, or a Unix guru. It has to do with editing your .cshrc and/or .login (or on bash, your .profile, etc. etc.)

Two more things you need to know before you start

  1. Go to the web site for the textbook. Find a link labelled "errata". You should do this with every technical textbook you read. The errata is a list of known errors in the book and how to fix them. Some time later, fix all the errors in your book. For now, just fix the ones on pages 67-91.
  2. In this chapter, you are going to be typing in some code from the book and making it run. Gradually, the book walks you step-by-step through some iterative changes to that code, with the changes marked in bold. However, in at least one place, they didn't mark a necessary change in bold. You'll have to read the code carefully to find that spot.

    If you miss it, you'll get a compiler error, and if your knowledge of Java is sound, you'll immediately know what is wrong and how to fix it. If not, this will be a good learing experience!

Step by step through the homework assignment, or
"How to do the examples in Chapter 3 with Resin on Jaguar"

Your book walks you through creating a small web applications using the MVC design pattern. The explanations in the book are very thorough, so we will not recreate them here. We are just going to point out the things that you need to do differently since the book is based on Jakarta Tomcat/Apache, and we are using Caucho Resin instead.

  1. On page 72, you will create the development environment. The only difference is that you need to create this directory structure (with a whole bunch cd and mkdir commands) under ~/cisc474/web_dev instead of under MyProjects. That is, the beerV1 directory goes immediately inside the ~/cisc474/web_dev directory.

    A unix hint: if you use "mkdir -p foo/bar/fum/fiddle, you can create an entire path with a single command (i.e. directory fiddle, inside directory fum, inside.. well, you get the idea.)
  2. On page 73 you will create the deployment environment. Here, instead of the directory tomcat/webapps being the root directory, you want the directory ~/cisc474/public_html/ to be the root directory.
  3. Do pages 74-76 as indicated in the text, except for this: From here on out, we'll expect you can make those kind of URL adjustments to the textbook's instructions on your own (i.e. changing localhost:8080 to jaguar.cis.udel.edu:pppp).
  4. Before you start on page 77, try bringing up the form and submitting it. You should see the form come up, but if you hit "Submit", you'll see an error message like the following: 
    404 Not Found
/Beer-v1/SelectBeer.do was not found on this server.

Resin 2.1.16 (built Tue Feb 15 11:12:27 PST 2005)
    Seeing this error message now will help you understand what the purpose of the next steps are, where you are implementing the thing that makes "SelectBeer.do" work properly.
  5. On page 77, you are creating a file called web.xml and saving it in your /beerV1/etc directory. The textbook shows you a <web-app ...> tag, and there is a note that says

    "You don't have to know what any of this means, just type it in".

    Well, yes and no. It is true that for now, we aren't too worried about what all that stuff means. But we do have to modify it a bit to make it work with Resin.


    Here's what the book has: 
    <web-app xmlns="http://java.sun.com/xml/ns/j2ee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
      version="2.4">

    Here's what you are going to need instead (a proper subset of the text above):

    <web-app xmlns="http://java.sun.com/xml/ns/j2ee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    For the intellectually curious for whom "Don't worry about it; just type it in" is too torturous, here's the quick explanation: the attributes of the web-app tag that we are leaving out are attributes that specify the XML schema for the deployment descriptor. These must be specified in the web-app element for Tomcat, but they are built in to Resin as defaults.

  6. Important:One more step is needed beyond what you have in the book to make this work with Resin. In your resin.conf file, add the following lines somewhere in the section that lists <web-app> tags: 

        <web-app id='Beer-v1/'/>
    As we all gain more familiarity with Resin and its configuration, perhaps we'll find a way to make it work without this. For now, this seems to be necessary.

  7. Continue with step 2 on page 77 exactly as shown, up through and including page 80.

    A hint: On page 80, there is some code you have to type into a file. The book doesn't tell you the filename explicitly, but if you have a sound knowledge of the Java language, there is only one possible filename that would make sense. The roadmap on page 72 tells you which directory to put that file in.


  8. On page 81, it shows the commands for compiling the servlet. Obviously, you want to cd to ~/cisc474/web_dev/beerV1 instead of MyProjects/beerV1. From now on, we'll assume you can figure out stuff like that on your own.

    What might not be obvious is the modification you will need to the classpath. Here is what the compile command needs to look like:
    javac -classpath $RESIN_HOME/lib/jsdk23.jar:classes:. -d classes src/com/example/web/BeerSelect.java
    There are similar compile commands on pages 85 and 90 that you'll need to modify in a similar fashion.
  9. Later on page 81, there are instructions for restarting Tomcat. You'll instead use the command:
        $RESIN_HOME/bin/httpd.sh restart
    Do this each time the book tells you to restart the server.
  10. Continue with the remaining steps and reading on pages 81-87.
  11. When you are done with the steps on p. 87, you'll have a file called result.jsp in both your development and your deployment directories. As soon as you have this file in the deployment directory, but before you have made the changes to the servlet to "call" your JSP file (i.e. before you do the steps on p. 88), just for fun, try this:
  12. Continue with the remaining steps and reading on pages 88-91.

That should take care of it! Once you have done all the steps in this chapter, we should be able to type in the following URL (replacing 8050 with your port number) and get the beer advisor application just like in the book:

http://jaguar.cis.udel.edu:8050/Beer-v1/form.html

Final steps for credit:

Once your application seems to be working properly on your port number, you will now create a "clone" of this application for some other product (e.g. Coffee, Soft Drinks, Cars, Pizzas, etc.) Here's how:

Under ~/cisc474/web_dev (called MyProjects in the book), you currently have a directory structure rooted in a directory called beerV1. You will create a second directory structure called productV1. This directory structure should mirror that of beerV1,but will be written for some other product of your choice: it could be coffee, or cars, or bagels, or whatever, but should have a similar interface and similar functionality to the Beer Expert page.

To make sure that each student chooses a different product, register your choice of product on the discussion board labelled "Product for H02" in WebCT. First come first served. Be sure that your product is one for which you can come up with at least four distinct categories, and have at least two example instances of the product for each category.

Develop and deploy this application in the same manner as the beerV1 example application in Chapter 3. Call your development directory ~/cisc474/web_dev/prodV1, and use the exact same directory structure. The separation of development directory and deployment directory, and the specific directory layout given is a required part of the assignment, not an optional one.

We'll look under http://jaguar.cis.udel.edu:pppp/Prod-v1/form.html for your application (where pppp is your port number). So name it literally Prod-v1; don't rename it to Cars-v1 or Coffee-v1 or whatever.

Be sure to add comments

The java files in the book have some comments in the margins in a kind of "hand written font". However they don't have actual Java-style comments such as: 
   // Instantiate a BeerExpert object, and iterate through all of
   // the beers that match the color selected by the user.  For each
   // one, generate some HTML and write it to the output file.
Add a reasonable number of such comments to the .java files for your clone application so that it is clear to your instructor and your TA that you know what the code is doing.

DO NOT just transcribe the "handwritten" comments in the textbook verbatim. Read those comments the first time you go through the code, but as you make the "clone" application, try to avoid reading them; instead, write comments in your own words based on your understanding of what the code is doing. (You can use those "handwritten" comments as a general guide for how much commenting is needed, and at what level of detail.)

In addition to these comments, be sure to have a comment at the top of each file similar to the following one that I wrote when testing out the assignment: 

// BeerExpert.java
// "Head First Servlets and JSP", 1st Edition, p. 82, O'Reilly (2004).
// Transcribed by Phillip T. Conrad for CISC474, 02/25/2005 
//
// "Model" part of a beer advisory system based on the
// Model-View-Controller design pattern.
Note that this comment contains:
  1. filename
  2. source of the code (in this case, name of book, page number)
  3. programmer name
  4. date
  5. brief description of the purpose of the code
Every source code file you ever write should contain these items (at a minimum) at the very top. This is a strict rule for me, and one that I try to model and live by, in addition to teaching it to other programmers.

The same rules goes equally for you .java and for your .xml, .html and .jsp files; put similar comments at or near the top of all the files in your projects.

To do that, you'll need to figure out the correct syntax for comments in each of those types of files. (If you don't know it, that becomes one of your "Learning Issues" in the "Problem-Based Learning" sense of the word. Use the resources available to you---check the course web site for hints!)

Submitting your work

To submit your work, you'll need to do four things.
  1. Deploy your prodV1 (aka /Prod-v1) application on your resin server on Jaguar so that it is publicly available.
  2. Write a paragraph or two about your experience with the assignment in a plain text file called README.txt, and place this in your ~/cisc474/web_dev/prodV1 directory. Include your full name.

    Here are some sample prompts to help you with writer's block: You may use these prompts verbatim if they are helpful, but don't be constrained by them. I always prefer to read sentences in your own words. Your paragraph(s) don't have to address each of those points---just the ones that apply to your experience.
  3. Create a gzipped tar file of your entire ~/cisc474/web_dev/prodV1 directory, including your README.txt file. Upload and submit this under the "H02" assignment on WebCT.
  4. Print out your README.txt, .java, .html, and .jsp source files, as well as printouts of a sample web session demonstrating your prodV1 application. Put the README.txt file on top as a cover sheet, staple everything together, and bring this to class to turn in on the day the assignment is due (Tuesday March 8th.)

Deadline

Get your Beer-v1 and Prod-v1 applications up and running by noon on Tuesday March 8rd. By then you should also have a solution to the problem of restarting your server after jaguar is rebooted. If we find a server down, we'll check back one hour later (assuming that your script to check and restart the server should run at least once per hour.)