Netscape NETSCAPE ENTERPRISE SERVER 6.1 - PROGRAMMER GUIDE TO... Manual

Programmer’s Guide to Servlets
Netscape Enterprise Server
Version 6.1
April 2002 (Draft)

Netscape Communications Corporation ("Netscape") and its licensors retain all ownership rights to the software programs offered by
Netscape (referred to herein as "Software") and related documentation. Use of the Software and related documentation is governed
by the license agreement for the Software and applicable copyright law.
Your right to copy this documentation is limited by copyright law. Making unauthorized copies, adaptations orcompilation works is
prohibited and constitutes a punishable violation of the law. Netscape may revise this documentation from time to time without
notice.
THIS DOCUMENTATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL NETSCAPE BE
LIABLE FOR INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY KIND ARISING FROM ANY
ERROR IN THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION ANY LOSS OR INTERRUPTION OF BUSINESS,
PROFITS, USE, OR DATA.
The Software and documentation are copyright © 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002 Netscape
Communications Corporation. All rights reserved.
This product includes software developed by Apache Software Foundation (http://www.apache.org/). Copyright (c) 1999 The
Apache Software Foundation. All rights reserved.
This product includes software developed by the University of California, Berkeley and its contributors. Copyright (c) 1990, 1993,
1994 The Regents of the University of California. All rights reserved.
Netscape and the Netscape N logo are registered trademarks of Netscape Communications Corporation in the United States and
other countries. Other Netscape logos, product names and service names are also trademarks of Netscape and may be registered in
some countries. Sun, Sun Microsystems, and the Sun logo, iPlanet, and the iPlanet logo are trademarks or registered trademarks of
Sun Microsystems, Inc. in the United States and other countries. Other product and brand names are trademarks of their respective
owners.
The downloading, exporting, or reexporting of Netscape software or any underlying information or technology must be in full
compliance with all United States and other applicable laws and regulations. Any provision of Netscape software or documentation
to the U.S. government is with restricted rights as described in the license agreement for that Software.

3
Contents
AboutThisBook ................................................................7
WheretoFindRelatedInformation ........................................................ 8
Chapter 1 Servlets and JavaServer Pages ........................................11
WebApplications ...................................................................... 11
Servlets ............................................................................... 12
JavaServerPages ....................................................................... 12
Chapter 2 WebApplications....................................................15
WebApplicationStructure .............................................................. 15
DynamicReconfiguration ............................................................... 16
web.xmlClarifications .................................................................. 17
login-config......................................................................... 17
security-constraint................................................................... 17
session-timeout ..................................................................... 17
Theweb-apps.xmlFileandVirtualServers ................................................ 18
TheDefaultContextforaVirtualServer ................................................ 18
Exampleserver.xmlFile .............................................................. 18
Exampleweb-apps.xmlFile........................................................... 20
web-apps.xmlElementReference...................................................... 21
auth-native ......................................................................... 21
class-loader......................................................................... 22
description ......................................................................... 22
form-login-session................................................................... 22
init-param .......................................................................... 23
jsp-servlet .......................................................................... 23
param-name ........................................................................ 24
param-value ........................................................................ 24
parameter-encoding ................................................................. 24
response-buffer ..................................................................... 26

4 Netscape Enterprise Server Programmer’s Guide to Servlets • April 2002 (Draft)
response-cookie ..................................................................... 26
role-mapping ....................................................................... 26
session-cookie....................................................................... 27
session-manager..................................................................... 27
session-tracking ..................................................................... 27
tempdir ............................................................................ 28
vs ................................................................................. 28
web-app ........................................................................... 28
DeployingaWebApplicationusingwdeploy.............................................. 29
WebApplicationExamples.............................................................. 31
Chapter 3 UsingServlets...................................................... 33
WhatDoestheServerNeedtoRunServlets?............................................... 33
UsingtheUserInterface................................................................. 34
EnablingServlets....................................................................... 34
MakingServletsAvailabletoClients...................................................... 34
The<SERVLET>SHTMLTag............................................................ 35
ServletOutput ......................................................................... 36
ConfiguringJVM....................................................................... 37
MaximizingServletPerformance ......................................................... 37
Chapter 4 UsingJavaServerPages ............................................. 39
WhatDoestheServerNeedtoRunJSP?................................................... 39
ConfiguringJRE/JDKPaths ............................................................. 41
UsingtheUserInterface................................................................. 43
EnablingJSPs.......................................................................... 44
MakingJSPsAvailabletoClients ......................................................... 44
DeletingCacheVersionFiles............................................................. 44
TheJSPCommand-LineCompiler........................................................ 45
PackageNamesGeneratedbytheJSPCompiler ......................................... 48
SpecifyingthatJSPsArePrecompiled .................................................. 48
OtherJSPInitializationParameters .................................................... 49
JSPTagLibrariesandStandardPortableTags.............................................. 49
Chapter 5 Debugging Servlets and JSPs . ........................................ 51
ServletDebugging ..................................................................... 51
JSPDebugging......................................................................... 52
GeneratingaStackTraceforDebugging................................................... 53
JPDAOptionsforDebugging ............................................................ 54
Chapter 6 Session Managers .................................................. 55
SessionOverview ...................................................................... 55

5
SpecifyingaSessionManager............................................................ 56
NESSessionManager.................................................................... 58
ParametersforNESSessionManager ................................................... 58
EnablingNESSessionManager ........................................................ 61
SourceCodeforNESSessionManager .................................................. 62
MMapSessionManager(UNIXOnly)...................................................... 63
Parameters ......................................................................... 63
EnablingMMapSessionManager ...................................................... 64
DeletingSessionDataVersionFiles..................................................... 65
DeprecatedSessionManagers ........................................................... 65
SimpleSessionManager............................................................... 65
JdbcSessionManager ................................................................. 67
LoadBalancing,SessionFailover,andSessionIDs .......................................... 70
Chapter 7 APIClarifications ....................................................73
ClarificationofHttpSessionScope........................................................ 73
ClarificationsforUsingMethods ......................................................... 74
HttpServlet.service .................................................................. 74
ServletContext.getAttribute ........................................................... 75
ServletRequest.setAttribute ........................................................... 75
ServletRequest.getParameter.......................................................... 75
ServletResponse.getOutputStreamandgetWriter ........................................ 77
RequestDispatcher.forwardandinclude ................................................ 77
OtherUsefulInformation ............................................................... 79
DatabaseConnectionPooling ......................................................... 79
FetchingtheClientCertificate ......................................................... 79
Chapter 8 LegacyServletandJSPConfiguration ..................................81
TheDefaultVirtualServer............................................................... 81
EnablingServletsandJSP ............................................................... 82
MakingJSPsAvailabletoClients ......................................................... 82
ConfiguringServletsintheDefaultVirtualServer .......................................... 82
ConfiguringGlobalServletAttributes .................................................. 83
RegisteringServletDirectories ........................................................ 83
RegisteringIndividualServlets........................................................ 85
SpecifyingServletVirtualPaths ....................................................... 86
SpecifyingServletContexts ........................................................... 88
UsingtheUserInterface................................................................. 88
LegacyConfigurationFiles .............................................................. 89
servlets.properties ................................................................... 90
rules.properties ..................................................................... 91
contexts.properties .................................................................. 92

6 Netscape Enterprise Server Programmer’s Guide to Servlets • April 2002 (Draft)
LegacyExamples....................................................................... 96
MaximizingLegacyServletPerformance .................................................. 97
Appendix A Servlet Settings in magnus.conf and obj.conf . . . ....................... 99
InitDirectivesinmagnus.conf ........................................................... 99
Objectsinobj.conf..................................................................... 100
DirectivesforRegisteredServletDirectories .............................................. 102
JSPDirectives......................................................................... 102
Appendix B ConvertingSSJSApplications ..................................... 103
DifferencesBetweenJavaScriptandJava ................................................. 103
JavaScripttoJavaClassConversions..................................................... 105
ConversionSteps...................................................................... 106
ExampleConversion .................................................................. 107
Appendix C JVMConfiguration ............................................... 109
Thejvm12.confFile.................................................................... 110
UsingJVMEnvironmentVariables ...................................................... 111
jvm12.confParameterReference......................................................... 112
Appendix D RemoteServletProfiling .......................................... 117
TheOptimizeit!Profiler ................................................................ 117
TheHPROFProfiler ................................................................... 118
Index ....................................................................... 123

7
About This Book
This book discusses how to enable and install Java™ servlets and JavaServer
Pages™ (JSP) in Netscape® Enterprise Server 6.1.
This book has the following chapters and appendices:
• Chapter 1, “Servlets and JavaServer Pages”
This chapter introduces web applications, servlets, and JavaServer Pages.
• Chapter 2, “Web Applications”
This chapter discusses the structure of web applications and how to deploy
them in Enterprise Server 6.1. It also lists example web applications and
describes the web-apps.xml file, which configures web applications for virtual
servers in Enterprise Server 6.1.
• Chapter 3, “Using Servlets”
This chapter discusses how to enable and install servlets in Enterprise Server
6.1.
• Chapter 4, “Using JavaServer Pages”
This chapter discusses how to enable and install JavaServer Pages in Enterprise
Server 6.1, including how to install the JDK.
• Chapter 5, “Debugging Servlets and JSPs”
This chapter discusses how to debug servlets and JSPs, and includes a section
on debugging using Forte™ for Java.
• Chapter 6, “Session Managers”
This chapter discusses the session managers provided with Enterprise Server
and explains how to customize session behavior to suit your own needs.

Where to Find Related Information
8 Netscape Enterprise Server Programmer’s Guide to Servlets • April 2002 (Draft)
• Chapter 7, “API Clarifications”
This chapter discusses methods in the Servlets API that behave marginally
differently in Enterprise Server than specified in the Sun Microsystems’
Servlets API documentation or where the behavior documented by Sun
Microsystemsisambiguous.
• Chapter 8, “Legacy Servlet and JSP Configuration”
This chapter discusses how to configure the default virtual server as in iPlanet
Web Server 4.x,andtheservlets.properties,rules.properties,and
contexts.properties files.
• Appendix A, “Servlet Settings in magnus.conf and obj.conf”
This appendix discusses how the configuration file obj.conf changes
depending on the settings for servlets and JSP.
• Appendix B, “Converting SSJS Applications”
This appendix discusses how to convert LiveWire applications to JSPs.
• Appendix C, “JVM Configuration”
This appendix discusses how to manually specify JVM configuration
information.
• Appendix D, “Remote Servlet Profiling”
This appendix discusses how to enable remote profiling for servlets.
Where to Find Related Information
Additional Enterprise Server documentation includes:
• Netscape Enterprise Server Installation and Migration Guide
• Netscape Enterprise Server Performance Tuning, Sizing, and Scaling Guide
• Netscape Enterprise Server Administrator’s Guide
• Netscape Enterprise Server Programmer’s Guide
NOTE Throughout this manual, all descriptions specific to UNIX® apply
to the Linux® operating system as well, except where Linux is
specifically mentioned.

Where to Find Related Information
About This Book 9
• Netscape Enterprise Server NSAPI Programmer’s Guide
•Netscape Enterprise Server Release Notes
You can find Enterprise Server documentation online in PDF and HTML formats
at:
http://enterprise.netscape.com/docs

Where to Find Related Information
10 Netscape Enterprise Server Programmer’s Guide to Servlets • April 2002 (Draft)

11
Chapter 1
Servlets and JavaServer Pages
Netscape Enterprise Server 6.1 supports servlets and JavaServer Pages (JSPs). This
chapter gives a brief overview of servlets and JSPs in Enterprise Server 6.1.
The sections in this chapter are:
• Web Applications
• Servlets
• JavaServer Pages
Enterprise Server 6.1 runs with a specific version of the JRE or JDK that is
operating-system dependent. For more information, see “What Does the Server
Need to Run JSP?,” on page 37.
Web Applications
Enterprise Server 6.1 supports the Servlet 2.3 API specification, which allows
servlets and JSPs to be included in web applications.
A web application is a collection of servlets, JavaServer Pages, HTML documents,
and other web resources which might include image files, compressed archives,
and other data. A web application may be packaged into an archive (a WAR file) or
exist in an open directory structure.
For more details about web application support in Enterprise Server, see Chapter 2,
“Web Applications.”
Although using web applications is recommended, you can still configure servlets
and JSPs as in iPlanet Web Server 4.x. For more information, see Chapter 8,
“Legacy Servlet and JSP Configuration.”

Servlets
12 Netscape Enterprise Server Programmer’s Guide to Servlets • April 2002 (Draft)
ServletsJava servlets are server-side Java programs that web servers can run to generate
content in response to a client request in much the same way as CGI programs do.
Servlets can be thought of as applets that run on the server side without a user
interface. Servlets are invoked through URL invocation.
Enterprise Server 6.1 supports the Java Servlet Specification version 2.3 (including
Web Application and WAR file support).
To develop servlets, use Sun Microsystems’ Java Servlet API. For information
about using the Java Servlet API, see the documentation provided by Sun
Microsystems at:
http://java.sun.com/products/servlet/index.html
JavaServer Pages
Enterprise Server 6.1 supports JavaServer Pages (JSP) Specification version 1.2.
A JSP is a page, much like an HTML page, that can be viewed in a web browser.
However, in addition to HTML tags, it can include a set of JSP tags and directives
intermixed with Java code that extend the ability of the web page designer to
incorporate dynamic content in a page. These additional features provide
functionality such as displaying property values and using simple conditionals.
One of the main benefits of JSPs is that, like HTML pages, they do not need to be
compiled. The web page designer simply writes a page that uses HTML and JSP
tags and puts it on their web server. The web page designer does not need to learn
how to define Java classes or use Java compilers.
Enterprise Server supports precompilation of JSPs, however, and this is
recommended for production servers.
NOTE Servlet API version 2.3 is fully backward compatible with version
2.2, so all existing servlets will continue to work without
modification or recompilation.

JavaServer Pages
Chapter 1 Servlets and JavaServer Pages 13
JSP pages can access full Java functionality in the following ways:
• by embedding Java code directly in scriptlets in the page
•byaccessingJavabeans
• by using server-side tags that include Java servlets
Both beans and servlets are Java classes that need to be compiled, but they can be
defined and compiled by a Java programmer, who then publishes the interface to
the bean or the servlet. The web page designer can access a pre-compiled bean or
servlet from a JSP page.
Enterprise Server 6.1 supports JSP tag libraries and standard portable tags.
For information about creating JSPs, see Sun Microsystem’s JavaServer Pages web
site at:
http://java.sun.com/products/jsp/index.html
For information about Java Beans, see Sun Microsystem’s JavaBeans web page at:
http://java.sun.com/beans/index.html

JavaServer Pages
14 Netscape Enterprise Server Programmer’s Guide to Servlets • April 2002 (Draft)

15
Chapter 2
Web Applications
Netscape Enterprise Server 6.1 supports the Servlet 2.3 API specification, which
allows servlets and JSPs to be included in web applications.
A web application is a collection of servlets, JavaServer Pages, HTML documents,
and other web resources which might include image files, compressed archives,
and other data. A web application may be packaged into an archive (a WAR file) or
exist in an open directory structure. For more information about web applications,
see the Servlet 2.3 API specification:
http://java.sun.com/products/servlet/index.html
This chapter describes how web applications are supported in Enterprise Server,
and includes the following sections:
• Web Application Structure
• Dynamic Reconfiguration
• web.xml Clarifications
• The web-apps.xml File and Virtual Servers
• Deploying a Web Application using wdeploy
• Web Application Examples
Web Application Structure
Web Applications have a directory structure, all accessible from a mapping to the
application’s document root (for example, /catalog). The document root contains
JSP files, HTML files, and static files such as image files.

Dynamic Reconfiguration
16 Netscape Enterprise Server Programmer’s Guide to Servlets • April 2002 (Draft)
A special directory under the document root, WEB-INF, contains everything related
to the application that is not in the public document tree of the application. No file
contained in WEB-INF can be served directly to the client. The contents of WEB-INF
include:
•/WEB-INF/web.xml, an XML-based deployment descriptor that specifies the
web application configuration, including mappings, initialization parameters,
and security constraints.
•/WEB-INF/classes/*, the directory for the servlet and utility classes.
•/WEB-INF/lib/*.jar, the directory for the JAR files containing servlets, beans,
and other utility classes.
A WAR (web application archive) file contains a complete web application in
compressed form. Enterprise Server cannot access an application in a WAR file.
You must uncompress a web application (deploy it using the wdeploy utility)
before Enterprise Server can serve it.
Web application configuration includes two parts:
•The
web.xml file, which is the standard Servlets 2.3 deployment descriptor.
Each web application has its own web.xml file. For information about web.xml,
see the Servlet 2.3 API specification:
http://java.sun.com/products/servlet/index.html
•Theweb-apps.xml file, which is specific to Enterprise Server. Each virtual
server has its own web-apps.xml file, which configures all the applications
running in that virtual server.
Dynamic Reconfiguration
When you make changes to a web application, you do not need to restart the
server. Changes are reloaded automatically at a frequency set in the
reload-interval attribute of the class-loader element in the web-apps.xml file.
When you make changes to the web-xml or web-apps.xml file, you also do not
need to restart the server. However, you must apply the changes by clicking the
Apply link and then clicking the Load Configuration Files button on the Apply
Changes screen.

web.xml Clarifications
Chapter 2 Web Applications 17
For more information about dynamic reconfiguration, see Chapter 1, “Basics of
Server Operation” in the Netscape Enterprise Server NSAPI Programmer’s Guide.
If you add or remove a web application, servlet, or JSP, you must restart the server.
web.xml Clarifications
This section provides clarifications for using the web.xml file with Enterprise
Server 6.1.
login-config
If there is a security constraint and no login-config element is present, or if no
auth-method is specified, the auth-method defaults to BASIC.ForBASIC
authentication, if no realm-name is specified, the realm-name defaults to nES Web
Container.Ifauth-method is not FORM,theform-login-config element is
ignored even if specified.
security-constraint
If no url-pattern is specified, no constraints are applied. If no http-method is
specified in a web-resource-collection subelement, the constraint is applied to
all HTTP methods. If no transport-guarantee is specified in a
user-data-constraint subelement, it defaults to NONE.Ifnoauth-constraint
subelement is present or if no role-name is specified, no user is allowed any access.
session-timeout
If session-timeout is specified in web.xml, this timeout value overrides any
timeOut parameter value specified in the session-manager element in
web-apps.xml. This override does not apply when you configure a single session
manager that all web applications in a virtual server use. It only applies when you:
• Do not configure a session manager for all web applications in a virtual server
(the default behavior) Each web application has its own session manager.
• Configure a web-application-specific session manager in addition to the
virtual-server-wide one. In that case, only the web-application-specific session
manager’s timeOut value is overridden.
Note that session-timeout value is specified in minutes while session-manager
timeOut parameters are specified in seconds.
For more information about session managers, see Chapter 6, “Session Managers.”

The web-apps.xml File and Virtual Servers
18 Netscape Enterprise Server Programmer’s Guide to Servlets • April 2002 (Draft)
The web-apps.xml File and Virtual Servers
The web-apps.xml file defines contexts for a set of web applications running in a
virtual server. The context information includes a context path of the web
application and other properties such as how it handles session management or
authentication.
The web-apps.xml file follows the standard J2EE deployment descriptor format: a
well-formed .XML document specified by a .dtd file. The web-apps.xml file
contains a set of web applications defined by their context path and physical
location.
Each web application may also define a number of configuration elements specific
to Enterprise Server that customize how the application is serviced. For example, a
web application can define pluggable session management or specify a java
compiler. The web-apps.xml file allows users to define a set of global
configuration elements and share (or override) them across multiple web
applications.
Each web-apps.xml file must be referenced in the server.xml file, which defines
virtual servers. For more information about server.xml,seetheNetscape Enterprise
Server NSAPI Programmer’s Guide.
The Default Context for a Virtual Server
When you create a new virtual server, an empty web-apps.xml file is created. You
can use the default context that is created automatically, or you can create your
own by modifying the web-apps.xml file.
If a servlets.properties file is present in the default virtual server (in the
config directory of the server instance), an iPlanet Web Server 4.xservlet context is
created instead of a web application context. For more information about legacy
configuration, see Chapter 8, “Legacy Servlet and JSP Configuration.”
Example server.xml File
The server.xml file contains two variables, webapps_enable and webapps_file,
that are relevant to web applications.
webapps_enable Atrue or false variable that allows you to enable or disable
web applications for a virtual server. If not present in a virtual
server definition, web applications are enabled by default.

The web-apps.xml File and Virtual Servers
Chapter 2 Web Applications 19
The following server.xml file uses these variables:
<?xml version="1.0" encoding="UTF-8"?>
<!-- declare any variables to be used in the obj.conf file in the
ATTLIST below -->
<!DOCTYPE SERVER SYSTEM "server.dtd" [
<!ATTLIST VARS
docroot CDATA #IMPLIED
adminusers CDATA #IMPLIED
webapps_file CDATA #IMPLIED
webapps_enable CDATA #IMPLIED
accesslog CDATA #IMPLIED
user CDATA #IMPLIED
group CDATA #IMPLIED
chroot CDATA #IMPLIED
dir CDATA #IMPLIED
nice CDATA #IMPLIED
>
]>
<SERVER legacyls="ls1">
<VARS accesslog="/nes60/https-server.netscape.com/logs/access"/>
<LS id="ls1" ip="0.0.0.0" port="80" security="off"
acceptorthreads="1">
<CONNECTIONGROUP id="group1" matchingip="default"
servername="example.com" defaultvs="example.com"/>
</LS>
<MIME id="mime1" file="mime.types"/>
<ACLFILE id="acl1"
file="/nes60/httpacl/generated.https-server.netscape.com.acl"/>
<VSCLASS id="defaultclass" objectfile="obj.conf"
rootobject="default">
<VARS docroot="/nes60/docs"/>
<VS id="example.com" connections="group1" mime="mime1"
aclids="acl1">
<VARS webapps_file="web-apps.xml" webapps_enable="on"/>
<USERDB id="default" database="default"/>
</VS>
</VSCLASS>
</SERVER>
For more information about the server.xml file, see Chapter 8, “Virtual Server
Configuration Files” in the Netscape Enterprise Server NSAPI Programmer’s Guide.
webapps_file The path to the web-apps.xml file for a virtual server.

The web-apps.xml File and Virtual Servers
20 Netscape Enterprise Server Programmer’s Guide to Servlets • April 2002 (Draft)
Example web-apps.xml File
Note that the !DOCTYPE declaration must be present and of the following format:
<!DOCTYPE vs PUBLIC "-//Netscape Communications Corp.;Netscape//DTD
Virtual Server Web Applications 6.1//EN"
"http://developer.netscape.com/products/servers/enterprise/dtds/nes
-webapps_6_1.dtd">
If for some reason if this URL is not accessible, the DTD file is located here:
"file:/server_root/bin/https/dtds/nes-webapps_6_1.dtd"
On Windows® 2000 or Windows NT®, be sure to include the drive letter, as
follows:
"file:/drive:/server_root_path/bin/https/dtds/nes-webapps_6_1.dtd"
The following web-apps.xml file configures a session manager and one web
application:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- NES 6.1 specific web application configuration. -->
<!DOCTYPE vs PUBLIC "-//Netscape Communications Corp.;Netscape//DTD
Virtual Server Web Applications 6.1//EN"
"http://developer.netscape.com/products/servers/enterprise/dtds/nes
-webapps_6_1.dtd">
<vs>
<!-- Define global configuration -->
<!- Configure a session manager and tracking configuration -->
<session-manager
class='com.netscape.server.http.session.NESSessionManager'
<init-param>
<param-name>maxSessions</param-name>
<param-value>1000</param-value>
</init-param>
<init-param>
<param-name>timeOut</param-name>
<param-value>1800</param-value>
</init-param>
<init-param>
<param-name>reapInterval</param-name>
<param-value>600</param-value>
</init-param>
<init-param>