Skip to content

Commit 41f345e

Browse files
ascopesascopes
committed
Add reactor gRPC example
1 parent c128209 commit 41f345e

1 file changed

Lines changed: 151 additions & 115 deletions

File tree

‎protobuf-maven-plugin/src/site/markdown/examples.md‎

Lines changed: 151 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,155 @@ to avoid dependencies on `javax.annotation-api`.
4040
<options>@generated=omit</options>
4141
```
4242

43+
## gRPC and Reactor
44+
45+
Salesforce maintains a library to allow you to generate gRPC service stubs that use reactive
46+
streams via the Reactor framework.
47+
48+
To configure protobuf-maven-plugin to use this `protoc` plugin, use the following configuration:
49+
50+
```xml
51+
52+
<plugin>
53+
<groupId>io.github.ascopes</groupId>
54+
<artifactId>protobuf-maven-plugin</artifactId>
55+
56+
<configuration>
57+
<protocVersion>${protobuf.version}</protocVersion>
58+
59+
<binaryMavenPlugins>
60+
<binaryMavenPlugin>
61+
<groupId>io.grpc</groupId>
62+
<artifactId>protoc-gen-grpc-java</artifactId>
63+
<version>${grpc.version}</version>
64+
</binaryMavenPlugin>
65+
</binaryMavenPlugins>
66+
67+
<jvmMavenPlugins>
68+
<jvmMavenPlugin>
69+
<groupId>com.salesforce.servicelibs</groupId>
70+
<artifactId>reactor-grpc</artifactId>
71+
<version>${reactor-grpc.version}</version>
72+
</jvmMavenPlugin>
73+
</jvmMavenPlugins>
74+
</configuration>
75+
</plugin>
76+
```
77+
78+
## gRPC and Vert.x
79+
80+
For integrating with Vert.x, you can use the official Vert.x gRPC plugin:
81+
82+
```xml
83+
<plugin>
84+
<groupId>io.github.ascopes</groupId>
85+
<artifactId>protobuf-maven-plugin</artifactId>
86+
87+
<configuration>
88+
<protocVersion>${protobuf.version}</protocVersion>
89+
<jvmMavenPlugins>
90+
<jvmMavenPlugin>
91+
<groupId>io.vertx</groupId>
92+
<artifactId>vertx-grpc-protoc-plugin2</artifactId>
93+
<version>${vertx.version}</version>
94+
<mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
95+
<jvmArgs>
96+
<jvmArg>--grpc-client</jvmArg>
97+
<jvmArg>--grpc-service</jvmArg>
98+
<jvmArg>--service-prefix=Vertx</jvmArg>
99+
</jvmArgs>
100+
</jvmMavenPlugin>
101+
</jvmMavenPlugins>
102+
</configuration>
103+
</plugin>
104+
```
105+
106+
For more information, see the [Vert.x gRPC plugin documentation](https://vertx.io/docs/vertx-grpc/java/#vertx-grpc-protoc-plugin).
107+
108+
## Scala
109+
110+
Scala support for Protobuf and gRPC can be enabled using the ScalaPB Protoc plugin.
111+
112+
This is distributed as an OS-dependent binary within a ZIP archive on their GitHub releases.
113+
114+
A suitable Maven plugin for providing Scala compilation is also required.
115+
116+
```xml
117+
<plugins>
118+
<plugin>
119+
<groupId>io.github.ascopes</groupId>
120+
<artifactId>protobuf-maven-plugin</artifactId>
121+
122+
<configuration>
123+
<javaEnabled>false</javaEnabled>
124+
125+
<binaryUrlPlugins>
126+
<binaryUrlPlugin>
127+
<url>zip:https://github.com/scalapb/ScalaPB/releases/download/v${scalapb.version}/protoc-gen-scala-${scalapb.version}-linux-x86_64.zip!/protoc-gen-scala</url>
128+
<options>flat_package,grpc,scala3_sources</options>
129+
</binaryUrlPlugin>
130+
</binaryUrlPlugins>
131+
</configuration>
132+
133+
<executions>
134+
<execution>
135+
<goals>
136+
<goal>generate</goal>
137+
</goals>
138+
</execution>
139+
</executions>
140+
</plugin>
141+
142+
143+
<plugin>
144+
<groupId>net.alchim31.maven</groupId>
145+
<artifactId>scala-maven-plugin</artifactId>
146+
147+
<configuration>
148+
<failOnMultipleScalaVersions>true</failOnMultipleScalaVersions>
149+
</configuration>
150+
</plugin>
151+
</plugins>
152+
```
153+
154+
An example service handler may look like the following:
155+
156+
`src/main/protobuf/helloworld.proto`:
157+
```protobuf
158+
syntax = "proto3";
159+
160+
option java_multiple_files = true;
161+
option java_package = "org.example.helloworld";
162+
163+
package org.example.helloworld;
164+
165+
message GreetingRequest {
166+
string name = 1;
167+
}
168+
169+
message GreetingResponse {
170+
string text = 1;
171+
}
172+
173+
service GreetingService {
174+
rpc Greet(GreetingRequest) returns (GreetingResponse);
175+
}
176+
```
177+
178+
`src/main/scala/org/example/helloworld/HelloWorld.scala`:
179+
```scala
180+
package org.example.helloworld
181+
182+
import scala.concurrent.Future
183+
184+
class GreetingServiceImpl extends GreetingServiceGrpc.GreetingService:
185+
override def greet(request: GreetingRequest) =
186+
val response = GreetingResponse(text = "Hello, " + request.name + "!")
187+
Future.successful(response)
188+
end GreetingServiceImpl
189+
```
190+
191+
43192
## JavaScript and gRPC-Web
44193

45194
While JavaScript generation is not natively supported by this plugin (as it's not part of core protoc), you can easily integrate JavaScript and gRPC-Web code generation using binary URL plugins.
@@ -154,36 +303,6 @@ The `protoc-gen-grpc-web` plugin supports:
154303

155304
For more information, see the [gRPC-Web plugin documentation](https://github.com/grpc/grpc-web).
156305

157-
## gRPC and Vert.x
158-
159-
For integrating with Vert.x, you can use the official Vert.x gRPC plugin:
160-
161-
```xml
162-
<plugin>
163-
<groupId>io.github.ascopes</groupId>
164-
<artifactId>protobuf-maven-plugin</artifactId>
165-
166-
<configuration>
167-
<protocVersion>${protobuf.version}</protocVersion>
168-
<jvmMavenPlugins>
169-
<jvmMavenPlugin>
170-
<groupId>io.vertx</groupId>
171-
<artifactId>vertx-grpc-protoc-plugin2</artifactId>
172-
<version>${vertx.version}</version>
173-
<mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
174-
<jvmArgs>
175-
<jvmArg>--grpc-client</jvmArg>
176-
<jvmArg>--grpc-service</jvmArg>
177-
<jvmArg>--service-prefix=Vertx</jvmArg>
178-
</jvmArgs>
179-
</jvmMavenPlugin>
180-
</jvmMavenPlugins>
181-
</configuration>
182-
</plugin>
183-
```
184-
185-
For more information, see the [Vert.x gRPC plugin documentation](https://vertx.io/docs/vertx-grpc/java/#vertx-grpc-protoc-plugin).
186-
187306
## Multiple Output Directories
188307

189308
If you need to generate code to different directories based on the target language:
@@ -213,95 +332,12 @@ If you need to generate code to different directories based on the target langua
213332
<goal>generate</goal>
214333
</goals>
215334
<configuration>
216-
<protocVersion>${protobuf.version}</protocVersion>
217335
<javaEnabled>false</javaEnabled>
218-
<pythonEnabled>true</pythonEnabled>
219336
<outputDirectory>${project.basedir}/target/python</outputDirectory>
337+
<protocVersion>${protobuf.version}</protocVersion>
338+
<pythonEnabled>true</pythonEnabled>
220339
</configuration>
221340
</execution>
222341
</executions>
223342
</plugin>
224343
```
225-
226-
## Scala
227-
228-
Scala support for Protobuf and gRPC can be enabled using the ScalaPB Protoc plugin.
229-
230-
This is distributed as an OS-dependent binary within a ZIP archive on their GitHub releases.
231-
232-
A suitable Maven plugin for providing Scala compilation is also required.
233-
234-
```xml
235-
<plugins>
236-
<plugin>
237-
<groupId>io.github.ascopes</groupId>
238-
<artifactId>protobuf-maven-plugin</artifactId>
239-
240-
<configuration>
241-
<javaEnabled>false</javaEnabled>
242-
243-
<binaryUrlPlugins>
244-
<binaryUrlPlugin>
245-
<url>zip:https://github.com/scalapb/ScalaPB/releases/download/v${scalapb.version}/protoc-gen-scala-${scalapb.version}-linux-x86_64.zip!/protoc-gen-scala</url>
246-
<options>flat_package,grpc,scala3_sources</options>
247-
</binaryUrlPlugin>
248-
</binaryUrlPlugins>
249-
</configuration>
250-
251-
<executions>
252-
<execution>
253-
<goals>
254-
<goal>generate</goal>
255-
</goals>
256-
</execution>
257-
</executions>
258-
</plugin>
259-
260-
261-
<plugin>
262-
<groupId>net.alchim31.maven</groupId>
263-
<artifactId>scala-maven-plugin</artifactId>
264-
265-
<configuration>
266-
<failOnMultipleScalaVersions>true</failOnMultipleScalaVersions>
267-
</configuration>
268-
</plugin>
269-
</plugins>
270-
```
271-
272-
An example service handler may look like the following:
273-
274-
`src/main/protobuf/helloworld.proto`:
275-
```protobuf
276-
syntax = "proto3";
277-
278-
option java_multiple_files = true;
279-
option java_package = "org.example.helloworld";
280-
281-
package org.example.helloworld;
282-
283-
message GreetingRequest {
284-
string name = 1;
285-
}
286-
287-
message GreetingResponse {
288-
string text = 1;
289-
}
290-
291-
service GreetingService {
292-
rpc Greet(GreetingRequest) returns (GreetingResponse);
293-
}
294-
```
295-
296-
`src/main/scala/org/example/helloworld/HelloWorld.scala`:
297-
```scala
298-
package org.example.helloworld
299-
300-
import scala.concurrent.Future
301-
302-
class GreetingServiceImpl extends GreetingServiceGrpc.GreetingService:
303-
override def greet(request: GreetingRequest) =
304-
val response = GreetingResponse(text = "Hello, " + request.name + "!")
305-
Future.successful(response)
306-
end GreetingServiceImpl
307-
```

0 commit comments

Comments
 (0)