Migrazione SAP Commerce Cloud a Java 21 + Spring 6: Guida per sviluppatori

Se eseguite codice Java personalizzato su SAP Commerce Cloud, avete una scadenza inderogabile: 30 giugno 2026. Dopo quella data, gli ambienti SAP Commerce Cloud richiedono Java 21. Nessuna proroga. Nessun periodo di grazia. I deployment compilati con Java 17 non passeranno la build pipeline.

E Java 21 non arriva da solo. La piattaforma è passata da Spring Framework 5 a Spring Framework 6, che porta con sé la migrazione del namespace Jakarta EE. Questo significa che javax.servlet, javax.persistence, javax.validation — gli import che scrivete da 15 anni — sono spariti. Sostituiti da jakarta.*.

Non si tratta di una modifica cosmetica. Tocca i vostri servlet, le entità JPA, le annotazioni di validazione, la configurazione di Spring Security e potenzialmente ogni estensione personalizzata che avete costruito. La buona notizia: esiste un tooling che gestisce circa l’80% del lavoro meccanico. L’altro 20% è dove entra in gioco il vero lavoro di ingegneria.

TL;DR: SAP Commerce Cloud richiede Java 21 entro il 30 giugno 2026. La piattaforma è già passata a Spring 6 e Jakarta EE 10, il che significa che il namespace javax.* è morto. OpenRewrite automatizza la maggior parte della migrazione del namespace, ma le riscritture di Spring Security, le configurazioni AOP personalizzate e il codice basato su reflection richiedono intervento manuale. Preventivate 2-4 settimane per la migrazione e 2-3 settimane per i test di regressione. Iniziate ora — i team che aspettano fino a maggio scoprono problemi che non si risolvono in quattro settimane.

Cosa cambia e perché

Tre cambiamenti avvengono contemporaneamente. Sono correlati, ma rompono parti diverse del vostro codice.

Da Java 17 a Java 21. SAP Commerce Cloud ha adottato Java 17 come requisito minimo con la release 2211. Ora la piattaforma passa a Java 21, che è una release Long-Term Support (LTS) da settembre 2023. Java 21 introduce virtual threads, pattern matching per switch, record patterns e sequenced collections. La maggior parte di queste sono funzionalità additive — non rompono il codice esistente. Cosa si rompe: le API rimosse che erano deprecated da Java 9 ma funzionavano ancora in 17, e l’incapsulamento più rigido degli internals del JDK a cui alcune librerie accedono via reflection.

Da Spring 5 a Spring 6. Spring Framework 6.0 richiede Java 17+ e utilizza le API Jakarta EE 9+ come base. Questo è il cambiamento principale. Spring 6 ha eliminato completamente il supporto per il namespace javax.*. Ogni modulo Spring — Web MVC, Security, Data JPA, AOP — dipende ora dai corrispondenti jakarta.*. Se il vostro codice personalizzato estende classi Spring o implementa interfacce Spring che fanno riferimento a tipi javax.*, non compilerà contro Spring 6.

Migrazione del namespace Jakarta EE 9/10. La comunità Java ha rinominato i pacchetti javax.* in jakarta.* dopo che Oracle ha trasferito Java EE alla Eclipse Foundation. Si tratta di una modifica meccanica (rinomina di pacchetti), ma è pervasiva. Ogni istruzione import, ogni nome di classe qualificato nelle configurazioni XML, ogni riferimento stringa a javax.persistence.Entity — tutto deve essere aggiornato.

Per un approfondimento su come l’architettura di Commerce Cloud gestisce questi cambiamenti a livello di piattaforma, consultate la nostra guida all’architettura SAP Commerce Cloud.

La timeline

SAP ha distribuito questo cambiamento in fasi. Ecco cosa è già successo e cosa ci aspetta:

La finestra tra «tooling disponibile» e «scadenza» è di circa sei mesi. Sembra confortevole. Non lo è. La maggior parte dei progetti Commerce Cloud porta con sé 50.000-200.000 righe di codice Java personalizzato distribuito su decine di estensioni. La sola migrazione del namespace genera migliaia di modifiche ai file. I test richiedono più tempo della migrazione stessa.

La nostra raccomandazione: Iniziate la migrazione adesso. Eseguite il tooling automatizzato, correggete quello che non riesce a gestire e cominciate i test di regressione. I team che iniziano nel Q2 2026 hanno tempo per due cicli completi di test. I team che iniziano a giugno hanno tempo per il panico.

Checklist dei breaking changes

Ecco cosa incontrerete, ordinato approssimativamente per frequenza e impatto.

Migrazione del namespace da javax.* a jakarta.*

Questo è il cambiamento più pervasivo. Ogni riferimento a questi pacchetti deve essere aggiornato:

Prima:

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

Dopo:

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

Semplice trova-e-sostituisci? Per lo più. Ma fate attenzione ai literal stringa e ai file XML dove javax.persistence compare come nome qualificato. OpenRewrite cattura la maggior parte dei casi. Un grep manuale cattura il resto.

Modifiche a Spring Security

Spring Security 6 ha introdotto diversi breaking changes che impattano i progetti Commerce Cloud. Il più grande: WebSecurityConfigurerAdapter non esiste più.

Prima (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();
    }
}

Dopo (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();
    }
}

Modifiche chiave da tenere sotto controllo:

• WebSecurityConfigurerAdapter rimosso — usate bean SecurityFilterChain
• authorizeRequests() sostituito da authorizeHttpRequests()
• antMatchers() sostituito da requestMatchers()
• csrf(), cors(), sessionManagement() usano ora esclusivamente la DSL lambda
• SecurityContext utilizza RequestAttributeSecurityContextRepository di default (non basato su sessione)

Se il vostro progetto Commerce Cloud ha configurazioni Spring Security personalizzate per l’autenticazione dello storefront, il login B2B o l’accesso al Backoffice — queste dovranno essere riscritte manualmente. La DSL lambda è più componibile, ma non potete limitarvi a rinominare i metodi.

Deprecazioni Spring MVC

Spring 6 ha rimosso diversi pattern che erano deprecati in 5.x:

• Modifiche al tipo di ritorno @RequestMapping: i metodi che restituiscono String come nomi di view funzionano ancora, ma la gestione di ModelAndView ha cambiamenti comportamentali sottili nella semantica dei redirect.
• CommonsMultipartResolver sostituito da StandardServletMultipartResolver. Se avete configurato un upload file personalizzato, aggiornate il bean del resolver.
• Trailing slash matching disabilitato per default. /api/products/ e /api/products sono ora route diverse. Se il vostro storefront o i client API si affidano alla tolleranza dello slash finale, configurate PathMatchConfigurer.setUseTrailingSlashMatch(true) — ma pianificate di correggere gli URL in futuro.

Modifiche Hibernate 6 (JPA)

SAP Commerce Cloud utilizza Hibernate come provider JPA. Il passaggio a Jakarta EE significa Hibernate 6.x, che porta le proprie modifiche:

• Generazione ID basata su sequenze come default. Hibernate 6 preferisce SEQUENCE a IDENTITY per @GeneratedValue. Se fate affidamento sul comportamento auto-increment, impostate esplicitamente strategy = GenerationType.IDENTITY.
• Revisione del sistema dei tipi. Le implementazioni personalizzate di UserType devono essere aggiornate. L’interfaccia UserType ha modificato la sua firma generica.
• Modifiche all’annotazione @Type. @Type(type = "yes_no") diventa @Convert(converter = YesNoConverter.class) o @JdbcTypeCode(Types.CHAR).
• Applicazione implicita di @Column(length). Hibernate 6 applica la validazione della lunghezza delle colonne in modo più rigido a livello di schema. Le colonne che funzionavano con default impliciti possono ora generare eccezioni di validazione.

Prima:

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

Dopo:

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

API Java rimosse

Java 21 ha rimosso diverse API che erano marcate deprecated-for-removal da Java 9-11. Controllate il vostro codice per:

• java.lang.SecurityManager — completamente rimosso. Se qualche estensione lo usa (raro in Commerce Cloud, ma controllate le librerie di terze parti), deve essere riscritta.
• Costruttori java.util.Date / Calendar — alcuni costruttori deprecated rimossi. Usate java.time.*.
• Thread.stop(), Thread.suspend(), Thread.resume() — rimossi. Erano sempre pericolosi; se del codice li usa, era già difettoso.
• Accesso riflettivo illegale: il flag --illegal-access=permit non esiste più. Le librerie che accedono agli internals del JDK (sun.misc.Unsafe, ecc.) devono usare le API appropriate o aggiungere flag --add-opens espliciti.

Eseguite questa verifica immediatamente sul vostro codice:

# Trovare utilizzi del SecurityManager rimosso
grep -rn "SecurityManager" --include="*.java" src/

# Trovare pattern di accesso riflettivo illegale
grep -rn "sun\.misc\|sun\.reflect\|com\.sun\.proxy" --include="*.java" src/

# Trovare costruttori Date deprecati
grep -rn "new Date(" --include="*.java" src/

OpenRewrite: automatizzare l’80% del lavoro

OpenRewrite è uno strumento automatizzato di refactoring del codice che applica trasformazioni a livello di AST. Comprende il codice sorgente Java come albero sintattico, non come testo — gestisce quindi import, nomi qualificati e riferimenti ai tipi correttamente.

SAP ha pubblicato ricette OpenRewrite specifiche per Commerce Cloud. Ecco come configurarle.

Passo 1: aggiungere il plugin OpenRewrite

Nel vostro build.gradle radice (o nel file di build per le estensioni personalizzate):

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'
    )
}

Passo 2: eseguire prima un dry run

Controllate sempre le modifiche prima di applicarle:

./gradlew rewriteDryRun

Questo genera un report delle differenze in build/reports/rewrite/. Esaminate. Cercate i falsi positivi. Fate attenzione a modifiche in file che non sono vostri (classi della piattaforma che non dovrebbero essere modificate).

Passo 3: applicare la migrazione

./gradlew rewriteRun

Questo modifica i vostri file sorgente direttamente. Fate il commit del risultato come singolo commit «namespace migration» in modo da poter revisionare e fare revert in modo pulito.

Passo 4: eseguire la ricetta Spring Security separatamente

Le modifiche a Spring Security sono più complesse delle rinominazioni di namespace. Eseguite la ricetta dedicata:

# Aggiungere al blocco rewrite
rewrite {
    activeRecipe(
        'org.openrewrite.java.spring.security6.UpgradeSpringSecurity_6_2'
    )
}

Esaminate l’output con attenzione. La ricetta Spring Security gestisce la rimozione del WebSecurityConfigurerAdapter e la rinomina dei metodi, ma a volte genera codice che compila ma non corrisponde alla semantica di sicurezza desiderata. Verificate manualmente ogni modifica relativa alla sicurezza.

Cosa copre OpenRewrite

• Import javax.* a jakarta.* (tutti i pacchetti)
• Rimozione dell’adapter Spring Security e migrazione alla DSL lambda
• Rinominazione antMatchers() a requestMatchers()
• Aggiornamenti delle annotazioni Hibernate @Type
• Sostituzioni API Java 21 (swap di metodi deprecati)
• Aggiornamenti delle firme dei metodi Spring MVC

Cosa manca a OpenRewrite

OpenRewrite opera su pattern AST. Non comprende la vostra logica di business. Questi richiedono lavoro manuale:

• Riferimenti a classi basati su stringa: Class.forName("javax.servlet.Filter") non viene rilevato
• File di configurazione XML: bean Spring XML che riferiscono classi javax.*
• File properties: qualsiasi riferimento javax.* in .properties o .yml
• Caricamento di tipi basato su reflection: pattern di class loading dinamico
• Annotation processor personalizzati: se avete scritto processori personalizzati che ispezionano annotazioni javax.*

Cosa OpenRewrite non riesce a correggere

Il 20% che rimane dopo il tooling automatizzato è dove gli sviluppatori esperti dimostrano il loro valore.

Configurazioni Spring personalizzate. Se il vostro progetto Commerce Cloud usa configurazioni Spring basate su XML (ancora comuni nelle estensioni più vecchie), OpenRewrite non trasforma in modo affidabile i riferimenti <bean class="javax.servlet.…">. Dovete cercare manualmente in ogni file *-spring.xml e *-beans.xml.

# Trovare riferimenti javax nelle configurazioni Spring XML
grep -rn "javax\." --include="*-spring.xml" --include="*-beans.xml" src/

Pattern AOP. Se le vostre estensioni usano Spring AOP con espressioni pointcut che riferiscono tipi javax.*, queste sono tipicamente memorizzate come stringhe dentro annotazioni @Pointcut o @Around. OpenRewrite le analizza come stringhe, non come riferimenti a tipi. Aggiornate manualmente:

Prima:

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

Dopo:

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

Codice basato su reflection. Le estensioni Commerce Cloud che usano reflection per ispezionare tipi di entità, caricare Spring bean dinamicamente o creare oggetti proxy possono contenere stringhe javax.* hardcoded. Questi compilano senza problemi ma falliscono a runtime.

Librerie di terze parti. Una trappola comune: il vostro progetto dipende da una libreria che include le proprie classi javax.*. Dopo la migrazione, vi ritrovate con sia javax.servlet che jakarta.servlet sul classpath. Questo causa ClassCastException a runtime — un jakarta.servlet.http.HttpServletRequest non è un javax.servlet.http.HttpServletRequest, anche se hanno metodi identici. Rimuovete o aggiornate il JAR problematico.

Interceptor SAP Commerce e sistema di tipi dinamico. Il sistema di tipi hybris utilizza il proprio framework di interceptor. Se i vostri interceptor riferiscono tipi javax.* attraverso parametri generici o firme di metodi, necessitano di revisione manuale. Questo vale in particolare per le implementazioni PrepareInterceptor, ValidateInterceptor e LoadInterceptor che processano attributi annotati JPA.

Strategia di test

La migrazione crea una sfida di test unica: migliaia di modifiche ai file, la maggior parte meccaniche, ma con alcune modifiche semantiche nascoste nel rumore. La vostra strategia di test deve individuare i problemi semantici senza annegare nel volume.

Unit test

Eseguite prima la vostra suite di unit test esistente. Questo è il ciclo di feedback più rapido.

./gradlew test

Correggete prima gli errori di compilazione — derivano da modifiche namespace mancate. Poi correggete i fallimenti delle assertion — derivano da cambiamenti comportamentali in Spring 6 o Hibernate 6.

Aspettatevi che circa il 5-15% degli unit test necessiti di aggiornamenti, principalmente per:

• Setup dei mock modificato (le API di mocking di Spring Security sono cambiate)
• Modifiche ai tipi di risultato delle query Hibernate
• Modifiche alla configurazione del contesto di test Spring

Test di integrazione

I test di integrazione Commerce Cloud che usano @SpringBootTest o il framework di test hybris faranno emergere problemi che gli unit test non rilevano:

• Errori nel wiring dei bean Spring (tipi errati dopo la modifica del namespace)
• Configurazione errata della filter chain di sicurezza
• Errori nel mapping delle entità JPA con Hibernate 6

Eseguite la suite completa di integrazione contro un’installazione Commerce Cloud locale con Java 21:

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

Regressione delle prestazioni

I virtual thread e i miglioramenti al garbage collector di Java 21 dovrebbero migliorare le prestazioni, non peggiorarle. Verificate comunque:

1. Tempo di avvio: confrontate i tempi di avvio a freddo tra build Java 17 e Java 21
2. Footprint di memoria: monitorate l’uso dell’heap sotto carico — il sistema dei tipi di Hibernate 6 usa leggermente più memoria per i metadati
3. Throughput: eseguite i vostri scenari standard di test di carico e confrontate i tempi di risposta
4. Comportamento GC: il generational ZGC di Java 21 è ora production-ready — valutate il passaggio da G1GC se il vostro workload è sensibile alla latenza

Framework di test specifici SAP

• Test di import ImpEx: verificate che tutti i file ImpEx importino correttamente — in particolare quelli che riferiscono nomi di classi Java
• Validazione Backoffice: accedete al Backoffice e verificate che tipi personalizzati, editor e widget vengano renderizzati correttamente
• Smoke test dello storefront: percorrete il flusso di acquisto critico — carrello, checkout, pagamento, conferma ordine
• Test API OCC: testate i vostri endpoint OCC personalizzati e verificate che i contratti request/response non siano cambiati

Procedura di migrazione passo per passo

Ecco la sequenza che seguiamo. Dieci passi, in ordine. Non saltatene nessuno.

Passo 1: inventariate il codice personalizzato. Contate le vostre estensioni personalizzate, le righe di codice Java, i file Spring XML e le dipendenze di terze parti. Questo vi indica l’ambito.

# Contare file e righe Java
find . -name "*.java" -path "*/src/*" | wc -l
find . -name "*.java" -path "*/src/*" -exec cat {} \; | wc -l

# Contare configurazioni Spring XML
find . -name "*-spring.xml" -o -name "*-beans.xml" | wc -l

# Elencare i JAR di terze parti
find . -name "*.jar" -path "*/lib/*" | sort

Passo 2: create un branch di migrazione. Create un branch dedicato. Questa migrazione toccherà centinaia di file — volete una separazione pulita dal lavoro sulle funzionalità.

git checkout -b migration/java21-spring6

Passo 3: aggiornate gli strumenti di build. Assicuratevi che Gradle (o Ant/Maven, a seconda del vostro setup) supporti Java 21. Aggiornate il JDK nel vostro ambiente di build e nella pipeline CI.

Passo 4: eseguite la migrazione namespace OpenRewrite. Applicate le ricette JavaxMigrationToJakarta e UpgradeToJava21. Fate il commit del risultato.

Passo 5: eseguite la migrazione Spring 6 OpenRewrite. Applicate le ricette Spring Framework e Spring Security. Revisionate e committate separatamente.

Passo 6: correggete quello che OpenRewrite ha mancato. Cercate con grep i riferimenti javax.* rimanenti in XML, properties e literal stringa. Correggete manualmente. Committate.

# Trovare TUTTI i riferimenti javax rimanenti
grep -rn "javax\." --include="*.xml" --include="*.properties" \
  --include="*.yml" --include="*.java" src/

Passo 7: correggete gli errori di compilazione. Compilate il progetto e lavorate su ogni errore. Tipicamente sono modifiche alle API Spring Security, modifiche al sistema dei tipi Hibernate o API Java rimosse.

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

Passo 8: eseguite gli unit test. Correggete i fallimenti. Metodicamente. Correggete i test che falliscono per modifiche alle API, non eliminandoli.

Passo 9: eseguite i test di integrazione su un ambiente Java 21. Deployate su un ambiente staging SAP Commerce Cloud con Java 21. Eseguite l’intera suite di test di integrazione e smoke test.

Passo 10: validazione delle prestazioni e deployment in produzione. Eseguite test di carico, confrontate le metriche con la vostra baseline Java 17 e deployate in produzione prima del 30 giugno.

Insidie comuni

Da progetti reali che abbiamo visto o su cui abbiamo lavorato — i problemi che costano ai team giorni invece di ore.

ClassNotFoundException a runtime. Tutto compila, ma un bean Spring non si carica all’avvio perché una configurazione XML fa ancora riferimento a javax.servlet.Filter come stringa. Questo non causa un errore di compilazione. Causa una ClassNotFoundException a runtime quando Spring prova a istanziare il bean. Cercate sempre nei file XML.

Spring Security permette silenziosamente tutte le richieste. Quando si migra da WebSecurityConfigurerAdapter a SecurityFilterChain, un errore comune è dimenticare .build() alla fine della catena, o definire il bean senza annotare la classe con @Configuration. Il risultato: Spring carica la sua configurazione di sicurezza predefinita, che potrebbe permettere tutto o negare tutto a seconda del classpath. Testate autenticazione e autorizzazione esplicitamente.

Errori di validazione dello schema Hibernate. Hibernate 6 è più rigoroso sulla validazione dello schema all’avvio. Se le colonne del vostro database hybris non corrispondono esattamente alle annotazioni JPA (es. una colonna VARCHAR(255) con @Column(length = 100)), Hibernate 6 potrebbe lanciare SchemaManagementException dove Hibernate 5 ignorava silenziosamente la discrepanza. Revisionate il vostro sistema di tipi e lo schema del database insieme.

Inferno dei JAR di terze parti. Una trappola comune: il vostro progetto dipende da una libreria che include le proprie classi javax.*. Dopo la migrazione, vi ritrovate con sia javax.servlet che jakarta.servlet sul classpath. Questo causa ClassCastException a runtime — un jakarta.servlet.http.HttpServletRequest non è un javax.servlet.http.HttpServletRequest, anche se hanno metodi identici. Rimuovete o aggiornate il JAR problematico.

Riferimenti a classi ImpEx. I file ImpEx possono riferire classi Java per traduttori e processori di importazione personalizzati. Se queste classi erano nel namespace javax.* (improbabile ma possibile con interceptor personalizzati), l’importazione ImpEx fallirà silenziosamente o con un errore criptico. Controllate i vostri file ImpEx.

Mismatch della versione Java nella build pipeline. La vostra macchina locale usa Java 21. La pipeline CI usa ancora Java 17. Tutto funziona localmente, il deployment fallisce. Aggiornate la configurazione CI — Jenkinsfile, manifest.yml o .github/workflows/*.yml — per specificare Java 21 prima del primo tentativo di deployment.

La migrazione a Java 21 e Spring 6 è meccanica nella natura ma ampia nell’ambito. Il tooling automatizzato è davvero buono — OpenRewrite gestisce la migrazione del namespace in modo affidabile. Quello che rimane è il lavoro ingegneristico accurato: riscritture di Spring Security, compatibilità con Hibernate 6, codice basato su reflection e test approfonditi.

Iniziate ora. La scadenza non si sposta.

Avete bisogno di aiuto per valutare l’ambito della migrazione del vostro progetto Commerce Cloud? Contattateci — abbiamo già affrontato questo percorso con diversi progetti Commerce Cloud e possiamo dirvi esattamente dove si trovano i punti critici nel vostro codice. Potete anche esplorare le nostre soluzioni SAP Commerce Cloud per avere il quadro completo di come lavoriamo con la piattaforma.