A servlet is a small J2EE component designed to run on a Java Web server. It can receive and respond to requests from clients usually using HTTP. Servlets extend the capabilities of the Web server by having access to the entire spectrum of J2EE services including database access and security. Because they are written in Java, they take advantage of the portability and security that Java offers.

Servlets are created and initialized once and are generally not removed from the Web server during normal operation. Because they have a lifetime that is greater than that of a single HTTP request, there is not the overhead of creating additional operating system processes. This can greatly improve the scalability of the Web server.

Most servlets are able to serve multiple clients simultaneously. The server in which the servlet runs creates a new thread for each client request and dispatches the request to the same instance of the servlet. This is a vast departure from CGI where the Web server creates an entire new operating system process.

Servlets have a specialized class for dealing with HTTP clients such as browsers. The javax.servlet.http.HttpServlet class simplifies the delivery of dynamic content with a unified programming interface to the Web stream. It can drastically simplify the programming task of handling and generating dynamic content.

The most common way to use the servlet package is by extending HttpServlet. You then override one or more of the following methods as needed by your application.

Servlets are executed in a servlet container. A servlet container manages the life cycle of the servlet from its creation through its destruction. Unlike normal Java classes, you will never directly create a servlet class; it is created for you by the container on an event-driven model. This simplifies development, as the servlet author does not have to be concerned about creating and managing a servlet. Its lifecycle is taken care of by the servlet container.

When the servlet container needs to create a servlet, it first invokes the init() method on the servlet. This is where you would set up any resources that may be shared across multiple invocations of the service methods for your servlet. For example, we may initialize a database connection pool in the init() method so that other methods are able to use it.

After a servlet is initialized, it is ready to serve client requests. The servlet container automatically calls the service() method of a servlet when the URL requested matches the URL that the servlet has been registered to handle. The service() method is overridden in the HttpServlet and in turn, it calls the appropriate service method on the servlet based on the type of HTTP request. If your servlet has overridden the method, your method is called instead. As long as the servlet is still in the servlet container, the service() method will be called for each request.

Servlets can be removed for a variety of reasons:

When any of these events occur, the destroy() method is called on the servlet. This is where the servlet should release any resources it has acquired, such as database connections.

An important advantage of servlets over CGI programs is that servlets are, by default, multi-threaded. This means that regardless of how many clients are attempting to access the servlet there is only one instance of the servlet class in the container. In CGI, a new process is spawned for each request. Although it is important to keep in mind threading issues when developing a servlet, the reuse of a single servlet greatly expands the scalability of a servlet-based server.

If a particular servlet cannot have multiple simultaneous accesses to it, the developer can have it implement the SingleThreadModel. This is a flag to the servlet container that tells it to serialize access to the servlet so that only one thread at a time uses it. The container is also allowed to create a pool of the single threaded servlets to help with scalability.

Why would you ever need a single-threaded servlet? The biggest reason would be if the servlet was a facade on a resource that itself could not handle multiple simultaneous client requests. For example, consider that you created a print servlet that sends whatever you have in your browser over a parallel port to a printer. In this case, you would want only one client accessing that servlet at a time. If you did not you might get parts of one printout intermixed with another. However, even this may not work as the container is allowed to create a pool of these servlets and dispatch client requests to one of the instances. The WebLogic 7.0 servlet container does just this with SingleThreadModel servlets and so you would need additional synchronization outside of the servlet itself.

Listing 17.1 shows a very simple HTTP servlet that displays the parameters of a client request. The example code shows how to use the doGet() method to interact with the browser or other Web-based client.

import javax.servlet.*;
import javax.servlet.http.*;
import java.io.*;

public class MyFirstServlet extends HttpServlet
{
public void doGet( HttpServletRequest request,
    HttpServletResponse response )
    throws ServletException, IOException
    {
//
// get a simple way of putting text into the response
//
ServletOutputStream    out = response.getOutputStream();
//
// tell the client (possibly a browser) what type of document is being returned
//
response.setContentType("text/html");
//
// generate the required HTML elements
//
out.println("<html><head><title>Hello!</title></head><body>" );
//
// generate some dynamic content. the method getRemoteHost() on HttpServletRequest
// returns the host name (i.e. www.objectmind.com) from where the request came from
//
out.println( "Welcome " + request.getRemoteHost() + ".<br>" );
//
// print out the user agent information from the browser
//       out.println( "Your user agent string is " +
                    request.getHeader( "User-Agent" ) );
//
// finish the html page
//
out.println( "</body></html>" );
    }
}

The other commonly used service method is doPost(), which is called via the HTTP POST method. One way that this method could be called is if an HTML form specified “post” as its method, and gave the URL of the servlet as the action; for example, if you had an HTML file that looked like Listing 17.2.

<html>
<head>
<title>A sample form handled by a servlet</title>

<body>
<form action="http://localhost:7001/myFirstWebApp/myfirstservlet" method="post">
    Please enter your name: <input type="text" name="username">
    <input type="submit" value="Submit">
</form>

</body>
</html>

This specifies a small HTML form that would send an HTTP POST to the URL http://localhost:7001/myFirstWebApp/myfirstservlet, the same one you used for the doGet() method. The doPost() method of the servlet would be called with the same arguments as the doGet() method. However, an important difference in this example is that you want to get content that the user entered (in this case a text field labeled as “username”). The HttpServlet makes this task extremely easy, as shown in Listing 17.3.

public void doPost( HttpServletRequest request,
                    HttpServletResponse response )
    throws ServletException, IOException
{
//
// get a simple way of putting text into the response
//
ServletOutputStream    out = response.getOutputStream();
//
// tell the browser what type of document is being returned
//
response.setContentType("text/html");
//
// generate the required HTML elements
//
out.println("<html><head><title>Hello!</title></head><body>" );
//
// generate dynamic content based on the user input. the method getParameter()
// on HttpServletRequest returns the value of the named parameter from the
// POST request.
//
out.println( "Welcome to my site " + request.getParameter( "username" ) );
//
// finish the html page
//
    out.println( "</body></html>" );

}

Notice that you can get the data from the form by calling the getParameter() method on the HttpServletRequest. In this very simple example, the doPost() method is called when the user clicks on the Submit button on the HTML form. The browser packages up the parameters and sends an HTTP POST to the URL specified. It is the responsibility of the HttpServlet to then pull those parameters apart to allow access to them in the servlet.

An important part of the HttpServlet is the HttpServletRequest and the HttpServletResponse. These classes enable the developer to interact with the input and output of the Web stream. HttpServletRequest has methods that parse the HTML data stream and return these values to the caller. This is faster and less error prone than parsing the HTML directly. In our previous example, you called request.getRemoteHost() to return the name of the client that requested this servlet. This information came from the server-side socket connection that the client is using. Obviously, it is much simpler to call this method than have to deal directly with the socket semantics.

Other methods available through HttpServletRequest include the following:

The HttpServletResponse class has methods that do the opposite—build the HTTP header so that the developers do not have to generate it themselves. The ones used in our previous example, response.setContentType() and response.getOutputStream(), are the two most commonly used.

The setContentType() method enables the developer to tell the browser what kind of content will be returned. Often this is “text/html” for HTML documents, but it can also be any “mime type” that you need. Mime is an abbreviation for Multipurpose Internet Mail Extensions. These are defined methods for how messages are exchanged between two parties. Although they were originally used for electronic mail, they are also used on Web resources to describe them. RFC 2045 has pointers to more information.

The getOutputStream() method gets a javax.servlet.ServletOutputStream that allows the developer to handle the output stream the same way as any other Java stream. Simple println() methods assist in generating output.

Other methods in the HttpServletResponse class include

If you have a Web Application named myFirstWebApp, the directory structure would start out with a top-level directory named the same—myFirstWebApp. The directory structure would then look like this:

myFirstWebApp/

One way you could expand your servlet would be to add a connection to a database to retrieve, for example, the user’s account balance when he enters his username in the HTML form. The servlet reading from the database would need information such as the JDBC driver name being used along with the URL of the database.

There are many ways you could conceive of to pass initialization parameters to the servlet. You could have a file living in a particular directory or some other method. However, some of the best things that J2EE provides are simplicity and consistency across different vendor’s application server implementation.

The J2EE method of passing initialization parameters to a servlet is very simple. In the web.xml file that you created you add an XML stanza that looks like this:

<init-param>
        <param-name>dbClass</param-name>
        <param-value>org.postgresql.Driver</param-value>
</init-param>

This addition enables you to get, in this case, the class name of the database driver that you will use to connect to the database. Your code to access this initialization parameter would look like this:

public void init( ServletConfig config ) throws ServletException
{
    super.init( config);

    String dbClass = getInitParameter( "dbClass" );
}

The init() method of a servlet enables the developer to do any sort of initialization that is required before any requests are processed. As shown, this can include reading configuration parameters, but can also include, for example, getting a connection to a database to be used during processing.

As shown earlier in this chapter, you could use the init() method on a servlet to get the parameters needed to connect to the database. You would have to have parameters for the class name as we have shown, the database URL, and probably a user name and password to access the database. With this information you could modify your servlet as follows:

import javax.servlet.*;
import javax.servlet.http.*;
import java.sql.*;
import java.io.*;

public class MyFirstServlet extends HttpServlet
{
    private    Connection    connection = null;
. . .

We have added an import statement to get the JDBC-related classes and we have added a private member variable of type Connection.

Now you could modify the init() method to include the following (exception and error handling has been removed to simplify the view):

String dbURL = getInitParameter( "dbURL" );
String dbUserName = getInitParameter( "dbUserName" );
String dbUserPassword = getInitParameter( "dbUserPassword" );
Class.forName( dbClass ).newInstance();
connection = DriverManager.getConnection( dbURL, dbUserName, dbUserPassword );

Now anywhere in your servlet that you needed access to a database you could use the member variable “connection”. However, there are several problems with this approach. The biggest problem is that not all JDBC connections are thread safe. Remember that, by default, servlets are multi-threaded and that many threads could be executing your service methods simultaneously. This could lead to disastrous results in the database or at least a greatly enhanced possibility that our database would become corrupt.

What if we modified the code so that the connection was not a member variable but instead we created a new one each time we needed it? This would solve our thread problem. Each thread would get its own database connection so there would be no concurrency issues. However, creating a database connection is a fairly expensive operation. Because most Web transactions are short-lived, we would be creating and destroying connections at a fairly high rate. Additionally, what if 1,000 clients requested access to our servlet at the same time? We would quickly overload the database with client connections.

WebLogic 7.0 has two ways of improving this situation drastically: database connection pools and the J2EE DataSource.

connection.close();