Skip to content

5.0.0-beta1

Latest
Latest
Compare
Choose a tag to compare
@amanteaux amanteaux released this 22 Nov 08:58
· 4 commits to master since this release
5.0.0-beta1
189a316

This release is the biggest Plume release, by features and by breaking changes. We strived to make the upgrade as fast as possible and as documented as possible. On most projects, the migration should not take more than 1 hour of work. However, what can be time-consuming is to upgrade other dependencies that have not yet migrated to Jakarta EE (mostly dependency injection or Jersey web-service). If there is an upgrade issue, please reach out.

About the beta release: no big change are expected before the final release version. This beta version has been tested, but since the changes of this release are bigger than usual, we prefer to release first a non-final version that is more likely to contain small bugs that we will fix in the final version. Please share all the issues you might encounter with this beta version.

Identified issue

There is an issue with Jersey/HK2 and the beta1 release: eclipse-ee4j/glassfish-hk2#1130

To mitigate this issue, in the JerseyConfigProvider class, the 2 lines for the bindings for the WebSessionAdminFactory class should be inverted this way:

bindFactory(WebSessionAdminFactory.class).to(WebSessionAdmin.class).in(RequestScoped.class);
bindFactory(WebSessionAdminFactory.class).to(WebSessionPermission.class).in(RequestScoped.class);

Changelog

Upgrade instructions from 4.x to 5.x

Java 17

The minimum required Java version is now 17.

Migration from Java EE to Jakarta EE

This migration can mainly be done automatically with:

  • Either Intellij using the main menu (on the top bar): Refactor > Migrate Packages and Classes... > Java EE to Jakarta EE
  • Either by running the openrewrite migration plugin: mvn -U org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:RELEASE -Drewrite.activeRecipes=org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta -Drewrite.exportDatatables=true ⚠️ This command line must be executed before upgrading plume version in the pom.xml file

Note that dependency javax.servlet-api should now be deleted in the pom.xml file since it should not be used anymore.

swagger-jaxrs2 artifact must also be changed in the pom.xml file to use the Jakarta version swagger-jaxrs2-jakarta:

<dependency>
  <groupId>io.swagger.core.v3</groupId>
  <artifactId>swagger-jaxrs2-jakarta</artifactId>
</dependency>

Swagger upgrade

Swagger has been upgraded and it is not possible anymore to use the query parameter url: swagger-api/swagger-ui#7702

To overcome this, Swagger UI is now loaded directly from the index.html file of the project using webjars.
This file was generally containing this:

API Swagger documentation:
        <a href="webjars/swagger-ui/4.1.2/index.html?url=/api/swagger">
            webjars/swagger-ui/4.1.2/index.html?url=/api/swagger
        </a>

And now the file should be updated with:

<head>
  <!-- current head tag content should remain unchanged -->

  <!-- head tag content to be added: new links to updated swagger-ui -->
  <script src="webjars/swagger-ui/5.17.14/swagger-ui-bundle.js" charset="UTF-8"></script>
  <script src="webjars/swagger-ui/5.17.14/swagger-ui-standalone-preset.js" charset="UTF-8"></script>
  <link rel="stylesheet" href="webjars/swagger-ui/5.17.14/swagger-ui.css">
</head>
<body>
  <div id="swagger-ui"></div>
  <script>
    SwaggerUIBundle({
      url: "/api/swagger",
      dom_id: '#swagger-ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
      ],
      layout: "StandaloneLayout"
    });
  </script>
</body>

After the update, Swagger UI will be accessible on the URL http://localhost:8080/ instead of http://localhost:8080/webjars/swagger-ui/4.1.2/index.html?url=/api/swagger

JUnit 5 migration

Plume now uses only JUnit 5.
This migration has been covered in many guides, for example https://blog.jetbrains.com/idea/2020/08/migrating-from-junit-4-to-junit-5/ or https://docs.openrewrite.org/running-recipes/popular-recipe-guides/migrate-from-junit-4-to-junit-5

Intellij also provide a feature that automates most of this: Refactor > Migrate Packages and Classes... > Unit (4.x -> 5.0). Note that this feature seems a bit buggy and it often needs to be launched multiple times. Moreover, @Test(expected = SomeException.class) is not migrated automatically, for that, the stackoverflow Q/A can be followed.

Note that the new package Guice JUnit has been included in Plume to run easily JUnit 5 tests that requires Guice dependency members. This replaces the non maintained JUnit 4 Guice integration referenced by Plume < v5.0.0. The migration to use Guice JUnit is straightforward:

  • Remove the line @RunWith(GuiceTestRunner.class) from tests
  • Replace the line @GuiceModules(MyModule.class) by @GuiceTest(MyModule.class)

TimeProvider deprecated to use Clock instead

The TimeProvider class has been deprecated: it was a custom solution that wasn't easy to use in non Plume project and that is actually resolved by the Java based standard Clock object.

To facilitate the use of the Clock object, the Plume test module can be used. It contains especially the MockedClock class.

When using Plume Admin, here are the files that have switched to using Clock instead of TimeProvider:

  • AdminUserService
  • JwtSessionSigner
  • JwtSessionSignerProvider
  • LogApiService
  • SessionWs

Improved security: request max content size verification

A new Jersey feature has been added to limit the size of body requests. This feature mitigates risk of denial of service.

See Plume Jersey documentation to enable it.

Enabling this feature will improve the robustness of the application, but it can also lead to regressions: some API might require to support large body requests. So after setting this up:

  • A review should be made to try to identify API that require large body requests to configure correctly the max content size
  • A full testing of the application should be performed

Plume file update

If Plume file is used, its updated version number is now configured in Plume dependencies.

This means that referenced Plume file version should be removed in the pom.xml file. If this changes is not applied, Plume file version must be updated to work correctly with the Java EE to Jakarta EE update.

For Plume file v1 usage, please upgrade to Plume file latest version.

JJwt update

If JJwt is manipulated directly, some changes are required: https://github.com/jwtk/jjwt/blob/0.12.0/CHANGELOG.md

A migration sample can be found in the Plume Admin JJwt migration.

Transaction manager

TransactionManager and TransactionManagerQuerydsl are not creating by HikariCP pool by themselves anymore. Instead, they rely on a DataSource object. This DataSource can be created using the HikariDataSources.fromConfig() method, e.g. : HikariDataSources.fromConfig(config, "db.hikari").

Monitoring

HikariCP threads pool and Grizzly threads pool can now be easily monitored.
To do that:

  • In GrizzlySetup, in the start() method:
    • add the following dependency in the method signature: GrizzlyThreadPoolProbe grizzlyThreadPoolProbe
    • declare the prob in the http server configuration: httpServer.getServerConfiguration().getMonitoringConfig().getThreadPoolConfig().addProbes(grizzlyThreadPoolProbe);
  • In MonitoringWs, in the constructor:
    • add the following dependencies in the method signature: GrizzlyThreadPoolProbe grizzlyThreadPoolProbe and HikariDataSource hikariDataSource
    • Use the metrics: this.metricsStatusProvider = new MetricsCheckBuilder().registerJvmMetrics().registerGrizzlyMetrics(grizzlyThreadPoolProbe).registerHikariMetrics(hikariDataSource).build()
Assets 2
Loading