Class DefaultApiVersionStrategy

java.lang.Object

org.springframework.web.accept.DefaultApiVersionStrategy

All Implemented Interfaces:

ApiVersionStrategy

public class DefaultApiVersionStrategy
extends Object
implements ApiVersionStrategy

Default implementation of ApiVersionStrategy that delegates to the configured version resolvers, version parser, and deprecation handler.

Since:

7.0

Author:

Rossen Stoyanchev

Constructor Summary

Constructors

Constructor	Description
DefaultApiVersionStrategy(List<ApiVersionResolver> versionResolvers, ApiVersionParser<?> versionParser, @Nullable Boolean versionRequired, @Nullable String defaultVersion, boolean detectSupportedVersions, @Nullable Predicate<Comparable<?>> supportedVersionPredicate, @Nullable ApiVersionDeprecationHandler deprecationHandler)	Create an instance.

Method Summary

Modifier and Type	Method	Description
void	addMappedVersion(String... versions)	Internal method to add to the list of actual version values that appear in request mappings, which allows supported versions to be discovered rather than configured.
void	addSupportedVersion(String... versions)	Add to the list of supported versions to check against in ApiVersionStrategy.validateVersion(Comparable, HttpServletRequest) before raising InvalidApiVersionException for unknown versions.
boolean	detectSupportedVersions()	Whether the strategy is configured to detect supported versions.
@Nullable Comparable<?>	getDefaultVersion()	Return a default version to use for requests that don't specify one.
void	handleDeprecations(Comparable<?> version, jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)	Check if the requested API version is deprecated, and if so handle it accordingly, e.g.
Comparable<?>	parseVersion(String version)	Parse the version of a request into an Object.
@Nullable String	resolveVersion(jakarta.servlet.http.HttpServletRequest request)	Resolve the version value from a request, e.g.
String	toString()
void	validateVersion(@Nullable Comparable<?> requestVersion, jakarta.servlet.http.HttpServletRequest request)	Validate a request version, including required and supported version checks.

Methods inherited from class Object

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

Methods inherited from interface ApiVersionStrategy

resolveParseAndValidateVersion

Constructor Details

DefaultApiVersionStrategy

public DefaultApiVersionStrategy(List<ApiVersionResolver> versionResolvers,
 ApiVersionParser<?> versionParser,
 @Nullable Boolean versionRequired,
 @Nullable String defaultVersion,
 boolean detectSupportedVersions,
 @Nullable Predicate<Comparable<?>> supportedVersionPredicate,
 @Nullable ApiVersionDeprecationHandler deprecationHandler)

Create an instance.

Parameters:

versionResolvers - one or more resolvers to try; the first non-null value returned by any resolver becomes the value used

versionParser - parser for raw version values

versionRequired - whether a version is required leading to MissingApiVersionException for requests that don't have one; by default set to true unless there is a defaultVersion

defaultVersion - a default version to assign to requests that don't specify one

detectSupportedVersions - whether to use API versions that appear in mappings for supported version validation (true), or use only explicitly configured versions (false).

deprecationHandler - handler to send hints and information about deprecated API versions to clients

Method Details

getDefaultVersion

public @Nullable Comparable<?> getDefaultVersion()

Description copied from interface: ApiVersionStrategy

Return a default version to use for requests that don't specify one.

Specified by:

getDefaultVersion in interface ApiVersionStrategy

detectSupportedVersions

public boolean detectSupportedVersions()

Whether the strategy is configured to detect supported versions. If this is set to false then addMappedVersion(String...) is ignored and the list of supported versions can be built explicitly through calls to addSupportedVersion(String...).

addSupportedVersion

public void addSupportedVersion(String... versions)

Add to the list of supported versions to check against in ApiVersionStrategy.validateVersion(Comparable, HttpServletRequest) before raising InvalidApiVersionException for unknown versions.

By default, actual version values that appear in request mappings are considered supported, and use of this method is optional. However, if you prefer to use only explicitly configured, supported versions, then set detectSupportedVersions flag to false.

Parameters:

versions - the supported versions to add

See Also:

• addMappedVersion(String...)

addMappedVersion

public void addMappedVersion(String... versions)

Internal method to add to the list of actual version values that appear in request mappings, which allows supported versions to be discovered rather than configured.

If you prefer to use explicitly configured, supported versions only, set the detectSupportedVersions flag to false.

Parameters:

versions - the versions to add

See Also:

• addSupportedVersion(String...)

resolveVersion

public @Nullable String resolveVersion(jakarta.servlet.http.HttpServletRequest request)

Description copied from interface: ApiVersionStrategy

Resolve the version value from a request, e.g. from a request header.

Specified by:

resolveVersion in interface ApiVersionStrategy

Parameters:

request - the current request

Returns:

the version, if present or null

See Also:

• ApiVersionResolver

parseVersion

public Comparable<?> parseVersion(String version)

Description copied from interface: ApiVersionStrategy

Parse the version of a request into an Object.

Specified by:

parseVersion in interface ApiVersionStrategy

Parameters:

version - the value to parse

Returns:

an Object that represents the version

See Also:

• ApiVersionParser

validateVersion

public void validateVersion(@Nullable Comparable<?> requestVersion,
 jakarta.servlet.http.HttpServletRequest request)
                     throws MissingApiVersionException,
InvalidApiVersionException

Description copied from interface: ApiVersionStrategy

Validate a request version, including required and supported version checks.

Specified by:

validateVersion in interface ApiVersionStrategy

Parameters:

requestVersion - the version to validate

request - the request

Throws:

MissingApiVersionException - if the version is required, but not specified

InvalidApiVersionException - if the version is not supported

handleDeprecations

public void handleDeprecations(Comparable<?> version,
 jakarta.servlet.http.HttpServletRequest request,
 jakarta.servlet.http.HttpServletResponse response)

Description copied from interface: ApiVersionStrategy

Check if the requested API version is deprecated, and if so handle it accordingly, e.g. by setting response headers to signal the deprecation, to specify relevant dates and provide links to further details.

Specified by:

handleDeprecations in interface ApiVersionStrategy

Parameters:

version - the resolved and parsed request version

request - the current request

response - the current response

See Also:

• ApiVersionDeprecationHandler

toString

public String toString()

Overrides:

toString in class Object