Chapter 3   Using Servlets


This chapter discusses how to enable and configure servlets in iPlanet Web Server 6.0. The sections in this chapter are:

• What Does the Server Need to Run Servlets?

• Using the User Interface

• Enabling Servlets

• Making Servlets Available to Clients

• The <SERVLET> SHTML Tag

• Servlet Output

• Configuring JVM

• Maximizing Servlet Performance

What Does the Server Need to Run Servlets?

---

iPlanet Web Server 6.0 includes all the files necessary for developing Java Servlets. The servlet.jar file is in the iPlanet Web Server 6.0 installation directory at:

server_root/bin/https/jar

When compiling servlets, make sure the servlet.jar file is accessible to your Java compiler. Include the servlet.jar file in your CLASSPATH.

iPlanet Web Server 6.0 includes the Java Runtime Environment (JRE) but not the Java Development Kit (JDK) due to licensing restrictions. The server can run servlets using the JRE only or the JDK. For information about installing the JDK, see "What Does the Server Need to Run JSP?."

Using the User Interface

---

For information about using the user interface to specify settings for servlets, see the following topics in the online help.

This page is located in the Web Server Administration Server on the Global Settings tab.

• The Configure JRE/JDK Paths Page

These pages are located in the Server Manager on the Java tab.

• The Enable/Disable Servlets/JSP Page

• The Configure JVM Attributes Page

• The Delete Version Files Page

This page is located on the Virtual Servers tab in the Class Manager. (To open the Class Manager, select the Manage Classes page on the Virtual Server Class tab in the Server Manager, select a class from the list, then select the Manage button.)

• The Java Web Apps Settings Page

Enabling Servlets

---

To enable servlets, select the Java tab in the Server manager, then select the Enable/Disable Servlets/JSP tab. Check the Enable Java Globally box to enable servlets for the entire server. Check the Enable Java for Class box to enable servlets for a single virtual server class. You cannot enable servlets for a class unless Java is globally enabled. By default, Java is globally enabled and enabled for each virtual server class.

Making Servlets Available to Clients

---

You can make servlets accessible to clients in one of these two ways:

• Include the servlets in web applications and deploy those web applications. How to do this is described in Chapter 2 "Web Applications."

• Configure the servlets in the default virtual server. This is provided for backward compatibility with iPlanet Web Server 4.x. How to do this is described in Chapter 8 "Legacy Servlet and JSP Configuration."

The <SERVLET> SHTML Tag

---

iPlanet Web Server 6.0 supports the <SERVLET> tag as introduced by Java Web Server. This tag allows you to embed servlet output in an SHTML file. No configuration changes are necessary to enable this behavior. If SSI and servlets are both enabled, the <SERVLET> tag is enabled.

The <SERVLET> tag syntax is slightly different from that of other SSI commands; it resembles the <APPLET> tag syntax:

<servlet name=name code=code codebase=path iParam1=v1 iParam2=v2> <param name=param1 value=v3> <param name=param2 value=v4> . . </servlet>

If the servlet is part of a web application, the code parameter is required and other parameters are ignored. The code parameter must include:

• The value of the url-pattern element defined in the web.xml file for the web application. For more information about web.xml, see the Servlet 2.2 API specification:

  http://java.sun.com/products/servlet/index.html

• The value of the uri attribute defined in the web-apps.xml file for the web application. For more information about web-apps.xml, see Chapter 2 "Web Applications."

For example, if you wanted to include the following in your SHTML file:

<servlet name=pparams code="/PrintApp/PrintParams">
</servlet>

you would need to include the following in your web-apps.xml file:

<web-app uri="/PrintApp" dir="/iws60/https-server.iplanet.com/acme.com/webapps/PrintApp"/>

You would also need to include the following in your web.xml file:

<servlet>
   <servlet-name> pparams </servlet-name>
   <servlet-class> PrintPackage.PrintParams </servlet-class>
</servlet>
<servlet-mapping>
   <servlet-name> pparams </servlet-name>
   <url-pattern> /PrintParams </url-pattern>
</servlet-mapping>

You must also include any servlet initialization parameters in the web.xml file.

For legacy (iPlanet Web Server 4.x) servlets, the code parameter specifies the .class file for the servlet and is required. The codebase parameter is required if the servlet is not defined in the servlets.properties file and the .class file is not in the same directory as the HTML file containing the <SERVLET> tag. Legacy servlets must be configured in the default virtual server and do not require a web.xml file.

For more information about SSI commands, see the Programmer's Guide for iPlanet Web Server.

Servlet Output

---

When iPlanet Web Server is started in the background, which it is by default, the System.out and System.err output of servlets are not sent to the web server's error log, because servlets are external to iPlanet Web Server.

On Unix, you can modify your server_root/https-server_id/start file to run iPlanet Web Server in the foreground or to redirect servlet output. First enter the following command from the server_root/https-server_id directory:

./start -shell

This command puts you in the server_root/bin/https/bin directory. Then enter the following command:

./ns-httpd -d server_root/https-server_id/config

On NT, you can run iPlanet Web Server in the NT console, and thus in the foreground, by including the following line in the magnus.conf file:

Init fn="nt-console-init" stdout=console stderr=console

Configuring JVM

---

If necessary, you can configure parameters for JVM either by using the Java>Configure JVM Attributes page in the Server Manager interface, or by editing jvm12.conf. For more information about JVM settings, see Appendix C "JVM Configuration."

The default settings in iPlanet Web Server for JVM are suitable for running servlets. However, there may be times when you want to change the settings. For example, if a servlet or bean file uses a JAR file, you can add the JAR location to the JVM classpath.

Maximizing Servlet Performance

---

Consider the following guidelines for improving servlet performance:

• The jvm12.conf file has a configuration parameter, jvm.stickyAttach. Setting the value of this parameter to 1 causes threads to remember that they are attached to the JVM, thus speeding up request processing by eliminating AttachCurrentThread and DetachCurrentThread calls. It can, however, have a side-effect: recycled threads which may be doing other processing can be suspended by the garbage collector arbitrarily.

  Thread pools can be used to eliminate this side effect for other subsystems. For more information about thread pools, see the iPlanet Web Server Administrator's Guide.

• Increase the front-end thread stack size in magnus.conf (via the StackSize directive), or the respective pool stack size parameter if you're using thread pools. For more information, see the NSAPI Programmer's Guide for iPlanet Web Server.

• Increase the heap size to help garbage collection: jvm.minHeapSize or maxHeapSize or the Configure JVM Attributes page.

• Ensure that your jvm.classpath is short (if you don't need some of the examples). You can set jvm.include.CLASSPATH=0 so it won't inherit the CLASSPATH environment variable.

• Sometimes, iPlanet Web Server 6.0 may run out of stack space if applications use deep recursion when a JIT compiler is enabled, especially on UNIX platforms where the default stack size is small, or in any cases where very complex JSP pages are used.

  You can set the stack space using the StackSize directive in the magnus.conf file. For more information, see the NSAPI Programmer's Guide for iPlanet Web Server.

• The session ID generator, which is used for servlet sessions, employs cryptographically strong unique random number generation algorithms. This may present a performance problem on older, slow machines. For more information, see Chapter 6 "Session Managers."

  
  

  ---

  Note	When running an SSL server without Java, you can improve performance by enabling SmartHeap in the server's start script. However, SmartHeap is not compatible with Java.

  ---