Skip to content
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

gRPC code gen to generate health and reflection stubs #10886

Merged
merged 2 commits into from
Jul 23, 2020
Merged

gRPC code gen to generate health and reflection stubs #10886

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3ecb368
grpc code gen to generate health and reflection stubs
michalszynkiewicz Jul 21, 2020
bbb79f1
grpc docs fixes
michalszynkiewicz Jul 23, 2020
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
101 changes: 101 additions & 0 deletions bom/application/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -192,6 +192,8 @@
<!-- Make sure to check compatibility between these 2 gRPC components before upgrade -->
<grpc.version>1.29.0</grpc.version>
<grpc-jprotoc.version>1.0.1</grpc-jprotoc.version>
<protobuf-java.version>3.11.0</protobuf-java.version>
<protoc.version>3.11.4</protoc.version>

<picocli.version>4.4.0</picocli.version>
<org.eclipse.sisu.inject.version>0.3.4</org.eclipse.sisu.inject.version>
Expand Down Expand Up @@ -1222,6 +1224,16 @@
<artifactId>quarkus-grpc</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-grpc-codegen</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-grpc-stubs</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-grpc-deployment</artifactId>
Expand Down Expand Up @@ -4261,6 +4273,95 @@
<artifactId>jprotoc</artifactId>
<version>${grpc-jprotoc.version}</version>
</dependency>
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java</artifactId>
<version>${protobuf-java.version}</version>
</dependency>
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protoc</artifactId>
<classifier>linux-aarch_64</classifier>
<type>exe</type>
<version>${protoc.version}</version>
</dependency>
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protoc</artifactId>
<classifier>linux-x86_32</classifier>
<type>exe</type>
<version>${protoc.version}</version>
</dependency>
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protoc</artifactId>
<classifier>linux-x86_64</classifier>
<type>exe</type>
<version>${protoc.version}</version>
</dependency>
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protoc</artifactId>
<classifier>osx-x86_64</classifier>
<type>exe</type>
<version>${protoc.version}</version>
</dependency>
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protoc</artifactId>
<classifier>windows-x86_32</classifier>
<type>exe</type>
<version>${protoc.version}</version>
</dependency>
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protoc</artifactId>
<classifier>windows-x86_64</classifier>
<type>exe</type>
<version>${protoc.version}</version>
</dependency>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>protoc-gen-grpc-java</artifactId>
<type>exe</type>
<classifier>linux-aarch_64</classifier>
<version>${grpc.version}</version>
</dependency>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>protoc-gen-grpc-java</artifactId>
<type>exe</type>
<classifier>linux-x86_32</classifier>
<version>${grpc.version}</version>
</dependency>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>protoc-gen-grpc-java</artifactId>
<type>exe</type>
<classifier>linux-x86_64</classifier>
<version>${grpc.version}</version>
</dependency>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>protoc-gen-grpc-java</artifactId>
<type>exe</type>
<classifier>osx-x86_64</classifier>
<version>${grpc.version}</version>
</dependency>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>protoc-gen-grpc-java</artifactId>
<type>exe</type>
<classifier>windows-x86_32</classifier>
<version>${grpc.version}</version>
</dependency>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>protoc-gen-grpc-java</artifactId>
<type>exe</type>
<classifier>windows-x86_64</classifier>
<version>${grpc.version}</version>
</dependency>

<!-- Picocli -->
<dependency>
Expand Down
15 changes: 0 additions & 15 deletions build-parent/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,11 +92,6 @@
<jacoco.agent.argLine></jacoco.agent.argLine>
<jacoco.version>0.8.5</jacoco.version>

<!-- grpc -->
<os-maven-plugin.version>1.6.2</os-maven-plugin.version>
<protobuf-maven-plugin.version>0.6.1</protobuf-maven-plugin.version>
<protoc.version>3.11.4</protoc.version>
<grpc.version>1.29.0</grpc.version>
<maven-dependency-plugin.version>3.1.2</maven-dependency-plugin.version>
</properties>

Expand Down Expand Up @@ -481,16 +476,6 @@
</dependency>
</dependencies>
</plugin>
<plugin>
<groupId>kr.motd.maven</groupId>
<artifactId>os-maven-plugin</artifactId>
<version>${os-maven-plugin.version}</version>
</plugin>
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<version>${protobuf-maven-plugin.version}</version>
</plugin>
</plugins>
</pluginManagement>
</build>
Expand Down
2 changes: 0 additions & 2 deletions docs/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,8 +115,6 @@

<grpc-version>${grpc.version}</grpc-version>
<protoc-version>${protoc.version}</protoc-version>
<os-maven-plugin-version>${os-maven-plugin.version}</os-maven-plugin-version>
<protobuf-maven-plugin-version>${protobuf-maven-plugin.version}</protobuf-maven-plugin-version>
<elasticsearch-version>${elasticsearch-server.version}</elasticsearch-version>

<!-- Project website home page -->
Expand Down
163 changes: 97 additions & 66 deletions docs/src/main/asciidoc/grpc-getting-started.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,87 +15,32 @@ The default configuration is enough, but you can also select some extensions if

== Configuring your project

Edit the `pom.xml` file to add the quarkus gRPC extension dependency and the JSR 305 (just under `<dependencies>`):
Make sure you have `prepare` goal of `quarkus-maven-plugin` enabled in your `pom.xml`:

[source, xml]
----
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-grpc</artifactId>
</dependency>
----

In the `<properties>` section, define the 2 following properties:

[source, xml, subs="verbatim,attributes"]
----
<grpc.version>{grpc-version}</grpc.version>
<protoc.version>{protoc-version}</protoc.version>
----

They configure the gRPC version and the `protoc` version.

Finally, add to the `build` section the `os-maven-plugin` extension and the `protobuf-maven-plugin` configuration.

[source, xml, subs="verbatim,attributes"]
[source,xml]
----
<build>
<extensions>
<extension>
<groupId>kr.motd.maven</groupId>
<artifactId>os-maven-plugin</artifactId>
<version>{os-maven-plugin-version}</version>
</extension>
</extensions>

<plugins>
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<artifactId>protobuf-maven-plugin</artifactId> // <1>
<version>{protobuf-maven-plugin-version}</version>
<configuration>
<protocArtifact>com.google.protobuf:protoc:${protoc.version}:exe:${os.detected.classifier}</protocArtifact> // <2>
<pluginId>grpc-java</pluginId>
<pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
<protocPlugins>
<protocPlugin>
<id>quarkus-grpc-protoc-plugin</id>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-grpc-protoc-plugin</artifactId>
<version>{quarkus-version}</version>
<mainClass>io.quarkus.grpc.protoc.plugin.MutinyGrpcGenerator</mainClass>
</protocPlugin>
</protocPlugins>
</configuration>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<executions>
<execution>
<id>compile</id>
<goals>
<goal>compile</goal>
<goal>compile-custom</goal>
</goals>
</execution>
<execution>
<id>test-compile</id>
<goals>
<goal>test-compile</goal>
<goal>test-compile-custom</goal>
<goal>prepare</goal>
<goal>build</goal>
</goals>
</execution>
</executions>
</plugin>

<!-- ... -->
</plugins>
</build>
----
1. The `protobuf-maven-plugin` that generates stub classes from your gRPC service definition (`proto` files).
2. The class generation uses a tool named `protoc`, which is OS-specific.
That's why we use the `os-maven-plugin` to target the executable compatible with the operating system.

NOTE: This configuration instructs the `protobuf-maven-plugin` to generate the default gRPC classes and classes using Mutiny to fit with the Quarkus development experience.

With this configuration, you can put your service and message definitions in the `src/main/proto` directory.
`quarkus-maven-plugin` will generate Java files from your `proto` files.
Alternatively, you can use `protobuf-maven-plugin` to generate these files, more in <<Generating Java files from proto with protobuf-maven-plugin>>

Let's start with a simple _Hello_ service.
Create the `src/main/proto/helloworld.proto` file with the following content:

Expand Down Expand Up @@ -287,14 +232,15 @@ public class ExampleResource {
}
}
----
1. Inject the service and configure its name. This name is used in the application configuration

1. Inject the service and configure its name.This name is used in the application configuration
2. Use the _blocking_ stub (also a generated class)
3. Invoke the service

We need to configure the application to indicate where is the `hello` service.
In the `src/main/resources/application.properties` file, add the following property:

[source, text]
[source,text]
----
quarkus.grpc.clients.hello.host=localhost
----
Expand All @@ -308,3 +254,88 @@ Then, open http://localhost:8080/hello/quarkus in a browser, and you should get

Like any other Quarkus applications, you can package it with: `mvn package`.
You can also package the application into a native executable with: `mvn package -Pnative`.

== Generating Java files from proto with protobuf-maven-plugin

Alternatively to using Quarkus code generation to generate stubs for `proto` files, you can also use
`protobuf-maven-plugin` for this purpose.
To do it, edit the `pom.xml` file to add the quarkus gRPC extension dependency and the JSR 305 (just under `<dependencies>`):
michalszynkiewicz marked this conversation as resolved.
Show resolved Hide resolved

[source,xml]
----
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-grpc</artifactId>
</dependency>
----

In the `<properties>` section, define the 2 following properties:

[source,xml,subs="verbatim,attributes"]
----
<grpc.version>{grpc-version}</grpc.version>
<protoc.version>{protoc-version}</protoc.version>
----

They configure the gRPC version and the `protoc` version.

Finally, add to the `build` section the `os-maven-plugin` extension and the `protobuf-maven-plugin` configuration.

[source,xml,subs="verbatim,attributes"]
----
<build>
<extensions>
<extension>
<groupId>kr.motd.maven</groupId>
<artifactId>os-maven-plugin</artifactId>
<version>${os-maven-plugin-version}</version>
</extension>
</extensions>

<plugins>
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<artifactId>protobuf-maven-plugin</artifactId> // <1>
<version>${protobuf-maven-plugin-version}</version>
<configuration>
<protocArtifact>com.google.protobuf:protoc:${protoc.version}:exe:${os.detected.classifier}</protocArtifact> // <2>
<pluginId>grpc-java</pluginId>
<pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
<protocPlugins>
<protocPlugin>
<id>quarkus-grpc-protoc-plugin</id>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-grpc-protoc-plugin</artifactId>
<version>{quarkus-version}</version>
<mainClass>io.quarkus.grpc.protoc.plugin.MutinyGrpcGenerator</mainClass>
</protocPlugin>
</protocPlugins>
</configuration>
<executions>
<execution>
<id>compile</id>
<goals>
<goal>compile</goal>
<goal>compile-custom</goal>
</goals>
</execution>
<execution>
<id>test-compile</id>
<goals>
<goal>test-compile</goal>
<goal>test-compile-custom</goal>
</goals>
</execution>
</executions>
</plugin>

<!-- ... -->
</plugins>
</build>
----

1. The `protobuf-maven-plugin` that generates stub classes from your gRPC service definition (`proto` files).
2. The class generation uses a tool named `protoc`, which is OS-specific.
That's why we use the `os-maven-plugin` to target the executable compatible with the operating system.

NOTE: This configuration instructs the `protobuf-maven-plugin` to generate the default gRPC classes and classes using Mutiny to fit with the Quarkus development experience.
Loading