CS145 - Spring
2004
Introduction to Databases
Project Part 3: AuctionBase Web Site Due
Thursday May 27th |
- Submission: Programming work is submitted electronically
and must be submitted by Thursday at 11:59 PM. Programming work
submitted after the deadline but less than 24 hours late (i.e., by
Friday 11:59 PM) will be accepted but penalized 10%, and programming
work submitted more than 24 hours but less than 48 hours late (i.e.,
by Saturday 11:59 PM) will be penalized 30%. No programming work will
be accepted more than 48 hours late.
- For emergencies: Since emergencies do arise, each
student is allowed a total of four unpenalized late days (four periods
up to 24 hours each) for programming work together with challenge
problems, although no single assignment may be more than two days
late. See the Assigned
Work page for more information.
- Honor Code reminder: For more detailed
discussion of the Stanford Honor Code as it pertains to CS145, please
see the Assigned
Work page under Honor Code. In summary: You must
indicate on your written and programming assignments any
assistance (human or otherwise) that you received. Any assistance
received that is not given proper citation will be considered a
violation of the Honor Code. In any event, you are responsible for
understanding and being able to explain on your own all material that
you submit.
- Projects must be completed individually.
Warning: Even more so than in the last project, a large number
of students will be putting significant load onto the Oracle
system at the same time. We strongly suggest that you start
early for your own benefit and convenience, and please be aware
that we will not extend the on-time deadline because the system
is slow.
Overview
As a baseline, you will design a set of queries and updates for your
AuctionBase system and create a simple Web interface for
them. Ambitious students may migrate the simple front-end into a
user-friendly Web interface that looks like a "real" auction site, and
may exploit triggers and other Oracle features for additional
functionality. Use your creativity. Several projects will be selected
to be demonstrated on the last day in class (for glory, not grades).
Getting Familiar with Java Servlets
In this portion of the project you will become familiar with Java
Servlets by setting up a servlet directory and experimenting with
sample code for a restaurant site.
- Step 0: Read the document Web-Database
Programming: CGI and Java Servlets (available through the course
web site Project
Support Materials page) for an overview of Servlets (you may
ignore the CGI section). Read the sections on Java Servlets
carefully.
- Step 1: Set up your directories.
Compiling Servlets in Unix requires a few changes to your
PATH and CLASSPATH environment variables. These
changes have been made for you in the source file
/usr/class/cs145/all.env. Just type "source
/usr/class/cs145/all.env". Alternatively, you can add this command to
your .cshrc file.
Within your home directory you must set up the following
directory structure:
servletdir
webpages
WEB-INF
servlets
A shell script to build this hierarchy is provided at
/usr/class/cs145/code/bin/buildServletDirectory. (Note: If
you add "source /usr/class/cs145/all.env" to your .cshrc
file, you can run buildServletDirectory by just typing the
command.)
You should store .html pages within this structure, in
the webpages directory. All Servlets must be located in the
servlets directory.
- Step 2: Copy the sample code. (If you do not want to
work off our sample code, you are free to write your own.)
We are providing a sample program to demonstrate the basic
functionality of Servlets and get you started with your
programming. It is in the directory
/usr/class/cs145/project/pa3/restaurant/. Please note
that the instructions, code, and support we are providing are only
tested and "guaranteed" on the leland Solaris machines.
Copy the appropriate files to your own directory. All
.html files should be placed in the webpages
directory from Step 1. All .java files should be
placed in the servlets directory.
- Step 3: You must compile your .java files by
running javac *.java. Once your directory structure is set
up and your Servlets are compiled, you can run the Java JSDK 2.1 Web
server manually on any leland Solaris machine (e.g., saga's,
elaine's, myth's) in order to provide these
documents over the Web. The steps involved in starting the server
are:
- Choose a random port number in the range 5000-65000. You
will bind your server application to that port for the machine on
which you're running your server. Try to choose a random number and
remember it -- you will be the only person on that machine who can use
that port, and you will need it to have access over the Web.
- Change to the servletdir directory, which is the root
of the directory structure you created in Step 1. From there, start
the server by calling "startserver -port portnum" from the Unix
command line, where "portnum" is the port number you chose in the
previous step. The server will begin in the background, and you can
see it using the "ps -elf | grep username" command. If you do not
enter a port number, the default port number 8080 will be chosen for
you. (You can actually set the default yourself: After you've run the
server once, it will create a configuration file called "default.cfg"
for you; it finds the default port number there.)
- From your browser, enter the URL of a Web page or Servlet
contained in your servletdir hierarchy. Static HTML documents
placed in the webpages directory are accessible from the Web
at the address http://machineXX:portnum/page.html, where
"machineXX" refers to the Solaris machine from which you're running
the Web server (e.g., saga22, elaine12,
myth7, etc.), "portnum" is a specific port (see above), and
"page.html" is the name of the HTML page that you are serving.
- To stop the server, issue the command
"stopserver". Warning: If you log into a leland machine and cannot
start a server because one is already running, do NOT type
"stopserver" or you will stop someone else's server! Instead, find a
different machine with no servers running on it.
- If you want to recompile your Servlets you must stop the
server, recompile, then restart the server. Static HTML pages that
you are hosting from the webpages directory can be changed at
will.
- Step 4: Understand the sample code.
Read the provided Java and HTML files and make sure you understand how
they work. For detailed documentation you may want to refer to the
Java Servlets Class Docs from Sun.
Connecting to Oracle through JDBC
The sample code does not actually connect to Oracle. Fortunately, Java
and JDBC make it very easy to connect to Oracle with only a few lines
of code. Everything you need to know can be found in our Introduction
to JDBC help document together with the JDBC
Tutorial web site from Sun.
Functionality
The functionality of your final AuctionBase system is quite flexible
and open-ended, however you must implement at least the following
basic capabilities in order to receive full credit on the project.
- Ability to manually change the "current time."
- Ability for auction users to enter bids on open auctions.
- Automatic auction closing. An auction is "open" after its
start time and "closed" when its end time is past or its buy price is
reached. Your design may be such that an auction closes implicitly
with high enough bids or a time update, or you may have chosen to
represent open/closed status with an explicit data field.
- Ability to see the winner of a closed auction.
- Ability to browse auctions of interest based on some simple
input choices such as category, price, and open/closed status.
Here are some examples of additional capabilities beyond our basic
expectations that you might consider adding to your system if you are feeling
ambitious. Use your imagination to come up with even more.
- Ability for new auction users to provide information to be
entered into the database (name, initial rating if not assigned
automatically, optional location and country).
- Ability for auction users to add new items up for auction.
- Ability to retrieve auction or bidding history for a given
user, including current auctions or bids.
- Ability to browse auctions of interest based on even more
input choices, such as date, substring match in description, etc.
- Ability to run some statistics over the auctions.
Possibilities include average number of bids per user, highest selling
price over initial bid, average time to reach buy-price, etc.
A note on extra functionality: You can receive full credit on
the project by implementing just the basic capabilities in the first
bullet list and a simple Web interface. That is the standard against
which projects will be graded. Many of you will realize that it is not
difficult to add functionality or "pretty up" the interface. You will
not receive additional points for doing so. However, in
addition to the possibility of winning the AuctionBase contest
(described below), we will make a note of students whose project goes
well beyond the basic expectations. Such notes do not affect the
grading curve, but they can on occasion affect an individual grade --
in a borderline case, or when an earlier project part was botched or
missed entirely. If you have questions about this policy, please ask
the course staff.
Notes
- All constraints and triggers from Project Part 2 should
continue to be active in your "live" AuctionBase system. In
particular, constraint violations due to data entry errors or bad
input values should be managed gracefully: it should be possible
for users to continue interacting with the system after a
constraint violation is detected, and the database should not be
corrupt. For information on constraint error-handling in your
Web interface please see the Constraints
and Triggers help document (under Constraint Violations).
- You don't have to implement user authentication. For
example, it's okay to ask the user to enter his username when
bidding, without asking for a password.
- If you allow new auction items to be entered into your
database, you will need to automatically generate unique itemIDs for
them. You may do so any way you like.
- When you generate dynamic HTML pages from your program, use
relative paths for URLs, i.e., do not hard-code the machine name and
port number into your program. (We will almost certainly be testing
your program on a different machine.) With relative paths the browser
will automatically find the right machine and port number.
- Important: The special characters &, <, and
> need to be replaced in HTML by the escape strings "&",
"<", and ">" (without the quotes) respectively so they
can be displayed properly. We expect you to escape all three
characters in displayed data even if you are testing on a browser that
does not require it.
User interface
While the functionality of your AuctionBase system is quite
open-ended, the interface itself is extremely open-ended. CS145
is not a user interface class and you can certainly get full credit
for a solid system with simple input boxes, menus, and/or radio
buttons, and simple HTML output tables, similar in style to the sample
restaurant Servlet we provide. (However, under no circumstances should
you be exposing SQL to the end user.) Of course we welcome much
snazzier interfaces, with the zenith being a near-replica of eBay itself.
Browser compatibility
Before turning in your final project please ensure that it operates
correctly using the Netscape browser on the Sweet Hall Solaris
workstations. If there is a compelling reason you cannot make your
system work in the Solaris Netscape browser environment (e.g., you
really want to exploit certain features in Internet Explorer), you
must get "preapproval" from the course staff to use a different
browser environment. Send an email message to cs145@cs.stanford.edu telling
us precisely what browser environment you wish to use for your
project. The message must be sent by Wednesday May 19 so that we
have time to work things out if your browser environment poses a
problem for us. You will receive a reply within 24 hours of your
message, and you must receive a positive confirmation message before
assuming that your alternate environment is okay.
When the preapproval process is not followed, projects that
have problems on the Sweet Hall Solaris Netscape browsers may
lose points, possibly all points if we cannot run your project at
all.
System testing and runaway queries
We strongly suggest that you debug your queries directly on Oracle
before hooking them into your Web interface. JDBC is
not particularly friendly when it comes to "runaway" queries, so
you will benefit yourself and the rest of the class by using
sqlplus first (through which runaway queries are easy to
kill using Ctrl-C) to ensure that your queries are
working properly and are finishing in a reasonable amount of
time. Once you are certain your queries are working correctly,
incorporate them into your Web interface.
Even with prior debugging, it is prudent to set a timeout
mechanism in JDBC for all of your queries. Use
setQueryTimeout([time in seconds]) on each of your
statement objects, for example:
Statement stmt = conn.createStatement( );
stmt.setQueryTimeout(180);
...
Finally, you should never close an ssh or
telnet session or an xterm window without
stopping all queries and Java servlets first. Otherwise, queries
may continue to run on Oracle long after you've turned in for the
night. Specifically:
- Always quit your programs cleanly (including
sqlplus), run stopserver for Java servlets, and
type exit or logout to quit from ssh,
telnet, or xterm.
- Do not force-close any windows.
- If you have trouble quitting normally, log into the same
machine from another window, use "ps -aef | grep
[username]" to find your process ID(s), and use "kill
[processID]" to kill each process.
- If you don't remember which machine your process(es) may be
running on, log into any leland machine and type
"sweetfinger [username]", which tells you the machines
you were logged into within the last few minutes.
Using other languages and tools
You are not required to implement your AuctionBase web site using Java
Servlets and JDBC. Any web programming environment and means of
connecting to Oracle is fine with us. However, only Java Servlets and
JDBC have guaranteed support from the course staff in terms of system
problems, knowledge, and general help. If you choose to use alternate
languages or tools, you may be on your own, and you are still required
to meet the project specifications.
Most importantly: It is imperative that we can run your
project with a minimum of effort on the Sweet Hall Solaris machines.
Due to the size of the class we will not be able to set up separate
environments for individual projects, or conduct private demos.
Having trouble?
If you run into difficulties, before contacting the course staff
please consult the Project Part 3
FAQ Page. We will keep it up-to-date with answers to common
questions.
What to submit
Prepare a submission directory containing a text file called
README.txt along with your entire servletdir
directory. Your README should include at least the
following, in this order:
- The line "I WOULD LIKE TO ENTER THE AUCTIONBASE CONTEST"
if you want your project to be considered for the contest described
below. Otherwise leave blank.
- A description of how the user gets to each of the basic
capabilities required by the assignment.
- A short description of the input parameters a user can provide
when browsing auctions.
- A list of any capabilities in your system beyond the basic
requirements, how the user gets to them, and a short description of
any relevant input parameters.
Since your servlet will be connecting to your Oracle database, make
sure that before submission and throughout the grading period your
database is loaded with all of the appropriate data, constraints, and
triggers. If you are using PL/SQL procedures or functions, make sure
they are loaded also.
If you did not use Java Servlets and/or JDBC: It's
imperative that we can run your project with a minimum of effort on
the Sweet Hall Solaris machines. You must submit all of your source
code, along with the following set of files:
Makefile | |
For compiling your source code |
runServer | |
Script for starting your server |
killServer | |
Script for stopping your server |
runBrowser | |
Script for starting a Netscape browser with appropriate arguments |
As usual, from your submission directory execute the script:
/afs/ir/class/cs145/bin/submit-project
You may resubmit as many times as you like, however only the latest
submission and timestamp are saved, and those are what we will use for
grading your work and determining late penalties. Submissions via
email will not be accepted.
Remember that points may be deducted if you do not follow the
submission procedures exactly as specified.
The (Optional) CS145 AuctionBase Contest
|
We will select a small number of AuctionBase systems as winners
of our third annual CS145 AuctionBase Contest. Winners
of the contest will:
- Demonstrate their projects to the class and the world (via
Stanford Online) as part of the last class meeting on June 2.
- Logistics permitting, have their running systems linked to
the CS145 home page for anyone to try.
- Be invited to enjoy lunch at the Stanford Faculty Club with
Prof. Widom, the TA's, and the other contest winners.
- Receive no extra credit, just the extra recognition.
The criteria for selection will be some combination of
beyond-the-basics functionality and a good user interface.
Important - If you want your project to be considered
for the contest, you must:
- Submit your project no later than one day late, i.e., by
Friday, May 28th at 11:59pm. This deadline is to allow
sufficient time for us to carefully select winners. Please note
that you may not submit one version of your project for grading
and one for the contest. Your last submission will be the one
used for grading and late penalty calculations, and it can be
considered for the contest only if it is submitted before
Friday at 11:59pm.
- As specified in What to submit, clearly indicate
at the top of your README file your desire to be
considered for the contest.