reactive-commons-java
The purpose of reactive-commons is to provide a set of abstractions and implementations over different patterns and practices that make the foundation of a reactive microservices architecture.
Docs: https://reactivecommons.org/reactive-commons-java/
Other projects: https://github.com/bancolombia
Sponsor by: https://medium.com/bancolombia-tech
Even though the main purpose is to provide such abstractions in a mostly generic way such abstractions would be of little use without a concrete implementation so we provide some implementations in a best effors maner that aim to be easy to change, personalize and extend.
The first approach to this work was to release a very simple abstractions and a corresponding implementation over asyncronous message driven communication between microservices build on top of project-reactor and spring boot.
Get Started
To include all (API and implementation) (Spring boot Starter):
dependencies {
compile 'org.reactivecommons:async-commons-rabbit-starter:<version-here>'
}
//IMPORTANT! if you use the version 0.6.x
repositories {
...
maven { url "https://repo.spring.io/milestone" }
}
configurations.all {
resolutionStrategy.eachDependency {DependencyResolveDetails details ->
if (details.requested.group == 'io.projectreactor.rabbitmq'){
details.useVersion('1.5.0')
details.because('Upgrade')
}
}
}
In application.properties
spring.application.name=MyAppName
Or yaml
spring:
application:
name: myAppName
To include only domain events API:
dependencies {
compile 'org.reactivecommons:domain-events-api:<version-here>'
}To include only async commons API:
dependencies {
compile 'org.reactivecommons:async-commons-api:<version-here>'
}Main abstractions
Domain events API (Broadcast of events)
package org.reactivecommons.api.domain;
import org.reactivestreams.Publisher;
public interface DomainEventBus {
<T> Publisher<Void> emit(DomainEvent<T> event);
}The above interface is the main interface for Broadcast of domain events, the DomainEvent class has the following structure:
package org.reactivecommons.api.domain;
public class DomainEvent<T> {
private final String name;
private final String eventId;
private final T data;
public DomainEvent(String name, String eventId, T data) {
this.name = name;
this.eventId = eventId;
this.data = data;
}
//... getters, equals, hascode, toString impl..
}Usage example:
public class ManageTasksUseCase {
private TaskToDoRepository tasks;
private DomainEventBus eventBus;
public Mono<TaskToDo> createNew(String name, String description) {
return uuid()
.flatMap(id -> TaskToDoFactory.createTask(id, name, description))
.flatMap(tasks::save)
.flatMap(task -> emitCreatedEvent(task).thenReturn(task));
}
private Mono<Void> emitCreatedEvent(TaskToDo task) {
return Mono.from(eventBus.emit(new DomainEvent<>("task.created", task.getId(), task)));
}
//...
}Then enable this feature in a Configuration class and inject implementation:
import org.reactivecommons.async.impl.config.annotations.EnableDomainEventBus;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
@EnableDomainEventBus
public class MainApplication {
public static void main(String[] args) {
SpringApplication.run(MainApplication.class, args);
}
@Bean
public ManageTasksUseCase manageTasksUseCase(TaskToDoRepository tasks, DomainEventBus eventBus) {
return new ManageTasksUseCase(tasks, eventBus);
}
}
Don't forget to add the starter bundle to the main spring boot module (application):
dependencies {
compile 'org.reactivecommons:async-commons-rabbit-starter:<version-here>'
}Or add the implementation dependency if for any reason you don't want to use the starter:
dependencies {
compile 'org.reactivecommons:async-commons:<version-here>'
}Domain Event-Listener
Reactive commons has four types of listeners implemented, available to be registered in the application via the HandlerRegistry, each of them is designed to tackle
common requirements for listeners in event based applications and abstracts the behavior of event flow in every situation (Varying for example in retrying strategy, dead letter events, sources and so on).
The available event listeners are:
- Domain Event Listener
- Query Event Listener
- Command Listener
- Notification Listener
Example Code:
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.beans.factory.annotation.Autowired;
@Configuration
public class SomeConfigurationClass {
@Autowired
private ManageTasksUseCase someBusinessDependency;
@Bean
public HandlerRegistry notificationEvents() {
return HandlerRegistry.register()
.listenNotificationEvent("some.event.name", event -> someBusinessDependency.someFunctionReturningMonoVoid(event), SomeClass.class)
.listenEvent("some.event.name2", event -> someBusinessDependency.functionReturningMonoVoid(event), Some.class)
.serveQuery("query.name", query -> someBusinessDependency.findSomething(query), SomeQuery.class)
.handleCommand("command.name", cmd -> someBusinessDependency.handleCommand(cmd), CmdClass.class);
}
}The first line below "HandlerRegistry.register()" shows how to handle a notification event (Notification event: an event that should be handled by every running instance of a microservice, e.g: notify to every instance that a configuration setting has changed and has to do a hot reload from a persistent source of that data).
The line ".listenEvent.." shows how to handle a standard event, and event that should be handled only once by some running instance of the microservice.
The line ".serveQuery..." shows how to handle a standard request/reply or rpc messages flow.
The line ".handleCommand..." shows how to handle a standard directed command, a message with a delivery guarantee.
Request-Reply
Example Code:
public Mono<AggregateResponse> queryInformation() {
AsyncQuery<String> userQuery = new AsyncQuery<>("user.byId", "42");
AsyncQuery<String> projectQuery = new AsyncQuery<>("project.byId", "343");
AsyncQuery<String> productQuery = new AsyncQuery<>("product.byId", "22");
Mono<User> user = gateway.requestReply(userQuery, "Users", User.class);
Mono<Project> project = gateway.requestReply(projectQuery, "Projects", Project.class);
Mono<Product> product = gateway.requestReply(productQuery, "Products", Product.class);
return zip(user, project, product).map(function(this::aggregate));
}Direct Commands
package org.reactivecommons.async.api;
import org.reactivecommons.api.domain.Command;
import reactor.core.publisher.Mono;
public interface DirectAsyncGateway {
<T> Mono<Void> sendCommand(Command<T> command, String targetName);
<T, R> Mono<R> requestReply(AsyncQuery<T> query, String targetName, Class<R> type);
}Command Type
package org.reactivecommons.api.domain;
public class Command<T> {
private final String name;
private final String commandId;
private final T data;
}Send Commands
private static final String REGISTER_MEMBER = "Members.registerMember";
private static final String TARGET = "Members";
private DirectAsyncGateway asyncGateway;
public Mono<Void> registerMember(Member member){
String uuid = UUID.randomUUID().toString();
return asyncGateway.sendCommand(new Command<>(REGISTER_MEMBER, uuid, member), TARGET);
}Handle Commands
private static final String REGISTER_MEMBER = "Members.registerMember";
@Bean
public HandlerRegistry commandHandlers(MembersRegistryUseCase useCase) {
return HandlerRegistry.register()
.handleCommand(REGISTER_MEMBER, useCase::registerMember, Member.class);
}Broker Configuration (RabbitMQ)
spring.rabbitmq.host= 8.8.8.1
spring.rabbitmq.port=5729
spring.rabbitmq.username=user
spring.rabbitmq.password=pass
Retry Strategy Config (RabbitMQ)
app.async.withDLQRetry=true
app.async.retryDelay=1000
app.async.maxRetries=10
Domain custom Configuration (RabbitMQ)
app.async.domain.events.exchange=exchangeCustomName
app.async.domain.events.maxLengthBytes=125000000
Direct custom Configuration (RabbitMQ)
app.async.direct.exchange=exchangeCustomName
app.async.direct.maxLengthBytes=125000000
Global custom Configuration (RabbitMQ)
app.async.global.exchange=exchangeCustomName
app.async.global.maxLengthBytes=125000000
app.async.maxConcurrency=20
- withDLQRetry: Whether to enable or not the new Retry DLQ Strategy
- retryDelay: Delay retry value in ms
- maxRetries: Number of retries in case of error in addition to the one automatic retry per queue.