From 69c25e8845a2cfe58e580bfd45be1fd40a1c129e Mon Sep 17 00:00:00 2001 From: Martin Kouba Date: Thu, 10 Jun 2021 13:50:16 +0200 Subject: [PATCH] gRPC - clarify naming for clients - GrpcClient#value() is actually a "client name" and the client can be shared, i.e. the underlying Channel can be used for several services running on the target gRPC server --- .../main/asciidoc/grpc-getting-started.adoc | 4 +- .../asciidoc/grpc-service-consumption.adoc | 8 +-- .../grpc/deployment/GrpcClientBuildItem.java | 8 +-- .../grpc/deployment/GrpcClientProcessor.java | 52 +++++++++---------- .../runtime/config/GrpcConfiguration.java | 2 +- .../main/java/io/quarkus/grpc/GrpcClient.java | 4 +- 6 files changed, 39 insertions(+), 39 deletions(-) diff --git a/docs/src/main/asciidoc/grpc-getting-started.adoc b/docs/src/main/asciidoc/grpc-getting-started.adoc index 94caea8801750..03de6d411ee41 100644 --- a/docs/src/main/asciidoc/grpc-getting-started.adoc +++ b/docs/src/main/asciidoc/grpc-getting-started.adoc @@ -265,7 +265,7 @@ public class ExampleResource { } } ---- -<1> Inject the service and configure its name. The service name is used in the application configuration. If not specified then the field name is used instead: `hello` in this particular case. +<1> Inject the service and configure its name. The name is used in the application configuration. If not specified then the field name is used instead: `hello` in this particular case. <2> Use the generated service interface based on Mutiny API. <3> Invoke the service. @@ -277,7 +277,7 @@ In the `src/main/resources/application.properties` file, add the following prope quarkus.grpc.clients.hello.host=localhost ---- -- `hello` is the name of the service used in the `@GrpcClient` annotation. +- `hello` is the name used in the `@GrpcClient` annotation. - `host` configures the service host (here it's localhost). Then, open http://localhost:8080/hello/quarkus in a browser, and you should get `Hello quarkus`! diff --git a/docs/src/main/asciidoc/grpc-service-consumption.adoc b/docs/src/main/asciidoc/grpc-service-consumption.adoc index 85d205cd5bc73..e895a40897920 100644 --- a/docs/src/main/asciidoc/grpc-service-consumption.adoc +++ b/docs/src/main/asciidoc/grpc-service-consumption.adoc @@ -49,8 +49,8 @@ class MyBean { } ---- -<1> A gRPC client injection point must be annotated with the `@GrpcClient` qualifier. This qualifier can be used to specify the service name that is used to configure the underlying gRPC client. For example, if you set it to `hello-service`, configuring the host of the service is done using the `quarkus.grpc.clients.**hello-service**.host`. -<2> If the service name is not specified via the `GrpcClient#value()` then the field name is used instead, e.g. `helloService` in this particular case. +<1> A gRPC client injection point must be annotated with the `@GrpcClient` qualifier. This qualifier can be used to specify the name that is used to configure the underlying gRPC client. For example, if you set it to `hello-service`, configuring the host of the service is done using the `quarkus.grpc.clients.**hello-service**.host`. +<2> If the name is not specified via the `GrpcClient#value()` then the field name is used instead, e.g. `helloService` in this particular case. The stub class names are derived from the service name used in your `proto` file. For example, if you use `Greeter` as a service name as in: @@ -205,9 +205,9 @@ For each gRPC service you inject in your application, you can configure the foll include::{generated-dir}/config/quarkus-grpc-config-group-config-grpc-client-configuration.adoc[opts=optional, leveloffset=+1] -The `service-name` is the name set in the `@GrpcClient` or derived from the injection point if not explicitly defined. +The `client-name` is the name set in the `@GrpcClient` or derived from the injection point if not explicitly defined. -The following examples uses _hello_ as service name. +The following examples uses _hello_ as the client name. Don't forget to replace it with the name you used in in the `@GrpcClient` annotation. === Enabling TLS diff --git a/extensions/grpc/deployment/src/main/java/io/quarkus/grpc/deployment/GrpcClientBuildItem.java b/extensions/grpc/deployment/src/main/java/io/quarkus/grpc/deployment/GrpcClientBuildItem.java index 318af9c5db931..17913e920c71e 100644 --- a/extensions/grpc/deployment/src/main/java/io/quarkus/grpc/deployment/GrpcClientBuildItem.java +++ b/extensions/grpc/deployment/src/main/java/io/quarkus/grpc/deployment/GrpcClientBuildItem.java @@ -10,11 +10,11 @@ public final class GrpcClientBuildItem extends MultiBuildItem { - private final String serviceName; + private final String clientName; private final Set clients; public GrpcClientBuildItem(String name) { - this.serviceName = name; + this.clientName = name; this.clients = new HashSet<>(); } @@ -26,8 +26,8 @@ public void addClient(ClientInfo client) { clients.add(client); } - public String getServiceName() { - return serviceName; + public String getClientName() { + return clientName; } public static final class ClientInfo { diff --git a/extensions/grpc/deployment/src/main/java/io/quarkus/grpc/deployment/GrpcClientProcessor.java b/extensions/grpc/deployment/src/main/java/io/quarkus/grpc/deployment/GrpcClientProcessor.java index 1706ade3cc635..b2723fb9d838f 100644 --- a/extensions/grpc/deployment/src/main/java/io/quarkus/grpc/deployment/GrpcClientProcessor.java +++ b/extensions/grpc/deployment/src/main/java/io/quarkus/grpc/deployment/GrpcClientProcessor.java @@ -75,7 +75,7 @@ void registerBeans(BuildProducer beans) { @BuildStep void discoverInjectedGrpcServices(BeanDiscoveryFinishedBuildItem beanDiscovery, - BuildProducer services, + BuildProducer clients, BuildProducer features, CombinedIndexBuildItem index) { @@ -105,17 +105,17 @@ void discoverInjectedGrpcServices(BeanDiscoveryFinishedBuildItem beanDiscovery, continue; } - String serviceName; - AnnotationValue serviceNameValue = clientAnnotation.value(); - if (serviceNameValue == null || serviceNameValue.asString().equals(GrpcClient.ELEMENT_NAME)) { + String clientName; + AnnotationValue clientNameValue = clientAnnotation.value(); + if (clientNameValue == null || clientNameValue.asString().equals(GrpcClient.ELEMENT_NAME)) { // Determine the service name from the annotated element if (clientAnnotation.target().kind() == Kind.FIELD) { - serviceName = clientAnnotation.target().asField().name(); + clientName = clientAnnotation.target().asField().name(); } else if (clientAnnotation.target().kind() == Kind.METHOD_PARAMETER) { MethodParameterInfo param = clientAnnotation.target().asMethodParameter(); - serviceName = param.method().parameterName(param.position()); - if (serviceName == null) { - throw new DeploymentException("Unable to determine the service name from the parameter at position " + clientName = param.method().parameterName(param.position()); + if (clientName == null) { + throw new DeploymentException("Unable to determine the client name from the parameter at position " + param.position() + " in method " + param.method().declaringClass().name() + "#" + param.method().name() @@ -126,20 +126,20 @@ void discoverInjectedGrpcServices(BeanDiscoveryFinishedBuildItem beanDiscovery, throw new IllegalStateException(clientAnnotation + " may not be declared at " + clientAnnotation.target()); } } else { - serviceName = serviceNameValue.asString(); + clientName = clientNameValue.asString(); } - if (serviceName.trim().isEmpty()) { + if (clientName.trim().isEmpty()) { throw new DeploymentException( - "Invalid @GrpcClient `" + injectionPoint.getTargetInfo() + "` - service name cannot be empty"); + "Invalid @GrpcClient `" + injectionPoint.getTargetInfo() + "` - client name cannot be empty"); } GrpcClientBuildItem item; - if (items.containsKey(serviceName)) { - item = items.get(serviceName); + if (items.containsKey(clientName)) { + item = items.get(clientName); } else { - item = new GrpcClientBuildItem(serviceName); - items.put(serviceName, item); + item = new GrpcClientBuildItem(clientName); + items.put(clientName, item); } Type injectionType = injectionPoint.getRequiredType(); @@ -178,18 +178,18 @@ void discoverInjectedGrpcServices(BeanDiscoveryFinishedBuildItem beanDiscovery, if (!items.isEmpty()) { for (GrpcClientBuildItem item : items.values()) { - services.produce(item); - LOGGER.debugf("Detected GrpcService associated with the '%s' configuration prefix", item.getServiceName()); + clients.produce(item); + LOGGER.debugf("Detected GrpcService associated with the '%s' configuration prefix", item.getClientName()); } features.produce(new FeatureBuildItem(GRPC_CLIENT)); } } @BuildStep - public void generateGrpcServicesProducers(List clients, + public void generateGrpcClientProducers(List clients, BuildProducer syntheticBeans) { - for (GrpcClientBuildItem svcClients : clients) { + for (GrpcClientBuildItem client : clients) { // For every service we register: // 1. the channel // 2. the blocking stub - if needed @@ -200,26 +200,26 @@ public void generateGrpcServicesProducers(List clients, // bean that provides the GrpcClientConfiguration for the specific service. syntheticBeans.produce(SyntheticBeanBuildItem.configure(GrpcDotNames.CHANNEL) - .addQualifier().annotation(GrpcDotNames.GRPC_CLIENT).addValue("value", svcClients.getServiceName()).done() + .addQualifier().annotation(GrpcDotNames.GRPC_CLIENT).addValue("value", client.getClientName()).done() .scope(Singleton.class) .unremovable() .creator(new Consumer() { @Override public void accept(MethodCreator mc) { - GrpcClientProcessor.this.generateChannelProducer(mc, svcClients); + GrpcClientProcessor.this.generateChannelProducer(mc, client); } }) .destroyer(Channels.ChannelDestroyer.class).done()); - String svcName = svcClients.getServiceName(); - for (ClientInfo client : svcClients.getClients()) { - syntheticBeans.produce(SyntheticBeanBuildItem.configure(client.className) + String svcName = client.getClientName(); + for (ClientInfo clientInfo : client.getClients()) { + syntheticBeans.produce(SyntheticBeanBuildItem.configure(clientInfo.className) .addQualifier().annotation(GrpcDotNames.GRPC_CLIENT).addValue("value", svcName).done() .scope(Singleton.class) .creator(new Consumer() { @Override public void accept(MethodCreator mc) { - GrpcClientProcessor.this.generateClientProducer(mc, svcName, client); + GrpcClientProcessor.this.generateClientProducer(mc, svcName, clientInfo); } }).done()); } @@ -289,7 +289,7 @@ private DeploymentException invalidInjectionPoint(InjectionPointInfo injectionPo } private void generateChannelProducer(MethodCreator mc, GrpcClientBuildItem svc) { - ResultHandle name = mc.load(svc.getServiceName()); + ResultHandle name = mc.load(svc.getClientName()); ResultHandle result = mc.invokeStaticMethod(CREATE_CHANNEL_METHOD, name); mc.returnValue(result); mc.close(); diff --git a/extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/config/GrpcConfiguration.java b/extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/config/GrpcConfiguration.java index f28dacdb5881b..9d6096960b5c5 100644 --- a/extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/config/GrpcConfiguration.java +++ b/extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/config/GrpcConfiguration.java @@ -15,7 +15,7 @@ public class GrpcConfiguration { */ @ConfigItem @ConfigDocSection - @ConfigDocMapKey("service-name") + @ConfigDocMapKey("client-name") public Map clients; /** diff --git a/extensions/grpc/stubs/src/main/java/io/quarkus/grpc/GrpcClient.java b/extensions/grpc/stubs/src/main/java/io/quarkus/grpc/GrpcClient.java index 9e7ede4c91905..14aceb91e1c8f 100644 --- a/extensions/grpc/stubs/src/main/java/io/quarkus/grpc/GrpcClient.java +++ b/extensions/grpc/stubs/src/main/java/io/quarkus/grpc/GrpcClient.java @@ -24,9 +24,9 @@ String ELEMENT_NAME = "<>"; /** - * The service name is used to configure the gRPC client, e.g. the location, TLS/SSL, etc. + * The name is used to configure the gRPC client, e.g. the location, TLS/SSL, etc. * - * @return the service name + * @return the client name */ String value() default ELEMENT_NAME;