gRPC client API improvements (2.0) (helidon-io#1851)

* gRPC client API improvements
* Rename @GrpcService -> @grpc and @GrpcServiceProxy -> @GrpcProxy
* Rename GrpcClientProxyBuilder to GrpcProxyBuilder
* Leftover @GrpcService -> @grpc changes
* Added breaking change documentation to CHANGELOG.md

Co-authored-by: Tomas Langer <tomas.langer@gmail.com>

Author: aseovic

CHANGELOG.md

@@ -19,6 +19,28 @@ This is the fourth milestone release of Helidon 2.0.
 
 ### Backward incompatible changes
 
+#### gRPC: Renamed several annotations and classes
+
+As part of gRPC API cleanup, we have renamed the following annotations and classes:
+
+| Old Name                 | New Name           |
+| ------------------------ | ------------------ |
+| `@RpcService`            | `@Grpc`            |
+| `@RpcMethod`             | `@GrpcMethod`      |
+| `@GrpcServiceProxy`      | `@GrpcProxy`       |
+| `GrpcClientProxyBuilder` | `GrpcProxyBuilder` |
+
+While in general we prefer not to break backwards compatibility by renaming public API
+classes, we felt that in this case the change was warranted and acceptable, for several reasons:
+
+1. gRPC API was marked experimental in Helidon 1.x
+2. While using gRPC in our own applications, we have realized that the code in some cases
+   does not read as well as it should, and that some class and annotation names should be changed
+   to improve both internal API consistency and readability
+
+We apologize for the inconvenience, but we do feel that the impact of the changes is minimal
+and that the changes will be beneficial in the long run.     
+
 #### Internal `helidon-common-metrics` and Related Classes Removed
 Later releases of Helidon 1.x included the `helidon-common-metrics` component and related
 classes which provided a common interface to ease the transition from MicroProfile 
@@ -41,6 +63,7 @@ Any user code that used these internal classes can use the corresponding support
 | |`InternalMetadataImpl` |
 | |`InternalMetricIDImpl` |
 
+
 ## [2.0.0-M3]
 
 ### Notes

docs/mp/grpc/01_mp_server_side_services.adoc

@@ -54,7 +54,7 @@ For example:
 .Simple gRPC Service
 ----
 @ApplicationScoped
-@io.helidon.microprofile.grpc.core.RpcService
+@io.helidon.microprofile.grpc.core.Grpc
 public class StringService {
 
     @io.helidon.microprofile.grpc.core.Unary
@@ -65,7 +65,7 @@ public class StringService {
 ----
 
 The code above is a simple service with a single unary method that just converts a String to uppercase.
-The important parts in the example are the `@ApplicationScoped`, `@RpcService` and `@Unary` annotations; these,
+The important parts in the example are the `@ApplicationScoped`, `@Grpc` and `@Unary` annotations; these,
 along with other annotations discussed later, allow the gRPC MP APIs to discover, configure and deploy the service.
 
 Of course Helidon gRPC MP does not preclude you from using the Protobuf files approach, traditional gRPC Java services
@@ -77,22 +77,22 @@ annotations.
 [source,java]
 ----
 @ApplicationScoped                                <1>
-@io.helidon.microprofile.grpc.core.RpcService     <2>
+@io.helidon.microprofile.grpc.core.Grpc     <2>
 public class StringService {
 ----
 
 <1> The `ApplicationScoped` annotation is what makes the service implementation a CDI bean and hence discoverable.
-<2> The `RpcService` annotation is what defines the class as a gRPC service so that when the bean is iscovered it is
+<2> The `Grpc` annotation is what defines the class as a gRPC service so that when the bean is discovered it is
 then deployed by the gRPC MP server.
 
 === Service Name
-By default when a class is annotated with `RpcService` the class name will be used as the gRPC service name. So in the example
+By default when a class is annotated with `Grpc` the class name will be used as the gRPC service name. So in the example
 above the service name will be `StringService`. This can be change by supplying a name to the annotation.
 
 [source,java]
 ----
 @ApplicationScoped
-@io.helidon.microprofile.grpc.core.RpcService(name="Strings") <1>
+@io.helidon.microprofile.grpc.core.Grpc(name="Strings") <1>
 public class StringService {
 ----
 <1> in the example above the name of the deployed service will be `Strings`.

docs/mp/grpc/02_mp_clients.adoc

@@ -61,7 +61,7 @@ For example, suppose we have a simple server side service that has a unary metho
 .Simple gRPC Service
 ----
 @ApplicationScoped
-@io.helidon.microprofile.grpc.core.RpcService
+@io.helidon.microprofile.grpc.core.Grpc
 public class StringService {
 
     @io.helidon.microprofile.grpc.core.Unary
@@ -81,7 +81,7 @@ To write a client for the StringService all that is required is an interface.
 .Simple gRPC Service
 ----
 @ApplicationScoped
-@io.helidon.microprofile.grpc.core.RpcService
+@io.helidon.microprofile.grpc.core.Grpc
 public class StringService {
 
     @io.helidon.microprofile.grpc.core.Unary
@@ -100,7 +100,7 @@ unary method signature:
 .Simple gRPC Service
 ----
 @ApplicationScoped
-@io.helidon.microprofile.grpc.core.RpcService
+@io.helidon.microprofile.grpc.core.Grpc
 public class StringService {
 
     @io.helidon.microprofile.grpc.core.Unary
@@ -114,7 +114,7 @@ We could also have made the client asynchronous by using one of the async method
 .Simple gRPC Service
 ----
 @ApplicationScoped
-@io.helidon.microprofile.grpc.core.RpcService
+@io.helidon.microprofile.grpc.core.Grpc
 public class StringService {
 
     @io.helidon.microprofile.grpc.core.Unary
@@ -237,13 +237,13 @@ The field is then annotated so that CDI will inject the client proxy into the fi
 public class Client {
 
     @Inject                                  <1>
-    @GrpcServiceProxy                        <2>
+    @GrpcProxy                        <2>
     @GrpcChannel(name = "test-server")       <3>
     private StringService stringService;
 ----
 
 <1> The `@Inject` annotation tells the CDI to inject the client implementation; the gRPC MP APIs have a bean provider that does this.
-<2> The `@GrpcServiceProxy` annotation is used by the CDI container to match the injection point to the gRPC MP APIs provider
+<2> The `@GrpcProxy` annotation is used by the CDI container to match the injection point to the gRPC MP APIs provider
 <3> The `@GrpcChannel` annotation identifies the gRPC channel to be used by the client. The name used in the annotation refers to
 a channel name in the application configuration.
 

examples/grpc/microprofile/basic-client/src/main/java/io/helidon/microprofile/grpc/example/client/AsyncClient.java

@@ -24,7 +24,7 @@
 import javax.inject.Inject;
 
 import io.helidon.microprofile.grpc.client.GrpcChannel;
-import io.helidon.microprofile.grpc.client.GrpcServiceProxy;
+import io.helidon.microprofile.grpc.client.GrpcProxy;
 
 /**
  * A client to the {@link io.helidon.microprofile.grpc.example.client.AsyncStringService}.
@@ -42,7 +42,7 @@ public class AsyncClient {
      * This proxy will connect to the service using the default {@link io.grpc.Channel}.
      */
     @Inject
-    @GrpcServiceProxy
+    @GrpcProxy
     @GrpcChannel(name = "test-server")
     private AsyncStringService stringService;
 

examples/grpc/microprofile/basic-client/src/main/java/io/helidon/microprofile/grpc/example/client/AsyncStringService.java

@@ -21,7 +21,7 @@
 
 import io.helidon.microprofile.grpc.core.Bidirectional;
 import io.helidon.microprofile.grpc.core.ClientStreaming;
-import io.helidon.microprofile.grpc.core.RpcService;
+import io.helidon.microprofile.grpc.core.Grpc;
 import io.helidon.microprofile.grpc.core.ServerStreaming;
 import io.helidon.microprofile.grpc.core.Unary;
 
@@ -30,10 +30,10 @@
 /**
  * The gRPC StringService.
  * <p>
- * This class has the {@link io.helidon.microprofile.grpc.core.RpcService} annotation
+ * This class has the {@link io.helidon.microprofile.grpc.core.Grpc} annotation
  * so that it will be discovered and loaded using CDI when the MP gRPC server starts.
  */
-@RpcService
+@Grpc
 @SuppressWarnings("CdiManagedBeanInconsistencyInspection")
 public interface AsyncStringService {
 

examples/grpc/microprofile/basic-client/src/main/java/io/helidon/microprofile/grpc/example/client/Client.java

@@ -26,7 +26,7 @@
 import javax.inject.Inject;
 
 import io.helidon.microprofile.grpc.client.GrpcChannel;
-import io.helidon.microprofile.grpc.client.GrpcServiceProxy;
+import io.helidon.microprofile.grpc.client.GrpcProxy;
 
 import io.grpc.stub.StreamObserver;
 
@@ -46,7 +46,7 @@ public class Client {
      * This proxy will connect to the service using the default {@link io.grpc.Channel}.
      */
     @Inject
-    @GrpcServiceProxy
+    @GrpcProxy
     @GrpcChannel(name = "test-server")
     private StringService stringService;
 

examples/grpc/microprofile/basic-client/src/main/java/io/helidon/microprofile/grpc/example/client/StringService.java

@@ -20,7 +20,7 @@
 
 import io.helidon.microprofile.grpc.core.Bidirectional;
 import io.helidon.microprofile.grpc.core.ClientStreaming;
-import io.helidon.microprofile.grpc.core.RpcService;
+import io.helidon.microprofile.grpc.core.Grpc;
 import io.helidon.microprofile.grpc.core.ServerStreaming;
 import io.helidon.microprofile.grpc.core.Unary;
 
@@ -29,10 +29,10 @@
 /**
  * The gRPC StringService.
  * <p>
- * This class has the {@link io.helidon.microprofile.grpc.core.RpcService} annotation
+ * This class has the {@link io.helidon.microprofile.grpc.core.Grpc} annotation
  * so that it will be discovered and loaded using CDI when the MP gRPC server starts.
  */
-@RpcService
+@Grpc
 @SuppressWarnings("CdiManagedBeanInconsistencyInspection")
 public interface StringService {
 

examples/grpc/microprofile/basic-server-implicit/README.md

@@ -7,7 +7,7 @@ It is implicit because in this example you don't write the
 
 The gRPC services to deploy will be discovered by CDI when the gRPC server starts.
 The `StringService` is a POJO service implementation that is annotated with the
-CDI qualifier `RpcService` so that it can be discovered.
+CDI qualifier `Grpc` so that it can be discovered.
 
 Two additional services (`GreetService` and `EchoService`) that are not normally CDI
 managed beans are manually added as CDI managed beans in the `AdditionalServices` class

examples/grpc/microprofile/basic-server-implicit/src/main/java/io/helidon/microprofile/grpc/example/basic/implicit/AsyncStringService.java

@@ -26,7 +26,7 @@
 import io.helidon.grpc.server.CollectingObserver;
 import io.helidon.microprofile.grpc.core.Bidirectional;
 import io.helidon.microprofile.grpc.core.ClientStreaming;
-import io.helidon.microprofile.grpc.core.RpcService;
+import io.helidon.microprofile.grpc.core.Grpc;
 import io.helidon.microprofile.grpc.core.ServerStreaming;
 import io.helidon.microprofile.grpc.core.Unary;
 
@@ -35,11 +35,11 @@
 /**
  * The gRPC StringService implementation that uses async unary methods.
  * <p>
- * This class is a gRPC service annotated with {@link io.helidon.microprofile.grpc.core.RpcService} and
+ * This class is a gRPC service annotated with {@link io.helidon.microprofile.grpc.core.Grpc} and
  * {@link javax.enterprise.context.ApplicationScoped} so that it will be discovered and deployed using
  * CDI when the MP gRPC server starts.
  */
-@RpcService
+@Grpc
 @ApplicationScoped
 public class AsyncStringService {
 

examples/grpc/microprofile/basic-server-implicit/src/main/java/io/helidon/microprofile/grpc/example/basic/implicit/StringService.java

@@ -24,7 +24,7 @@
 import io.helidon.grpc.server.CollectingObserver;
 import io.helidon.microprofile.grpc.core.Bidirectional;
 import io.helidon.microprofile.grpc.core.ClientStreaming;
-import io.helidon.microprofile.grpc.core.RpcService;
+import io.helidon.microprofile.grpc.core.Grpc;
 import io.helidon.microprofile.grpc.core.ServerStreaming;
 import io.helidon.microprofile.grpc.core.Unary;
 
@@ -33,10 +33,10 @@
 /**
  * The gRPC StringService implementation.
  * <p>
- * This class is a gRPC service annotated with {@link RpcService} and {@link ApplicationScoped}
+ * This class is a gRPC service annotated with {@link Grpc} and {@link ApplicationScoped}
  * so that it will be discovered and deployed using CDI when the MP gRPC server starts.
  */
-@RpcService
+@Grpc
 @ApplicationScoped
 public class StringService {