Writing a Play Framework Plugin in Java

By Craig Thomas, Tue 27 January 2015, in category Development

java, play_framework

I really like using the Play Framework to write simple web applications and REST interfaces. One of the interesting things about the Play Framework is that it is meant to be both stateless and asynchronous. The stateless nature of the framework makes it easy to scale very quickly, since all you need to do is deploy multiple instances of your web application in order to serve larger loads.

Sometimes however, you need to introduce some sort of mechanism to create a global variable or object. For example, if your application needs to make an expensive database connection, sometimes it is better to create a single object (or pool of objects) that can handle your database connection, and have your controllers pick those up instead of generating new ones each time a REST endpoint or webpage is served. In this post, I’ll look at creating a Play Framework plugin, and how you can maintain a global state with that plugin.

The Problem

There are times that I have an Android emulator running and I want to issue it external events programmatically. The trick here is that I want to do it from within the emulator. More specifically, when I’m running tests for an application that receives SMS messages, it’s nice to be able to trigger an inbound SMS on demand. You can trigger SMS messages by opening a telnet session to your emulator and issuing the sms command. For example, assuming your emulator is running on port 5554, a typical session might look like this:

telnet localhost 5554

Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Android Console: type 'help' for a list of commands
OK
sms send 5550100 This is a test message!!
OK

The running emulator instantly receives it:

SMS Message

If I’m doing a lot of automated testing directly on the Android emulator, I want the emulated Android test cases to easily trigger an incoming SMS by itself. To get this functionality, I want to spin up a Play application on my testing machine that can open telnet sessions to the running emulators. The application would accept REST calls to generate the required incoming SMS, and post them to the correct virtual device.

Sidenote: how do the tests running on the Android emulator know what emulator they are running on? Easy – the last 4 digits of the emulated device’s phone number are the telnet port that it is running on. The test case can use TelephonyManager getLine1Number() to read the telephone number, and parse the port number. It then passes the port number on to the Play application when it makes the call to the REST API.

The Solution

To do this, I built a telnet manager class that would connect to the emulator, and then allow me to input commands and capture the output. To connect this telnet manager to my Play application, I needed to keep the telnet manager object around in some sort of global variable and make it accessible, since I didn’t want to connect and disconnect from the running emulator every single time I wanted to run a command.

There are two different approaches that would work for creating this type of global object. The first is to create an Actor that would work through Akka. I didn’t investigate how this was done, but instead opted to create a Play plugin. The benefit of creating a Play plugin is that they are very easy to create. The breakdown for creating the Play plugin is as follows:

  1. Create the class that you want to manage your service.
  2. Create a class that implements play.api.Plugin interface.
  3. Add the plugin to your Play configuration.

Creating the TelnetManager

There isn’t too much to say about this step of the solution. In my case, I have a simple TelnetManager class that I am using to connect to a running emulator. With my class, I can open up a connection to a running emulator, and then issue commands to it. The idea is that the Play framework application can open a connection to an emulator, and keep that connection open between different REST calls.

Since I know it’s bad if two different processes try and use the object at the same time, I used a simple lock variable to block until the resource becomes free. This ensures that two processes don’t try and talk to the same device at the same time.

Creating the Play Framework Plugin

All you need to do is implement the play.api.Plugin interface. Minimally, it looks like this:

package plugins;

import models.TelnetManager;
import play.Application;
import play.api.Plugin;

public class AndroidSMSMessagerPlugin implements Plugin {

    private final TelnetManager sTelnetManager = new TelnetManager();

    public AndroidSMSMessagerPlugin(Application app) {
    }

    public void onStart() {
        sTelnetManager.start();
    }

    public void onStop() {
        sTelnetManager.stop();
    }

    public boolean enabled() {
        return true;
    }

    public TelnetManager getTelnetManager() {
        return sTelnetManager;
    }
}

From the above code, you can see that there are only 4 methods that you need to implement in your Plugin:

With those methods implemented, the last step is to configure your Play application to recognize the plugin.

Adding the Plugin to your Play Configuration

The easiest way to add your new plugin is to create a file in the conf of your project called play.plugins. In it, all you need is the following line:

2000:plugins.AndroidSMSMessagerPlugin

The 2000 acts as a priority level. The lower the number, the sooner the plugin is loaded (values can range from 0 – 10000). This can help you control when your plugin is loaded by the framework.

Accessing the Plugin

With everything plugged into the framework, the last thing to do is to actually access the plugin from a controller. You can do it with the following:

TelnetManager tm = Play.application().plugin(AndroidSMSMessagerPlugin.class).getTelnetManager();

As you can see, I now have a reference to the global TelnetManager object!

Wrapping Up

In this post, I went over how to create a Play framework plugin, and why you might need one. By implementing only 4 methods, you can easily create your own plugin to the Play framework.