Web Server

Download from http://www.nyangau.org/webserver/webserver.zip.

What does it do

WebServer is a rather trivial Java implementation of a web server.

It simply serves files from the filesystem.

It can be told to serve an index file (if one exists) when the user fetches a directory. Failing this it will generate a directory listing.

Multiple locations may be defined, so that different portions of the URI space can be mapped to different portions of the filesystem.

It is possible to fetch the (readable) contents of a directory and its subdirectories as a .zip file.

Concepts

The web server serves data from a set of locations.

Each location exists as a subset of the URI tree (from the request URL), and serves data from a directory of the filesystem.

A location should not be defined for the URI tree below /webserver. The web servers documentation (this page) and icons are served from here.

Properties

Given the Concepts listed above, the properties which must be set up match pretty much one-for-one.

WebServlet.props might contain :-

# Default properties, explicitly stated
locations.default.uri=/
locations.default.dir=/
locations.default.index=index.html

# Override defaults, for j2sdk location
locations.j2sdk.uri=/j2sdk
locations.j2sdk.dir=/work/doc/java/j2sdk/docs
locations.j2sdk.index=

# Override defaults, for root location
locations.root.uri=/
locations.root.dir=/pub

# Which locations will we serve
locations=j2sdk,root

# Explicit mappings from file extension to MIME type
mime.bkt=application/bucket

# Mappings from file extension to 24x24 graphic
icon.bkt=/icons/bucket.gif

# Server name
name=Andys Web Server

# Log accesses to
logfile=/tmp/webserver.log

First if a location doesn't define its URI, base directory or index file defined, defaults are used. If the defaults aren't specified as locations.default. properties, hard coded values within the web server will be used.

Next there is a location called j2sdk. If the user requests a URI below /j2sdk, they'll be served files from /work/doc/java/j2sdk/docs and below. eg: fetching http://hostname:8080/j2sdk/api/packages.html will result in /work/doc/java/j2sdk/docs/api/packages.html being served.

As locations.j2sdk.index is blank, when a directory is fetched, it will simply be listed, rather than returning an index page (if there is one).

The next location is called root.

If the user fetches a directory, as there is no locations.root.index property, we fall back to the locations.default.index property, which says that if there is an index.html file in the directory, this should be returned.

The web server is to consider serving information from the j2sdk location, and then the root location.

The order is important in this example. If root came first, a fetch of http://hostname:8080/j2sdk/api/packages.html would match the root location URI, and the web server would attempt to serve /pub/api/packages/html.

Additional mappings from file extension to MIME types and icon files can be specified, although the web server has quite a selection already built-in. In addition, the "container" within which the web server runs will also have a selection of MIME types defined. In this example is a theoretical example of a new MIME type, called application/bucket, whose files typically have a .bkt file extension, and a suitable mini-graphic is at /icons/bucket.gif.

The web server is named, and this name is shown at the top of auto-generated directory listings.

A log file is specified, where successful web fetches are logged. This can be omitted, in which case no logging occurs.

WebServer.props :-

# HTTP
port=8080

# HTTPS
port_ssl=8443
keystore=WebServer.jks
storepass=password

# Security
roles=secretfiles
userids=spy
password.spy=secretsquirrel
roles.spy=secretfiles
realm=Simple Website
#secureURIs=/secret/*
secureURIs.secretfiles=/secret/*

This tells the web server to listen on port 8080 and 8443. The shipped WebServer.jks has a test CA and a server certificate signed by it. To avoid browser complaints, use a respected CA and certificate signed by it. If not interested in SSL, just comment out port_ssl.

If the secureURIs property is present, then that portion of URI space is protected. Because basic authentication is used, best to turn off HTTP access and insist upon HTTPS.

How to run WebServer

WebServer is implemented as a servlet called WebServlet. This is then hosted in a container, making a web server. The container accepts the requests from web browsers, and passes these to WebServlet for processing.

Using nyangau.se

By default, WebServlet is hosted in the nyangau.se servlet engine, (available from where WebServlet is obtained). This is possible, as WebServlet only uses a limited subset of the servlet API. When using nyangau.se, servlet initialisation time parameters are already stored in a normal Java properties file (called WebServlet.props).

Assuming you've already set up the WebServlet.props properties file, and that the nyangau-se.jar file is in the current directory, you can :-

java -cp nyangau-se.jar:webserver.jar WebServer

Point a browser at http://hostname:8080/.

Using conventional container

A more conventional approach is to embed WebServlet into a web application, and install this into a Servlet Engine such as Tomcat or a Web Application Server such as WebSphere. Using this approach, all WebServlet related initialisation parameters can be set up in the web.xml file, or a single initialisation property webserver.propsfn can be set to the name of a properties file.

This is way overkill for something as trivial as WebServlet, but this approach may make sense if you already have a container, or wish to integrate this functionality into some larger framework.

User guide

Here is what happens when I visit this web server, set up as indicated in the properties files above, on my server, called nyangau.

First I see :-

This matches the URI in the root location, and comes from the file /pub/index.html.

Clicking on AE Documentation :-

Also from the root location, served from the file /pub/ae/ae.htm.

If we visit a directory without an index page, we see the directory listing, as generated by the web server :-

If we visit the j2sdk location, we see that the index.html isn't listed for the directory even though it is present :-

Note that the directories may be returned as .zip files.

Copying

Feel free to copy, its public domain. Caveat Emptor.


The documentation is written and maintained by the WebServer author, Andy Key
andy.z.key@googlemail.com