The ServletContext Class

The ServletContext object, available to both JSP and servlets via the getServletContext method, contains information about the servlet engine and the servlet environment. It provides an application-level view to your component.

Getting the Server Version

There are three methods you can use to get information about the server version and the Servlet API version:

public int getMajorVersion()
public int getMinorVersion()
public String getServerInfo()

If you are running with version 2.4 of the servlet API, getMajorVersion returns 2, and getMinorVersion returns 4. The getServerInfo method returns the name and version of the server separated by slashes. The current version of Tomcat returns the following server version:

Apache Tomcat/5.0

Getting the Context Name

The name of the context, as defined in the deployment descriptor by the display-name element, is obtained by using getServletContextName:

public String getServletContextName()

Initialization Parameters

The ServletContext object contains the same getInitParameterNames and getInitParameter methods that we discussed earlier in the book:

public java.util.Enumeration getInitParameterNames()
public String getInitParameter(String name)

These methods return information for an entire Web application, not just for a specific servlet.

Saving Application-Wide Objects

All the servlets and JSPs within an application can share objects when they are stored in the ServletContext object. The getAttribute, setAttribute, and removeAttribute methods work just like the ones in the ServletRequest class, except that the objects are visible to the entire application:

public Object getAttribute(String name)
public void setAttribute(String name, Object attr)
public void removeAttribute(String name)

Just as with the request object, you can get a list of the attribute names available in the ServletContext object by calling getAttributeNames:

public java.util.Enumeration getAttributeNames()

Logging Messages

One of the difficulties with debugging a server is that you can't easily see what is going on. After all, with a desktop application, you can see a dialog box pop up with an error message. Most developers writing a server application end up writing their own logging routines so they can gain some visibility into what the server is doing. The ServletContext object supplies two logging methods:

public void log(String message)
public void log(String message, Throwable throwable)

Although these methods are part of the standard Servlet API, the location of the log file varies between servers. When you pass a Throwable object to the log method, the server prints a stack trace to the log file.

Calling Other Servlets and JSPs

You use a RequestDispatcher object to include or forward to another JSP or servlet. You use the ServletContext object to locate the request dispatcher via either the getRequestDispatcher or getNamedDispatcher methods:

public RequestDispatcher getRequestDispatcher(String url)
public RequestDispatcher getNamedDispatcher(String name)

The request dispatcher enables you to access any resource on the local server. You aren't restricted to just servlets and JSPs. You can include an HTML file if you want. When you use getRequestDispatcher, the URL that you pass to the method must start with a /. Most of the time, you can think of the path as being relative to the server root. The / is actually relative to the context root in which the servlet or JSP is running.

The getNamedDispatcher method lets you refer to a servlet by its name as opposed to the path. The name in this case is the name specified in the web.xml file in the application's WAR file. For example, a servlet might be defined using the following tags:

<servlet>
    <servlet-name>shopping</servlet-name>
    <servlet-class>examples.cart.ShoppingCartServlet</servlet-class>
</servlet>

You can access this servlet with the line:

getServletContext().getNamedDispatcher("shopping");

One advantage of getNamedDispatcher is that it allows you to access servlets that are not directly available to users. When you use getRequestDispatcher to access a servlet, the servlet must have a URL mapping configured in the web.xml file. When this mapping is present, any browser can access the servlet. The getNamedDispatcher method doesn't require a URL mapping, however.

When you need to obtain a resource or obtain a RequestDispatcher that belongs to another context, getContext retrieves a reference to the context you need:

public ServletContext getContext(String uripath)

Accessing Application Resources

An application often requires additional resources other than its servlets and JSPs. You might need data files, image files, or sound files. When you install your application, you can copy all the files into one or more directories, or you can package all the necessary files into a WAR file (similar to a JAR file). You can use getResource and getResourceAsStream to retrieve these resources:

public java.net.URL getResource(java.lang.String path)
    throws java.net.MalformedURLException

public java.io.InputStream getResourceAsStream(
    java.lang.String path)

Using getResourcePaths, you can get a directory-like listing of resources available within a context:

public java.util.Set getResourcePaths(java.lang.String path)

If you need to access a resource directly, getRealPath takes a path that is appropriate to the context and returns an absolute file path that is appropriate to the server's file-system.

public String getRealPath(String path)