SAP Commerce Cloud Java 21 + Spring 6 Migration: Ein Leitfaden für Entwickler

Im September 2025 hat SAP das Framework-Update 2211-jdk21 für SAP Commerce Cloud veröffentlicht: Die Plattform läuft seither auf Java 21 und Spring Framework 6 (SAP Help Portal: Framework Update). Daraus folgten zwei Stichtage. Sicherheitsfixes für die auf Java 17 basierenden 2211-Updates gab es bis Ende Juni 2026. Und laut Ankündigung von SAP sind neue Builds für Java 17 nach dem 31. August 2026 gesperrt.

Beide Daten sind vorbei. Wenn Ihr Projekt umgestellt hat, hilft Ihnen dieser Leitfaden zu prüfen, was noch lauern könnte. Wenn nicht, eilt es: Ohne das Update können Sie keine Änderungen mehr bauen und deployen.

Das Update ist mehr als ein JDK-Wechsel. Spring 6 bringt den Jakarta-EE-Namespace mit, aus javax.servlet, javax.validation und javax.annotation, den Imports, die Entwickler seit fünfzehn Jahren schreiben, wird jakarta.*. Das betrifft Servlets, Filter, Validierungsannotationen, die Spring-Security-Konfiguration und potenziell jede eigene Extension. Werkzeuge erledigen den Grossteil der mechanischen Arbeit; der Rest ist echte Ingenieursarbeit.

Kurzfassung: Mit 2211-jdk21 läuft SAP Commerce Cloud auf Java 21 und Spring 6. Die Sicherheitsfixes für Java 17 endeten im Juni 2026, neue Java-17-Builds sind nach dem 31. August 2026 gesperrt. Die Migration heisst: javax.* auf jakarta.* umstellen, Spring-Security-Konfigurationen auf SecurityFilterChain umschreiben, XML-Bean-Definitionen, Reflection und Drittbibliotheken prüfen, dann gründlich testen. OpenRewrite automatisiert den Grossteil der Namespace-Arbeit. Rechnen Sie mit zwei bis vier Wochen Migration und zwei bis drei Wochen Regressionstests.

Was sich ändert und warum

Drei Umstellungen passieren gleichzeitig. Sie hängen zusammen, brechen aber verschiedene Dinge.

Java 17 auf Java 21. Release 2211, die reine Cloud-Generation von Commerce Cloud, hat das Minimum auf Java 17 gehoben; 2211-jdk21 wechselt auf Java 21, seit September 2023 ein Release mit Langzeitsupport (OpenJDK). Java 21 bringt Virtual Threads, Pattern Matching für switch, Record Patterns und Sequenced Collections. Das meiste davon ist additiv und bricht bestehenden Code nicht. Brechen kann Code, der sich per Reflection auf JDK-Interna stützt oder auf APIs, deren Verhalten sich geändert hat.

Spring 5 auf Spring 6. Spring Framework 6 setzt Java 17 oder neuer voraus und basiert auf den Jakarta-EE-9+-APIs (Upgrade-Hinweise zu Spring Framework 6). Das ist der grosse Brocken: Spring 6 unterstützt den javax.*-Namespace nicht mehr. Erweitert Ihr Code Spring-Klassen oder implementiert er Interfaces, die javax.*-Typen referenzieren, kompiliert er nicht mehr.

Der Jakarta-Namespace. Nachdem Oracle Java EE an die Eclipse Foundation übergeben hatte, wurden die Pakete von javax.* in jakarta.* umbenannt. Eine mechanische Änderung, aber eine allgegenwärtige: jeder Import, jeder vollqualifizierte Klassenname in XML, jede String-Referenz.

Wie sich diese Plattformänderungen in die Architektur von Commerce Cloud einfügen, zeigt unser Überblick über SAP Commerce Cloud. Die weiteren Neuerungen, die SAP in diesem Jahr ausgeliefert hat, fasst der Beitrag zu den praktischen Updates vom September 2026 zusammen.

Die Zeitleiste

Datum	Ereignis
September 2023	Java 21 erscheint als LTS-Version
September 2025	SAP veröffentlicht das Framework-Update 2211-jdk21 (Java 21, Spring 6)
Ende Juni 2026	Sicherheitsfixes für die auf Java 17 basierenden 2211-Updates enden
31. August 2026	Neue Builds für Java 17 werden gesperrt

Die meisten Commerce-Cloud-Projekte tragen Zehntausende Zeilen eigenen Java-Code in Dutzenden Extensions. Allein die Namespace-Umstellung erzeugt Tausende geänderte Dateien, und das Testen dauert länger als die Migration selbst.

Wo Sie im September 2026 stehen: Laufen Sie noch auf einer 2211-Version mit Java 17, arbeiten Sie ohne Sicherheitsfixes und können keine Änderungen mehr ausliefern. Setzen Sie die Migration an die erste Stelle Ihrer Roadmap, frieren Sie die Feature-Arbeit ein und folgen Sie dem Vorgehen weiter unten. Prüfen Sie die aktuell geltenden Regeln in der SAP-Dokumentation und beim SAP-Support, bevor Sie planen.

Checkliste der Breaking Changes

Grob nach Häufigkeit und Auswirkung geordnet.

Namespace-Migration von javax.* zu jakarta.*

Die allgegenwärtigste Änderung. Jede Referenz auf diese Pakete muss angepasst werden:

Alt (javax.*)	Neu (jakarta.*)	Betroffener Code
javax.servlet.*	jakarta.servlet.*	Filter, eigene Controller, Request/Response-Wrapper
javax.validation.*	jakarta.validation.*	Bean Validation, @NotNull, @Size, eigene Validatoren
javax.annotation.*	jakarta.annotation.*	@PostConstruct, @PreDestroy, @Resource
javax.inject.*	jakarta.inject.*	@Inject, @Named
javax.persistence.*	jakarta.persistence.*	Nur wo eigener Code JPA direkt nutzt
javax.ws.rs.*	jakarta.ws.rs.*	JAX-RS-Endpunkte (falls vorhanden)

Vorher:

import javax.servlet.http.HttpServletRequest;
import javax.annotation.PostConstruct;
import javax.validation.constraints.NotNull;

public class CustomRequestValidator {
    @NotNull
    private String customField;

    @PostConstruct
    public void init() { /* ... */ }
}

Nachher:

import jakarta.servlet.http.HttpServletRequest;
import jakarta.annotation.PostConstruct;
import jakarta.validation.constraints.NotNull;

public class CustomRequestValidator {
    @NotNull
    private String customField;

    @PostConstruct
    public void init() { /* ... */ }
}

Grösstenteils Suchen und Ersetzen, aber achten Sie auf String-Literale und XML-Dateien, in denen javax. als vollqualifizierter Name steht. OpenRewrite findet die meisten davon, ein manuelles grep den Rest.

Änderungen in Spring Security

Spring Security 6 bringt mehrere Breaking Changes, die Commerce-Cloud-Projekte betreffen. Der grösste: WebSecurityConfigurerAdapter ist weg.

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

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

Die wichtigsten Änderungen:

• WebSecurityConfigurerAdapter entfällt; stattdessen SecurityFilterChain-Beans
• authorizeRequests() wird zu authorizeHttpRequests()
• antMatchers() wird zu requestMatchers()
• csrf(), cors() und sessionManagement() werden über die Lambda-DSL konfiguriert
• Der SecurityContext wird nicht mehr automatisch in der Session gespeichert; die Persistenz ist explizit

Eigene Spring-Security-Konfigurationen für Storefront-Anmeldung, B2B-Login oder Backoffice-Zugriff müssen Sie von Hand umschreiben. Dasselbe gilt für Extensions, die auf dem alten Projekt Spring Security OAuth aufbauen, das 2022 sein Lebensende erreicht hat: Prüfen Sie in der SAP-Dokumentation zum Framework-Update, wie die OCC-Authentifizierung jetzt gelöst ist, bevor Sie etwas portieren.

Änderungen in Spring MVC

Spring 6 hat mehrere Muster entfernt, die in 5.x als veraltet galten:

• CommonsMultipartResolver wird durch StandardServletMultipartResolver ersetzt. Haben Sie einen eigenen Datei-Upload konfiguriert, passen Sie das Resolver-Bean an.
• Trailing-Slash-Matching ist standardmässig deaktiviert. /api/products/ und /api/products sind jetzt verschiedene Routen. Verlassen sich Storefront oder API-Clients auf die alte Toleranz, ergänzen Sie explizite Mappings oder einen Redirect und korrigieren Sie die URLs.
• Path Matching nutzt standardmässig den PathPatternParser, der bei einigen Mustern strenger ist als der AntPathMatcher. Testen Sie eigene Controller-Mappings.

Wo eigener Code JPA oder Hibernate nutzt

SAP Commerce speichert Daten über sein eigenes Typsystem und den Service Layer, nicht über JPA. Dieser Abschnitt betrifft nur Extensions, die einen eigenen JPA- oder Hibernate-Stack mitbringen, etwa für eine separate Datenbank. Für sie bedeutet der Jakarta-Wechsel Hibernate 6 mit eigenen Änderungen:

• Sequenzbasierte ID-Generierung als Standard. Verlassen Sie sich auf Auto-Increment, setzen Sie strategy = GenerationType.IDENTITY explizit.
• Überarbeitetes Typsystem. Eigene UserType-Implementierungen müssen angepasst werden; das Interface hat seine generische Signatur geändert.
• Geänderte @Type-Annotation. @Type(type = "yes_no") wird zu einem Converter:

Vorher:

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

Nachher:

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

JDK-Änderungen zwischen 17 und 21

Prüfen Sie Code und Bibliotheken auf:

• java.lang.SecurityManager: seit Java 17 zur Entfernung vorgesehen (JEP 411) und standardmässig nicht nutzbar. Code, der einen installiert, scheitert zur Laufzeit.
• Thread.stop(), Thread.suspend(), Thread.resume(): werfen jetzt eine UnsupportedOperationException. Sie waren immer gefährlich; Code, der sie aufruft, war schon vorher kaputt.
• Starke Kapselung der JDK-Interna: Reflection-Zugriffe auf interne Pakete (sun.misc, sun.reflect und andere) scheitern, solange keine expliziten --add-opens-Flags gesetzt sind. Aktualisieren Sie lieber die Bibliothek, als Flags zu ergänzen.
• Finalization: zur Entfernung vorgesehen. Ersetzen Sie finalize() durch Cleaner oder try-with-resources.

Führen Sie diese Prüfungen früh aus:

# Nutzung von SecurityManager finden
grep -rn "SecurityManager" --include="*.java" .

# Reflection-Zugriffe auf JDK-Interna finden
grep -rn "sun\.misc\|sun\.reflect\|com\.sun\.proxy" --include="*.java" .

# Entfernte Thread-Steuerungsmethoden finden
grep -rn "\.stop()\|\.suspend()\|\.resume()" --include="*.java" .

OpenRewrite: den Grossteil der Arbeit automatisieren

OpenRewrite ist ein Werkzeug für automatisiertes Refactoring, das auf dem Syntaxbaum arbeitet statt auf Text. Deshalb behandelt es Imports, vollqualifizierte Namen und Typreferenzen korrekt. Für diese Art von Migration ist es zum Standardwerkzeug geworden. Die Open-Source-Rezepte unten decken die generischen Teile für Java, Jakarta und Spring ab; ob es Commerce-spezifische Werkzeuge gibt, klären Sie in der SAP-Dokumentation zum Framework-Update.

Schritt 1: OpenRewrite-Plugin hinzufügen

SAP Commerce selbst baut mit Ant. Am einfachsten lassen Sie OpenRewrite über einen kleinen Gradle- (oder Maven-) Wrapper laufen, der auf die Quellordner Ihrer eigenen Extensions zeigt:

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

Die Rezepte sind dokumentiert unter UpgradeToJava21, JavaxMigrationToJakarta und UpgradeSpringFramework_6_2. Verwenden Sie aktuelle Versionen von Plugin und BOM.

Schritt 2: Zuerst einen Probelauf ausführen

./gradlew rewriteDryRun

Das schreibt einen Diff-Bericht nach build/reports/rewrite/. Prüfen Sie ihn, suchen Sie nach Fehlalarmen und nach Änderungen an Dateien, die Ihnen nicht gehören.

Schritt 3: Migration anwenden

./gradlew rewriteRun

Committen Sie das Ergebnis als einzelnen Commit «Namespace-Migration», damit es sich sauber prüfen und zurücknehmen lässt.

Schritt 4: Spring-Security-Rezept separat ausführen

rewrite {
    activeRecipe(
        'org.openrewrite.java.spring.security6.UpgradeSpringSecurity_6_2'
    )
}

Das Spring-Security-Rezept übernimmt den Wegfall des Adapters und die Umbenennungen, erzeugt aber manchmal Code, der kompiliert und trotzdem nicht der beabsichtigten Sicherheitslogik entspricht. Prüfen Sie jede sicherheitsrelevante Änderung von Hand.

Was OpenRewrite abdeckt

• Imports von javax.* auf jakarta.*
• Wegfall des Spring-Security-Adapters und Umstellung auf die Lambda-DSL
• Umbenennung von antMatchers() in requestMatchers()
• Anpassung der Hibernate-Annotation @Type (wo JPA genutzt wird)
• Ersatz von APIs für Java 21
• Anpassung von Spring-MVC-Signaturen

Was OpenRewrite übersieht

• String-basierte Klassenreferenzen: Class.forName("javax.servlet.Filter")
• XML-Konfiguration: Spring-Bean-Definitionen in *-spring.xml und *-beans.xml, die javax.*-Klassen referenzieren
• Properties-Dateien: javax.*-Referenzen in .properties-Dateien
• Typladen per Reflection: dynamisches Laden von Klassen
• Eigene Annotation-Prozessoren, die javax.*-Annotationen auswerten

Was OpenRewrite nicht reparieren kann

Hier verdienen erfahrene Entwickler ihr Geld.

Spring-XML-Konfigurationen. Commerce-Extensions definieren viele Beans in XML. OpenRewrite wandelt <bean class="javax.servlet.…">-Referenzen nicht zuverlässig um, also durchsuchen Sie jede Spring-XML-Datei:

# javax-Referenzen in Spring-XML-Configs finden
grep -rn "javax\." --include="*-spring.xml" --include="*-beans.xml" .

AOP-Muster. Pointcut-Ausdrücke in @Pointcut oder @Around sind Strings, keine Typreferenzen:

Vorher:

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

Nachher:

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

Code mit Reflection. Extensions, die Typen inspizieren, Beans dynamisch laden oder Proxys erzeugen, können fest codierte javax.*-Strings enthalten. Sie kompilieren und scheitern zur Laufzeit.

Drittbibliotheken. Hängt eine Extension an einem JAR, das noch nicht auf Jakarta EE umgestellt ist, aktualisieren oder ersetzen Sie es. Bridge-JARs sind bestenfalls eine Übergangslösung.

Interceptoren und Typsystem. Prüfen Sie Implementierungen von PrepareInterceptor, ValidateInterceptor und LoadInterceptor sowie jeden Code, der Validierungsannotationen oder Servlet-Typen in seinen Signaturen verwendet.

Teststrategie

Die Migration erzeugt Tausende mechanische Änderungen, zwischen denen sich einige inhaltliche verstecken. Die Teststrategie muss diese finden, ohne in der Menge unterzugehen.

Unit-Tests

Führen Sie zuerst die bestehenden Unit-Tests aus; sie sind die schnellste Rückmeldung und finden in dieser Phase mehr echte Regressionen als sorgfältige Code-Reviews. Beheben Sie zuerst Kompilierfehler (übersehene Namespace-Änderungen), dann Assertion-Fehler (Verhaltensänderungen in Spring 6).

Tests müssen typischerweise angepasst werden wegen:

• geänderter Mock-Einrichtung (die Test-APIs von Spring Security haben sich geändert)
• Änderungen an der Konfiguration des Spring-Testkontexts
• strengerem Path Matching in MVC-Tests

Integrationstests

Führen Sie die vollständige Integrationssuite auf einer lokalen Installation mit Java 21 aus:

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

Sie zeigen, was Unit-Tests übersehen: Fehler beim Verdrahten der Beans nach dem Namespace-Wechsel, falsch konfigurierte Security-Filterketten und ClassNotFoundExceptions aus XML zur Laufzeit.

Performance-Regression

Java 21 sollte die Performance verbessern, aber prüfen Sie:

1. Startzeit: Kaltstarts zwischen Java-17- und Java-21-Build vergleichen
2. Speicherbedarf: Heap-Nutzung unter Last beobachten
3. Durchsatz: Standard-Lasttests fahren und Antwortzeiten vergleichen
4. Garbage Collection: Generational ZGC steht in Java 21 zur Verfügung; bewerten Sie ihn für latenzkritische Lasten, bevor Sie umstellen

SAP-spezifische Prüfungen

• ImpEx-Importe: prüfen, dass alle ImpEx-Dateien noch importieren, besonders solche mit Java-Klassenreferenzen
• Backoffice: eigene Typen, Editoren und Widgets auf korrekte Darstellung prüfen
• Storefront-Smoke-Tests: Warenkorb, Checkout, Zahlung, Bestellbestätigung
• OCC-API-Tests: eigene OCC-Endpunkte aufrufen und Request- und Response-Verträge prüfen, einschliesslich Authentifizierung

Migration Schritt für Schritt

Zehn Schritte, in dieser Reihenfolge.

Schritt 1: Eigenen Code inventarisieren. Eigene Extensions, Java-Zeilen, Spring-XML-Dateien und Drittabhängigkeiten zählen.

# Java-Dateien und Zeilen zählen
find . -name "*.java" -path "*/src/*" | wc -l
find . -name "*.java" -path "*/src/*" -exec cat {} \; | wc -l

# Spring-XML-Configs zählen
find . -name "*-spring.xml" -o -name "*-beans.xml" | wc -l

# Drittanbieter-JARs auflisten
find . -name "*.jar" -path "*/lib/*" | sort

Schritt 2: Migrationsbranch anlegen. Die Migration berührt Hunderte Dateien; halten Sie sie von der Feature-Arbeit getrennt.

git checkout -b migration/java21-spring6

Schritt 3: Build aktualisieren. Lokales JDK und CI auf Java 21 umstellen und commerceSuiteVersion in der manifest.json auf eine aktuelle 2211-jdk21-Version setzen.

Schritt 4: Namespace-Migration mit OpenRewrite. JavaxMigrationToJakarta und UpgradeToJava21 anwenden und committen.

Schritt 5: Spring-6-Rezepte ausführen. Die Rezepte für Spring Framework und Spring Security anwenden, separat prüfen und committen.

Schritt 6: Nachbessern, was OpenRewrite übersehen hat. Nach verbleibenden javax.-Referenzen in XML, Properties und String-Literalen suchen.

# ALLE verbleibenden javax-Referenzen finden
grep -rn "javax\." --include="*.xml" --include="*.properties" \
  --include="*.java" .

Schritt 7: Kompilierfehler beheben. Bauen und jeden Fehler abarbeiten; typischerweise API-Änderungen in Spring Security, entferntes JDK-Verhalten oder veraltete Bibliotheken.

Schritt 8: Unit-Tests ausführen und Fehler beheben. Tests reparieren, die wegen API-Änderungen scheitern; nicht löschen.

Schritt 9: Integrationstests auf einer Java-21-Umgebung. Auf eine Commerce-Cloud-Staging-Umgebung mit 2211-jdk21 deployen und die vollständige Integrations- und Smoke-Test-Suite ausführen.

Schritt 10: Performance validieren und in Produktion gehen. Lasttests fahren, mit der Java-17-Baseline vergleichen und deployen.

Häufige Stolperfallen

ClassNotFoundException zur Laufzeit. Alles kompiliert, aber ein Spring-Bean scheitert beim Start, weil eine XML-Konfiguration javax.servlet.Filter noch als String referenziert. Durchsuchen Sie immer die XML-Dateien.

Spring Security lässt alles durch (oder nichts). Beim Wechsel von WebSecurityConfigurerAdapter zu SecurityFilterChain führt ein fehlendes .build() oder ein fehlendes @Configuration dazu, dass Spring auf eine Standardkonfiguration zurückfällt. Testen Sie Authentifizierung und Autorisierung explizit.

Konflikte mit Drittanbieter-JARs. Nach unserer Erfahrung kostet diese Falle die meisten Tage. Eine Bibliothek bringt ihre eigenen javax.*-Klassen mit, und nach der Migration liegen javax.servlet und jakarta.servlet gleichzeitig im Classpath. Die Folge ist eine ClassCastException zur Laufzeit: Ein jakarta.servlet.http.HttpServletRequest ist kein javax.servlet.http.HttpServletRequest, auch wenn die Methoden identisch sind. Entfernen oder aktualisieren Sie das betroffene JAR.

Klassenreferenzen in ImpEx. ImpEx-Dateien können Java-Klassen für eigene Translatoren und Import-Prozessoren referenzieren. Hängen diese Klassen an javax.*-Typen, scheitert der Import mit einer kryptischen Meldung. Prüfen Sie Ihre ImpEx-Dateien.

Unterschiedliche Versionen in der Build-Pipeline. Lokal läuft Java 21, aber die CI-Pipeline oder die manifest.json zeigt noch auf eine Java-17-Version. Lokal funktioniert alles, das Deployment scheitert. Passen Sie beides vor dem ersten Deployment an.

---

Die Migration auf Java 21 und Spring 6 ist mechanisch in der Art und breit im Umfang. OpenRewrite erledigt die mühsame Namespace-Arbeit zuverlässig. Was bleibt, ist sorgfältige Ingenieursarbeit: Spring Security umschreiben, XML-Konfigurationen, Reflection, Bibliotheken und gründliche Tests. Planen Sie auch grössere Plattformänderungen, deckt unsere Migrations-Checkliste für SAP Commerce den Rest des Wegs ab.

Brauchen Sie Hilfe, den Umfang in Ihrer Codebasis abzuschätzen? Nehmen Sie Kontakt auf. Wir kennen dieses Update aus unserer eigenen Commerce-Cloud-Arbeit. Wie wir mit der Plattform insgesamt arbeiten, zeigt unsere Seite zu SAP Commerce Cloud, und wenn Sie Implementierungspartner vergleichen, hilft unsere Übersicht über die besten SAP-Commerce-Cloud-Partner in der Schweiz.