How To run Servlets with Pi3Web: Configuration

A valid Java 2 runtime environment has to be installed on the machine, where the Pi3Web is installed as a Servlet engine. This could be done by installing either the JDK 1.2.2 or the JRE 1.3.1. Both are available as download packages from the SUN web site.

The Pi3Web 2.0 package for Win32 has to be installed and the WebServer should be ready to use so far.

2.2 Quick Start for Windows NT

The Pi3Web server should be stopped.
Unzip the Pi3Servlet-x86Win32-2_0_0-beta2.exe archive from Sourceforge or the Pi3Web website.
Run the installer and adjust the path to your Pi3Web installation folder (usually c:\Pi3Web).
Optionally adjust the JvmOption java.class.path and the JvmOption java.library.path in Servlet.cnf accordingly to your JDK/JRE installation-
Start your server using the Servlet.pi3 configuration i.e. from the command line by typing Pi3 ../Conf/Servlet.pi3 when your current directory is ./bin.
Try to call the following test page and to run the Servlet tests.

2.3 Details

Contents of Servlet package

The archive Pi3Servlet-x86Win32-2_0_0-beta2.exe contains:

.\bin\Servlet.dll - The shared library, which contains the Servlet container and the Servlet and JSP handlers
.\bin\Servlet.jar - a Java archive containing the javax.servlet.* interface classes of the Servlet API 2.1
.\bin\Pi3Servlet.jar - a Java archive containing the org.pi3.servlet.* package with the implementation classes of the Servlet API 2.1 and the sample Servlets class files
.\bin\Pi3ServletJNI.dll - The shared library, which contains the native methods (JNI) of the org.pi3.servlet.* classes
.\Conf\Servlet.cnf - The configuration include file which contains the class definitions for the container and handler object, the container object with configuration parameters and the prototype handler objects
.\Conf\Servlet.pi3 - a configuration file, which contains a complete Pi3Web server configuration to run Servlets together with static contents and CGI programs
.\Pi3Docs\Extras\Servlets.html - This document
.\devel\Servlets\*.java - The sources of the sample Servlets

The above listed path names are relative to your Pi3Web installation folder.

Configuration settings

Servlet Container parameters

JvmNumber - Pi3Web supports currently only one JVM per container. The default value, if this parameter is omitted is also one single JVM
JvmOption - This parameter occurs multiple times. The values are given to the JVM as startup options. This has to be used to set the class~ and the library path. For details refer to your JDK documentation
JvmIgnoreUnrecognized - Optional parameter, to let the JVM ignore unregognized options, which are given as JvmOption parameters. If not set, the JVM initialization will fail, if a option is unrecognized
JvmLocalReferences - The number of reserved resources for local references. If exceeded, the JVM will complain warning messages but silently try to allocate more local references or a fatal error will occur
LogFile - The relative or absolute path and logfile name for the servlet container. The container and also the individual Servlets will write their log output to this file
Expression -The evaluated expression is printed at the begin of a certain log line. This is used by Servlet logging at request time, because a HTTP object must be present to evaluate the Pi3Expressions
OpenMode - Either "c" to create a new logfile at server startup or "a" to append to an existing file
DocBase - The document root of the Servlet context. All physical paths, which a Servlet can request with certain Servlet API ServletContext methods like getRealPath() are relative to this path

Servlet/JSP parameters

Currently Servlet and JSP objects share the same configuration parameters.

Context - The Container object, wherein the Servlet will be created. Currently only one context is allowed.
ClassName - The class name of the Servlet. If omitted, the class name will be taken from request line.
ServletName - descriptive name for Servlet, not used in the current implementation of Servlet API 2.1
Init - One ore more initialization parameters, which are given to the ServletConfig object to be used by the Servlet during its init method. The format of a single init parameter must be "key=value"

This is a simplified example of Servlet.cnf:

        <Library>
                Name Servlet
                POSIXPath ./libServlet.so
                Win32Path Servlet.dll
        </Library>
 
        <Class>
                Name ServletContainerClass
                Type LogicExtension
                Library Servlet
                OnClassLoad ServletContainer_onClassLoad
                Constructor ServletContainer_constructor
                CopyConstructor ServletContainer_copyConstructor
                Destructor ServletContainer_destructor
                Execute ServletContainer_execute
        </Class>
 
        <Object>
                Name ServletContainer
                Class ServletContainerClass
                JvmNumber 1
                JvmOption "-Djava.compiler=NONE"
#               JvmOption "-verbose:jni"
                JvmOption "-Djava.class.path=servlet.jar;Pi3Servlet.jar"
                JvmOption "-Djava.library.path=."
#               JvmIgnoreUnrecognized
                JvmLocalReferences 128
                LogFile "../Logs/servlet.log"
                Expression "[$t|$P|$k|$T] "
                OpenMode "a"
                DocBase ".\WebRoot"
        </Object>
 
        <Class>
                Name ServletClass
                Type LogicExtension
                Library Servlet
                OnClassLoad HandlerBaseServlet_onClassLoad
                Constructor Servlet_constructor
                CopyConstructor HandlerBaseServlet_copyConstructor
                Destructor HandlerBaseServlet_destructor
                Execute HandlerBaseServlet_execute
        </Class>
 
        <Object>
                Name Servlet
                Class ServletClass
                Context ServletContainer
        </Object>
 
        <Class>
                Name JspClass
                Type LogicExtension
                Library Servlet
                OnClassLoad HandlerBaseServlet_onClassLoad
                Constructor Jsp_constructor
                CopyConstructor HandlerBaseServlet_copyConstructor
                Destructor HandlerBaseServlet_destructor
                Execute HandlerBaseServlet_execute
        </Class>
 
        <Object>
                Name Jsp
                Class JspClass
                Context ServletContainer
        </Object>

This is a simplified example of Servlet.pi3:

#!../bin/Pi3
 
include ../Conf/Servlet.cnf
 
<Object>
        Name Start
        Class FlexibleHandlerClass
        ...
        Mapping Condition="&regexp('*/servlet/*',$U)" ServletMapper \
From="/servlet/" To="/servlet/"
        ...
</Object>
 
<Object>
        Name HTTPLogicObject
        Class HTTPDispatcherClass
        ...
        Handlers Start Scripts WinScripts FastCGIScripts Servlets Default
        ...
</Object>
 
<Object>
        Name Servlets
        Class FlexibleHandlerClass
        Condition "&cmp(&dblookup(response,string,ObjectMap),Servlet)"
        CheckPath ReturnCode ReturnCode=COMPLETED
        CheckAccess ReturnCode ReturnCode=COMPLETED
        CheckType ReturnCode ReturnCode=COMPLETED
        Handle Condition="&regexp('*/SessionServlet*',$z)" Servlet ClassName="org.pi3.servlet.samples.SessionServlet"
        Handle Condition="&regexp('*/DispatchServlet*',$z)" Servlet ClassName="org.pi3.servlet.samples.DispatchServlet"
        Handle Condition="&regexp('*/org.pi3.servlet.samples.*',$z)" Servlet Init="Key1=Value1" Init="Key2=Value2"
</Object>
 
<Object>
        Name ServletMapper
        Class PathMapperClass
        CaseSensitive "No"
        PathInfo "Yes"
        Action "&dbreplace(response,string,ObjectMap,Servlet)"
</Object>

Enhanced tips

You don't need servlet.jar if you've already installed the JSWDK-1.0.1 (Java Server Web Development Kit) by SUN. But servlet.jar must be in your CLASSPATH anyway.
Servlet logging could be disabled by omitting the LogFile parameter of the ServletContainer object in Servlet.cnf.
A Servlet could be loaded at runtime by omitting the ClassName parameter. In this case the part of the URI after the mapped Servlet path must be a valid class name (may be including a package name, i.e. /servlet/org.pi3.servlet.samples.HelloServlet, where /servlet/ is the mapped path).

2.4 Development Environment

To build the source packages it is important to adjust the respective settings with yourd JDK paths. This is also required to change the development environment from one JDK version to another.

Win32

Open the "Properties" dialog of the MSVC projects Servlet.dsp and ServletJNI.dsp. Adjust the path settings for the compiler include and linker library search paths in accordance with your JDK installation.

Linux

Either set the required environment in your shell profile or run make in the ./Source/Servlet directory with the following trailer:

#!/bin/sh
export JAVA_HOME=/usr/local/jdk1.3.1
export CLASSPATH=$JAVA_HOME/jre/lib:$JAVA_HOME/jre/lib/Pi3Servlet.jar:\
$JAVA_HOME/jre/lib/servlet.jar
export LD_LIBRARY_PATH=.:$JAVA_HOME/jre/lib/i386:$JAVA_HOME/jre/lib/i386/Server:\
$JAVA_HOME/jre/lib/i386:$JAVA_HOME/jre/lib/i386/native_threads:$LD_LIBRARY_PATH
make

2.5 Troubleshooting

Most problems arise due to incorrect Java CLASSPATH settings. Dependant on the the affected Java classes there will be corresponding startup or runtime problems.

General you've a number of options to detect the reason of a certain problem:

to increase JVM verbosity level (uncomment JvmOption "-verbose:jni" in Servlet.cnf
to have a close look to the ./logs/Servlet.log
to observe the server startup console messages

Because the server starts an own JVM (Java Virtual Machine) with an own environment, which is configured in Servlet.cnf, the machine's original Java runtime environment settings aren't relevant.

The server won't startup using Servlet.pi3

Some of the probably errors at startup time are

libjvm.so, libhpi.so or other Java runtime library not found (Linux only) - a console message shows you, which library couldn't be loaded. The LD_LIBRARY_PATH environment variable must contain the path to this libraries (the configuration for JRE 1.2.2 has to be made accordingly):

export JAVA_HOME=/usr/local/jdk1.3.1
export LD_LIBRARY_PATH=.:$JAVA_HOME/jre/lib/i386:$JAVA_HOME/jre/lib/i386/Server:\
$JAVA_HOME/jre/lib/i386/native_threads:$LD_LIBRARY_PATH

Container class not found - If the server complains that one of the container objects (Servlet context, config or DefJspFactory) couldn't be loaded at startup time, the Pi3Servlet.jar is probably not in the CLASSPATH. Check this in Servlet.cnf.
Native method of container class not found - a JNI console message shows you, which native method of a class couldn't be loaded. Check the JvmOption java.library.path in Servlet.cnf, if the location of the library Pi3ServletJNI.dll is accordingly.
Servlet class couldn't be found - The servlet engine tried to load a Servlet but can't find the respective class file. Check, if the file exists and is in the CLASSPATH. Check, if the class name you entered in the used configuration file is a valid Servlet class name (may be including a package name).
Servlet exception - if an exception is raised in the Servlet code or in a object instantiated by the Servlet, this is probably a bug in your Servlet either in the constructor or the init method. Check this, recompile the Servlet, replace the .class file and restart the Pi3Web server.

The server won't process a certain Servlet URL

Some of the probably errors at request time are

Wrong URL mapping - check your PathMapper configuration and the conditions of the respective handler objects in the used server configuration file. Switch on the Pi3Web debug log to see how the request is processed.
Class not found error at runtime - The servlet engine attempts to load a Servlet at runtime but can't find the appropriate class file. Check, if the file exists and is in the CLASSPATH. Check, if the URL you entered in the browser contained the valid Servlet class name (may be including a package name).
Servlet exception - if an exception is raised in the Servlet code or in a object instantiated by the Servlet, this is probably a bug in your Servlet, probably in one of the methods called by the service() method, like doGet() or doPost(). Check this, recompile the Servlet, replace the .class file and restart the Pi3Web server.
Method not found exception - if a certain method of objects representing the Servlet interface (i.e. request, response) could not be found, check, if this method was introduced with Servlet API 2.2. Pi3Web does only support Servlet API 2.1. In this case you could try to modify your Servlet to be API 2.1 compliant.
Other Java exception - if an exception is thrown outside the Servlet objects or not in an object instantiated by the Servlet, probably a Servlet engine bug. Report the detailed error description including the error stack trace to zimpel@t-online.de.

2. Configuration

2.1 Preferences