Integrating Play for Java and Akka
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
The previous two articles in this series, Introduction to Play 2 for Java, and Developing Scalable Web Applications with Play, explored the value of the Play Framework, set up a development environment, wrote a Hello, World application, and then explored Play's support for domain-driven design and its use of Scala templates as we built a simple Widget management application. Now we turn our attention to probably the most exciting part of Play: asynchronous processing. Here we explore Play's support for sending messages to "actors," relinquishing the request processing thread while those actors run, and then assembling and returning a response when those actors complete. Furthermore, we explore integrating Play with Akka so that our play applications can send messages to actors running in a separate Akka server for processing. In short, we're going to learn how to service far more simultaneous requests than we have threads and scale our application almost infinitely.
The code for the examples provided in this article can be downloaded here.
Asynchronous Processing
The Play Framework not only allows you to think in terms of HTTP rather than Java APIs, which alone would be enough to encourage you to adopt it, but it also allows your application to relinquish its request processing thread while executing long-running operations. For example, in a standard web framework, if you need to make a dozen database calls to satisfy your request, then you would block your thread while waiting for the database to respond. If your web container had 50 threads, then at most you could support 50 simultaneous requests. Play, however, allows you to build a message, send it to an "actor," and then relinquish its thread. The actor can then make your database calls for you and, when it is finished processing, it can send your Play application a response message. Play delivers the message to your application, along with the request/response context so that you can respond back to the caller. This means that 50 threads can service far more than 50 simultaneous requests. In addition, the actors to which you send messages do not necessarily need to be collocated with your application; they can be running in an Akka server on another machine. This section demonstrates how to execute actors in the Play JVM, and the next section demonstrates how to execute actors on an external server.
Thus far our controller actions have returned a Result, but now we're going to change them to return the promise of a result: Promise<Result>. Essentially this means that we will "eventually" return a response. Play knows that when it sees a promise for a result that it can suspend processing of that request and reuse the thread for other operations. When the result does arrive, then Play can use a thread to extract the response, convert it to a Result, and return that Result back to the caller.
A full description of Akka actors is beyond the scope of this article, but I need to give you enough to be dangerous (and you can read an article that I wrote about Akka here: http://www.javaworld.com/article/2078775/scripting-jvm-languages/open-source-java-projects-akka.html). Akka implements the Actor Model (http://en.wikipedia.org/wiki/Actor_model), which was defined in 1973 to support concurrent systems. Interest in the Actor Model has reemerged in recent years with the advent of cloud computing: In 1973 it was trying to distribute processing across multiple physical machines whereas now we're trying to distribute processing across multiple virtual machines.
Akka operates through a level of indirection: All actors live in an "ActorSystem" and your application requests a reference to an actor (ActorRef) from the ActorSystem. Your application constructs a message and sends it to the ActorRef. The ActorRef delivers the message to a MessageDispatcher that in turn delivers the message to the Actor's MessageQueue. When the actor is allotted CPU time, the actor's Mailbox checks its MessageQueue and, if there are messages available, the Mailbox removes the message from the MessageQueue and passes it to the Actor's onReceive() method. All this is summarized in Figure 1.
)
Figure 1 Akka's implementation of the Actor Model
The benefit to this approach is that we can have millions of messages passing through a JVM and the application will not crash: Under extreme load the MessageQueue may back up, but the actors will process messages using the JVM's threads as they are able. Furthermore, the indirection allows the actor's location to be decoupled from the client. (The actor may be in the same JVM or across the country running in another data center.)
In this section we want to create an actor in the local JVM and send it a message. Listing 1 shows the source code for our HelloLocalActor class.
Listing 1. HelloLocalActor.java
package actors;
import akka.actor.UntypedActor;
import com.geekcap.informit.akka.MyMessage;
/**
* Local Hello, World Actor
*/
public class HelloLocalActor extends UntypedActor
{
@Override
public void onReceive( Object message ) throws Exception
{
if( message instanceof MyMessage )
{
MyMessage myMessage = ( MyMessage )message;
myMessage.setMessage( "Local Hello, " + myMessage.getMessage() );
getSender().tell( myMessage, getSelf() );
}
else
{
unhandled( message );
}
}
}
Actors extend UntypedActor and override its onReceive() method, which is passed an Object. It typically inspects the type of message and then either handles the message or returns unhandled(message). The message that we're passing around is of type MyMessage, which wraps a single String property named message (shown in Listing 2.) If the message is of type MyMessage, then the HelloLocalActor prefixes the message with "Local Hello, " and notifies our sender by invoking getSender().tell().getSender() returns a reference to the Actor that sent the message and tell() is the mechanism through which we can send a response message. The tell() method accepts the message to send as well as a reference to the sender of the message, which in this case is the HelloLocalActor.
Listing 2. MyMessage.java
package com.geekcap.informit.akka;
import java.io.Serializable;
public class MyMessage implements Serializable
{
private String message;
public MyMessage()
{
}
public MyMessage( String message )
{
this.message = message;
}
public String getMessage()
{
return message;
}
public void setMessage( String message )
{
this.message = message;
}
}
Now that we have an actor that can process a MyMessage, let's add a controller action that can call it. Listing 3 shows the source code for the first version of our Application class, which contains a localHello() action.
Listing 3. Application.java
package controllers;
import akka.actor.ActorSelection;
import akka.actor.ActorSystem;
import akka.actor.Props;
import play.*;
import play.libs.Akka;
import play.libs.F.Promise;
import play.libs.F.Function;
import play.mvc.*;
import views.html.*;
import static akka.pattern.Patterns.ask;
import actors.HelloLocalActor;
import com.geekcap.informit.akka.MyMessage;
public class Application extends Controller {
static ActorSystem actorSystem = ActorSystem.create( "play" );
static {
// Create our local actors
actorSystem.actorOf( Props.create( HelloLocalActor.class ), "HelloLocalActor" );
}
public static Result index() {
return ok(index.render("Your new application is ready."));
}
/**
* Controller action that constructs a MyMessage and sends it to our local
* Hello, World actor
*
* @param name The name of the person to greet
* @return The promise of a Result
*/
public static Promise<Result> localHello( String name )
{
// Look up the actor
ActorSelection myActor =
actorSystem.actorSelection( "user/HelloLocalActor" );
// Connstruct our message
MyMessage message = new MyMessage( name );
// As the actor for a response to the message (and a 30 second timeout);
// ask returns an Akka Future, so we wrap it with a Play Promise
return Promise.wrap(ask(myActor, message, 30000)).map(
new Function<Object, Result>() {
public Result apply(Object response) {
if( response instanceof MyMessage ) {
MyMessage message = ( MyMessage )response;
return ok( message.getMessage() );
}
return notFound( "Message is not of type MyMessage" );
}
}
);
}
}
The Application class contains a static reference to the ActorSystem and initializes as its defined. We need the ActorSystem to host our actors as well as to send and receive messages. The ActorSystem is named, which makes it addressable, and it makes it possible to have multiple ActorSystems in the same JVM. In our case we named our ActorSystem "play", but you could have just as easily named it "foo" or "bar". Furthermore, there is a static code block in which we create the HelloLocalActor. We create actors by invoking the actorOf() method on the ActorSystem (there are other mechanisms, but this is certainly one of the easiest), passing it a Props object with the class that implements the actor. We also pass the actorOf() method the name of the actor so that it will be easier for us to lookup later.
When the localHello() action is invoked, we search for our actor, by name, using the ActorSystem's actorSelection() method. Actors are identified using an actor path, which is of the format:
akka://ActorSystemName@server:port/guardian/TopLevelActor/SubActor
In this case we are looking for an actor in the local JVM and our ActorSystem is already named, so we do not need to specify the ActorSystemName, the server, or the port. There are two guardians in Akka: system and user. System contains all Akka's actors and user contains ours. The HelloLocalActor is defined directly in the ActorSystem, so it is considers a "top-level actor". If it were to create sub-actors of its own, then they would be defined as sub-actors of the HelloLocalActor. Therefore we can find our actor with the path "user/HelloLocalActor". In the next section we'll be looking up an actor that is not in our local JVM, so we'll see a full actor path.
The ActorSelection is an ActorRef, so at this point we just need to construct a message and send it to the ActorRef. We construct a simple MyMessage and then enter the scary-looking code. There's a lot going on in the next line, so let's review what it's doing step-by-step:
- Patterns.ask: This is an Akka function that sends a message asynchronously to an actor (an ActorRef) with a message and a timeout, which eventually returns a response through a scala.concurrent.Future<Object> object. Note that the target actor needs to send the result to the sender reference provided.
- F.Promise.wrap() accepts a Future<Object> and returns a F.Promise<Object>. Akka works in terms of futures, but Play works in terms of promises, so this is just a wrapper to integrate Akka with Play.
- map() accepts a Function that maps an Object to a Result. When we receive our response from the actor, it will be in terms of an Object, but Play wants a Result.
- The Function has an apply(Object) method that accepts an Object and returns a Result. In this case we inspect the message to make sure it is a MyMessage and then return an HTTP 200 OK message containing the text of the message. We could have just as easily passed the MyMessage to a template to render the response, but I wanted to keep it simple here.
Stating this more verbosely, when we call the ask() method, Akka asynchronously sends the message to the specified actor via its ActorRef. Akka immediately returns a Future<Object> that will "eventually" have the response from the actor. Play uses Promises rather than Futures, so the Promise.wrap() method wraps the Future with a Promise that Play knows how to handle. When the actor is complete, the response is sent to the future (Scala code) that is wrapped in the promise, and we provide a mapping function that converts the Object to a Play Result. The Result is then returned to the caller as though the entire operation happened synchronously.
Next, we need to add a new route to the routes file to send a request to the localHello() method:
GET /local-hello/:name controllers.Application.localHello( name : String )
Finally, we need to add Akka support to our build file (build.sbt). Listing 4 shows the contents of our build.sbt file.
Listing 4. build.sbt
name := "SimplePlayApp"
version := "1.0-SNAPSHOT"
libraryDependencies ++= Seq(
javaJdbc,
javaEbean,
cache,
"com.typesafe.akka" % "akka-remote_2.10" % "2.2.3",
"com.geekcap.informit.akka" % "akka-messages" % "1.0-SNAPSHOT"
)
play.Project.playJavaSettings
We could import Akka's actors package, but because in the next section we're going to call an external Akka server, I opted to use akka-remote. Note that the version is not the latest: You need to pair your Play and Akka versions. (I found out the hard way using the latest version and seeing weird errors that did not direct me to the fact that I don't have the correct version.) The notation is a little different from a Maven POM file, but the information is the same:
group ID % artifact ID % version
You'll notice that I have a separate project for akka-messages. We will be serializing MyMessage instances and sending them across the network to the Akka server (called a micro-kernel) so it is important that the messages are identical. Rather than copying-and-pasting the code, I decided to create another project that includes just our message(s) and import that project into both of our projects (Play and Akka).
With all this complete, start Play (execute Play from the command line and invoke the run command from the Play prompt) and open a browser to http://localhost:9000/local-hello/YourName, and you should see "Hello, YourName".
Integration with Akka
When I think about the true power of Play, what comes to mind is a web framework that accepts a request, dispatches work to one or more external servers, and then allows its thread to be used by other requests while the work is completed elsewhere. Play runs on top of Akka, and integrating Akka Remoting into Play is straightforward, so it makes it a natural choice. Listing 5 shows the source code for our actor, which looks remarkably similar to the HelloLocalActor created in the previous section.
Listing 5. HelloWorldActor.java
package com.geekcap.informit.akka;
import akka.actor.UntypedActor;
public class HelloWorldActor extends UntypedActor
{
@Override
public void onReceive( Object message ) throws Exception
{
if( message instanceof MyMessage )
{
MyMessage myMessage = ( MyMessage )message;
System.out.println( "Received message: " + message );
myMessage.setMessage( "Hello, " + myMessage.getMessage() );
getSender().tell( myMessage, getSelf() );
}
else
{
unhandled( message );
}
}
}
This actor receives a message, validates that it is an instance of MyMessage, and returns a response to the sender that is "Hello, " + the body of the supplied message. This is the same functionality as our local actor, but we're going to deploy it to Akka directly.
Deploying actors to an Akka server, which Akka calls a "micro-kernel", requires you to build a "bootable" class that manages the startup and shutdown life cycle events of your actors. Listing 6 shows the source code for our life cycle management class.
Listing 6. MyKernel.java
package com.geekcap.informit.akka;
import akka.actor.ActorSystem;
import akka.actor.Props;
import akka.kernel.Bootable;
public class MyKernel implements Bootable
{
final ActorSystem system = ActorSystem.create("mykernel");
public void shutdown()
{
// Shutdown our actor system
system.shutdown();
}
public void startup()
{
// Create our actors
system.actorOf( Props.create( HelloWorldActor.class ), "HelloWorldActor" );
}
}
Listing 6 creates a class called MyKernel that implements the akka.kernel.Bootable interface. This interface defines two methods: startup() and shutdown(), which are called when the kernel starts up and shuts down, respectively. We create an ActorSystem named "mykernel" as our bootable class is created and we shut it down when the shutdown() method is called. You are free to name your ActorSystem anything that you want: When Play sends a message to our ActorSystem, it will send the name as a parameter in the actor path. In the startup() method we create all our top-level actors, with their names.
To make our actor available remotely, we need to add an application.conf file to the root of our resultant JAR file. In Maven projects, we can put this file in src/main/resources. Listing 7 shows the contents of the application.conf file.
Listing 7. application.conf
akka {
actor {
provider = "akka.remote.RemoteActorRefProvider"
}
remote {
enabled-transports = ["akka.remote.netty.tcp"]
netty.tcp {
hostname = "127.0.0.1"
port = 2552
}
}
}
The application.conf file sets up a remote provider that listens on the local machine on port 2552, which is Akka's default port. This configuration allows external Akka clients to send messages to actors running in our Akka micro-kernel.
Listing 8 shows the contents of the Maven POM file that builds the Akka project.
Listing 8. pom.xml file for Akka Actors
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.geekcap.informit.akka</groupId>
<artifactId>akka-actors</artifactId>
<packaging>jar</packaging>
<version>1.0-SNAPSHOT</version>
<name>akka-actors</name>
<url>http://maven.apache.org</url>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.11</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.typesafe.akka</groupId>
<artifactId>akka-actor_2.11.0-M3</artifactId>
<version>2.2.0</version>
</dependency>
<dependency>
<groupId>com.typesafe.akka</groupId>
<artifactId>akka-kernel_2.10</artifactId>
<version>2.3.2</version>
</dependency>
<dependency>
<groupId>com.geekcap.informit.akka</groupId>
<artifactId>akka-messages</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.3.2</version>
<configuration>
<source>1.6</source>
<target>1.6</target>
</configuration>
</plugin>
</plugins>
</build>
</project>
Listing 8 build our Akka actor and kernel and bundles the application.conf file with it into a single JAR file. The POM file includes the Akka actor and Kernel dependencies, but also includes a reference to our akka-messages project. The source code attached to this article will have that project - you'll need to build it before you can build this project. And remember that we externalized our message to its own project so that we could include it in both the Akka project as well as the Play project.
You can build the project with the following command:
mvn clean install
Now that you have your actor and kernel in a JAR file, you need to set up an Akka environment. You can download Akka from here (http://akka.io/downloads/). I downloaded the previous version (2.2.4) to ensure that it is compatible with the version of Play we installed (2.2.3). The specific versions do not matter, just make sure that when you install both Play and Akka that the versions match up. Download the ZIP file and decompress it to your hard drive. Next, set the AKKA_HOME environment variable to the directory to which you decompressed the Akka archive.
To deploy your actor and kernel to Akka, copy the akka-actors.jar file that you just built to Akka's deploy directory and copy the akka-messages.jar file (that contains the MyMessage class) to Akka's lib/akka directory. With these two files in place, you can launch Akka from the bin directory by executing the following command:
./akka com.geekcap.informit.akka.MyKernel
After the Akka header is displayed, you should see something like the following:
Starting up com.geekcap.informit.akka.MyKernel Successfully started Akka
Now we need to retrofit the Play application to make the remote call to Akka. We already included the Akka remoting dependency in our build.sbt file, but to get called back we're going to need to add the following to the end of our conf/application.conf file:
akka.default-dispatcher.fork-join-executor.pool-size-max = 64
akka.actor.debug.receive = on
akka {
actor {
provider = "akka.remote.RemoteActorRefProvider"
}
remote {
enabled-transports = ["akka.remote.netty.tcp"]
netty.tcp {
hostname = "127.0.0.1"
port = 2555
}
}
}
This will configure Play to listen for callbacks from Akka on port 2555. (The port number doesn't matter; it just needs to be different from the Akka port if you're running them on the same machine.) Next, we're going to add a new route and a new controller action to our Application class. The following shows the new route (added to the conf/routes file):
GET /hello/:name controllers.Application.hello( name : String )
This maps a GET request to hello/:name to the hello() action in the Application class, which is shown in Listing 9.
Listing 9. Application Class's hello() Method
public static Promise<Result> hello( String name )
{
ActorSelection myActor =
actorSystem.actorSelection(
"akka.tcp://mykernel@127.0.0.1:2552/user/HelloWorldActor" );
MyMessage message = new MyMessage( name );
return Promise.wrap(ask(myActor, message, 30000)).map(
new Function<Object, Result>() {
public Result apply(Object response) {
if( response instanceof MyMessage ) {
MyMessage message = ( MyMessage )response;
return ok( message.getMessage() );
}
return notFound( "Message is not of type MyMessage" );
}
}
);
}
The hello() method in Listing 9 looks almost identical to our localHello() method in Listing 3. The only difference is that we changed the actor path from "user/HelloLocalActor" to point to the HelloActor we have running in Akka:
akka.tcp://mykernel@127.0.0.1:2552/user/HelloWorldActor
This actor path can be defined as follows:
- akka: Identifies this as an actor path.
- tcp: Defines the call as using TCP (Transmission Control Protocol), which will be resolved to Netty from the application.conf file.
- mykernel: The name of the actor system, which we defined in the MyKernel class in the Akka project.
- 127.0.0.1:2552: The address and port of Akka.
- user: The user guardian, which is the guardian that manages all our top-level actors.
- HelloWorldActor: The name of the top-level actor to which to send the message.
And that's it. Save your file, start Play if it is not already running, and then open a web browser to http://localhost:9000/hello/YourName
As a response you should see "Hello, YourName". In the Play console, you should see something like the following:
[INFO] [05/23/2014 14:34:32.395] [play-akka.actor.default-dispatcher-5] [Remoting] Starting remoting [INFO] [05/23/2014 14:34:33.490] [play-akka.actor.default-dispatcher-5] [Remoting] Remoting started; listening on addresses :[akka.tcp://play@127.0.0.1:2555]
This says that Play has started remoting and is listening for a response in actor system "play", which is defined in Listing 3, on port the local machine (127.0.0.1) on port 2555, both of which are defined in application.conf.
In the Akka console you should see something like the following:
Received message: com.geekcap.informit.akka.MyMessage@5a5a7c64
This is from the System.out.println() call that we made in the HelloWorldActor class.
Summary
The Play Framework not only provides a natural web-centric paradigm for developing web applications, but it also can be used to asynchronously process requests while not monopolizing threads that are doing nothing more but waiting for long-running operations. We explored Play's asynchronous processing model by first delegating request processing to a local actor running in the same JVM and then sending a message to an Akka micro-kernel for processing on a potentially different server. This is where the true power of Play and Akka comes from: Your Play application can receive requests, dispatch work to a cluster of Akka micro-kernels, and then, when that processing is complete, it can compose a response to send to the caller. And while it is waiting for a response from the remote actors, Play can give up the request processing thread to allow that thread to service additional requests. In short this means that if you have 50 threads in your thread pool, you can satisfy far more than 50 simultaneous requests!