-----------------------
Lab #05 for CST8165 due November 22, 2006  (* DUE DATE UPDATED *)
-----------------------
-Ian! D. Allen - idallen@idallen.ca

Remember - knowing how to find out an answer is more important than
memorizing the answer.  Learn to fish!  RTFM!  (Read The Fine Manual)

Global weight: 5% of your total mark this term.
Due date: At the start of your lab period on Wednesday November 22.

Interim submissions: Wednesday November 8 and 15
  You will submit whatever progress you have made on this assignment
  before midnight on Wednesday November 8 and 15.

The on-line deliverables for this exercise are to be submitted on-line in
the Linux Lab T127 using the "cstsubmit" method described in the exercise
description, below.  No paper; no email; no FTP.

Late-submission date: I will accept without penalty exercises that are
submitted late but before 10h00 (10am) Thursday November 23, 2006.
After that late-submission date, the exercise is worth zero marks.

Interim work must be submitted by midnight on November 8 and 15.

Exercises submitted by the *due date* will be marked on-line and your
marks will be sent to you by email after the late-submission date.

Code submitted without your added useful comments (no matter what its
source) will not be marked (except for the Pig Latin code file).

Exercise Synopsis
-----------------
    Modify an existing Java-based HTTP server.
    Document it.
    Test it.

Where to work
-------------
    Submissions must run cleanly in the T127 Linux Lab, though you are
    free to develop and work on them anywhere you like.

    If you develop elsewhere, make sure the code works on the Linux Lab
    machines as well; that's where I test it!

    Code submitted without your added useful comments (no matter what
    its source) will not be marked (except for the Pig Latin code file).

Resources / Documentation
-------------------------
    See week10notes.txt : "Coding an HTTP server (Java)"

    Suggested template from which to start coding a simple HTTP server:

    http://www.brics.dk/ixwt/examples/FileServer.java

      - this version does not adhere to the HTTP RFC in many respects
      - needs comments on functionality (not on how Java works)
      - has many "public" items that should be made private
      - may be missing things such as closing opened files...
      - client request parsing is broken and also not very "liberal"
      - needs a "time-out" so it doesn't run all day

Code Quality and Portability
----------------------------

A.  You must include useful comment blocks ahead of the code you write or
    modify.  Code submitted without your added useful comments will not
    be marked (except for the Pig Latin code file).

B.  Marks are awarded for readability and elegance, not just correctness.  
    If your code can't be read, you're useless in a team project.

Coding the server
-----------------

1)  Using the sample code (above), implement a basic HTTP RFC 2616 server
    with Java class name "PigLatinHTTP" that handles the two methods that
    MUST BE supported by a general-purpose HTTP server.  (5.1.1 p.36)
    The 145-line FileServer code (above) is a very good starting point;
    but, note its many flaws (and lack of comments).

2)  Add comments to the given source code.  Fix the above problems.

3)  Your PigLatinHTTP server must accept HTTP protocol versions 1.0 and 1.1
    in requests from clients.  (The sample code already does this.)
    Your server does *not* have to implement:
     - persistent connections
     - continuation lines
     - URIs with blanks or escapes (e.g. + or %20)
     - reading header lines from a client (only read one client request line)
     - checking for a mandatory "Host:" field (even for HTTP 1.1)
    The server need only read a single request line from a client.
    (The above sample code already does this; only one line is read.)

    If in doubt about what you need to implement, ask your instructor.

4)  BE LIBERAL in the syntax you accept in client requests to your
    server.  For example: Allow extra white-space after the method and
    before the HTTP version string.  You may assume that the URI in
    the client request does not contain any whitespace.  (Blanks would
    usually be escaped as %20; however, your server doesn't need to
    handle blanks or escapes in URIs.  See the programming Hints below.)  

5)  Implement the following additional server response header fields:
    Server:           (pick a name for your PigLatinHTTP server)
    Content-Length:   (the length in bytes of the file being served)
    Content-Type:     (the MIME type of the file being returned)
    Date:             (the current date - section 14.18)
    Last-Modified:    (the last modified date of the file being served - 14.29)

    (Java note: The java.io.File class has methods to return some of
    the above required information.  See the Hints and Resources.)

6)  Use the guessContentTypeFromName method to generate your
    Content-Type field.  (The sample code already does this.)
    
7)  Major Change:  If the content type being requested is "text/plain",
    return the "Pig Latin" version of the file, not the regular text.
    You will find a PigLatinTranslator.java file in the course notes.
    You can try the translator by building and running it:
        $ javac PigLatinTranslator.java
	$ java PigLatinTranslator <inputfile.txt
    You may use any Pig Latin software you wish; however, you have
    to supply it with your submission named "PigLatinTranslator.java".
    Students do *NOT* need to add further comments to the Pig Latin
    translator source file.

8)  Important Programming Hints:
    - Remember to return lines ending in CR+LF, not just LF
    - Remember that error messages should appear on stderr, not stdout:
      use System.err.println() not System.out.println().
    - The "trim()" method of String is useful for removing whitespace.
    - The "split()" method of String is useful for parsing into an array.
    - Make sure you use the ".equals(String)" method to compare strings.
    - The "lastModified()" and "length()" methods of File will be useful.
    - The Date(int) class is useful for converting lastModified() seconds.
    - The main() and filter() inside PigLatinTranslator are useful as a
      model for reading and writing lines (not bytes) from/to a stream.
    - See the comments at the top of the PigLatinTranslator.java file for
      how to use it in your PigLatinHTTP class.

9)  If you find yourself duplicating code, re-factor your source and
    create a function to handle the duplicate code in one place.

10) Code submitted without your added useful comments (no matter what
    its source) will not be marked (except for the Pig Latin code).

Bonus Work
----------

11) When generating error codes, supply more useful information about
    the error in the Reason-Phrase text field (section 6.1.1),
    e.g. "400 Unknown Version String: HTTP/2.0".  (Remember - the
    ideal is error messages that adhere to the four rules given in
    programming_style.txt.)  For other ideas, see the sample error
    messages in the file test_out3.txt in the Notes.

Automated Test Plan
--------------------

12) The object of a Test Plan is to prove to the reader that your code
    works under all possible combinations of inputs (or at least as many
    as you can reasonably test).  You will use an automated script to
    run tests against your server.  I will run your test plan and the
    thoroughness of your tests will be the primary basis for your mark.

13) Automated testing: To test HTTP requests, you can "fake" requests
    from a browser by putting the lines you want the server to send into
    a text file (e.g. input.txt) and using "nc" as the HTTP client:

       $ java PigLatinHTTP 55555 . &        # start server
       $ nc -v localhost 55555 <input.txt   # send input.txt to server

14) You will find an automated test script with a few tests already
    programmed, in the notes as "testplanscript3.txt".  Sample output
    from running the test script is in notes file "test_out3.txt".

    Rename and modify the given automated test script testplanscript3.txt
    to test your PigLatinHTTP server.

15) Record the output of applying your Test Plan in file "test_out.txt".
    (Either redirect the output of your test script; or, run a "script"
    session and submit it with your files for marking.)

16) Develop a written Test Plan "README.txt" that outlines the types
    of tests done by test_plan.sh (with output in test_out.txt).
    Summarize your test results.
    Partial test plans are work partial marks.

17) Note: Nothing in your code or test structure can include absolute
    pathnames (except to well-known system files); in particular, you
    must not reference your own home directory or directories that are
    not public.

Submission and Marking Scheme
-----------------------------

Submission Standards (see earlier labs for details):

18) At the top of each and every submitted file, as comments, create an
    Exterior Assignment Submission label.  This label identifies the
    file; it is not a substitute for proper documentation in the file.
    Your file will still need comments and function headers.

19) For material you copy from other sources, credit the author and source.
    If the comments in the source you copy are not sufficient, you must
    fix and add to them, just as if you wrote the code yourself.

20) Submit all your source files for marking as Exercise 05 using a
    *single* cstsubmit command line (always submit all files together):

      $ ~alleni/bin/cstsubmit 05 \
          PigLatinHTTP.java  PigLatinTranslator.java \
          README.txt  test_plan.sh  test_out.txt

    Submit all the files necessary to buid, run, and test your HTTP
    server.  Do not submit object files or binary files.

21) To be marked, the files named above must have the exact names given.
    Code submitted without your added useful comments (no matter what
    its source) will not be marked (except for the Pig Latin code file).

22) If you aren't sure if you've submitted all the necessary files for your
    project, change to a new empty directory and use cstsubmit to fetch
    back your submission, then expand it, run "javac *.java" to compile it,
    and then run your test script.  It should work.

All files submitted must be named correctly and have assignment headers.

Marking Scheme
--------------

23) Your Automated Testing and README.txt : 80%
 - File names:  README.txt, test_plan.sh, and output in test_out.txt
 - Your automated test plan is most of your mark.
 - Number the sections in README.txt; refer to them in your testing,
   and vice-versa (cross reference both files).
 - Your test_plan.sh must refer to the numbered sections in your README file.
 - Your README file must refer to the numbered sections in your test_plan.sh.
 - Document what should happen for every possible type of good and bad input.
   - Test command line argument parsing and error messages.
   - Test parsing and error detection by your HTTP server.
 - Submit your testing output file named "test_out.txt"
 - You must use and enhance the "test_plan.sh" automated testing script.
 - The HTTP RFC 2616 sets down the rules for your server behaviour;
   but, remember that you don't have to implement the tricky stuff yet.

24) Coding Style: 20%
 - Source File: PigLatinHTTP.java
 - see note file programming_style.txt (updated November 9)
 - are the comments you add useful in understanding what the code does?
 - no "useless comments" - see programming_style.txt
 - comments are in block form, not excessively interleaved with code
 - sparing use of end-of-line comments
 - "be liberal in what you accept"
 - do the error messages appear on stderr and contain full information,
   including the name of the program issuing them?
   - never say "too many" - print the limit
   - never say "not enough" - tell exactly what was expected
   - no user input, short of child pornography, should be mislabelled "illegal" 
 - is this code easy to read and understand?
   - neat, organized, well-spaced
   - is the indentation consistent (Unix tabs are every 8 - "man expand")
 - is this code easy to change and maintain?
   - no "magic numbers" - document your constants and offsets
   - no duplicate code (uses functions for common actions, repeated code)
 - all input presumed hostile and handled safely
 - all return codes checked
 - "less code is better code"

25) Bonus Work: +10%
 - You may earn an additional 10% for bonus work (see above).

All files submitted must be named correctly and have assignment headers.