javax.servlet
Interface ServletContext

public abstract interface ServletContext

A class created by the server to give servlets access to certain environment related objects and methods.
It contains standard information like the names of all the servlets, two kinds of log methods, the server name, etc.
The server can also store extra information here in the form of {String, Object} pairs. Different servlets can live in different ServletContexts, but a servlet engine can group related Servlets in the same ServletContext.
Servlet specific information can be transferred to a servlet using a class implementing the ServletConfig interface.

Since:
Servlet API 1.0
Version:
Servlet API 2.1

Method Summary
 java.lang.Object getAttribute(java.lang.String name)
          Gets the value of a named attribute
 java.util.Enumeration getAttributeNames()
          Gets an enumeration containing all the attribute names
 ServletContext getContext(java.lang.String UriPath)
          Gives the ServletContext of another servlet indicated by the UriPath on the same server.
 int getMajorVersion()
          Major version number of the Servlet API the servlet engine supports.
 java.lang.String getMimeType(java.lang.String filename)
          Gives the mimetype of the requested file
 int getMinorVersion()
          Minor version number of the Servlet API the servlet engine supports.
 java.lang.String getRealPath(java.lang.String virtualPath)
          Translates the requested virtual path to the real filesystem path using the servers knowledge of the document root.
 RequestDispatcher getRequestDispatcher(java.lang.String UriPath)
          Returns a RequestDispatcher to forward requests or include responses from another (active) resource.
 java.net.URL getResource(java.lang.String virtualPath)
          Translates the requested virtual path to an URL object that can be accesed by the servlet.
 java.io.InputStream getResourceAsStream(java.lang.String virtualPath)
          A convenience method for getResource(virtualPath).openStream().
 java.lang.String getServerInfo()
          A server supplied string containing the server name, version number, etc
 Servlet getServlet(java.lang.String name)
          Deprecated. Always returns null. Since the servlet engine cannot know if a servlet ever gives up the reference to another servlet it could never destroy the servlet after this call. Only the servlet engine should have references to Servlets.
 java.util.Enumeration getServletNames()
          Deprecated. Always returns an empty Enumeration. Only the servlet engine should have references to Servlets.
 java.util.Enumeration getServlets()
          Deprecated. Always returns an empty Enumeration. Only the servlet engine should have references to Servlets.
 void log(java.lang.Exception exception, java.lang.String message)
          Deprecated. Use log(String, Throwable) which is more general.
 void log(java.lang.String message)
          Writes a message to the log
 void log(java.lang.String message, java.lang.Throwable t)
          Writes an exception + message to the log
 void removeAttribute(java.lang.String name)
          Removes the named object from the ServletContext
 void setAttribute(java.lang.String name, java.lang.Object o)
          Puts a named object into the ServletContext.
 

Method Detail

getAttribute

public java.lang.Object getAttribute(java.lang.String name)
Gets the value of a named attribute
Parameters:
name - the name of the attribute
Returns:
the value of the attribute or null if there is no attribute with this name
Since:
Servlet API 1.0

getAttributeNames

public java.util.Enumeration getAttributeNames()
Gets an enumeration containing all the attribute names
Returns:
The enumeration containing all the attribute names
Since:
Servlet API 2.1

getContext

public ServletContext getContext(java.lang.String UriPath)
Gives the ServletContext of another servlet indicated by the UriPath on the same server. For security reasons this can return null even if there is an active servlet at that location. This can then be used to set attributes in the context of another servlet.
Parameters:
UriPath - The path to the servlet, such as /servlet/ShowBook
Returns:
ServletContext of the requested servlet or null if there is no servlet at the requested UriPath or when it is unavailable due to security restrictions
Since:
Servlet API 2.1
See Also:
setAttribute(java.lang.String, java.lang.Object)

getMajorVersion

public int getMajorVersion()
Major version number of the Servlet API the servlet engine supports.
Returns:
2 if the 2.1 Servlet API is supported
Since:
Servlet API 2.1

getMinorVersion

public int getMinorVersion()
Minor version number of the Servlet API the servlet engine supports.
Returns:
1 if the 2.1 Servlet API is supported
Since:
Servlet API 2.1

getMimeType

public java.lang.String getMimeType(java.lang.String filename)
Gives the mimetype of the requested file
Parameters:
filename - the file
Returns:
a String containing the mime type or null if the mime type cannot be determined
Since:
Servlet API 1.0

getRealPath

public java.lang.String getRealPath(java.lang.String virtualPath)
Translates the requested virtual path to the real filesystem path using the servers knowledge of the document root. Use the getResource and getResourceAsStream methods to access the original object in a more abstract way not tied to the filesystem.
Parameters:
virtualPath - the path to be translated (e.g. /graphics/baby-gnu.png)
Returns:
the translated real filesystem path or null if the real system path cannot be found
Since:
Servlet API 1.0
See Also:
getResource(java.lang.String), getResourceAsStream(java.lang.String)

getResource

public java.net.URL getResource(java.lang.String virtualPath)
Translates the requested virtual path to an URL object that can be accesed by the servlet. This is more generic than the getRealPath method since it is not tied to the local filesystem. This means that a servlet can access the resource even when loaded in a servlet engine on a different machine. The servlet engine should make sure that the appropriate URLStreamHandlers and URLConnection classes are implemented to acces to resource.

This can also be used to write to a resource if the resource (URLConnection) supports it. The following example gives you an OutputStream:

URLConnection con = getResource("/logs/mylog.txt").openConnection();
con.setDoOutput(true);
OutputStream out = con.getOutputStream();

Note that a ServerContext does not have to have access to the complete servers document space and is allowed to return null even for valid virtual paths.

Note that according to the 2.1 API documentation this method can throw a MalformedURLException. But according to the official spec it does not throw any exceptions.

Parameters:
virtualPath - the path to the requested resource (e.g. /philosophy/words-to-avoid.html)
Returns:
the URL that can be used to access the resource or null if the resource cannot be found
Since:
Servlet API 2.1
See Also:
URL.openConnection(), URLConnection.setDoOutput(boolean), URLConnection.getOutputStream()

getResourceAsStream

public java.io.InputStream getResourceAsStream(java.lang.String virtualPath)
A convenience method for getResource(virtualPath).openStream(). But the servlet engine is allowed to implement is in a more efficient way.
Parameters:
virtualPath - the path to the requested resource (e.g. /philosophy/words-to-avoid.html)
Returns:
the InputStream that can be used to read the resource or null if the resource cannot be found
Since:
Servlet API 2.1
See Also:
getResource(java.lang.String), URL.openStream()

getRequestDispatcher

public RequestDispatcher getRequestDispatcher(java.lang.String UriPath)
Returns a RequestDispatcher to forward requests or include responses from another (active) resource. Some resources can also be accessed by the getResource method.
Parameters:
UriPath - the path to another (active) resource (e.g. /servlet/OtherServlet)
Returns:
an RequestDispatcher for the (active) resource found at UriPath
Since:
Servlet API 2.1
See Also:
getResource(java.lang.String)

getServerInfo

public java.lang.String getServerInfo()
A server supplied string containing the server name, version number, etc
Returns:
the string
Since:
Servlet API 1.0

log

public void log(java.lang.String message)
Writes a message to the log
Parameters:
message - the message to write
Since:
Servlet API 1.0

log

public void log(java.lang.String message,
                java.lang.Throwable t)
Writes an exception + message to the log
Parameters:
t - the exception
message - the message
Since:
Servlet API 2.1

log

public void log(java.lang.Exception exception,
                java.lang.String message)
Deprecated. Use log(String, Throwable) which is more general.
Writes an exception + message to the log
Parameters:
exception - the exception
message - the message
Since:
Servlet API 2.0
See Also:
log(java.lang.String, java.lang.Throwable)

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object o)
Puts a named object into the ServletContext. Can be used to communicate with other servlets in this ServletContext. The names used must follow the conventions used for naming java packages.
Parameters:
name - - which is used to refer to this object
object - - which should be returned when somebody calls getAttribute(name)
Since:
Servlet API 2.1
See Also:
getAttribute(java.lang.String)

removeAttribute

public void removeAttribute(java.lang.String name)
Removes the named object from the ServletContext
Parameters:
name - The name which was used to set the object with setObject
Since:
Servlet API 2.1

getServlet

public Servlet getServlet(java.lang.String name)
                   throws ServletException
Deprecated. Always returns null. Since the servlet engine cannot know if a servlet ever gives up the reference to another servlet it could never destroy the servlet after this call. Only the servlet engine should have references to Servlets.
Gets a specific servlet by name. The Servlet is guaranteed to accept service requests.
Parameters:
name - the name of the wanted servlet
Returns:
null, used to return the servlet or null if not loaded.
Throws:
ServletException - if a servlet related error occured
Since:
Servlet API 1.0

getServlets

public java.util.Enumeration getServlets()
Deprecated. Always returns an empty Enumeration. Only the servlet engine should have references to Servlets.
Gets all servlets
Returns:
Empty Enumeration, used to return an enumeration containing all loaded servlets including the calling servlet.
Since:
Servlet API 1.0

getServletNames

public java.util.Enumeration getServletNames()
Deprecated. Always returns an empty Enumeration. Only the servlet engine should have references to Servlets.
Gets all servlet names
Returns:
Empty Enumeration, used to return an enumeration containing all loaded servlet names including the calling servlet name
Since:
Servlet API 2.0