public abstract class

FrameworkServlet

extends HttpServletBean
java.lang.Object
   ↳ javax.servlet.GenericServlet
     ↳ javax.servlet.http.HttpServlet
       ↳ org.springframework.web.servlet.HttpServletBean
         ↳ org.springframework.web.servlet.FrameworkServlet
Known Direct Subclasses

Class Overview

Base servlet for Spring's web framework. Provides integration with a Spring application context, in a JavaBean-based overall solution.

This class offers the following functionality:

  • Manages a WebApplicationContext instance per servlet. The servlet's configuration is determined by beans in the servlet's namespace.
  • Publishes events on request processing, whether or not a request is successfully handled.

Subclasses must implement doService(HttpServletRequest, HttpServletResponse) to handle requests. Because this extends HttpServletBean rather than HttpServlet directly, bean properties are automatically mapped onto it. Subclasses can override initFrameworkServlet() for custom initialization.

Detects a "contextClass" parameter at the servlet init-param level, falling back to the default context class, XmlWebApplicationContext, if not found. Note that, with the default FrameworkServlet, a custom context class needs to implement the ConfigurableWebApplicationContext SPI.

Passes a "contextConfigLocation" servlet init-param to the context instance, parsing it into potentially multiple file paths which can be separated by any number of commas and spaces, like "test-servlet.xml, myServlet.xml". If not explicitly specified, the context implementation is supposed to build a default location from the namespace of the servlet.

Note: In case of multiple config locations, later bean definitions will override ones defined in earlier loaded files, at least when using Spring's default ApplicationContext implementation. This can be leveraged to deliberately override certain bean definitions via an extra XML file.

The default namespace is "'servlet-name'-servlet", e.g. "test-servlet" for a servlet-name "test" (leading to a "/WEB-INF/test-servlet.xml" default location with XmlWebApplicationContext). The namespace can also be set explicitly via the "namespace" servlet init-param.

See Also

Summary

Constants
String DEFAULT_NAMESPACE_SUFFIX Suffix for WebApplicationContext namespaces.
Fields
public static final Class DEFAULT_CONTEXT_CLASS Default context class for FrameworkServlet.
public static final String SERVLET_CONTEXT_PREFIX Prefix for the ServletContext attribute for the WebApplicationContext.
[Expand]
Inherited Fields
From class org.springframework.web.servlet.HttpServletBean
Public Constructors
FrameworkServlet()
Public Methods
void destroy()
Close the WebApplicationContext of this servlet.
String getContextAttribute()
Return the name of the ServletContext attribute which should be used to retrieve the WebApplicationContext that this servlet is supposed to use.
Class getContextClass()
Return the custom context class.
String getContextConfigLocation()
Return the explicit context config location, if any.
String getNamespace()
Return the namespace for this servlet, falling back to default scheme if no custom namespace was set: e.g.
String getServletContextAttributeName()
Return the ServletContext attribute name for this servlet's WebApplicationContext.
final WebApplicationContext getWebApplicationContext()
Return this servlet's WebApplicationContext.
void onApplicationEvent(ContextRefreshedEvent event)
Callback that receives refresh events from this servlet's WebApplicationContext.
void refresh()
Refresh this servlet's application context, as well as the dependent state of the servlet.
void setContextAttribute(String contextAttribute)
Set the name of the ServletContext attribute which should be used to retrieve the WebApplicationContext that this servlet is supposed to use.
void setContextClass(Class contextClass)
Set a custom context class.
void setContextConfigLocation(String contextConfigLocation)
Set the context config location explicitly, instead of relying on the default location built from the namespace.
void setDispatchOptionsRequest(boolean dispatchOptionsRequest)
Set whether this servlet should dispatch an HTTP OPTIONS request to the doService(HttpServletRequest, HttpServletResponse) method.
void setDispatchTraceRequest(boolean dispatchTraceRequest)
Set whether this servlet should dispatch an HTTP TRACE request to the doService(HttpServletRequest, HttpServletResponse) method.
void setNamespace(String namespace)
Set a custom namespace for this servlet, to be used for building a default context config location.
void setPublishContext(boolean publishContext)
Set whether to publish this servlet's context as a ServletContext attribute, available to all objects in the web container.
void setPublishEvents(boolean publishEvents)
Set whether this servlet should publish a ServletRequestHandledEvent at the end of each request.
void setThreadContextInheritable(boolean threadContextInheritable)
Set whether to expose the LocaleContext and RequestAttributes as inheritable for child threads (using an InheritableThreadLocal).
Protected Methods
LocaleContext buildLocaleContext(HttpServletRequest request)
Build a LocaleContext for the given request, exposing the request's primary locale as current locale.
WebApplicationContext createWebApplicationContext(WebApplicationContext parent)
Instantiate the WebApplicationContext for this servlet, either a default XmlWebApplicationContext or a custom context class, if set.
WebApplicationContext createWebApplicationContext(ApplicationContext parent)
Instantiate the WebApplicationContext for this servlet, either a default XmlWebApplicationContext or a custom context class, if set.
final void doDelete(HttpServletRequest request, HttpServletResponse response)
Delegate DELETE requests to processRequest(HttpServletRequest, HttpServletResponse).
final void doGet(HttpServletRequest request, HttpServletResponse response)
Delegate GET requests to processRequest/doService.
void doOptions(HttpServletRequest request, HttpServletResponse response)
Delegate OPTIONS requests to processRequest(HttpServletRequest, HttpServletResponse), if desired.
final void doPost(HttpServletRequest request, HttpServletResponse response)
Delegate POST requests to processRequest(HttpServletRequest, HttpServletResponse).
final void doPut(HttpServletRequest request, HttpServletResponse response)
Delegate PUT requests to processRequest(HttpServletRequest, HttpServletResponse).
abstract void doService(HttpServletRequest request, HttpServletResponse response)
Subclasses must implement this method to do the work of request handling, receiving a centralized callback for GET, POST, PUT and DELETE.
void doTrace(HttpServletRequest request, HttpServletResponse response)
Delegate TRACE requests to processRequest(HttpServletRequest, HttpServletResponse), if desired.
WebApplicationContext findWebApplicationContext()
Retrieve a WebApplicationContext from the ServletContext attribute with the configured name.
String getUsernameForRequest(HttpServletRequest request)
Determine the username for the given request.
void initFrameworkServlet()
This method will be invoked after any bean properties have been set and the WebApplicationContext has been loaded.
final void initServletBean()
Overridden method of HttpServletBean, invoked after any bean properties have been set.
WebApplicationContext initWebApplicationContext()
Initialize and publish the WebApplicationContext for this servlet.
void onRefresh(ApplicationContext context)
Template method which can be overridden to add servlet-specific refresh work.
void postProcessWebApplicationContext(ConfigurableWebApplicationContext wac)
Post-process the given WebApplicationContext before it is refreshed and activated as context for this servlet.
final void processRequest(HttpServletRequest request, HttpServletResponse response)
Process this request, publishing an event regardless of the outcome.
[Expand]
Inherited Methods
From class org.springframework.web.servlet.HttpServletBean
From class javax.servlet.http.HttpServlet
From class javax.servlet.GenericServlet
From class java.lang.Object
From interface javax.servlet.Servlet
From interface javax.servlet.ServletConfig
From interface org.springframework.context.EnvironmentAware

Constants

public static final String DEFAULT_NAMESPACE_SUFFIX

Suffix for WebApplicationContext namespaces. If a servlet of this class is given the name "test" in a context, the namespace used by the servlet will resolve to "test-servlet".

Constant Value: "-servlet"

Fields

public static final Class DEFAULT_CONTEXT_CLASS

Default context class for FrameworkServlet.

See Also

public static final String SERVLET_CONTEXT_PREFIX

Prefix for the ServletContext attribute for the WebApplicationContext. The completion is the servlet name.

Public Constructors

public FrameworkServlet ()

Public Methods

public void destroy ()

Close the WebApplicationContext of this servlet.

See Also

public String getContextAttribute ()

Return the name of the ServletContext attribute which should be used to retrieve the WebApplicationContext that this servlet is supposed to use.

public Class getContextClass ()

Return the custom context class.

public String getContextConfigLocation ()

Return the explicit context config location, if any.

public String getNamespace ()

Return the namespace for this servlet, falling back to default scheme if no custom namespace was set: e.g. "test-servlet" for a servlet named "test".

public String getServletContextAttributeName ()

Return the ServletContext attribute name for this servlet's WebApplicationContext.

The default implementation returns SERVLET_CONTEXT_PREFIX + servlet name.

See Also

public final WebApplicationContext getWebApplicationContext ()

Return this servlet's WebApplicationContext.

public void onApplicationEvent (ContextRefreshedEvent event)

Callback that receives refresh events from this servlet's WebApplicationContext.

The default implementation calls onRefresh(ApplicationContext), triggering a refresh of this servlet's context-dependent state.

Parameters
event the incoming ApplicationContext event

public void refresh ()

Refresh this servlet's application context, as well as the dependent state of the servlet.

See Also

public void setContextAttribute (String contextAttribute)

Set the name of the ServletContext attribute which should be used to retrieve the WebApplicationContext that this servlet is supposed to use.

public void setContextClass (Class contextClass)

Set a custom context class. This class must be of type WebApplicationContext.

When using the default FrameworkServlet implementation, the context class must also implement the ConfigurableWebApplicationContext interface.

See Also

public void setContextConfigLocation (String contextConfigLocation)

Set the context config location explicitly, instead of relying on the default location built from the namespace. This location string can consist of multiple locations separated by any number of commas and spaces.

public void setDispatchOptionsRequest (boolean dispatchOptionsRequest)

Set whether this servlet should dispatch an HTTP OPTIONS request to the doService(HttpServletRequest, HttpServletResponse) method.

Default is "false", applying javax.servlet.http.HttpServlet's default behavior (i.e. enumerating all standard HTTP request methods as a response to the OPTIONS request).

Turn this flag on if you prefer OPTIONS requests to go through the regular dispatching chain, just like other HTTP requests. This usually means that your controllers will receive those requests; make sure that those endpoints are actually able to handle an OPTIONS request.

Note that HttpServlet's default OPTIONS processing will be applied in any case. Your controllers are simply available to override the default headers and optionally generate a response body.

public void setDispatchTraceRequest (boolean dispatchTraceRequest)

Set whether this servlet should dispatch an HTTP TRACE request to the doService(HttpServletRequest, HttpServletResponse) method.

Default is "false", applying javax.servlet.http.HttpServlet's default behavior (i.e. reflecting the message received back to the client).

Turn this flag on if you prefer TRACE requests to go through the regular dispatching chain, just like other HTTP requests. This usually means that your controllers will receive those requests; make sure that those endpoints are actually able to handle a TRACE request.

Note that HttpServlet's default TRACE processing will be applied in any case. Your controllers are simply available to override the default headers and the default body, calling response.reset() if necessary.

public void setNamespace (String namespace)

Set a custom namespace for this servlet, to be used for building a default context config location.

public void setPublishContext (boolean publishContext)

Set whether to publish this servlet's context as a ServletContext attribute, available to all objects in the web container. Default is "true".

This is especially handy during testing, although it is debatable whether it's good practice to let other application objects access the context this way.

public void setPublishEvents (boolean publishEvents)

Set whether this servlet should publish a ServletRequestHandledEvent at the end of each request. Default is "true"; can be turned off for a slight performance improvement, provided that no ApplicationListeners rely on such events.

See Also

public void setThreadContextInheritable (boolean threadContextInheritable)

Set whether to expose the LocaleContext and RequestAttributes as inheritable for child threads (using an InheritableThreadLocal).

Default is "false", to avoid side effects on spawned background threads. Switch this to "true" to enable inheritance for custom child threads which are spawned during request processing and only used for this request (that is, ending after their initial task, without reuse of the thread).

WARNING: Do not use inheritance for child threads if you are accessing a thread pool which is configured to potentially add new threads on demand (e.g. a JDK ThreadPoolExecutor), since this will expose the inherited context to such a pooled thread.

Protected Methods

protected LocaleContext buildLocaleContext (HttpServletRequest request)

Build a LocaleContext for the given request, exposing the request's primary locale as current locale.

Parameters
request current HTTP request
Returns
  • the corresponding LocaleContext

protected WebApplicationContext createWebApplicationContext (WebApplicationContext parent)

Instantiate the WebApplicationContext for this servlet, either a default XmlWebApplicationContext or a custom context class, if set. Delegates to #createWebApplicationContext(ApplicationContext).

Parameters
parent the parent WebApplicationContext to use, or null if none
Returns
  • the WebApplicationContext for this servlet
See Also

protected WebApplicationContext createWebApplicationContext (ApplicationContext parent)

Instantiate the WebApplicationContext for this servlet, either a default XmlWebApplicationContext or a custom context class, if set.

This implementation expects custom contexts to implement the ConfigurableWebApplicationContext interface. Can be overridden in subclasses.

Do not forget to register this servlet instance as application listener on the created context (for triggering its callback, and to call refresh() before returning the context instance.

Parameters
parent the parent ApplicationContext to use, or null if none
Returns
  • the WebApplicationContext for this servlet
See Also

protected final void doDelete (HttpServletRequest request, HttpServletResponse response)

Delegate DELETE requests to processRequest(HttpServletRequest, HttpServletResponse).

Throws
IOException
ServletException
See Also

protected final void doGet (HttpServletRequest request, HttpServletResponse response)

Delegate GET requests to processRequest/doService.

Will also be invoked by HttpServlet's default implementation of doHead, with a NoBodyResponse that just captures the content length.

Throws
IOException
ServletException
See Also

protected void doOptions (HttpServletRequest request, HttpServletResponse response)

Delegate OPTIONS requests to processRequest(HttpServletRequest, HttpServletResponse), if desired.

Applies HttpServlet's standard OPTIONS processing first.

Throws
ServletException
IOException
See Also

protected final void doPost (HttpServletRequest request, HttpServletResponse response)

Delegate POST requests to processRequest(HttpServletRequest, HttpServletResponse).

Throws
IOException
ServletException
See Also

protected final void doPut (HttpServletRequest request, HttpServletResponse response)

Delegate PUT requests to processRequest(HttpServletRequest, HttpServletResponse).

Throws
IOException
ServletException
See Also

protected abstract void doService (HttpServletRequest request, HttpServletResponse response)

Subclasses must implement this method to do the work of request handling, receiving a centralized callback for GET, POST, PUT and DELETE.

The contract is essentially the same as that for the commonly overridden doGet or doPost methods of HttpServlet.

This class intercepts calls to ensure that exception handling and event publication takes place.

Parameters
request current HTTP request
response current HTTP response
Throws
Exception in case of any kind of processing failure
See Also

protected void doTrace (HttpServletRequest request, HttpServletResponse response)

Delegate TRACE requests to processRequest(HttpServletRequest, HttpServletResponse), if desired.

Applies HttpServlet's standard TRACE processing first.

Throws
ServletException
IOException
See Also

protected WebApplicationContext findWebApplicationContext ()

Retrieve a WebApplicationContext from the ServletContext attribute with the configured name. The WebApplicationContext must have already been loaded and stored in the ServletContext before this servlet gets initialized (or invoked).

Subclasses may override this method to provide a different WebApplicationContext retrieval strategy.

Returns
  • the WebApplicationContext for this servlet, or null if not found
See Also

protected String getUsernameForRequest (HttpServletRequest request)

Determine the username for the given request.

The default implementation takes the name of the UserPrincipal, if any. Can be overridden in subclasses.

Parameters
request current HTTP request
Returns
  • the username, or null if none found
See Also

protected void initFrameworkServlet ()

This method will be invoked after any bean properties have been set and the WebApplicationContext has been loaded. The default implementation is empty; subclasses may override this method to perform any initialization they require.

Throws
ServletException in case of an initialization exception

protected final void initServletBean ()

Overridden method of HttpServletBean, invoked after any bean properties have been set. Creates this servlet's WebApplicationContext.

Throws
ServletException

protected WebApplicationContext initWebApplicationContext ()

Initialize and publish the WebApplicationContext for this servlet.

Delegates to createWebApplicationContext(ApplicationContext) for actual creation of the context. Can be overridden in subclasses.

Returns
  • the WebApplicationContext instance
See Also

protected void onRefresh (ApplicationContext context)

Template method which can be overridden to add servlet-specific refresh work. Called after successful context refresh.

This implementation is empty.

Parameters
context the current WebApplicationContext
See Also

protected void postProcessWebApplicationContext (ConfigurableWebApplicationContext wac)

Post-process the given WebApplicationContext before it is refreshed and activated as context for this servlet.

The default implementation is empty. refresh() will be called automatically after this method returns.

Parameters
wac the configured WebApplicationContext (not refreshed yet)
See Also

protected final void processRequest (HttpServletRequest request, HttpServletResponse response)

Process this request, publishing an event regardless of the outcome.

The actual event handling is performed by the abstract doService(HttpServletRequest, HttpServletResponse) template method.

Throws
IOException
ServletException