Introduction to Java Servlets

A servlet is an application that uses the Java Servlet API (application programming interface) to deliver dynamically generated content via a web server. More technically, the Java Servlet API defines the interactions between a web container and a Java application, where a web container is the logical component of a web server that communicates with Java entities such as servlets.

This article will demonstrate how to code servlets using the Java Servlet API. The basic servlet code is applicable across a variety of web containers, including the widely available (and free) Tomcat, WebLogic and others.

Java Servlet API

The API is contained in the javax.servlet package hierarchy. The API was originally created in 1997 with version 1.0, but there was no formal specification until version 2.1 arrived in 1998. As of May 2006, the current version of the specification is 2.5.

A servlet is basically a Java class that extends the javax.servlet.HttpServlet class. Within this class, there are really only five methods that a servlet developer needs to know about:

• public void init(ServletConfig config)
   
  This method is called once when the servlet is first loaded by the container, before the servlet can even process its first request.

• public void service(ServletRequest request, ServletResponse response)
   
  This method is called whenever a servlet request needs to be processed. If the request represents an HTTP GET request (such as a normal request for a web page), then the doGet method will be called. If the request represents an HTTP POST request (such as the submission of a form), then the doPost method will be called. Multiple threads (one per request) can execute this method in parallel, so it must be thread-safe.

• protected void doGet(HttpServletRequest request, HttpServletResponse response)
   
  This method handles HTTP GET requests. It may be called by multiple threads, so it must be coded in a thread-safe manner.

• public void doPost(HttpServletRequest request, HttpServletResponse response)
   
  This method handles HTTP POST requests, which generally represent submissions from a form. It may be called by multiple threads, so it must be coded in a thread-safe manner.

• public void destroy()
   
  This method is called once just before the servlet is unloaded by the container and taken out of service.

To create a servlet, developers extend the javax.servlet.HttpServlet class, overriding the above methods as needed to implement their desired functionality. In practice, developers should never override the service method; they should instead provide implementations for the doGet or doPost methods. Initialization tasks, if any, can be performed in the init method. Likewise, cleanup tasks, if any, can be performed in the destroy method.

It sounds more complicated than it really is. My guess is that 98% of servlets only implement one method, either the doGet or doPost methods.

A Simple Servlet

OK, it's time to create a really simple servlet. This servlet is going to respond to a request by simply returning an HTML web page with the text "Hello, World!" as the page content. The servlet is shown in Listing 1 below:

The HelloServlet class extends the HttpServlet class, providing an implementation for the doGet method. This method generates the HTML that will be sent back to the requester.

What it's really doing is providing content for the response object that will be sent back. To eliminate any possible confusion, the method calls the setContentType method of the HttpServletResponse parameter to ensure that the requester knows that what is being provided is HTML content (as opposed to XML, a PDF file, an image or other types of content).

Next, the method calls the getWriter method to get access to a PrintWriter object for the response. This allows content to be dynamically inserted into the response object.

Information Available to Servlets

The doGet and doPost methods both accept the same parameters: HttpServletRequest and HttpServletResponse, generally referred to as simply the request and response objects. The servlet also has access to the System object, which provides information about the web server environment. The request object provides the developer with the capability to access a wide range of information, including cookies, URL parameters, data items posted from a form, HTTP headers and local (to the server) environment variables. Likewise, the response object provides developers with the capability to tailor the output that will be sent back to the requester.

Listing 2 shows how to access information available in the request object. Add this code to the doGet method of the simple servlet from the previous section. First, the code shows the output of many of the methods provided by the request object. For example, the getMethod method shows whether the request is a GET or POST request. Not all of these values will be provided by every web server.

Next, the code checks for any parameters that may have been passed to the servlet. Parameters can either be passed as part of the URL or posted from a form. An example of passing a URL parameter to a servlet is shown below, with the test parameter:

There are some things to remember about accessing parameters from the request object. As mentioned before, parameters can appear as part of a URL or be posted from a form. It's also possible for a form to have multiple fields with the same name, i.e. - it's possible for a parameter to have multiple values. Accordingly, you can use getParameterNames to get a list of the available parameters. Then you can use getParameterValues to get a string array containing all of the values for that parameter.

Alternately, if you know that a parameter will only have one value, you can use the getParameter method (note that the method name is singular) to retrieve just one value for a parameter (if you're wrong, and there are multiple values, only the first one will be returned).

The getHeaderNames method can be used to retrieve HTTP headers associated with the request. This information isn't commonly needed for a servlet, but it's still available. Cookies are also accessible from the request object.

The last section of code retrieves the names and values of environment variables that are defined in the environment in which the web server is running. Environment variables are not available from the request object, but they are available from the System object.

The output of a sample run of the servlet using Tomcat is shown below, and clearly illustrates the type of information that is accessible from within a servlet. In fact, I've found this servlet, and the information that it provides, useful for debugging web server configuration issues, as it answers the question: "Now what information is my application actually getting?"

Thread-Safe Code

At any given time, multiple threads could be executing the doGet or doPost methods. When coding a servlet, it's necessary to code a servlet in a thread-safe manner. Great. But what does that mean?

Well, it's actually pretty simple. Basically, this means no global variables, i.e. - no class-level variables that are shared across instances of your class because multiple threads might access the shared variable at the same time. You'll have to code with an eye towards making sure that your methods are essentially self-contained.

If your methods absolutely must access shared elements, Java does support locking features to serialize access to objects. However, that's generally not required, and also somewhat out-of-scope for this article. I've never had to worry about locking in the servlets that I've done.

Configuration Settings

Well, you've seen how create a simple servlet that sends HTML back to the requester. But you probably want to do more than that. It would be nice to be able to make some configuration settings available to the servlet. As a prime example, you might want to have database connection information specified in way that is accessible throughout an entire web application, including from within servlets.

When it comes to configuration settings, you're entering an area that may potentially differ between web containers. This section describes how to set up configuration settings using Tomcat; the details are likely to be similar for other web containers.

Servlets have access to a ServletContext object that, in turn, provides access to application-specific settings. For Tomcat, configuration settings are defined in a file called "web.xml". The ServletContext class provides the getInitParameter method, which allows configuration settings to be retrieved. Within a servlet, the following code can be used to access a user-defined "DBINFO" parameter defined in the "web.xml" file.

   String dbinfo = getServletContext().getInitParameter("DBINFO");
   if (dbinfo != null)
   {
      // Do something with the value
   }

Within the "web.xml" file for the application, configuration settings can be defined using the <context-param> construct, as shown below:

   <context-param>
      <param-name>DBINFO</param-name>
      <param-value>oracle,127.0.0.1,1521,test,2Rbpg+ek=,TESTDB</param-value>
      <description>Database connection info</description>
   </context-param>

In this example, the context parameter is named "DBINFO". This parameter has a value that includes a comma-delimited set of data items related to establishing a database connection. Specifically, the list includes the type of database, the host where the database can be found, the name of the user account for the database, the encrypted account password and the name of the database.

Again, this is only an example. Clearly, using this technique, you can define whatever configuration settings your web application, and your servlets, will need.

Conclusion

The Java Servlet API provides a powerful and effective way to dynamically generate and deliver content to users. The API ensures that detailed information about each request is available to developers and provides extensive capabilities for tailoring the response that is sent back.

The API also provides a useful platform for other Java technologies, notably Java Server Pages (JSP). With JSP pages, users integrate Java functionality into HTML templates, which are then automatically compiled into Java servlets.