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

      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:

    • 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:

    • 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:

    • 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, Object handler, 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
      handler - the handler chosen for the request
      request - the current request
      response - the current response
      See Also:

    • toString

      public String toString()
      Overrides:
      toString in class Object