servlet: Implement gRPC server as a Servlet

RELEASING.md

@@ -47,6 +47,7 @@ $ VERSION_FILES=(
   examples/example-gauth/pom.xml
   examples/example-kotlin/build.gradle
   examples/example-kotlin/android/helloworld/app/build.gradle
+  examples/example-servlet/build.gradle
   examples/example-tls/build.gradle
   examples/example-tls/pom.xml
   )

core/src/main/java/io/grpc/internal/AbstractServerImplBuilder.java

@@ -217,7 +217,7 @@ protected void setTracingEnabled(boolean value) {
   }
 
   @Override
-  public final Server build() {
+  public Server build() {
     ServerImpl server = new ServerImpl(
         this,
         buildTransportServer(getTracerFactories()),

examples/example-servlet/build.gradle

@@ -0,0 +1,47 @@
+plugins {
+    // ASSUMES GRADLE 2.12 OR HIGHER. Use plugin version 0.7.5 with earlier gradle versions
+    id 'com.google.protobuf' version '0.8.5'
+    // Generate IntelliJ IDEA's .idea & .iml project files
+    id 'idea'
+    id 'war'
+}
+
+repositories {
+    maven { // The google mirror is less flaky than mavenCentral()
+        url "https://maven-central.storage-download.googleapis.com/repos/central/data/" }
+    mavenLocal()
+}
+
+sourceCompatibility = 1.8
+targetCompatibility = 1.8
+
+def grpcVersion = '1.19.0-SNAPSHOT' // CURRENT_GRPC_VERSION
+def protocVersion = '3.5.1-1'
+
+dependencies {
+    implementation "io.grpc:grpc-protobuf:${grpcVersion}",
+            "io.grpc:grpc-servlet:${grpcVersion}",
+            "io.grpc:grpc-stub:${grpcVersion}"
+
+
+    providedCompile "javax.annotation:javax.annotation-api:1.2",
+            "javax.servlet:javax.servlet-api:4.0.1"
+}
+
+protobuf {
+    protoc { artifact = "com.google.protobuf:protoc:${protocVersion}" }
+    plugins { grpc { artifact = "io.grpc:protoc-gen-grpc-java:1.13.1" } }
+    generateProtoTasks {
+        all()*.plugins { grpc {} }
+    }
+}
+
+// Inform IDEs like IntelliJ IDEA, Eclipse or NetBeans about the generated code.
+sourceSets {
+    main {
+        java {
+            srcDirs 'build/generated/source/proto/main/grpc'
+            srcDirs 'build/generated/source/proto/main/java'
+        }
+    }
+}

examples/example-servlet/settings.gradle

@@ -0,0 +1,8 @@
+pluginManagement {
+    repositories {
+        maven { // The google mirror is less flaky than mavenCentral()
+            url "https://maven-central.storage-download.googleapis.com/repos/central/data/"
+        }
+        gradlePluginPortal()
+    }
+}

examples/example-servlet/src/main/java/io/grpc/servlet/examples/helloworld/HelloWorldServlet.java

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2018 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.servlet.examples.helloworld;
+
+import io.grpc.stub.StreamObserver;
+import io.grpc.examples.helloworld.GreeterGrpc;
+import io.grpc.examples.helloworld.HelloReply;
+import io.grpc.examples.helloworld.HelloRequest;
+import io.grpc.servlet.ServletAdapter;
+import io.grpc.servlet.ServletServerBuilder;
+import java.io.IOException;
+import java.util.concurrent.Executors;
+import javax.servlet.annotation.WebServlet;
+import javax.servlet.http.HttpServlet;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+/**
+ * A servlet that hosts a gRPC server over HTTP/2 and shares the resource URI for the normal servlet
+ * clients over HTTP/1.0+.
+ *
+ * <p>For creating a servlet that solely serves gRPC services, do not follow this example, simply
+ * extend or register a {@link io.grpc.servlet.GrpcServlet} instead.
+ */
+@WebServlet(urlPatterns = {"/helloworld.Greeter/SayHello"}, asyncSupported = true)
+public class HelloWorldServlet extends HttpServlet {
+  private static final long serialVersionUID = 1L;
+
+  private final ServletAdapter servletAdapter = ServletAdapter.Factory.create(
+      new ServletServerBuilder().addService(new GreeterImpl()));
+
+  private static final class GreeterImpl extends GreeterGrpc.GreeterImplBase {
+    GreeterImpl() {}
+
+    @Override
+    public void sayHello(HelloRequest req, StreamObserver<HelloReply> responseObserver) {
+      HelloReply reply = HelloReply.newBuilder().setMessage("Hello " + req.getName()).build();
+      responseObserver.onNext(reply);
+      responseObserver.onCompleted();
+    }
+  }
+
+  @Override
+  protected void doGet(HttpServletRequest request, HttpServletResponse response)
+      throws IOException {
+    response.setContentType("text/html");
+    response.getWriter().println("<p>Hello World!</p>");
+  }
+
+  @Override
+  protected void doPost(HttpServletRequest request, HttpServletResponse response)
+      throws IOException {
+    if (ServletAdapter.isGrpc(request)) {
+      servletAdapter.doPost(request, response);
+    } else {
+      response.setContentType("text/html");
+      response.getWriter().println("<p>Hello non-gRPC client!</p>");
+    }
+  }
+
+  @Override
+  public void destroy() {
+    servletAdapter.destroy();
+    super.destroy();
+  }
+}

examples/example-servlet/src/main/proto/helloworld/helloworld.proto

@@ -0,0 +1,37 @@
+// 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.
+syntax = "proto3";
+
+option java_multiple_files = true;
+option java_package = "io.grpc.examples.helloworld";
+option java_outer_classname = "HelloWorldProto";
+option objc_class_prefix = "HLW";
+
+package helloworld;
+
+// The greeting service definition.
+service Greeter {
+  // Sends a greeting
+  rpc SayHello (HelloRequest) returns (HelloReply) {}
+}
+
+// The request message containing the user's name.
+message HelloRequest {
+  string name = 1;
+}
+
+// The response message containing the greetings
+message HelloReply {
+  string message = 1;
+}

examples/example-servlet/src/main/webapp/WEB-INF/glassfish-web.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Need this file for deployment to GlassFish -->
+<!DOCTYPE glassfish-web-app PUBLIC "-//GlassFish.org//DTD GlassFish Application Server 3.1 Servlet 3.0//EN" "http://glassfish.org/dtds/glassfish-web-app_3_0-1.dtd">
+<glassfish-web-app error-url="">
+   <class-loader delegate="false"/>
+</glassfish-web-app>

examples/example-servlet/src/main/webapp/WEB-INF/jboss-web.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Need this file for deployment to WildFly  -->
+<jboss-web xmlns="http://www.jboss.com/xml/ns/javaee"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="
+  http://www.jboss.com/xml/ns/javaee
+  http://www.jboss.org/j2ee/schema/jboss-web_5_1.xsd">
+  <context-root>/</context-root>
+</jboss-web>

interop-testing/src/main/java/io/grpc/testing/integration/AbstractInteropTest.java

@@ -200,10 +200,8 @@ public ServerStreamTracer newServerStreamTracer(String fullMethodName, Metadata
 
   protected static final Empty EMPTY = Empty.getDefaultInstance();
 
-  private void startServer() {
-    AbstractServerImplBuilder<?> builder = getServerBuilder();
+  private void configBuilder(@Nullable AbstractServerImplBuilder<?> builder) {
     if (builder == null) {
-      server = null;
       return;
     }
     testServiceExecutor = Executors.newScheduledThreadPool(2);
@@ -229,6 +227,13 @@ private void startServer() {
             serverStatsRecorder,
             GrpcUtil.STOPWATCH_SUPPLIER,
             true, true, true, false /* real-time metrics */));
+  }
+
+  protected void startServer(@Nullable AbstractServerImplBuilder<?> builder) {
+    if (builder == null) {
+      server = null;
+      return;
+    }
     try {
       server = builder.build().start();
     } catch (IOException ex) {
@@ -280,7 +285,9 @@ public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
    */
   @Before
   public void setUp() {
-    startServer();
+    AbstractServerImplBuilder<?> builder = getServerBuilder();
+    configBuilder(builder);
+    startServer(builder);
     channel = createChannel();
 
     blockingStub =

netty/src/test/java/io/grpc/netty/InternalNettyTestAccessor.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2018 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.netty;
+
+import com.google.common.annotations.VisibleForTesting;
+import io.grpc.internal.ClientTransportFactory;
+import io.grpc.internal.TransportTracer;
+import javax.annotation.CheckReturnValue;
+
+/**
+ * Internal Accessor for tests.
+ */
+@VisibleForTesting
+public final class InternalNettyTestAccessor {
+  private InternalNettyTestAccessor() {}
+
+  public static void setTransportTracerFactory(
+      NettyChannelBuilder builder, TransportTracer.Factory factory) {
+    builder.setTransportTracerFactory(factory);
+  }
+
+  @CheckReturnValue
+  public static ClientTransportFactory buildTransportFactory(NettyChannelBuilder builder) {
+    return builder.buildTransportFactory();
+  }
+}

servlet/build.gradle

@@ -0,0 +1,22 @@
+description = "gRPC: Servlet"
+sourceCompatibility = 1.8
+targetCompatibility = 1.8
+
+dependencies {
+    compile project(':grpc-core')
+    compileOnly 'javax.servlet:javax.servlet-api:4.0.1',
+            libraries.javax_annotation // java 9, 10 needs it
+
+    testCompile project(':grpc-stub'),
+            project(':grpc-protobuf'),
+            project(':grpc-servlet'),
+            project(':grpc-netty'),
+            project(':grpc-testing'),
+            project(':grpc-auth'),
+            project(':grpc-interop-testing'),
+            project(':grpc-core').sourceSets.test.output,
+            project(':grpc-netty').sourceSets.test.output,
+            libraries.junit,
+            'io.undertow:undertow-servlet:2.0.15.Final',
+            'org.apache.tomcat.embed:tomcat-embed-core:9.0.12'
+}

servlet/src/main/java/io/grpc/servlet/GrpcServlet.java

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2018 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.servlet;
+
+import com.google.common.annotations.VisibleForTesting;
+import io.grpc.BindableService;
+import java.io.IOException;
+import java.util.List;
+import java.util.function.Supplier;
+import javax.servlet.http.HttpServlet;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+/**
+ * A simple servlet backed by a gRPC server. Must set {@code asyncSupported} to true. The {@code
+ * /contextRoot/urlPattern} must match the gRPC services' path, which is
+ * "/full-service-name/short-method-name".
+ *
+ * <p>The API is unstable. The authors would like to know more about the real usecases. Users are
+ * welcome to provide feedback by commenting on
+ * <a href=https://github.com/grpc/grpc-java/issues/5066>the tracking issue</a>.
+ */
+@io.grpc.ExperimentalApi("https://github.com/grpc/grpc-java/issues/5066")
+public class GrpcServlet extends HttpServlet {
+  private static final long serialVersionUID = 1L;
+
+  private final ServletAdapter servletAdapter;
+
+  @VisibleForTesting
+  GrpcServlet(ServletAdapter servletAdapter) {
+    this.servletAdapter = servletAdapter;
+  }
+
+  /**
+   * Instantiate the servlet with the given serverBuilder.
+   */
+  public GrpcServlet(ServletServerBuilder serverBuilder) {
+    this(ServletAdapter.Factory.create(serverBuilder));
+  }
+
+  /**
+   * Instantiate the servlet serving the given list of gRPC services.
+   */
+  public GrpcServlet(List<BindableService> grpcServices) {
+    this(
+        ((Supplier<ServletServerBuilder>)
+                () -> {
+                  ServletServerBuilder serverBuilder = new ServletServerBuilder();
+                  grpcServices.forEach(service -> serverBuilder.addService(service));
+                  return serverBuilder;
+                })
+            .get());
+  }
+
+  @Override
+  protected final void doGet(HttpServletRequest request, HttpServletResponse response)
+      throws IOException {
+    servletAdapter.doGet(request, response);
+  }
+
+  @Override
+  protected final void doPost(HttpServletRequest request, HttpServletResponse response)
+      throws IOException {
+    servletAdapter.doPost(request, response);
+  }
+
+  @Override
+  public void destroy() {
+    servletAdapter.destroy();
+    super.destroy();
+  }
+}