9A4.Upgrade 3.0.3.300

trydoforOriginalPracticeUpgradeAbout 3 min

9A4.Upgrade 3.0.3.300

Upgraded build to 300 with the following major incompatibility,

java 17 instead of 11
EE rename, jakarta instead of javax
boot 3.0 instead of 2.7, Release Notesopen in new window
check wings notable changelog

9A4.1.Modify pom.xml

change version to 3.0.3.300-SNAPSHOT

<parent>
    <groupId>pro.fessional</groupId>
    <artifactId>wings</artifactId>
    <version>3.0.3.300-SNAPSHOT</version>
</parent>

9A4.2.Dependency Change

2a.git-commit-id-pluginopen in new window

<plugin>
    <groupId>pl.project13.maven</groupId>
    <artifactId>git-commit-id-plugin</artifactId>
</plugin>
<!-- ↑↑ before ↑↑, ↓↓ after ↓↓ -->
<plugin>
    <groupId>io.github.git-commit-id</groupId>
    <artifactId>git-commit-id-maven-plugin</artifactId>
</plugin>

2b.springdocopen in new window

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-javadoc</artifactId>
</dependency>
<!-- ↑↑ before ↑↑, ↓↓ after ↓↓ -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>

// import org.springdoc.api.annotations.ParameterObject;
import org.springdoc.core.annotations.ParameterObject;
// import org.springdoc.core.SpringDocConfiguration;
import org.springdoc.core.configuration.SpringDocConfiguration;
// import org.springdoc.core.SpringDocUtils;
import org.springdoc.core.utils.SpringDocUtils;
// import org.springdoc.core.customizers.OpenApiCustomiser;
import org.springdoc.core.customizers.OpenApiCustomizer;

9A4.3.javax to jakarta namespace

The namespace changes have been completed in the springboot3 ecology. Wings mainly involves the following

jakarta.annotation.PostConstruct;
jakarta.mail.*
jakarta.servlet.*
jakarta.validation.*
jakarta.xml.bind.*

Note that not all replacements are needed, handle and exclude them differently,

Not all replacements are needed under the javax namespace
Due to indirect dependencies, both javax and jakarta packages may exist
Most 3rd libs release both javax and jakarta
IDEA provides migration tools

9A4.4.Rework Autogen

See the 277.220 upgrade guide.

Sine JPA have been disabled, now only the following javax annotations are affected,

javax.annotation.processing.Generated (JDK 9+ )
javax.annotation.Generated (JDK 8- )

9A4.5.Add-modules and Add-opens

Default --illegal-access=deny in java17, without add-opens will throws the runtime error. The wings starter.sh, pom.xml, are set correctly and can be used directly.

It is known that the argLine of surefire is not referenced when executing the Whole project test in IDEA. As a result, some of the test cases that use the reflection will fail. The solution is as follows.

Execute by module, and argLine will be auto set correctly.
For the whole project, you need to specify add-opens by yourself and refer to argLine.

9A4.6.Syntax for java17

java17 provides some comfortable syntax features, RECOMMENDED to use

PatternVariable of type casting instanceof final G g
Enhanced switch with arrow case gg -> ;
Text block instead of string concat """ """

The following features are NOT recommended

record - try to use lombok for more features and extensibility, except for small classes

9A4.7.Important Dependency

mirana 2.4.0-SNAPSHOT → 2.4.4-SNAPSHOT
springdoc 1.6.14 → 2.0.2
- org.springdoc:springdoc-openapi-starter-webmvc-ui
boot-admin 2.7.10 → 3.0.0
sentry 6.12.1 → 6.13.0
- sentry-spring-boot-starter-jakarta
flatten-maven-plugin 1.2.7 → 1.3.0

9A4.8.Wingsboot User

This subsection applies to upgrading of maven projects with wingsboot as parent in IDEA. It is recommended to upgrade from 2.7.7.220, otherwise you will need to temporarily import the libs when regenerating the jooq code.

Before starting the upgrade, the following things need to be noted and done on a new git branch

Do only one step at a time, and move on to the next if it succeeds
Commit the workspace in time for an easy fallback when each step succeeds
Make sure the compilation works first, then run runtime testcase

You can use spring-boot-migratoropen in new window to do automatic upgrades.

8a.Modify parent/version

Refer to Section 1 and use 3.0.3.300-SNAPSHOT.

Note that you should not change the version of the unnecessary dependencies, only the wings and spring related ones. Do not change any business libs that do not affect the compilation, to avoid changing too much content at once without clear boundaries.

8b.Project Use JDK17

Use OpenJDK17 from Eclipse Temurin™open in new window install directly via asdfopen in new window asdf install java temurin-17.0.9+9

Re-import the maven project, or set it in IDEA's menu

File | Project Structure (⌘;) | Project

SDK - temurin-17
Language level - SDK default

8c.Namespace jakarta

Using IDEA's refactoring feature to do jakarta's namespace migration, it is recommended to exclude jooq's auto-generated code first.

Refactor | Migrate Packages and Classes | JavaEE to JakartaEE

If Jooq code is included, do not replace javax.annotation.processing.Generated.

After the migration is complete, the compilation error, should be mainly focus on the code generated by Jooq, see the next section for the solution.

If there are 3rd deps, such as sentry, generally use the artifactId with -jakarta.

<dependency>
  <groupId>io.sentry</groupId>
  <artifactId>sentry-spring-boot-starter</artifactId>
</dependency>
<!-- ↑↑ before ↑↑, ↓↓ after ↓↓ -->
<dependency>
  <groupId>io.sentry</groupId>
  <artifactId>sentry-spring-boot-starter-jakarta</artifactId>
</dependency>

8d.Regenerate Jooq Code

If you are not upgrading from 2.7.7.220, you need to temporarily import the following dependencies, and remove them after regenerating the jooq code.

<!-- javax.persistence -->
<dependency>
    <groupId>jakarta.persistence</groupId>
    <artifactId>jakarta.persistence-api</artifactId>
</dependency>
<!-- javax.validation.constraints -->
<dependency>
    <groupId>jakarta.validation</groupId>
    <artifactId>jakarta.validation-api</artifactId>
</dependency>

There may be a jakarta.annotation.processing.Generated compilation error, you need to replace it back to javax.annotation.processing.Generated

8e.Upgrade Other Libs

Libs without compilation errors during upgrade
Those that affect compilation, but can be quickly fixed or hidden

Other than the above libs, it is recommended to upgrade them one by one after the above major changes are completed.

8f.Official Spring Migrator

After wings upgrade, follow the official spring upgrade manual and use the automated tool to check.

Release Notesopen in new window Checking the dependencies
3.0-Migration-Guideopen in new window Upgrade Guide
spring-boot-migratoropen in new window Automatic upgrade tool

Because the cascading properties of wings are not recognized by spring, the following properties need to be set manually,

logging.pattern.dateformat
management.endpoints.jmx.exposure.include
spring.factories to org.springframework.boot.autoconfigure.AutoConfiguration.imports

8g.NoSuchBeanDefinitionException

org.springframework.beans.factory.NoSuchBeanDefinitionException: No qualifying bean of type '.JiayuincFedexProp' available: expected at least 1 bean which qualifies as autowire candidate.

If using AutoConfiguration in spring.factories to Auto Scan Bean, must change to, org.springframework.boot.autoconfigure.AutoConfiguration.imports