Guide to Reactive Microservices Using Lagom Framework

1. Overview

In this article, we’ll explore the Lagom framework and implement an example application using a reactive microservices driven architecture.

Simply put, reactive software applications rely on message-driven asynchronous communication and are highly Responsive, Resilient and Elastic in nature.

By microservice-driven architecture, we meant splitting the system into boundaries between collaborative services for achieving goals of Isolation, Autonomy, Single Responsibility, Mobility, etc. For further reading on these two concepts, refer The Reactive Manifesto and Reactive Microservices Architecture.

2. Why Lagom?

Lagom is an open source framework built with the shifting from monoliths to microservices-driven application architecture in mind. It abstracts the complexity of building, running and monitoring microservices driven applications.

Behind the scenes, Lagom framework uses the Play Framework, an Akka message-driven runtime, Kafka for decoupling services, Event Sourcing, and CQRS patterns, and ConductR support for monitoring and scaling microservices in the container environment.

3. Hello World in Lagom

We’ll be creating a Lagom application to handle a greeting request from the user and reply back with a greeting message along with weather statistics for the day.

And we’ll be developing two separate microservices: Greeting and Weather.

Greeting will focus on handling a greeting request, interacting with weather service to reply back to the user. The Weather microservice will service the request for weather statistics for today.

In the case of existing user interacting with Greeting microservice, the different greeting message will be shown to the user.

3.1. Prerequisites

1. Install Scala (we are currently using 2.11.8 version) from here
2. Install sbt build tool (we are currently using 0.13.11) from here

4. Project Setup

Let’s now have a quick look at the steps to set up a working Lagom system.

4.1. SBT Build

Create a project folder lagom-hello-world followed by the build file build.sbt. A Lagom system is typically made up of a set of sbt builds with each build corresponding to a group of related services:

organization in ThisBuild := "com.baeldung"

scalaVersion in ThisBuild := "2.11.8"

lagomKafkaEnabled in ThisBuild := false

lazy val greetingApi = project("greeting-api")
  .settings(
    version := "1.0-SNAPSHOT",
    libraryDependencies ++= Seq(
      lagomJavadslApi
    )
  )

lazy val greetingImpl = project("greeting-impl")
  .enablePlugins(LagomJava)
  .settings(
    version := "1.0-SNAPSHOT",
    libraryDependencies ++= Seq(
      lagomJavadslPersistenceCassandra
    )
  )
  .dependsOn(greetingApi, weatherApi)

lazy val weatherApi = project("weather-api")
  .settings(
    version := "1.0-SNAPSHOT",
    libraryDependencies ++= Seq(
      lagomJavadslApi
    )
  )

lazy val weatherImpl = project("weather-impl")
  .enablePlugins(LagomJava)
  .settings(
    version := "1.0-SNAPSHOT"
  )
  .dependsOn(weatherApi)

def project(id: String) = Project(id, base = file(id))

To start with, we’ve specified the organization details, scala version, and disabled Kafka for the current project. Lagom follows a convention of two separate projects for each microservice: API project and an implementation project.

The API project contains the service interface on which the implementation depends.

We’ve added dependencies to the relevant Lagom modules like lagomJavadslApi, lagomJavadslPersistenceCassandra for using the Lagom Java API in our microservices and storing events related to the persistent entity in Cassandra, respectively.

Also, the greeting-impl project depends on the weather-api project to fetch and serve weather stats while greeting a user.

Support for the Lagom plugin is added by creating a plugin folder with plugins.sbt file, having an entry for Lagom plugin. It provides all the necessary support for building, running, and deploying our application.

Also, the sbteclipse plugin will be handy if we use Eclipse IDE for this project. The code below shows the contents for both plugins:

addSbtPlugin("com.lightbend.lagom" % "lagom-sbt-plugin" % "1.3.1")
addSbtPlugin("com.typesafe.sbteclipse" % "sbteclipse-plugin" % "3.0.0")

Create project/build.properties file and specify sbt version to use:

sbt.version=0.13.11

4.2. Project Generation

Running sbt command from the project root will generate the following project templates:

1. greeting-api
2. greeting-impl
3. weather-api
4. weather-impl

Before we start implementing the microservices, let’s add the src/main/java and src/main/java/resources folders inside each of the projects, to follow Maven-like project directory layout.

Also, two dynamic projects are generated inside project-root/target/lagom-dynamic-projects:

1. lagom-internal-meta-project-cassandra
2. lagom-internal-meta-project-service-locator

These projects are used internally by Lagom.

5. Service Interface

In the greeting-api project, we specify the following interface:

public interface GreetingService extends Service {

    public ServiceCall<NotUsed, String> handleGreetFrom(String user);

    @Override
    default Descriptor descriptor() {
        return named("greetingservice")
          .withCalls(restCall(Method.GET, "/api/greeting/:fromUser",
            this::handleGreetFrom))
          .withAutoAcl(true);
    }
}

GreetingService exposes handleGreetFrom() to handle greet request from the user. A ServiceCall API is used as the return type of these methods. ServiceCall takes two type parameters Request and Response.

The Request parameter is the type of the incoming request message, and the Response parameter is the type of the outgoing response message.

In the example above, we’re not using request payload, request type is NotUsed, and Response type is a String greeting message.

GreetingService also specifies a mapping to the actual transport used during the invocation, by providing a default implementation of the Service.descriptor() method. A service named greetingservice is returned.

handleGreetFrom() service call is mapped using a Rest identifier: GET method type and path identifier /api/greeting/:fromUser mapped to handleGreetFrom() method. Check this link out for more details on service identifiers.

On the same lines, we define WeatherService interface in the weather-api project. weatherStatsForToday() method and descriptor() method are pretty much self explanatory:

public interface WeatherService extends Service {
    
    public ServiceCall<NotUsed, WeatherStats> weatherStatsForToday();

    @Override
    default Descriptor descriptor() {
        return named("weatherservice")
          .withCalls(
            restCall(Method.GET, "/api/weather",
              this::weatherStatsForToday))
          .withAutoAcl(true);
    }
};

WeatherStats is defined as an enum with sample values for different weather and random lookup to return weather forecast for the day:

public enum WeatherStats {

    STATS_RAINY("Going to Rain, Take Umbrella"), 
    STATS_HUMID("Going to be very humid, Take Water");

    public static WeatherStats forToday() {
        return VALUES.get(RANDOM.nextInt(SIZE));
    }
}

6. Lagom Persistence – Event Sourcing

Simply put, in a system making use of Event Sourcing, we’ll be able to capture all changes as immutable domain events appended one after the other. The current state is derived by replaying and processing events. This operation is essentially a foldLeft operation known from the Functional Programming paradigm.

Event sourcing helps to achieve high write performance by appending the events and avoiding updates and deletes of existing events.

Let’s now look at our persistent entity in the greeting-impl project, GreetingEntity:

public class GreetingEntity extends 
  PersistentEntity<GreetingCommand, GreetingEvent, GreetingState> {

      @Override
      public Behavior initialBehavior(
        Optional<GreetingState> snapshotState) {
            BehaviorBuilder b 
              = newBehaviorBuilder(new GreetingState("Hello "));
        
            b.setCommandHandler(
              ReceivedGreetingCommand.class,
              (cmd, ctx) -> {
                  String fromUser = cmd.getFromUser();
                  String currentGreeting = state().getMessage();
                  return ctx.thenPersist(
                    new ReceivedGreetingEvent(fromUser),
                    evt -> ctx.reply(
                      currentGreeting + fromUser + "!"));
              });
        
            b.setEventHandler(
              ReceivedGreetingEvent.class,
              evt -> state().withMessage("Hello Again "));

            return b.build();
      }
}

Lagom provides PersistentEntity<Command, Entity, Event> API for processing incoming events of type Command via setCommandHandler() methods and persist state changes as events of type Event. The domain object state is updated by applying the event to the current state using the setEventHandler() method. The initialBehavior() abstract method defines the Behavior of the entity.

In initialBehavior(), we build original GreetingState “Hello” text. Then we can define a ReceivedGreetingCommand command handler – which produces a ReceivedGreetingEvent Event and gets persisted in the event log.

GreetingState is recalculated to “Hello Again” by the ReceivedGreetingEvent event handler method. As mentioned earlier, we’re not invoking setters – instead, we are creating a new instance of State from the current event being processed.

Lagom follows the convention of GreetingCommand and GreetingEvent interfaces for holding together all the supported commands and events:

public interface GreetingCommand extends Jsonable {

    @JsonDeserialize
    public class ReceivedGreetingCommand implements 
      GreetingCommand, 
      CompressedJsonable, 
      PersistentEntity.ReplyType<String> {      
          @JsonCreator
          public ReceivedGreetingCommand(String fromUser) {
              this.fromUser = Preconditions.checkNotNull(
                fromUser, "fromUser");
          }
    }
}

public interface GreetingEvent extends Jsonable {
    class ReceivedGreetingEvent implements GreetingEvent {

        @JsonCreator
        public ReceivedGreetingEvent(String fromUser) {
            this.fromUser = fromUser;
        }
    }
}

7. Service Implementation

7.1. Greeting Service

public class GreetingServiceImpl implements GreetingService {

    @Inject
    public GreetingServiceImpl(
      PersistentEntityRegistry persistentEntityRegistry, 
      WeatherService weatherService) {
          this.persistentEntityRegistry = persistentEntityRegistry;
          this.weatherService = weatherService;
          persistentEntityRegistry.register(GreetingEntity.class);
      }

    @Override
    public ServiceCall<NotUsed, String> handleGreetFrom(String user) {
        return request -> {
            PersistentEntityRef<GreetingCommand> ref
              = persistentEntityRegistry.refFor(
                GreetingEntity.class, user);
            CompletableFuture<String> greetingResponse 
              = ref.ask(new ReceivedGreetingCommand(user))
                .toCompletableFuture();
            CompletableFuture<WeatherStats> todaysWeatherInfo
              = (CompletableFuture<WeatherStats>) weatherService
                .weatherStatsForToday().invoke();
            
            try {
                return CompletableFuture.completedFuture(
                  greetingResponse.get() + " Today's weather stats: "
                    + todaysWeatherInfo.get().getMessage());
            } catch (InterruptedException | ExecutionException e) {
                return CompletableFuture.completedFuture(
                  "Sorry Some Error at our end, working on it");
            }
        };
    }
}

public class GreetingServiceModule extends AbstractModule 
  implements ServiceGuiceSupport {
 
      @Override
      protected void configure() {
          bindServices(
            serviceBinding(GreetingService.class, GreetingServiceImpl.class));
          bindClient(WeatherService.class);
    }
}

play.modules.enabled
  += com.baeldung.lagom.helloworld.greeting.impl.GreetingServiceModule

public class WeatherServiceImpl implements WeatherService {
 
    @Override
    public ServiceCall<NotUsed, WeatherStats> weatherStatsForToday() {
        return req -> 
          CompletableFuture.completedFuture(WeatherStats.forToday());
    }
}

We follow the same steps as we did above for greeting module to register the weather module with Lagom:

public class WeatherServiceModule 
  extends AbstractModule 
  implements ServiceGuiceSupport {
 
      @Override
      protected void configure() {
          bindServices(serviceBinding(
            WeatherService.class, 
            WeatherServiceImpl.class));
      }
}

Also, register the weather module to Play’s framework list of enabled modules:

play.modules.enabled
  += com.baeldung.lagom.helloworld.weather.impl.WeatherServiceModule

8. Running the Project

Lagom allows running any number of services together with a single command.

We can start our project by hitting the below command:

sbt lagom:runAll

This will start the embedded Service Locator, embedded Cassandra and then start microservices in parallel. The same command also reloads our individual microservice when the code changes so that we don’t have to restart them manually.

We can be focused on our logic and Lagom handle the compilation and reloading. Once started successfully, we will see the following output:

................
[info] Cassandra server running at 127.0.0.1:4000
[info] Service locator is running at http://localhost:8000
[info] Service gateway is running at http://localhost:9000
[info] Service weather-impl listening for HTTP on 0:0:0:0:0:0:0:0:56231 and how the services interact via
[info] Service greeting-impl listening for HTTP on 0:0:0:0:0:0:0:0:49356
[info] (Services started, press enter to stop and go back to the console...)

Once started successfully we can make a curl request for greeting:

curl http://localhost:9000/api/greeting/Amit

We will see following output on the console:

Hello Amit! Today's weather stats: Going to Rain, Take Umbrella

Running the same curl request for an existing user will change the greeting message:

Hello Again Amit! Today's weather stats: Going to Rain, Take Umbrella

9. Conclusion

In this article, we have covered how to use Lagom framework to create two micro services that interact asynchronously.

The complete source code and all code snippets for this article are available in the GitHub project.