Skip to content

Refactor gRPC plugin implementation for modular architecture #206

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zZHorizonZz merged 9 commits into from
Oct 20, 2025
Merged

Refactor gRPC plugin implementation for modular architecture #206

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
c7d3174
Refactor gRPC plugin implementation
zZHorizonZz Sep 9, 2025
cfaf0af
Migrate doc to use `io.github.ascopes` and update configurations acro…
zZHorizonZz Sep 9, 2025
e18f1cd
Add `VertxGrpcGeneratorCommand` for CLI argument parsing and enhance …
zZHorizonZz Sep 12, 2025
46fcf63
Clarify plugin names
zZHorizonZz Sep 12, 2025
73e3c95
Expand plugin argument documentation with detailed value specifications
zZHorizonZz Sep 12, 2025
ec2ba1c
Refactor code generation architecture
zZHorizonZz Oct 2, 2025
4792079
Remove TemplateEngine and rename MustacheTemplateEngine to TemplateEn…
zZHorizonZz Oct 9, 2025
c305e4b
Refactor method name formatting logic
zZHorizonZz Oct 11, 2025
d2b94ff
Remove `FileWriter` and its usages from the gRPC plugin
zZHorizonZz Oct 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,6 +264,14 @@
<pluginParameter>@generated=omit</pluginParameter>
</configuration>
</plugin>
<plugin>
<groupId>io.github.ascopes</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<version>3.8.2</version>
<configuration>
<protocVersion>${protobuf.version}</protocVersion>
</configuration>
</plugin>
</plugins>
</pluginManagement>
<plugins>
Expand Down
49 changes: 28 additions & 21 deletions vertx-grpc-docs/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,33 +81,40 @@
</executions>
</plugin>
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<groupId>io.github.ascopes</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<configuration>
<outputDirectory>${project.basedir}/src/main/java</outputDirectory>
<cleanOutputDirectories>false</cleanOutputDirectories>
<jvmMavenPlugins>
<jvmMavenPlugin>
<groupId>io.vertx</groupId>
<artifactId>vertx-grpc-protoc-plugin2</artifactId>
<version>${project.version}</version>
<mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
<options>grpc-client=true,grpc-service=true,grpc-io=true</options>
</jvmMavenPlugin>
</jvmMavenPlugins>
<!--jvmMavenPlugins>
<jvmMavenPlugin>
<groupId>io.vertx</groupId>
<artifactId>vertx-grpc-protoc-plugin2</artifactId>
<version>${project.version}</version>
<mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
<jvmArgs>
<jvmArg>-grpc-client</jvmArg>
<jvmArg>-grpc-service</jvmArg>
<jvmArg>-grpc-io</jvmArg>
</jvmArgs>
</jvmMavenPlugin>
</jvmMavenPlugins-->
</configuration>
<executions>
<execution>
<id>compile</id>
<goals>
<goal>compile</goal>
<goal>compile-custom</goal>
<goal>generate</goal>
</goals>
<configuration>
<protocPlugins>
<protocPlugin>
<id>vertx-grpc-protoc-plugin</id>
<groupId>io.vertx</groupId>
<artifactId>vertx-grpc-protoc-plugin2</artifactId>
<version>${project.version}</version>
<mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
<args>
<arg>--grpc-client</arg>
<arg>--grpc-service</arg>
<arg>--grpc-io</arg>
</args>
</protocPlugin>
</protocPlugins>
<outputDirectory>${project.basedir}/src/main/java</outputDirectory>
<clearOutputDirectory>false</clearOutputDirectory>
</configuration>
</execution>
</executions>
</plugin>
Expand Down
177 changes: 87 additions & 90 deletions vertx-grpc-docs/src/main/asciidoc/plugin.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,51 +38,88 @@ Using the definition above we need to compile it.

You can compile the proto file using the `protoc` compiler if you https://github.com/google/protobuf/tree/master/java#installation---without-maven[like], or you can integrate it in your build.

If you're using Apache Maven you need to add the plugin:
If you're using Apache Maven you can choose from 2 plugins `io.github.ascopes:protobuf-maven-plugin` (Recommended) or `org.xolstice.maven.plugin:protobuf-maven-plugin`:

[source,xml]
----
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<version>0.6.1</version>
<configuration>
<protocArtifact>com.google.protobuf:protoc:${protoc.version}:exe:${os.detected.classifier}</protocArtifact>
<pluginId>grpc-java</pluginId>
<pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
<protocPlugins>
<protocPlugin>
<id>vertx-grpc-protoc-plugin2</id>
<groupId>io.vertx</groupId>
<artifactId>vertx-grpc-protoc-plugin2</artifactId>
<version>${stack.version}</version>
<mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
</protocPlugin>
</protocPlugins>
</configuration>
<executions>
<execution>
<id>compile</id>
<configuration>
<outputDirectory>${project.basedir}/src/main/java</outputDirectory>
<clearOutputDirectory>false</clearOutputDirectory>
</configuration>
<goals>
<goal>compile</goal>
<goal>compile-custom</goal>
</goals>
</execution>
</executions>
<groupId>io.github.ascopes</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<version>${ascopes.grpc.version}</version>
<configuration>
<protocVersion>${protobuf.version}</protocVersion>
</configuration>
<executions>
<execution>
<id>compile-java</id>
<configuration>
<jvmMavenPlugins>
<jvmMavenPlugin>
<groupId>io.vertx</groupId>
<artifactId>vertx-grpc-protoc-plugin2</artifactId>
<version>${vertx.version}</version>
<mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
<options>grpc-client=true,grpc-service=true,grpc-io=true</options>
<!-- OR You can use jvmArgs -->
<jvmArgs>
<jvmArg>--grpc-client=true</jvmArg>
<jvmArg>--grpc-service=true</jvmArg>
<jvmArg>--grpc-io=true</jvmArg>
</jvmArgs>
</jvmMavenPlugin>
</jvmMavenPlugins>
</configuration>
</execution>
</executions>
</plugin>
----

The plugin configuration includes:
This plugin uses `protocVersion` instead of platform-specific artifacts and takes care of downloading protoc based on your platform and version on its own.

1. **Protocol Buffer compiler artifact** (`protocArtifact`) - Required for compiling `.proto` files into Java classes
2. **gRPC Java plugin** (`pluginId` and `pluginArtifact`) - Generates standard gRPC Java stubs, essential when using the `--grpc-io` option
3. **Vert.x gRPC plugin** (`protocPlugins`) - Generates Vert.x-specific gRPC client and service classes
4. **Output configuration** - Specifies where generated Java files will be placed (`src/main/java`)
5. **Compilation goals** - Defines which Maven goals to execute (`compile` and `compile-custom`)
For more details, see the https://ascopes.github.io/protobuf-maven-plugin/[ascopes protobuf-maven-plugin documentation].

[source,xml]
----
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<version>0.6.1</version>
<configuration>
<protocArtifact>com.google.protobuf:protoc:${protoc.version}:exe:${os.detected.classifier}</protocArtifact>
<pluginId>grpc-java</pluginId>
<pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
<protocPlugins>
<protocPlugin>
<id>vertx-grpc-protoc-plugin2</id>
<groupId>io.vertx</groupId>
<artifactId>vertx-grpc-protoc-plugin2</artifactId>
<version>${stack.version}</version>
<mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
<args>
<arg>--grpc-client=true</arg>
<arg>--grpc-service=true</arg>
<arg>--grpc-io=true</arg>
</args>
</protocPlugin>
</protocPlugins>
</configuration>
<executions>
<execution>
<id>compile</id>
<configuration>
<outputDirectory>${project.basedir}/src/main/java</outputDirectory>
<clearOutputDirectory>false</clearOutputDirectory>
</configuration>
<goals>
<goal>compile</goal>
<goal>compile-custom</goal>
</goals>
</execution>
</executions>
</plugin>
----

NOTE: The `org.xolstice.maven.plugin:protobuf-maven-plugin` is no longer supported as per https://github.com/xolstice/protobuf-maven-plugin/issues/121#issuecomment-2832430955. Users are encouraged to use `io.github.ascopes:protobuf-maven-plugin` instead.

For more details, see the https://www.xolstice.org/protobuf-maven-plugin/[xolstice protobuf-maven-plugin documentation].

Expand Down Expand Up @@ -111,66 +148,26 @@ By default, the plugin generates both client and service files. If you need only

[source,xml]
----
<protocPlugin>
<id>vertx-grpc-protoc-plugin2</id>
<jvmMavenPlugin>
<groupId>io.vertx</groupId>
<artifactId>vertx-grpc-protoc-plugin2</artifactId>
<version>${stack.version}</version>
<version>${vertx.version}</version>
<mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
<args>
<arg>--grpc-client</arg>
</args>
</protocPlugin>
----

=== Alternative Plugin Configuration

Alternatively, you can use the newer `io.github.ascopes` protobuf plugin:

[source,xml]
----
<plugin>
<groupId>io.github.ascopes</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<version>${ascopes.grpc.version}</version>
<configuration>
<protocVersion>${protobuf.version}</protocVersion>
</configuration>
<executions>
<execution>
<id>compile-java</id>
<configuration>
<jvmMavenPlugins>
<jvmMavenPlugin>
<groupId>io.vertx</groupId>
<artifactId>vertx-grpc-protoc-plugin2</artifactId>
<version>${vertx.version}</version>
<mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
<jvmArgs>
<jvmArg>--grpc-client=false</jvmArg>
</jvmArgs>
</jvmMavenPlugin>
</jvmMavenPlugins>
</configuration>
</execution>
</executions>
</plugin>
<options>grpc-client=true,grpc-service=true,grpc-io=true</options>
</jvmMavenPlugin>
----

This plugin uses `protocVersion` instead of platform-specific artifacts and takes care of downloading protoc based on your platform and version on its own.

For more details, see the https://ascopes.github.io/protobuf-maven-plugin/[ascopes protobuf-maven-plugin documentation].

=== Arguments:

- _--grpc-client_: generate the client files
- _--grpc-service_: generate the service files
- _--grpc-io_: generate stub files compatible with `io.grpc:grpc-stub`, not generated by default. When using this option, you must also ensure the grpc-java plugin is configured (as shown in the Maven configuration above)
- _--grpc-transcoding_: whether to generate transcoding options for methods with HTTP annotations
- _--vertx-codegen_: whether to add Vert.x annotations to the generated classes (`@VertxGen`) By default, this is disabled
- _--service-prefix_: generate service classes with a prefix. For example, if you set it to `MyService`, the generated service class will be `MyServiceGreeterService` instead of `GreeterService`.
- _--help_: show help message
- _--version_: show version information
- _[--]grpc-client[=true/false]_: generate the client files
- _[--]grpc-service[=true/false]_: generate the service files
- _[--]grpc-io[=true/false]_: generate stub files compatible with `io.grpc:grpc-stub`, not generated by default. When using this option, you must also ensure the grpc-java plugin is configured (as shown in the Maven configuration above)
- _[--]grpc-transcoding[=true/false]_: whether to generate transcoding options for methods with HTTP annotations
- _[--]vertx-codegen[=true/false]_: whether to add Vert.x annotations to the generated classes (`@VertxGen`) By default, this is disabled
- _[--]service-prefix[=Your Name]_: generate service classes with a prefix. For example, if you set it to `MyService`, the generated service class will be `MyServiceGreeterService` instead of `GreeterService`.

* [--] This means the argument can be prefixed with `--` when used as JVM arguments, but should be used without `--` when specified in the options tag. If possible, users should use plugin options as a more universal protoc plugin approach.
* [=value] This means the argument can optionally specify a value. For boolean arguments (true/false), if no value is specified, the default is `true` when the argument is present. For string arguments like `service-prefix`, a value must be provided.

If no specific generation options are provided, both client and service files will be generated by default. By default, all extensions (currently only 'http') are supported.

Expand Down
31 changes: 15 additions & 16 deletions vertx-grpc-it/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,33 +114,32 @@
</executions>
</plugin>
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<groupId>io.github.ascopes</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<configuration>
<protocArtifact>com.google.protobuf:protoc:${protoc.version}:exe:${os.detected.classifier}</protocArtifact>
<pluginId>grpc-java</pluginId>
<pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
<protocPlugins>
<protocPlugin>
<id>vertx-grpc-protoc-plugin</id>
<binaryMavenPlugins>
<binaryMavenPlugin>
<groupId>io.grpc</groupId>
<artifactId>protoc-gen-grpc-java</artifactId>
<version>${grpc.version}</version>
<options>@generated=omit</options>
</binaryMavenPlugin>
</binaryMavenPlugins>
<jvmMavenPlugins>
<jvmMavenPlugin>
<groupId>io.vertx</groupId>
<artifactId>vertx-grpc-protoc-plugin2</artifactId>
<version>${project.version}</version>
<mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
<args>
<arg>--grpc-client</arg>
<arg>--grpc-service</arg>
<arg>--grpc-io</arg>
</args>
</protocPlugin>
</protocPlugins>
<options>grpc-client=true,grpc-service=true,grpc-io=true</options>
</jvmMavenPlugin>
</jvmMavenPlugins>
</configuration>
<executions>
<execution>
<id>test-compile</id>
<goals>
<goal>test-compile</goal>
<goal>test-compile-custom</goal>
<goal>generate-test</goal>
</goals>
</execution>
</executions>
Expand Down
12 changes: 3 additions & 9 deletions vertx-grpc-protoc-plugin2/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,15 +40,9 @@
<version>2.50.0</version>
</dependency>
<dependency>
<groupId>com.salesforce.servicelibs</groupId>
<artifactId>jprotoc</artifactId>
<version>${jprotoc.version}</version>
<exclusions>
<exclusion>
<groupId>javax.annotation</groupId>
<artifactId>javax.annotation-api</artifactId>
</exclusion>
</exclusions>
<groupId>com.github.spullara.mustache.java</groupId>
<artifactId>compiler</artifactId>
<version>0.9.14</version>
</dependency>
<dependency>
<groupId>info.picocli</groupId>
Expand Down
Loading