§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 invoke 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 on the Lagom client to your build. If using sbt, this can be done by adding the following dependency:
libraryDependencies += lagomScaladslClient
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.
§Creating a LagomClientFactory
In a LagomApplication
you can create clients by calling the serviceClient
method. In non Lagom applications you need to first to create a LagomClientFactory
. This factory will give you access to an equivalent serviceClient
method to generate clients.
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 extending one of the following abstract classes: LagomClientFactory
or StandaloneLagomClientFactory
.
In both cases, the constructor takes two arguments, 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.
There is one more component that you’ll need to provide when creating a LagomClientFactory
, that is a service locator. It is up to you what service locator you use, it could be a third party service locator, or a service locator created from static configuration.
Lagom provides a number of built-in service locators, including a StaticServiceLocator
, a RoundRobinServiceLocator
and a ConfigurationServiceLocator
. The easiest way to use these is to mix in their respective `Components` traits.
The StandaloneLagomClientFactory
variant is useful for applications that do not have a running ActorSystem
. Internally, the StandaloneLagomClientFactory
will create a dedicated ActorSystem
and Materializer
to be used by the clients. Both will be managed by the StandaloneLagomClientFactory
and will be shutdown when the factory is closed.
For example, here’s a StandaloneLagomClientFactory
built using the static service locator, which uses a static URI:
import java.net.URI
import com.lightbend.lagom.scaladsl.client._
import play.api.libs.ws.ahc.AhcWSComponents
val clientFactory =
new StandaloneLagomClientFactory("my-client", classOf[StandaloneLagomClientFactory].getClassLoader)
with StaticServiceLocatorComponents with AhcWSComponents {
override def staticServiceUri = URI.create("http://localhost:8080")
}
We highly recommend you to not use StandaloneLagomClientFactory
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 LagomClientFactory
variant is useful for applications that have a running ActorSystem
. In which case, we recommend to reuse the existing ActorSystem
and Materializer
.
The easiest way to reuse your existing ActorSystem
and Akka Stream Materializer
is to extend the LagomClientFactory
and add a constructor where you can pass them as arguments.
For example, here’s a LagomClientFactory
built using the static service locator, which uses a static URI, and reusing an ActorSystem
and Materializer
created outside it:
import java.net.URI
import com.lightbend.lagom.scaladsl.client._
import play.api.libs.ws.ahc.AhcWSComponents
class MyLagomClientFactory(val actorSystem: ActorSystem, val materializer: Materializer)
extends LagomClientFactory("my-client", classOf[MyLagomClientFactory].getClassLoader)
with StaticServiceLocatorComponents
with AhcWSComponents {
override def staticServiceUri = URI.create("http://localhost:8080")
}
val actorSystem = ActorSystem("my-app")
val materializer = ActorMaterializer()(actorSystem)
val clientFactory = new MyLagomClientFactory(actorSystem, materializer)
When you have finished with the application, for example, when the system shuts down, you need to stop the factory, by invoking the stop()
method:
clientFactory.stop()
You may want to override the stop()
method when implementing your own LagomClientFactory
. For instance, in case you are reusing an existing ActorSystem
, but prefer to use a internal Materializer
. In which case, you can use this method to shutdown the Materializer
only. When overriding this method, make sure you also release the internally managed resources by calling LagomClientFactory.releaseInternalResources()
method.
Typically this 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 stopped the factory client.
§Creating a client
Once you have created the factory client, you can easily create a client using it, for example:
val helloService = clientFactory.serviceClient.implement[HelloService]
Here we’ve created a client for the HelloService
the same way we would in a regular Lagom application, using serviceClient.implementClient
.
§Working with dev mode
When running your service in development, you can tell the service to use Lagom’s dev mode service locator, by adding a dependency on Lagom’s dev mode support:
libraryDependencies += lagomScaladslDevMode
Then, when you instantiate your factory client, rather than mixing in your production service locator, you can mix in the LagomDevModeServiceLocatorComponents
trait to get the dev mode service locator:
import java.net.URI
import com.lightbend.lagom.scaladsl.client._
import play.api.libs.ws.ahc.AhcWSComponents
import com.lightbend.lagom.scaladsl.devmode.LagomDevModeServiceLocatorComponents
val clientApplication = if (devMode) {
new StandaloneLagomClientFactory("my-client") with AhcWSComponents with LagomDevModeServiceLocatorComponents
} else {
new StandaloneLagomClientFactory("my-client") with StaticServiceLocatorComponents with AhcWSComponents {
override def staticServiceUri = URI.create("http://localhost:8080")
}
}
You’ll also need to configure your application to tell it where the service locator is running, this can be done by passing a system property to your application when it starts up, for example:
-Dlagom.service-locator-url=http://localhost:9008
Alternatively, you can configure it programmatically by overriding the devModeServiceLocatorUrl
value on the LagomDevModeServiceLocatorComponents
trait:
new StandaloneLagomClientFactory("my-client") with AhcWSComponents with LagomDevModeServiceLocatorComponents {
override lazy val devModeServiceLocatorUrl = URI.create("http://localhost:8001")
}