3.3 Configuring the Servlet Execution Engine

The servlet execution engine hosts all services, including both those written directly with the Servlet API (see the HydraExpress Servlet Development Guide), and those created using code generator rwsfgen directly (see the HydraExpress Web Service Development Guide).

A global web.xml file sets configuration parameters that apply to each servlet context. Individual servlets are configured in a web.xml configuration file that must reside in a WEB-INF directory inside your project, as shown in Table 3.

Table 3: Servlet execution engine deployment directory structure 

apps

      servlets

          <contextname>

                WEB-INF

The global web.xml file sets configuration parameters that apply to each context. The web.xml file, located in the <installdir>\conf\server directory, maps common file extensions to mime-types and sets resources to handle global error pages. Many installations require no changes to the global web.xml file.

Note that the global web.xml file does not define a context, so this file should not define or map servlets, filters, listeners, or named objects. The HydraExpress Agent ignores any such definitions or mappings in the global web.xml file.

For more information, see Section 5.4, "Context Does Not Load," in the HydraExpress Servlet Development Guide.

Individual servlets are configured in a web.xml configuration file that must reside in a WEB-INF directory inside your project. For example, here is the web.xml file that configures the test servlet for the DemoProject, located in your <installdir>\tutorials\process\DemoProject\WEB-INF directory:

<web-xml>
  <servlet>
    <servlet-name>DemoProjectServlet</servlet-name>
    <servlet-class>DemoProjectServlet.createDemoProjectServlet
    </servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>DemoProjectServlet</servlet-name>
    <url-pattern>/DemoProjectServlet/*</url-pattern>
  </servlet-mapping>
</web-xml>

You can use any web.xml file provided with the tutorials in the HydraExpress Tutorials as a template for creating web.xml files for your servlets. For detailed information on servlet configuration, see Section 24.4, "Configuring the Servlet Used by the Service," in the HydraExpress Web Service Development Guide.

Servlets are inherently multithreaded. However, the servlet execution engine supports a simple mechanism for serializing access to a particular servlet. If a servlet element in the web.xml file contains the attribute single-thread="true", the servlet execution engine 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 LEIF server 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.

<servlet single-thread="true">
  <servlet-name>singleServlet</servlet-name>
  <servlet-class>sync.createSingleServlet</servlet-class>
</servlet>

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 servlet engine, it may be unsuitable for production applications. Configuring multiple containers, each with a single thread, may offer better performance, as described in Section 3.3.3.1.

The servlet execution engine is inherently multithreaded. However, code which is not multithread-safe can be hosted in a servlet execution engine provided that the engine is configured so that only one thread is active within servlet code at a given time. To increase performance, install more than one servlet engine and use an lb worker to balance requests between them. Although this solution provides somewhat lower performance than a multithreaded servlet execution engine, this strategy may provide acceptable performance for single-threaded code in a production environment.

Declare servlets in the context web.xml files located in the WEB-INF directory inside the project directory, as discussed in

<web-xml>
  <servlet>
    <servlet-name>DemoProjectServlet</servlet-name>
    <servlet-class>DemoProjectServlet.createDemoProjectServlet</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>DemoProjectServlet</servlet-name>
    <url-pattern>/DemoProjectServlet/*</url-pattern>
  </servlet-mapping>
</web-xml>

Notice that the servlets in the servlet execution engine should not be set to single-thread access. Since the servlet execution engine only has one thread available, there is no need to incur the additional overhead of synchronizing access to the servlets.

Create a worker.properties file that includes each servlet execution engine as an ajp13 worker managed by an lb worker. The sample worker.properties file below shows an lb worker balancing two servlet execution engine.

#
# Load balancing for single-threaded containers.
#

# Define only the lb worker in the worker.list.  The Web server
# should not communicate directly with the workers that the
# lb worker manages.

worker.list=loadbalancer

# Define the first container.
worker.container1.type=ajp13
worker.container1.host=localhost
worker.container1.port=8009
worker.container1.lbfactor=1

# Define the second container.
worker.container2.type=ajp13
worker.container2.host=localhost
worker.container2.port=8011
worker.container2.lbfactor=1

# Define the load balancing worker.

worker.loadbalancer.type=lb
worker.loadbalancer.balanced_workers=container1,container2

Note that the ajp13 workers have an equal lbfactor. The default cachesize for a worker is 1, so the file does not set a cachesize for either ajp13 worker.

The Web server configuration maps the servlet requests directly to the loadbalancer worker. On an Apache HTTP server, the servlet.conf file contains the following line:

JkMount /servlets/* loadbalancer

For IIS, the uriworkermap.properties file contains the line:

/servlets/*=loadbalancer

©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.