4.1 Introduction

Each servlet, filter, and listener in the servlet container exists within a context. This chapter describes the tasks involved in creating a new context and configuring a context.

Each servlet and each filter must have a URL pattern mapping, and may have initialization parameters. Section 4.2 discusses initialization parameters. Section 4.3 explains URL pattern matching.

The remainder of this chapter covers the steps listed below. All contexts must have access to the library files that contain the compiled servlets. The contexts are specified in <<installdir>>\apps\servlets, but the libraries can be anywhere in the path.

The first two steps are required for all contexts. Whether the other steps are necessary or not depends on the context. For example, if no servlets or filters in the context require context parameters, there is no need to add parameters to the context.

To add a context:

• Install the files that contain the compiled servlets, filters, and listeners that the context will contain (Section 4.4). All contexts require this step.

• Create a context directory that contains a WEB-INF directory and create a web.xml file within the WEB-INF directory (Section 4.5). All contexts require this step.

• Add context parameters to the web.xml file (Section 4.6).

• Define servlets and map them to URL patterns (Section 4.7).

• Define filters and map them to URL patterns (Section 4.8).

• Define listeners (Section 4.9).

• Define error page handlers (Section 4.10).

• Define session characteristics (Section 4.11).

• Configure the external Web server (Section 4.12).

To load the context, stop and restart the HydraExpress service execution engine (which implements the servlet container). The Introduction to HydraExpress can tell you how. The execution engine reports unrecoverable errors to the console. Errors in a context web.xml file appear in the Agent log if the Agent has logging enabled.

To add a servlet to an existing context, follow the steps below:

• Install the file that contains the compiled servlet (Section 4.4)

• Define the servlet and map the servlet to a URL pattern (Section 4.7)

Stop and restart the Agent to load the servlet.

To add a filter to an existing context, follow the steps below:

• Install the file that contains the compiled filter (Section 4.4)

• Define the filter and map the filter to one or more URL patterns (Section 4.8)

Stop and restart the Agent to load the servlet.

To add a listener to an existing context, follow the steps below:

• Install the file that contains the compiled listener (Section 4.4)

• Define the listener (Section 4.8)

Stop and restart the Agent to load the servlet.

The example below is a simple context web.xml file. The context that this file defines contains a servlet, a filter that processes requests for the servlet, and a listener. Sessions in the context time out after 10 minutes. The file declares the 404.html document in the root directory of the context as the page the servlet container will return in response to a 404 error within the context.

<web-app>

  <!-- Define and map a servlet (Section 4.7) -->
  <servlet>
   <servlet-name>HelloWorld</servlet-name>
   <servlet-class>
     servletexample.createHelloWorldExample</servlet-class>
  </servlet>
  <servlet-mapping>
   <servlet-name>HelloWorld</servlet-name>
   <url-pattern>/HelloWorldExample/*</url-pattern>
  </servlet-mapping>

  <!-- Define and map a filter (Section 4.8) -->
  <filter>
    <filter-name>simpleFilter</filter-name>
    <filter-class>servletexample.createSimpleFilter</filter-class>
  </filter>
  <filter-mapping>
    <filter-name>simpleFilter</filter-name>
    <url-pattern>/HelloWorldExample/*</url-pattern>
  </filter-mapping>

  <!-- Define a listener (Section 4.9) -->
  <listener>
    <listener-class>mylistener.createSessionListener</listener-class>
  </listener>

<!-- Define an error-page for code 404, File Not Found
    (Section 4.10) -->
  <error-page>
    <error-code>404</error-code>
    <location>404.html</location>
  </error-page>

  <!-- Define a 10 minute session timeout (Section 4.11) -->
  <session-config>
    <session-timeout>10</session-timeout>
  </session-config>

</web-app>

A production application generally has a more elaborate configuration file. A file can contain any number of servlet, filter, and listener declarations. A file may contain one session-config element, and one error-page element for each HTTP error code.

The web.xml file may be encoded in either UTF-8 or UTF-16. The container transcodes the file to UTF-8 before passing strings to a servlet or filter. Initialization parameter names, initialization parameter values, servlet names, and filter names are expressed as UTF-8 within a running container.

© Copyright Rogue Wave Software, Inc. All Rights Reserved. All Rights Reserved. Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. HydraExpress is a trademark of Rogue Wave Software, Inc. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.