Releases · Coreoz/Plume

22 Nov 08:58

5.0.0-beta1

189a316

5.0.0-beta1 Latest

Latest

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

Java EE -> Jakarta EE
JUnit 4 -> JUnit 5
Dependencies upgrade
Java 20+ support
Enables HikariCP and Grizzly threads pool monitoring
Add Jersey request max content size verification to improve security and avoid denial-of-service attacks
Fix timing attack on the basic authentication service
Pagination for plume-db-querydsl
Use by standard Clock instead of the custom TimeProvider
Add plume-test module
#26 Add nullable annotations for better Kotlin integration
Review how Swagger UI is used to enable to use the latest version of the UI

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

03 Aug 08:48

amanteaux

4.2.3

d741d31

4.2.3

Changelog

This release contains:

(4d92e96) Plume Jersey monitoring: fix object mapper regression

Assets 2

27 Jul 14:51

amanteaux

4.2.2

c167aa7

4.2.2

Changelog

This release contains:

Plume Jersey monitoring: fix /info endpoint

Assets 2

21 Jul 14:21

amanteaux

4.2.1

4e71351

4.2.1

Changelog

This release contains:

Plume Jersey monitoring module addition
Upgrade Guice and H2 to fix security issues

Assets 2

21 Jul 14:19

amanteaux

4.2.0

cd7bb49

4.2.0

Failed Maven release :(

Assets 2

06 Dec 17:39

lucas-amiaud

4.1.1

f981a31

4.1.1

Changelog

This release contains:

936f500 Update Jackson to version 2.14.11 to fix CVE-2022-42003
6b61eb0 Fix plume-db transaction rollback error report

Assets 2

16 Sep 11:25

amanteaux

4.1.0

0ab47b1

4.1.0

Changelog

This release contains only updated dependencies, mainly:

Wisp to version 2.3.0: it reduces the overall footprint of the library and contains security improvement
SLF4J to version 2.0.0: it contains a new fluent API to add logs which arguments are not evaluated if the log is ignored, e.g logger.atDebug().setMessage("Temperature set to {}. Old value was {}.").addArgument(() -> t16()).addArgument(oldT).log()
Flyway to version 9.x.x

Other minor upgrades are detailed in commit d45cea7.

Upgrade instructions

If Wisp is used with Cron expression, upgrade instructions should be followed (but are not mandatory).

Assets 2

28 Apr 12:06

amanteaux

4.0.0

f6d5840

4.0.0

Changelog

This release contains only updated dependencies. It enables to fix security issues that should have a limited impact on projects:

Jackson security issues (DoS and gadget issues: https://cowtowncoder.medium.com/on-jackson-cves-dont-panic-here-is-what-you-need-to-know-54cd0d6e8062)
H2 security issue, though H2 is only used for tests in Plume

Upgrade instructions from 3.x to 4.x

H2 has migrated to the V2 version. The main impacts observed is that SQL scripts that contains reserved keywords (user, type, value, etc.) in table/column names must be escaped: SELECT * FROM user => SELECT * FROM "user". More details are available on http://www.h2database.com/html/migration-to-v2.html. A side effect is that Flyway scripts used with H2 may be broken... whereas they already have been executed on other environments: In that case, Flyway checksums should be updated on other environments manually or using a temporary fix (until every environments are updated) by replacing flyway.migrate() by flyway.repair(); flyway.migrate(), for more information see https://flywaydb.org/documentation/command/repair
For H2, table/column names are now escaped in QueryDSL: most of the time it should not be an issue, but for tests, when H2 is set to MYSQL mode, the QueryDSL dialect must be set to MYSQL too. It means that if the test config file contains something similar to this db.hikari."dataSource.url"="jdbc:h2:mem:test;MODE=MYSQL", then db.dialect="MYSQL" should be used (and not H2)
Simple Mail Java has been updated to the V7 version. No impact have been noticed. More details are available on https://github.com/bbottema/simple-java-mail#whats-new
Flyway has been upgraded to the V8 version: details are available on flyway/flyway#3247. The main impact observed is that project using MySQL/MariaDB and Flyway must now add this dependency in their pom.xml file:

<dependency>
  <groupId>org.flywaydb</groupId>
  <artifactId>flyway-mysql</artifactId>
</dependency>

Swagger UI has been updated to version 4.1.2, links to Swagger must be updated, for example in src/main/resources/statics/index.html:

<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>

Java 9+ dependencies are now part of Plume dependencies, so these dependencies can be removed from the pom.xml file:

<!-- jdk9+ non included Java libraries required for Jersey -->
<dependency>
  <groupId>javax.xml.bind</groupId>
  <artifactId>jaxb-api</artifactId>
</dependency>
<dependency>
  <groupId>com.sun.xml.bind</groupId>
  <artifactId>jaxb-core</artifactId>
</dependency>
<dependency>
  <groupId>com.sun.xml.bind</groupId>
  <artifactId>jaxb-impl</artifactId>
</dependency>
<dependency>
  <groupId>javax.activation</groupId>
  <artifactId>javax.activation-api</artifactId>
</dependency>
<dependency>
  <groupId>javax.annotation</groupId>
  <artifactId>javax.annotation-api</artifactId>
</dependency>

In QuerydslGenerator, to keep the toString() method on generated beans, replace exporter.setBeanSerializer(new IdBeanSerializer().setUseJacksonAnnotation(true)); by:

IdBeanSerializer beanSerializer = new IdBeanSerializer().setUseJacksonAnnotation(true);
beanSerializer.setAddToString(true);
exporter.setBeanSerializer(beanSerializer);

Assets 2

23 Sep 08:58

amanteaux

3.0.0

e968434

3.0.0

Changelog

Java 11+ required
Update dependencies
Upgrade Swagger/OpenAPI

Upgrade instructions from 2.x to 3.x

At least Java 11 is required
If you are using Plume Admin, you will need to follow the specific upgrade instructions
Swagger/OpenAPI annotations need to be update:
- @Api(value = "API Description") -> @Tag(name = "api-name", description = "API Description")
- @ApiOperation(value = "API endpoint operation description") -> @Operation(description = "API endpoint operation description")
- @ApiParam -> @Parameter
SwaggerWs API needs to be updated, this parts need to be replaced:

BeanConfig beanConfig = new BeanConfig();
beanConfig.setResourcePackage("com.coreoz.webservices.api"); // The package will be different for your project
beanConfig.setBasePath("/api");
beanConfig.setTitle("API plume-demo-admin"); // The title is different for your project
// this is not only a setter, it also starts the Swagger classes analyzing process
beanConfig.setScan(true);

// the swagger object can be changed to add security definition
// or to alter the generated mapping
Swagger swagger = beanConfig.getSwagger();

// serialization of the Swagger definition
try {
	this.swaggerDefinition = Json.mapper().writeValueAsString(swagger);
} catch (JsonProcessingException e) {
	throw new RuntimeException(e);
}

by (and @SneakyThrows should be added to the constructor):

// Basic configuration
SwaggerConfiguration openApiConfig = new SwaggerConfiguration()
	.resourcePackages(Set.of("com.coreoz.webservices.api")) // The package will be different for your project
	.sortOutput(true)
	.openAPI(new OpenAPI().servers(List.of(
		new Server()
			.url("/api")
			.description("API plume-demo-admin") // The title is different for your project
	)));

// Generation of the OpenApi object
OpenApiContext context = new JaxrsOpenApiContextBuilder<>()
	.openApiConfiguration(openApiConfig)
	.buildContext(true);
// the OpenAPI object can be changed to add security definition
// or to alter the generated mapping
OpenAPI openApi = context.read();

// serialization of the Swagger definition
this.swaggerDefinition = Yaml.mapper().writeValueAsString(openApi);

pom.xml must be updated:
- play2-maven-plugin version must be set to 1.0.0-rc5
- If a library that provides Swagger annotation (e.g. plume-file is used, the old Swagger annotations library should be excluded:

<dependency>
  <groupId>com.coreoz</groupId>
  <artifactId>plume-file</artifactId>
  <exclusions>
    <exclusion>
      <artifactId>swagger-jaxrs</artifactId>
      <groupId>io.swagger</groupId>
    </exclusion>
  </exclusions>
</dependency>

Dependency swagger-jaxrs must be updated and the exclusion of joda-time & jsr311-api can be removed:
from:

<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-jaxrs</artifactId>
</dependency>

to:

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

index.html file should be updated:
From:

<a href="webjars/swagger-ui/2.2.10-1/index.html?url=/api/swagger">webjars/swagger-ui/2.2.10-1/index.html?url=/api/swagger</a>

To:

<a href="webjars/swagger-ui/3.52.1/index.html?url=/api/swagger">webjars/swagger-ui/3.52.1/index.html?url=/api/swagger</a>

Assets 2

24 Jun 12:21

amanteaux

2.1.0

bcec46f

2.1.0

Changelog

Java 16 support
Update dependencies

Upgrade process

The upgrade should be done by updating the Plume POM dependencies management version to 2.1.1.

Assets 2

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Identified issue

Changelog

Upgrade instructions from 4.x to 5.x

Java 17

Migration from Java EE to Jakarta EE

Swagger upgrade

JUnit 5 migration

TimeProvider deprecated to use Clock instead

Improved security: request max content size verification

Plume file update

JJwt update

Transaction manager

Monitoring

Changelog

Changelog

Changelog

Changelog

Changelog

Upgrade instructions

Changelog

Upgrade instructions from 3.x to 4.x

Changelog

Upgrade instructions from 2.x to 3.x

Changelog

Upgrade process

Releases: Coreoz/Plume

5.0.0-beta1

Identified issue

Changelog

Upgrade instructions from 4.x to 5.x

Java 17

Migration from Java EE to Jakarta EE

Swagger upgrade

JUnit 5 migration

TimeProvider deprecated to use Clock instead

Improved security: request max content size verification

Plume file update

JJwt update

Transaction manager

Monitoring

4.2.3

Changelog

4.2.2

Changelog

4.2.1

Changelog

4.2.0

4.1.1

Changelog

4.1.0

Changelog

Upgrade instructions

4.0.0

Changelog

Upgrade instructions from 3.x to 4.x

3.0.0

Changelog

Upgrade instructions from 2.x to 3.x

2.1.0

Changelog

Upgrade process