§Integrating with non Lagom services

§Invoking Lagom services

Lagom service calls are implemented using idiomatic REST. The simplest way to invoke a Lagom service from another framework is to use that frameworks REST client to invoke the Lagom service.

Another way to implement Lagom services, if the client is running in a JVM, is to use the Lagom service interface directly.

§Using the Lagom service client

§Configuring dependencies

To use the Lagom service interface, you will need to add a dependency of the Lagom integration client to your build. If using maven, this can be done by adding the following dependency in your pom:

    <dependency>
        <groupId>com.lightbend.lagom</groupId>
        <artifactId>lagom-javadsl-integration-client_${scala.binary.version}</artifactId>
        <version>${lagom.version}</version>
    </dependency>

Of course, you will also need to add a dependency to the API project that you have created in your Lagom project. For more details, see Understanding your project structure.

§Managing the client factory

The Lagom integration client provides LagomClientFactory creating Lagom client services. This factory creates and manages thread pools and connection pools, so it’s important to manage its lifecycle correctly in your application, ensuring that you only create one instance of it, and to shut it down when you’re finished with it.

A LagomClientFactory needs an ActorSystem and Akka Streams Materializer and therefore there are two ways of creating it depending if your application is already using Akka or not. You can create it by calling one of the following methods:

LagomClientFactory clientFactory =
    LagomClientFactory.create("legacy-system", LagomClientFactory.class.getClassLoader());

or

LagomClientFactory clientFactory =
    LagomClientFactory.create(
        "legacy-system",
        LagomClientFactory.class.getClassLoader(),
        actorSystem,
        materializer);

The first variant should be used in applications that do not have a running ActorSystem. Internally, the LagomClientFactory will create a dedicated ActorSystem and Materializer to be used by the clients. Both will be managed by the LagomClientFactory and will be shutdown when the factory is closed.

We highly recommend you to not use this first variant if your application has already an ActorSystem. The reason for that is that the factory will start its own ActorSystem and will read the same configuration as your default ActorSystem. This can cause a few unexpected errors, for instances, you may get port binding conflicts when both Actor Systems try to bind the akka-remote port.

The second variant should be used in applications that have a running ActorSystem. In which case, we recommend to reuse the existing ActorSystem and Materializer. The passed ActorSystem and Materializer won’t be shutdown when closing the factory.

In both cases you need to pass a service name and a ClassLoader. The service name, will be the name of the client service that is consuming the remote Lagom service, and will impact how calls made through clients generated by this factory will identify themselves. The second argument is a ClassLoader, it will be used to create the service proxy and needs to have the API for the client in it.

When you have finished with the factory, for example, when the system shuts down, you need to close the factory, by invoking the close method:

clientFactory.close();

Typically the factory will be a singleton in your system. If your system is using Spring for example, you would create a FactoryBean that instantiates it, and you would implement a @PreDestroy annotated method that closed the client factory.

§Creating a client

Once you have created a client factory, you can easily create a client using it, for example:

HelloService serviceClient =
    clientFactory.createClient(HelloService.class, helloServiceUri);

Here we’ve created a client for the HelloService using the createClient method. We’ve passed in static URI to tell the client where the HelloService lives, typically you would read this from a configuration file on your service.

You can also pass a list of URIs using createClient, and finally, if your environment is capable of looking up service URIs dynamically, you can pass an implementation of ServiceLocator.

§Working with dev mode

When running your service in development, you can tell the service to use Lagom’s dev mode service locator, using createDevClient. Typically, you would want to have some configuration in your application that tells you whether it is running in development or not, and only create the dev mode client if you are in development. For example:

HelloService helloService;
if (isDevelopment) {
  helloService = clientFactory.createDevClient(HelloService.class);
} else {
  helloService = clientFactory.createClient(HelloService.class, helloServiceUri);
}

This means that you don’t have to worry about what URI your services are running on in development, you just need to ensure the Lagom runAll command has been run to run the service locator.