Spring @RSocketExchange with Example

Starting Spring 6 and Spring Boot 3, similar to other declarative clients like OpenFeign and Retrofit, the Spring framework supports creating an RSocket service as a Java interface with annotated methods for RSocket exchanges. This tutorial will teach us to use @RSocketExchange to create a declarative requester client for RSocket protocol.

A declarative HTTP interface is a Java interface that helps reduce the boilerplate code, generates a proxy implementing this interface, and performs the exchanges at the framework level.

1. Maven

We need to include the latest version of spring-boot-starter-rsocket dependency to include all necessary classes and interfaces.

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-rsocket</artifactId>
</dependency>

2. Using @RSocketExchange

The @RSocketExchange annotation to declare a method on an RSocket service interface as an RSocket endpoint. It accepts a ‘value’ argument that defines the endpoint route. Similar to @RequestMapping for HTTP transfers, @RSocketExchange can be used at the interface level to express a common route, to be inherited by all service methods.

public interface MessageService {

  @RSocketExchange("message")
  public Mono<String> sendMessage(Mono<String> requestObject);
}

A service method can accept the following method arguments:

• @DestinationVariable: to add a route variable to expand template placeholders into the route.
• @Payload: an optional annotation that sets the request’s input payload(s).
• Object, followed by MimeType: send additional metadata entry in the input payload and its mime type.

public interface MessageService {

  @RSocketExchange("greeting/{name}")
  public Mono<String> sendMessage(@DestinationVariable("name") String name, @Payload Mono<String> greetingMono);
}

Under the hood, Spring generates a proxy that implements MessageService interface and performs the exchanges using the underlying RSocketRequester.

3. Generating Service Proxy

As we know that Spring boot autoconfiguration automatically configures the RSocketRequester.Builder for us. We can use the builder to create RSocketRequester.

@Autowired
RSocketRequester.Builder requesterBuilder;

//In any method
RSocketRequester rsocketRequester = requesterBuilder.tcp("localhost", 7000);

Finally, we can use the RSocketRequester to initialize a RSocketServiceProxyFactory that is ultimately used for creating the client proxy for any RSocket service interface with @RSocketExchange methods.

RSocketServiceProxyFactory factory = RSocketServiceProxyFactory.builder(rsocketRequester).build();

MessageService service = factory.createClient(MessageService.class);

Finally, we can use the created service proxy to invoke exchange methods. Let us see the full example together.

@SpringBootApplication
@Slf4j
public class App implements CommandLineRunner {

  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  @Autowired
  RSocketRequester.Builder requesterBuilder;

  @Override
  public void run(String... args) throws Exception {

    RSocketRequester rsocketRequester = requesterBuilder.tcp("localhost", 7000);
    RSocketServiceProxyFactory factory = RSocketServiceProxyFactory.builder(rsocketRequester).build();

    MessageService service = factory.createClient(MessageService.class);

    Mono<String> response = service.sendMessage("Lokesh", Mono.just("Hello there!"));
    response.subscribe(message -> log.info("RSocket response : {}", message));
  }
}

Program output in the console.

...[ctor-http-nio-2] c.h.a.r.controller.MessageController     : Received a greeting from Lokesh : Hello there!
...[actor-tcp-nio-2] c.howtodoinjava.app.rsocketexchange.App  : RSocket response : Hello Lokesh!

4. Conclusion

In this short Spring tutorial, we learned a new feature introduced in Spring 6 i.e. creating a declarative RSocket client using the @RSocketExchange annotation. We learned to create and instantiate the service proxy and use it to connect to a remote endpoint over TCP protocol.

Happy Learning !!

Sourcecode on Github