The following are prerequisites for running the Sambar JavaEngine:

• Download and Install the Java2 SDK, Standard Edition (Version 1.4.1 or later) from Sun Micrososystems.
• Configure your PATH environment variable to include the jre/bin directory (java.dll is used). For 1.4 and later SDKs, you must include the jre/bin/server or jre/bin/hotspot (jvm.dll is used) in the PATH. (Note: For Linux users, configure LD_LIBRARY_PATH rather than PATH for the above variables.)
• Configure your CLASSPATH environment variable to include the jre/lib directory and jre/lib/rt.jar file. Note: See Setting CLASSPATH for details. Note: For JSP support, the jdk/lib/tools.jar directory must also be appended to the CLASSPATH.
• 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.

On Linux systems, the LD_LIBRARY_PATH and JAVA_HOME must be configured. The following is an example configuration (.bashrc):

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/j2sdk1.4.1/jre/lib/i386:/home/j2sdk1.4.1/jre/lib/i386/server;export LD_LIBRARY_PATH
JAVA_HOME=/home/j2sdk1.4.1;export JAVA_HOME
CLASSPATH=/home/j2sdk1.4.1/jre/lib/rt.jar:/home/j2sdk1.4.1/lib/tools.jar;export CLASSPATH


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

Servlet Aliases
By default, the /servlet/ URL element is used to indicate that the request references a servlet. It is sometimes desireable to reference the servlet directly, without the /servlet/ descriptor. The following example illustrates how to alias the Hello.java servlet using the config/mappings.ini file.

[servlet-aliases]
/Hello = Hello
/snoop-it = sysadmin.Snoop


By default, accessing the /servlets/Hello.java servlet required the URL http://localhost/servlet/Hello, whereas with the alias, the servlet can be directly accessed via http://localhost/Hello.

Apache/Jasper Support
The Apache/Jasper package is included with the Sambar Server JavaEngine. Simply configure your CLASSPATH environment variable to include the tools.jar file from the Sun JSDK and modify the config/mappings.ini file to add the following entry:

[servlet-aliases]
*.jsp = org.apache.jasper.servlet.JspServlet


The server must be restarted after making these modifications. Important! The JSP scratch directory maps to the "Tmp Directory" of the virtual host making the request. To avoid nameing conflicts, configure each virtual-host entry with it's own unique "Tmp Directory".

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, 1.3 and 1.4 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 =	720	The amount of time, in seconds, that idle sessions should be cached before being automatically logged out.
sessionCheckFrequency =	10	The duration, in seconds, between checks of the session cache for idle/expired sessions.
JSPTrace =	warning	The JSP trace level: debug | informational | warning | error | fatal
JSPLog =	path	The complete path to the JSP log for trace messages. If left blank, all trace information is output to stderr (you will need to use bin/serverd.exe to see messages).
[initParameters]
compiler =	builtin-javac	The compiler option for use with Java Server Pages.
development =	true | false	Is Jasper being used in development mode?
keepgenerated =	true | false	Do you want to keep the generated Java files around?
largefile =	true | false	Store HTML data in a JSP file separately rather than as constant strings.
enablePooling =	true | false	Determines whether tag handler pooling is enabled.
mappedfile =	true | false	Generate servlet that has print statement per line of JSP file (helpful for debugging).
sendErrToClient =	true | false	Display stack traces in the client's browser. If false, errors are only written to the server.log.
classdebugInfo =	true | false	Do you want to include debugging information in the class file?
checkInterval =	300	Background compile thread check interval in seconds.
reloading =	true | false	JSP reloading check?
classpath =		The classpath to use when compiling generated servlets. If not found, use the default server classpath.

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.

Is the Sambar Server J2EE compliant ?
No. The J2EE specification includes not only Java Server Pages and servlets, but Enterprise Java Beans and related specifications such as Java Messaging Service.

To be certified as a J2EE-compliant server, a platform must support all of the J2EE technologies, including EJB. To become J2EE-certified, products must pass Sun Microsystems' Certification Test Suite. Sambar Technologies has no plans to implement Enterprise Java Beans; SOAP and/or XML-RPC (which are being developed) appear to be significantly better solutions for the problems that EJBs attempt to address.

Tag Library Support
The Sambar Server JavaEngine supports tag libraries and configuration via the config/web.xml file. The following is an example config/web.xml file which specifies a simple tag library element:

<web-app>
<description>
web.xml file used to specify various JSP configuration information.
</description>
<taglib>
<tag-uri>/myjsp-taglib.tld</tag-uri>
<tag-location>d:/sambar52/servlets/myjsp-taglib.tld</tag-location>
</taglib>
</web-app>


JSP Compilation Warning!
The Java compiler leaks memory each time a class is compiled. Web applications containing many JSP files that are dynamically (re)compiled may trigger out of memory errors as a result of these memory leaks. The memory can only be freed by stopping the Sambar Server and then restarting it.

Tracking Memory Leaks
hprof can be used to trace memory usage/leaks within the JVM. To enable this functionality, add the following line to the javaeng.ini:

[jvmArguments]
Xrunhprof:heap=sites,depth=10,doe=y


Addition information is available at: http://java.sun.com/developer/onlineTraining/Programming/JDCBook/perf3.html.

SE Linux UnsatisfiedLinkError
Java native libraries on SE Linux may cause: UnsatisfiedLinkError: "cannot restore segment prot after reloc" According to Ken Martinek, this is to be caused by some java awt native libraries. The solution to the problem is to apply the following selinux label command: chcon -R -t texrel_shlib_t $JAVA_HOME/jre/