Codelabs for Java Intro and Java Intro Streaming (#5)

Author: larry-safran

codelabs/Getting_Started_with_gRPC_Java/README.md

@@ -0,0 +1,25 @@
+@@ -0,0 +1,24 @@
+# Getting Started with gRPC-Java
+
+Get hands-on with gRPC for Java in this interactive codelab! <!-- TODO(larry-safran): Insert link once codelab is published. -->
+
+Perfect for Java developers new to gRPC, those seeking a refresher, or anyone building distributed systems. No prior gRPC experience needed! 
+
+#### Build a complete gRPC service from scratch, learning: 
+- Protocol Buffers (protobuf): Define service contracts & data. 
+- gRPC Code Generation: Auto-generate Java code. 
+- Client/Server Communication: Implement seamless interactions. 
+
+#### You'll gain: 
+- A working gRPC service in Java. 
+- Hands-on experience with Protocol Buffers and code generation. 
+- Skills to design, build, & test gRPC clients and servers. 
+- A strong foundation in gRPC for real-world projects.
+
+## How to use this directory
+
+- [start_here](start_here/) directory serves as a starting point for the
+codelab. 
+- [complete](complete/) directory showcases the finished code, giving you a peak
+of how the final implementation should look like.
+

codelabs/Getting_Started_with_gRPC_Java/complete/src/main/java/io/grpc/examples/routeguide/RouteGuideClient.java

@@ -0,0 +1,130 @@
+/*
+ * Copyright 2024 The gRPC Authors
+ *
+ * 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.grpc.examples.routeguide;
+
+import com.google.common.annotations.VisibleForTesting;
+import com.google.protobuf.Message;
+import io.grpc.Channel;
+import io.grpc.Grpc;
+import io.grpc.InsecureChannelCredentials;
+import io.grpc.ManagedChannel;
+import io.grpc.Status;
+import io.grpc.StatusRuntimeException;
+import io.grpc.examples.routeguide.RouteGuideGrpc.RouteGuideBlockingStub;
+import io.grpc.examples.routeguide.RouteGuideGrpc.RouteGuideStub;
+import io.grpc.stub.StreamObserver;
+import java.io.IOException;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Random;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+/**
+ * Sample client code that makes gRPC calls to the server.
+ */
+public class RouteGuideClient {
+  private static final Logger logger = Logger.getLogger(RouteGuideClient.class.getName());
+
+  private final RouteGuideBlockingStub blockingStub;
+
+  private Random random = new Random();
+  private TestHelper testHelper;
+
+  /** Construct client for accessing RouteGuide server using the existing channel. */
+  public RouteGuideClient(Channel channel) {
+    blockingStub = RouteGuideGrpc.newBlockingStub(channel);
+  }
+
+  /**
+   * Blocking unary call example.  Calls getFeature and prints the response.
+   */
+  public void getFeature(int lat, int lon) {
+    info("*** GetFeature: lat={0} lon={1}", lat, lon);
+
+    Point request = Point.newBuilder().setLatitude(lat).setLongitude(lon).build();
+
+    Feature feature;
+    try {
+      feature = blockingStub.getFeature(request);
+      if (testHelper != null) {
+        testHelper.onMessage(feature);
+      }
+    } catch (StatusRuntimeException e) {
+      warning("RPC failed: {0}", e.getStatus());
+      if (testHelper != null) {
+        testHelper.onRpcError(e);
+      }
+      return;
+    }
+    if (RouteGuideUtil.exists(feature)) {
+      info("Found feature called \"{0}\" at {1}, {2}",
+          feature.getName(),
+          RouteGuideUtil.getLatitude(feature.getLocation()),
+          RouteGuideUtil.getLongitude(feature.getLocation()));
+    } else {
+      info("Found no feature at {0}, {1}",
+          RouteGuideUtil.getLatitude(feature.getLocation()),
+          RouteGuideUtil.getLongitude(feature.getLocation()));
+    }
+  }
+
+  /** Issues several different requests and then exits. */
+  public static void main(String[] args) throws InterruptedException {
+    String target = "localhost:8980";
+    if (args.length > 0) {
+      if ("--help".equals(args[0])) {
+        System.err.println("Usage: [target]");
+        System.err.println("");
+        System.err.println("  target  The server to connect to. Defaults to " + target);
+        System.exit(1);
+      }
+      target = args[0];
+    }
+
+    List<Feature> features;
+    try {
+      features = RouteGuideUtil.parseFeatures(RouteGuideUtil.getDefaultFeaturesFile());
+    } catch (IOException ex) {
+      ex.printStackTrace();
+      return;
+    }
+
+    ManagedChannel channel = Grpc.newChannelBuilder(target, InsecureChannelCredentials.create())
+        .build();
+    try {
+      RouteGuideClient client = new RouteGuideClient(channel);
+      // Looking for a valid feature
+      client.getFeature(409146138, -746188906);
+
+      // Feature missing.
+      client.getFeature(0, 0);
+    } finally {
+      channel.shutdownNow().awaitTermination(5, TimeUnit.SECONDS);
+    }
+  }
+
+  private void info(String msg, Object... params) {
+    logger.log(Level.INFO, msg, params);
+  }
+
+  private void warning(String msg, Object... params) {
+    logger.log(Level.WARNING, msg, params);
+  }
+}

codelabs/Getting_Started_with_gRPC_Java/complete/src/main/java/io/grpc/examples/routeguide/RouteGuideServer.java

@@ -0,0 +1,158 @@
+/*
+ * Copyright 2024 The gRPC Authors
+ *
+ * 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.grpc.examples.routeguide;
+
+import static java.lang.Math.atan2;
+import static java.lang.Math.cos;
+import static java.lang.Math.max;
+import static java.lang.Math.min;
+import static java.lang.Math.sin;
+import static java.lang.Math.sqrt;
+import static java.lang.Math.toRadians;
+import static java.util.concurrent.TimeUnit.NANOSECONDS;
+
+import io.grpc.Grpc;
+import io.grpc.InsecureServerCredentials;
+import io.grpc.Server;
+import io.grpc.ServerBuilder;
+import io.grpc.stub.StreamObserver;
+import java.io.IOException;
+import java.net.URL;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
+import java.util.concurrent.TimeUnit;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+/**
+ * A sample gRPC server that serve the RouteGuide (see route_guide.proto) service.
+ */
+public class RouteGuideServer {
+  private static final Logger logger = Logger.getLogger(RouteGuideServer.class.getName());
+
+  private final int port;
+  private final Server server;
+
+  public RouteGuideServer(int port) throws IOException {
+    this(port, RouteGuideUtil.getDefaultFeaturesFile());
+  }
+
+  /** Create a RouteGuide server listening on {@code port} using {@code featureFile} database. */
+  public RouteGuideServer(int port, URL featureFile) throws IOException {
+    this(Grpc.newServerBuilderForPort(port, InsecureServerCredentials.create()),
+        port, RouteGuideUtil.parseFeatures(featureFile));
+  }
+
+  /** Create a RouteGuide server using serverBuilder as a base and features as data. */
+  public RouteGuideServer(ServerBuilder<?> serverBuilder, int port, Collection<Feature> features) {
+    this.port = port;
+    server = serverBuilder.addService(new RouteGuideService(features))
+        .build();
+  }
+
+  /** Start serving requests. */
+  public void start() throws IOException {
+    server.start();
+    logger.info("Server started, listening on " + port);
+    Runtime.getRuntime().addShutdownHook(new Thread() {
+      @Override
+      public void run() {
+        // Use stderr here since the logger may have been reset by its JVM shutdown hook.
+        System.err.println("*** shutting down gRPC server since JVM is shutting down");
+        try {
+          RouteGuideServer.this.stop();
+        } catch (InterruptedException e) {
+          e.printStackTrace(System.err);
+        }
+        System.err.println("*** server shut down");
+      }
+    });
+  }
+
+  /** Stop serving requests and shutdown resources. */
+  public void stop() throws InterruptedException {
+    if (server != null) {
+      server.shutdown().awaitTermination(30, TimeUnit.SECONDS);
+    }
+  }
+
+  /**
+   * Await termination on the main thread since the grpc library uses daemon threads.
+   */
+  private void blockUntilShutdown() throws InterruptedException {
+    if (server != null) {
+      server.awaitTermination();
+    }
+  }
+
+  /**
+   * Main method.  This comment makes the linter happy.
+   */
+  public static void main(String[] args) throws Exception {
+    RouteGuideServer server = new RouteGuideServer(8980);
+    server.start();
+    server.blockUntilShutdown();
+  }
+
+  /**
+   * Our implementation of RouteGuide service.
+   *
+   * <p>See route_guide.proto for details of the methods.
+   */
+  private static class RouteGuideService extends RouteGuideGrpc.RouteGuideImplBase {
+    private final Collection<Feature> features;
+
+    RouteGuideService(Collection<Feature> features) {
+      this.features = features;
+    }
+
+    /**
+     * Gets the {@link Feature} at the requested {@link Point}. If no feature at that location
+     * exists, an unnamed feature is returned at the provided location.
+     *
+     * @param request the requested location for the feature.
+     * @param responseObserver the observer that will receive the feature at the requested point.
+     */
+    @Override
+    public void getFeature(Point request, StreamObserver<Feature> responseObserver) {
+      responseObserver.onNext(checkFeature(request));
+      responseObserver.onCompleted();
+    }
+
+    /**
+     * Gets the feature at the given point.
+     *
+     * @param location the location to check.
+     * @return The feature object at the point. Note that an empty name indicates no feature.
+     */
+    private Feature checkFeature(Point location) {
+      for (Feature feature : features) {
+        if (feature.getLocation().getLatitude() == location.getLatitude()
+            && feature.getLocation().getLongitude() == location.getLongitude()) {
+          return feature;
+        }
+      }
+
+      // No feature was found, return an unnamed feature.
+      return Feature.newBuilder().setName("").setLocation(location).build();
+    }
+  }
+}

codelabs/Getting_Started_with_gRPC_Java/complete/src/main/java/io/grpc/examples/routeguide/RouteGuideUtil.java

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2015 The gRPC Authors
+ *
+ * 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.grpc.examples.routeguide;
+
+import com.google.protobuf.util.JsonFormat;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.io.Reader;
+import java.net.URL;
+import java.nio.charset.Charset;
+import java.util.List;
+
+/**
+ * Common utilities for the RouteGuide demo.
+ */
+public class RouteGuideUtil {
+  private static final double COORD_FACTOR = 1e7;
+
+  /**
+   * Gets the latitude for the given point.
+   */
+  public static double getLatitude(Point location) {
+    return location.getLatitude() / COORD_FACTOR;
+  }
+
+  /**
+   * Gets the longitude for the given point.
+   */
+  public static double getLongitude(Point location) {
+    return location.getLongitude() / COORD_FACTOR;
+  }
+
+  /**
+   * Gets the default features file from classpath.
+   */
+  public static URL getDefaultFeaturesFile() {
+    return RouteGuideServer.class.getResource("route_guide_db.json");
+  }
+
+  /**
+   * Parses the JSON input file containing the list of features.
+   */
+  public static List<Feature> parseFeatures(URL file) throws IOException {
+    InputStream input = file.openStream();
+    try {
+      Reader reader = new InputStreamReader(input, Charset.forName("UTF-8"));
+      try {
+        FeatureDatabase.Builder database = FeatureDatabase.newBuilder();
+        JsonFormat.parser().merge(reader, database);
+        return database.getFeatureList();
+      } finally {
+        reader.close();
+      }
+    } finally {
+      input.close();
+    }
+  }
+
+  /**
+   * Indicates whether the given feature exists (i.e. has a valid name).
+   */
+  public static boolean exists(Feature feature) {
+    return feature != null && !feature.getName().isEmpty();
+  }
+}