Chapter 13. Writing Play Plugins

In order to make our applications manageable, we break them down into independent modules. These modules can also be extracted into individual projects/libraries.

A Play plugin is nothing but another module with an additional ability—of binding tasks before starting, on starting and/or stopping a Play application. In this chapter, we will see how to write custom plugins.

In this chapter, we will cover the following topics:

• Plugin definition

• Plugin declaration

• Exposing services through plugins

• Tips for writing a plugin

Plugin definition

A Play plugin can be defined by extending play.api.plugin, which is defined as follows:

trait Plugin {

  //Called when the application starts.
  def onStart() {}

  // Called when the application stops.
  def onStop() {}

  // Is the plugin enabled?
  def enabled: Boolean = true
}

Now, we might be in a situation where we need to send an e-mail when an application is started or stopped so that the administrator can later use this time interval to monitor the application's performance and check why it stopped. We could define a plugin to do this for us:

class NotifierPlugin(app:Application) extends Plugin{ 

  private def notify(adminId:String,status:String):Unit = { 

    val time = new Date() 

    val msg = s"The app has been $status at $time" 

    //send email to admin with the msg

    log.info(msg)

  } 



  override def onStart() { 

    val emailId = app.configuration.getString("notify.admin.id").get 

    notify(emailId,"started") 

  } 



  override def onStop...

Plugin declaration

Now that we have defined a plugin, let's see how the Play Framework identifies and enables it for the application. ApplicationProvider for the production and development mode (static and reloadable applications, respectively) both rely on DefaultApplication, which is defined as follows:

class DefaultApplication(
  override val path: File,
  override val classloader: ClassLoader,
  override val sources: Option[SourceMapper],
  override val mode: Mode.Mode) extends Application with WithDefaultConfiguration with WithDefaultGlobal with WithDefaultPlugins

The trait WithDefaultPlugins line is responsible for binding the plugins to application's life cycle. It is defined as follows:

trait WithDefaultPlugins {
  self: Application =>
  private[api] def pluginClasses: Seq[String] = {
    import scala.collection.JavaConverters._
    val PluginDeclaration = """([0-9_]+):(.*)""".r
    val pluginFiles = self.classloader.getResources("play.plugins").asScala.toList ++ self.classloader...

Exposing services through plugins

Some plugins need to provide users with helper methods to simplify transactions, whereas others need not do anything besides some tasks to be added in the application's life cycle. For example, our NotifierPlugin just sends e-mails on start and stop. Then, the methods of our CassandraPlugin can be accessed using the plugin method of play.api.Application:

object CassandraHelper {
  private val casPlugin = Play.application.plugin[CassandraPlugin].get

  //complete DB transactions with the connection pool started through the plugin
  def executeStmt(stmt:String) = {
    casPlugin.session.execute(stmt)
  }
  
}

Alternatively, the plugin can also provide a helper object:

object Cassandra {
  private val casPlugin = Play.application.plugin[CassandraPlugin].get

  private val cassandraHelper = casPlugin.helper

  /**
   * gets the Cassandra hosts provided in the configuration
   */
  def hosts: Array[java.lang.String] = cassandraHelper.hosts

  /**
    * gets the...

Tips for writing a plugin

Here are some tips for writing a plugin:

• Before you start writing a plugin, check if you really need one to solve your problem. If your problem does not require meddling with the application's life cycle, it's better to write a library.

• While writing/updating a plugin, simultaneously build an example Play application that uses the plugin. This will allow you to check the functionality of it thoroughly with only the additional overheads of publishing the plugin locally for every change made.

• If the plugin exposes some services, try to provide a helper object. This makes it easier to maintain the API's consistency and also simplifies the developer experience.

  For example, most of the plugins provided by Play (such as akka, jdbc, ws, and so on) provide helper objects through which the API is available. Internal changes to the plugin do not affect the public API exposed through these objects.

• If and where possible, try and back up the plugin with sufficient tests.

• Document...

Summary

The Play plugins provide us with the flexibility to perform specific tasks at a desired stage in the application's life cycle. Play has some plugins that are commonly required by most applications, such as web services, authentication, and so on. We discussed how the Play plugins work and how we can build custom plugins to meet different requirements.