Rogue Wave banner
Previous fileTop of DocumentContentsIndex pageNext file
HydraExpress Servlet Development Guide
Rogue Wave web site:  Home Page  |  Main Documentation Page

4.7 Define and Map Servlets

A web.xml file must first define a servlet instance, then map that instance to one or more URL patterns. For details on programming servlets, see Chapter 9.

4.7.1 Defining the Servlet Instance

The servlet element of a web.xml file defines a servlet instance. The servlet element always contains a servlet-name element and a servlet-class element, and may also contain initialization parameters.

The servlet-name element declares a name for this particular servlet instance. Each servlet instance in a context must have a unique name. However, the name is only used to associate URL mappings with this instance, and need not correspond to the name of the servlet class or the URL of the servlet.

The servlet-class element tells the container how to construct an instance of the servlet class. There are two components to this element. The element contains the base name of the DLL that contains the servlet, and the name of the function that the container uses to load the servlet. The components of the element are separated by a single period. For example, the element status.createStatusServlet contains the base name status and the function name createStatusServlet.

The base name of a DLL is the name of the library without the platform-specific prefix (if any), without the suffix specified on the HydraExpress command line, and without the platform-specific extension. See Appendix C for information on library name mappings for each platform that HydraExpress supports.

The function name in the servlet-class element must match the function name defined in the servlet implementation. The RWSF_DEFINE_SERVLET macro in the implementation source code defines the function name, as described in Section 6.5. Note that the name of this function must be a legal C++ identifier.

The servlet element below defines a servlet named getStatus. The servlet DLL has the base name status, and the container calls the function createStatusServlet to load the servlet instance.

Notice that the name of the servlet instance need not correspond to the class name. To add another instance of the same servlet class to the container, use another servlet element with a different servlet-name. The web.xml file fragment below defines two different instances of the same servlet class:

Each servlet element may contain any number of init-param elements. The container passes the parameters to the servlet in much the same way that command line parameters are passed to a complete program, so the exact parameter names and values required depend on the individual servlet. The example below shows a web.xml file fragment that defines two different instances of the same servlet class. The container starts each instance with different parameters.

A servlet element only defines an instance of a servlet. For the container to forward requests to the servlet, the servlet must be mapped to one or more URLs or called by name from another servlet or a filter.

4.7.2 Mapping Servlets to URLs

The servlet-mapping element associates a URL pattern to a servlet instance. The servlet-mapping always contains a servlet-name element and a url-pattern element.

The servlet-name element must match a servlet-name defined in a servlet element elsewhere in the web.xml file. Since a servlet container may have multiple instances of the same servlet running, the container uses the servlet-name to associate a mapping with a servlet.

The url-pattern element contains a pattern that the container uses to determine whether an incoming request should be forwarded to a given servlet. In simple terms, the url-pattern determines the location of the servlet within the context. The url-pattern element can also contain more sophisticated mappings, as described in Section 4.3, "URL Patterns."

For example, the web.xml fragment below maps the URL /status/* to a servlet named getStatus. If the servlet is defined in the examples context of a container at, then this element tells the container that the getStatus servlet will receive requests for URLs that start with

A servlet may receive requests from any number of URL patterns. The fragment below maps two different patterns to the same servlet instance:

Although different patterns can map to the same servlet, the same pattern cannot map to two different servlets. If the same url-pattern appears more than once within a web.xml file, the HydraExpress Agent makes no guarantees about which servlet receives a request. Section 4.3, "URL Patterns," describes the url-pattern element in detail.

4.7.3 Single-thread Access

Servlets are inherently multithreaded. However, the servlet container supports a simple mechanism for serializing access to a particular servlet. If a servlet element contains the attribute single-thread="true", the container only allows one thread at a time to enter the servlet. If a new request arrives for the servlet while a thread is active in the servlet, the new request waits until the active thread leaves the servlet. This slows down the servlet, and may even slow down other servlets in the container if many threads are waiting. Note that specifying single-thread access does not protect the servlet from all threading issues. The container does not prevent threads from entering other instances of the servlet, and other threads in the container remain active when a thread enters a single-thread access servlet.

The servlet element below specifies that only one thread at a time may enter the singleServlet instance.

Single-thread access can be useful for debugging purposes or as a temporary solution for a wrapper around an application with threading problems. However, because single-thread access does not completely solve threading issues and can reduce performance for the overall container, single-thread access may be unsuitable for production applications. Configuring multiple containers with a single thread each may offer better performance. See Chapter 3 of the HydraExpress User's Guide for advanced configuration techniques.

Previous fileTop of DocumentContentsIndex pageNext file

©2004-2007 Copyright Quovadx, Inc. All Rights Reserved.
Quovadx and Rogue Wave are registered trademarks of Quovadx, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.