@dsivd/prestations-ng 18.8.0-beta.13 → 19.0.0-beta.2

package/UPGRADING_V19.md

@@ -0,0 +1,174 @@
+# PRESTAKIT : Upgrading from v18 to v19
+
+To migrate your project from `prestakit` v18 to v19, you need to migrate prestations-ng and prestations-be, as usual.
+But to migrate to prestations-be v19, you need to migrate your project to Spring Boot 4 / Java 25.
+
+Let's start by migrating to Spring Boot 4 / prestations-be v19.
+
+## PRESTATIONS-BE (via parent - Spring boot 4 / java 25)
+
+From here on, we are in the root folder of your project, for example ~/git/cybsdk/skeleton.
+
+### Spring Boot 4
+
+You can switch to Java 25 `jdk25` + change in IntelliJ: right-click on your project > Open Module Settings > Project > set "SDK" to `jdk25` from devtools and "Language
+level" to `25` in "Modules"
+
+Use the latest application-parent v15+ in your `pom.xml`.
+
+You can use this OpenRewrite recipe to simplify the migration (run with java 25).
+
+```bash
+source ~/devtools/fordev.sh 25 20
+mvn -U org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:RELEASE -Drewrite.activeRecipes=org.openrewrite.java.spring.boot4.UpgradeSpringBoot_4_0 -Pnof,noft
+```
+
+#### Fixes
+
+Fix application.properties :
+
+```diff
+# Remove the following properties if it was added by the recipe
+spring.liquibase.password=${spring.datasource.password}
+spring.liquibase.username=${spring.datasource.username}
+Replace the spring.jackson.serialization.WRITE_DATES_AS_TIMESTAMPS property by spring.jackson.datatype.datetime.write-dates-as-timestamps if it was not done by the recipe
+```
+
+If the following plugin with Lombok path was added by the recipe, remove this plugin:
+
+```xml
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-compiler-plugin</artifactId>
+    <configuration>
+        <annotationProcessorPaths>
+            <path>
+                <groupId>org.projectlombok</groupId>
+                <artifactId>lombok</artifactId>
+                <version>1.18.40</version>
+            </path>
+        </annotationProcessorPaths>
+    </configuration>
+</plugin>
+```
+
+If the code uses `AutoConfigureMockMvc`, add:
+
+```xml
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-webmvc-test</artifactId>
+    <scope>test</scope>
+</dependency>
+```
+
+And replace the old `AutoConfigureMockMvc` import which is not recognized anymore by the new one.
+
+If we use in pom.xml Spring/Hibernate dependencies (like hibernate-jpamodelgen), check the Spring Boot 4 migration
+guide to see if it has been replaced by another library: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
+
+### Jackson migration
+
+With Spring Boot 4, Jackson 3 is now used instead of Jackson 2, so we need to replace the previous Jackson 2 classes.
+Replace `com.fasterxml.jackson.databind.ObjectMapper` with `tools.jackson.databind.json.JsonMapper`.
+
+### BO : Package renaming
+
+- `ch.vd.cyberadminbe.jms` has been moved to `ch.vd.cyber.backofficebe.jms`
+- `ch.vd.cyberadminbe.security` has been moved to `ch.vd.cyber.backofficebe.security`
+- `ch.vd.cyberadminbe.editique` has been moved to `ch.vd.cyber.backofficebe.editique`
+- `cyberadminbe.config.CyberAdminBeEsbHttpConfig` has renamed to `backofficebe.config.BoCommonEsbHttpConfig`
+
+### BO : Brave Tracer
+
+If you are using Brave Tracer (search `brace.Tracer` in the code, usually in backoffices), you need to replace it with
+OpenTelemetry by adding the following dependencies (already included by `ch.vd.cyber:starter-bo-jdbc-jms` and `ch.vd.cyber:starter-prestation`):
+
+```xml
+<!-- Tracing -->
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-micrometer-tracing-opentelemetry</artifactId>
+</dependency>
+<dependency>
+    <groupId>io.micrometer</groupId>
+    <artifactId>micrometer-tracing-bridge-otel</artifactId>
+</dependency>
+```
+
+And replace `brave.Tracer` imports by `io.micrometer.tracing.Tracer`;
+
+#### BO : EsbMessageListenerWithSleuthIntegration
+
+This base class has been moved from `ch.vd.cyber.sdk:cyberadmin-be` to `ch.vd.cyber.sdk:backoffice-be`
+and renamed `EsbMessageListenerWithTracingPropagation`.
+the constructor has also been updated :
+
+```java
+import ch.vd.cyberadminbe.jms.EsbMessageListenerWithSleuthIntegration;
+import brave.Tracer;
+
+public class MyListener extends EsbMessageListenerWithSleuthIntegration {
+    public MyListener(final EsbJmsTemplate nozipEsbTemplate,
+                      final Tracer tracer) {
+        super(nozipEsbTemplate, tracer);
+    }
+}
+```
+
+should now be :
+
+```java
+import ch.vd.cyber.backofficebe.jms.EsbMessageListenerWithTracingPropagation;
+import io.micrometer.tracing.propagation.Propagator;
+import io.micrometer.tracing.Tracer;
+
+public class MyListener extends EsbMessageListenerWithTracingPropagation {
+    public MyListener(final EsbJmsTemplate nozipEsbTemplate,
+                      final Tracer tracer,
+                      final Propagator propagator) {
+        super(nozipEsbTemplate, tracer, propagator);
+    }
+}
+```
+
+finally, if you have mock issues with you integration tests, you can use `ch.vd.cyber.backofficebe.jms.JmsTestUtils.mockTracingPropagation(final Tracer tracerMock, final Propagator propagatorMock)`
+
+### BO : ESB Integration
+
+- Check that you should always create your ListenerContainer with `ch.vd.cyber.backofficebe.jms.EsbConfigUtils.createDefaultMessageListenerContainer(...)`
+    - This simplifies the configuration and ensures that the correct `MessageListenerContainer` is used with the new tracing integration.
+
+### Property migration
+
+Run your application with this dependency :
+
+```
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-properties-migrator</artifactId>
+    <scope>runtime</scope>
+</dependency>
+```
+
+Look for logs that indicate property you should migrate (watch for WARN logs of class PropertiesMigrationListener), update them and remove the dependency
+
+### Debugging tips
+
+Spring boot 4 doesn't support calling a controller with a trailing slash, fix the url called (/api/ping != /api/ping**/**)
+
+### Clean Sonar code smells
+
+You can use the following OpenRewrite recipes to clean Sonar code smells. It is recommended to do it after the migration to avoid mixing the migration changes with code cleaning changes, and to make it easier to review.
+
+```bash
+mvn -U org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-testing-frameworks:RELEASE -Drewrite.activeRecipes=org.openrewrite.java.testing.junit.JUnit6BestPractices, -Pnof,noft
+
+mvn -U org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-static-analysis:RELEASE -Drewrite.activeRecipes=org.openrewrite.staticanalysis.CommonStaticAnalysis -Pnof,noft
+
+mvn -U org.openrewrite.maven:rewrite-maven-plugin:run --define rewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-testing-frameworks:RELEASE --define rewrite.activeRecipes=org.openrewrite.java.testing.mockito.MockitoBestPractices --define rewrite.exportDatatables=true -Pnof,noft
+
+mvn -U org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.activeRecipes=org.openrewrite.java.RemoveUnusedImports -Pnof,noft
+```
+
+Take a look at Sonar to see other things that you can improve or ignore.