Designing a Flexible Java RPC Framework: Client, Server, and Protocol Layers

Overview

Repository URL: https://github.com/Wasabi1234/rpc-framework – a simple RPC framework used for teaching. The article describes how to develop with the framework and its internal design.

User workflow

Define a service interface.

Provide a server‑side implementation of the interface.

On the client, obtain a generated stub (proxy) that forwards calls to the remote service.

Client design

The client creates a proxy for the service interface using JDK dynamic proxies. A ClientStubProxyFactory encapsulates proxy creation.

Key design questions

What responsibilities belong to ClientStubInvocationHandler (e.g., marshalling request, invoking network layer)?

Which component performs request marshalling into a message?

Should the message protocol be fixed or configurable per service? The framework aims for a flexible, service‑specific protocol.

How does the framework discover which protocol a service uses? Via a pluggable service‑information discovery component.

To support multiple discovery mechanisms and protocols, the design uses interfaces, the Strategy pattern, and composition.

Client protocol layer

Define standard Request and Response classes that carry service name, method name, parameter types, and argument values.

Separate the message protocol into its own layer, shared by client and server. The network layer sends Request objects and receives Response objects, requiring the service address.

Server design

RPCServer

RPCServer

listens for incoming connections, decodes raw bytes, and forwards the resulting messages to a RequestHandler. The network layer can be implemented with Netty or another asynchronous I/O library.

RequestHandler

The RequestHandler unmarshals a message into a Request object, looks up the corresponding service implementation (registered via a ServiceRegister), and invokes the target method via reflection. The result is wrapped in a Response and sent back.

Key responsibilities:

Locate the service instance from a service registry.

Extract service name, method name, parameter types, and argument values from the Request.

Invoke the method and capture the return value or exception.

Service registration and exposure

Users register their service implementations with a ServiceRegister. The same component can also expose the service to the network, allowing the server to advertise available services.

Implementation notes

Server configuration requires specifying a listening port and the protocol implementation (e.g., JSON, Protobuf).

Client configuration must provide the remote service address and select a matching protocol.

Sample code snippets

// Service interface
public interface HelloService {
    String sayHello(String name);
}

// Server side registration
ServiceRegister register = new ServiceRegister();
register.register(HelloService.class, new HelloServiceImpl());

// Starting the RPC server
RPCServer server = new RPCServer(8080, new JsonProtocol());
server.start();

// Client side proxy creation
HelloService proxy = ClientStubProxyFactory.create(
    HelloService.class,
    "http://localhost:8080",
    new JsonProtocol()
);
String result = proxy.sayHello("World");