javax.servlet

Interface ServletContext

All Known Implementing Classes:

ServletContextImpl, UnknownWebApp, WebApp

public interface ServletContext

ServletContexts encapsulate applications. Applications are generalized virtual hosts; a URL prefix defines a distinct application. So /myapp and /yourapp could define different applications. As a degenerate case, each virtual host has its own ServletContext.

Each application is entirely distinct. Each has its own:

• Class loader -- each application gets its own beans and servlets.
• ServletContext attributes
• Servlets and servlet mappings (e.g. *.jsp could map to different servlets in different applications.)
• File root
• Mime mapping
• Real-path mapping (aliases)

URIs are relative to the application root (e.g. /myapp) for most ServletContext methods. So you can define user workspaces with identical JSP files and servlets in different applications.

Including and forwarding

Forwarding and including files, the Servlet equivalent of SSI are handled by the RequestDispatcher methods.

Global initialization

There is no direct equivalent of a global.jsa. To initialize and cleanup shared classes on start and stop, use a load-on-startup servlet. The init() method will be called when the application starts and the destroy() method will be called when the application finishes.

   <servlet servlet-name='global'
            servlet-class='test.InitServlet'
            load-on-startup/>
 

Basic configuration

In the resin.conf, to define the /myapp application with a document root in /www/myweb, add the following to the resin.conf.

   <web-app id='/myapp' app-dir='/www/myweb'/>
 

Servlet and Bean locations (class loaders)

Each application has its own directories to load application servlets and beans. By default these are WEB-APP/classes and WEB-APP/lib. To add a servlet test.MyServlet, create the java file: /www/myweb/WEB-APP/classes/test/MyServlet.java

Load balancing

When using load balancing with a web server, each JVM will have its own application object. The attributes are not shared. In contrast, sessions are always sent to the same JVM.

So the application object is best used as a cache rather than as a way for servlets to communicate.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ORDERED_LIBS
static java.lang.String	TEMPDIR

Method Summary

Modifier and Type	Method and Description
FilterRegistration.Dynamic	addFilter(java.lang.String filterName, java.lang.Class<? extends Filter> filterClass) Adds a filter using filterClass
FilterRegistration.Dynamic	addFilter(java.lang.String filterName, Filter filter) Adds a dynamic filter registration using filter
FilterRegistration.Dynamic	addFilter(java.lang.String filterName, java.lang.String className) Adds a dynamic filter registration using className
void	addListener(java.lang.Class<? extends java.util.EventListener> listenerClass)
void	addListener(java.lang.String className)
<T extends java.util.EventListener> void	addListener(T t)
ServletRegistration.Dynamic	addServlet(java.lang.String servletName, java.lang.Class<? extends Servlet> servletClass) Adds a servlet class to the servlet container.
ServletRegistration.Dynamic	addServlet(java.lang.String servletName, Servlet servlet) Adds a servlet to context
ServletRegistration.Dynamic	addServlet(java.lang.String servletName, java.lang.String className) Adds a servlet with the given className to context
<T extends Filter> T	createFilter(java.lang.Class<T> c) Create a filter using class
<T extends java.util.EventListener> T	createListener(java.lang.Class<T> listenerClass)
<T extends Servlet> T	createServlet(java.lang.Class<T> c) Creates a servlet instance using the web-apps injection.
void	declareRoles(java.lang.String... roleNames)
java.lang.Object	getAttribute(java.lang.String name) Returns an attribute value.
java.util.Enumeration<java.lang.String>	getAttributeNames() Returns an enumeration of all the attribute names.
java.lang.ClassLoader	getClassLoader()
ServletContext	getContext(java.lang.String uri) Returns the ServletContext for the uri.
java.lang.String	getContextPath() Returns the context-path for the web-application.
java.util.Set<SessionTrackingMode>	getDefaultSessionTrackingModes() The session tracking mode
int	getEffectiveMajorVersion()
int	getEffectiveMinorVersion()
java.util.Set<SessionTrackingMode>	getEffectiveSessionTrackingModes() The session tracking mode
FilterRegistration	getFilterRegistration(java.lang.String filterName) Returns filter registration sing filterName
java.util.Map<java.lang.String,? extends FilterRegistration>	getFilterRegistrations() Returns filter registrations
java.lang.String	getInitParameter(java.lang.String name) Returns the value of an initialization parameter from the configuration file.
java.util.Enumeration<java.lang.String>	getInitParameterNames() Returns an enumeration of all init parameter names.
JspConfigDescriptor	getJspConfigDescriptor()
int	getMajorVersion() Returns the major version of the servlet API.
java.lang.String	getMimeType(java.lang.String uri) Returns the mime type for the given uri.
int	getMinorVersion() Returns the minor version of the servlet API.
RequestDispatcher	getNamedDispatcher(java.lang.String servletName) Returns a request dispatcher based on a servlet name.
java.lang.String	getRealPath(java.lang.String uri) Returns the real file path for the given uri.
RequestDispatcher	getRequestDispatcher(java.lang.String uri) Returns a request dispatcher for later inclusion or forwarding.
java.net.URL	getResource(java.lang.String uri) Returns the resource for the given uri.
java.io.InputStream	getResourceAsStream(java.lang.String path) Returns the resource as a stream.
java.util.Set<java.lang.String>	getResourcePaths(java.lang.String prefix) Returns the set all resources held by the application.
java.lang.String	getServerInfo() Returns a server-specific string identifying the servlet engine.
Servlet	getServlet(java.lang.String name) Deprecated.
java.lang.String	getServletContextName() Returns the URL prefix for the ServletContext.
java.util.Enumeration<java.lang.String>	getServletNames() Deprecated.
ServletRegistration	getServletRegistration(java.lang.String servletName) Returs servlet registration using servletName
java.util.Map<java.lang.String,? extends ServletRegistration>	getServletRegistrations() Returns servlet registrations
java.util.Enumeration<Servlet>	getServlets() Deprecated.
SessionCookieConfig	getSessionCookieConfig() Sets the session cookie configuration
void	log(java.lang.Exception exception, java.lang.String msg) Deprecated.
void	log(java.lang.String msg) Logs a message.
void	log(java.lang.String message, java.lang.Throwable throwable) Logs a message and a stack trace.
void	removeAttribute(java.lang.String name) Removes an attribute.
void	setAttribute(java.lang.String name, java.lang.Object value) Sets an attribute value.
boolean	setInitParameter(java.lang.String name, java.lang.String value) Sets init parameter
void	setSessionTrackingModes(java.util.Set<SessionTrackingMode> modes) The session tracking mode

Field Detail

ORDERED_LIBS

static final java.lang.String ORDERED_LIBS

See Also:

Constant Field Values

TEMPDIR

static final java.lang.String TEMPDIR

See Also:

Constant Field Values

Method Detail

getServletContextName

java.lang.String getServletContextName()

Returns the URL prefix for the ServletContext.

getServerInfo

java.lang.String getServerInfo()

Returns a server-specific string identifying the servlet engine.

getMajorVersion

int getMajorVersion()

Returns the major version of the servlet API.

getEffectiveMajorVersion

int getEffectiveMajorVersion()

Returns:

major version of the spec the app is based on

getMinorVersion

int getMinorVersion()

Returns the minor version of the servlet API.

getEffectiveMinorVersion

int getEffectiveMinorVersion()

Returns:

minor version of the spec the app is based on

getInitParameter

java.lang.String getInitParameter(java.lang.String name)

Returns the value of an initialization parameter from the configuration file. The Resin configuration looks something like:

 <web-app id='/myapp' app-dir='/www/myapp'>
   <context-param name1='value1'/>
   <context-param name2='value2'/>
 </web-app>
 

Parameters:

name - init parameter name

Returns:

init parameter value

getInitParameterNames

java.util.Enumeration<java.lang.String> getInitParameterNames()

Returns an enumeration of all init parameter names.

getContext

ServletContext getContext(java.lang.String uri)

Returns the ServletContext for the uri. Note: the uri is not relative to the application.T

Parameters:

uri - path relative to the root

Returns:

the ServletContext responsible for the given uri.

getContextPath

java.lang.String getContextPath()

Returns the context-path for the web-application.

getRealPath

java.lang.String getRealPath(java.lang.String uri)

Returns the real file path for the given uri. The file path will be in native path format (with native path separators.)

See ServletRequest to return the real path relative to the request uri.

Parameters:

uri - path relative to the application root to be translated.

Returns:

native file path for the uri.

getRequestDispatcher

RequestDispatcher getRequestDispatcher(java.lang.String uri)

Returns a request dispatcher for later inclusion or forwarding. This is the servlet API equivalent to SSI includes. The uri is relative to the application root.

The following example includes the result of executing inc.jsp into the output stream. If the context path is /myapp, the equivalent uri is /myapp/inc.jsp

   RequestDispatcher disp;
   disp = getRequestDispatcher("/inc.jsp?a=b");
   disp.include(request, response);
 

See ServletRequest to return a request dispatcher relative to the request uri.

Parameters:

uri - path relative to the app root (including query string) for the included file.

Returns:

RequestDispatcher for later inclusion or forwarding.

getNamedDispatcher

RequestDispatcher getNamedDispatcher(java.lang.String servletName)

Returns a request dispatcher based on a servlet name.

Parameters:

servletName - the servlet name to include or forward to.

Returns:

RequestDispatcher for later inclusion or forwarding.

getMimeType

java.lang.String getMimeType(java.lang.String uri)

Returns the mime type for the given uri.

Parameters:

uri - path relative to the application root.

getAttribute

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

Returns an attribute value.

Parameters:

name - of the attribute.

Returns:

stored value

getAttributeNames

java.util.Enumeration<java.lang.String> getAttributeNames()

Returns an enumeration of all the attribute names.

setAttribute

void setAttribute(java.lang.String name,
                  java.lang.Object value)

Sets an attribute value. Because servlets are multithreaded, setting ServletContext attributes will generally need synchronization.

A typical initialization of an application attribute will look like:

 ServletContext app = getServletContext();
 Object value;
 synchronized (app) {
   value = app.getAttribute("cache");
   if (value == null) {
     value = new Cache();
     app.setAttribute("cache", value);
   }
 }
 

Parameters:

name - of the attribute.

value - value to store

removeAttribute

void removeAttribute(java.lang.String name)

Removes an attribute. Because servlets are multithreaded, removing ServletContext attributes will generally need synchronization.

Parameters:

name - of the attribute.

log

void log(java.lang.String msg)

Logs a message.

log

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

Logs a message and a stack trace.

getResource

java.net.URL getResource(java.lang.String uri)
                  throws java.net.MalformedURLException

Returns the resource for the given uri. In general, the RequestDispatcher routines are more useful.

Parameters:

uri - path relative to the application root.

Throws:

java.net.MalformedURLException

getResourcePaths

java.util.Set<java.lang.String> getResourcePaths(java.lang.String prefix)

Returns the set all resources held by the application.

getResourceAsStream

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

Returns the resource as a stream. In general, the RequestDispatcher routines are more useful.

Parameters:

path - path relative to the application root.

Returns:

InputStream to the resource.

getServlet

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

Deprecated.

Throws:

ServletException

getServlets

java.util.Enumeration<Servlet> getServlets()

Deprecated.

getServletNames

java.util.Enumeration<java.lang.String> getServletNames()

Deprecated.

log

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

Deprecated.

getSessionCookieConfig

SessionCookieConfig getSessionCookieConfig()

Sets the session cookie configuration

setSessionTrackingModes

void setSessionTrackingModes(java.util.Set<SessionTrackingMode> modes)

The session tracking mode

getDefaultSessionTrackingModes

java.util.Set<SessionTrackingMode> getDefaultSessionTrackingModes()

The session tracking mode

getEffectiveSessionTrackingModes

java.util.Set<SessionTrackingMode> getEffectiveSessionTrackingModes()

The session tracking mode

setInitParameter

boolean setInitParameter(java.lang.String name,
                         java.lang.String value)

Sets init parameter

Parameters:

name -

value -

Returns:

addServlet

ServletRegistration.Dynamic addServlet(java.lang.String servletName,
                                       java.lang.String className)

Adds a servlet with the given className to context

addServlet

ServletRegistration.Dynamic addServlet(java.lang.String servletName,
                                       Servlet servlet)

Adds a servlet to context

addServlet

ServletRegistration.Dynamic addServlet(java.lang.String servletName,
                                       java.lang.Class<? extends Servlet> servletClass)

Adds a servlet class to the servlet container.

createServlet

<T extends Servlet> T createServlet(java.lang.Class<T> c)
                             throws ServletException

Creates a servlet instance using the web-apps injection.

Throws:

ServletException

getServletRegistration

ServletRegistration getServletRegistration(java.lang.String servletName)

Returs servlet registration using servletName

Parameters:

servletName -

Returns:

a ServletRegistration object

getServletRegistrations

java.util.Map<java.lang.String,? extends ServletRegistration> getServletRegistrations()

Returns servlet registrations

Returns:

addFilter

FilterRegistration.Dynamic addFilter(java.lang.String filterName,
                                     java.lang.String className)

Adds a dynamic filter registration using className

Parameters:

filterName -

className -

Returns:

addFilter

FilterRegistration.Dynamic addFilter(java.lang.String filterName,
                                     Filter filter)

Adds a dynamic filter registration using filter

Parameters:

filterName -

filter -

Returns:

addFilter

FilterRegistration.Dynamic addFilter(java.lang.String filterName,
                                     java.lang.Class<? extends Filter> filterClass)

Adds a filter using filterClass

Parameters:

filterName -

filterClass -

Returns:

createFilter

<T extends Filter> T createFilter(java.lang.Class<T> c)
                           throws ServletException

Create a filter using class

Type Parameters:

T -

Parameters:

c -

Returns:

Throws:

ServletException

getFilterRegistration

FilterRegistration getFilterRegistration(java.lang.String filterName)

Returns filter registration sing filterName

Parameters:

filterName -

Returns:

getFilterRegistrations

java.util.Map<java.lang.String,? extends FilterRegistration> getFilterRegistrations()

Returns filter registrations

Returns:

addListener

void addListener(java.lang.String className)

addListener

<T extends java.util.EventListener> void addListener(T t)

addListener

void addListener(java.lang.Class<? extends java.util.EventListener> listenerClass)

createListener

<T extends java.util.EventListener> T createListener(java.lang.Class<T> listenerClass)
                                              throws ServletException

Throws:

ServletException

getJspConfigDescriptor

JspConfigDescriptor getJspConfigDescriptor()

getClassLoader

java.lang.ClassLoader getClassLoader()

declareRoles

void declareRoles(java.lang.String... roleNames)