Mastering the Transition: Navigating Java 17, Spring 6, and Spring Boot 3 Upgrades

Mastering the Transition: Navigating Java 17, Spring 6, and Spring Boot 3 Upgrades

This article was authored by Vidhyadharan Deivamani

He has over 15 years of experience with robust background in Java and front-end development, specializing in complex architectures and API management. He seamlessly integrated technologies like HUGO and Angular 6, developed multi-tenant web apps with Spring Boot, and orchestrated secure environments using Keycloak OAuth2/OpenID. His expertise extends to DevOps practices, CI/CD pipelines, K8S and ensuring code quality through code reviews and static code analysis tools. He also regular speaker and participant of Java User Group Chennai.

Introduction

Navigating the Java 17, Spring 6, and Spring Boot 3 Upgrade Journey can be a challenging yet rewarding endeavor. As you embark on this journey, it’s crucial to understand the scope of the upgrade and the key considerations involved in each component’s migration. In this article, we’ll delve into essential aspects of upgrading, including migrating from Java EE to Jakarta EE in Spring 6, updating Hibernate configurations for Java 17 and Spring 6, upgrading API documentation from Swagger to OpenAPI, transitioning to Apache HttpClient 5, and migrating to Java 17 with Spring Boot 3 using OpenRewrite.

Migrating from Java EE to Jakarta EE in Spring 6

When upgrading to Spring 6 and Spring Boot 3, compatibility with Java EE or Jakarta EE APIs is paramount. This entails updating imports and configurations to align with namespace changes. For instance, understanding the mapping between Java EE and Jakarta EE namespaces is crucial for a seamless migration:

Java EE NamespaceJakarta EE Namespace
javax.servletjakarta.servlet
javax.servlet.httpjakarta.servlet.http
javax.servlet.annotationjakarta.servlet.annotation
javax.servlet.descriptorjakarta.servlet.descriptor
javax.servlet.jspjakarta.servlet.jsp
javax.servlet.jsp.eljakarta.servlet.jsp.el
javax.servlet.jsp.tagextjakarta.servlet.jsp.tagext
javax.websocketjakarta.websocket
javax.websocket.serverjakarta.websocket.server
javax.xml.*jakarta.xml.*
javax.activationjakarta.activation
javax.annotationjakarta.annotation
javax.enterprisejakarta.enterprise
javax.jmsjakarta.jms
javax.jwsjakarta.jws
javax.mailjakarta.mail
javax.managementjakarta.management
javax.persistencejakarta.persistence
javax.security.*jakarta.security.*
javax.transactionjakarta.transaction
javax.validationjakarta.validation
javax.websocketjakarta.websocket
javax.xml.*jakarta.xml.*

Hibernate Update in Java 17 and Spring 6

Upgrading to Java 17 and Spring 6 necessitates considerations for updating Hibernate configurations. Key points to note include updating the Hibernate dialect and annotations for defining custom types. Ensuring compatibility with the latest Hibernate versions and adhering to evolving best practices is essential.

  1. Hibernate Dialect Update: The org.hibernate.dialect.MySQLDialect is supported from Hibernate 5.3 onwards. Prior to Hibernate 5.3, it was recommended to use org.hibernate.dialect.MySQL57Dialect for MySQL 5.x and 8.x. However, with the release of Hibernate 5.3, a org.hibernate.dialect.MySQL8Dialect was introduced, and it is recommended to use org.hibernate.dialect.MySQLDialect since Hibernate 6, as org.hibernate.dialect.MySQL8Dialect is deprecated.

  2. Type and TypeDef Annotations Update: In Hibernate 6, there are changes in the annotations used for defining custom types. For example, the usage of @TypeDef and @Type annotations has been updated.

<dependency>
    <groupId>com.vladmihalcea</groupId>
    <artifactId>hibernate-types-60</artifactId>
    <version><!-- specify version --></version>
</dependency>

Instead of:

import org.hibernate.annotations.Type;
import org.hibernate.annotations.TypeDef;

@TypeDef(name = "json", typeClass = StringJsonUserType.class)
public class EntityName {

 @Type(type = "json")
 private propertyName
}

You should now use:

import jakarta.persistence.Convert;
import org.hibernate.annotations.JdbcTypeCode;

@Convert(attributeName = "entityAttrName", converter = StringJsonUserType.class)
public class EntityName {

 @JdbcTypeCode(SqlTypes.JSON)
 private propertyName
}

API documentation upgrade swagger to OpenAPI

Migrating from Swagger annotations to OpenAPI annotations involves updating your codebase to use the newer annotations provided by the springdoc-openapi library, as well as adjusting any configuration or usage accordingly. Here’s a list of some common changes you may need to make:

Swagger AnnotationOpenAPI (springdoc-openapi) Annotation
io.swagger.annotations.ApiIgnoreorg.springdoc.core.annotations.Hidden
io.swagger.annotations.ApiModelPropertyio.swagger.v3.oas.annotations.media.Schema
io.swagger.annotations.ApiParamio.swagger.v3.oas.annotations.Parameter
io.swagger.annotations.ApiOperationio.swagger.v3.oas.annotations.Operation
io.swagger.annotations.ApiResponseio.swagger.v3.oas.annotations.responses.ApiResponse
io.swagger.annotations.ApiModelio.swagger.v3.oas.annotations.media.Schema
io.swagger.annotations.ApiImplicitParamsio.swagger.v3.oas.annotations.parameters.Parameters
io.swagger.annotations.ApiResponsesio.swagger.v3.oas.annotations.responses.ApiResponse

Swagger Annotation: @ApiIgnore

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiIgnore;

@Api(tags = "Sample Controller")
public class SampleController {

    @ApiIgnore
    public void ignoredMethod() {
        // This method will be ignored in Swagger documentation
    }
}

OpenAPI (springdoc-openapi) Annotation: Hidden

import org.springdoc.core.annotations.Hidden;
import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "Sample Controller")
public class SampleController {

    @Hidden
    public void ignoredMethod() {
        // This method will be hidden in OpenAPI documentation
    }
}

Swagger Annotation: @ApiModelProperty


import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
public class SampleModel {

    @ApiModelProperty(value = "The ID of the entity", example = "1")
    private Long id;

    @ApiModelProperty(value = "The name of the entity")
    private String name;
}

OpenAPI (springdoc-openapi) Annotation: Schema Flor


import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
public class SampleModel {

    @Schema(description = "The ID of the entity", example = "1")
    private Long id;

    @Schema(description = "The name of the entity")
    private String name;
}

Upgrading to Apache HttpClient 5

Key Differences:

  • Package Names: HttpClient 5 uses org.apache.hc.client5.http and related packages, whereas HttpClient 4 uses org.apache.http.

  • Class Structure: HttpClient 5 introduces new classes and restructures existing ones for configuration and connection management.

  • SSL Context Handling: HttpClient 5 provides a different approach for SSL context handling using SSLConnectionSocketFactoryBuilder.

  • Connection Pooling Configuration: Configuration related to connection pooling is done differently in HttpClient 5 with PoolingHttpClientConnectionManagerBuilder.

  • Proxy Configuration: HttpClient 5 proxy configuration involves changes in how HttpHost is used.

import org.apache.http.HttpHost;
import org.apache.http.conn.ssl.SSLConnectionSocketFactory;
import org.apache.http.conn.ssl.TrustStrategy;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.ssl.SSLContexts;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.config.ConfigurableBeanFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Scope;
import org.springframework.core.env.Environment;
import org.springframework.http.client.ClientHttpRequestFactory;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
import org.springframework.util.StringUtils;

import javax.net.ssl.SSLContext;
import java.security.KeyManagementException;
import java.security.KeyStoreException;
import java.security.NoSuchAlgorithmException;
import java.security.cert.CertificateException;

@Configuration
public class RestTemplateConfiguration {

    private final static Logger logger = LoggerFactory.getLogger(RestTemplateConfiguration.class);

    @Autowired
    private Environment environment;

    @Autowired
    private ApplicationProperties appconfig;

    @Bean
    @Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE)
    public ClientHttpRequestFactory clientHttpRequestFactory() throws KeyStoreException, NoSuchAlgorithmException, KeyManagementException {
        HttpComponentsClientHttpRequestFactory requestFactory = null;

        String proxyHost = environment.getProperty("proxy.host");
        String proxyPortStr = environment.getProperty("proxy.port");
        Integer proxyPort = null;

        if (!StringUtils.isEmpty(proxyPortStr)) {
            proxyPort = Integer.valueOf(proxyPortStr);
        }

        // Proxy
        if (!StringUtils.isEmpty(proxyHost) && proxyPort != null) {
            requestFactory = new HttpComponentsClientHttpRequestFactory(
                HttpClients.custom()
                    .setProxy(new HttpHost(proxyHost, proxyPort))
                    .build());
            logger.info("Using proxy {}:{}", proxyHost, proxyPort);
        } else {
            requestFactory = new HttpComponentsClientHttpRequestFactory();
        }

        requestFactory.setConnectTimeout(appconfig.getConfig().getConnectTimeout());
        requestFactory.setReadTimeout(appconfig.getConfig().getReadTimeout());

        // SSL
        TrustStrategy acceptingTrustStrategy = (chain, authType) -> true;
        SSLContext sslContext = SSLContexts.custom()
            .loadTrustMaterial(null, acceptingTrustStrategy)
            .build();

        SSLConnectionSocketFactory csf = new SSLConnectionSocketFactory(sslContext);
        CloseableHttpClient httpClient = HttpClients.custom()
            .setSSLSocketFactory(csf)
            .build();

        requestFactory.setHttpClient(httpClient);

        return requestFactory;
    }
}

view rawRestTemplateLegacy.java hosted with ❤ by GitHub

New updated migrated code

import org.apache.hc.client5.http.config.ConnectionConfig;
import org.apache.hc.client5.http.config.RequestConfig;
import org.apache.hc.client5.http.cookie.StandardCookieSpec;
import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClients;
import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManager;
import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManagerBuilder;
import org.apache.hc.client5.http.ssl.SSLConnectionSocketFactoryBuilder;
import org.apache.hc.client5.http.ssl.SSLConnectionSocketFactory;
import org.apache.hc.core5.http.io.SocketConfig;
import org.apache.hc.core5.http.ssl.TLS;
import org.apache.hc.core5.pool.PoolConcurrencyPolicy;
import org.apache.hc.core5.pool.PoolReusePolicy;
import org.apache.hc.core5.util.TimeValue;
import org.apache.hc.core5.util.Timeout;
import org.apache.http.HttpHost;
import org.apache.http.conn.ssl.TrustStrategy;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.ssl.SSLContexts;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.config.ConfigurableBeanFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Scope;
import org.springframework.core.env.Environment;
import org.springframework.http.client.ClientHttpRequestFactory;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
import org.springframework.util.StringUtils;

import javax.net.ssl.SSLContext;
import java.io.IOException;
import java.security.KeyManagementException;
import java.security.KeyStoreException;
import java.security.NoSuchAlgorithmException;
import java.security.cert.CertificateException;
import java.security.cert.X509Certificate;

@Configuration
public class RestTemplateConfiguration {

    private final static Logger logger = LoggerFactory.getLogger(RestTemplateConfiguration.class);

    @Autowired
    private Environment environment;

    @Autowired
    private ApplicationProperties appconfig;

    @Bean
    @Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE)
    public ClientHttpRequestFactory clientHttpRequestFactory() throws KeyStoreException, NoSuchAlgorithmException, KeyManagementException, IOException {
        CloseableHttpClient httpClient = HttpClients.custom()
            .setConnectionManager(getConnectionManager())
            .setDefaultRequestConfig(RequestConfig.custom()
                .setCookieSpec(StandardCookieSpec.STRICT)
                .build())
            .build();

        HttpComponentsClientHttpRequestFactory requestFactory = new HttpComponentsClientHttpRequestFactory();

        String proxyHost = environment.getProperty("proxy.host");
        String proxyPortStr = environment.getProperty("proxy.port");
        Integer proxyPort = null;
        if (!StringUtils.isEmpty(proxyPortStr)) {
            proxyPort = Integer.valueOf(proxyPortStr);
        }

        // Proxy
        if (!StringUtils.isEmpty(proxyHost) && proxyPort != null) {
            requestFactory = new HttpComponentsClientHttpRequestFactory(
                HttpClients.custom()
                    .setProxy(new org.apache.hc.core5.http.HttpHost(proxyHost, proxyPort))
                    .build());
            logger.info("Using proxy {}:{}", proxyHost, proxyPort);
        } else {
            requestFactory = new HttpComponentsClientHttpRequestFactory();
        }
        return requestFactory;
    }

    public PoolingHttpClientConnectionManager getConnectionManager() throws IOException {
        TrustStrategy acceptingTrustStrategy = (X509Certificate[] chain, String authType) -> true;

        SSLContext sslContext = null;
        try {
            sslContext = SSLContexts.custom().loadTrustMaterial(null, acceptingTrustStrategy).build();
        } catch (KeyManagementException | NoSuchAlgorithmException | KeyStoreException e) {
            throw new IOException(e);
        }

        SSLConnectionSocketFactory csf = new SSLConnectionSocketFactory(sslContext);
        PoolingHttpClientConnectionManager connectionManager = PoolingHttpClientConnectionManagerBuilder.create()
            .setSSLSocketFactory(SSLConnectionSocketFactoryBuilder.create()
                .setSslContext(org.apache.hc.core5.ssl.SSLContexts.createSystemDefault())
                .setTlsVersions(TLS.V_1_3)
                .build())
            .setSSLSocketFactory(csf)
            .setDefaultSocketConfig(SocketConfig.custom()
                .setSoTimeout(Timeout.ofMinutes(10))
                .build())
            .setPoolConcurrencyPolicy(PoolConcurrencyPolicy.STRICT)
            .setConnPoolPolicy(PoolReusePolicy.LIFO)
            .setDefaultConnectionConfig(ConnectionConfig.custom()
                .setSocketTimeout(Timeout.ofMilliseconds(appconfig.getConfig().getReadTimeout()))
                .setConnectTimeout(Timeout.ofMilliseconds(appconfig.getConfig().getConnectTimeout()))
                .setTimeToLive(TimeValue.ofMinutes(10))
                .build())
            .build();
        return connectionManager;
    }
}

view rawRestTemplateHttp5Upgrade.java hosted with ❤ by GitHub

Additional Notes:

  • WebClient: Remember that WebClient is the recommended alternative to RestTemplate for new applications, as it provides both synchronous and asynchronous capabilities.

  • RestTemplate: However, if you’re working with existing code, RestTemplate remains a viable choice.

The new webclient will be

import io.netty.channel.ChannelOption;
import io.netty.handler.timeout.ReadTimeoutHandler;
import io.netty.handler.timeout.WriteTimeoutHandler;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.client.reactive.ClientHttpConnector;
import org.springframework.http.client.reactive.ReactorClientHttpConnector;
import org.springframework.web.reactive.config.WebFluxConfigurer;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.netty.http.client.HttpClient;

@Configuration
public class WebFluxConfig implements WebFluxConfigurer {

    private static final Logger logger = LoggerFactory.getLogger(WebFluxConfig.class);

    @Autowired
    private RestTimeoutConfiguration timeoutConfiguration;

    @Bean
    public WebClient getWebClient() {
        HttpClient httpClient = HttpClient
            .create()
            .tcpConfiguration(client ->
                client
                    .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, timeoutConfiguration.getConnectTimeout())
                    .doOnConnected(conn ->
                        conn
                            .addHandlerLast(new ReadTimeoutHandler(timeoutConfiguration.getReadTimeout()))
                            .addHandlerLast(new WriteTimeoutHandler(timeoutConfiguration.getWriteTimeout()))
                    )
            );

        ClientHttpConnector connector = new ReactorClientHttpConnector(httpClient.wiretap(true));
        logger.info("WebClient initialized");
        return WebClient
            .builder()            
            .clientConnector(connector)
            .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
            .build();
    }
}

view rawWebFluxConfig.java hosted with ❤ by GitHub

Migrating to Java 17 with Spring Boot 3 using OpenRewrite

Introduction to OpenRewrite

OpenRewrite is a powerful tool for automating code refactoring and transformation tasks in Java projects. It provides a flexible framework for writing custom rules to analyze and modify Java code programmatically. In this section, we’ll explore how to integrate OpenRewrite into both Maven and Gradle projects to facilitate the migration from Java 11 to Java 17, along with Spring Boot 3.

// Before OpenRewrite
import javax.servlet.http.HttpServletRequest;
...
// After OpenRewrite
import jakarta.servlet.http.HttpServletRequest;
...

Integrating OpenRewrite into Maven Projects

Step 1: Add OpenRewrite Plugin to pom.xml

To use OpenRewrite in a Maven project, first, add the OpenRewrite Maven plugin to your project’s pom.xml:

<project>
  <build>
    <plugins>
      <plugin>
        <groupId>org.openrewrite.maven</groupId>
        <artifactId>rewrite-maven-plugin</artifactId>
        <version>5.27.0</version>
        <configuration>
          <activeRecipes>
            <recipe>org.openrewrite.java.migrate.UpgradeToJava17</recipe>
          </activeRecipes>
        </configuration>
        <dependencies>
          <dependency>
            <groupId>org.openrewrite.recipe</groupId>
            <artifactId>rewrite-migrate-java</artifactId>
            <version>2.11.0</version>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>
</project>

Run mvn rewrite:run to run the recipe. alternatively

mvn -U org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE -Drewrite.activeRecipes=org.openrewrite.java.migrate.UpgradeToJava17

Integrating OpenRewrite into Gradle Projects

Step 1: Add OpenRewrite Plugin to gradle

  • Add the following to your build.gradle file:

      plugins {
          id("org.openrewrite.rewrite") version("6.11.2")
      }
    
      rewrite {
          activeRecipe("org.openrewrite.java.migrate.UpgradeToJava17")
      }
    
      repositories {
          mavenCentral()
      }
    
      dependencies {
          rewrite("org.openrewrite.recipe:rewrite-migrate-java:2.11.0")
      }
    
  • Run gradle rewriteRun to run the recipe.