Migrationsleitfaden IsyFact 2

Die IsyFact ist eine vom Bundesverwaltungsamt entwickele Software Factory für den Bau von Informationssystemen in komplexen IT-Anwendungslandschaften. Sie bündelt bestehendes technisches Know-how um Anwendungssysteme effizienter entwickeln und betreiben zu können.

Für die IsyFact gibt es zwei Versionszweige: IsyFact 1 und IsyFact 2.

Seit dem Jahr 2020 steht das neue Major-Release IsyFact 2 zur Verfügung. Dieser beruht auf den IsyFact Bausteinen der IsyFact 1 mit zwei wesentlichen Neuerungen:

Einführung von Spring Boot,
Unterstützung des Frontend-Frameworks Angular, zusätzlich zu JSF.

Die auf dieser Seite aufgeführten Hinweise sollen IsyFact Anwendungsentwicklern bei der Umstellung einer auf IsyFact 1 basierenden Anwendung auf IsyFact 2 helfen.

1. Geschäftsanwendung

1.1. Spring Konfiguration

Die Konfiguration von Spring wird von XML auf Java-Config umgestellt.

Siehe Detailkonzept Komponente Anwendungskern - Kapitel: Vorgaben zur Spring-Konfiguration.
Für die betriebliche Konfiguration wird die Datei application.properties anlegt.

Siehe Detailkonzept Komponente Anwendungskern - Kapitel: Konfigurationsparameter über Property-Objekte konfigurieren.

1.2. Konfigurationsparameter

Die Bereitstellung von Konfigurationsparametern innerhalb der Geschäftsanwendung erfolgt über @ConfigurationProperties-Klassen. Soll die Bibliothek isy-konfiguration weiterhin verwendet werden, muss die Bean aus der Spring-Konfiguration entfernt werden. Die Liste mit den Property-Dateien wird nach application.properties übertragen.

1.3. Applikationsklasse

Für eine auf IsyFact 2.x basierende Anwendung wird eine Applikationsklasse im Root-Package der Anwendung erstellt.

Siehe Detailkonzept Komponente Anwendungskern - Kapitel: Vorgaben zur Spring-Konfiguration.

@SpringBootApplication
public class IsyFact2Application extends SpringBootServletInitializer {
    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
        return application.sources(IsyFact2Application.class);
    }
}

1.4. Deployment Descriptor web.xml

Bei einer Migration von einer IsyFact 1.x Version auf IsyFact 2.x sind Änderungen an der web.xml Datei (Deployment Descriptor) vorzunehmen.

1.4.1. Spring Kontext

Die Konfiguration des Spring-Kontextes erfolgt über Java-Config / Component Scan. Die Deklaration in der web.xml entfällt.

Abbildung 1. Spring Kontext Deklaration entfällt

1.4.2. Logging

Die Deklaration zum Logging in der web.xml entfällt.

Siehe Kapitel Bausteine/Logging.

Abbildung 2. Logging Deklaration entfällt

1.4.3. Spring Context Loader

Der Spring-Kontext wird über ServletInitializer hochgefahren. Die Listener-Deklaration in der web.xml entfällt.

Siehe Kapitel Geschäftsanwendung/Applikationsklasse.

Abbildung 3. ContextLoaderListener entfällt

1.4.4. Dispatcher Servlet

Das Dispatcher-Servlet wird automatisch von Spring Boot konfiguriert. Die Trennung von Web- und Anwendungskontext entfällt.

Abbildung 4. DispatcherServlet entfällt

1.4.5. Loadbalancer

Das LoadBalancer-Servlet entfällt.

Siehe Kapitel Bausteine/Überwachung.

Abbildung 5. LoadBalancer entfällt

1.4.6. HttpInvokerServiceExporter

Beans vom Typ HttpInvokerServiceExporter werden automatisch von Spring Boot konfiguriert.

Abbildung 6. HttpInvokerServiceExporter Servlets entfallen

Der Pfad für das Mapping wird vom Namen der Bean abgeleitet.

Siehe Kapitel Bausteine/Service.

Abbildung 7. Bean Deklaration von HttpInvokerServiceExporter

Abbildung 8. httpInvokerService entfällt

1.5. Unit-Tests

Verwendung der Annotation SpringBootTest bei den Unit-Tests

@RunWith(SpringRunner.class)
@SpringBootTest(classes = RaumplanungApplication.class)
@TestExecutionListeners({DependencyInjectionTestExecutionListener.class, TransactionDbUnitTestExecutionListener.class})
@DatabaseSetup("testdatensatz.xml")
public class EintragControllerTest {

}

2. Bausteine

2.1. Persistenz

Die Spring-Konfiguration für die Persistenz muss geändert werden (EntityManager, DataSource). Ebenso wird die betriebliche Konfiguration aus jpa.properties nach application.properties übertragen.

Siehe Nutzungsvorgaben JPA/Hibernate - Kapitel: Konfiguration von JPA über Spring Beans durchführen.
Sollen die alten DAOs aus isy-persistence weitergenutzt werden, dann sind diese als Beans in Java-Config zu übernehmen.

2.2. Logging

Die Konfiguration des Logging-Frameworks erfolgt über logback.xml und zusätzliche Properties in application.properties.

Die Datei logback.xml liegt unter src/main/resources/config. Die Änderung der Log-Level erfolgt über application.properties, diese werden nicht in logback.xml angegeben.

Siehe Nutzungsvorgaben Logging - Kapitel: Logback-Konfiguration.
Der LogbackConfigListener entfällt komplett, d.h. die Abhängigkeit in pom.xml und die Konfiguration in web.xml sind nicht notwendig.
Interceptoren für System- und Komponentengrenzen und der LogApplicationListener werden per Autokonfiguration erstellt und müssen aus der Spring-Konfiguration entfernt werden. Die System- und Komponentengrenzen werden nicht über manuell konfigurierte Pointcuts, sondern über die Annotation @Systemgrenze und @Komponentengrenze festgelegt.
Die Konfiguration der Interceptoren für das Logging an System- und Komponentengrenzen über Properties in application.properties erfolgt, falls abweichend von der Default-Konfiguration, nach dem Schema:

Siehe Nutzungsvorgaben Logging - Kapitel: Spring-Konfiguration.
Die Konfiguration des LogApplicationListener erfolgt über Properties in application.properties:

Siehe Nutzungsvorgaben Logging - Kapitel: LogApplicationListener.
Listing 1. application.properties
```
isy.logging.anwendung.name=Anwendung
isy.logging.anwendung.version=2.0.0
isy.logging.anwendung.typ=GA
```
Über einen Eintrag in applicaton.properties ist das Performance Logging zu aktivieren.

isy.logging.performancelogging.enabled=true

Siehe Nutzungsvorgaben Logging - Kapitel: Performance Logging.

2.3. Überwachung

isy-ueberwachung setzt Spring Boot Actuator und micrometer ein.
Die Überwachungsinformationen für Services werden über micrometer bereitgestellt. Die eigentliche Überwachung erfolgt über einen AOP-Advice. Dieser wird per Java-Config konfiguriert:

Siehe Nutzungsvorgaben Überwachung - Kapitel: Informationen von Services.
Die Implementierung von Ping- und Prüfmethoden wird über HealthIndicator realisiert.

Siehe Nutzungsvorgaben Überwachung - Kapitel: Prüfung der Verfügbarkeit.
Die Verbindung zur Datenbank wird von einem HealthIndicator aus isy-persistence überwacht. Eine eventuell vorhandene manuelle Prüfung kann entfernt werden.
Das Loadbalancer-Servlet wird automatisch konfiguriert und der Eintrag in web.xml kann entfernt werden.

Siehe Nutzungsvorgaben Überwachung - Kapitel: Integration des Loadbalancer-Servlets.

2.4. Polling

Die Konfiguration (Polling-Cluster und JMX-Verbindungen) müssen nach application.properties überführt werden.

Siehe Nutzungsvorgaben Polling - Kapitel: Konfiguration über Properties.
Die Beans für den Polling-Verwalter und die Interceptoren für @PollingAktion müssen entfernt werden.

Siehe Nutzungsvorgaben Polling - Kapitel: Spring-Konfiguration.

2.5. Batchrahmen

Die Spring-Konfiguration muss in Java-Config überführt werden. Eine gesonderte Konfiguration des Anwendungskontextes für den Batchrahmen ist nicht zwingend notwendig. Um Beans aus der Spring-Konfiguration der Anwendung für die Ausführung eines Batches auszuschließen, kann die Annotation (@ExcludeFromBatchContext) verwendet werden.

Siehe Detailkonzept Komponente Batch - Kapitel: Konfiguration der Spring-Kontexte.
In den Property-Dateien zur Konfiguration der Batches werden statt XML-Konfigurationsdateien, die vollqualifizierten Namen der Java-Konfigurationsklassen eingetragen.

Siehe Detailkonzept Komponente Batch - Kapitel: Konfigurationsdatei und Kommandozeilen-Parameter.

2.6. Standards

In allen Bausteinen (isy-util, isy-sonderzeichen, isy-exception, …) der IsyFact Bibliothek ìsyfact-standards haben sich die bisherigen Packages von
```
de.bund.bva.pliscommon.{baustein}
```
auf
```
de.bund.bva.isyfact.{baustein}
```
geändert
Die Bibliothek isy-standards benutzt nicht mehr isyfact-masterpom-lib, sondern nunmehr isyfact-standards als <parent> in der pom.xml.

2.7. Sicherheit

Bei der Überführung in Java-Config können bestimmte Beans entfernt werden. Automatisch konfiguriert werden die @Gesichert-Annotation, die AufrufKontextFactory und die Thread-Scopes thread und request für Spring.
In der Anwendung müssen die Beans für AufrufKontextVerwalter, Sicherheit und AccessManager konfiguriert werden.

Siehe Nutzungsvorgaben Sicherheit - Kapitel: Grundkonzepte und Konfiguration.
Die Konfiguration des Caches für Authentifizierungen erfolgt in application.properties.

Siehe Nutzungsvorgaben Sicherheit - Kapitel: Caching von Authentifizierungen.

2.8. Task Scheduler

2.8.1. Task Spring Konfiguration

Das Einbinden der XML-Spring-Konfiguration entfällt.

Die Properties zur Konfiguration der Tasks müssen nach application.properties übertragen werden. Die Verwendung von isy-sicherheit wird mit einer Property in application.properties gesteuert.

Um die Verwendung von isy-sicherheit für die Authentifizierung und Autorisierung zu konfigurieren, wird die Property isy.task.authentication.enabled in application.properties auf true oder false gesetzt.

Siehe Nutzungsvorgaben Task Scheduling - Kapitel: Konfigurieren von Tasks.

Siehe Nutzungsvorgaben Task Scheduling - Kapitel: Konfigurationsschlüssel.

2.9. Service

Die Konfiguration der HttpInvoker muss nach Java-Config überführt werden.

Beans vom Typ HttpInvokerServiceExporter werden automatisch von Spring Boot konfiguriert. Der Pfad für das Mapping wird vom Namen der Bean abgeleitet.

@Configuration
public class ServiceConfiguration {

    @Bean(name = "/AuskunftBean_v1_0")
    public HttpInvokerServiceExporter meldung() {
        // ...
    }

}

3. Dokumentation

Die Dokumentation des Major Release Zweigs IsyFact 2.x (Konzepte, Bausteine, …) basiert auf dem Stand der IsyFact 1.8.0. Sollten sich durch die Versionsanhebung Änderungen, z.B. bei der Konfiguration eines IsyFact Bausteins ergeben haben, so wurden diese im jeweiligen Dokument aktualisiert. Es wird daher empfohlen, bei der Migration jeweils die Dokumentation der Version 2.x zu berücksichtigen.

Abbildung 9. Einheitliche Dokumenten-Versionsnummer innerhalb eines Releases

Auf folgende Dokumentenänderungen (seit IsyFact IF-1.8) soll besonders hingewiesen werden:

3.1. Frontend Technologien

Das Detailkonzept Web-GUI enthielt bisher Erläuterungen zur Bibliothek isy-webgui, welche eine rein JSF-basierende Frontend-Demo-Anwendung erzeugt, in der JSF-Widgets beispielhaft implementiert und damit dargestellt werden.

Mit der Einführung von Angular als zweites, großes von der IsyFact unterstütztes Frontend-Framework, wurde das Dokument aufgesplittet in:

Detailkonzept Web-GUI (nur noch technologieübergreifende Themen),
Konzept,
Nutzungsvorgaben,

und den neuen Dokumenten:

Konzept Angular,
Nutzungsvorgaben Angular.

3.2. IT-Grundschutz

Sicherheit ist ein zentrales Thema einer jeden Geschäftsanwendung. Bei der Umsetzung von Geschäftsanwendungen in IT-Systeme wird ein Großteil der Anforderungen an die Sicherheit durch Maßnahmen der IT-Sicherheit abgedeckt.

Gerade bei einer Migration von einer IsyFact Version kleiner als v1.8 ist zu prüfen, ob alle aktuellen sicherheitsrelevanten Vorgaben erfüllt werden. Die IsyFact richtet sich beim Thema Sicherheit nach behördlichen Standards sowie De-Facto-Standards aus der Industrie:

3.3. IsyFact Referenzarchitektur

Auf eine Änderung im Dokument Referenzarchitektur soll besonders hingewiesen werden:

Service-Framework: Das Service-Framework dient als Kapsel für die Technologie, mit der die Services des Anwendungskerns zur Verfügung gestellt werden. Hierfür wird das Framework Spring HTTP-Invoker verwendet.

Ab IsyFact 2 ist die Verwendung von REST-Schnittstellen erlaubt. Spring HTTP-Invoker wird in folgenden Releases als Schnittstellenformat abgelöst. Die Verwendung von REST-Schnittstellen wird im Baustein REST (siehe Konzept REST und Nutzungsvorgaben REST) erläutert.

In der Regel wird ein extern angebotener Service noch durch zusätzliche Daten oder Logik ergänzt. Diese werden in der Komponente Service-Logik implementiert.

Siehe IsyFact Referenzarchitektur IT-Systeme - Kapitel: Servicezugriffe.