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.
<servlet>
<servlet-name>HelloWorld</servlet-name>
<servlet-class>rwsf_servlet_example.createHelloWorldExample</servlet-class>
</servlet>
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 shared library (.dll or .so) 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 shared library is the name of the library without the platform-specific prefix (if any), without the
12d or
15d suffix, 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
Defining Filters, Servlets, and Listeners. Note that the name of this function must be a legal C++ identifier.
The servlet element below defines a servlet named HelloWorld. The servlet shared library has the base name rwsf_servlet_example, and the container calls the function createHelloWorld to load the servlet instance. Notice that the name of the servlet instance does not need to correspond to the class name.
<servlet>
<servlet-name>HelloWorld</servlet-name>
<servlet-class>rwsf_servlet_example.createHelloWorldExample</servlet-class>
</servlet>
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:
<servlet>
<servlet-name>getStatus</servlet-name>
<servlet-class>status.createStatusServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>getFullStatus</servlet-name>
<servlet-class>status.createStatusServlet</servlet-class>
</servlet>
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 program, so the exact parameter names and values required depend on the individual servlet. (See below for an example of the corresponding servlet code.) 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.
<servlet>
<servlet-name>getStatus</servlet-name>
<servlet-class>status.createStatusServlet</servlet-class>
<init-param>
<param-name>output</param-name>
<param-value>brief</param-value>
</init-param>
</servlet>
<servlet>
<servlet-name>getFullStatus</servlet-name>
<servlet-class>status.createStatusServlet</servlet-class>
<init-param>
<param-name>output</param-name>
<param-value>verbose</param-value>
</init-param>
</servlet>
Here is an example of the servlet code that might retrieve the initiation parameter.
rwsf::ServletConfig config = getServletConfig();
rwsf::ServletContext context = config.getServletContext();
std::string initParam = context.getInitParameter("output");
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.
