Protobuf and gRPC with Spring Boot: A Complete Guide

By /

Overview

gRPC is a high-performance open-source remote procedure call framework, initially it was developed by Google. It is to eliminate the boilerplate code and connect with services in and across the data center. The gRPC API uses the Protocol Buffers, it uses the protec compiler to generate source code in different supported languages.

gRPC services are alternative of SOAP, REST, or GraphQL, it is developed on HTTP/2 protocol and provides features of streaming connection with uni-directional or bi-directional endpoints.

In this tutorial, we’ll explore to implement gRPC service with a producer and consumer with Spring Boot.

Protobuf and gRPC with Spring Boot

What is gRPC?

Google Remove Procedure Call (gRPC) is open source, high performance RPC framework, that uses HTTP/2 for transport, Protocol Buffers(protobuf) as interface to declare the endpoints. It provides features like:

  1. Unidirectional and Bi-Directional: In unidirectional flow data in only one direction at a time, either from client to server or server to client. Whereas in Bi-Directional, the data flow in both client and server send streams simultaneously. and the data flow both in client and server side independently.
  2. Multiplexing: It is a technique used in all the communication systems, also gRPC uses it to send streaming data in both client and server.
  3. Strongly Typed Contract: gRPC uses a strongly typed contract in client and server message stream, where predefined, compiled, and checked at runtime using Protocol Buffer.
  4. Built-in Authentication and Load Balancing: gRPC supports multiple authentication and transport layer security(TLS), which help us to secure and authenticate.

What is Protocol Buffers (Protobuf)?

Protocol Buffers are the language-neutral and platform-independent, it is mechanism for serializing structured data. It is a different and simpler mechanism than XML and JSON. Protobuf define the data structure in the .proto file, and compiles using protoc compiler.

Development Challenges

In the current Spring and Spring Boot packages, there is no support for gRPC. It supports only Protocol Buffers, and helps us to implement protobuf-based service endpoints. Now to explore protobuf and gRPC with Spring Boot, we need to include third-party dependencies.

  1. The protobuf protec compiler, compiles and generates stubs which are platform-dependent. it should be generated during build time.
  2. However, protec compiler generates and adds a javax.annotation.Generated annotation. which requires an older version of Java EE Annotation. So the Spring Boot should be compatible with all the dependencies.
  3. Shadded Netty is server provider for gRPC services, it should run within the own server. So we need to replace the Spring Boot server which is already provided by Spring Boot.
  4. In the transport layer, Spring Boot provides RestClient or WebClient, which are not compatible or configured with gRPC. Because gRPC uses the HTTP/2 protocol with custom transport technology.

Step-by-Step: gRPC with Spring Boot

Here, the implementation of Protobuf and gRPC with Spring Boot, we’ll walk through a step-by-step guide to implementing a gRPC service using Spring Boot.

1. Add Maven Dependencies

Add the necessary Maven dependencies into pom.xml to enable gRPC service implementation in a Spring Boot application.

Protocol Buffer Dependencies: Add the following protobuf dependencies and protoc plugin.

<!--protobuf required dependencies-->
<dependency>
	<groupId>com.google.protobuf</groupId>
	<artifactId>protobuf-java</artifactId>
	<version>${protobuf.version}</version>
</dependency>
<dependency>
	<groupId>io.grpc</groupId>
	<artifactId>grpc-protobuf</artifactId>
	<version>${grpc.version}</version>
</dependency>
<dependency>
	<groupId>javax.annotation</groupId>
	<artifactId>javax.annotation-api</artifactId>
	<version>1.3.2</version>
</dependency>
<dependency>
	<groupId>io.grpc</groupId>
	<artifactId>grpc-stub</artifactId>
	<version>${grpc.version}</version>
</dependency>

<!--protoc compiler plugin-->
<plugin>
        <groupId>org.xolstice.maven.plugins</groupId>
	<artifactId>protobuf-maven-plugin</artifactId>
	<extensions>true</extensions>
	<version>0.6.1</version>
	<configuration>
		<protoSourceRoot>src/main/proto</protoSourceRoot>
		<protocArtifact>com.google.protobuf:protoc:4.30.2:exe:${os.detected.classifier}</protocArtifact>
		<pluginId>grpc-java</pluginId>
		<pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}
		</pluginArtifact>
	</configuration>
	<executions>
		<execution>
			<goals>
				<goal>compile</goal>
				<goal>compile-custom</goal>
			</goals>
		</execution>
	</executions>
</plugin>

Spring Boot gRPC dependencies: As Spring Boot doesn’t provide direct dependencies for gRPC, the following third-party service provider dependencies can be added to pom.xml.

<dependency>
    <groupId>net.devh</groupId>
    <artifactId>grpc-spring-boot-starter</artifactId>
    <version>3.1.0.RELEASE</version>
</dependency>

2. Define a Protocol Buffer file

Define protobuf file and generate stub classes. In Protobuf and gRPC with Spring Boot use case, we have taken the employee example. You can learn more about protobuf data types.

syntax = "proto3";

option java_package = "com.javatecharc.demo.protobuf.grpc";
option java_multiple_files = true;

service EmployeeService {
    rpc GetEmployeeDetails (EmployeeRequest) returns (EmployeeResponse);
}

message EmployeeRequest {
    int32 empId = 1;
}

message EmployeeResponse {
    int32 empId = 1;
    string name = 2;
    string department = 3;
    string email = 4;
    int64 salary = 5;
}

Compile the above employee.proto file using the protoc compiler plugin. This will generate a set of stub classes, including EmployeeServiceGrpc.EmployeeServiceImplBase, which defines the contract for the getEmployeeDetails() method. It will also generate the corresponding request and response classes.

3. Implement gRPC Service in Spring Boot

Create a new class EmployeeServiceImpl.java, which will implement the defined contract of EmployeeServiceGrpc.EmployeeServiceImplBase of getEmployeeDetails().

package com.javatecharc.demo.grpc.service;

import com.javatecharc.demo.protobuf.grpc.EmployeeRequest;
import com.javatecharc.demo.protobuf.grpc.EmployeeResponse;
import com.javatecharc.demo.protobuf.grpc.EmployeeServiceGrpc;
import io.grpc.stub.StreamObserver;
import net.devh.boot.grpc.server.service.GrpcService;

import java.util.HashMap;
import java.util.Map;

@GrpcService
public class EmployeeServiceImpl extends EmployeeServiceGrpc.EmployeeServiceImplBase {

    @Override
    public void getEmployeeDetails(EmployeeRequest request, StreamObserver<EmployeeResponse> responseObserver) {
        Integer empId = request.getEmpId();
        System.out.println("Received request for employee : " + request);

        Map<Integer, EmployeeResponse> employeeMap = getEmployeeDataMap();

        EmployeeResponse response = employeeMap.get(empId);

        responseObserver.onNext(response);
        responseObserver.onCompleted();
    }

    private Map<Integer, EmployeeResponse> getEmployeeDataMap() {
        // This method simulates a database or Hazelcast Map for employee details.
        Map<Integer, EmployeeResponse> employeeMap = new HashMap<>();

        employeeMap.put(101, EmployeeResponse.newBuilder()
                .setEmpId(101)
                .setName("John Smith")
                .setDepartment("Engineering")
                .setSalary(30000)
                .build());

        employeeMap.put(102, EmployeeResponse.newBuilder()
                .setEmpId(102)
                .setName("Jane Brown")
                .setDepartment("HR")
                .setSalary(25000)
                .build());

        employeeMap.put(103, EmployeeResponse.newBuilder()
                .setEmpId(103)
                .setName("Alice Johnson")
                .setDepartment("Finance")
                .setSalary(50000)
                .build());

        return employeeMap;
    }
}
  1. In getEmployeeDetails(), EmployeeRequest request and StreamObserver<EmployeeResponse> responseObserver defines the request and response of the RPC endpoint.
  2. In this use case, we have taken getEmployeeMap() as input for employee details.
  3. You can explore more about gRPC request and response implementation.

4. Configure Port in Application YML

You can configure the gRPC port in the application YML or properties file if required, the default port is 8080 without SSL. 

grpc:
  server:
    port: 8090

5. GRPC Service Client

If you calling gRPC endpoint from another Spring Boot application, then you can configure and create gRPC client.

Consumer client dependencies:

<dependency>
   <groupId>net.devh</groupId>
   <artifactId>grpc-client-spring-boot-starter</artifactId>
   <version>3.1.0.RELEASE</version>
</dependency>

Application YML configuration:

# Another client spring boot application.yml
grpc:
  client:
    employeeService:
      address: 'static://localhost:8090'
      enableKeepAlive: true
      negotiationType: plaintext

Then create the client service class EmployeeServiceClient.java using the generated stub.

package com.javatecharc.demo.grpc.client.service;

import com.javatecharc.demo.protobuf.grpc.EmployeeRequest;
import com.javatecharc.demo.protobuf.grpc.EmployeeResponse;
import com.javatecharc.demo.protobuf.grpc.EmployeeServiceGrpc;
import net.devh.boot.grpc.client.inject.GrpcClient;
import org.springframework.stereotype.Component;

@Component
public class EmployeeServiceClient {
    @GrpcClient("employeeService")
    EmployeeServiceGrpc.EmployeeServiceBlockingStub stub;

    public EmployeeResponse getEmployeeDetails(int empId) {
        EmployeeRequest request = EmployeeRequest.newBuilder().setEmpId(103).build();
        EmployeeResponse response = stub.getEmployeeDetails(request);

        System.out.println(response);
        // You can add additional logic here if needed, such as error handling or logging.

        return response;
    }
}

6. Run and Test

Start the Spring Boot service and test service using the above client.

gRPC Client is running...
empId: 103
name: "Alice Johnson"
department: "Finance"
salary: 50000

Spring Boot gRPC SSL Handshake

In protobuf and gRPC with Spring Boot, the built-in netty server default does not use the SSL, we need to configure it explicility. The SSL(Secure Sockets Layer) is a process to establish a connection and transfer the data between client and server with secure and encrypted.

gRPC Server Config:

#GRPC server config application.yml
grpc:
  server:
    security:
      enabled: true
      certificateChain: classpath:certs/server.crt
      privateKey: classpath:certs/server.key

Client Config:

# Client Spring Service application.yml
grpc:
  client:
    myService:
      address: "static://localhost:8090"
      negotiationType: TLS
      trustCertCollection: classpath:certs/ca.crt

gRPC use cases:

  • Internal microservices uni-directional or bi-directional communication.
  • Real-time chat, video services
  • Language-agnostic API development
  • Fintech like low-latency service application

Conclusion

Protobuf and gRPC with Spring Boot, provide strong typing, and contract design and they use the HTTP/2 protocol. gPRC provides high-performance and efficiency, which is out perform with JSON+REST in both speed and size. It is ideal for internal server calls and data streaming. Spring Boot gRPC built-in reliability features like TLS encryption, client-side load balancing, retry policies, deadlines etc.

The source code demonstrated on the demo, available on Github.

Related Articles

Leave a Comment

Your email address will not be published. Required fields are marked *

Table of Contents

→ Index
Scroll to Top