Instant Play Framework Starter

The app/ folder contains the source code of our application. According to the MVC architectural pattern, we have three separate components in the form of the following directories:

The default directory (or package) names, models, views, and controllers, can be changed if needed.

The conf/ directory is the place where the application's configuration files are placed. There are two main configuration files:

The application.conf file is the best place to add more configuration options if needed for our application.

Configuration files for third-party libraries should also be put in the conf/ directory or an appropriate sub-directory of conf/.

Play builds applications with the Simple Build Tool (SBT). The project/ folder contains the SBT build definitions:

Static web resources are placed in the public/ folder. Play offers standard sub-directories for images, CSS stylesheets, and JavaScript files. Use these directories to keep your Play applications consistent.

Create additional sub-directories of public/ for third-party libraries for a clear resource management and to avoid file name clashes.

Finally, the test/ folder contains unit tests or functional tests. This code is not distributed with a release of our application.

We create the package models in the app/ folder of our Java application and add a new entity class Entry.java to it. As mentioned before, the package name models can be changed if needed.

package models;

public class Entry {

  public Long id;
  public String name;
  public String phone;

}

The Entry class represents phone book entries. Objects of this class contain a specific name and phone entity. Also we need a unique identifier, id, to be able to distinguish phone book entries. Especially, it is allowed to create multiple entries with the same name and phone number. Please note that phone numbers are of type String, because we also want to allow characters other than digits.

For the sake of simplicity, the visibility of the properties is public to omit the implementation of getters and setters.

Next, we need to create our data access object (DAO). We choose to name it Entries.java. To keep it simple, we place it in the same package:

package models;

import static play.libs.Scala.toSeq;

import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;

import scala.collection.Seq;

public class Entries {

  private static Map<Long, Entry> entries =
      new ConcurrentHashMap<Long, Entry>();

  private static AtomicLong uuid = new AtomicLong();

  public static void delete(long id) {
    entries.remove(id);
  }

  public static Entry findById(long id) {
    return entries.get(id);
  }

  public static Seq<Entry> findByName(String filter) {
    List<Entry> result = new ArrayList<Entry>();
    for (Entry entry : entries.values()) {
      if (entry.name.toLowerCase()
          .contains(filter.toLowerCase())) {
        result.add(entry);
      }
    }
    return toSeq(result);
  }

  public static void save(Entry entry) {
    if (entry.id == null) {
      entry.id = uuid.incrementAndGet();
    }
    entries.put(entry.id, entry);
  }

}

The DAO consists of static methods only and we will not create instances of that class. This pattern is also found in controllers and reflects a fundamental idea of the Play framework; to encourage us to follow a stateless programming model.

Phone book entries can be deleted by an entry id entity. We search entries by their ID and by their name. The findByName implementation returns a list of entries (of type Seq) that contain a specific string in their name, ignoring the case. If the search string is empty, all entries are returned. The order of list items is undetermined here.

Finally, the entries can be saved. The save method equips new entries with an ID. Existing entries are updated in the underlying storage. Our storage is a map associating IDs with the corresponding entries.

Our Scala implementation of the model resides in app/models/ in the file Entries.scala:

package models

import scala.collection.concurrent.TrieMap
import java.util.concurrent.atomic.AtomicLong

case class Entry(name: String = "", phone: String = "",
    id: Option[Long] = None)

object Entries {

  val entries = TrieMap[Long, Entry]()
  val uuid: AtomicLong = new AtomicLong()

  def delete(id: Long) = entries.remove(id)

  def findById(id: Long) = entries.get(id)

  def findByName(filter: String) = entries.values.filter {
    _.name.toLowerCase.contains(filter.toLowerCase)
  }.toSeq

  def save(entry: Entry) =
    ( if (entry.id.isDefined) entry
      else entry.copy(id = Some(uuid.incrementAndGet()))
    ) match {
      case e@Entry(_, _, Some(id)) => entries += (id -> e)
    }

}

This contains both the entry entity and the entries DAO. Entry is a case class, which allows us to implement data beans in a very concise way, literally as a one-liner.

The functionality of our Java and Scala DAO implementations is the same here. The entity is containing the data and will be part of our interface between view and controller. Only the controller is permitted to use the DAO to access the data layer.

In our example the GET and POST methods are sufficient. Described in a nutshell, we use the GET method to load a specific web page without modifying a resource and the POST method to change a resource and navigate to a result page.

Please insert the following code lines behind the first route definition of the conf/routes file of both the projects (Java and Scala):

GET   /entries             controllers.Entries.list(filter ?= "")
GET   /entries/new         controllers.Entries.add
GET   /entries/:id         controllers.Entries.edit(id: Long)
POST  /entries/:id/remove  controllers.Entries.remove(id: Long)
POST  /entries             controllers.Entries.save

Routes are processed in the order of their occurrence until a match is found. If no route matches the actual URL, Play returns a HTTP 404 Not Found page.

The first line reflects that we want to retrieve a list of phone book entries filtered by a specific search string. We are planning to add controls to the phone book list that will allow us to add new phone book entries, edit existing ones, and remove entries.

If we add or edit an entry, we navigate to a phone book entry details page. After the user has finished editing the entry on the client side, it can be saved or canceled. In both cases, we want to return back to the entry list page.

There is one thing we have not explained yet regarding our new routes. Play allows a special notation of the request path of the route. There are three kinds of placeholders for path segments we can use:

The first two placeholders can be combined in a request path, such as:

/shop/:product/$number<[0-9]+>/details

Given that, /shop/socks/1234/details is a valid request path, where product is socks and number is 1234. We pass these placeholders to a controller method, say:

controllers.Shop.showProductDetails(product: String, number: Int)

Also, please note that Play takes care of converting the text content of the extracted path segments to the appropriate parameter types declared in the controller method. The trailing parentheses are optional if the controller method has no arguments.

If we declare a controller method parameter that has no corresponding request path placeholder, Play tries to find that value in the HTTP request header. In other words, the parameter can be specified as a URL query string parameter shop?product=socks.

Additionally, we can define a special handling for controller method parameters:

We need to get back to our phone book example if we want to test our newly created routes. The routes file is compiled and executed when we visit localhost:9000.

Play provides us with a hint that the Entries controller is missing. So, we will implement it next.

Apparently, the routes file has errors because of the missing controller Entries (not to be confused with models.Entries).

To fix that, we create app/controllers/Entries.java with the following content:

package controllers;

import play.mvc.*;

public class Entries extends Controller {

  public static Result list(String filter) {
    return TODO;
  }

  public static Result remove(long id) {
    return TODO;
  }

  public static Result add() {
    return TODO;
  }

  public static Result edit(long id) {
    return TODO;
  }

  public static Result save() {
    return TODO;
  }

}

The corresponding Scala code looks almost the same:

package controllers

import play.api.mvc._

object Entries extends Controller {

  def list(filter: String) = TODO

  def remove(id: Long) = TODO
  def add = TODO

  def edit(id: Long) = TODO

  def save = TODO

}

We actually don't have provided real implementations of the controller methods. Instead, we return Play's empty result (Java) and action (Scala) implementation, TODO. Now the controller is syntactically correct and can be compiled.

To trigger the routes generator, we are reloading the web pages of our Java and Scala applications. So now, the error should disappear.

Of course we can already test what happens when we visit a specific URL listed in our routes file, say localhost:9000/entries?filter=test. According to the route, the controller method controllers.Entries.list("test") is called, which returns the TODO dummy page:

The router can also be used to programmatically generate an URL. Each controller has a so-called reverse controller in a sub-package routes of the corresponding controller class. For example, the controller controllers.Entries has a reverse controller controllers.routes.Entries, which contains (almost) the same methods. The difference is that the reverse controller methods return a Call instead of a Result, where a call corresponds to an URL.

As an example, we will redirect our base URL localhost:9000 to the list of phone book entries located at localhost:9000/entries.

Technically, the Play server performs the redirect by sending an HTTP 302 response to the client, where the response header contains the new URL. In contrast to directly calling the controller method Entries.list(""), the browser location is changed.

In Java, we replace the body of the Application controller's index method with:

public class Application extends Controller {
  
    public static Result index() {
        return redirect(routes.Entries.list(""));
    }
  
}

The Scala solution allows us to omit the argument of the list method and use the default method defined in the routes definition:

object Application extends Controller {
  
  def index = Action {
    Redirect(routes.Entries.list())
  }
  
}

The routes file tells us that a request of localhost:9000/ invokes Application.index, which in turn invokes Entries.list with a redirect to localhost:9000/entries.

We will also use reverse controllers to generate links in our view templates. We have all our URI patterns centralized in the routes file. Using reverse controllers instead of hard-coded links provides us with the certainty that all links are correct—which is one of the several advantages of using Play.

Now we have met all the requirements to implement our first two controller methods, list and remove.

We edit app/controllers/Entries.java and insert the following method bodies. Please note that we will adjust the index view template accordingly:

public static Result list(String filter) {
  Seq<Entry> entries = models.Entries.findByName(filter);
  return ok(views.html.index.render(entries));
}

The list method first calls the findByName method of our DAO models.Entries, which returns all phone book entries where the given filter is part of the entry name.

Then the views.html.index view template renders the list of phone book entries. The result is an HTML page, which is returned by the action with the HTTP 200 OK status and the correct content type text/html. The content type is inferred based on the value passed to the status function (but could be changed by calling .as(…)).

The implementation of remove looks very similar to that of the list method:

public static Result remove(long id) {
  models.Entries.delete(id);
  return redirect(routes.Entries.list(""));
}

First, the DAO is called to delete the entry by it's ID. Then a redirect to the list of phone book entries is returned.

Because Entries.findByName returns a sequence of phone book entries of type Seq<Entry>, we additionally need to import the following classes:

import scala.collection.Seq;
import models.Entry;

We edit app/controllers/Entries.scala and insert the implementation of list:

def list(filter: String) = Action {
  val entries = DAO.findByName(filter.trim)
  Ok(views.html.index(entries))
}

The implementation of remove is also analogous to Java:

def remove(id: Long) = Action {
  DAO.delete(id)
  Redirect(routes.Entries.list())
}

Our DAO models.Entries has the same name as our current controller. To resolve this name clash, we had to provide the fully-qualified name of the DAO in the Java implementation of the list action. In Scala we have the ability to substitute the imported class name with a shortcut by specifying the following import:

import models.{Entries => DAO}

The syntax of view templates are basically a combination of HTML for the static parts and Scala for the dynamic parts.

@(entries: Seq[models.Entry])

@import java.util.List
@import views.html.helper._

A view can be seen as a function. It computes an HTML fragment based on specific parameters. In that manner, views are reusable building blocks. They are referenced by their fully-qualified name, for example, @viewName(params){param}{…}.

Parameters are of an arbitrary Java or Scala type. Especially, blocks of HTML can be passed to views. The type of an HTML block is play.api.templates.Html for both Java and Scala.

When a view is called, it is evaluated. This is done by evaluating all of its contained template expressions and subsequently concatenating the results. The result is of type play.api.templates.Html.

@(message: String)
@main("Sample") {
  <h1>@message</h1>
}

@(title: String)(content: Html)
<html>
  <head>
    <title>@title</title>
  </head>
  <body>
    @content
  </body>
</html>

We use the CSS framework Twitter Bootstrap to style our application. These styles are annotated in class="…" attributes of the HTML elements. The styles are not explained in detail here because they do not affect the functionality of the phone book application.

To install Twitter Bootstrap, please download it at http://twitter.github.com/bootstrap/ and extract its contents to the public/ folder of our Java and Scala application. The result should look similar to this:

/path/to/play-starter-scala/public
   |-bootstrap
   | |-css
   | |-img
   | |-js
   |-images
   |-javascripts
   |-stylesheets

Currently, the compiler complains about the wrong parameter type of the index view located at app/views/index.scala.html. We fix that by introducing the entries parameter of type Seq[Entry]. Also we replace the content passed to the main view:

@(entries: Seq[Entry])

@main {

  <form action="@routes.Entries.list()" method="GET">
    <div class="input-append">
      <input type="text" name="filter" class="input-xxlarge"
             autofocus="">
      <button type="submit" class="btn">Search</button>
    </div>
  </form>

  <a href="@routes.Entries.add()"
     class="btn btn-small btn-primary">New entry</a>

  @list(entries)

}

The main view does not take the title parameter any more. We replaced the welcome message of the initial view with the following:

As we already stated, we use reverse controllers instead of hard-coded URLs.

The HTTP method of the form is GET and it is used in order to append the form data to the request query string. This makes searches bookmarkable.

Instead of @views.html.list(entries), we can write @list(entries). The packages views.html and models are in scope by default.

The list of entries is rendered by a separate view app/views/list.scala.html. We create it with the following content for our Java application:

@(entries: Seq[Entry])

<table class="table table-hover">
  @for(entry <- entries) {
    <tr>
      <td>
        <strong>@entry.name</strong><br>
        <a href="tel:@entry.phone">@entry.phone</a>
        <form action="@routes.Entries.remove(entry.id)"
            method="POST">
          <a href="@routes.Entries.edit(entry.id)"
              class="btn btn-small">Edit</a>
          <input type="submit" value="Remove" class="btn btn-small">
        </form>
      </td>
    </tr>
  }
</table>

Our Entry implementations slightly differ in Java and Scala. In Scala, we avoid them to cope with null value handling. Instead, we use the generic Option[T] type, which has two implementations, Some[T] and None[T].

Here we get Some(id) if entry.id is defined, otherwise, we get None. The Option type plays well together with the for expression. This is our Scala implementation:

@(entries: Seq[Entry])

<table class="table table-hover">
  @for(entry <- entries; id <- entry.id) {
    <tr>
      <td>
        <strong>@entry.name</strong><br>
        <a href="tel:@entry.phone">@entry.phone</a>
        <form action="@routes.Entries.remove(id)"
            method="POST">
          <a href="@routes.Entries.edit(id)"
              class="btn btn-small">Edit</a>
          <input type="submit" value="Remove" class="btn btn-small">
        </form>
      </td>
    </tr>
  }
</table>

According to the call of the list view in the index view, there is one parameter entries of type Seq[Entry]. The phonebook entries are aligned in a table by iterating the given sequence and producing a table row for each Entry.

In Scala we do not expect None values here. Anyway, if entry.id is None, no table row is generated for that entry.

A table row consists of the phone book entry name, the phone number, and two buttons for editing and removing phone book entries. The phone number is displayed as a click-to-call link for mobile browsers. We use the reverse controllers for linking our edit and remove actions.

Finally, we have to provide a proper implementation of the main view:

@(content: Html)

@style(asset: String) = {
  <link rel="stylesheet" href="@routes.Assets.at(asset)">
}

<!DOCTYPE html>
<html>
  <head>
    <title>Play Framework Starter Guide</title>
    @style("bootstrap/css/bootstrap.css")
    @style("bootstrap/css/bootstrap-responsive.css")
    @style("stylesheets/main.css")
  </head>
  <body>
    <div class="navbar navbar-inverse navbar-fixed-top">
      <div class="navbar-inner">
        <div class="container">
          <a class="brand" href="/">Phonebook</a>
        </div>
      </div>
    </div>
    <div class="container">
      @content
    </div>
  </body>
</html>

We removed the title parameter of the initial main view implementation and declared the style function, which we use in the HTML head element to include our CSS stylesheets.

The body consists of the popular Twitter Bootstrap navbar, which displays our brand, Phonebook, and the content argument of the main view.

Fine-tuning the CSS style

We have to customize the Twitter Bootstrap style for our design. Please replace the content of public/stylesheets/main.css with the following:

@media (min-width:979px) {
  body          { padding-top:60px }
}
form            { margin:0 }
table           { margin-top:8px }
td              { position:relative }
td > form       { position:absolute; right:8px; top:14px }

We ensure correct alignment to the top of big screens. The margin of tables and forms is also tweaked a little bit. Also, we align our Entry buttons to the right-hand side of a table row.

Now reload our page. This is what it looks like:

Unfortunately, our data store is empty and we are currently unable to add entries. Nevertheless, to test the functionality we need to add some test data.

One easy way to achieve this is to intercept the application start-up and create some test data by implementing app/Global.java in the Java project:

import models.*;
import play.*;

public class Global extends GlobalSettings {

  @Override
  public void onStart(Application app) {

    Entries.save(newEntry("Guillaume Bort",
        "+33 5 55 55 55 55"));
    Entries.save(newEntry("Sadek Drobi", "+33 5 55 55 55 55"));

  }
  private Entry newEntry(String name, String phone) {

    Entry entry = new Entry();
    entry.name = name;
    entry.phone = phone;
    return entry;

  }

}

The onStart method is called by Play on the application startup. So we have the opportunity to initialize our data store by programmatically saving phone book entries.

For the Scala project, we create app/Global.scala:

import models.{Entry, Entries => DAO}
import play.api._

object Global extends GlobalSettings {

  override def onStart(app: Application) {

    DAO.save(Entry("Guillaume Bort", "+33 5 55 55 55 55"))
    DAO.save(Entry("Sadek Drobi", "+33 5 55 55 55 55"))

  }

}

Feel free to play around with our first version of the phone book prototype!

Users submit HTML form fields on the client side. The data is sent as text to the server packaged within an HTTP request. It has to be parsed on the server side. A corresponding typed data structure is filled with the form field values.

import play.data.Form;
import static play.data.Form.form;

public class Entries extends Controller {

  final static Form<Entry> entryForm = form(Entry.class);

  // ...

}

public static Result save() {
  Entry entry = entryForm.bindFromRequest(request()).get();
  models.Entries.save(entry);
  return redirect(routes.Entries.list(""));
}

public static Result add() {
  Form<Entry> form = entryForm.fill(new Entry());
  return ok(views.html.edit.render(form, "Add entry"));
}

public static Result edit(long id) {
  Entry entry = models.Entries.findById(id);
  if (entry != null) {
    Form<Entry> form = entryForm.fill(entry);
    return ok(views.html.edit.render(form, "Edit entry"));
  } else {
    return redirect(routes.Entries.list(""));
  }
}

import models.{Entry, Entries => DAO}
import play.api.data._
import play.api.data.Forms._

object Entries extends Controller {

  val entryForm = Form(
    mapping(
      "name" -> text,
      "phone" -> text,
      "id" -> optional(longNumber)
    )(Entry.apply)(Entry.unapply))

  // ...

}

def save = Action { implicit request =>
  val entry = entryForm.bindFromRequest.get
  DAO.save(entry)
  Redirect(routes.Entries.list())
}

def add = Action {
  val form = entryForm.fill(Entry())
  Ok(views.html.edit(form, "Add entry"))
}

def edit(id: Long) = Action {
  DAO.findById(id) map { entry =>
    val form = entryForm.fill(entry)
    Ok(views.html.edit(form, "Edit entry"))
  } getOrElse {
    Redirect(routes.Entries.list())
  }
}

The edit page displayed on the client side is created by rendering the edit view template. Create app/views/edit.scala.html with the following content:

@(entryForm: Form[Entry], heading: String)

@main {

  <h1>@heading</h1>

  <form action="@routes.Entries.save()" method="POST">
    <input type="hidden" name="id" value="@entryForm("id").value">
    <div>
      <label for="name">Name</label>
      <div class="input">
        <input type="text" id="name" name="name"
            value="@entryForm("name").value" autofocus="">
      </div>
    </div>
    <div>
      <label for="phone">Phone</label>
      <div class="input">
        <input type="text" id="phone" name="phone" 
            value="@entryForm("phone").value">
      </div>
    </div>
    <div>
      <button type="submit" class="btn btn-primary">Save</button>
      <a class="btn" href="@routes.Entries.list()">Cancel</a>
    </div>
  </form>

}

The HTML form consists of one hidden input field containing the ID of the entry. The ID is needed on the server side to identify the entity to be saved to the data storage.

Furthermore, there are two input fields holding the name and the phone number of our entry. All fields are initialized with the corresponding form value of the given entryForm parameter, for example, @entryForm("name").value.

On form submission, the reverse controller method Entries.save is called. Additionally there is a cancel link, which loads the list of phone book entries.

Now we are able to create and edit phone book entries.

On the server side, we have two tasks regarding validation, including attribution of our form fields with constraints, and adapting the control flow of the save method.

package models;

import static play.data.validation.Constraints.*;

public class Entry {

  public Long id;

  @Required
  @MinLength(value = 2)
  public String name;

  @Required
  @Pattern(
    value = "\\+?[0-9\\s]+",
    message = "Optional +, followed by digits & spaces"
  )
  public String phone;

  public Entry() {}

}

public static Result save() {
  Form<Entry> form = entryForm.bindFromRequest(request());
  if (form.hasErrors()) {
    return badRequest(
      views.html.edit.render(form, "Correct entry"));
  } else {
    models.Entries.save(form.get());
    return redirect(routes.Entries.list(""));
  }
}

import play.api.data.validation.Constraints._

val entryForm = Form(
  mapping(
    "name" -> nonEmptyText(minLength = 2),
    "phone" -> (nonEmptyText verifying pattern(
      """\+?[0-9\s]+""".r,
      error = "Optional +, followed by digits & spaces")
    ),
    "id" -> optional(longNumber)
  )(Entry.apply)(Entry.unapply))

def save = Action { implicit request =>
  entryForm.bindFromRequest.fold(
    errors => BadRequest(views.html.edit(errors, "Correct entry")),
    entry => {
      DAO.save(entry)
      Redirect(routes.Entries.list())
    }
  )
}

Our program does already compile and run, but we also need to customize the edit view in regards to the way that validation errors are displayed:

<form action="@routes.Entries.save()" method="POST">
  <input type="hidden" name="id" value="@entryForm("id").value">
  <div class="control-group
      @if(entryForm("name").hasErrors) {error}">
    <label for="name">Name</label>
    <div class="input">
      <input type="text" id="name" name="name"
          value="@entryForm("name").value" autofocus="">
      <span class="help-inline">@(entryForm("name").errors.map{ e =>
          play.api.i18n.Messages(e.message , e.args: _*)
      }.mkString(", "))</span>
    </div>
  </div>
  <div class="control-group
      @if(entryForm("phone").hasErrors) {error}">
    <label for="phone">Phone</label>
    <div class="input">
      <input type="text" id="phone" name="phone"
          value="@entryForm("phone").value">
      <span class="help-inline">@(entryForm("phone").errors.map{e => 
          play.api.i18n.Messages(e.message , e.args: _*)
      }.mkString(", "))</span>
    </div>
  </div>
  <div>
    <button type="submit" class="btn btn-primary">Save</button>
    <a class="btn" href="@routes.Entries.list()">Cancel</a>
  </div>
</form>

This view compiles only in Scala. Because of a small discrepancy between the Java and Scala API, the string e.args must be replaced with e.arguments in the highlighted lines for the Java version.

We have added some additional error message handling to two visible input fields here, and to be honest, there is so much repetition already that the source code starts to look really horrible. Not to imagine how a more complex form would look like.

But we can do better…

By default, a new Play application for Java that has been created with the play new command has all the required dependencies pre-defined in our SBT project definition project/Build.scala:

val appDependencies = Seq(
  javaCore,
  javaJdbc,
  javaEbean
)

We register the H2 in-memory JDBC driver for our database named default by uncommenting these two lines in our configuration file conf/application.conf:

db.default.driver=org.h2.Driver
db.default.url="jdbc:h2:mem:play"

To activate the Ebean initialization on application startup, we have to uncomment the following line:

ebean.default="models.*"

With this property, we specify where to search for entities; in our case the class Entry.java. Also we define which Ebean server is used to access our entities, in this case default, which corresponds to the connection properties previously given.

Now the configuration of Ebean is complete.

We have two choices when it comes to creating a database schema; we either do it manually or automatically. Ebean supports automatic DDL generation, that is, it produces SQL scripts based on our entities. This is good for testing or as a starting point for large databases, but it is discouraged for production quality applications.

Here we are going to create the database schema manually. Play supports us in tracking and executing our database changes. We call these changes evolutions; they are divided into files located in conf/evolutions/<database-name>/. In our case <database-name> is default. The first evolution has the name 1.sql, the second 2.sql, and so on. These files contain the so-called up and down scripts, which are used to change and revert the database. A revert may occur during development if an existing evolution changes.

So let's create our first database evolution. As mentioned previously, it is located in conf/evolutions/default/1.sql with the following content:

# --- !Ups

create table entry (
  id                  bigint not null,
  name                varchar(255) not null,
  phone               varchar(255) not null,
  constraint pk_entry primary key (id))
;

create sequence entry_seq start with 1;

# --- !Downs

drop table if exists entry;

drop sequence if exists seq_entry;

The Ups and the Downs comments are mandatory. In the Ups part we create a table entry; rows of phone book entries with a unique ID, a name, and a phone number. Additionally, we are using a sequence to generate our unique IDs. In the Downs part we specify how to revert the changes, which in our case is simply by dropping the table and the sequence.

Before we start our application and create the schema, we have to implement our Ebean based model.

Ebean uses the same mapping annotations as the Java Persistence API (JPA). These are located in the package javax.persistence. We use the @Entity annotation that denotes that our Entry class is mapped to a table with the same name. The @Id annotation marks our Primary key field.

We implement app/models/Entry.java as follows:

package models;

import play.db.ebean.Model;

import javax.persistence.Entity;
import javax.persistence.Id;

import static play.data.validation.Constraints.*;

@Entity
public class Entry extends Model {
  @Id
  public Long id;

  @Required
  @MinLength(value = 2)
  public String name;

  @Required
  @Pattern(
    value = "\\+?[0-9\\s]+",
    message = "Optional +, followed by digits & spaces"
  )
  public String phone;

  public Entry() {}

  public static Finder<Long,Entry> find =
    new Finder<Long,Entry>(Long.class, Entry.class);

}

Ebean has a default naming convention that maps Java names written in camel-case fooBarBaz to database names in snake-case format foo_bar_baz. Of course this convention can be customized.

We extend the Model class, which is part of the Play Framework. It contains convenient methods and a Finder class that we use to create a finder for our Entry entity.

Next, we are using the query DSL of Ebean to implement our DAO methods. Please modify app/models/Entries.java accordingly:

package models;

import static play.libs.Scala.toSeq;
import scala.collection.Seq;

public class Entries {

  public static void delete(long id) {
        Entry.find.ref(id).delete();
  }

  public static Entry findById(long id) {
    return Entry.find.byId(id);
  }

  public static Seq<Entry> findByName(String filter) {
        return toSeq(Entry.find
        .where()
        .ilike("name", "%"+filter+"%")
        .findList());
  }

  public static void save(Entry entry) {
        if (entry.id == null) {
            entry.save();
        } else {
            entry.update();
        }
  }

}

As you can see, it is pretty straightforward to query the database with Ebean.

Ebean, by default, executes a query in an implicit transaction, so we don't have to care here about session and transaction management.

We can now start reloading our application in the browser:

Play checks on each page reload in development mode to see if database evolutions have changed. If there are new evolutions or an existing one has changed, Play asks to apply the scripts. We press the Apply this script now! button to execute the Ups sections of the changed scripts in the right-hand side order.

Now we have a working Ebean implementation of our model.

When creating a new Play application for Scala with the play new command, the required dependencies jdbc and anorm are already configured in the SBT build definition file project/Build.scala:

val appDependencies = Seq(
  jdbc,
  anorm
)

Like for our Ebean example, we enable the in-memory H2 database in conf/application.conf by uncommenting the following lines:

db.default.driver=org.h2.Driver
db.default.url="jdbc:h2:mem:play"

There is no additional configuration needed.

Again we will create the database DDL script conf/evolutions/default/1.sql.

# --- !Ups

create table entry (
  id                  bigint auto_increment primary key,
  name                varchar(255) not null,
  phone               varchar(255) not null)
;

# --- !Downs

drop table if exists entry;

We declare our primary key column as auto_increment to automatically generate IDs in the database when inserting new phone book entries. Ebean needs a database sequence for ID generation, but Anorm also works well with an auto increment key.

The database access is implementation in the DAO through models/Entries.scala. Our entity case class Entry remains unchanged.

The necessary imports for using Anorm and JDBC connections are also added:

package models

import anorm._
import anorm.SqlParser._
import play.api.Play.current
import play.api.db.DB

case class Entry(name: String = "", phone: String = "",
    id: Option[Long] = None)

object Entries {

  val simple = {
    get[String]("entry.name") ~
    get[String]("entry.phone") ~
    get[Option[Long]]("entry.id") map {
      case name ~ phone ~ id => Entry(name, phone, id)
    }
  }

  def delete(id: Long) = DB.withConnection {
    implicit connection =>
      SQL("delete from entry where id = {id}")
        .on('id -> id)
        .executeUpdate()
  }

  def findById(id: Long) = DB.withConnection {
    implicit connection =>
      SQL("select * from entry where id = {id}")
        .on('id -> id)
        .singleOpt(simple)
  }

  def findByName(filter: String) = DB.withConnection {
    implicit connection =>
      SQL("select * from entry where lower(name) like {filter}")
        .on('filter -> ("%"+filter.toLowerCase+"%"))
        .as(simple.*)
  }

  def save(entry: Entry) = DB.withConnection {
    implicit connection =>
      if (entry.id.isDefined) {
        SQL("""update entry set name={name}, phone={phone}
               where id = {id}""")
          .on('name -> entry.name, 'phone -> entry.phone,
              'id -> entry.id)
          .executeUpdate()
      } else {
        SQL("""insert into Entry(name, phone)
               values ({name}, {phone})""")
          .on('name -> entry.name, 'phone -> entry.phone)
          .executeInsert()
      }
  }
}

The row parser simple defines how rows of our database table Entry are retrieved. For each column, we specify the type and the name, for example, get[String]("entry.name"). These definitions are concatenated with the tilde character ~. Finally, we tell Anorm how to create an Entry object of a given row.

Unlike Ebean, we have to explicitly retrieve a new database connection when we execute database queries. We do this by calling DB.withConnection. The Anorm SQL API needs an implicit connection to be in scope.

With the connection in place, we are able to implement our database queries based on plain SQL. In Anorm, we start a query by passing our SQL statement to the SQL method, which returns an SqlQuery object. Placeholders for variable values are denoted within curly braces {}. On the SqlQuery object, we call the on() method to specify the placeholder values. Finally we execute the query.

Anorm provides us with different methods for querying the database. Here we use:

When running our application, we are asked to apply the new database evolution. We do so by pressing the Apply this script now! button.

As of Play 2.1, we have to add an external dependency to the SBT build definition project/Build.scala in order to use Slick:

val appDependencies = Seq(
  jdbc,
  "com.typesafe.slick" %% "slick" % "1.0.0"
)

The jdbc module is also needed; the anorm module can be removed.

Don't forget to regenerate your project files via play idea or play eclipse to update your class path accordingly if you use one of these IDEs.

Again we enable the in-memory H2 database in conf/application.conf.

db.default.driver=org.h2.Driver
db.default.url="jdbc:h2:mem:play"

As mentioned previously, Slick has a query compiler that generates SQL statements. We give Slick a hint about which SQL dialect to use by importing an appropriate Driver and ExtendedProfile respectively (replaced by JdbcDriver with Slick 1.1).

Please create the file app/models/DAL.scala with the following content:

package models

trait Profile {
  val driver: slick.driver.ExtendedProfile
  val db: scala.slick.session.Database

}

The driver variable holds the specific Slick database driver. We also need to add a variable db, which is used to create database sessions and transactions.

package models

case class Entry(name: String = "", phone: String = "",
    id: Option[Long] = None)

trait EntriesComponent { self: Profile =>

  import driver.simple._
  import Database.threadLocalSession

  object Entries extends Table[Entry]("ENTRY") {
    def id = column[Long]("ID", O.PrimaryKey, O.AutoInc)
    def name = column[String]("NAME")
    def phone = column[String]("PHONE")
    def * = name ~ phone ~ id.? <> (Entry, Entry.unapply _)

    def delete(id: Long) = db withSession {
      Query(this).where(_.id is id).delete
    }

    def findById(id: Long) = db withSession {
      Query(this).where(_.id is id).firstOption
    }

    def findByName(filter: String) = db withSession {
      val search = "%"+filter.toLowerCase+"%"
      Query(this).where(_.name.toLowerCase like search).list
    }

    def save(entry: Entry) = db withSession {
      entry.id.fold {
        this.insert(entry)
      }{ id =>
        Query(this).where(_.id is id).update(entry)
      }
    }
  }
}

import play.api.Play.current
import play.api.db.DB
import scala.slick.session.Database

object DAL extends EntriesComponent
    /* with OtherComponent */ with Profile {

  val driver = scala.slick.driver.H2Driver
  val db = Database.forDataSource(DB.getDataSource("default"))
  val ddl = Entries.ddl // ++ Other.ddl

}

import models.Entry
import models.DAL.{Entries => DAO}

You should remember that we have inserted some test data on startup in our GlobalSettings implementation. This is the right place to create our database on application startup.

import models.{DAL, Entry}, DAL._, DAL.driver.simple._
import play.api._

object Global extends GlobalSettings {

  override def onStart(app: Application) {

    DAL.db withSession { implicit s: Session =>
      ddl.create
    }

    Entries.save(Entry("Guillaume Bort", "+33 5 55 55 55 55"))
    Entries.save(Entry("Sadek Drobi", "+33 5 55 55 55 55"))

  }

}

We use our DAL to bring a session into scope and create our database schema.

You can now run this application.

Now go ahead and start to implement amazing web applications with Play!