Migrationsleitfaden IsyFact 4.x

Die auf dieser Seite aufgeführten Hinweise sollen der Entwicklung bei der Umstellung einer auf IsyFact 3.x basierenden Anwendung auf IsyFact 4.x helfen.

1. Bausteine

Folgende Bibliotheken entfallen ab IsyFact 4.0:

  • isy-aufrufkontext: wird mit dem Wegfall der HttpInvoker nicht länger benötigt

  • isy-konfiguration: ersetzt durch Bordmittel von Spring, beschrieben in der Referenzarchitektur von Backends

  • isy-sicherheit: ersetzt durch Spring Security OAuth2 und isy-security

  • isy-serviceapi-core: HttpInvoker-Schnittstellen müssen durch entsprechende REST-Schnittstellen ersetzt werden (siehe auch Konzept REST/Nutzungsvorgaben REST).

1.1. Security

Method Security ist in der IsyFact 4 version von isy-security standardmäßig nicht mehr aktiviert und muss durch Setzen der @EnableMethodSecurity- Annotation an einer @Configuration-Klasse aktiviert werden.

Detaillierte Konfigurationsmöglichkeiten sind den Nutzungsvorgaben Security und der Spring Security Dokumentation zu entnehmen.

1.2. Überwachung

In IsyFact 3 muss die Absicherung der Endpoints aus den Nutzungsvorgaben abgeleitet und pro Anwendung implementiert werden.

In IsyFact 4 stellt der Baustein isy-ueberwachung über die AutoConfiguration eine Standardabsicherung für Endpoints und entsprechende Konfigurationsparameter bereit. Eine detaillierte Beschreibung zur Konfiguration und Anpassungsmöglichkeiten sind in den Nutzungsvorgaben Überwachung zu finden.

1.3. Utilities

In IsyFact 3 wurden die Klassen MessageSourceHolder sowie MessageSourceFehlertextProvider auf deprecated gesetzt.

In der IsyFact 4 muss jede Bibliothek/Anwendung eine eigene MessageSource-Bean für die Verwaltung von Nachrichten implementieren. Wenn Bedarf zur Anpassung der Nachrichten besteht, muss die jeweilige MessageSource-Bean mittels Spring-Bordmitteln überschrieben werden.

Für Fehlermeldungen wird empfohlen, das Interface de.bund.bva.isyfact.exception.FehlertextProvider aus isy-exception-core zu implementieren.

Weiterführende Informationen unter:

1.4. Spring Boot

IsyFact 4 erfordert eine Migration von Spring Boot 2.x auf Spring Boot 3.5.0. Dieser Abschnitt beschreibt die wichtigsten Änderungen und Migrationsschritte.

1.4.1. Voraussetzungen

  • Java 17 oder höher wird benötigt (Spring Boot 3.x erfordert mindestens Java 17)

  • Maven Version 3.6.3 oder höher wird benötigt.

1.4.2. Jakarta EE statt Java EE

Einer der größten Änderungen ist die Migration von javax. zu jakarta. Packages:

- import javax.persistence.Entity;
+ import jakarta.persistence.Entity;

- import javax.validation.constraints.NotNull;
+ import jakarta.validation.constraints.NotNull;

- import javax.servlet.http.HttpServletRequest;
+ import jakarta.servlet.http.HttpServletRequest;

Diese Änderung betrifft unter anderem:

  • JPA (javax.persistence → jakarta.persistence)

  • Bean Validation (javax.validation → jakarta.validation)

  • Servlet API (javax.servlet → jakarta.servlet)

  • JAX-RS (javax.ws.rs → jakarta.ws.rs)

  • JAXB (javax.xml.bind → jakarta.xml.bind)

Nutzen Sie IDE-Tools oder Maven-Plugins zur Unterstützung der Migration, wie z.B. das Eclipse Transformer Maven Plugin das auch z.B. unter IntelliJ verwendet werden kann.

1.4.3. Dependency Management

  • Stellen Sie sicher, dass alle Abhängigkeiten mit Jakarta EE kompatibel sind

1.4.4. Security-Konfiguration

Spring Security hat erhebliche Änderungen in Spring Boot 3.x erfahren:

  • Die WebSecurityConfigurerAdapter-Klasse wurde entfernt

  • Method Security ist standardmäßig deaktiviert

Aktivieren Sie Method Security explizit:

@Configuration
@EnableMethodSecurity // Ersetzt @EnableGlobalMethodSecurity
public class SecurityConfig {
    // Konfiguration
}

Anstatt WebSecurityConfigurerAdapter zu erweitern, definieren Sie nun SecurityFilterChain-Beans:

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(authorize -> authorize
            .requestMatchers("/public/**").permitAll()
            .anyRequest().authenticated()
        )
        .formLogin(withDefaults());
    return http.build();
}

1.4.5. Datenbankzugriff und JPA

  • Spring Data und Hibernate wurden aktualisiert und verwenden nun Jakarta Persistence

  • Überprüfen Sie Ihre Entity-Klassen, Repositories und JPA-Konfigurationen

  • Beachten Sie Änderungen bei den Namingstrategien in Hibernate 6

1.4.6. Konfiguration

  • Viele Konfigurationseigenschaften wurden umbenannt oder entfernt

  • Neue Konfigurationsoptionen sind verfügbar

Beispiele für geänderte Properties:

# Alt
spring.datasource.initialization-mode=always
# Neu
spring.sql.init.mode=always

# Alt
server.tomcat.min-spare-threads=10
# Neu
server.tomcat.threads.min-spare=10

1.4.7. Actuator und Überwachung

  • Die Endpoints und ihre Konfiguration wurden überarbeitet

  • Neue Metriken und Observability-Features sind verfügbar

  • Die Standard-Pfade für Actuator-Endpoints haben sich teilweise geändert

1.4.8. Testing

Spring Boot 3.x enthält aktualisierte Test-Frameworks:

  • JUnit 5 wird standardmäßig verwendet

  • Die Test-Slices wurden überarbeitet

  • MockMvc hat ein aktualisiertes API

1.4.9. Weitere wichtige Änderungen

  • Das Auto-Configuration-System wurde überarbeitet

  • Die Unterstützung für GraalVM Native Image wurde verbessert

  • Reactive Programming hat erweiterte Unterstützung erhalten

  • Die Dokumentation von REST-APIs verwendet nun standardmäßig OpenAPI 3

1.4.10. Schrittweise Migrationsempfehlung

  1. Aktualisieren Sie zuerst auf die letzte Spring Boot 2.7.x-Version

  2. Lösen Sie alle Deprecation-Warnungen und nutzen Sie die neuen APIs

  3. Aktualisieren Sie auf Java 17

  4. Migrieren Sie zu Jakarta EE (javax zu jakarta Packages)

  5. Aktualisieren Sie auf Spring Boot 3.5.0

  6. Beheben Sie alle auftretenden Fehler und Inkompatibilitäten

Die offizielle Spring Boot Migrationsdokumentation enthält weitere Details und spezifische Anweisungen: https://docs.spring.io/spring-boot/upgrading.html.