CS145 - Spring
2003
Introduction to Databases
Part 3: AuctionBase Web Site   --   Due
Thursday May 29th |
- Programming work: Programming work must be submitted
electronically by Thursday at 11:59pm. Programming work submitted
after the deadline but less than 24 hours late (i.e., by Friday
11:59pm) 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:59pm) will be penalized 30%. No programming work will be
accepted more than 48 hours late.
- For emergencies: Since emergencies do arise, each
student is allocated four "chits" for turning in CS145 project
work or challenge problems late with no penalty. Please see the
Late Policy on the Assigned
Work page for a detailed description of chits.
- 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.
- Reminder: 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 an appropriate 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. This 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 with Oracle through JDBC
The sample code does not actually connect to
Oracle. Fotunately, 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 on these two websites: Introduction
to JDBC and the JDBC
Tutorial 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.
- Ability to manually change the "current time."
- 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 for new auction users to provide their
information to be entered into the database (name, initial rating
if not assigned automatically, optional location and country), if
relevant in your schema.
- Ability to browse auctions of interest based on a variety
of input choices. Possible parameters include open/closed status,
category, date, price, substring match in description, etc. Use
your imagination.
- Ability to see the winner(s) of a closed auction.
- Ability for auction users to enter bids on open auctions.
- 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 run various 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. Use your imagination.
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 will need to automatically generate unique itemIDs
for new auction items. You may do so any way you like.
- 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.
- When you generate dynamic HTML pages from your program, please
try to use relative paths for URLs, i.e., do not hard-code the machine
name and port number into your program. (We may be testing your
program on a different machine.) If you use relative paths then the
browser will automatically find the right machine and port number.
- Please note: 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 21 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 do need to 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 Jave
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.
What to submit
Prepare a submission directory containing a text file called
README 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 short description of all the input parameters that a user
can provide when browsing auctions.
- A short description of the different statistics that can be
computed.
- How the user gets to each of the capabilities required by the
assignment, if there's any chance at all it's not obvious from the
user interface.
- A list of any additional capabilities in your system, and
how the user gets to them if it's not obvious.
If you did not use Java Servlets and/or JDBC, your README
file must also include a detailed section explaining the languages or
tools that you used, how the code is structured, and how to run your
project. As a reminder, it is imperative that we can run your project
with a minimum of effort on the Sweet Hall Solaris machines.
From your submission directory, execute the command
/usr/class/cs145/bin/submit
Follow the
instructions exactly. If you must resubmit, run the command
/usr/class/cs145/bin/submit -replace
If you have
any problems, please send mail to cs145@cs.stanford.edu.
Remember that points may be deducted if you do not follow the
submission procedures exactly as specified, including file naming
and contents.
The (Optional) CS145 AuctionBase Contest
|
We will select a small number of AuctionBase systems as winners
of our second 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 4.
- 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 30th 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.