FrameworkServlet (Spring Framework API 2.1) - Spring Framework 2.1.0 API 文档英文版

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

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.

boolean isPublishContext()
          Return whether to publish this servlet's context as a ServletContext attribute.

boolean isPublishEvents()
          Return whether this servlet should publish a ServletRequestHandledEvent at the end of each request.

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 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 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 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, doOptions, doTrace, 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 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`	`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.
`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.
`boolean`	`isPublishContext()` Return whether to publish this servlet's context as a ServletContext attribute.
`boolean`	`isPublishEvents()` Return whether this servlet should publish a ServletRequestHandledEvent at the end of each request.
`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`	`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`	`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`	`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, doOptions, doTrace, 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

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.

isPublishContext

public boolean isPublishContext()

Return whether to publish this servlet's context as a ServletContext attribute.

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

isPublishEvents

public boolean isPublishEvents()

Return whether this servlet should publish a ServletRequestHandledEvent at the end of each request.

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)

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

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)

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. 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
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()