Java Servlets for MPE/iX

Mod_jserv is the add-on module to Apache that communicates with the servlet engine, JServ. It converts browser HTTP requests to servlet AJP requests then converts servlet AJP responses to HTTP responses and returns them to the client browser. Mod_jserv has a ".so" suffix because it is a Dynamic Shared Object (DSO), an NMXL on MPE. Mod_jserv is written in C and has the same structure as other Apache compiled-in modules. Because it is a DSO, it is loaded and run at Apache startup or restart.

This is the "servlet engine," a 100% pure java application that executes servlets. This servlet engine executes like a regular Java application with a static main method in class org.apache.jserv.JServ. This version of the servlet engine, Apache JServ 1.1, executes servlets that are compliant with JavaSoft's Java Servlet APIs, version 2.0. The servlet engine forwards AJP client request data to the requested servlet and then forwards the servlet response back to the AJP client.

This version of Java Servlets for MPE/iX uses the class definitions from Sun's Java Servlet Development Kit 2.0 (JSDK2.0). JSDK2.0 is a Sun product that can be downloaded for free from Sun's web site. For your convenience, the JSDK2.0 class definitions are installed as part of Java Servlets for MPE/iX in their complete and unmodified form. These servlet classes come packaged by Sun in a Java archive file, jsdk.jar. Any version of the servlet classes other than JSDK 2.0 (past, present, or future version) may not work with this release of Java Servlets for MPE/iX and should not be used.

The jsdk.jar class library file is installed in /APACHE/PUB/lib for standard Apache and in /APACHE/SECURE/lib for WebWise.

All servlets use the class definitions in jsdk.jar. Because the servlet engine is itself a servlet, the jsdk.jar file is also required for the servlet engine to run.

The JSDK2.0 API documentation is also distributed in its complete and unmodified form with your installation at http://yourhost.com/JSDK2.0/doc/apidoc. This includes:

Additional components of the JSDK2.0 are available by downloading the entire package from Sun's site at http://java.sun.com/products/servlet. The JSDK2.0 is not an HP product and is not supported by HP.

This is the first of three new configuration files. This configuration file contains directives for Apache only and is not read by the servlet engine. It contains directives which, for example, indicate whether mod_jserv.so should be loaded and whether the servlet engine will be run automatically or be manually started. Automatic launching of the servlet engine is not supported on MPE/iX. The ApJServManual directive should always be set to true:

ApJServManual on

The grammar for this file follows the grammar used by other Apache configuartion files:

DirectiveName value

This file is read once at Apache startup or restart.

This is the second of three new configuration files. This file contains all the properties required by the servlet engine. Some properties are passed to the Java Virtual Machine (JVM) and others include various security preferences, settings for internal communication between the servlet engine and the Apache web server, properties for enabling logging, and a list of all servlet zones and their respective property files.

The grammar for this file follows a grammar similar to Java property files:

property_name=value, value, ...

This file is read by both mod_jserv and by the servlet engine. It is loaded once at startup, so changes are available only after restart of the web server and of the JVM.

This is the third of three new configuration files. Each servlet zone requires its own properties file. The installation and configuration processes set up one servlet zone called "root" and its corresponding properties file called "root.properties". A properties file contains a list of servlet repositories for a specific zone. This is the location of the servlet class files for that zone. Any other settings that are specific to a zone must also be in the properties file. It also contains aliases and initialization arguments for the servlets in that zone.

Properties files use the same grammar as the jserv.properties file and are usually named using the zonename.properties syntax.

This file is read once by the servlet engine at startup.

The servlet installation job creates 3 sample configuration files in the directory conf/jserv. These sample files are derived from their corresponding default files for use on MPE. Copy these sample files to create your own configuration files. Make sure to log on first as MGR.APACHE:

:HELLO MGR.APACHE:xeq sh.hpbin.sys -Lshell/iX>cd /APACHE/SECURE/conf/jserv

or

shell/iX>cd /APACHE/PUB/conf/jservshell/iX>cp jserv.conf.sample jserv.confshell/ix>cp jserv.properties.sample jserv.propertiesshell/iX>cp root.properties.sample root.properties

Modify your conf/httpd.conf file by adding an include directive after the last AddModule directive in the module list. The included file, jserv.conf, contains a LoadModule directive for loading the mod_jserv.so library.

For WebWise Secure Web Server, the include should be added after mod_ssl.c as shown here:

shell/iX>cd /APACHE/SECURE/conf
shell/iX>cat httpd.conf
...
AddModule mod_unique_id.c
AddModule mod_so.c
AddModule mod_setenvif.c
<IfDefine>
AddModule mod_ssl.c
</IfDefine>

Include /APACHE/SECURE/conf/jserv/jserv.conf

For Standard Apache, the include should be added after mod_setenvif.c as shown here:

shell/iX>cd /APACHE/PUB/conf
shell/iX>cat httpd.conf
...
AddModule mod_unique_id.c
AddModule mod_so.c
AddModule mod_setenvif.c
 
Include /APACHE/PUB/conf/jserv/jserv.conf
...

The conf/jserv/jserv.conf file contains configuration directives for viewing servlet status once the servlet engine has started. To enable, replace "your.PC.com" with the IP address of your PC's browser (127.0.0.1 is equivalent to "localhost"). This feature should be enabled for trusted users only (i.e. the system administrator) and probably disabled on production systems. To disable this feature, remove your PC's address from the "allow from" directive.

shell/iX>cd /APACHE/SECURE/conf/jserv 
orshell/iX>cd /APACHE/PUB/conf/jserv 
shell/iX>cat jserv.conf 
...
<Location /jserv/>
SetHandler jserv-status 
 
order deny, allow
deny from all
allow from 127.0.0.1 your.PC.com
</Location>
...

The servlet engine, JServ, is started by streaming JSRV (for standard Apache) or JSRVS (for WebWise Secure Web Server). The servlet engine is stopped by streaming JSRVOFF (for standard Apache) or JSRVSOFF (for WebWise Secure Web Server).

Change the TZ variable for your local timezone in JSRV and JSRVOFF or in JSRVS and JSRVSOFF,

shell/iX>cd /APACHE/SECURE
shell/iX>cat ./JSRVS
!job jsrvs,mgr.apache,secure;pri=cs
!setvar TZ 'PST8PDT'
...
!eoj
 
shell/iX>cd /APACHE/SECURE
shell/iX>cat JSRVSOFF
!job jsrvsoff,mgr.apache,secure;pri=cs
!setvar TZ 'PST8PDT' 
...
!eoj 

JServ should never be terminated using the POSIX shell's kill command. Terminating it with kill prevents it from cleanly destroying all servlets.

To start WebWise Secure Web Server and the servlet engine,

:stream jhttpds.secure.apache
:stream jsrvs.secure.apache

To start standard Apache and the servlet engine,

:stream jhttpd.pub.apache
:stream jsrv.pub.apache

Starting the servlet engine also starts up the Java Virtual Machine (JVM) since the servlet engine itself is a servlet. Because the JVM is starting up, there will a short delay before the engine is running.

Successful installation and startup of the servlet engine can be verified by

For the first startup after installation, it is best to start Apache or WebWise Secure Web Server then check the conf/error_log and conf/mod_jserv.log files. This will verify that the web server has started successfully and was able to load the mod_jserv module. Mod_jserv.log is created at Apache startup, if it doesn't already exist. Next, start the servlet engine. Jserv.log is created when the servlet engine is started.

shell/iX>cd /APACHE/SECURE/logs
or
shell/iX>cd /APACHE/PUB/logs
shell/iX>tail error_log
shell/iX>tail mod_jserv.log
shell/iX>tail jserv.log

Once the servlet engine is running, you can view servlet status by calling the servlet status handler (the trailing slash is required),

http://your.host.com/jserv/ 

To run the example servlets,

http://your.host.com/servlets/Hello
http://your.host.com/servlets/IsItWorking 

To access the Jserv documentation,

http://your.host.com/jservdocs 

To stop WebWise Secure Web Server and the servlet engine,

:xeq sh.hpbin.sys "-c 'kill `cat /APACHE/SECURE/logs/httpd.pid`'"
:stream jsrvsoff.secure.apache 

To stop standard Apache,

:xeq sh.hpbin.sys "-c 'kill `cat /APACHE/PUB/logs/httpd.pid`'"
:stream jsrvoff.pub.apache

Java servlets on MPE follow the same rules and conventions as Java programs on MPE.

Any HP e3000 editor can be used to create a servlet file but, like Java programs, Java servlets must be in bytestream format. Servlets created with vi or using Samba from a PC will always be in bytestream format. Servlet files created using traditional HP e3000 editors such as EDIT/3000 and HP EDIT must be converted to bytestream using the tobyte utility. For information on tobyte, execute "man tobyte" in the POSIX shell to invoke the POSIX help facility.

The naming conventions for Java servlets follow those of Java programs:

The jsdk.jar servlet classes in the JSDK2.0 are required for proper servlet execution whether you write your own servlets or get them from another source. The jsdk.jar file contains the javax.servlet and javax.servlet.http packages. To view the list of classes in the jsdk.jar file, use the Java Archive Utility:

shell/iX>/usr/local/java/latest/bin/jar tvf /APACHE/SECURE/lib/jsdk.jar

or

shell/iX> /usr/local/java/latest/bin/jar tvf /APACHE/PUB/lib/jsdk.jar

For servlet API documentation and examples, use the following URL on your own server:

http://yourhost.com/JSDK2.0/doc/apidoc.

Servlets can be written to call any of the Java APIs available to Java applications. Servlets use the Java standard extension classes in the packages javax.servlet (the basic Servlet framework) and javax.servlet.http (extensions of the servlet framework for servlets that answer HTTP requests) that are in the jsdk.jar file. Since servlets are written in Java and follow a standard framework, they are portable between operating systems.

Here is an example of a simple servlet.

File: HelloWorld.java
 
import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
/** * This is a simple example of an HTTP Servlet.  It responds to the GET
 * and HEAD methods of the HTTP protocol.
 */public class HelloWorld extends HttpServlet
{     public void doGet (HttpServletRequest request,
       HttpServletResponse response)         throws ServletException, IOException        {            PrintWriter out;            String title = "Hello World Servlet";            // set content type and other response header fields first            response.setContentType("text/html");            // then write the data of the response            out = response.getWriter();            
            out.println("<HTML><HEAD><TITLE>");
            out.println(title);
            out.println("</TITLE></HEAD><BODY bgcolor=\"#FFFFFF\">");
            out.println("<H2><Hello, World!<br>");
            out.println("</BODY></HTML>");
            out.close();        }}

The above is an example of an HTTP servlet since it extends the HttpServlet class. For HTTP servlets, an HTTP method (i.e., GET) is generally handled by a corresponding Java method (i.e. doGet). The method should return a response which contains a body and header field(s) which describe the body. In this example, the doGet method in the HttpServlet base class is overridden. The body is the HTML output and the header field is the Content-Type "text/html." This is an example of a static servlet that returns the same output every time it is called.

The class path is where the JVM looks for class definitions. The jsdk.jar file, which contains servlet class definitons, should be specified to the JVM by adding its path to the CLASSPATH environment variable. CLASSPATH can be set at the command line or in a profile file:

shell/iX>export CLASSPATH=/APACHE/PUB/lib/jsdk.jar:$CLASSPATH

or

shell/iX>export CLASSPATH=/APACHE/SECURE/lib/jsdk.jar:$CLASSPATH

Servlets are compiled using the Java compiler, javac. The path to the javac binary can be fully qualified or the PATH variable can be modified to include it. PATH can be set at the command line or in a profile file.

shell/iX>/usr/local/java/latest/bin/javac HelloWorld.java

or

shell/iX>export PATH=/usr/local/java/latest/bin:$PATH	
shell/iX>javac HelloWorld.java

If you are planning to compile multiple servlets, you may want to set the PATH and CLASSPATH variables in the .profile file for MGR.APACHE or in the system-wide /etc/profile.local file. To create a new .profile file with these variables for MGR.APACHE:

:HELLO MGR.APACHE
:XEQ SH.HPBIN.SYS -L
shell/iX>echo export PATH=/usr/local/java/latest/bin:\$PATH > .profile
shell/iX>echo export CLASSPATH=/APACHE/PUB/lib/jsdk.jar:\$CLASSPATH >> .profile
shell/iX>. ./.profile

The sample configuration files are set up to execute servlets from the /APACHE/PUB/servlets directory for standard Apache and from /APACHE/SECURE/servlets for WebWise. This is where your servlet .class files must reside. This directory is a servlet repository in the " root" zone and is configured in the root.properties file:

repositories=/APACHE/SECURE/servlets 

To run the servlet HelloWorld from the servlets repository, enter its URL in your web browser:

http://yourhost.com:port/servlets/HelloWorld

or

http://yourhost.com:port/servlet/HelloWorld

"HelloWorld" is the name of the servlet to run and "servlets" and "servlet" are the mount points for the "root" zone. Zone mount points are specified in the jserv.conf file using the ApJServMount directive. Here are the ApJServMount values set in the jserv.conf.sample file:

ApJServMount /servlets /root

ApJServMount /servlet /root

Mounting maps a URL to a zone. With the above mounts , requests to a URL starting with /servlets or /servlet will be handled by the servlets in the zone "root."

Servlets can be passed input in a manner similar to CGI. To run the servlet "MyServlet" with an address input value, the URL would be,

http://yourhost.com:port/servlets/MyServlet?address=foo@bar.com