Top Description Inners Fields Constructors Methods
org.springframework.web.servlet.resource

public Class VersionResourceResolver

extends AbstractResourceResolver
Class Inheritance
Imports
java.io.File, .IOException, .InputStream, java.net.URI, .URL, java.nio.channels.ReadableByteChannel, java.nio.charset.Charset, java.util.ArrayList, .Arrays, .Comparator, .LinkedHashMap, .List, .Map, jakarta.servlet.http.HttpServletRequest, org.springframework.core.io.AbstractResource, .Resource, org.springframework.http.HttpHeaders, org.springframework.lang.Nullable, org.springframework.util.AntPathMatcher, .Assert, .StringUtils
Resolves request paths containing a version string that can be used as part of an HTTP caching strategy in which a resource is cached with a date in the distant future (e.g. 1 year) and cached until the version, and therefore the URL, is changed.

Different versioning strategies exist, and this resolver must be configured with one or more such strategies along with path mappings to indicate which strategy applies to which resources.

ContentVersionStrategy is a good default choice except in cases where it cannot be used. Most notably the ContentVersionStrategy cannot be combined with JavaScript module loaders. For such cases the FixedVersionStrategy is a better choice.

Note that using this resolver to serve CSS files means that the CssLinkResourceTransformer should also be used in order to modify links within CSS files to also contain the appropriate versions generated by this resolver.

Authors
Brian Clozel, Rossen Stoyanchev
Since
4.1
See Also
VersionStrategy

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
VersionResourceResolver.FileNameVersionedResource

Field Summary

Modifier and TypeField and Description
private final AntPathMatcher
pathMatcher

private final Map<String, VersionStrategy>
versionStrategyMap

Map from path pattern -> VersionStrategy.

Inherited from org.springframework.web.servlet.resource.AbstractResourceResolver:
logger

Constructor Summary

AccessConstructor and Description
public
VersionResourceResolver()

Method Summary

Modifier and TypeMethod and Description
public VersionResourceResolver

Returns:

the current instance for chained method invocation
addContentVersionStrategy(String...
one or more resource URL path patterns, relative to the pattern configured with the resource handler
pathPatterns)

Insert a content-based version in resource URLs that match the given path patterns.

public VersionResourceResolver

Returns:

the current instance for chained method invocation
addFixedVersionStrategy(String
a version string
version, String...
one or more resource URL path patterns, relative to the pattern configured with the resource handler
pathPatterns)

Insert a fixed, prefix-based version in resource URLs that match the given path patterns, for example: "{version}/js/main.js".

public VersionResourceResolver

Returns:

the current instance for chained method invocation
addVersionStrategy(VersionStrategy
the custom strategy
strategy, String...
one or more resource URL path patterns, relative to the pattern configured with the resource handler
pathPatterns)

Register a custom VersionStrategy to apply to resource URLs that match the given path patterns.

protected VersionStrategy

Returns:

an instance of a VersionStrategy or null if none matches that request path
getStrategyForPath(String requestPath)

Find a VersionStrategy for the request path of the requested resource.

public Map<String, VersionStrategy>
getStrategyMap()

Return the map with version strategies keyed by path pattern.

protected Resource
resolveResourceInternal(HttpServletRequest request, String requestPath, List<? extends Resource> locations, ResourceResolverChain chain)

Implements abstract org.springframework.web.servlet.resource.AbstractResourceResolver.resolveResourceInternal.

protected String
resolveUrlPathInternal(String resourceUrlPath, List<? extends Resource> locations, ResourceResolverChain chain)

Implements abstract org.springframework.web.servlet.resource.AbstractResourceResolver.resolveUrlPathInternal.

public void
setStrategyMap(Map<String, VersionStrategy>
a map with URLs as keys and version strategies as values
map)

Set a Map with URL paths as keys and VersionStrategy as values.

Inherited from org.springframework.web.servlet.resource.AbstractResourceResolver:
resolveResourceresolveUrlPath

Field Detail

pathMatcherback to summary
private final AntPathMatcher pathMatcher
versionStrategyMapback to summary
private final Map<String, VersionStrategy> versionStrategyMap

Map from path pattern -> VersionStrategy.

Constructor Detail

VersionResourceResolverback to summary
public VersionResourceResolver()

Method Detail

addContentVersionStrategyback to summary
public VersionResourceResolver addContentVersionStrategy(String... pathPatterns)

Insert a content-based version in resource URLs that match the given path patterns. The version is computed from the content of the file, e.g. "css/main-e36d2e05253c6c7085a91522ce43a0b4.css". This is a good default strategy to use except when it cannot be, for example when using JavaScript module loaders, use addFixedVersionStrategy instead for serving JavaScript files.

Parameters
pathPatterns:String[]

one or more resource URL path patterns, relative to the pattern configured with the resource handler

Returns:VersionResourceResolver

the current instance for chained method invocation

See Also
ContentVersionStrategy
addFixedVersionStrategyback to summary
public VersionResourceResolver addFixedVersionStrategy(String version, String... pathPatterns)

Insert a fixed, prefix-based version in resource URLs that match the given path patterns, for example: "{version}/js/main.js". This is useful (vs. content-based versions) when using JavaScript module loaders.

The version may be a random number, the current date, or a value fetched from a git commit sha, a property file, or environment variable and set with SpEL expressions in the configuration (e.g. see @Value in Java config).

If not done already, variants of the given pathPatterns, prefixed with the version will be also configured. For example, adding a "/js/**" path pattern will also configure automatically a "/v1.0.0/js/**" with "v1.0.0" the version String given as an argument.

Parameters
version:String

a version string

pathPatterns:String[]

one or more resource URL path patterns, relative to the pattern configured with the resource handler

Returns:VersionResourceResolver

the current instance for chained method invocation

See Also
FixedVersionStrategy
addVersionStrategyback to summary
public VersionResourceResolver addVersionStrategy(VersionStrategy strategy, String... pathPatterns)

Register a custom VersionStrategy to apply to resource URLs that match the given path patterns.

Parameters
strategy:VersionStrategy

the custom strategy

pathPatterns:String[]

one or more resource URL path patterns, relative to the pattern configured with the resource handler

Returns:VersionResourceResolver

the current instance for chained method invocation

See Also
VersionStrategy
getStrategyForPathback to summary
protected VersionStrategy getStrategyForPath(String requestPath)

Find a VersionStrategy for the request path of the requested resource.

Returns:VersionStrategy

an instance of a VersionStrategy or null if none matches that request path

Annotations
@Nullable
getStrategyMapback to summary
public Map<String, VersionStrategy> getStrategyMap()

Return the map with version strategies keyed by path pattern.

resolveResourceInternalback to summary
protected Resource resolveResourceInternal(HttpServletRequest request, String requestPath, List<? extends Resource> locations, ResourceResolverChain chain)

Implements abstract org.springframework.web.servlet.resource.AbstractResourceResolver.resolveResourceInternal.

Annotations
@Override
@Nullable
resolveUrlPathInternalback to summary
protected String resolveUrlPathInternal(String resourceUrlPath, List<? extends Resource> locations, ResourceResolverChain chain)

Implements abstract org.springframework.web.servlet.resource.AbstractResourceResolver.resolveUrlPathInternal.

Annotations
@Override
@Nullable
setStrategyMapback to summary
public void setStrategyMap(Map<String, VersionStrategy> map)

Set a Map with URL paths as keys and VersionStrategy as values.

Supports direct URL matches and Ant-style pattern matches. For syntax details, see the org.springframework.util.AntPathMatcher javadoc.

Parameters
map:Map<String, VersionStrategy>

a map with URLs as keys and version strategies as values

org.springframework.web.servlet.resource back to summary

private Class VersionResourceResolver.FileNameVersionedResource

extends AbstractResource
implements HttpResource
Class Inheritance
All Implemented Interfaces
org.springframework.web.servlet.resource.HttpResource, org.springframework.core.io.Resource, org.springframework.core.io.InputStreamSource

Field Summary

Modifier and TypeField and Description
private final Resource
original

private final String
version

Constructor Summary

AccessConstructor and Description
public
FileNameVersionedResource(Resource original, String version)

Method Summary

Modifier and TypeMethod and Description
public long
contentLength()

Overrides org.springframework.core.io.AbstractResource.contentLength.

Implements org.springframework.core.io.Resource.contentLength.

Determine the content length for this resource.

public Resource
createRelative(String
the relative path (relative to this resource)
relativePath)

Overrides org.springframework.core.io.AbstractResource.createRelative.

Implements org.springframework.core.io.Resource.createRelative.

Create a resource relative to this resource.

public boolean
exists()

Overrides org.springframework.core.io.AbstractResource.exists.

Implements org.springframework.core.io.Resource.exists.

Determine whether this resource actually exists in physical form.

public byte[]
getContentAsByteArray()

Overrides default org.springframework.core.io.Resource.getContentAsByteArray.

Return the contents of this resource as a byte array.

public String
getContentAsString(Charset
the charset to use for decoding
charset)

Overrides default org.springframework.core.io.Resource.getContentAsString.

Return the contents of this resource as a string, using the specified charset.

public String
getDescription()

Implements org.springframework.core.io.Resource.getDescription.

Return a description for this resource, to be used for error output when working with the resource.

public File
getFile()

Overrides org.springframework.core.io.AbstractResource.getFile.

Implements org.springframework.core.io.Resource.getFile.

Return a File handle for this resource.

public String
getFilename()

Overrides org.springframework.core.io.AbstractResource.getFilename.

Implements org.springframework.core.io.Resource.getFilename.

Determine the filename for this resource — typically the last part of the path — for example, "myfile.txt".

public InputStream
getInputStream()

Implements org.springframework.core.io.InputStreamSource.getInputStream.

Return an InputStream for the content of an underlying resource.

public HttpHeaders
getResponseHeaders()

Implements org.springframework.web.servlet.resource.HttpResource.getResponseHeaders.

The HTTP headers to be contributed to the HTTP response that serves the current resource.

public URI
getURI()

Overrides org.springframework.core.io.AbstractResource.getURI.

Implements org.springframework.core.io.Resource.getURI.

Return a URI handle for this resource.

public URL
getURL()

Overrides org.springframework.core.io.AbstractResource.getURL.

Implements org.springframework.core.io.Resource.getURL.

Return a URL handle for this resource.

public boolean
isFile()

Overrides org.springframework.core.io.AbstractResource.isFile.

Overrides default org.springframework.core.io.Resource.isFile.

Determine whether this resource represents a file in a file system.

public boolean
isOpen()

Overrides org.springframework.core.io.AbstractResource.isOpen.

Overrides default org.springframework.core.io.Resource.isOpen.

Indicate whether this resource represents a handle with an open stream.

public boolean
isReadable()

Overrides org.springframework.core.io.AbstractResource.isReadable.

Overrides default org.springframework.core.io.Resource.isReadable.

Indicate whether non-empty contents of this resource can be read via getInputStream().

public long
lastModified()

Overrides org.springframework.core.io.AbstractResource.lastModified.

Implements org.springframework.core.io.Resource.lastModified.

Determine the last-modified timestamp for this resource.

public ReadableByteChannel
readableChannel()

Overrides org.springframework.core.io.AbstractResource.readableChannel.

Overrides default org.springframework.core.io.Resource.readableChannel.

Return a ReadableByteChannel.

Inherited from org.springframework.core.io.AbstractResource:
equalsgetFileForLastModifiedCheckhashCodetoString

Field Detail

originalback to summary
private final Resource original
versionback to summary
private final String version

Constructor Detail

FileNameVersionedResourceback to summary
public FileNameVersionedResource(Resource original, String version)

Method Detail

contentLengthback to summary
public long contentLength() throws IOException

Overrides org.springframework.core.io.AbstractResource.contentLength.

Implements org.springframework.core.io.Resource.contentLength.

Doc from org.springframework.core.io.Resource.contentLength.

Determine the content length for this resource.

Annotations
@Override
Exceptions
IOException:
if the resource cannot be resolved (in the file system or as some other known physical resource type)
createRelativeback to summary
public Resource createRelative(String relativePath) throws IOException

Overrides org.springframework.core.io.AbstractResource.createRelative.

Implements org.springframework.core.io.Resource.createRelative.

Doc from org.springframework.core.io.Resource.createRelative.

Create a resource relative to this resource.

Parameters
relativePath:String

the relative path (relative to this resource)

Returns:Resource

the resource handle for the relative resource

Annotations
@Override
Exceptions
IOException:
if the relative resource cannot be determined
existsback to summary
public boolean exists()

Overrides org.springframework.core.io.AbstractResource.exists.

Implements org.springframework.core.io.Resource.exists.

Doc from org.springframework.core.io.Resource.exists.

Determine whether this resource actually exists in physical form.

This method performs a definitive existence check, whereas the existence of a Resource handle only guarantees a valid descriptor handle.

Annotations
@Override
getContentAsByteArrayback to summary
public byte[] getContentAsByteArray() throws IOException

Overrides default org.springframework.core.io.Resource.getContentAsByteArray.

Doc from org.springframework.core.io.Resource.getContentAsByteArray.

Return the contents of this resource as a byte array.

Returns:byte[]

the contents of this resource as byte array

Annotations
@Override
Exceptions
IOException:
in case of general resolution/reading failures
getContentAsStringback to summary
public String getContentAsString(Charset charset) throws IOException

Overrides default org.springframework.core.io.Resource.getContentAsString.

Doc from org.springframework.core.io.Resource.getContentAsString.

Return the contents of this resource as a string, using the specified charset.

Parameters
charset:Charset

the charset to use for decoding

Returns:String

the contents of this resource as a String

Annotations
@Override
Exceptions
IOException:
in case of general resolution/reading failures
getDescriptionback to summary
public String getDescription()

Implements org.springframework.core.io.Resource.getDescription.

Doc from org.springframework.core.io.Resource.getDescription.

Return a description for this resource, to be used for error output when working with the resource.

Implementations are also encouraged to return this value from their toString method.

Annotations
@Override
getFileback to summary
public File getFile() throws IOException

Overrides org.springframework.core.io.AbstractResource.getFile.

Implements org.springframework.core.io.Resource.getFile.

Doc from org.springframework.core.io.Resource.getFile.

Return a File handle for this resource.

Annotations
@Override
Exceptions
IOException:
in case of general resolution/reading failures
getFilenameback to summary
public String getFilename()

Overrides org.springframework.core.io.AbstractResource.getFilename.

Implements org.springframework.core.io.Resource.getFilename.

Doc from org.springframework.core.io.Resource.getFilename.

Determine the filename for this resource — typically the last part of the path — for example, "myfile.txt".

Returns null if this type of resource does not have a filename.

Implementations are encouraged to return the filename unencoded.

Annotations
@Override
@Nullable
getInputStreamback to summary
public InputStream getInputStream() throws IOException

Implements org.springframework.core.io.InputStreamSource.getInputStream.

Doc from org.springframework.core.io.InputStreamSource.getInputStream.

Return an InputStream for the content of an underlying resource.

It is expected that each call creates a fresh stream.

This requirement is particularly important when you consider an API such as JavaMail, which needs to be able to read the stream multiple times when creating mail attachments. For such a use case, it is required that each getInputStream() call returns a fresh stream.

Returns:InputStream

the input stream for the underlying resource (must not be null)

Annotations
@Override
Exceptions
IOException:
if the content stream could not be opened
getResponseHeadersback to summary
public HttpHeaders getResponseHeaders()

Implements org.springframework.web.servlet.resource.HttpResource.getResponseHeaders.

Doc from org.springframework.web.servlet.resource.HttpResource.getResponseHeaders.

The HTTP headers to be contributed to the HTTP response that serves the current resource.

Returns:HttpHeaders

the HTTP response headers

Annotations
@Override
getURIback to summary
public URI getURI() throws IOException

Overrides org.springframework.core.io.AbstractResource.getURI.

Implements org.springframework.core.io.Resource.getURI.

Doc from org.springframework.core.io.Resource.getURI.

Return a URI handle for this resource.

Annotations
@Override
Exceptions
IOException:
if the resource cannot be resolved as URI, i.e. if the resource is not available as a descriptor
getURLback to summary
public URL getURL() throws IOException

Overrides org.springframework.core.io.AbstractResource.getURL.

Implements org.springframework.core.io.Resource.getURL.

Doc from org.springframework.core.io.Resource.getURL.

Return a URL handle for this resource.

Annotations
@Override
Exceptions
IOException:
if the resource cannot be resolved as URL, i.e. if the resource is not available as a descriptor
isFileback to summary
public boolean isFile()

Overrides org.springframework.core.io.AbstractResource.isFile.

Overrides default org.springframework.core.io.Resource.isFile.

Doc from org.springframework.core.io.Resource.isFile.

Determine whether this resource represents a file in a file system.

A value of true strongly suggests (but does not guarantee) that a getFile() call will succeed.

This is conservatively false by default.

Annotations
@Override
isOpenback to summary
public boolean isOpen()

Overrides org.springframework.core.io.AbstractResource.isOpen.

Overrides default org.springframework.core.io.Resource.isOpen.

Doc from org.springframework.core.io.Resource.isOpen.

Indicate whether this resource represents a handle with an open stream. If true, the InputStream cannot be read multiple times, and must be read and closed to avoid resource leaks.

Will be false for typical resource descriptors.

Annotations
@Override
isReadableback to summary
public boolean isReadable()

Overrides org.springframework.core.io.AbstractResource.isReadable.

Overrides default org.springframework.core.io.Resource.isReadable.

Doc from org.springframework.core.io.Resource.isReadable.

Indicate whether non-empty contents of this resource can be read via getInputStream().

Will be true for typical resource descriptors that exist since it strictly implies exists() semantics as of 5.1. Note that actual content reading may still fail when attempted. However, a value of false is a definitive indication that the resource content cannot be read.

Annotations
@Override
lastModifiedback to summary
public long lastModified() throws IOException

Overrides org.springframework.core.io.AbstractResource.lastModified.

Implements org.springframework.core.io.Resource.lastModified.

Doc from org.springframework.core.io.Resource.lastModified.

Determine the last-modified timestamp for this resource.

Annotations
@Override
Exceptions
IOException:
if the resource cannot be resolved (in the file system or as some other known physical resource type)
readableChannelback to summary
public ReadableByteChannel readableChannel() throws IOException

Overrides org.springframework.core.io.AbstractResource.readableChannel.

Overrides default org.springframework.core.io.Resource.readableChannel.

Doc from org.springframework.core.io.Resource.readableChannel.

Return a ReadableByteChannel.

It is expected that each call creates a fresh channel.

The default implementation returns Channels#newChannel(InputStream) with the result of getInputStream().

Returns:ReadableByteChannel

the byte channel for the underlying resource (must not be null)

Annotations
@Override
Exceptions
IOException:
if the content channel could not be opened