New gRPC SE example that implements a random number generator service…

…. Example created for blog article.

examples/webserver/grpc-random/README.md

@@ -0,0 +1,21 @@
+# Helidon gRPC SE Randome Example
+
+
+This example shows a simple _Random_ service written with the Helidon gRPC SE 
+API. See `RandomService` for the service implementation and `RandomServiceTest`
+for how to use the Helidon's `WebClient` to access the service. .
+
+The gRPC service definition is found in the `random.proto` file which is compiled 
+using `protoc` at build time. 
+
+## Build and run tests
+
+```shell
+mvn package
+```
+
+## Run the app
+
+```shell
+java -jar target/helidon-examples-webserver-grpc-random.jar
+```

examples/webserver/grpc-random/pom.xml

@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright (c) 2024 Oracle and/or its affiliates.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.helidon.applications</groupId>
+        <artifactId>helidon-se</artifactId>
+        <version>4.2.0-SNAPSHOT</version>
+        <relativePath/>
+    </parent>
+
+    <groupId>io.helidon.examples.webserver</groupId>
+    <artifactId>helidon-examples-webserver-grpc-random</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+    <name>Helidon Examples WebServer gRPC Random</name>
+
+    <description>
+        Application demonstrates the use of gRPC with a service that returns random numbers.
+    </description>
+
+    <properties>
+        <mainClass>io.helidon.examples.webserver.grpc.random.Main</mainClass>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.config</groupId>
+            <artifactId>helidon-config-yaml</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.grpc</groupId>
+            <artifactId>helidon-grpc-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.webserver</groupId>
+            <artifactId>helidon-webserver-grpc</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.logging</groupId>
+            <artifactId>helidon-logging-jul</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.google.protobuf</groupId>
+            <artifactId>protobuf-java</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.webclient</groupId>
+            <artifactId>helidon-webclient-grpc</artifactId>
+        </dependency>
+        <dependency>
+            <!-- required for @Generated -->
+            <groupId>javax.annotation</groupId>
+            <artifactId>javax.annotation-api</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.webserver.testing.junit5</groupId>
+            <artifactId>helidon-webserver-testing-junit5</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.hamcrest</groupId>
+            <artifactId>hamcrest-all</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.logging</groupId>
+            <artifactId>helidon-logging-jul</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <extensions>
+            <extension>
+                <groupId>kr.motd.maven</groupId>
+                <artifactId>os-maven-plugin</artifactId>
+                <version>${version.plugin.os}</version>
+            </extension>
+        </extensions>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-dependency-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>copy-libs</id>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.xolstice.maven.plugins</groupId>
+                <artifactId>protobuf-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>compile</goal>
+                            <goal>compile-custom</goal>
+                        </goals>
+                    </execution>
+                </executions>
+                <configuration>
+                    <protocArtifact>com.google.protobuf:protoc:${version.lib.google-protobuf}:exe:${os.detected.classifier}</protocArtifact>
+                    <pluginId>grpc-java</pluginId>
+                    <pluginArtifact>io.grpc:protoc-gen-grpc-java:${version.lib.grpc}:exe:${os.detected.classifier}
+                    </pluginArtifact>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

examples/webserver/grpc-random/src/main/java/io/helidon/examples/webserver/grpc/random/Main.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2024 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.helidon.examples.webserver.grpc.random;
+
+import io.helidon.config.Config;
+import io.helidon.logging.common.LogConfig;
+import io.helidon.webserver.WebServer;
+import io.helidon.webserver.grpc.GrpcRouting;
+
+class Main {
+
+    private Main() {
+    }
+
+    /**
+     * Main method.
+     *
+     * @param args ignored
+     */
+    public static void main(String[] args) {
+        LogConfig.configureRuntime();
+
+        // initialize global config from default configuration
+        Config config = Config.create();
+        Config.global(config);
+        Config serverConfig = config.get("server");
+
+        // start server and register gRPC routing and health check
+        WebServer.builder()
+                .config(serverConfig)
+                .addRouting(GrpcRouting.builder().service(new RandomService()))
+                .build()
+                .start();
+    }
+}

examples/webserver/grpc-random/src/main/java/io/helidon/examples/webserver/grpc/random/RandomService.java

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) 2024 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.helidon.examples.webserver.grpc.random;
+
+import java.util.Random;
+
+import io.helidon.examples.webserver.grpc.random.Random.ParamMessage;
+import io.helidon.examples.webserver.grpc.random.Random.RandomMessage;
+import io.helidon.webserver.grpc.GrpcService;
+
+import com.google.protobuf.Descriptors;
+import io.grpc.stub.StreamObserver;
+
+class RandomService implements GrpcService {
+
+    private final Random random = new Random();
+
+    @Override
+    public Descriptors.FileDescriptor proto() {
+        return io.helidon.examples.webserver.grpc.random.Random.getDescriptor();
+    }
+
+    @Override
+    public void update(Routing router) {
+        router.unary("RandomSingle", this::randomSingle)
+                .bidi("RandomMany", this::randomMany);
+    }
+
+    private void randomSingle(ParamMessage request, StreamObserver<RandomMessage> response) {
+        int bound = request.getNumber();
+        response.onNext(newRandomMessage(random.nextInt(bound)));
+        response.onCompleted();
+    }
+
+    private StreamObserver<ParamMessage> randomMany(StreamObserver<RandomMessage> response) {
+        return new StreamObserver<>() {
+
+            private int bound = Integer.MIN_VALUE;
+            private int count = Integer.MIN_VALUE;
+
+            @Override
+            public void onNext(ParamMessage paramMessage) {
+                // collect bound and count, in that order
+                if (bound == Integer.MIN_VALUE) {
+                    bound = paramMessage.getNumber();
+                } else if (count == Integer.MIN_VALUE) {
+                    count = paramMessage.getNumber();
+                } else {
+                    onError(new IllegalStateException("Received extra input params"));
+                }
+            }
+
+            @Override
+            public void onError(Throwable throwable) {
+                response.onError(throwable);
+            }
+
+            @Override
+            public void onCompleted() {
+                // verify input params received
+                if (bound == Integer.MIN_VALUE || count == Integer.MIN_VALUE) {
+                    onError(new IllegalStateException("Did not receive all input params"));
+                }
+
+                // send stream of random numbers
+                for (int i = 0; i < count; i++) {
+                    response.onNext(newRandomMessage(random.nextInt(bound)));
+                }
+                response.onCompleted();
+            }
+        };
+    }
+
+    private static RandomMessage newRandomMessage(int random) {
+        return RandomMessage.newBuilder().setNumber(random).build();
+    }
+}

examples/webserver/grpc-random/src/main/java/io/helidon/examples/webserver/grpc/random/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright (c) 2024 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Example of gRPC in webserver.
+ */
+package io.helidon.examples.webserver.grpc.random;

examples/webserver/grpc-random/src/main/proto/random.proto

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2024 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+syntax = "proto3";
+option java_package = "io.helidon.examples.webserver.grpc.random";
+
+service RandomService {
+  rpc RandomSingle (ParamMessage) returns (RandomMessage) {}
+  rpc RandomMany (stream ParamMessage) returns (stream RandomMessage) {}
+}
+
+message ParamMessage {
+  int32 number = 1;
+}
+
+message RandomMessage {
+  int32 number = 1;
+}

examples/webserver/grpc-random/src/main/resources/application.yaml

@@ -0,0 +1,30 @@
+#
+# Copyright (c) 2024 Oracle and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+server:
+  port: 8080
+  tls:
+    trust:
+      keystore:
+        passphrase: "password"
+        trust-store: true
+        resource:
+          resource-path: "server.p12"
+    private-key:
+      keystore:
+        passphrase: "password"
+        resource:
+          resource-path: "server.p12"