Spring Application Advisor mapping command does not infer Java version requirements for non-Spring projects

Products

• VMware Tanzu Platform Spring

Issue/Introduction

When using the Spring Application Advisor advisor mapping create command with projects that do not use Spring or Spring Boot, such as internal shared libraries or common-util projects, Advisor can detect the Maven artifact versions and generate a basic upgrade mapping.

For example, Advisor may detect the available versions of an internal artifact and generate an upgrade path such as:

common-util: 1.0.x → 2.0.x

However, Advisor does not automatically infer the required Java version for those non-Spring artifacts.

A generated mapping for an internal library may contain the artifact upgrade path:

"nextRewrite" : {
  "version" : "2.0.x",
  "project" : null
}

but the Java version requirements are not populated:

"requirements" : {
  "supportedGenerations" : { },
  "excludedArtifacts" : [ ]
}

As a result, advisor upgrade-plan get may generate a dependency upgrade plan, but it may not include the Java upgrade required by the target version of the non-Spring artifact.

For example, without Java requirements in the custom mapping, Advisor may report only:

Projects discovered:
  - common-util: 1.0.x → 2.0.x

Upgrade Plan for your Dependencies:
  - Step 1:
      * Upgrade common-util from 1.0.x to 2.0.x

If common-util:2.0.x requires Java 17, that Java requirement must be provided manually in the custom mapping.

Environment

Spring Application Advisor

Cause

.advisor/mappings/common-util.json

The current implementation of the mapping command relies on Maven metadata when generating upgrade mappings.

Maven metadata can provide artifact and version information, but it does not reliably provide the Java runtime requirement for a given artifact version. For Spring and Spring Boot projects, Advisor can derive Java compatibility from Spring-provided metadata and known compatibility rules.

For non-Spring or customer-owned artifacts, such as internal utility libraries, Advisor has no authoritative source from which to infer the required Java version automatically.

Resolution

For non-Spring artifacts where the Java version requirement cannot be inferred automatically, define the Java requirement manually in a custom upgrade mapping catalog.

1. Generate the initial mapping

Run the mapping command for the internal artifact:

advisor mapping create -c='com.example.internal:common-util'

Advisor generates the mapping file under .advisor/mappings.

Example generated file:

.advisor/mappings/common-util.json

 

2. Review the generated mapping

Inspect the generated JSON file.

Example:

{
  "slug" : "common-util",
  "coordinates" : [ "com.example.internal:common-util" ],
  "repositoryUrl" : "",
  "rewrite" : {
    "1.0.x" : {
      "recipes" : [ ],
      "nextRewrite" : {
        "version" : "2.0.x",
        "project" : null
      },
      "requirements" : {
        "supportedGenerations" : { },
        "excludedArtifacts" : [ ]
      }
    },
    "2.0.x" : {
      "recipes" : [ ],
      "nextRewrite" : null,
      "requirements" : {
        "supportedGenerations" : { },
        "excludedArtifacts" : [ ]
      }
    }
  }
}

 

The mapping contains the upgrade path from 1.0.x to 2.0.x, but it does not include Java requirements.

3. Add supportedJavaVersions manually

Edit the custom mapping and add the Java requirements inside each version’s requirements section.

Example:

{
  "slug" : "common-util",
  "coordinates" : [ "com.example.internal:common-util" ],
  "repositoryUrl" : "",
  "rewrite" : {
    "1.0.x" : {
      "recipes" : [ ],
      "nextRewrite" : {
        "version" : "2.0.x",
        "project" : null
      },
      "requirements" : {
        "supportedJavaVersions" : {
          "major" : 11,
          "minor" : 11
        },
        "supportedGenerations" : { },
        "excludedArtifacts" : [ ]
      }
    },
    "2.0.x" : {
      "recipes" : [ ],
      "nextRewrite" : null,
      "requirements" : {
        "supportedJavaVersions" : {
          "major" : 17,
          "minor" : 17
        },
        "supportedGenerations" : { },
        "excludedArtifacts" : [ ]
      }
    }
  }
}

 

In this example:

common-util:1.0.x supports Java 11
common-util:2.0.x supports Java 17

 

4. Configure Advisor to use the custom mapping

Set the custom mapping file path:

export SPRING_ADVISOR_MAPPING_CUSTOM_0_FILEPATH=$PWD/.advisor/mappings/common-util.json

If the environment requires an explicit merge strategy, set it as well:

export SPRING_ADVISOR_MAPPING_CUSTOM_0_MERGE_STRATEGY=override

 

5. Generate the upgrade plan again

Run:

advisor upgrade-plan get

 

Advisor now uses the Java requirements from the custom mapping.

Expected example output:

Projects discovered:
  - common-util: 1.0.x → 2.0.x

Upgrade Plan for your Dependencies:
  - Step 1:
      * Upgrade java from 11 to 17
  - Step 2:
      * Upgrade common-util from 1.0.x to 2.0.x

Additional Information

This behavior is expected for artifacts whose Java compatibility cannot be determined from Maven metadata or from Spring-provided compatibility information.