Tiny Java Web Server and Servlet Container

aka Miniature JWS

(with security update, J2EE deployment, JSP,  and  J2EE without application server)

If a solution seems to be too complicated,
then it means that a simpler alternative was missed.

Download

The Miniature Java Web Server includes most of functionality of real Web Servers including a servlet container capability. 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, it can be used as a regular web server for sites with low to medium load. I found also very convenient to ship a servlet based product including this server, so a user can start a product just after unwrapping. You can try a web site hosted on this server under Linux. This web server also works 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

Sometime at the end of 1998 I looked a web server with sources to debug some servlets. One of my findings was ACME Java Web Server. It was pretty good, but 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. After I just continued adding more features and providing bug fixes. The current version is mostly compatible with the latest servlet container  specification (2.5). 

Benefits

  • About 74Kb footprint (TJWS is the smallest one, like 5 times less in comparison 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 connections, clustering configuration is about of development
  • Perfect solution for web interfaced applications
  • Standard J2EE servlet deployment for .war packaged applications
  • Simple configuration, no hundreds of config parameters
  • flexible JSP support

 

Is it real 2.5?

Most of servlet specification 2.5 features are available for J2EE deployed applications. Annotation processing is about of development.

Tell me my size

Selecting or not J2EE deployment  gives an extra flexibility in a final size of a deployed application. Like for an embeddable or a mobile application is possible to use Java Personal Profile 1.x compatible  servlet container module. For less critical in size deployment is possible to use J2EE deployment module and JSP module. Note that  a standard JSP support is provided by GNU JSP 0.9. This version is very old and restrictive. So for contemporary JSP specification is possible to use GNU JSP 1.0 or Jasper. Base module, JSP, and J2EE deployment modules have sizes 71K, 20K, and 32K correspondingly. More advanced version of GNU JSP 1.0 provider has size 67K, and  Jasper's size is 580K.

Supported web.xml deployment tags

2.5 Deployment descriptor

Multiple URL patterns can be defined anywhere. Some other features are under consideration. Work on processing annotations in servlet code started..

Application with Web UI

Recently, a new type of application appeared on the market. After starting an application is launching a browser which represents its UI. This approach has many advantages and becomes more popular and wider used. The Miniature Java Web Server is a right tool for creation such kind of application. Download and double click JAR in Explorer or launch it from a terminal typing java -jar finesearch.jar, then point browser to http://localhost:8080/finesearch and enjoy the web interfaced application. Starting from version 1.21 TJWS includes a launcher of a .war packaged application from command line or a start script. The feature is very similar to used by Winstone.  Use:
java -jar webapplauncher.jar war_file_name [optional standard TJWS CLI parameters]
for example:
java -jar webapplauncher.jar "C:\Project Files\finesearch\finesearch_app\finesearch.war"
Note if extra command line arguments are not specified, then TJWS will try to discover them from cmdparams located in a working directory.
Version 1.22 and above makes launching Web UI application even more simpler. Web application .war can be packaged inside of TJWS .jar file allowing one click launch. To package web application .war with TJWS use target 'embedded' of 7Bee build tool and answer on few simple questions.  For example:
C:\Project Files\tjws>bee embedded
Launcher's been built.
Enter command line arguments for app [-nohup -p 80]? -p 80
Enter application .war file location? C:\Project Files\finesearch\finesearch_app\finesearch.war
As result finesearch.jar is created in lib directory which is launchable using java -jar finesearch.jar
When JDK 6 is used you can get it running in system tray, use javaw for JAR launching.

System tray menu will contain an item for going directly to an application with web UI (since 1.24).
Web interfaced applications also build on using pure JavaScript and ActiveX controls. However a light-weight  Java servlet container approach looks better from portability and security point of view.

J2EE without application server

TJWS gives a good possibility  to create enterprise class J2EE applications without an expensive and heavy weight application server. DemRog library will take care of SOA registry, MVC servlet framework with template based presentation layer, data persistence and much more. Check out a demo of a real application based on this approach.

How To?

Since TJWS has long history it supports as legacy way of  configuration and deployment servlets as a new .war based. The legacy configuration is based on property files, like servlets.properties and aliases.properties.  J2EE way is based on .war and config.xml files. When a legacy way used, the server can keep minimal configuration and run on JDK 1.2 or better. For J2EE deployment 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 auto deployment. J2EE way is quite simplistic and doesn't support live applications update, however can do that at startup time. server.xml isn't supported and most of server specific parameters have to be specified as command line arguments, or stored in flat file as cmdparams. All examples of startup scripts are presented in a distributive archive. Most of examples contain both ways of server configuration and application deployment. Note that deployment descriptor (web.xml) parameter display-name defines a context path of a deployed web application. If you want to have context path matching .war name then add system property tjws.wardeploy.warname-as-context set to yes. For command line it will look like -Dtjws.wardeploy.warname-as-context=yes . (Since 1.24) To prevent application update at startup time you need to remove corresponding .war from deployment directory. It gives also a way to deploy web applications without .war just manually create web app directory structure. Check section 'Application with Web UI' for more options of deployment and distribution of applications

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. Every line of the file specifies one alias entry starting from keyword from=webpath;dir=directory_in_filesysten_to_map, 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 alias name of CGI scripts directory.

e - provides session timeout in minutes and can be negative. Negative value won't start session cleaning thread and will use a 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; extra init parameters can be specified for JSP servlet; syntax of parameters is -class_name_perfix.param_name param_value; note that value can contain variables like %context% and %deploydir% substituted by actual values respectfully. Another substitution happens for %classloader% by a name of a servlet context attribute keeping an instance of a class loader used for a web application deployment (available from version 1.15). Version 1.22 and above introduced another variable %classpath% which substituted by class path used for loading servlet.

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

sp - persistence for sessions, TJWS is capable storing sessions data in a portable format and reload them between restarts or nodes of a cluster. Do not use this option if sessions contain sensitive, not serializable, 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.

z - defines max number of created threads in a thread pool used for servicing requests. 20 used when the parameter not defined. 0 or negative - do not use thread pool.

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

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

Running it as a service on NT/2000/XP

You can run the latest version of the server (>1.42/1.7)  as Windows service. File servservice.exe added to the distribution. I wrote this service for JDK 1.4. It works without a change for Java 5 and 6. 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 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. Use -nohup switch to avoid console read attempt. To get help line, run servservice.exe -help. Parameterless version of servservice.exe  is considered as a service.

Note that arg[0] which supposes to give a fully qualified name of a service executable on some versions Windows ((like XP) doesn't do that. For this reason you have to specify a fully qualified path as the last parameter of an installation command. There is no requirements to have servservice.exe in the same directory where TJWS is. Here is an example of an installation command:
servservice.exe -install "C:\Project Files\tjws" "C:\Project Files\gnujsp\lib\jspengine.jar" TinyJavaWebServer TinyJavaWebServer "C:\Project Files\tjws\servservice\Debug\servservice.exe"

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.

Run it on WindowsCE based PDA

A base TJWS runs perfectly on PDAs under IBM's J9 VM. Make sure that you installed Personal Profile 1.1 VM to your PDA following IBM's instruction. In this case you can run TJWS out of the box, just copying webserver.jar and servlet.jat to your PDA. Use tjws.lnk for starting a server. You may need to edit it first to accommodate with J9 installation and location of .jar files. Note that J2EE deployment requires Java 5, when Personal Profile 1.1 is JDK 1.4.2 compatible. So J2EE deployment can't be used with J9 and you can exclude war.jar from copying to PDA. You should edit manually servlet.properties and classpath to deploy servlets. I recommend to use command line option -Xoptionsfile of J9 to place class path in a separate file, otherwise you can have difficulties to start VM properly with long names in class path. I do not recommend to use ex Jeode VM with the latest TJWS, since Jeode is Personal Profile 1.0 compatible.

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 TJWS. Thanks JSSE for making that fairly easy. Here some tips how to install SSL support to the server.

There are two SSL supporting socket factories packaged with TJWS - Acme.Serve.SSLServerSocketFactory and rogatkin.web.DoubleHeadSocketFactory (available from v 1.17). First is recommended to use with core TJWS, when second with J2EE deployment module since it provides supporting http and https at the same time and requires Java 5. 7Bee script contains examples of usage both factories. To use first one type bee -Dsecure=true and for second bee -Ddoublehead=true. Additional command line parameters can be specified with each factory like :

  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
  10. ssl-port  SSL port (only for DoubleHeadSocketFactory)
  11. ssl-backlog backlog size (only for DoubleHeadSocketFactory)

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

You may also adding your own socket factory implementations. See the packaged socket factories as a reference implementation.

Jasper JSP provider integration

You can use Jasper JSP provider for servicing JSP pages inside an application. Since original Jasper is a bit bulky for TJWS taste, it's recommended to strip it to a manageable size.  TJWS distribution includes instructions about modifying, build, and connection of Jasper in file jasper.html of webroot directory.

Help wanted

I'm looking for developers to finish work on pending web.xml instructions and also adding tag library support. Another plan is adding SOAP/RPC support for easy SOA. SSI servlet is also waiting to be developed. There is no plan for EJB though.

Download

Please download (version 1.23 updated on 07/04/2006 )

You can download 1.24 preview from here to get bug fixes and more exciting features a bit earlier. Generally this version solves a problem of a deployment out of the box web applications that deployment descriptor includes namespace and xml schema attributes. It also supports multiple url patterns for servlets and filters.

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 7Bee 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. 

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.

Tested web applications

I use TJWS primary for my business, however I verified functionality of some popular web applications. Here is the list:

  1. Apache Slide (WebDav)
  2. jCVSWeb/jCVSServlet 1.41/1.01 (CVS web front-end)
  3. Pebble 2.0-2 (Blogger solution)
  4. DaveNPort 0.9.10 (Simba web front-end)

Version tracking notes

All version numbers restarted after rechecking sources in sourceforge CVS repository,  So, please forgive some version number discrepancy. 

CVS

SF.net doesn't reflect this project anymore due instability. Weekly build will be provided to get changes faster. Sorry for inconvenience.

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 code base and not supported anymore.

Sources

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

JVMs

TJWS was tested with most popular JVMs under Windows, Linux, and Solaris platforms and also on mobile platforms as Sharp Zaurus and Windows CE.  Sun, IBM, and GNU VMs are capable to run TJWS.

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 Tiny Java Web Server inherited BSD like license from the original code, check any source file for details.

Support

I provide support of the server on voluntary basis. However server is so simple and stable that requirements in supporting shouldn't ever happen. Since we are still humans, 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 a 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..

MediaChest 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

Refine your search result - a smart filter helping to narrow multi thousand result produced by popular search engines

Contact

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