ResourceHttpRequestHandler (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.web.servlet.resource

## Class ResourceHttpRequestHandler

- java.lang.Object
- - org.springframework.context.support.ApplicationObjectSupport
  - - org.springframework.web.context.support.WebApplicationObjectSupport
    - - org.springframework.web.servlet.support.WebContentGenerator
      - - org.springframework.web.servlet.resource.ResourceHttpRequestHandler

- All Implemented Interfaces:
    Aware, InitializingBean, ApplicationContextAware, ServletContextAware, HttpRequestHandler

      public class ResourceHttpRequestHandler
      extends WebContentGenerator
      implements HttpRequestHandler, InitializingBean

  `HttpRequestHandler` that serves static resources optimized for superior browser performance (according to the guidelines of Page Speed, YSlow, etc.) by allowing for flexible cache settings ("cacheSeconds" property, last-modified support).

  The "locations" property takes a list of Spring `Resource` locations from which static resources are allowed to be served by this handler. For a given request, the list of locations will be consulted in order for the presence of the requested resource, and the first found match will be written to the response, with `Expires` and `Cache-Control` headers set as configured. The handler also properly evaluates the `Last-Modified` header (if present) so that a `304` status code will be returned as appropriate, avoiding unnecessary overhead for resources that are already cached by the client. The use of `Resource` locations allows resource requests to easily be mapped to locations other than the web application root. For example, resources could be served from a classpath location such as "classpath:/META-INF/public-web-resources/", allowing convenient packaging and serving of resources such as a JavaScript library from within jar files.

  To ensure that users with a primed browser cache get the latest changes to application-specific resources upon deployment of new versions of the application, it is recommended that a version string is used in the URL mapping pattern that selects this handler. Such patterns can be easily parameterized using Spring EL. See the reference manual for further examples of this approach.

  Rather than being directly configured as a bean, this handler will typically be configured through use of the `<mvc:resources/>` XML configuration element.

  Since:
    3.0.4
  Author:
    Keith Donald, Jeremy Grelle, Juergen Hoeller

- - ### Field Summary

    - ### Fields inherited from class org.springframework.web.servlet.support.WebContentGenerator

      `METHOD_GET, METHOD_HEAD, METHOD_POST`

    - ### Fields inherited from class org.springframework.context.support.ApplicationObjectSupport

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ResourceHttpRequestHandler()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterPropertiesSet()` Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).
    `protected MediaType` | `getMediaType(Resource resource)` Determine an appropriate media type for the given resource.
    `protected Resource` | `getResource(HttpServletRequest request)`
    `void` | `handleRequest(HttpServletRequest request, HttpServletResponse response)` Processes a resource request.
    `protected boolean` | `isInvalidPath(String path)` Validates the given path: returns `true` if the given path is not a valid resource path.
    `protected void` | `setHeaders(HttpServletResponse response, Resource resource, MediaType mediaType)` Set headers on the given servlet response.
    `void` | `setLocations(List<Resource> locations)` Set a `List` of `Resource` paths to use as sources for serving static resources.
    `protected void` | `writeContent(HttpServletResponse response, Resource resource)` Write the actual content out to the given servlet response, streaming the resource's content.

    - ### Methods inherited from class org.springframework.web.servlet.support.WebContentGenerator

      `applyCacheSeconds, applyCacheSeconds, cacheForSeconds, cacheForSeconds, checkAndPrepare, checkAndPrepare, getCacheSeconds, getSupportedMethods, isAlwaysMustRevalidate, isRequireSession, isUseCacheControlHeader, isUseCacheControlNoStore, isUseExpiresHeader, preventCaching, setAlwaysMustRevalidate, setCacheSeconds, setRequireSession, setSupportedMethods, setUseCacheControlHeader, setUseCacheControlNoStore, setUseExpiresHeader`

    - ### Methods inherited from class org.springframework.web.context.support.WebApplicationObjectSupport

      `getServletContext, getTempDir, getWebApplicationContext, initApplicationContext, initServletContext, isContextRequired, setServletContext`

    - ### Methods inherited from class org.springframework.context.support.ApplicationObjectSupport

      `getApplicationContext, getMessageSourceAccessor, initApplicationContext, requiredContextClass, setApplicationContext`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ResourceHttpRequestHandler

          public ResourceHttpRequestHandler()

  - ### Method Detail

    - #### setLocations

          public void setLocations(List<Resource> locations)

      Set a `List` of `Resource` paths to use as sources for serving static resources.

    - #### afterPropertiesSet

          public void afterPropertiesSet()
                                  throws Exception

      Description copied from interface: `InitializingBean`
      Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).

      This method allows the bean instance to perform initialization only possible when all bean properties have been set and to throw an exception in the event of misconfiguration.

      Specified by:
        `afterPropertiesSet` in interface `InitializingBean`
      Throws:
        `Exception` - in the event of misconfiguration (such as failure to set an essential property) or if initialization fails.

    - #### handleRequest

          public void handleRequest(HttpServletRequest request,
                           HttpServletResponse response)
                             throws ServletException,
                                    IOException

      Processes a resource request.

      Checks for the existence of the requested resource in the configured list of locations. If the resource does not exist, a `404` response will be returned to the client. If the resource exists, the request will be checked for the presence of the `Last-Modified` header, and its value will be compared against the last-modified timestamp of the given resource, returning a `304` status code if the `Last-Modified` value is greater. If the resource is newer than the `Last-Modified` value, or the header is not present, the content resource of the resource will be written to the response with caching headers set to expire one year in the future.

      Specified by:
        `handleRequest` in interface `HttpRequestHandler`
      Parameters:
        `request` - current HTTP request
        `response` - current HTTP response
      Throws:
        `ServletException` - in case of general errors
        `IOException` - in case of I/O errors

    - #### getResource

          protected Resource getResource(HttpServletRequest request)

    - #### isInvalidPath

          protected boolean isInvalidPath(String path)

      Validates the given path: returns `true` if the given path is not a valid resource path.

      The default implementation rejects paths containing "WEB-INF" or "META-INF" as well as paths with relative paths ("../") that result in access of a parent directory.

      Parameters:
        `path` - the path to validate
      Returns:
        `true` if the path has been recognized as invalid, `false` otherwise

    - #### getMediaType

          protected MediaType getMediaType(Resource resource)

      Determine an appropriate media type for the given resource.
      Parameters:
        `resource` - the resource to check
      Returns:
        the corresponding media type, or `null` if none found

    - #### setHeaders

          protected void setHeaders(HttpServletResponse response,
                        Resource resource,
                        MediaType mediaType)
                             throws IOException

      Set headers on the given servlet response. Called for GET requests as well as HEAD requests.
      Parameters:
        `response` - current servlet response
        `resource` - the identified resource (never `null`)
        `mediaType` - the resource's media type (never `null`)
      Throws:
        `IOException` - in case of errors while setting the headers

    - #### writeContent

          protected void writeContent(HttpServletResponse response,
                          Resource resource)
                               throws IOException

      Write the actual content out to the given servlet response, streaming the resource's content.
      Parameters:
        `response` - current servlet response
        `resource` - the identified resource (never `null`)
      Throws:
        `IOException` - in case of errors while writing the content