javax.servlet
Interface ServletContext

public abstract interface ServletContext

A servlet engine generated object that gives servlets information about their environment.

In a server that supports the concept of multiple hosts (and even virtual hosts), the context must be at least as unique as the host. Servlet engines may also provide context objects that are unique to a group of servlets and which is tied to a specific portion of the URL path namespace of the host. This grouping may be administratively assigned or defined by deployment information.

Servlets get the ServletContext object via the getServletContext method of ServletConfig. The ServletConfig object is provided to the servlet at initialization, and is accessible via the servlet's getServletConfig method.

See Also:

Servlet.getServletConfig(), ServletConfig.getServletContext()

Method Summary

java.lang.Object	getAttribute(java.lang.String name) Returns an object that is known to the context by a given name, or null if there is no such object associated with the name.
java.util.Enumeration	getAttributeNames() Returns an enumeration of the attribute names present in this context.
ServletContext	getContext(java.lang.String uripath) Returns a ServletContext object for a particular URL path.
int	getMajorVersion() Returns the major version of the servlet API that this servlet engine supports.
java.lang.String	getMimeType(java.lang.String file) Returns the mime type of the specified file, or null if not known.
int	getMinorVersion() Returns the minor version of the servlet API that this servlet engine supports.
java.lang.String	getRealPath(java.lang.String path) Applies alias rules to the specified virtual path in URL path format, that is, /dir/dir/file.ext.
RequestDispatcher	getRequestDispatcher(java.lang.String urlpath) Returns a RequestDispatcher object for the specified URL path if the context knows of an active source (such as a servlet, JSP page, CGI script, etc) of content for the particular path.
java.net.URL	getResource(java.lang.String path) Returns a URL object of a resource that is mapped to a corresponding URL path.
java.io.InputStream	getResourceAsStream(java.lang.String path) Returns an InputStream object allowing access to a resource that is mapped to a corresponding URL path.
java.lang.String	getServerInfo() Returns the name and version of the network service under which the servlet is running.
Servlet	getServlet(java.lang.String name) Deprecated. This method has been deprecated for servlet lifecycle reasons. This method will be permanently removed in a future version of the Servlet API.
java.util.Enumeration	getServletNames() Deprecated. This method has been deprecated for servlet lifecycle reasons. This method will be permanently removed in a future version of the Servlet API.
java.util.Enumeration	getServlets() Deprecated. This method has been deprecated for servlet lifecycle reasons. This method will be permanently removed in a future version of the Servlet API.
void	log(java.lang.Exception exception, java.lang.String msg) Deprecated. Use log(String message, Throwable t) instead
void	log(java.lang.String msg) Logs the specified message to the context's log.
void	log(java.lang.String message, java.lang.Throwable throwable) Logs the specified message and a stack trace of the given Throwable object to the context's log.
void	removeAttribute(java.lang.String name) Removes the attribute from the context that is bound to a particular name.
void	setAttribute(java.lang.String name, java.lang.Object object) Binds an object to a given name in this context.

Method Detail

getContext

public ServletContext getContext(java.lang.String uripath)

Returns a ServletContext object for a particular URL path. This allows servlets to potentially gain access to the resources and to obtain RequestDispatcher objects from the target context.

In security concious environments, the servlet engine may always return null for any given URL path.

Parameters:

uripath -

getMajorVersion

public int getMajorVersion()

Returns the major version of the servlet API that this servlet engine supports. All 2.1 compliant implementations must return the integer 2 from this method.

Returns:

2

getMimeType

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

Returns the mime type of the specified file, or null if not known. The MIME type is determined according to the configuration of the servlet engine.

Parameters:

file - name of the file whose mime type is required

getMinorVersion

public int getMinorVersion()

Returns the minor version of the servlet API that this servlet engine supports. All 2.1 compliant implementations must return the integer 1 from this method.

Returns:

1

getResource

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

Returns a URL object of a resource that is mapped to a corresponding URL path. The URL path must be of the form /dir/dir/file.ext. This method allows a servlet to access content to be served from the servlet engines document space in a system independent manner. Resources could be located on the local file system, a remote file system, a database, or a remote network site.

This method may return null if there is no resource mapped to the given URL path.

The servlet engine must implement whatever URL handlers and URLConnection objects are necessary to access the given content.

This method does not fill the same purpose as the getResource method of java.lang.Class. The method in java.lang.Class looks up resources based on class loader. This method allows servlet engines to make resources avaialble to a servlet from any source without regards to class loaders, location, etc.

Parameters:

path - Path of the content resource

Throws:

java.net.MalformedURLException - if the resource path is not properly formed.

getResourceAsStream

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

Returns an InputStream object allowing access to a resource that is mapped to a corresponding URL path. The URL path must be of the form /dir/dir/file.ext.

Note that meta-information such as content length and content type that are available when using the getResource method of this class are lost when using this method.

This method may return null if there is no resource mapped to the given URL path.

The servlet engine must implement whatever URL handlers and URLConnection objects are necessary to access the given content.

This method does not fill the same purpose as the getResourceAsStream method of java.lang.Class. The method in java.lang.Class looks up resources based on class loader. This method allows servlet engines to make resources avaialble to a servlet from any source without regards to class loaders, location, etc.

Parameters:

name -

getRequestDispatcher

public RequestDispatcher getRequestDispatcher(java.lang.String urlpath)

Returns a RequestDispatcher object for the specified URL path if the context knows of an active source (such as a servlet, JSP page, CGI script, etc) of content for the particular path. This format of the URL path must be of the form /dir/dir/file.ext. The servlet engine is responsible for implementing whatever functionality is required to wrap the target source with an implementation of the RequestDispatcher interface.

This method will return null if the context cannot provide a dispatcher for the path provided.

Parameters:

urlpath - Path to use to look up the target server resource

See Also:

RequestDispatcher

getServlet

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

Deprecated. This method has been deprecated for servlet lifecycle reasons. This method will be permanently removed in a future version of the Servlet API.

Originally defined to return a servlet from the context with the specified name. This method has been deprecated and only remains to preserve binary compatibility. This method will always return null.

getServlets

public java.util.Enumeration getServlets()

Deprecated. This method has been deprecated for servlet lifecycle reasons. This method will be permanently removed in a future version of the Servlet API.

Originally defined to return an Enumeration of Servlet objects containing all the servlets known to this context. This method has been deprecated and only remains to preserve binary compatibility. This method must always return an empty enumeration.

getServletNames

public java.util.Enumeration getServletNames()

Deprecated. This method has been deprecated for servlet lifecycle reasons. This method will be permanently removed in a future version of the Servlet API.

Originally defined to return an Enumeration of String objects containing all the servlet names known to this context. This method has been deprecated and only remains to preserve binary compatibility. This methd must always return an empty enumeration.

log

public void log(java.lang.String msg)

Logs the specified message to the context's log. The name and type of the servlet log is servlet engine specific, but is normally an event log.

Parameters:

msg - the message to be written

log

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

Deprecated. Use log(String message, Throwable t) instead

Logs the specified message and a stack trace of the given exception to the context's log. The name and type of the servlet log is servlet engine specific, but is normally an event log.

Parameters:

exception - the exception to be written

msg - the message to be written

log

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

Logs the specified message and a stack trace of the given Throwable object to the context's log. The name and type of the servlet log is servlet engine specific, but is normally an event log.

Parameters:

msg - the message to be written

throwable - the exception to be written

getRealPath

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

Applies alias rules to the specified virtual path in URL path format, that is, /dir/dir/file.ext. Returns a String representing the corresponding real path in the format that is appropriate for the operating system the servlet engine is running under (including the proper path separators).

This method returns null if the translation could not be performed for any reason.

Parameters:

path - the virtual path to be translated into a real path

getServerInfo

public java.lang.String getServerInfo()

Returns the name and version of the network service under which the servlet is running. The form of this string must begin with <servername>/<versionnumber>. For example the Java Web Server could return a string of the form Java Web Server/1.1.3. Other optional information can be returned in parenthesis after the primary string. For example, Java Web Server/1.1.3 (JDK 1.1.6; Windows NT 4.0 x86) .

getAttribute

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

Returns an object that is known to the context by a given name, or null if there is no such object associated with the name. This method allwos access to additional information about the servlet engine not already provided by other methods in this interface. Attribute names should follow the same convention as package names. Names matching java.*, javax.*, and sun.* are reserved for definition by this specification or by the reference implementation.

Parameters:

name - the name of the attribute whose value is required

Returns:

the value of the attribute, or null if the attribute does not exist.

getAttributeNames

public java.util.Enumeration getAttributeNames()

Returns an enumeration of the attribute names present in this context.

setAttribute

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

Binds an object to a given name in this context. If an object is allready bound into the context with the given name, it will be replaced. Attribute names should follow the same convention as package names. Names matching java.*, javax.*, and sun.* are reserved for definition by this specification or by the reference implementation.

Parameters:

name - the name of the attribute to store

value - the value of the attribute

removeAttribute

public void removeAttribute(java.lang.String name)

Removes the attribute from the context that is bound to a particular name.

Parameters:

name - the name of the attribute to remove from the context