Running Play 1 natively on OpenShift

So for a while now, I have been using Heroku for my hosting of Play applications. It is easy, very fast to deploy and therefore first into my mantra for development (be productive). My only issue with Heroku is the database. When I created the Play developer map, I knew that the database size was likely to be an issue, so I worked around the problem, by using a cloud database that I already had an account for.

Recently however, I have been working with some friends and we wanted to build a site which again would likely break the Heroku limit of 10K rows in the database. However, this time I didn’t want to be mixing my personal cloud db account with an application that we may want to scale up at any time. So, I went looking for an alternative solution. The options are actually pretty limited if you don’t want to splash out immediately. So the one that intrigued me the most was OpenShift. It gives you 1Gb, regardless of whether this is used for DB, application files or other.

The downside of OpenShift, is that Play is not supported as a native application server, and I needed the native features (too many potential surprises when using a WAR wrapper around a Play application). OpenShift has the concept of DIY cartridges though, that allow you to install whatever Java process you like, as long as it binds to the correct port number. So it can be done!

I spent a good few days messing around with different configurations, following other’s blog posts and installing VMs (the Play OpenShift module doesn’t work on Windows, so I tried using a Ubuntu VM on VirtualBox to trial that approach!).
Anyway, the good news is that it is relatively straightforward, once you have jumped over the hurdles in your way, so this is intended to save anyone who wants an alternative to Heroku a great deal of time in deploying an OpenShift application natively.

In a nutshell, the steps are

1. Sign up to OpenShift
2. Install Ruby and GIT (I deployed from Windows, so used Ruby for Windows and GIT for windows)
3. Install RHC (red hat console) using the Ruby Gem — gem install rhc
4. Create an application on OpenShift using a DIY cartridge
5. Put your application code in the cloned directory
6. Copy the open-shift hooks (see code below) into the hooks directory, which will install Play on the DIY cartridge, and correctly start/stop Play when needed
7. Set up the application.conf to work with OpenShift ports/db/etc
8. GIT Add/Commit/Push, to push the code to OpenShift, and watch the magic happen!

Step 1 – 3 will only ever need doing once. Once configured, each modification simply needs a GIT add/commit/push to see your changes running (Step 8). Step 4 to 7 should be a case of copy/paste. So, hopefully, we can have you up and running in no time.

The Detail

Steps 1, 2 and 3 – SignUp and Install Software
I won’t go into detail on Step 1 to 3, as the OpenShift information does a very good job of doing so. So, follow steps 1, 2 and 3 on the OpenShift Setup page and install the necessary tools for your platform (Ruby, GIT and RHC) plus sign up for an account and set up RHC.

Step 4 – Create an application
Before running the following command, make sure a directory with the same name of the app you want to create doesn’t already exists, otherwise the git clone will fail. Once you are happy, run the following code from the command prompt.
rhc app create #appname# diy-0.1

Replacing #appname# with the name of your application. This will create a DIY cartridge for you. This will automatically call GIT clone, to clone the application on to your local machine. If for some reason you have created an application using the Web site at OpenShift, you can use git clone to clone the repo to you local machine, but in our example, you don’t need to do this.

The output will also tell you the URL where you will be able to access your application, so keep a note of it at this point!

If you want a Database (which was kind of my whole reason for coming to OpenShift), then follow this command with

rhc cartridge add mysql-5.1 -a #appname#

Again, replace #appname# with your application name you set up in the previous command.

Step 5 – Develop your Play application
Store all your play application code inside the cloned repository, in the standard Play structure. If you have already started a play app, and are just looking to deploy it, you can safely just copy all the play code into the cloned repo, so that app, public, conf, lib etc are all at the same level as the .openshift directory. If you are starting a new application, create a new application with a different name (otherwise Play will complain a directory already exists), and copy the contents of the new application into the cloned repo.

You directory structure should look something like

#appname#
|+ .openshift
|+ app
|+ conf
|+ diy
|+ lib
|+ misc
|+ public


You can still run play run from this structure as you did before.

Step 6 – Get the open_shift hooks!
The open shift hooks are a set of bash scripts that are executed at certain stages of the server’s lifecycle. It has scripts for things such as pre-build, start, stop etc. These are the scripts that will, install Play if it doesn’t already exist (so it will only install it once, unless you specify a new version), start the server and shutdown the server when OpenShift spins up and spins down instances. This is the bulk of the work for an OpenShift DIY cartridge. Fortunately, you can copy the code verbatim.

When you created the app, and the repo was cloned, a set of empty action_hooks were created and downloaded. There should have been 6 in total. These are

• Build – We can leave this blank
• Deploy – We can leave this blank
• Post-Deploy – We can leave this blank
• Pre-Deploy – This is where we will download and configure Play
• Start – This will start a Play instance
• Stop – This will stop a Play instance

So, we have 3 scripts we need to populate, and to make things easier, we will also create a shared script to help set up the configuration variables which will allow us to get data from our Play application.conf as well. These scripts were written by opensas, but I have updated them as there have been a few platform changes since his version was published.

Copy the following code into the action_hooks directory, and we are almost good to go!

Go to https://github.com/codemwnci/play-openshift, and copy the files into your action hooks directory.

NOTE: In the start script, I have configured the timezone to be for London (as OpenShift is US based, and most of my web apps are for UK based). If you don’t care about the default timezone, just delete the
-Duser.timezone=Europe/London
in the start script, or if you want a different timezone, update the value before you deploy your application.

Step 7 – Set up the application conf
Inside the scripts above, Play is configured to start with the ID of openshift. This means that we can keep our openshift config and local config completely separated. So, inside of your application.conf, place the following pieces of config.


# Openshift id configuration
# ~~~~~
%openshift.application.mode=prod
%openshift.http.port=${OPENSHIFT_INTERNAL_PORT}
%openshift.http.address=${OPENSHIFT_INTERNAL_IP}

# openshift mysql database
# ~~~~~
%openshift.db=${OPENSHIFT_MYSQL_DB_URL}#appname#
%openshift.jpa.ddl=update


Replace #appname# with the name of your application (the same name as you set up in step 4). This allows Play to use the short db configuration, rather than the 4 individual parameters.

Step 8 – Commit and Deploy

Finally, we are ready to deploy our app. So quite simply we run three simple GIT commands.

cd #appname#
git add .
git commit -m "deploy to OpenShift"
git push


If you want to see the log files for your app running, you can tail the logs by running
rhc tail #appname#

Again, replace #appname# with the application name set up in step 4.

Now, all you need to do is to browser to the URL that you noted in Step 4, and you are done!

Enjoy

I hope this saves you hours of effort. The time it has taken me to type this up hopefully will be less than the time it would take you to figure all this out through trial and error, like I did. Enjoy.

And for those following the Yalp progress. I will create a Quick starter guide for Yalp as well, when it gets closer to a release candidate.

A new life for Play!yalP

It’s been a while since I blogged last. The world of Play (certainly Play 1.x) has slowed, I guess as would have been expected when it was put into maintenance mode. I have also been doing lots of things Play related, but certainly nothing new. Suddenly, within a week of each other, I have 2 Play related stories to share.

First of all, Play is getting new life pumped into it. Secondly, I have been playing with OpenShift. I’ll come back to OpenShift later (maybe tomorrow), but for now let’s talk about Yalp.

After months of talking about the concept of forking Play and creating a new framework, the community has finally kicked into life and a new framework has been initialised. There have been a number of discussions on the playone discussion group (separated because of the noise of Play 2 in the Play google-group was making it hard to see Play 1 issues).

The first things have been to decide on a name, figure out some framework level issues (like the build system) and get the guiding principles in place. Helena Hjerten pointed out that searchable is a key issue, and a name that isn’t generic is a huge plus, so Nico suggested Yalp! Following a democratic survey, the name has been agreed, and the process of forking away from Play 1 has started.

It is early days and the community could really do with your help. If you have not already moved across to Play 2, and don’t intend to, then maybe join in on the discussion for the direction, scope and requirements of this evolving framework.

I for one hope that it is a success. I don’t have anything against Play 2, I think for certain requirements it is excellent, but for the majority of web applications I am building at the moment, the simplicity and productivity Play 1 gave me would still make me choose Play 1. The only downside is it’s no longer evolving and hopefully Yalp will solve this.

Community Split in Two?

I have just returned from a short trip to Rome on business. I didn’t have much access to email, so I came back to a large number of emails, many of which were from the ever increasing play framework digest emails I get from Google groups. Nothing to different yet, except when I started reading, I was amazed by the reactions to the “Open Letter” thread. If you haven’t read it, then feel free to go to Google Groups and have a read, but in summary it simple read ‘I don’t like Play 2, I don’t like Scala, the Play guys have messed up’.

Quite simply, the haters are wrong, simple as that. The Play team created a fantastic framework in Play 1.x. Even at 1.0 it was way ahead of the other frameworks, and continued to push the boundaries through 1.1 and 1.2. In Play 2.0, the team have taken a different direction from what made Play 1.x special, but have again built a fantastic framework.

Now, if I were to build a new web application, of course I would choose Play. Next question would be which one? Well, it depends on the project I am undertaking, but as of yet I have not come across a problem that Play 1.x could not solve. So, I would probably stick with Play 1.

I don’t feel proficient enough in Scala to jump onto the Scala version of Play, so if I did decide to go for a Play 2 app, I would choose Java. Indeed, I am looking forward to Nicolas’s book on Play 2 with Java. I will more than likely also get Peter Hilton’s book (Play 2 with Scala), but the Java book will be much more beneficial for me. Many people have argued that you need to know Scala to write views etc, but that is not true. I had never used Groovy before I started building Play apps, but I picked groovy up in no-time writing my views, and I have already found the same is true in Play 2. Also, as a side note, you can simply use the Groovy plugin and write your views in good-old Groovy.

Now, I understand why people aren’t fully bought into Play 2 yet, I get it. I am still so happy with Play 1.x, I am not ready to move across yet. But what I don’t get is why people are so upset that Play 2 exists? It has its place, and will grow into another great framework, and I will be a better professional for knowing both technologies.

Be grateful to Guillaume and the team for open sourcing the Play framework and continuing to support both 1.x and 2.x. They saved the Java world from the tedium of J2EE frameworks and made developing fun again. If you don’t like Play 2.0, don’t use it, continue to use Play 1.x.

Playframework, Twitter Bootstrap and Google Maps API

So, what did you do over the Christmas break? Presents, plenty of family time, kick back a little? I did all that and wrote a little web application as well. I thought I would share a little insight into how I got on.

Background

A while back, I created a publicly shared google map so that anyone interested in Play framework could add themselves to the map. A decent number of people signed up, but it was a pain to maintain. There was no control over who could put what where. For example, someone could delete someone else’s pinpoint, change someone else’s details, or the most common issue, overwrite the play framework description and URL’s. So, I decided to create a web application that would allow the community to have a developer map, but without the issues of a simple shared google map.

The tools

Obviously, I used the Playframework, but additionally I decided to Bootstrap from Twitter. Bootstrap, if you haven’t used it yet, is a CSS base that offers a way to develop clean designs and neat interfaces. There are plenty of blogs already about how to use bootstrap, and the documentation itself is pretty complete, but suffice to say, it made the job of building the UI significantly easier. As I am not a naturally artistic person, Bootstrap has allowed me to build a UI I am proud of, without having to suffer for the cause. It fits in with the “just-works” approach of Play, it makes what should be simple, simple.

Secondly, I used Google Maps to render the maps and the icons on top of the maps. I have used Google Maps before, but decided to check out Bing Maps before making my final choice. Put simply, I found Google Maps to do everything I needed, with relative ease, and found no reason why Bing maps could be a better choice.

Quite simply, Play, Bootstrap and GoogleMaps work amazingly well together.

Deployment

As most people tend to do, I decided to deploy the code onto Heroku. I have used Heroku a few times previously, and have had good experiences with it. I was tempted to try something else, due to the limit on the database size of the free account, but as I already have hosting elsewhere, I decided to just use the database on my paid-for hosting alongside Heroku as the application server. Even with this separation, the response times for the application are excellent. It has made me wonder whether there is a gap in the market for a low-end Database-as-a-Service facility to bridge the gap between the Heroku Postgres offerings.

I did have one issue with the deployment, which you may want to be aware of. My views were all lowercase HTML files, rather than camelCase, which was the case for my controller actions. On my Macbook Pro this made no difference, but as soon as I deployed to Heroku I started getting errors. It took me a while to figure this out, because the error logging wasn’t working ver well. Unfortunately I had already committed my code to the local git repository on my mac, which did not care about case differences, so I had to fight with a few git mv commands to move the files to uppercase equivalents. Other than that, the whole thing has worked out pretty well.

Next Steps

Well, its still in beta, so if you guys like it, and it starts to take off, expect more features to start appearing. What I am hoping for is for the word to spread, so that more and more people add themselves to the maps (why not start with the play framework map). Additionally, I would hope that people will create maps for other technologies that they are interested in.

If you have any thoughts or comments, please feel free to get in touch!

Play Hackathon

Get Hacking!

Inspired by the National Novel Writing Month (NaNoWriMo), this competition is aimed at teams of Play developers to produce awesome applications during the month of November. At the end of November, the finished applications will be judged (by the Play Community) to see who has the best application, and which team has won.

Rules

• Start developing 1st November 2011
• Finish developing 30th November 2011
• Judging will start 1st December for 1 week
• Winners will be announced 8th December
• Teams up to 5 members
• Your application must have an about page, or popup, stating it was developed as part of this event and using the Play Framework

Sponsors and Prizes

If you would like to be a sponsor, or donate prizes for this event, please get in contact with me.

Register
To sign up and register for the event, just go along to the Registration page, hosted on Heroku.

I will post another short blog later this week on how simple it was to get up and running on Heroku.

Hidden Features of the Play Framework Routes File

Background

Today, an interesting question was raised at Stackoverflow regarding if it were possible to define Dev/Prod mode specific routes in the Routes file.

The simple answer, was that I didn’t know, but I had an theory that this could be possible, so I threw together a quick prototype to see if it would work.

The premise of the idea was that the routes file does allow scripting to take place, which I have used before to define a Context, which is the agreed way to for managing the war context when deploying to Tomact and other Servlet containers.

So, taking the idea that scriptlets are possible in the routes file, I wondered if this could be taken a step further, whereby logic could be carried out in the routes file, rather than simple assignment scriptlets.

The prototype

The prototype itself was pretty simple. I started a new play project

play new routesproto

and started the Play server.

play run routesproto

I then modified the Application.java to have a few actions, which simply returned a little text to show the action completed successfully. There was simply no need to write templates for the actions, as that was not what I wanted to prove.

public class Application extends Controller {

    public static void index() {
        render();
    }
	
    public static void noDev() {
        renderText("NoDev");
    }
    public static void noProd() { 
        renderText("NoProd");
    }
}

I then went about making my routes file Dev and Prod specific. I created a few routes per environment as follows.

# Home page
GET     /                                       Application.index

# Ignore favicon requests
GET     /favicon.ico                            404
# Map static resources from the /app/public folder to the /public path
GET     /public/                                staticDir:public

%{ if (play.mode.isProd()) { }%
GET		/route1									Application.noDev
GET		/route2									Application.noDev
GET		/route3									Application.noDev
%{ } }%


%{ if (play.mode.isDev()) { }%
GET		/route4									Application.noProd
GET		/route5									Application.noProd
GET		/route6									Application.noProd
%{ } }%

*       /{controller}/{action}                  {controller}.{action}

So, what’s going on in here? Well, all the main (shared) routes are held at the top of the routes file, and then anything that becomes specific to Dev or Prod mode are placed at the bottom. As usually is the case, the catch-all should be last, so after the second if tag is closed, we follow it with the catch-all route.

The following line is responsible for the logic in our routes file.

%{ if (play.mode.isDev()) { }%

and all routes between this piece of logic, and the closing of the if statement, indicated by the following line, are enabled.

%{ } }%

This simple line simply checks what Mode the application is running in, and if it is running in Dev mode, then the routes defined in between the opening and closing parenthesis become available.

Conclusion

I do not expect this syntax to immediately find its way in to every Play application routes file, but I no doubt think that it will be useful to many of us Players. Indeed, without the Stackoverflow question, I would never have even considered experimenting whether this method was actually possible or not, so thanks to Roshan for raising the question.

Websockets in Play

It has been nearly 4 months since I released the first beta of the Play Framework eBook, quickly followed by the final release accompanied with the paperback edition. Comments and feedback have been fantastic, so thank you all!

I released the book fully updated to the 1.1 version of Play, and now 4 months later, Play 1.2 has been released with a host of new features. As a quick snapshot these features include

• Dependency Management – using Apache Ivy
• Evolutions – for tracking and organising changes to your database schemas
• H2 in memory database – replaces the older HSQLDB, and comes with a web console accessible using the URL /@db
• Updates to the TestRunner
• Plus many bug fixes and small enhancements to the Play codebase

All of these features sound absolutely great, but there is one set of features that I have been really looking forward to, and that is WebSockets!

Using WebSockets
So, why so exciting? Well quite simply put, a few years ago, in my spare time I used to write Java Swing based multi-player turn based games. Usually they were clones of popular board games, but they had a real problem! No-one really enjoyed downloading and installing a game. They wanted it on-demand, in a browser, easily accessible. But Web programming did not really lend itself well to this type of world. Play made it very easy to come close using AJAX and its long-polling method (discussed in Chapter 12) of suspending the HTTP request until there is an update, but for me I was eager for Websockets.

I finally got round to playing with Websockets this weekend and I must say, I am impressed. The Play Dev guys have done a great job with this. The documentation is not fantastically verbose, so this post is an attempt to make life a little easier for anyone wanting to play with Websockets using my favourite framework!

What do you need
Quite simply, you need Play 1.2 and a web browser that support websockets. So, switch off IE (even if you have IE9!), and use Chrome. If you have Firefox or Opera, the websocket protocol has been disabled due to some security issues, which is disappointing, but these will be cleared up at some point, so for now I will keep learning and playing with Websockets as they will be a great competitive advantage later.

Let’s try it out
Unlike the Long Polling method, which would check the database for changes to the model at predefined intervals, the idea of a websocket is to be always open, waiting for an event, and then broadcasting that event to everyone who needs to know. Therefore, the way to achieve this in Play is to have a Stateful object residing on the server side. I know this breaks a lot of the stateless, RESTful ideals of Play, but it is the only way to make this work. So, lets start with out Stateful Model.

Create a new application called websocket.

play new websocket

Now, create a new file called StatefulModel.java in the app/models directory and add the following code.

package models;

import play.libs.F;

public class StatefulModel {
   public static StatefulModel instance = new StatefulModel();
   public final F.EventStream event = new F.EventStream();

   private StatefulModel() { }
}

So, a very simple class. It is has a private constructor and a single static instance variable to enforce the Singleton pattern, meaning only a single instance of this model can exist on the server. The only other attribute is an EventStream object. This is an important piece. The EventStream is the core of the WebSockets implementation in Play. It allows events to be published, which notifies any waiting listeners that an event has been published. In this example, we are using a standard EventStream, which just gives access to the current event. Play also provides an ArchivedEventStream (check out the chat sample application to see it in action), which gives access to all the archived messages as well. To explain this EventStream concept in more detail, lets take a look at the Controller.

Open the Application.java in the app/controllers directory, and add the following code.

package controllers;

import play.mvc.*;
import models.*;

public class Application extends Controller {

   public static void index() {
      render();
   }

   public static class WebSocket extends WebSocketController {

      public static void listen() {
         while(inbound.isOpen()) {
            String event = await(StatefulModel.instance.event.nextEvent());
            outbound.send(event);
         }
      }
   }
}

So, not a lot going on here either. The index action will simply render the index page, and then we have a listen action inside a WebSocket static class. The WebSocket static class implements a new type of controller introduced in Play 1.2 called WebSocketController. The difference between a WebSocketController and a standard Controller is that it does away with the request/response model, and in its place has an inbound and outbound model. Here, the code simply loops while the inbound is open (which means the browser is still open, and the web socket is still connected). We then wait for a new event from our StatefulModel’s EventStream, by calling nextEvent.

The await function replaces the suspend function in play1.1. The await function will suspend the http request, freeing up the play framework to continue to process requests, until a new event is added to our Stateful Model, at which point the code will continue processing from the point where it left off. This is another important change in Play1.2. It does not call the method from the beginning again, it carries on where it left off, making the code more readable.
Once the code continues it sends the data from the event to the outbound, which sends the event back to the web browser.

So, how does the browser deal with it? Well, it is again really simple.
Open views/application/index.html and add the following code.

#{extends 'main.html' /}
#{set title:'Home' /}

<div id="socketout"></div>

<script type="text/javascript">
    // Create a socket
    var socket = new WebSocket('@@{Application.WebSocket.listen}')

    // Message received on the socket
    socket.onmessage = function(event) {
        $('#socketout').append(event.data+"<br />");
    }
</script>

So, all we have here is a DIV tag where we will output our Web Socket events, and a bit of javascript that, a) creates the websocket connection, and b) deals with the on message event by appending the data to the DIV.

One final piece before we start to add events to our websocket, is the routes file. Unlike the normal Catch-All request, this does not work, as the catch all works on Controller.action name, and we have also a static class to contend with as well. Therefore, for our routing to work, we also need to add a route. Open the routes file and add the following route next to the homepage

WS      /socket                                 Application.WebSocket.listen

Note, the WS as the HTTP Request type, to describe a WebSocket request. The rest of the route is accessed as you would expect any other route to be configured.

That is our websocket implementation up and running. The final part however is to start adding some events. If we started our application now, we would just see a blank page. Our websocket would be open, but there would be no data coming back to us from the server. So, lets create an asynchronous job to start putting some messages on the EventStream.

Create a new directory called app/jobs, and then create a file called Startup.java. Add the following code.

package job;

import play.jobs.*;
import models.StatefulModel;

@OnApplicationStart(async = true)
public class Startup extends Job {
   public void doJob() throws InterruptedException {
      int i = 0;

      while (true) {
         i++;
         Thread.sleep(1000);
         StatefulModel.instance.event.publish("On step " + i);
      }
   }
}

This is a simple startup job, that has been set to run asynchronously. It simply loops forever (or until the server is stopped) and on each iteration, it sleeps for 1 second, and then publishes an event to our StatefulModel’s EventStream with a String saying “On Step ” followed by the count. This will continue until the server is stopped.

To get this code to execute, we needed to specify the @OnApplicationStart was to run in async mode. Without this setting, the Bootstrap job would be configured so that it MUST complete before the first request can be executed. This makes sense, as if we are using the Bootstrap job to read runtime settings for our application, we would not want it to start until it had done all of its work. In this case however, we just want it to run in parallel.

If you now start the server with

play run websocket

Now point your browser at localhost:9000, you should see your browser start counting up from 1. But what if you open another web browser? You will see that it will start counting in time with the other browser. The event is effectively broadcasted to all listening browsers. Obviously this is by design and you could tailor the way in which you build your application, but the concept is a powerful one.

And before I sign off, another big thank you to the Play developers. This request for Websockets came directly from the very active Play community, and the Play Dev guys implemented superbly whilst staying true to the framework. A fine piece of software engineering.

Playframework Dev Mode: Never use in Production

It may sound like an obvious point, but until recently the major reason I had for setting my applications to use PROD mode when I move my applications to a production environment, was so that my source code would not be visible in the event of a server side error. However, whilst looking through the source code today, I found a major compelling reason to never use Dev mode in a production environment.

First of all though, here a few things that Play does when you move into production mode that makes it a good idea to use the setting.

• Play precompiles your source code for you, and does not check for code changes on the fly, adding a slight performance benefit
• Play starts the application immediately (including any bootstrap jobs), rather than waiting for the first request, again adding a small performance benefit for first use
• The 500 (server error) and 404 (page not found) pages do not show source code or your routes configuration, but instead show a standard error page
• Runs more HTTP threads to handle incoming requests (unless specifically set in the application.conf). The exact value set is number of processors + 1

So all sounds pretty sensible, but not entirely critical. So, here is why it is critical.

/@kill

Just like the @tests and @documentation URLs that can be used in Play, there is a largely unknown URL called @kill. As the name suggests, it simply performs a System.exit(0), which shuts down the Play server. The code first checks that the system is in Dev mode, and if it is, and the @kill request was received, the server is killed.

You will also get a nice output message printed to the logs @KILLED. Not exactly what you want your average user to be able to do on your shiny new application. Not that your average user will know that this feature exists, but it is better to be safe than sorry.

I assume that this facility has been made available, so that if you are running your application in a development set up, you can terminate the application remotely directly from the browser, without having to worry about accessing the server that it is running on. I can’t really think of any other good reasons why you would want to use this feature over simply terminating the command line or using the play stop command.

If you want to try it, just go to http://localhost:9000/@kill (assuming you have not changed your port, and you are running your play server locally in Dev mode).

So stick to PROD mode. Not only is it a better way to run your applications, it protects you from unwarranted server shut downs.

Play Modules

Introduction
I have been asked a few times since writing the Play Framework book about how modules fit into the Play Framework. I didn’t think it made sense to add modules into the first edition, as it was intended as an introduction, so I thought I would add a blog here instead.

Before we being, let first understand what we mean by a play module.

What is a module
A module in play is actually little more than an organisation of your code base. The structure of a play module is very much the same as a standard play application. You will see an app directory (with the normal controllers, views and models), you will see also a conf directory (without an application.conf) and finally a src folder. There is no application.conf as a module will conform to the configuration set out by the application that includes this module.

Note that when your module is running inside an application it has access to all of the applications properties, as if your module was directly inside the application itself.

Why use modules
The idea behind using modules is re-usability and separation. Imagine a scenario where you are building a web application that consists of several discrete pieces of functionality, such as an online Office suite, you may create a set of modules as follows:

• Core Application
• Authentication
• Word processing
• Presentations
• Spreadsheets
• etc

The core application would be your main application that tied all the modules together, and the authentication, word processing, presentations and spreadsheets would each be an individual module.

You could even distribute these modules to different teams to work on.

But I am not going to write an Office clone!
Okay, but the theory transfer to much smaller modules. You modules really could be any discrete piece of functionality, such as admin functions, authentication, dashboards. Anything! Its all about clean separation of concerns and re-usability. Your authentication module could be lifted to your next application with no more effort than simply dropping the directory structure and adding a line in your application.conf.

Creating a Module
Lets take the idea of having a project that has some authentication requirements that we want to split into a new module.

First we will create our main application.

play new core-app

Next we will create our module

play new-module auth

To include our module into our core application, we simply update the application.conf and add a module in the same way we would add a community module.

module.auth=D:\playframework\my-apps\auth

So, the path is module.=

And that is it, your module will be available. But there is nothing in it yet.

What do I put in my Module
Well this is really up to you. For the purposes of our module, the most obvious things to add to our module would be a User model class, an Authenticate controller containing methods for registration, login, and checking authority, and finally views to go with the registration and login actions.

We won’t go into how to build these, because you can quite simply use the Secure module already available in Play for most of this stuff. It simply serves as a nice example of how to separate out some clearly de-marked functionality.

What can’t I do in a module?
Not a lot really. Remember, a module is very much a play application, but just does not have an application.conf, so can’t be run directly. As soon as it is attached to a play application, it can do anything a play application can do, without exception.

What about the PlayPlugin and src folders?
Right at the beginning we mentioned a src folder. In that folder there is also a play.plugins file.

Firstly, the /src directory is compiled when the module is built using the build-module command. The idea, of this directory is for utility classes that don’t have anything to do with Play. .

When the module is built, the contents of the src folder is compiled into a jar file ready for distribution.

Play Plugins are another entirely different topic, which are designed to modify how the Play Framework functions. A great example of this is the DocViewerPlugin which comes bundled into Play. The module simple adds a number of routes to your routes file (if in DEV mode), that allows you to see the core play framework documentation by using the URL /@documentation. The play.plugins file specifies the order of invocation of the play plugins.

My new module is amazing, how do I share it?
Use the build-module command to build a distribution of your module. Announce your module on Google Groups and Guillaume or one of the Play team will give you access to the module repository. You will need to provide an OpenID as well. Once you have access, you can specify the description of your module, and share your module via GitHub or another repository.

You should also add some documentation about your project to /documentation/manual/home.textile.

Play Framework eBook – beta ending soon

The eBook – “Introducing the Play Framework” will shortly be coming out of beta. The good news is that there have been no changes to the content as a result of the beta phase, so for all who bought the beta, your faith was well placed!

Also, I would like to thank everyone for the very encouraging feedback. If anyone would like to add a comment to be published in the final release, just drop me an email.

Once the book comes out of beta, it will probably go up by a few pounds, so if anyone wants to save a little, get in quick!

Enjoy.