Migration Java 21 + Spring 6 de SAP Commerce Cloud : guide du développeur

Si vous faites tourner du code Java personnalisé sur SAP Commerce Cloud, vous avez une échéance ferme : le 30 juin 2026. Après cette date, les environnements SAP Commerce Cloud exigent Java 21. Pas de prolongation. Pas de période de grâce. Les déploiements compilés sous Java 17 ne passeront pas le pipeline de build.

Et Java 21 n’arrive pas seul. La plateforme est passée de Spring Framework 5 à Spring Framework 6, ce qui entraîne la migration du namespace Jakarta EE. Cela signifie que javax.servlet, javax.persistence, javax.validation — les imports que vous écrivez depuis 15 ans — disparaissent. Remplacés par jakarta.*.

Ce n’est pas un changement cosmétique. Il touche vos servlets, vos entités JPA, vos annotations de validation, votre configuration Spring Security et potentiellement chaque extension personnalisée que vous avez construite. La bonne nouvelle : des outils existent qui gèrent environ 80 % du travail mécanique. Les 20 % restants sont là où le vrai travail d’ingénierie intervient.

En bref : SAP Commerce Cloud exige Java 21 d’ici le 30 juin 2026. La plateforme a déjà migré vers Spring 6 et Jakarta EE 10, ce qui signifie que le namespace javax.* est mort. OpenRewrite automatise l’essentiel de la migration de namespace, mais les réécritures Spring Security, les configurations AOP personnalisées et le code utilisant massivement la réflexion nécessitent une intervention manuelle. Prévoyez 2 à 4 semaines pour la migration et 2 à 3 semaines pour les tests de régression. Commencez maintenant — les équipes qui attendent mai découvrent des problèmes qu’elles ne peuvent pas résoudre en quatre semaines.

Ce qui change et pourquoi

Trois évolutions se produisent simultanément. Elles sont liées, mais elles cassent des choses différentes dans votre base de code.

Java 17 vers Java 21. SAP Commerce Cloud avait adopté Java 17 comme version minimale avec la release 2211. Désormais, la plateforme passe à Java 21, qui est une version LTS (Long-Term Support) depuis septembre 2023. Java 21 introduit les threads virtuels, le pattern matching pour switch, les record patterns et les collections séquencées. La plupart de ces fonctionnalités sont additives — elles ne casseront pas le code existant. Ce qui cassera : les API supprimées qui étaient dépréciées depuis Java 9 mais fonctionnaient encore sous 17, et l’encapsulation renforcée des composants internes du JDK auxquels certaines bibliothèques accèdent par réflexion.

Spring 5 vers Spring 6. Spring Framework 6.0 requiert Java 17+ et utilise les API Jakarta EE 9+ comme base. C’est le changement majeur. Spring 6 a abandonné le support du namespace javax.* entièrement. Chaque module Spring — Web MVC, Security, Data JPA, AOP — dépend désormais des équivalents jakarta.*. Si votre code personnalisé étend des classes Spring ou implémente des interfaces Spring qui référencent des types javax.*, il ne compilera pas sous Spring 6.

Migration du namespace Jakarta EE 9/10. La communauté Java a renommé les packages javax.* en jakarta.* après le transfert de Java EE par Oracle à la Fondation Eclipse. C’est un changement mécanique (renommage de packages), mais il est omniprésent. Chaque instruction d’import, chaque nom de classe pleinement qualifié dans la configuration XML, chaque référence de chaîne à javax.persistence.Entity — tout doit être mis à jour.

Pour un examen approfondi de la façon dont l’architecture de Commerce Cloud gère ces changements au niveau de la plateforme, consultez notre guide de l’architecture SAP Commerce Cloud.

Le calendrier

SAP a déployé ces changements par phases. Voici ce qui s’est déjà produit et ce qui reste :

La fenêtre entre « outillage disponible » et « échéance » est d’environ six mois. Ça semble confortable. Ça ne l’est pas. La plupart des projets Commerce Cloud comportent 50’000 à 200’000 lignes de code Java personnalisé réparties sur des dizaines d’extensions. La migration de namespace seule génère des milliers de modifications de fichiers. Les tests prennent plus de temps que la migration elle-même.

Notre recommandation : Commencez la migration maintenant. Exécutez l’outillage automatisé, corrigez ce qu’il ne peut pas gérer, et démarrez les tests de régression. Les équipes qui commencent au T2 2026 ont le temps pour deux cycles de test complets. Les équipes qui commencent en juin ont le temps pour la panique.

Checklist des breaking changes

Voici ce que vous allez rencontrer, classé approximativement par fréquence et impact.

Migration du namespace javax.* vers jakarta.*

C’est le changement le plus omniprésent. Chaque référence à ces packages doit être mise à jour :

Avant :

import javax.servlet.http.HttpServletRequest;
import javax.persistence.Entity;
import javax.persistence.Column;
import javax.validation.constraints.NotNull;

@Entity
public class CustomProduct {
    @Column(nullable = false)
    @NotNull
    private String customField;
}

Après :

import jakarta.servlet.http.HttpServletRequest;
import jakarta.persistence.Entity;
import jakarta.persistence.Column;
import jakarta.validation.constraints.NotNull;

@Entity
public class CustomProduct {
    @Column(nullable = false)
    @NotNull
    private String customField;
}

Un simple chercher-remplacer ? En grande partie. Mais attention aux littéraux de chaîne et aux fichiers XML où javax.persistence apparaît comme nom de classe pleinement qualifié. OpenRewrite attrape la plupart de ces cas. Un grep manuel attrape le reste.

Changements Spring Security

Spring Security 6 a introduit plusieurs breaking changes qui affectent les projets Commerce Cloud. Le plus important : WebSecurityConfigurerAdapter a disparu.

Avant (Spring Security 5) :

@Configuration
@EnableWebSecurity
public class CustomSecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
            .antMatchers("/api/public/**").permitAll()
            .antMatchers("/api/admin/**").hasRole("ADMIN")
            .anyRequest().authenticated();
    }
}

Après (Spring Security 6) :

@Configuration
@EnableWebSecurity
public class CustomSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            );
        return http.build();
    }
}

Points clés à surveiller :

• WebSecurityConfigurerAdapter supprimé — utilisez des beans SecurityFilterChain à la place
• authorizeRequests() remplacé par authorizeHttpRequests()
• antMatchers() remplacé par requestMatchers()
• csrf(), cors(), sessionManagement() utilisent désormais exclusivement le DSL lambda
• SecurityContext utilise RequestAttributeSecurityContextRepository par défaut (plus basé sur la session)

Si votre projet Commerce Cloud a des configurations Spring Security personnalisées pour l’authentification storefront, la connexion B2B ou l’accès backoffice — elles devront être réécrites manuellement. Le DSL lambda est plus composable, mais vous ne pouvez pas simplement renommer les méthodes.

Dépréciations Spring MVC

Spring 6 a supprimé plusieurs patterns qui étaient dépréciés dans la version 5.x :

• Changements de type de retour @RequestMapping : les méthodes retournant un String comme nom de vue fonctionnent toujours, mais la gestion de ModelAndView présente des changements subtils de comportement concernant la sémantique de redirection.
• CommonsMultipartResolver remplacé par StandardServletMultipartResolver. Si vous aviez configuré un traitement personnalisé de l’upload de fichiers, mettez à jour le bean resolver.
• Correspondance du slash final désactivée par défaut. /api/products/ et /api/products sont désormais des routes différentes. Si votre storefront ou vos clients API dépendent de la tolérance au slash final, configurez PathMatchConfigurer.setUseTrailingSlashMatch(true) — mais prévoyez de corriger les URL à terme.

Changements Hibernate 6 (JPA)

SAP Commerce Cloud utilise Hibernate comme fournisseur JPA. Le passage à Jakarta EE implique Hibernate 6.x, qui apporte son lot de changements :

• Génération d’ID basée sur les séquences par défaut. Hibernate 6 préfère SEQUENCE à IDENTITY pour @GeneratedValue. Si vous dépendez du comportement auto-increment, définissez explicitement strategy = GenerationType.IDENTITY.
• Refonte du système de types. Les implémentations personnalisées de UserType doivent être mises à jour. L’interface UserType a changé sa signature générique.
• Changements de l’annotation @Type. @Type(type = "yes_no") devient @Convert(converter = YesNoConverter.class) ou @JdbcTypeCode(Types.CHAR).
• Application implicite de @Column(length). Hibernate 6 applique plus strictement la validation de la longueur des colonnes au niveau du schéma. Les colonnes qui fonctionnaient avec des valeurs par défaut implicites peuvent maintenant lever des exceptions de validation.

Avant :

@Type(type = "yes_no")
private Boolean active;

Après :

@Convert(converter = org.hibernate.type.YesNoConverter.class)
private Boolean active;

API Java supprimées

Java 21 a supprimé plusieurs API qui étaient dépréciées pour suppression depuis Java 9-11. Vérifiez votre base de code pour :

• java.lang.SecurityManager — entièrement supprimé. Si une extension l’utilise (rare dans Commerce Cloud, mais vérifiez les bibliothèques tierces), elle doit être réécrite.
• Constructeurs de java.util.Date / Calendar — certains constructeurs dépréciés ont été supprimés. Utilisez java.time.* à la place.
• Thread.stop(), Thread.suspend(), Thread.resume() — supprimés. Ceux-ci étaient toujours dangereux ; si du code les utilise, il était déjà cassé.
• Accès réflexif illégal : le flag --illegal-access=permit n’existe plus. Les bibliothèques qui accédaient aux composants internes du JDK (sun.misc.Unsafe, etc.) doivent utiliser les API appropriées ou ajouter des flags --add-opens explicites.

Exécutez cette vérification sur votre base de code immédiatement :

# Trouver les usages de SecurityManager supprimé
grep -rn "SecurityManager" --include="*.java" src/

# Trouver les patterns d'accès réflexif illégal
grep -rn "sun\.misc\|sun\.reflect\|com\.sun\.proxy" --include="*.java" src/

# Trouver les constructeurs Date dépréciés
grep -rn "new Date(" --include="*.java" src/

OpenRewrite : automatiser 80 % du travail

OpenRewrite est un outil de refactoring automatisé de code qui applique des transformations au niveau de l’AST. Il comprend le code source Java comme un arbre syntaxique, pas comme du texte — il gère donc correctement les imports, les noms pleinement qualifiés et les références de types.

SAP a publié des recettes OpenRewrite spécifiques à Commerce Cloud. Voici comment les configurer.

Étape 1 : ajouter le plugin OpenRewrite

Dans votre build.gradle racine (ou le fichier de build de vos extensions personnalisées) :

plugins {
    id 'org.openrewrite.rewrite' version '7.3.0'
}

dependencies {
    rewrite platform('org.openrewrite.recipe:rewrite-recipe-bom:3.5.0')
    rewrite 'org.openrewrite.recipe:rewrite-migrate-java'
    rewrite 'org.openrewrite.recipe:rewrite-spring'
}

rewrite {
    activeRecipe(
        'org.openrewrite.java.migrate.UpgradeToJava21',
        'org.openrewrite.java.spring.framework.UpgradeSpringFramework_6_2',
        'org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta'
    )
}

Étape 2 : exécuter un dry run d’abord

Prévisualisez toujours les changements avant de les appliquer :

./gradlew rewriteDryRun

Cela génère un rapport de diff dans build/reports/rewrite/. Examinez-le. Vérifiez les faux positifs. Recherchez les modifications dans des fichiers qui ne vous appartiennent pas (classes de la plateforme qui ne devraient pas être modifiées).

Étape 3 : appliquer la migration

./gradlew rewriteRun

Cela modifie vos fichiers sources en place. Committez le résultat comme un unique commit « migration de namespace » afin de pouvoir le réviser et le reverter proprement.

Étape 4 : exécuter la recette Spring Security séparément

Les changements Spring Security sont plus complexes que des renommages de namespace. Exécutez la recette dédiée :

# Ajoutez à votre bloc rewrite
rewrite {
    activeRecipe(
        'org.openrewrite.java.spring.security6.UpgradeSpringSecurity_6_2'
    )
}

Examinez la sortie avec attention. La recette Spring Security gère la suppression de WebSecurityConfigurerAdapter et les renommages de méthodes, mais elle génère parfois du code qui compile sans correspondre à la sémantique de sécurité souhaitée. Vérifiez manuellement chaque changement lié à la sécurité.

Ce que couvre OpenRewrite

• Imports javax.* vers jakarta.* (tous les packages)
• Suppression de l’adapter Spring Security et migration vers le DSL lambda
• Renommage de antMatchers() en requestMatchers()
• Mise à jour des annotations Hibernate @Type
• Remplacements d’API Java 21 (substitution de méthodes dépréciées)
• Mises à jour des signatures de méthodes Spring MVC

Ce que OpenRewrite rate

OpenRewrite opère sur des patterns AST. Il ne comprend pas votre logique métier. Ces éléments nécessitent un travail manuel :

• Références de classes en chaînes de caractères : Class.forName("javax.servlet.Filter") ne sera pas capturé
• Fichiers de configuration XML : beans Spring XML référençant des classes javax.*
• Fichiers de propriétés : toute référence javax.* dans les fichiers .properties ou .yml
• Chargement dynamique de types par réflexion : patterns de chargement dynamique de classes
• Processeurs d’annotations personnalisés : si vous avez écrit des processeurs qui inspectent les annotations javax.*

Ce que OpenRewrite ne peut pas corriger

Les 20 % qui restent après l’outillage automatisé sont là où les développeurs expérimentés font la différence.

Configurations Spring personnalisées. Si votre projet Commerce Cloud utilise des configurations Spring basées sur XML (encore courant dans les anciennes extensions), OpenRewrite ne transforme pas de manière fiable les références <bean class="javax.servlet.…">. Vous devez faire un grep dans chaque fichier *-spring.xml et *-beans.xml manuellement.

# Trouver les références javax dans les configs Spring XML
grep -rn "javax\." --include="*-spring.xml" --include="*-beans.xml" src/

Patterns AOP. Si vos extensions utilisent Spring AOP avec des expressions de pointcut qui référencent des types javax.*, celles-ci sont typiquement stockées comme des chaînes dans les annotations @Pointcut ou @Around. OpenRewrite les analyse comme des chaînes, pas comme des références de types. Mettez à jour manuellement :

Avant :

@Around("execution(* javax.servlet.http.HttpServlet+.do*(..))")

Après :

@Around("execution(* jakarta.servlet.http.HttpServlet+.do*(..))")

Code basé sur la réflexion. Les extensions Commerce Cloud qui utilisent la réflexion pour inspecter les types d’entités, charger des beans Spring dynamiquement ou créer des objets proxy peuvent contenir des chaînes javax.* codées en dur. Celles-ci compilent correctement mais échouent à l’exécution.

Bibliothèques tierces. Si vos extensions dépendent de JAR tiers qui n’ont pas migré vers Jakarta EE, vous êtes bloqué. Options : mettre à jour la bibliothèque, trouver une alternative ou utiliser les JAR de compatibilité jakarta.servlet (déconseillé sur le long terme).

Intercepteurs SAP Commerce et système de types dynamique. Le système de types hybris utilise son propre framework d’intercepteurs. Si vos intercepteurs référencent des types javax.* via des paramètres génériques ou des signatures de méthodes, ils nécessitent une revue manuelle. C’est particulièrement vrai pour les implémentations de PrepareInterceptor, ValidateInterceptor et LoadInterceptor qui traitent des attributs annotés JPA.

Stratégie de test

La migration crée un défi de test unique : des milliers de modifications de fichiers, la plupart mécaniques, mais avec quelques changements sémantiques cachés dans le bruit. Votre stratégie de test doit détecter les problèmes sémantiques sans se noyer dans le volume.

Tests unitaires

Exécutez d’abord votre suite de tests unitaires existante. C’est votre boucle de feedback la plus rapide.

./gradlew test

Corrigez d’abord les erreurs de compilation — elles proviennent des changements de namespace manqués. Puis corrigez les échecs d’assertions — ils proviennent des changements de comportement dans Spring 6 ou Hibernate 6.

Attendez-vous à ce qu’environ 5 à 15 % des tests unitaires nécessitent des mises à jour, principalement en raison de :

• Setup de mocks modifié (les API de mocking Spring Security ont changé)
• Changements de type de résultat des requêtes Hibernate
• Changements de configuration du contexte de test Spring

Tests d’intégration

Les tests d’intégration Commerce Cloud qui utilisent @SpringBootTest ou le framework de test hybris feront émerger des problèmes que les tests unitaires manquent :

• Échecs de câblage de beans Spring (mauvais types après le changement de namespace)
• Mauvaise configuration de la chaîne de filtres de sécurité
• Échecs de mapping d’entités JPA avec Hibernate 6

Exécutez la suite d’intégration complète contre une installation Commerce Cloud locale fonctionnant sous Java 21 :

ant alltests -Dtestclasses.packages=com.yourcompany.*

Régression de performance

Les threads virtuels et les améliorations du ramasse-miettes de Java 21 devraient améliorer les performances, pas les dégrader. Mais vérifiez :

1. Temps de démarrage : comparez les temps de démarrage à froid entre les builds Java 17 et Java 21
2. Empreinte mémoire : surveillez l’utilisation du heap sous charge — le système de types d’Hibernate 6 utilise légèrement plus de mémoire de métadonnées
3. Débit : exécutez vos scénarios de test de charge standard et comparez les temps de réponse
4. Comportement du GC : le ZGC générationnel de Java 21 est maintenant prêt pour la production — envisagez de quitter G1GC si votre charge de travail est sensible à la latence

Frameworks de test spécifiques SAP

• Tests d’import ImpEx : vérifiez que tous les fichiers ImpEx s’importent toujours correctement — en particulier ceux qui référencent des noms de classes Java
• Validation du backoffice : connectez-vous au Backoffice et vérifiez que les types personnalisés, les éditeurs et les widgets s’affichent correctement
• Tests de fumée du storefront : parcourez le chemin d’achat critique — panier, checkout, paiement, confirmation de commande
• Tests d’API OCC : appelez vos endpoints OCC personnalisés et vérifiez que les contrats requête/réponse n’ont pas changé

Procédure de migration pas à pas

Voici la séquence que nous suivons. Dix étapes, dans l’ordre. N’en sautez aucune.

Étape 1 : inventoriez votre code personnalisé. Comptez vos extensions personnalisées, lignes de code Java, fichiers Spring XML et dépendances tierces. Cela vous indique le périmètre.

# Compter les fichiers Java et les lignes
find . -name "*.java" -path "*/src/*" | wc -l
find . -name "*.java" -path "*/src/*" -exec cat {} \; | wc -l

# Compter les configs Spring XML
find . -name "*-spring.xml" -o -name "*-beans.xml" | wc -l

# Lister les JAR tiers
find . -name "*.jar" -path "*/lib/*" | sort

Étape 2 : créez une branche de migration. Créez une branche dédiée. Cette migration touchera des centaines de fichiers — vous voulez une séparation nette par rapport au développement de fonctionnalités.

git checkout -b migration/java21-spring6

Étape 3 : mettez à jour vos outils de build. Assurez-vous que Gradle (ou Ant/Maven, selon votre configuration) supporte Java 21. Mettez à jour le JDK dans votre environnement de build et votre pipeline CI.

Étape 4 : exécutez la migration de namespace OpenRewrite. Appliquez les recettes JavaxMigrationToJakarta et UpgradeToJava21. Committez le résultat.

Étape 5 : exécutez la migration Spring 6 OpenRewrite. Appliquez les recettes Spring Framework et Spring Security. Révisez et committez séparément.

Étape 6 : corrigez ce que OpenRewrite a raté. Faites un grep pour trouver les références javax.* restantes dans les fichiers XML, properties et littéraux de chaîne. Corrigez manuellement. Committez.

# Trouver TOUTES les références javax restantes
grep -rn "javax\." --include="*.xml" --include="*.properties" \
  --include="*.yml" --include="*.java" src/

Étape 7 : corrigez les erreurs de compilation. Compilez le projet et traitez chaque erreur de compilation. Ce sont typiquement des changements d’API Spring Security, des changements du système de types Hibernate ou des API Java supprimées.

./gradlew compileJava 2>&1 | grep "error:" | head -50

Étape 8 : exécutez les tests unitaires. Corrigez les échecs. De manière méthodique. Corrigez les tests qui échouent à cause de changements d’API, pas en les supprimant.

Étape 9 : exécutez les tests d’intégration sur un environnement Java 21. Déployez sur un environnement de staging SAP Commerce Cloud fonctionnant sous Java 21. Exécutez la suite complète de tests d’intégration et de fumée.

Étape 10 : validation de la performance et déploiement en production. Exécutez les tests de charge, comparez les métriques avec votre baseline Java 17, et déployez en production avant le 30 juin.

Pièges courants

Tirés de vrais projets que nous avons vus ou sur lesquels nous avons travaillé — les problèmes qui coûtent des jours au lieu d’heures.

ClassNotFoundException à l’exécution. Tout compile, mais un bean Spring échoue au chargement au démarrage parce qu’une config XML référence encore javax.servlet.Filter comme chaîne de caractères. Cela ne provoque pas d’erreur de compilation. Cela provoque une ClassNotFoundException à l’exécution quand Spring essaie d’instancier le bean. Faites toujours un grep dans les fichiers XML.

Spring Security autorise silencieusement toutes les requêtes. Lors de la migration de WebSecurityConfigurerAdapter vers SecurityFilterChain, une erreur courante est d’oublier .build() à la fin de la chaîne, ou de définir le bean sans annoter la classe avec @Configuration. Le résultat : Spring charge sa configuration de sécurité par défaut, qui peut tout autoriser ou tout refuser selon votre classpath. Testez l’authentification et l’autorisation explicitement.

Échecs de validation du schéma Hibernate. Hibernate 6 est plus strict sur la validation du schéma au démarrage. Si les colonnes de votre base de données hybris ne correspondent pas exactement aux annotations JPA (par ex. une colonne VARCHAR(255) avec @Column(length = 100)), Hibernate 6 peut lever une SchemaManagementException là où Hibernate 5 ignorait silencieusement la divergence. Révisez votre système de types et votre schéma de base de données ensemble.

Enfer des JAR tiers. Un piège courant : votre projet dépend d’une bibliothèque qui embarque ses propres classes javax.*. Après migration, vous vous retrouvez avec javax.servlet et jakarta.servlet sur le classpath en même temps. Cela provoque une ClassCastException à l’exécution — un jakarta.servlet.http.HttpServletRequest n’est pas un javax.servlet.http.HttpServletRequest, même s’ils ont des méthodes identiques. Supprimez ou mettez à jour le JAR incriminé.

Références de classes ImpEx. Les fichiers ImpEx peuvent référencer des classes Java pour des translators personnalisés et des processeurs d’import. Si ces classes étaient dans le namespace javax.* (peu probable, mais possible avec des intercepteurs personnalisés), l’import ImpEx échouera silencieusement ou avec une erreur cryptique. Vérifiez vos fichiers ImpEx.

Décalage de version Java dans le pipeline de build. Votre machine locale tourne sous Java 21. Le pipeline CI utilise encore Java 17. Tout fonctionne en local, le déploiement échoue. Mettez à jour votre configuration CI — Jenkinsfile, manifest.yml ou .github/workflows/*.yml — pour spécifier Java 21 avant votre première tentative de déploiement.

La migration Java 21 et Spring 6 est de nature mécanique mais de grande envergure. L’outillage automatisé est véritablement efficace — OpenRewrite gère la fastidieuse migration de namespace de manière fiable. Ce qui reste est le travail d’ingénierie minutieux : réécritures Spring Security, compatibilité Hibernate 6, code basé sur la réflexion et tests approfondis.

Commencez maintenant. L’échéance ne bouge pas.

Besoin d’aide pour évaluer le périmètre de votre migration Commerce Cloud ? Contactez-nous — nous avons accompagné cette transition sur plusieurs projets Commerce Cloud et pouvons vous indiquer précisément où se trouvent les points de friction dans votre base de code. Vous pouvez aussi explorer nos solutions SAP Commerce Cloud pour avoir une vue complète de notre travail avec la plateforme.