Book Home Java Servlet Programming Search this book

Chapter 4. Retrieving Information

Contents:

Initialization Parameters
The Server
The Client
The Request

To build a successful web application, you often need to know a lot about the environment in which it is running. You may need to find out about the server that is executing your servlets or the specifics of the client that is sending requests. And no matter what kind of environment the application is running in, you most certainly need information about the requests that the application is handling.

Servlets have a number of methods available to gain access to this information. For the most part, each method returns one specific result. If you compare this to the way environment variables are used to pass a CGI program its information, the servlet approach has several advantages:

If you're coming to servlets from CGI, Table 4-1 is a "cheat sheet" you can use for your migration. It lists each CGI environment variable and the corresponding HTTP servlet method.

Table 4-1. CGI Environment Variables and the Corresponding Servlet Methods

CGI Environment Variable

HTTP Servlet Method

SERVER_NAME

req.getServerName()

SERVER_SOFTWARE

getServletContext().getServerInfo()

SERVER_PROTOCOL

req.getProtocol()

SERVER_PORT

req.getServerPort()

REQUEST_METHOD

req.getMethod()

PATH_INFO

req.getPathInfo()

PATH_TRANSLATED

req.getPathTranslated()

SCRIPT_NAME

req.getServletPath()

DOCUMENT_ROOT

req.getRealPath("/")

QUERY_STRING

req.getQueryString()

REMOTE_HOST

req.getRemoteHost()

REMOTE_ADDR

req.getRemoteAddr()

AUTH_TYPE

req.getAuthType()

REMOTE_USER

req.getRemoteUser()

CONTENT_TYPE

req.getContentType()

CONTENT_LENGTH

req.getContentLength()

HTTP_ACCEPT

req.getHeader("Accept")

HTTP_USER_AGENT

req.getHeader("User-Agent")

HTTP_REFERER

req.getHeader("Referer")

In the rest of this chapter, we'll see how and when to use these methods--and several other methods that have no CGI counterparts. Along the way, we'll put the methods to use in some real servlets.

4.1. Initialization Parameters

Each registered servlet name can have specific initialization (init) parameters associated with it. Init parameters are available to the servlet at any time; they are often used in init() to set initial or default values for a servlet or to customize the servlet's behavior in some way. Init parameters are more fully explained in Chapter 3, "The Servlet Life Cycle".

4.1.1. Getting an Init Parameter

A servlet uses the getInitParameter() method to get access to its init parameters:

public String ServletConfig.getInitParameter(String name)

This method returns the value of the named init parameter or null if it does not exist. The return value is always a single String. It is up to the servlet to interpret the value.

The GenericServlet class implements the ServletConfig interface and thus provides direct access to the getInitParameter() method.[1] The method is usually called like this:

[1] The servlet must call super.init(config) in its init() method to get this functionality.

public void init(ServletConfig config) throws ServletException {
  super.init(config);
  String greeting = getInitParameter("greeting");
}

A servlet that needs to establish a connection to a database can use its init parameters to define the details of the connection. We can assume a custom establishConnection() method to abstract away the details of JDBC, as shown in Example 4-1.

Example 4-1. Using init parameters to establish a database connection

java.sql.Connection con = null;

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

  String host = getInitParameter("host");
  int port = Integer.parseInt(getInitParameter("port"));
  String db = getInitParameter("db");
  String user = getInitParameter("user");
  String password = getInitParameter("password");
  String proxy = getInitParameter("proxy");

  con = establishConnection(host, port, db, user, password, proxy);
}

4.1.2. Getting Init Parameter Names

A servlet can examine all its init parameters using getInitParameterNames() :

public Enumeration ServletConfig.getInitParameterNames()

This method returns the names of all the servlet's init parameters as an Enumeration of String objects or an empty Enumeration if no parameters exist. It's most often used for debugging.

The GenericServlet class also makes this method directly available to servlets. Example 4-2 shows a servlet that prints the name and value for all of its init parameters.

Example 4-2. Getting init parameter names

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

public class InitSnoop extends GenericServlet {

  // No init() method needed

  public void service(ServletRequest req, ServletResponse res) 
                             throws ServletException, IOException {
    res.setContentType("text/plain");
    PrintWriter out = res.getWriter();

    out.println("Init Parameters:");
    Enumeration enum = getInitParameterNames();
    while (enum.hasMoreElements()) {
      String name = (String) enum.nextElement();
      out.println(name + ": " + getInitParameter(name));
    }
  }
}

Notice that this servlet directly subclasses GenericServlet, showing that init parameters are available to servlets that aren't HTTP servlets. A generic servlet can be used in a web server even though it lacks any support for HTTP-specific functionality.

Unfortunately, there's no server-independent way for a servlet to ask for its registered name or its class file location. This information may be added in a future version of the Servlet API. Until then, although it's not pretty, this information can be passed using init parameters where necessary. Also, some servers--including the Java Web Server--provide a back door whereby a servlet can get its registered name. If a servlet defines a method with the following signature, the server calls it and passes it the servlet's registered name at initialization:

public void setServletName(String name);

The servlet can save the passed-in name and use it later. You'll notice this back door was built without changing the Servlet API, a necessary requirement because, by the time it was added, the Servlet API 2.0 had already been frozen.



Library Navigation Links

Copyright © 2001 O'Reilly & Associates. All rights reserved.