javax.servlet
Interface ServletContext

public abstract interface ServletContext

Defines a set of methods that a servlet uses to communicate with a servlet engine, for example, to get the MIME type of a file, locate other servlets running on the server, or write to a servlet log file.

The servlet engine talks to the servlet by returning a ServletContext object (defined by this interface) that gives servlets information about their environment. Servlets use the ServletConfig.getServletContext() method to get the ServletContext object.

If the server supports multiple or virtual hosts, the ServletContext object must be at least as unique as the host. Servlet engines can also create ServletContext objects that are unique to a group of servlets and are tied to a specific part of the host's URL namespace. You can assign this grouping administratively or define it in a deployment descriptor file.

The ServletContext object is contained within the ServletConfig object, which the Web server provides the servlet when the servlet is initialized. You can access the ServletConfig object by using the Servlet.getServletConfig() method.

Version:

$Version$

Author:

Various

See Also:

Servlet.getServletConfig(), ServletConfig.getServletContext()

Method Summary

java.lang.Object	getAttribute(java.lang.String name) Returns the servlet engine attribute with the given name, or null if there is none.
java.util.Enumeration	getAttributeNames() Returns an Enumeration containing the attribute names available within this servlet context.
ServletContext	getContext(java.lang.String uripath) Returns a ServletContext object that corresponds to a specified URL on the server.
int	getMajorVersion() Returns the major version of the Java Servlet API that this Web server supports.
java.lang.String	getMimeType(java.lang.String file) Returns the MIME type of the specified file, or null if the MIME type is not known.
int	getMinorVersion() Returns the minor version of the Servlet API that this Web server supports.
java.lang.String	getRealPath(java.lang.String path) Returns a String containing the real path that corresponds to a virtual path.
RequestDispatcher	getRequestDispatcher(java.lang.String urlpath) Returns a RequestDispatcher object that acts as a wrapper for the resource located at the named path.
java.net.URL	getResource(java.lang.String path) Returns the resource that is mapped to a specified path.
java.io.InputStream	getResourceAsStream(java.lang.String path) Returns the resource located at the named path as an InputStream object.
java.lang.String	getServerInfo() Returns the name and version of the servlet engine on which the servlet is running.
Servlet	getServlet(java.lang.String name) Deprecated. As of Java Servlet API 2.1, with no replacement. This method was originally defined to retrieve a servlet from a ServletContext. In this version, this method always returns null and remains only to preserve binary compatibility. This method will be permanently removed in a future version of the Java Servlet API.
java.util.Enumeration	getServletNames() Deprecated. As of Java Servlet API 2.1, with no replacement. This method was originally defined to return an Enumeration of all the servlet names known to this context. In this version, this method always returns an empty Enumeration and remains only to preserve binary compatibility. This method will be permanently removed in a future version of the Java Servlet API.
java.util.Enumeration	getServlets() Deprecated. As of Java Servlet API 2.0, with no replacement. This method was originally defined to return an Enumeration of all the servlets known to this servlet context. In this version, this method always returns an empty enumeration and remains only to preserve binary compatibility. This method will be permanently removed in a future version of the Java Servlet API.
void	log(java.lang.Exception exception, java.lang.String msg) Deprecated. As of Java Servlet API 2.1, use log(String message, Throwable throwable) instead. This method was originally defined to write an exception's stack trace and an explanatory error message to the servlet log file.
void	log(java.lang.String msg) Writes the specified message to a servlet log file, which is usually an event log.
void	log(java.lang.String message, java.lang.Throwable throwable) Writes the stack trace and an explanatory message for a given Throwable exception to the servlet log file.
void	removeAttribute(java.lang.String name) Removes the attribute with the given name from the servlet context.
void	setAttribute(java.lang.String name, java.lang.Object object) Gives an attribute a name in this servlet context.

Method Detail

getContext

public ServletContext getContext(java.lang.String uripath)

Returns a ServletContext object that corresponds to a specified URL on the server.

This method allows servlets to gain access to the resources located at a specified URL and obtain RequestDispatcher objects from it.

In security conscious environments, the servlet engine can return null for a given URL.

Parameters:

uripath - a String specifying the URL for which you are requesting a ServletContext object

Returns:

the ServletContext object that corresponds to the named URL

See Also:

RequestDispatcher

getMajorVersion

public int getMajorVersion()

Returns the major version of the Java Servlet API that this Web server supports. All implementations that comply with Version 2.1 must have this method return the integer 2.

Returns:

2

getMimeType

public java.lang.String getMimeType(java.lang.String file)

Returns the MIME type of the specified file, or null if the MIME type is not known. The MIME type is determined by the configuration of the servlet engine. Common MIME types are "text/html" and "image/gif".

Parameters:

a - String specifying the name of the file whose MIME type you want to check

Returns:

a String specifying the MIME type

getMinorVersion

public int getMinorVersion()

Returns the minor version of the Servlet API that this Web server supports. All implementations that comply with Version 2.1 must have this method return the integer 1.

Returns:

1

getResource

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

Returns the resource that is mapped to a specified path. The path must be in the form /dir/dir/file.ext.

This method allows the Web server to make a resource available to a servlet from any source. Resources can be located on a local or remote file system, in a database, or on a remote network site.

This method can return null if no resource is mapped to the pathname.

The servlet engine must implement the URL handlers and URLConnection objects that are necessary to access the resource.

This method has a different purpose than java.lang.Class.getResource, which looks up resources based on a class loader. This method does not use class loaders.

Parameters:

path - a String specifying the path to the resource, in the form /dir/dir/file.ext

Returns:

the resource located at the named path, or null if there is no resource at that path

Throws:

java.net.MalformedURLException - if the pathname is not given in the correct form

getResourceAsStream

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

Returns the resource located at the named path as an InputStream object.

The data in the InputStream can be of any type or length. The path must be of the form /dir/dir/file.ext. This method returns null if no resource exists at the specified path.

Metainformation such as content length and content type that is available when you use the getResource method is lost when you use this method.

The servlet engine must implement the URL handlers and URLConnection objects necessary to access the resource.

This method is different from java.lang.Class.getResourceAsStream, which uses a class loader. This method allows servlet engines to make a resource available to a servlet from any location, without using a class loader.

Parameters:

name - a String specifying the path to the resource, in the form /dir/dir/file.ext

Returns:

the InputStream returned to the servlet, or null if no resource exists at the specified path

getRequestDispatcher

public RequestDispatcher getRequestDispatcher(java.lang.String urlpath)

Returns a RequestDispatcher object that acts as a wrapper for the resource located at the named path. You can use a RequestDispatcher object to forward a request to the resource or include a resource in a response.

The pathname must be in the form /dir/dir/file.ext. This method returns null if the ServletContext cannot return a RequestDispatcher.

The servlet engine is responsible for wrapping the resource with a RequestDispatcher object.

Parameters:

urlpath - a String specifying the pathname to the resource

Returns:

a RequestDispatcher object that acts as a wrapper for the resource at the path you specify

See Also:

RequestDispatcher

getServlet

public Servlet getServlet(java.lang.String name)
                   throws ServletException

Deprecated. As of Java Servlet API 2.1, with no replacement.

This method was originally defined to retrieve a servlet from a ServletContext. In this version, this method always returns null and remains only to preserve binary compatibility. This method will be permanently removed in a future version of the Java Servlet API.

getServlets

public java.util.Enumeration getServlets()

Deprecated. As of Java Servlet API 2.0, with no replacement.

This method was originally defined to return an Enumeration of all the servlets known to this servlet context. In this version, this method always returns an empty enumeration and remains only to preserve binary compatibility. This method will be permanently removed in a future version of the Java Servlet API.

getServletNames

public java.util.Enumeration getServletNames()

Deprecated. As of Java Servlet API 2.1, with no replacement.

This method was originally defined to return an Enumeration of all the servlet names known to this context. In this version, this method always returns an empty Enumeration and remains only to preserve binary compatibility. This method will be permanently removed in a future version of the Java Servlet API.

log

public void log(java.lang.String msg)

Writes the specified message to a servlet log file, which is usually an event log. The message provides explanatory information about an exception or error or an action the servlet engine takes. The name and type of the servlet log file is specific to the servlet engine.

Parameters:

msg - a String specifying the explanatory message to be written to the log file

log

public void log(java.lang.Exception exception,
                java.lang.String msg)

Deprecated. As of Java Servlet API 2.1, use log(String message, Throwable throwable) instead.

This method was originally defined to write an exception's stack trace and an explanatory error message to the servlet log file.

log

public void log(java.lang.String message,
                java.lang.Throwable throwable)

Writes the stack trace and an explanatory message for a given Throwable exception to the servlet log file. The stack trace is part of the Throwable object, and the message is the one you specify in the message parameter. The name and type of the servlet log file is specific to the servlet engine, but it is usually an event log.

Parameters:

message - a String that describes the error or exception

throwable - the Throwable error or exception

getRealPath

public java.lang.String getRealPath(java.lang.String path)

Returns a String containing the real path that corresponds to a virtual path. A virtual path contains a servlet name followed by the name of a file the servlet should act upon, in the form /dir/dir/servlet/file.ext. In this form, file.ext is a filename used instead of the path to the file. The servlet locates the file and translates the file name to the path that locates the file.

The real path the servlet returns is in a form appropriate to the computer and operating system on which the servlet engine is running, including the proper path separators. This method returns null if the servlet engine cannot translate the virtual path to a real path for any reason.

Parameters:

path - a String specifying a virtual path, in the form /dir/dir/servlet/file.ext

Returns:

a String specifying the real path, with path separators appropriate for the system on which the servlet engine is running

getServerInfo

public java.lang.String getServerInfo()

Returns the name and version of the servlet engine on which the servlet is running.

The form of the returned string is servername/versionnumber. For example, the Java Web Server can return the string Java Web Server/1.1.3.

You can design the servlet engine to have this method return other optional information in parentheses after the primary string, for example, Java Web Server/1.1.3 (JDK 1.1.6; Windows NT 4.0 x86).

Returns:

a String containing at least the servlet engine name and version number

getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Returns the servlet engine attribute with the given name, or null if there is none. An attribute allows a servlet engine to give the servlet additional information not already provided by this interface. See your Web server documentation for information about its attributes.

The attribute is returned as a java.lang.Object. Attribute names should follow the same convention as package names. The Java Servlet API specification reserves names matching java.*, javax.*, and sun.*.

Parameters:

name - a String specifying the name of the attribute

Returns:

an Objectnull if no attribute exists matching the given name

getAttributeNames

public java.util.Enumeration getAttributeNames()

Returns an Enumeration containing the attribute names available within this servlet context. You can use the getAttribute(java.lang.String) method with an attribute name to get the value of an attribute.

Returns:

an Enumeration of attribute names

See Also:

getAttribute(java.lang.String)

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object object)

Gives an attribute a name in this servlet context. If the name specified is already used for an attribute, this method will overwrite the old attribute and bind the name to the new attribute.

Attribute names should follow the same convention as package names. The Java Servlet API specification reserves names matching java.*, javax.*, and sun.*.

Parameters:

name - a String specifying the name of the attribute

object - an Object representing the attribute to be given the name

removeAttribute

public void removeAttribute(java.lang.String name)

Removes the attribute with the given name from the servlet context. If you remove an attribute, and then use getAttribute(java.lang.String) to retrieve the attribute's value, getAttribute returns null.

Parameters:

name - a String specifying the name of the attribute to be removed