gRPCtoJAXRS_archetype

The RESTEasy grpc provider supports exposing JAX-RS services to gRPC clients. See the README.md file there for a discussion of the various mechanisms and classes involved.

There are a lot of pieces to create, and this maven archetype includes a pom.xml which incorporates the steps necessary to create them.

Using the archetype

gRPCtoJAXRS_archetype takes the GAV of an existing JAX-RS project, called the target project, and creates a new project which can generate a WAR with all of the pieces needed to interface between a gRPC client and the existing project. We will refer to the generated project as the corresponding gRPCtoJAXRS project.

To create a gRPCtoJAXRS project from an existing project, the archetype needs several pieces of information:

1. the GAV of the original project

2. the intended GAV of the gRPCtoJAXRS project

3. the package of the target JAX-RS resource class

4. root-class, the simple name of the target JAX-RS resource class [Note "-" rather than ".".]

For example,

    mvn archetype:generate \
      -DarchetypeGroupId=org.jboss.resteasy -DarchetypeArtifactId=gRPCtoJAXRS-archetype -DarchetypeVersion=0.0.1-SNAPSHOT \
      -DgroupId=jaxrs.example -DartifactId=jaxrs.example -Dversion=0.0.1-SNAPSHOT \
      -Dpackage=org.jboss.resteasy.example -Droot-class=CC1

See jaxrs.example:jaxrs.example:0.0.1-SNAPSHOT for the sample code mentioned here.

The result is a new gRPCtoJAXRS maven project named by its artifactId. Its initial contents are

1. pom.xml

2. src/main/webapp/WEB-INF/web.xml

3. a JAX-RS resource class named <root.class>_Server

4. a template for a JAX-RS test client named <root.class>_Client

Building the gRPCtoJAXRS project downloads the src/main/java contents of the target project, and builds all of the generated classes described in RESTEasy grpc provider.

The following parameters are needed:

1. resteasy.version

2. servlet.name [elaborate here]

3. root.class

For example,

    mvn -Dresteasy.version=4.7.0.Final -Dservlet.name=org.jboss.resteasy.example.ExampleApp -Droot.class=CC1 clean install

The gRPCtoJAXRS project will be populated as follows

1. src/main/java will be copied from the target project

2. src/main/proto will hold the <root.class>.proto file

3. src/main/webapp/WEB-INF will hold web.xml

4. src/test/java will hold test.grpc.<root.class>_Client.java and test.grpc.<root.class>_Server.java

5. target/generated-sources/protobuf/java will hold <root.class>_proto.java, compiled from <root.class>.proto

6. target/generated-sources/protobuf/grpc-java will hold the following generated classes:

   A. <root.class>ServiceGrpc.java (generated by the proto compiler gRPC plugin)

   B. <root.class>ServiceGrpcImpl.java (generated by org.jboss.resteasy.grpc.JaxrsImplBaseExtender)

   C. <root.class>_JavabufTranslator.java (generated by org.jboss.resteasy.plugins.protobuf.JavabufTranslatorGenerator)

   D. <root.class>MessageBodyReaderWriter.java (generated by org.jboss.resteasy.plugins.protobuf.ReaderWriterGenerator)

The principal output is a WAR in the target directory which can be deployed to WildFly.

Using the Web Archive

The class ${root-class}_Server is a JAX-RS resource that can start up a gRPC server by calling

    http://localhost:8080/jaxrs.example.grpc-0.0.1-SNAPSHOT/root/grpcserver/start

Once the gRPC server is started, the JAX-RS resources in the target project can be invoked by an appropriate gRPC client. The class ${root-class}_Client is a JUnit test class with a number of tests.

1. There are some hard coded tests like testInt() and testInteger() that verify that basic types are handled correctly.

2. There is also a template method, commented out, that indicates how to test the specific methods of the JAX-RS resources. The appropriate javabuf objects need to be created and passed to the appropriate gRPC client stub method. Then the result needs to be verified.

To Do

gRPCtoJAXRS_archetype is a work in progress. More needs to be done, including:

1. Additional primitive and wrapper tests

2. More testing.

3. Probably lots of other stuff.