Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| The Spring Framework
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.springframework.web.servlet
Class FrameworkServlet

    java.lang.Object
      javax.servlet.GenericServlet
          javax.servlet.http.HttpServlet
              org.springframework.web.servlet.HttpServletBean
                  org.springframework.web.servlet.FrameworkServlet

All Implemented Interfaces:
  Serializable, EventListener, Servlet, ServletConfig, ApplicationListener

Direct Known Subclasses:
  DispatcherServlet

    public abstract class FrameworkServlet

extends HttpServletBean
implements ApplicationListener

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(javax.servlet.http.HttpServletRequest, javax.servlet.http.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.

Author:
  Rod Johnson, Juergen Hoeller, Sam Brannen
See Also:
  `doService(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`, `setContextClass(java.lang.Class)`, `setContextConfigLocation(java.lang.String)`, `setNamespace(java.lang.String)`, Serialized Form

Field Summary
`static Class` | `DEFAULT_CONTEXT_CLASS` Default context class for FrameworkServlet.
`static String` | `DEFAULT_NAMESPACE_SUFFIX` Suffix for WebApplicationContext namespaces.
`static String` | `SERVLET_CONTEXT_PREFIX` Prefix for the ServletContext attribute for the WebApplicationContext.

Fields inherited from class org.springframework.web.servlet.HttpServletBean
`logger`

Constructor Summary
`FrameworkServlet()`

Method Summary
`protected WebApplicationContext` | `createWebApplicationContext(WebApplicationContext parent)` Instantiate the WebApplicationContext for this servlet, either a default `XmlWebApplicationContext` or a `custom context class`, if set.
`void` | `destroy()` Close the WebApplicationContext of this servlet.
`protected void` | `doDelete(HttpServletRequest request, HttpServletResponse response)` Delegate DELETE requests to `processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`.
`protected void` | `doGet(HttpServletRequest request, HttpServletResponse response)` Delegate GET requests to processRequest/doService.
`protected void` | `doOptions(HttpServletRequest request, HttpServletResponse response)` Delegate OPTIONS requests to `processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`, if desired.
`protected void` | `doPost(HttpServletRequest request, HttpServletResponse response)` Delegate POST requests to `processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`.
`protected void` | `doPut(HttpServletRequest request, HttpServletResponse response)` Delegate PUT requests to `processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`.
`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.
`protected void` | `doTrace(HttpServletRequest request, HttpServletResponse response)` Delegate TRACE requests to `processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`, if desired.
`protected WebApplicationContext` | `findWebApplicationContext()` Retrieve a `WebApplicationContext` from the `ServletContext` attribute with the `configured name`.
`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.
`protected String` | `getUsernameForRequest(HttpServletRequest request)` Determine the username for the given request.
`WebApplicationContext` | `getWebApplicationContext()` Return this servlet's WebApplicationContext.
`protected void` | `initFrameworkServlet()` This method will be invoked after any bean properties have been set and the WebApplicationContext has been loaded.
`protected void` | `initServletBean()` Overridden method of `HttpServletBean`, invoked after any bean properties have been set.
`protected WebApplicationContext` | `initWebApplicationContext()` Initialize and publish the WebApplicationContext for this servlet.
`void` | `onApplicationEvent(ApplicationEvent event)` ApplicationListener endpoint that receives events from this servlet's WebApplicationContext.
`protected void` | `onRefresh(ApplicationContext context)` Template method which can be overridden to add servlet-specific refresh work.
`protected void` | `postProcessWebApplicationContext(ConfigurableWebApplicationContext wac)` Post-process the given WebApplicationContext before it is refreshed and activated as context for this servlet.
`protected void` | `processRequest(HttpServletRequest request, HttpServletResponse response)` Process this request, publishing an event regardless of the outcome.
`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(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)` method.
`void` | `setDispatchTraceRequest(boolean dispatchTraceRequest)` Set whether this servlet should dispatch an HTTP TRACE request to the `doService(javax.servlet.http.HttpServletRequest, javax.servlet.http.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.

Methods inherited from class org.springframework.web.servlet.HttpServletBean
`addRequiredProperty, getServletContext, getServletName, init, initBeanWrapper`

Methods inherited from class javax.servlet.http.HttpServlet
`doHead, getLastModified, service, service`

Methods inherited from class javax.servlet.GenericServlet
`getInitParameter, getInitParameterNames, getServletConfig, getServletInfo, init, log, log`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DEFAULT_NAMESPACE_SUFFIX

    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".

  See Also:
    Constant Field Values

### DEFAULT_CONTEXT_CLASS

    public static final Class DEFAULT_CONTEXT_CLASS

  Default context class for FrameworkServlet.

  See Also:
    `XmlWebApplicationContext`

### SERVLET_CONTEXT_PREFIX

    public static final String SERVLET_CONTEXT_PREFIX

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

Constructor Detail

### FrameworkServlet

    public FrameworkServlet()

Method Detail

### setContextAttribute

    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.

### getContextAttribute

    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.

### setContextClass

    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:
    `createWebApplicationContext(org.springframework.web.context.WebApplicationContext)`

### getContextClass

    public Class getContextClass()

  Return the custom context class.

### setNamespace

    public void setNamespace(String namespace)

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

### getNamespace

    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".

### setContextConfigLocation

    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.

### getContextConfigLocation

    public String getContextConfigLocation()

  Return the explicit context config location, if any.

### setPublishContext

    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.

### setPublishEvents

    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:
    `ServletRequestHandledEvent`

### setDispatchOptionsRequest

    public void setDispatchOptionsRequest(boolean dispatchOptionsRequest)

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

  Default is "false", applying `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.

### setDispatchTraceRequest

    public void setDispatchTraceRequest(boolean dispatchTraceRequest)

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

  Default is "false", applying `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.

### initServletBean

    protected final void initServletBean()
                                  throws ServletException,
                                         BeansException

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

  Overrides:
    `initServletBean` in class `HttpServletBean`
  Throws:
    `ServletException` - if subclass initialization fails
    `BeansException`

### initWebApplicationContext

    protected WebApplicationContext initWebApplicationContext()
                                                       throws BeansException

  Initialize and publish the WebApplicationContext for this servlet.

  Delegates to `createWebApplicationContext(org.springframework.web.context.WebApplicationContext)` for actual creation of the context. Can be overridden in subclasses.

  Returns:
    the WebApplicationContext instance
  Throws:
    `BeansException` - if the context couldn't be initialized
  See Also:
    `setContextClass(java.lang.Class)`, `setContextConfigLocation(java.lang.String)`

### findWebApplicationContext

    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:
    `getContextAttribute()`

### createWebApplicationContext

    protected WebApplicationContext createWebApplicationContext(WebApplicationContext parent)
                                                         throws BeansException

  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 `ConfigurableApplicationContext.refresh()` before returning the context instance.

  Parameters:
    `parent` - the parent ApplicationContext to use, or `null` if none
  Returns:
    the WebApplicationContext for this servlet
  Throws:
    `BeansException` - if the context couldn't be initialized
  See Also:
    `XmlWebApplicationContext`

### postProcessWebApplicationContext

    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:
    `createWebApplicationContext(org.springframework.web.context.WebApplicationContext)`, `ConfigurableApplicationContext.refresh()`

### getServletContextAttributeName

    public String getServletContextAttributeName()

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

  The default implementation returns `SERVLET_CONTEXT_PREFIX + servlet name`.

  See Also:
    `SERVLET_CONTEXT_PREFIX`, `HttpServletBean.getServletName()`

### getWebApplicationContext

    public final WebApplicationContext getWebApplicationContext()

  Return this servlet's WebApplicationContext.

### initFrameworkServlet

    protected void initFrameworkServlet()
                                 throws ServletException,
                                        BeansException

  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
    `BeansException` - if thrown by ApplicationContext methods

### refresh

    public void refresh()
                 throws BeansException

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

  Throws:
    `BeansException` - in case of errors
  See Also:
    `getWebApplicationContext()`, `ConfigurableApplicationContext.refresh()`

### onApplicationEvent

    public void onApplicationEvent(ApplicationEvent event)

  ApplicationListener endpoint that receives events from this servlet's WebApplicationContext.

  The default implementation calls `onRefresh(org.springframework.context.ApplicationContext)` in case of a `ContextRefreshedEvent`, triggering a refresh of this servlet's context-dependent state.

  Specified by:
    `onApplicationEvent` in interface `ApplicationListener`
  Parameters:
    `event` - the incoming ApplicationContext event

### onRefresh

    protected void onRefresh(ApplicationContext context)
                      throws BeansException

  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
  Throws:
    `BeansException` - in case of errors
  See Also:
    `refresh()`

### doGet

    protected final void doGet(HttpServletRequest request,
                               HttpServletResponse response)
                        throws ServletException,
                               IOException

  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.

  Overrides:
    `doGet` in class `HttpServlet`
  Throws:
    `ServletException`
    `IOException`
  See Also:
    `doService(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`, `HttpServlet.doHead(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`

### doPost

    protected final void doPost(HttpServletRequest request,
                                HttpServletResponse response)
                         throws ServletException,
                                IOException

  Delegate POST requests to `processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`.

  Overrides:
    `doPost` in class `HttpServlet`
  Throws:
    `ServletException`
    `IOException`
  See Also:
    `doService(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`

### doPut

    protected final void doPut(HttpServletRequest request,
                               HttpServletResponse response)
                        throws ServletException,
                               IOException

  Delegate PUT requests to `processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`.

  Overrides:
    `doPut` in class `HttpServlet`
  Throws:
    `ServletException`
    `IOException`
  See Also:
    `doService(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`

### doDelete

    protected final void doDelete(HttpServletRequest request,
                                  HttpServletResponse response)
                           throws ServletException,
                                  IOException

  Delegate DELETE requests to `processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`.

  Overrides:
    `doDelete` in class `HttpServlet`
  Throws:
    `ServletException`
    `IOException`
  See Also:
    `doService(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`

### doOptions

    protected void doOptions(HttpServletRequest request,
                             HttpServletResponse response)
                      throws ServletException,
                             IOException

  Delegate OPTIONS requests to `processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`, if desired.

  Applies HttpServlet's standard OPTIONS processing first.

  Overrides:
    `doOptions` in class `HttpServlet`
  Throws:
    `ServletException`
    `IOException`
  See Also:
    `doService(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`

### doTrace

    protected void doTrace(HttpServletRequest request,
                           HttpServletResponse response)
                    throws ServletException,
                           IOException

  Delegate TRACE requests to `processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`, if desired.

  Applies HttpServlet's standard TRACE processing first.

  Overrides:
    `doTrace` in class `HttpServlet`
  Throws:
    `ServletException`
    `IOException`
  See Also:
    `doService(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`

### processRequest

    protected final void processRequest(HttpServletRequest request,
                                        HttpServletResponse response)
                                 throws ServletException,
                                        IOException

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

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

  Throws:
    `ServletException`
    `IOException`

### getUsernameForRequest

    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:
    `HttpServletRequest.getUserPrincipal()`

### doService

    protected abstract void doService(HttpServletRequest request,
                                      HttpServletResponse response)
                               throws Exception

  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:
    `HttpServlet.doGet(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`, `HttpServlet.doPost(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`

### destroy

    public void destroy()

  Close the WebApplicationContext of this servlet.

  Specified by:
    `destroy` in interface `Servlet`
  Overrides:
    `destroy` in class `GenericServlet`
  See Also:
    `ConfigurableApplicationContext.close()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| The Spring Framework
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2008 The Spring Framework.