Tiny Java Web Server and Servlet Container

aka Miniature WS

(with security update, J2EE deployment, and JSP)

Download

The Miniature Java Web Server includes most of functionality of real Web Servers including running servlets. The server is pretty small as in Java code as in result byte code. General  purpose of the Web server is running and debugging servlets. However, if you host not so high loaded web site, you can use the server as a regular web server with some benefits against big brothers. I found also very convenient to ship a servlet based product including this server, as a user can start a product just after unwrapping. You can try a web site hosted on this server under Linux. This web server works also on PDA like Sharp Zaurus LS5xxx, or on Windows CE based handhelds when JVM installed. It gives additional flexibility for your PDA, since using file upload and download servlet can simplify file synchronization and provide control of your PDA from web.

Testimonies

Using tjws with WebServices as a "RMI"/RPC protocol, and with HTTPS on
top, this is gold! Thanks!

I've downloaded TJWS and it looks like exactly what I’ve been looking for to use as a local web server to generate a web application.

I'm using the miniature java webserver on
my zaurus.
I wrote a few servlets for it and I'm very happy with how it performs.

History

Something in the end of 1998 I needed a web server with sources to debug some servlets, so I started used ACME Java Web Server. It was pretty good, expect supporting only JSDK 1.x and JDK 1.02. Since my servlets required a bit more, I have added support for contemporary versions of JDK and JSDK. Then I just continued adding more features and bug fixes. The current version is mostly compatible with the latest servlet container  specification (2.4). 

Benefits

  • About 60Kb footprint (almost smallest one, TJWS has almost 5 times less footprint comparing to competitors LWS and Jetty, more than twice less than Winstone)
  • Very fast and reliable, it performs better than some C/C++ based web servers
  • Can scale to thousands connection, clustering configuration is about of development
  • Perfect solution for web interfaced applications
  • Standard J2EE servlet deployment for .war packaged servlets
  • Simple configuration, no hundreds of config parameters
  • JSP

 

Is it real 2.4?

Most of servlet specification 2.4 features are available for J2EE deployed servlets. Selecting or not J2EE deployment  gives extra flexibility to develop very small servlets using minimum of 2.4 servlet specification. In this case a separate module for J2EE deployment and JSP scan be dropped (about 46Kb footprint).  It's an ideal for embedded system. Note that  JSP support is provided by GNU JSP. This version can be outdated, however TJWS can easily adopt any newer JSP provider.

Supported web.xml deployment tags

2.5 Deployment descriptor

2.5 specification introduced in Glassfish project looks interesting, so there is a plan to add 2.5 capabilities.

Application with Web UI

Recently, a new type of application appeared on market. You need to start an application and it will launch a web browser which will represent UI of the  application. This approach has many advantages and becomes more widely used. The Miniature Java Web Server is right tool to creation such kind of application. Download and unzip the archive and double click JAR in explorer or start shell script, then point browser to http://localhost:81 and enjoy the web interfaced application. (If you are on Unix, you need to have privileges to use port 81 or just change it to 80xx in cmd file). Note, that such kind of applications are also built on base heavily using JavaScript and ActiveX controls without actual web server, however such approach isn't secure and platform dependent.

How To?

Configuration of MJWS is fairly simple and based on properties files. You can use standard J2EE deployment of web applications. In this case you need to make sure that war.jar is presented in classpath when you start the server. It will create webapps directory where you can put your .war files for deployment. J2EE deployer is quite simplistic and there is no server.xml file yet. However, set of supported tags of web.xml is quite comprehensive. 

Command line parameters

All command line parameters start with '-' (dash) and most of them have a value part. Here they are:

p - specifies port number served by TJWS, default value is 80 for non secure and 443 for secure configuration, for example -p 8080

t - specifies name of throttles definition file. It allows to reduce speed accessing to particular files and improve overall performance of a server. An example of this file can look like:

# throttle file for tjws.sourceforge.net
   *               100000  # limit total web usage to 2/3 of our T1
   *.jpg|*.gif     50000   # limit images to 1/3 of our T1
   *.mpg           20000   # and movies to even less
   mediachest/*    20000   # MediaChest's pages are too popular

s - specifies servlet properties file in old Sun's legacy form. An example of this file can look like:

servlet./app-bin/tree.code=rogatkin.servlet.Dispatcher
servlet./app-bin/tree.initArgs=properties=src\javaarchitect\servlet\treeview.properties
servlet./app-bin/chat.code=rogatkin.chatservlet.ChatServlet
servlet./app-bin/chat.initArgs=properties=C:\\Projects\\ChatServlet\\chatservlet.properties
servlet./app-bin/lunch.code=javaarchitect.servlet.mishka.Friday
servlet./app-bin/lunch.initArgs=properties=src\javaarchitect\servlet\mishka.properties

r - specifies realm file. A format of this file looks like:

realmname=path,user:password

a - specifies aliases definition file, for example:

from=/;dir=src\javaarchitect\servlet\tree\resource
from=/pool;dir=data

b - bind address, if your server has several IP addresses, then you can specify which one to use.

k - backlog size, by default 50, but can't be less than 2.

nohup - server doesn't expect any terminal window, can be only killed to stop.

c - specifies CGI scripts location.

e - provides session timeout in minutes and can be negative. Negative value won't start session cleaning thread and will use persistent session cookie.

l[ar] - specifies to log accesses with optionally logged user-agent and referer HTTP headers.

w - provides web app deployer class name, by default used rogatkin.web.WarRoller

j - JSP servlet class, org.gjt.jsp.JSPServlet is default

nka - no keep alive (server uses keep-alive by default)

kat - keep alive timeout interval in seconds, default is 30

mka - max number of use a connection in keep-alive

nsp - no persistence for sessions (can be useful if sessions contain sensitive or bulky data)

err - allows to use own or standard error print stream. If there is no following parameter class name then used System.err as error print stream. If a parameter specified, then it's considered as a class name compatible for assignment to PrintStream. Such class will be instantiated and used for error redirection.

socketFactory - specifies class name of socket factory and used for setting secure connection.

It accepts also any freely specified options in form -option_name option_value. Such options passed without checking to custom server socket factory implementation.

Running it as a service on NT/2000/XP

You can run the latest version of the server (>1.42/1.7)  as NT service. File servservice.exe added to the distribution. I wrote this service for JDK 1.4. However, if somebody needs it to run on lower versions of JDK and has problems, then get sources from CVS, modify, and compile them, The NT service starter considers that all TJWS files reside in the same directory specified at installation of the service. .jar files can be in sub directory lib. Command line parameters have to be specified in cmdparams file. To get help line, run servservice.exe -help. Parameterless version of servservice.exe  is considered as a service.

Note that arg[0] on some versions Windows doesn't contain fully specified path to an executable, so you need to specify it as a parameter at installation. So, there is no requirements to have servservice.exe in the same directory where TJWS is.

Run it on Zaurus

Zaurus version of the web server is JDK 1.1 compatible and distributed in a separate archive. Unzip distributive to CF card. Directory ws should be created. Insert the card to Zaurus and run terminal window. Type cd /mnt/cf/ws, then ./ws.sh. After few second you can see message on screen that the server is running on port 8080. Run opera and select URL http://localhost:8080. You should see a web page. Select URL http://localhost:8080/app/, then you should be able to browse your Zaurus file system. When your Zaurus connected to host PC over USB cradle or Wi-Fi card, you should be able to access this server remotely from PC browser using your Zaurus IP address. Mark this page for upcoming cool servlets. You can also try .ipk installation package, however it isn't tested well and no way to stop it unless using kill. You can try also the not Zaurus adopted version of the server on Zaurus, since Zaurus' Java has support of collection classes introduced in JDK 1.2.

Hints to compile Zaurus version

I use cross compilation with the latest version J2SDK, to make sure that result version will run on Zaurus the following compilation options used:

-source 1.1 -target 1.1 -bootclasspath "C:\Program Files\Java\j2re1.1\lib\core.jar;C:\Program Files\Java\j2re1.1\lib\classes.jar"

Note that core.jar extracted from Zaurus and classes.jar is system classes from J2SDK 1.1.8.

Note for OpenZaurus users

If you use this server running on original Zaurus OS (it's good idea to run  home web site to save some electricity) and going to update your version to OpenZaurus 3.x, then do not forget to extract Jeode. Supplied kaffe for OpenZaurus is quite unstable and you can lose possibility to run this web server on it. Good instructions how to move Jeode from Zaurus OS to OpenZaurus you can find here.

FAQ (Zaurus)

I got some flow of questions regarding Zaurus version and running servlets on it, so I decided to provide short FAQ.

Q: When I try to reach my servlet of Zaurus using http://localhost/MyServlet.class I'm getting page not found error, what can be wrong?

A: Most frequent cause of this problem, that you need to add a servlet definition in servlet .properties file and add a reference to this file to a start script using key -s.

Q: I created servlet.properties file and add MyServlet to it, but I am still not getting the servlet running, what can be a cause?

A: You probably forgot to add your servlet classes location in class path in a start script of a server.

Security

Security becomes more important nowadays, so I decided to add SSL support to MJWS. Thanks JSSE that makes that fairly easy. Here some tips how to install SSL support to the server.

Here is a list of free options for secure socket:

  1. algorithm - encryption algorithm, SUNX509 when not specified
  2. clientAuth - requires client authorization, false when not specified
  3. keystoreFile - key store file path, user_home/.keystore by default
  4. keystorePass - key store password, empty string when not specified
  5. keystoreType - type of key store, Sun's JKS when not specified
  6. protocol - secure protocol, TLS when not specified
  7. backlog - backlog value, 1000 by default
  8. ifAddress - bind to specified address
  9. port - bind to specified port

Note that some secure socket options will override options specified in common way.

Help wanted

I'm looking for a developer to finish work on pending web.xml instructions and also adding tag library support. Next step can be adding EJB support as well.

Download

Please download (version 1.13 updated on 01/10/2006 )

Note: Base TJWS is Java 2 (JDK 1.2) compatible, SSL module requires extra classes introduced in JDK 1.3-1.4. J2EE war deployment requires Java 5 (JDK 1.5 or 1.6). If you would like to build a version, then you will need to download 7bees Java based build tool. env.xml assumes target 1.4 for TJWS and 1.5 for the rest. It may need editing to provide SDK paths and targets. Since a build tool is matter of personal taste, you can use any other favorite build tools. 

Since this project is in a stage of adding new features, you can get them faster when checking out the latest code from CVS.

Zaurus version get here and .ipk version (use kill to stop)

Last changes history

Attention users of 2.4-2.5 features

J2EE deployment and web.xml processing were added recently, so some bugs excepted. Do not hesitate to report any problems. Your reports help to keep the server in a good shape. I encourage you to try all your web applications on TJWS.

Version tracking notes

After rechecking sources in sourceforge CVS repository, all version numbers restarted. So, all mentions of versions below are related to versions maintained in my CVS repository. 

CVS

CVS is hosted for the project, so you can always get latest sources from there.

J2SDK 1.5

Starting from version 1.50 new 1.5 Java language features used. Zaurus version stopped for support.

Build Tool

Starting from version 1.53 the project uses 7bee as a building tool. You can freely download 7bee from here. You can still use old batch/script files, however they are removed from the current archive and not supported anymore.

Sources

Although a distributed archive includes all source, you can always get the latest from CVS..

Copyrights

The Miniature Java Web Server carries all copyrights of the original author as stated in the license you can find in any source file.

License

The Miniature Java Web Server inherited BSD like license from the original code, check any source file for details. Note, that the server is completely free and no any donations ever asked. Recently I traveled to Asia and found that asking for donation is kind of Asian business, when people initially offer some services for free, and then asking for money. So every free service has hidden obligation for paying for it.  

Support

I do not provide as free as paid support for the server. However, you are always welcome to send a bug report, or an enhancement request.

Extra Bonus

Version of 1.7 and later include some useful web applications packaged as .war files and deployed at first server run. To enjoy the applications just follow a link on start page. If you do not want to have these applications deployed, just remove corresponding .war files from webapps directory before first server run.

Check also..

Comprehensive tools to handle all media files as digital photos and  music

xBox - Bean box supporting XML serialization (do not confuse with proposed later java.beans.Encoder)

jAddressBook is an address book with float XML format of addresses and another profile information

Contact

Bugs, questions, and enhancement requests you can send to Dmitriy Rogatkin. I hope you enjoy using this server.