Add README files to explain how to run the grpc-web java in-process p…

…roxy.

This is not final yet. Just want to get some README's in place so we can review the whole code + READMEs as a whole before saying this is officially ready for some beta customer.

README.md

@@ -10,6 +10,9 @@ In the future, we expect gRPC-web to be supported in language-specific web
 frameworks for languages such as Python, Java, and Node. For details, see the
 [roadmap](doc/roadmap.md).
 
+Java gRPC-web in-process proxy implementation is
+in beta stage. For details, see [details](src/connector/README.md).
+
 ## Quick Start
 
 Eager to get started? Try the [Hello World example][]. From this example, you'll

net/grpc/gateway/examples/grpc-web-java/greeter-service/README.md

@@ -0,0 +1,14 @@
+This dir contains code to exercise the [java grpc-web in-process
+proxy](../../../../../../src/connector) with a simple 
+[service](src/main/proto/greeter.proto).
+
+To run this example, run this command
+```
+mvn test
+```
+
+This example does the following:
+1. Implement a [service](src/main/proto/greeter.proto)
+2. Start the service on a **grpc-port**. Service is now ready to accept grpc requests on **grpc-port**
+3. Start the grpc-web in-process proxy on another port **grpc-web-port**
+4. Service is now ready to accept grpc-web requests on the **grpc-web-port**

net/grpc/gateway/examples/grpc-web-java/interop-test-service/README.md

@@ -0,0 +1,6 @@
+This dir contains code to run 
+[interop-tests](../../../../../../test/interop/README.md)
+on the [java grpc-web in-process proxy](../../../../../../src/connector)
+
+See [details](../../../../../../src/connector/README.md) 
+on how to run the interop-tests using code in this dir.

src/connector/README.md

@@ -1,21 +1,65 @@
-grpc-web Java in-process Proxy code.
-Outline of the code at this point.
+Java gRPC-web in-process proxy
+==============================
 
-This is Work-in-Progress.
+### Background & Motivation
+This project enables gRPC-web support in a Java Service that currently
+serves only gRPC clients but not equipped to handle gRPC-web clients.
+This project provides a java jar file that can be added to the Java Service
+when it is deployed. There are minimal changes to be made to the Java Service
+before linking the jar file provided by this project and re-deploying the
+Java Service.
 
-Current state of the code: All interop-tests work
- (interop-tests are listed here
-   https://github.com/stanley-cheung/grpc-web/blob/add-interop/test/interop/README.md
+### How to use it in your Java Service
+Here are the steps needed to use this project to add gRPC-web client serving
+capability to your existing Java Service (that only serves gRPC clients but not
+gRPC-web clients)
 
- To run the interop-tests with this code, do the following
- 1. mvn package. This brings ip a Test Service + grpc-web in-process proxy 
- 2. Run the client as documented here:
-    https://github.com/stanley-cheung/grpc-web/blob/add-interop/test/interop/README.md#run-the-grpc-web-browser-client
+Examine the code in the following
+[dir](../../net/grpc/gateway/examples/grpc-web-java/greeter-service)
 
-3. And then Open up the browser and go to http://localhost:8081/index.html
-4. Open the browser to go to Console.
-5. It should show the following:
-      EmptyUnary: passed
-      LargeUnary: passed
-      etc for all tests
+- A Java Service specified by
+[this proto](../../net/grpc/gateway/examples/grpc-web-java/greeter-service/src/main/proto/greeter.proto) is implemented
+[here](../../net/grpc/gateway/examples/grpc-web-java/greeter-service/src/main/java/grpcweb/examples/greeter/GreeterService.java)
 
+- [This](../../net/grpc/gateway/examples/grpc-web-java/greeter-service/src/main/java/grpcweb/examples/greeter/StartServiceAndGrpcwebProxy.java)
+code starts the above gRPC-Service and a gRPC-web in-process proxy
+provided by this project.
+
+- Since you will already have implemented code to start your gRPC-Service,
+add code to start gRPC-web in-process proxy, as demonstrated by
+the above.
+
+- The only critical piece of info needed by the gRPC-web in-process proxy is the port
+to listen on, for gRPC-web requests.
+[This file](../../net/grpc/gateway/examples/grpc-web-java/greeter-service/src/main/java/grpcweb/examples/greeter/Util.java)
+ externalizes grpc-web port# thru a static member.
+
+Rebuild your Service with the Java jar file provided by this project and re-deploy.
+
+Voila! Your service can now service gRPC and gRPC-web clients!
+
+### How to run the [Interop tests](https://github.com/grpc/grpc-web/blob/master/test/interop/README.md) with this code
+
+- Install "grpc-web java" jar locally
+```shell script
+$ cd src/connector
+$ mvn install
+```
+- Bring up a Test Service with this code as "grpc-web in-process proxy"
+```shell script
+       $ cd net/grpc/gateway/examples/grpc-web-java/interop-test-service
+       $ mvn package
+       $ java -jar target/interop-test-0.1-jar-with-dependencies.jar
+```
+- Run the interop tests from browser
+```shell script
+$ cd test/interop
+$ docker-compose up interop-client
+```
+Open browser at http://localhost:8081/index.html and
+check the console for messages like the following:
+```shell script
+EmptyUnary: passed
+LargeUnary: passed
+etc..
+```