Java Protobuf Examples

Before writing the code, it is essential to ensure that your development environment has correctly configured the Google Protocol Buffers for Java (referred to as gRPC-Java) compilation plugin and runtime support. For modern Java projects, Maven or Gradle are recommended build tools for dependency management. Taking Maven as an example, you need to add the following core coordinates in the pom.xml file:

<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-protobuf</artifactId>
    <version>1.62.0</version> <!-- Adjust according to your actual project version -->
</dependency>
<!-- If you need to generate Java code, also add the compiler plugin -->
<build>
    <plugins>
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>protoc-maven-plugin</artifactId>
            <version>3.19.2</version>
            <configuration>
                <sourceDirectories>${project.basedir}/src/main/proto</sourceDirectories>
            </configuration>
        </plugin>
    </plugins>
</build>

After installation, developers must place .proto files in the src/main/resources directory or a custom proto subdirectory. The build tool will automatically invoke the compiler to generate corresponding Java interface classes, message definition classes, and service implementation base classes, serving as foundational infrastructure for subsequent development.
The core of Protobuf lies in its declarative syntax within .proto files. These files define data structures and service contracts that can be understood without relying on any specific programming language. Below is a typical example of a user data model:

syntax = "proto3";

package com.example.user;

// Define message type (Message)
message User {
    string id = 1;              // Unique identifier
    string name = 2;            // Name field
    int64 age = 3;             // Age, using long type to support large values
    repeated string hobbies = 4;// Hobbies list, 'repeated' keyword indicates variable-length array
    
    optional bool is_active = 5; // Optional boolean flag indicating if user is active
}

// Define service (Service) interface
service UserService {
    rpc GetUser(GetUserRequest) returns (User);
    
    rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
}

message GetUserRequest {
    string user_id = 1; // User ID carried in the request
}

message ListUsersRequest {
    int32 page_size = 1;      // Pagination size limit
    repeated string ids = 2;   // Multiple specific user IDs to query
}

message ListUsersResponse {
    repeated User users = 1; // Returned list of users
    int64 total_count = 2;   // Total record count statistics
}

The above definition demonstrates key Protobuf features: field numbers are used for positioning during serialization, the repeated keyword handles collection types, and the optional modifier provides default value logic. These declarations map directly to Java class structures, generic lists, and enum flags, significantly reducing data inconsistency risks across language communication.

Generating Java Code and Configuring Service Interfaces

The compiled Java files are typically located in the target/generated-sources/protobuf/java/com/example/user directory. At this stage, developers will obtain three main components: message classes (such as User.java), request/response wrapper classes, and abstract service base classes (such as UserServiceGrpc.UserServiceImplBase.java). To invoke these services in practice, you must introduce gRPC's auto-generated stubs and service generator dependencies into your project.

Add the following runtime dependencies to your pom.xml:

<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-stub</artifactId>
    <version>1.62.0</version>
</dependency>
<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-protobuf</artifactId>
    <version>1.62.0</version>
</dependency>

The generated code structure typically looks as follows: com.example.user.UserProto$User corresponds to the message definition, while com.example.user.UserServiceGrpc$$ServiceStubBuilder is used for constructing client invocation objects. This auto-generated mechanism ensures that field names and type mappings strictly align with the .proto file, avoiding potential errors caused by manually writing serialization logic.

Implementing Server-Side Example Code

Server-side implementation requires inheriting the base class provided by the compiler and overriding specific methods. Below is a simplified UserServiceImpl.java example:

import io.grpc.stub.StreamObserver;
import com.example.user.UserProto$User;
import com.example.user.UserServiceGrpc$$ServiceImplBase;
import java.util.ArrayList;
import java.util.List;

public class UserServiceImpl extends UserServiceGrpc$$ServiceImplBase {
    
    @Override
    public void getUser(com.example.user.UserProto$GetUserRequest request, StreamObserver<User> responseObserver) {
        // Simulate database retrieval logic for user
        User user = new User();
        user.setId(request.getUser_id());
        
        if (request.getUser_id().equals("100")) {
            user.setName("Alice");
            user.setAge(25L);
            ArrayList<String> hobbiesList = new ArrayList<>();
            hobbiesList.add("Reading");
            hobbiesList.add("Coding");
            user.addAllHobbies(hobbiesList.toArray(new String[0])); // Note: Actual API might use addAllStrings
            
            responseObserver.onNext(user);
        } else {
            responseObserver.onError(new RuntimeException("User not found"));
        }
    }

    @Override
    public void listUsers(com.example.user.UserProto$ListUsersRequest request, StreamObserver<UserProto$ListUsersResponse> responseObserver) {
        UserProto$ListUsersResponse.Builder builder = UserProto$ListUsersResponse.newBuilder();
        
        // Simulate returning multiple records
        for (int i = 0; i < request.getPage_size() && i < 10; i++) {
            User user = new User();
            String idStr = "USER_" + Integer.toString(i);
            builder.addUsers(user.newBuilder().setId(idStr).setName("User" + i));
        }
        
        responseObserver.onNext(builder.build()); // Note: Actual API might use addAllUsers
    }

    @Override
    public void close() {
        super.close();
    }
}

It is worth noting that due to potential minor differences in the generated Java API across Protobuf versions (e.g., distinction between addAllStrings and addRepeatedString), developers must verify correct usage according to their current version when consulting documentation. Additionally, starting a server typically requires configuring gRPC ServerBuilder with a port number and registering an instance of this implementation class to expose network interfaces.

Client Invocation and Service Interaction Demonstration

After completing the server deployment, you can write Java client code to initiate RPC calls. This involves creating a Channel, building a ServiceStub, and executing asynchronous or synchronous request operations. Below is a typical UserClient.java example:

import io.grpc.ManagedChannel;
import io.grpc.stub.ClientCalls;
import com.example.user.UserProto$GetUserRequest;
import com.example.user.UserServiceGrpc$$ServiceBlockingStub; // Using blocking Stub to simplify code
import java.util.concurrent.TimeUnit;

public class UserClient {
    private static final String SERVER_ADDRESS = "localhost:50051";

    public static void main(String[] args) throws Exception {
        ManagedChannel channel = new ManagedChannel().usePlaintext(); // SSL should be enabled in production
        
        ServiceBlockingStub stub = UserServiceGrpc.newBlockingStub(channel);
        
        GetUserRequest requestBuilder = GetUserRequest.newBuilder()
                .setUser_id("100")
                .build();

        UserProto$User userResponse = stub.getUser(requestBuilder, 
            com.example.user.UserProto.getDefaultInstance()); // Timeout configuration can be set in builder
        
        System.out.println("Retrieved User: " + userResponse.getName() + ", Age: " + userResponse.getAge());
        
        channel.shutdown();
    }
}

In this manner, the client transparently handles underlying binary data transmission details. If non-blocking calls or streaming data transfer (such as Server-Side Streaming) are required, one must use ClientCall.newFutureCall() in conjunction with the StreamObserver interface for more complex logic orchestration. This design pattern not only simplifies development but also ensures stability and performance under high-concurrency scenarios.