Skip to content

Commit 2c83c5d

Browse files
anavarrjponge
anavarr
and
jponge
committed
docs: add a migration guide for mutiny bindings generator 3.x to 4.x
- details how the new generator is a full CLI instead of an annotation processing tool - add links to 'using the generator' in index and in migration guide - augment 'using the generator' with a tip explaining how additional sources are useful Co-authored-by: Julien Ponge <julien.ponge@outlook.com>
1 parent 859b2a6 commit 2c83c5d

File tree

7 files changed

+24853
-7
lines changed

7 files changed

+24853
-7
lines changed

‎docs/compatibility-report-3-to-4.html‎

Lines changed: 24706 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,3 +74,5 @@ JsonObject body = fetchData(client).await().indefinitely();
7474
- [Type Mapping](type-mapping.md): understand how Vert.x types are converted to Mutiny types.
7575
- [Error Handling](error-handling.md): strategies for handling failures in reactive pipelines.
7676
- [Available Modules](available-modules.md): the full list of generated client modules.
77+
- [Upgrading from version 3 to 4](migration-guide-3x-4x.md): migrate to the new Mutiny bindings generator.
78+
- [Using the binding generator for your own APIs](using-the-generator.md): learn to use the generator for your own APIs.

‎docs/migration-guide-3x-4x.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Upgrading from version 3 to 4
2+
3+
## Overview
4+
5+
With the release of Vert.x 5, important API changes were made, sometimes breaking the compability with Vert.x 4.x projects. It was an opportunity to release a new version of the generator. This guide will walk through the changes between the Mutiny Vert.x bindings for Vert.x 4 and Vert.x 5.
6+
7+
## A new Mutiny bindings generator
8+
In its 3.x version, the Vert.x-mutiny bindings generator was an annotation processor. It was executed on a given module by using the `maven-processor-plugin`.
9+
As an annotation processor, it can only be run during maven compilation. Generating bindings thus requires compiling or recompiling the sources.
10+
The new approach still uses annotations to detect which classes and interfaces must be generated, but annotation processing is now part of a full CLI possessing its own `Main` class and its own lifecycle independent from that of the sources.
11+
This makes it easier to test and faster to run.
12+
13+
## API changes
14+
Numerous API changes are due to the transition to Vert.x 5.
15+
The Vert.x 4 to 5 migration guide is available at <https://vertx.io/docs/guides/vertx-5-migration-guide/>.
16+
17+
We provide here a brief summary of the breaking changes, the exhaustive list can be found [in a compatibility report detailing every API change](compatibility-report-3-to-4.html).
18+
19+
### Generics are better specified
20+
In version 3 of the bindings generator, several generics were left unspecified. We changed this behavior so that every generics used is either correctly specified or uses a wildcard.
21+
See the [full compatibility report](compatibility-report-3-to-4.html) for more information.
22+
23+
### No more Callbacks
24+
25+
Complete removal of callback methods such as:
26+
```java
27+
void request(RequestOptions request, Handler<AsyncResult<HttpClientRequest>> callback);
28+
```
29+
30+
They have all been replaced with a Future such as:
31+
```java
32+
Future<HttpClientRequest> request(RequestOptions request);
33+
```
34+
35+
Consequently, the bindings generator only supports the `Future` style and will generate the following:
36+
```java
37+
Uni<HttpClientRequest> request(RequestOptions request);
38+
```
39+
40+
### Deprecated modules are no more
41+
| Sunsetting in 4.x | Replacement in 5.x |
42+
|-----------------------|-----------------------------------------------------------------------------------|
43+
| Vert.x Sync | Vert.x virtual threads |
44+
| Service Factories | None |
45+
| Maven Service Factory | None |
46+
| HTTP Service Factory | None |
47+
| Vert.x Web OpenAPI | [Vert.x Web OpenAPI Router](https://vertx.io/docs/vertx-web-openapi-router/java/) |
48+
| Vert.x CLI | None |
49+
50+
51+
### Changes with regards to `@DataObject` and `@VertxGen`
52+
Numerous classes are now annotated `@DataObject` instead of `@VertxGen`. `@DataObject` annotation existed in Vert.x 4.x and was used mainly for `*Options.java` classes. No wrappers are thus required, the core Vert.x interface is used directly. They will break existing projects as imports are now invalid.
53+
54+
Below are some classes that are not converted to Mutiny shims anymore:
55+
56+
- `io.vertx.core.buffer.Buffer`
57+
- `io.vertx.core.net.Address`
58+
- `io.vertx.core.net.SocketAddress`
59+
- `io.vertx.core.parsetools.JsonEvent`
60+
- `io.vertx.core.MultiMap`
61+
- `io.vertx.core.datagram.DatagramPacket`
62+
63+
### SQL clients have been reworked
64+
In Vert.x 4, `Pool` subtypes were used for every kind of databases: `PgPool, MySQLPool, MSSQLPool`, etc. They have all been removed and replaced with client builder subtypes:
65+
66+
```java
67+
// 4.x
68+
PgPool client = PgPool.pool(vertx, connectOptions, poolOptions);
69+
70+
//5.0
71+
Pool client = PgBuilder.pool()
72+
.with(poolOptions)
73+
.connectingTo(connectOptions)
74+
.using(vertx)
75+
.build();
76+
```
77+
78+
For more information, see [Vert.x 5 migration guide](https://vertx.io/docs/guides/vertx-5-migration-guide/#_vert_x_sql_client).
79+
80+
## Dropped or replaced modules
81+
82+
| Module | Replacement |
83+
| ------------------- | ----------------------------- |
84+
| service-discovery-* | *dropped* |
85+
| web-openapi | (openapi, web-openapi-router) |
86+
| web-auth-shiro | *dropped* |
87+
| web-auth-webauthn | web-auth-webauthn4j |
88+
| auth-jdbc | *dropped* |
89+
| jdbc-client | *dropped* |
90+
| web-api-contract | *dropped* |
91+
| web-templ-jade | *dropped* |
92+
| stomp | *dropped* |
93+
| shell | *dropped* |
94+
95+
96+
## Using the generator with your own asynchronous APIs
97+
[Learn how to use the bindings generator with your own asynchronous APIs](using-the-generator.md).

‎docs/using-the-generator.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,46 @@ The `maven-dependency-plugin` extracts Vert.x source JARs into `target/sources/j
6666
</plugin>
6767
```
6868

69+
!!! tip "Additional sources"
70+
You might need to generate Mutiny bindings for modules `moduleA` and `moduleB`, where `moduleB` uses classes or interfaces from `moduleA`.
71+
In this instance, you should add `moduleA` as additional sources to ensure that you are using the generated mutiny API for `moduleA` in `moduleB`, and not the original one.
72+
This is easily achievable by setting the `maven-dependency-plugin` for `moduleB` like below.
73+
```xml
74+
<plugin>
75+
<artifactId>maven-dependency-plugin</artifactId>
76+
<configuration>
77+
<includeGroupIds>org.acme</includeGroupIds>
78+
<includeArtifactIds>moduleB</includeArtifactIds>
79+
<classifier>sources</classifier>
80+
<includeTypes>jar</includeTypes>
81+
</configuration>
82+
<executions>
83+
<execution>
84+
<id>unpack-java</id>
85+
<phase>generate-sources</phase>
86+
<goals><goal>unpack-dependencies</goal></goals>
87+
<configuration>
88+
<includes>io/vertx/**/*.java</includes>
89+
<excludes>**/impl/**/*.java</excludes>
90+
<outputDirectory>${project.build.directory}/sources/java</outputDirectory>
91+
</configuration>
92+
</execution>
93+
<!-- Optional: unpack additional sources for cross-module resolution -->
94+
<execution>
95+
<id>unpack-vertx-core</id>
96+
<phase>generate-sources</phase>
97+
<goals><goal>unpack-dependencies</goal></goals>
98+
<configuration>
99+
<includes>io/vertx/**/*.java</includes>
100+
<excludes>**/impl/**/*.java</excludes>
101+
<includeArtifactIds>vertx-core,moduleA</includeArtifactIds>
102+
<outputDirectory>${project.basedir}/target/additional-sources/vertx-core</outputDirectory>
103+
</configuration>
104+
</execution>
105+
</executions>
106+
</plugin>
107+
```
108+
69109
### 2. Run the Generator
70110

71111
The `exec-maven-plugin` invokes the generator with the unpacked sources as input.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ nav:
1111
- Blocking and Testing: blocking-and-testing.md
1212
- Using the Generator: using-the-generator.md
1313
- Available Modules: available-modules.md
14+
- Upgrading from version 3 to 4: migration-guide-3x-4x.md
1415
- Javadoc: './apidocs/index.html'
1516

1617
theme:

‎uv.lock‎

Lines changed: 6 additions & 6 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎vertx-mutiny-code-generator/src/test/java/io/smallrye/mutiny/vertx/apigenerator/generation/AndAwaitWithVoidTest.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,4 +35,4 @@ public interface MyInterface {
3535
assertThat(env.getOutputFor("org.acme.MyInterface").javaFile().toString()).contains("void methodAndAwait()");
3636

3737
}
38-
}
38+
}

0 commit comments

Comments
 (0)