| Previous Contents Index DocHome Next |
| iPlanet Web Server, Enterprise Edition Programmer's Guide to Servlets |
Chapter 2 Web Applications
iPlanet Web Server 6.0 supports the Servlet 2.2 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.2 API specification:
http://java.sun.com/products/servlet/index.html
This chapter describes how web applications are supported in iPlanet Web Server, and includes the following sections:
Web Application Structure
The web-apps.xml File and Virtual Servers
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.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.
A WAR (web application archive) file contains a complete web application in compressed form. iPlanet Web Server cannot access an application in a WAR file. You must uncompress a web application (deploy it using the wdeploy utility) before iPlanet Web Server can serve it./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.
Web application configuration includes two parts:
The web.xml file, which is the standard Servlets 2.2 deployment descriptor. Each web application has its own web.xml file. For information about web.xml, see the Servlet 2.2 API specification:
The web-apps.xml file, which is specific to iPlanet Web Server. Each virtual server has its own web-apps.xml file, which configures all the applications running in that virtual server.
- http://java.sun.com/products/servlet/index.html
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.
For more information about dynamic reconfiguration, see Chapter 1, "Basics of Server Operation" in the NSAPI Programmer's Guide for iPlanet Web Server.
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 iPlanet Web Server 6.0.
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. For BASIC authentication, if no realm-name is specified, the realm-name defaults to iWS Web Container. If auth-method is not FORM, the form-login-config element is ignored even if specified.
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. If no auth-constraint subelement is present or if no role-name is specified, no user is allowed any access.
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.
Note that session-timeout value is specified in minutes while session-manager timeOut parameters are specified in seconds.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.
For more information about session managers, see Chapter 6 "Session Managers."
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 iPlanet Web 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, see the NSAPI Programmer's Guide for iPlanet Web Server.
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.x servlet 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.
A true 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 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="/iws60/https-server.iplanet.com/logs/access"/>
<LS id="ls1" ip="0.0.0.0" port="80" security="off"
acceptorthreads="1">
<CONNECTIONGROUP id="group1" matchingip="default"
servername="acme.com" defaultvs="acme.com"/>
</LS>
<MIME id="mime1" file="mime.types"/>
<ACLFILE id="acl1"
file="/iws60/httpacl/generated.https-server.iplanet.com.acl"/>
<VSCLASS id="defaultclass" objectfile="obj.conf"
rootobject="default">
<VARS docroot="/iws60/docs"/>
<VS id="acme.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 NSAPI Programmer's Guide for iPlanet Web Server.
Example web-apps.xml File
Note that the !DOCTYPE declaration must be present and of the following format:<!DOCTYPE vs PUBLIC "-//Sun Microsystems, Inc.; iPlanet//DTD Virtual Server Web Applications 6.0//EN" "http://developer.iplanet.com/webserver/dtds/iws-webapps_6_0.dtd">
If for some reason if this URL is not accessible, the DTD file is located here:
"file:/server_root/bin/https/dtds/iws-webapps_6_0.dtd"
On Windows NT, be sure to include the drive letter, as follows:
"file:/drive:/server_root_path/bin/https/dtds/iws-webapps_6_0.dtd"
The following web-apps.xml file configures a session manager and one web application:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- iWS 6.0 specific web application configuration. -->
<!DOCTYPE vs PUBLIC "-//Sun Microsystems, Inc.; iPlanet//DTD Virtual Server Web Applications 6.0//EN" "http://developer.iplanet.com/webserver/dtds/iws-webapps_6_0.dtd">
<vs>
<!-- Define global configuration -->
<!- Configure a session manager and tracking configuration -->
<session-manager
class='com.iplanet.server.http.session.IWSSessionManager'
<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>
<param-name>session-data-dir</param-name>
<param-value>/net/dotcom.com/sessions</param-value>
</init-param>
</session-manager>
<session-tracking use-cookies="true" />
<!-- Define the web applications for this virtual server-->
<!-- catalog application -->
<web-app uri="/catalog" dir="/webapps/catalog">
<!-- Specify a tempory directory. A path returned in the "javax.servlet.context.tempdir" property; -- defaults to WEB-INF/tmp. -->
<tempdir dir='/var/catalog/tmp'/>
<!-- reload classes at every 5 minutes; also include mycatlog.jar file in the classpath -->
<class-loader reload-interval='300' classpath='/home/work/mycatalog.jar' />
</web-app>
</vs>
web-apps.xml Element Reference
This section shows the elements allowed in a web-apps.xml file. These elements are defined in the master dtd file.
Configures a specific native user/group database for authentication and role mapping. If this element is not specified, authentication is enabled using the native default authentication database.
The native authentication database. This database must also be defined in the server.xml file in the database attribute of a USERDB element, and in the dbswitch.conf file.
The class loader for the virtual server or the web application. There is a default class loader for the virtual server if you don't specify one. Classes loaded by the virtual-server-level class loader are not dynamically reloaded.
You can use the ServletContext.getAttribute method to retrieve the class loader and the class loader's classpath or reload interval for a context. For more information, see Chapter 7 "API Clarifications."
A description of a parameter. Used within an init-param element. iPlanet Web Server ignores this element.
These elements implement the Filter API from the Servlet 2.3 specification. Used within a web-app element.
Although iPlanet Web Server 6.0 supports only the Servlet 2.2 API in the web.xml file, the Filter API from the Servlet 2.3 specification is available in the web-apps.xml file.
The filter and filter-mapping elements implement the Filter API. They are both subelements of a web-app element in the web-apps.xml file. Except for their file location, filter and filter-mapping are as described in the Servlet 2.3 specification. For more information, see:
http://java.sun.com/products/servlet/index.html
Configures form-based authentication for single sign-on across all web applications in a virtual server. If not present, the default virtual server level session manager is used.
The name of the cookie that tracks the session ID. The default is iwsformloginid.
The session timeout in seconds. The default is 600 (10 minutes).
Specifies an initialization parameter for the containing element. The attributes of init-param depend on the object referenced by the containing element.
For example, if the containing element is session-manager and the session manager is IWSSessionManager, the attributes of init-param are the initialization parameters of IWSSessionManager.
Subelements: param-name, param-value, description
Configures JSP compilation behavior. For a description of the initialization parameters, see "The JSP Command-Line Compiler."
Enables JSP. Allowed values are true and false. The default is true.
The name of a parameter. Used within an init-param element.
The value of a parameter. Used within an init-param element.
Advises the web server on how to decode parameters from forms.
Allowed values are auto (the default), none, or a specific encoding such as utf8 or Shift_JIS:
A specific encoding, such as utf8 or Shift_JIS. Set this option if you know the encoding that servlet parameters use. A complete list is available here:
http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html
Uses the system default encoding. Set this option if the encoding of the servlet parameter data is the same as the system default encoding.
(Default) Tries to figure out the proper encoding from, in order, 1) the charset if it is set in the Content-Type header, 2) the parameterEncoding attribute (see "ServletRequest.setAttribute"), then 3) a hidden form field defined in form-hint-field. Otherwise, the system default encoding is used. Set this option to prevent misinterpretation of non-ASCII characters in servlet parameters.
When this property is set to auto, the server has to convert native characters into a java byte array before transforming them into the requested encoding. Therefore, performance is slightly better for none or a specific encoding.
The name of the hidden field in the form that specifies the encoding. The default is j_encoding.
If a servlet uses the ServletRequest.getParameter method to retrieve values in form fields having non-UTF-8 characters, the enc attribute must be set to auto (the default). Otherwise, the values extracted by the getParameter method are zeros or are undefined. For more information see "ServletRequest.getParameter."
The enc attribute setting applies to how a servlet processes parameters after the iPlanet Web Server receives a request. The URI that is sent to the server must consist of only the standard ASCII set, especially if the request method is GET. All other characters must be encoded.
For example, to encode a backslash, you would replace the backslash with a % followed by the hexadecimal number corresponding to the backslash in the ASCII character set, 5c. Therefore, vw\xyz becomes vw%5cxyz.
For more information, read section 2.2 of the following document from the URI working group of the Internet Engineering Task Force:
http://www.ietf.org/rfc/rfc1738.txt
Configures the initial and default size of the HTTP servlet's response buffer. A servlet can reconfigure its response buffer size using the setBufferSize method of the ServletResponse object.
Tells the server to respond with a specific cookie version.
Maps role-name values from web.xml to LDAP users, groups, or roles.
Specifies whether to map role-name values from web.xml to LDAP users or groups. Values are group (the default) and user.
Sets parameters for the session cookie.
The session manager for the web application. See Chapter 6 "Session Managers" for the initialization parameters for each session manager.
If session-timeout is specified in web.xml, it overrides any session manager's timeOut initialization parameter. For details, see "session-timeout."
Determines the method of session tracking.
Uses cookies for session tracking if true (the default). Allowed values are true and false.
Uses URL rewriting for session tracking if true (the default). Allowed values are true and false.
A temporary directory used by the web application.
The top-level element in the web-apps.xml file. Subelements other than web-app set defaults for all web applications.
Subelements: auth-native, class-loader, form-login-session, jsp-servlet, parameter-encoding, response-buffer, response-cookie, role-mapping, session-manager, session-tracking, session-cookie, tempdir, web-app
The web application. A web application is packaged in a WAR file and can contain servlets, JSPs, HTML pages, class files, and other resources of an application.
The subelements of a web-app element override the equivalent subelements of the containing vs element for that web application.
Subelements: auth-native, class-loader, filter, filter-mapping, jsp-servlet, parameter-encoding, response-buffer, response-cookie, role-mapping, session-manager, session-tracking, session-cookie, tempdir
The directory where the web application contents are located.
The URI that clients use to access the web application. This URI can be a regular expression.
Deploying a Web Application using wdeploy
Before you can deploy a web application manually, you must make sure that the server_root/bin/https/httpsadmin/bin directory is in your path and that the IWS_SERVER_HOME environment variable is set to your server_root directory.You can use the wdeploy utility at the command line to deploy a WAR file into a virtual server web application environment:
wdeploy deploy -u uri_path -i instance -v vs_id [-d directory] war_file
You can also delete a virtual server web application:
wdeploy delete -u uri_path -i instance -v vs_id hard|soft
You can also list the web application URIs and directories for a virtual server:
wdeploy list -i instance -v vs_id
The command parameters have the following meanings:
When you execute the wdeploy deploy command, two things happen:
A web application with the given uri_path and directory gets added to the web-apps.xml file.
For example:wdeploy deploy -u /hello -i server.iplanet.com -v acme.com -d /iws60/https-server.iplanet.com/acme.com/web-apps/hello /iws60/plugins/servlets/examples/web-apps/HelloWorld/HelloWorld.war
This utility results in the following web-apps.xml entry:
<vs>
<web-app uri="/hello"
dir="/iws60/https-server.iplanet.com/acme.com/webapps/hello"/>
</vs>The /iws60/https-server.iplanet.com/acme.com/web-apps/hello directory has the following contents:
colors
index.jsp
META-INF
WEB-INF/
web.xml
/classes/
HelloWorldServlet.class
HelloWorldServlet.java
SnoopServlet.class
SnoopServlet.javaBefore you can run a web application that has been deployed, you must make sure that the server.xml file for the server instance points to the web-apps.xml file for your virtual server.
After you have deployed an application, you can access it from a browser as follows:
http://vs_urlhost[:vs_port]/uri_path/[index_page]
The parts of the URL have the following meanings:
http://acme.com:80/hello/index.jsp
Web Application Examples
iPlanet Web Server 6.0 comes with a set of example web applications. You can find them at the following location:server_root/plugins/servlets/examples/web-apps
This directory contains the following directories:
HelloWorld -- Contains a simple web application in a HelloWorld.war file.
You can deploy any of these examples using the wdeploy utility.filter-test -- Contains an example of the Filter API feature in a filter-test.war file.
utility-taglib -- Contains an example JSP tag library in a utility-taglib.war file. This tag library was created by the Jakarta project at jakarta.apache.org.
Previous Contents Index DocHome Next
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.
Last Updated May 02, 2001