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, EmbeddedValueResolverAware, ServletContextAware, CorsConfigurationSource, HttpRequestHandler
public class ResourceHttpRequestHandler extends WebContentGenerator implements HttpRequestHandler, EmbeddedValueResolverAware, InitializingBean, CorsConfigurationSource
HttpRequestHandler that serves static resources in an optimized way according to the guidelines of Page Speed, YSlow, etc.

The properties "locations" and "locationValues" accept locations from which static resources can be served by this handler. This can be relative to the root of the web application, or from the classpath, for example, "classpath:/META-INF/public-web-resources/", allowing convenient packaging and serving of resources such as .js, .css, and others in jar files.

This request handler may also be configured with a resourcesResolver and resourceTransformer chains to support arbitrary resolution and transformation of resources being served. By default, a PathResourceResolver simply finds resources based on the configured "locations". An application can configure additional resolvers and transformers such as the VersionResourceResolver which can resolve and prepare URLs for resources with a version in the URL.

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

Since:
3.0.4
Author:
Keith Donald, Jeremy Grelle, Juergen Hoeller, Arjen Poutsma, Brian Clozel, Rossen Stoyanchev

  • Constructor Details

    • ResourceHttpRequestHandler

      public ResourceHttpRequestHandler()

  • Method Details

    • setLocationValues

      public void setLocationValues(List<String> locations)
      Configure String-based locations to serve resources from.

      For example, {"/", "classpath:/META-INF/public-web-resources/"} allows resources to be served both from the web application root and from any JAR on the classpath that contains a /META-INF/public-web-resources/ directory, with resources in the web application root taking precedence.

      For URL-based resources (for example, files, HTTP URLs, etc.) this method supports a special prefix to indicate the charset associated with the URL so that relative paths appended to it can be encoded correctly, for example "[charset=Windows-31J]https://example.org/path".

      Since:
      4.3.13
      See Also:

    • setLocations

      public void setLocations(List<Resource> locations)
      Configure locations to serve resources from as pre-resourced Resource's.
      See Also:

    • getLocations

      public List<Resource> getLocations()
      Return the configured List of Resource locations including both String-based locations provided via setLocationValues and pre-resolved Resource locations provided via setLocations.

      Note that the returned list is fully initialized only after initialization via afterPropertiesSet().

      Note: The list of locations may be filtered to exclude those that don't actually exist, and therefore the list returned from this method may be a subset of all given locations. See setOptimizeLocations(boolean).

      See Also:

    • setResourceResolvers

      public void setResourceResolvers(@Nullable List<ResourceResolver> resourceResolvers)
      Configure the list of ResourceResolvers to use.

      By default PathResourceResolver is configured. If using this property, it is recommended to add PathResourceResolver as the last resolver.

    • getResourceResolvers

      public List<ResourceResolver> getResourceResolvers()
      Return the list of configured resource resolvers.

    • setResourceTransformers

      public void setResourceTransformers(@Nullable List<ResourceTransformer> resourceTransformers)
      Configure the list of ResourceTransformers to use.

      By default no transformers are configured for use.

    • getResourceTransformers

      public List<ResourceTransformer> getResourceTransformers()
      Return the list of configured resource transformers.

    • setResourceHttpMessageConverter

      public void setResourceHttpMessageConverter(@Nullable ResourceHttpMessageConverter messageConverter)
      Configure the ResourceHttpMessageConverter to use.

      By default a ResourceHttpMessageConverter will be configured.

      Since:
      4.3

    • getResourceHttpMessageConverter

      public @Nullable ResourceHttpMessageConverter getResourceHttpMessageConverter()
      Return the configured resource converter.
      Since:
      4.3

    • setResourceRegionHttpMessageConverter

      public void setResourceRegionHttpMessageConverter(@Nullable ResourceRegionHttpMessageConverter messageConverter)
      Configure the ResourceRegionHttpMessageConverter to use.

      By default a ResourceRegionHttpMessageConverter will be configured.

      Since:
      4.3

    • getResourceRegionHttpMessageConverter

      public @Nullable ResourceRegionHttpMessageConverter getResourceRegionHttpMessageConverter()
      Return the configured resource region converter.
      Since:
      4.3

    • setMediaTypes

      public void setMediaTypes(Map<String, MediaType> mediaTypes)
      Add mappings between file extensions, extracted from the filename of a static Resource, and corresponding media type to set on the response.

      Use of this method is typically not necessary since mappings are otherwise determined via ServletContext.getMimeType(String) or via MediaTypeFactory.getMediaType(Resource).

      Parameters:
      mediaTypes - media type mappings
      Since:
      5.2.4

    • getMediaTypes

      public Map<String, MediaType> getMediaTypes()
      Return the configured media types.
      Since:
      5.2.4

    • setCorsConfiguration

      public void setCorsConfiguration(CorsConfiguration corsConfiguration)
      Specify the CORS configuration for resources served by this handler.

      By default this is not set in which allows cross-origin requests.

    • getCorsConfiguration

      public @Nullable CorsConfiguration getCorsConfiguration(jakarta.servlet.http.HttpServletRequest request)
      Return the specified CORS configuration.
      Specified by:
      getCorsConfiguration in interface CorsConfigurationSource
      Returns:
      the associated CorsConfiguration, or null if none

    • setUrlPathHelper

      @Deprecated(since="7.0", forRemoval=true) public void setUrlPathHelper(@Nullable UrlPathHelper urlPathHelper)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use of PathMatcher and UrlPathHelper is deprecated for use at runtime in web modules in favor of parsed patterns with PathPatternParser.
      Provide a reference to the UrlPathHelper used to map requests to static resources. This helps to derive information about the lookup path such as whether it is decoded or not.
      Since:
      4.3.13

    • getUrlPathHelper

      @Deprecated(since="7.0", forRemoval=true) public @Nullable UrlPathHelper getUrlPathHelper()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use of PathMatcher and UrlPathHelper is deprecated for use at runtime in web modules in favor of parsed patterns with PathPatternParser.
      The configured UrlPathHelper.
      Since:
      4.3.13

    • setUseLastModified

      public void setUseLastModified(boolean useLastModified)
      Set whether we should look at the Resource.lastModified() when serving resources and use this information to drive "Last-Modified" HTTP response headers.

      This option is enabled by default and should be turned off if the metadata of the static files should be ignored.

      Since:
      5.3

    • isUseLastModified

      public boolean isUseLastModified()
      Return whether the Resource.lastModified() information is used to drive HTTP responses when serving static resources.
      Since:
      5.3

    • setEtagGenerator

      public void setEtagGenerator(@Nullable Function<Resource,String> etagGenerator)
      Configure a generator function that will be used to create the ETag information, given a Resource that is about to be written to the response.

      This function should return a String that will be used as an argument in ServletWebRequest.checkNotModified(String), or null if no value can be generated for the given resource.

      Parameters:
      etagGenerator - the HTTP ETag generator function to use.
      Since:
      6.1

    • getEtagGenerator

      public @Nullable Function<Resource,String> getEtagGenerator()
      Return the HTTP ETag generator function to be used when serving resources.
      Returns:
      the HTTP ETag generator function
      Since:
      6.1

    • setOptimizeLocations

      public void setOptimizeLocations(boolean optimizeLocations)
      Set whether to optimize the specified locations through an existence check on startup, filtering non-existing directories upfront so that they do not have to be checked on every resource access.

      The default is false, for defensiveness against zip files without directory entries which are unable to expose the existence of a directory upfront. Switch this flag to true for optimized access in case of a consistent jar layout with directory entries.

      Since:
      5.3.13

    • isOptimizeLocations

      public boolean isOptimizeLocations()
      Return whether to optimize the specified locations through an existence check on startup, filtering non-existing directories upfront so that they do not have to be checked on every resource access.
      Since:
      5.3.13

    • setEmbeddedValueResolver

      public void setEmbeddedValueResolver(StringValueResolver resolver)
      Description copied from interface: EmbeddedValueResolverAware
      Set the StringValueResolver to use for resolving embedded definition values.
      Specified by:
      setEmbeddedValueResolver in interface EmbeddedValueResolverAware

    • afterPropertiesSet

      public void afterPropertiesSet() throws Exception
      Description copied from interface: InitializingBean
      Invoked by the containing BeanFactory after it has set all bean properties and satisfied BeanFactoryAware, ApplicationContextAware etc.

      This method allows the bean instance to perform validation of its overall configuration and final initialization when all bean properties have been set.

      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 for any other reason

    • initAllowedLocations

      protected void initAllowedLocations()
      Look for a PathResourceResolver among the configured resource resolvers and set its allowedLocations property (if empty) to match the locations configured on this class.

    • handleRequest

      public void handleRequest(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response) throws jakarta.servlet.ServletException, IOException
      Processes a resource request.

      Finds the requested resource under one of the configured locations. If the resource does not exist, NoResourceFoundException is raised. 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:
      jakarta.servlet.ServletException - in case of general errors
      IOException - in case of I/O errors

    • getResource

      protected @Nullable Resource getResource(jakarta.servlet.http.HttpServletRequest request) throws IOException
      Throws:
      IOException

    • processPath

      protected String processPath(String path)
      Process the given resource path.

      By default, this method delegates to ResourceHandlerUtils.normalizeInputPath(String).

      Since:
      3.2.12

    • isInvalidPath

      protected boolean isInvalidPath(String path)
      Invoked after ResourceHandlerUtils.isInvalidPath(String) to allow subclasses to perform further validation.

      By default, this method does not perform any validations.

    • getMediaType

      protected @Nullable MediaType getMediaType(jakarta.servlet.http.HttpServletRequest request, Resource resource)
      Determine the media type for the given request and the resource matched to it. This implementation tries to determine the MediaType using one of the following lookups based on the resource filename and its path extension:
      1. ServletContext.getMimeType(String)
      2. getMediaTypes()
      3. MediaTypeFactory.getMediaType(String)
      Parameters:
      request - the current request
      resource - the resource to check
      Returns:
      the corresponding media type, or null if none found

    • setHeaders

      protected void setHeaders(jakarta.servlet.http.HttpServletResponse response, Resource resource, @Nullable 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
      Throws:
      IOException - in case of errors while setting the headers

    • toString

      public String toString()
      Overrides:
      toString in class Object