The following are prerequisites for running the Sambar JavaEngine:

• Download and Install the Java2 Runtime Environment (Version 1.2.1 or later) from Sun Micrososystems
• Configure your PATH environment variable to include the jre/bin and jre/bin/classic directories (java.dll jvm.dll etc. are used).
• Configure your CLASSPATH environment variable to include the jre/lib directory and jre/lib/rt.jar file. Note: See Setting CLASSPATH for details.
• Configure Enable JavaEngine to true in the Sambar Server config.ini file

Important: If you are running the Sambar Server as a service, the PATH and CLASSPATH environment variables should be configured as System Variables. Kevin Gillespie provides the following configuration help:

1. Login with administrator rights.
2. Right click on the My Computer Icon on your desktop
3. Click on Properties
4. Choose the Environment Tab
5. Highlight (click on) any variable under the system variable heading. Note: this will NOT change the highlighted variable, it will ADD a NEW variable.
6. At the bottom of the Environment page you will see the settings for the variable you highlighted in the system variables box
7. Highlight the variable box and type classpath
8. Highlight the value box and type the location of your jre\lib directory (i.e. c:\jre\lib\)
9. Click the SET button
10. Click the APPLY button
11. Click the OK button
12. Classpath should now be set as a system variable, to check this, exit the properties window and repeat steps 2,3, and 4 you should now see classpath in the system variables box. Note: you might have to reboot your system for these settings to take effect.

After completing the above steps, the Sambar Server load the Java VM engine at startup. IMPORTANT!!! The bin/serverd.exe is a WIN32 console application that may be useful in diagnosing Java and/or CLASSPATH mis-configurations should the Sambar Server fail to start. To run this applicant, open a DOS shell and CD to the Sambar Server installation directory. Then execute the serverd shell wrapper for the Sambar Server by typing: bin/serverd.

You can verify that the JavaEngine is enabled is enabled from the System Administration forms. The left-hand side of the administration form contains the status of all Sambar Server Services. One common mistake when configuring the Sambar Server for Java servlet or JSP support is to fail to enable the JavaEngine.

The Basics
The /servlets directory is where you put your servlets during development and deployment. All servlets found in this directory are dynamically reloaded if they are changed. Important: If you want to dynamically class reloading DO NOT put the Sambar /servlets directory in your CLASSPATH.

A servlet is loaded once when it is called. The servlet is not loaded again until it changes. The servlet stays resident in memory allowing static or persistent information to be shared across multiple invocations of the servlet. The determination that a servlet has changed is based on the date of the .class file of the servlet; the date of the supporting class files does not have any affect on the reloading of the servlet. You can force a reload of your servlet's supporting classes (if the supporting classes are also in the Sambar /servlets directory) by modifying the timestamp of the servlet class file (i.e. recompile the servlet .java file.)

GNUJSP Support
The GNUJSP package can be used with the Sambar Server JavaEngine. Simply place the gnujsp10.jar file in the Sambar Server lib directory and configure your CLASSPATH environment variable to include the tools.jar file from the Sun JSDK as well as the path to the GNUJSP installation directory so the w3c class files can be loaded (these can be placed in the Sambar Server lib directory to be loaded automatically. In addition, the following should be added to the config/mappings.ini:

[servlet-aliases]
*.jsp = org.gjt.jsp.JspServlet


The server must be restarted after making these modifications.

Architecture
The JavaEngine is an in-process implementation. If the Enable JavaEngine is set to true in the config.ini file, the Sambar Server will dynamically load the bin/sambarje.dll module file at startup and launch the Java VM. The Sambar JavaEngine loads the lib/servlets.jar and lib/javaeng.jar at initialization; these packages contain the Sun Java Servlet reference APIs and Sambar Servlet implementation respectively (Note: Source code to the Sambar Servlet implementation is included in the lib/javaeng.jar file. To un-jar this file and view the code use: jar -xvf javaeng.jar).

By running Java servlets in-process, the Sambar Server can pass a native server thread directly to the JavaVM to continue running the servlet request. This results in a significantly faster servlet implementation, but also subjects the Sambar Server to memory leaks and other process vulnerabilities of the Java VM.

Important! A bug in the Java 1.2 VM prevents the VM from unloading. As a result, the only way to reload Java system classes (those found in your CLASSPATH) is to stop and then start the Sambar Server. The Sambar Server restart mechanism is not able to unload the Java VM.

CLASSPATH
The class path tells Java VM where to find third-party and user-defined classes. The Sambar Server passes the CLASSPATH environment settings to the JavaVM when it is initialized. In addition, all .jar and .zip files found in the Sambar Server lib directory are appended to the CLASSPATH environment variable (by default, this is the location of the javaeng.jar file.)

The class path should be set by setting the CLASSPATH environment variable:

C:> set CLASSPATH=path1;path2...

Each path ends with a filename or directory depending on what you are setting the classpath to:

• For a .zip or .jar file that contains .class files, the path ends with the name of the .zip or .jar file.
• For .class files in an unnamed package, the path ends with the directory that contains the .class files.
• For .class files in a named package, the path ends with the directory that contains the "root" package (the first package in the full package name).

If your CLASSPATH environment variable has been set to a value that is not correct, or if your startup file or script is setting an incorrect path, you can unset CLASSPATH by using:

C:> set CLASSPATH=

This command unsets CLASSPATH for the current command prompt window only. You should also delete or modify your startup settings to ensure that you have the right CLASSPATH settings in future sessions.

If the CLASSPATH variable is set at system startup, the place to look for it depends on your operating system:

• Windows 95/98 Examine autoexec.bat for the set command.
• Windows NT Open the Control Panel, select System, click the Environment tab and, in the User Variables section, examine the CLASSPATH variable.

javaeng.ini

[javaeng]
Verbose =	true | false	Boolean indicating whether Java servlet actions should be traced to the server.log file. Note: When verbose is enabled, numerous errors (i.e. JNI local ref creation exceeded capacity) are written to the server.log; these do not appear to have a material impact on the server.
Servlet Extension =	/servlet/	The default URL alias that is used to indicate that the request is a Servlet.
Servlets Directory =	/servlets	The location of the servlets to be executed.
Preload GenericServlet =	servlet-name	If specified, the servlet that should be loaded at server startup. This must be a GenericServlet. A sample can be found in /servlets/Preload.java
[properties]
traceServlets =	true | false	Boolean indicating whether Java servlet execution should be traced to the server.log file.
sessionTimeout =	180000	The amount of time, in seconds, that idle sessions should be cached before being automatically logged out.
sessionCheckFrequency =	5000	The duration, in seconds, between checks of the session cache for idle/expired sessions.
[initParameters]
compiler =	builtin-javac -classpath %classpath%;%scratchdir% -d %scratchdir% -deprecation %source%	The compiler option for use with GNUJSP.

Additional user-defined properties can be specified by adding entries to the [properties] section of the javaeng.ini file. The properties can be retrieved using the System.getProperty() method.

Servlets
Servlets are loaded and initialized when the servlet is first run. Upon shutdown of the Sambar Server the server removes the servlet. In addition, all servlets are removed when the server's class loader is re-initialized; the class loader is re-initialized any time a servlet is reloaded due to a code modification.

When the server loads a servlet, it runs the servlet's init method. The server calls the init method once when the server loads the servlet, and will not call this method again unless the server is reloading the servlet. The server will not reload a servlet until after the server has destroyed the servlet by calling the destroy method.