What do you get with Print?

Instant access to your digital copy whilst your Print order is Shipped

Paperback book shipped to your preferred address

Redeem a companion digital copy on all Print orders

Access this title in our online reader with advanced features

DRM FREE - Read whenever, wherever and however you want

Play Framework essentials

Chapter 1. Building a Web Service

This chapter will cover the following topics:

Bootstrapping a Play project
Understanding the different pieces of a Play project
Mapping URLs to your service entry points
Serving JSON responses and reading and validating JSON requests

Play – a framework used to write web applications

Play is a framework used to write web applications. As shown in the following diagram, a web application is based on a client-server architecture and uses the HTTP protocol for communication:

Web-oriented architecture

Users have the role of clients and make HTTP requests to servers to interact with the application. The servers process their requests and send them a response. Along the way, the web application might need to make use of various databases or perhaps other web services. This entire process is depicted in the following diagram:

The Play framework's overall architecture

This book will show you how Play can help you to write such web applications. The preceding diagram shows a first big picture of the framework's overall architecture. We will refine this picture as we read through this book, but for now it is a good start. The diagram shows a web client and a Play application. This one is made of a business layer (on the right), which provides the services and resources specific to the application. These features are exposed to the HTTP world by actions, which themselves can be logically grouped within controllers. Gray boxes represent the parts of code written by the developer (you!), while the white box (the router) represents a component already provided by Play.

HTTP requests performed by the client (1) are processed by the router that calls the corresponding action (2) according to URL patterns you configured. Actions fill the gap between the HTTP world and the domain of your application. Each action maps a service or resource of the business layer (3) to an HTTP endpoint.

All the code examples in this book will be based on a hypothetical shopping application allowing users to manage and sell their items. The service layer of this application is defined by the following Shop trait:

case class Item(id: Long, name: String, price: Double)

trait Shop {
  def list(): Seq[Item]
  def create(name: String, price: Double): Option[Item]
  def get(id: Long): Option[Item]
  def update(id: Long, name: String, price: Double): Option[Item]
  def delete(id: Long): Boolean
}

In Java, the service layer is defined by the following Shop interface:

public class Item {

  public final Long id;
  public final String name;
  public final Double price;

  public Item(Long id, String name, Double price) {
    this.id = id;
    this.name = name;
    this.price = price;
  }

}

interface Shop {
  List<Item> list();
  Item create(String name, Double price);
  Item get(Long id);
  Item update(Long id, String name, Double price);
  Boolean delete(Long id);
}

Tip

Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

The Item type simply says that an item has a name, a price, and an ID. The Shop type defines the typical Create, Read, Update, and Delete (CRUD) operations we want to do. Connecting with the figure that shows the architecture of Play applications, these types represent the business layer of your web service and their definition should live in a models package in the app/ source directory. The remainder of this chapter explains how to write a controller exposing this business layer via HTTP endpoints using JSON to represent the data.

As an example, here is a possible minimalist Scala implementation of the Shop trait:

package models

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

object Shop extends Shop {
  private val items = TrieMap.empty[Long, Item]
  private val seq = new AtomicLong

  def list(): Seq[Item] = items.values.to[Seq]

  def create(name: String, price: Double): Option[Item] = {
    val id = seq.incrementAndGet()
    val item = Item(id, name, price)
    items.put(id, item)
    Some(item)
  }

  def get(id: Long): Option[Item] = items.get(id)

  def update(id: Long, name: String, price: Double): Option[Item] = {
    val item = Item(id, name, price)
    items.replace(id, item)
    Some(item)
  }

  def delete(id: Long): Boolean = items.remove(id).isDefined
}

This implementation stores the data in memory, so it loses everything each time the application restarts! Nevertheless, it is a sufficient business layer basis, letting us focus on the web layer. The implementation uses a concurrent collection to solve concurrency issues. Indeed, as I will explain later, the code called by the controllers must be thread safe.

For Java developers, here is a minimalist implementation of the Shop interface:

import java.util.concurrent.ConcurrentSkipListMap;
import java.util.concurrent.atomic.AtomicLong;

new Shop() {

  SortedMap<Long, Item> items = new ConcurrentSkipListMap<>();
  AtomicLong seq = new AtomicLong();

  @Override
  public Collection<Item> list() {
    return new ArrayList<>(items.values());
  }
  @Override
  public Item create(String name, Double price) {
    Long id = seq.incrementAndGet();
    Item item = new Item(id, name, price);
    items.put(id, item);
    return item;
  }

  @Override
  public Item get(Long id) {
    return items.get(id);
  }

  @Override
  public synchronized Item update(Long id, String name, Double price) {
    Item item = items.get(id);
    if (item != null) {
      Item updated = new Item(id, name, price);
      items.put(id, updated);
      return updated;
    } else return null;
  }

  @Override
  public Boolean delete(Long id) {
    return items.remove(id) != null;
  }
};

As previously mentioned, the code called by controllers must be thread safe, hence the use of Java concurrent collections.

Bootstrapping a Play application

While it is totally possible to start a Play project from nothing, you might find it more convenient to start from an empty application skeleton and set up the build system to depend on Play so that you can directly focus on the code of your application.

Typesafe Activator (https://typesafe.com/activator) can be used to generate such an empty application skeleton. This tool lists several application templates designed to be used as the project's starting point. Actually, Activator does a bit more than this: it can also compile and run your project and even provide a minimalist development environment with a code editor right in your web browser!

Let's start with a basic Scala or Java application. Download and install Activator by referring to its documentation. Though some templates already support advanced features out of the box, we will begin with a completely empty application and will progressively enhance it with new features (for example, persistence or client-side technologies).

In a *nix terminal, create a new application skeleton by running the following activator command:

$ activator new

You will be asked which application template to use; choose just-play-scala (or just-play-java to create a Java application). Give the application the name shop.

A new directory, shop/, has been created that contains the application's code. Go to this directory and execute the activator run command:

$ cd shop
$ activator run

Activator starts a development HTTP server listening (by default) on port 9000. In your browser, go to http://localhost:9000 to test it; the HTTP server compiles your application, starts it, and processes your HTTP request. If everything works fine, your browser should show a page titled Just Play Scala (or Just Play Java).

You can stop the running application with Ctrl + D.

You can also start Activator without passing it a command name:

$ activator

In such a case, you enter in the project sbt shell, where you can manage the life cycle of your project as in any sbt project. For instance, you can try these commands: clean, compile, run, and console. The last one starts a REPL where you can evaluate expressions using your application's code.

Note

sbt is a build tool for Scala projects. Check out http://www.scala-sbt.org for more details.

Play applications' layout

To explain why you get this result in your browser when you ran the application, let's have a look at the files created by the activator new command. Under the project root directory (the shop/ directory), the build.sbt file describes your project to the build system.

It currently contains a few lines, which are as follows:

name := """shop"""

version := "1.0-SNAPSHOT"

lazy val root = project.in(file(".")).enablePlugins(PlayScala)

The first two lines set the project name and version, and the last line imports the default settings of Play projects (in the case of a Java project, this line contains PlayJava instead of PlayScala). These default settings are defined by the Play sbt plugin imported from the project/plugins.sbt file. As the development of a Play application involves several file generation tasks (templates, routes, assets and so on), the sbt plugin helps you to manage them and brings you a highly productive development environment by automatically recompiling your sources when they have changed and you hit the reload button of your web browser.

Though based on sbt, Play projects do not follow the standard sbt projects layout: source files are under the app/ directory, test files under the test/ directory, and resource files (for example, configuration files) are under the conf/ directory. For instance, the definitions of the Shop and Item types should go into the app/ directory, under a models package.

After running your Play application, try changing the source code of the application (under the app/ directory) and hit the reload button in your browser. The development HTTP server automatically recompiles and restarts your application. If your modification does not compile, you will see an error page in your browser that shows the line causing the error.

Let's have a deeper look at the files of this minimal Play application.

The app/ directory, as mentioned before, contains the application's source code. For now, it contains a controllers package with just one controller named Application. It also contains a views/ directory that contains HTML templates. We will see how to use them in Chapter 3, Turning a Web Service into a Web Application.

The conf/ directory contains two files. The conf/application.conf file contains the application configuration information as key-value pairs. It uses the Human Optimized Configuration Object Notation syntax (HOCON; it is a JSON superset, check out https://github.com/typesafehub/config/blob/master/HOCON.md for more information). You can define as many configuration points as you want in this file, but several keys are already defined by the framework to set properties, such as the language supported by the application, the URL to use to connect to a database, or to tweak the thread pools used by the application.

The conf/routes file defines the mapping between the HTTP endpoints of the application (URLs) and their corresponding actions. The syntax of this file is explained in the next section.

URL routing

The routing component is the first piece of the framework that we will look at:

URL routing

The preceding diagram depicts its process. It takes an HTTP request and calls the corresponding entry point of the application. The mapping between requests and entry points is defined by routes in the conf/routes file. The routes file provided by the application template is as follows:

# Routes
# This file defines all application routes (Higher priority routes first)
# ~~~~

# Home page
GET     /                 controllers.Application.index

# Map static resources from the /public folder to the /assets URL path
GET     /assets/*file     controllers.Assets.versioned(path="/public", file)

Apart from comments (starting with #), each line of the routes file defines a route associating an HTTP verb and a URL pattern to a controller action call.

For instance, the first route associates the / URL to the controllers.Application.index action. This one processes requests by always returning an HTTP response with a 200 status code (OK) and an HTML body that contains the result of the rendering of the views.html.index template.

The content of the routes file is compiled by the sbt plugin into a Scala object named Router and contains the dispatching logic (that is, which action to call according to the incoming request verb and URL). If you are curious, the generated code is written in the target/scala-2.10/src_managed/main/routes_routing.scala file. The router tries each route, one after the other, in their order of declaration. If the verb and URL match the pattern, the corresponding action is called.

Your goal is to expose your Shop business layer as a web service, so let's add the following lines to the routes file:

GET    /items        controllers.Items.list
POST   /items        controllers.Items.create
GET    /items/:id    controllers.Items.details(id: Long)
PUT    /items/:id    controllers.Items.update(id: Long)
DELETE /items/:id    controllers.Items.delete(id: Long)

The first route will return a list of items for sale in the shop, the second one will create a new item, the third one will show detailed information about an item, the fourth one will update the information of an item, and finally, the last one will delete an item. Note that we follow the REST conventions (http://en.wikipedia.org/wiki/REST) for the URL shapes and HTTP verbs.

In the controllers package of your code, add the following Items controller that matches the added routes:

package controllers

import play.api.mvc.{Controller, Action}

object Items extends Controller {
  val shop = models.Shop // Refer to your Shop implementation
  val list = Action { NotImplemented }
  val create = Action { NotImplemented }
  def details(id: Long) = Action { NotImplemented }
  def update(id: Long) = Action { NotImplemented }
  def delete(id: Long) = Action { NotImplemented }
}

The equivalent Java code is as follows:

package controllers;

import play.mvc.Controller;
import play.mvc.Result;

public class  Items extends Controller {

  static final Shop shop = Shop.Shop; // Refer to your Shop implementation

  public static Result list() {
    return status(NOT_IMPLEMENTED);
  }
  public static Result create() {
    return status(NOT_IMPLEMENTED);
  }
  public static Result details(Long id) {
    return status(NOT_IMPLEMENTED);
  }
  public static Result update(Long id) {
    return status(NOT_IMPLEMENTED);
  }
  public static Result delete(Long id) {
    return status(NOT_IMPLEMENTED);
  }
}

Each route is mapped by a controller member of type Action (or in Java, a public static method that returns a Result). For now, actions are not implemented (they all return NotImplemented) but you will progressively connect them to your Shop service so that, for instance, the Items.list action exposes the shop list method.

Route path parameters

In our example, in the first route, the URL pattern associated with the controllers.Items.details action is /items/:id, which means that any URL starting with /items/ and then containing anything but another / will match. Furthermore, the content that is after the leading / is bound to the id identifier and is called a path parameter. The /items/42 path matches this pattern, but the /items/, /items/42/0, or even /items/42/ paths don't.

When a route contains a dynamic part such as a path parameter, the routing logic extracts the corresponding data from the URL and passes it to the action call.

You can also force a path parameter to match a given regular expression by using the following syntax:

GET     /items/$id<\d+>    controllers.Items.details(id: Long)

Here, we check whether the id path parameter matches the regular expression \d+ (at least one digit). In this case, the /items/foo URL will not match the route pattern and Play will return a 404 (Not Found) error for such a URL.

A route can contain several path parameters and each one is bound to only one path segment. Alternatively, you can define a path parameter spanning several path segments using the following syntax:

GET     /assets/*file        controllers.Assets.at(path = "/public", file)

In this case, the file identifier captures everything after the /assets/ path segment. For instance, for an incoming request with the /assets/images/favicon.png URL, file is bound to images/favicon.png. Obviously, a route can contain at most one path parameter that spans several path segments.

Parameters type coercion

By default, request parameters are coerced to String values, but the type annotation id: Long (for example, in the details route) asks Play to coerce the id parameter to type Long. The routing process extracts the content corresponding to a parameter from the URL and tries to coerce it to its target type in the corresponding action (Long in our example) before calling it.

Note that /items/foo also matches the route URL pattern, but then the type coercion process fails. So, in such a case, the framework returns an HTTP response with a 400 (Bad Request) error status code.

This type coercion logic is extensible. See the API documentation of the QueryStringBindable and PathBindable classes for more information on how to support your own data types.

Parameters with fixed values

The parameter values of the called actions can be bound from the request URL, or alternatively, can be fixed in the routes file by using the following syntax:

GET     /          controllers.Pages.show(page = "index")
GET     /:page     controllers.Pages.show(page)

Here, in the first route, the page action parameter is set to "index" and it is bound to the URL path in the second route.

Query string parameters

In addition to path parameters, you can also define query string parameters: parameters extracted from the URL query string.

To define a query string parameter, simply use it in the action call part of the route without defining it in the URL pattern:

GET     /items          controllers.Items.details(id: Long)

The preceding route matches URLs with the /items path and have a query string parameter id. For instance, /items and /items?foo=bar don't match but /items?id=42 matches. Note that the URL must contain at least all the parameters corresponding to the route definition (here, there is only one parameter, which is id), but they can also have additional parameters; /items?foo=bar&id=42 also matches the previous route.

Default values of query string parameters

Finally, you can define default values for query string parameters. If the parameter is not present in the query string, then it takes its default value. For instance, you can leverage this feature to support pagination in your list action. It can take an optional page parameter defaulting to the value 1. The syntax for default values is illustrated in the following code:

GET   /items        controllers.Items.list(page: Int ?= 1)

The preceding route matches the /items?page=42 URL and binds the page query string parameter to the value 42, but also matches the /items URL and, in this case, binds the page query string parameter to its default value 1.

Change the corresponding action definition in your code so that it takes a page parameter, as follows:

def list(page: Int) = Action { NotImplemented }

The equivalent Java code is as follows:

public static Result list(Integer page) {
  return status(NOT_IMPLEMENTED);
}

Trying the routes

If you try to perform requests to your newly added routes from your browser, you will see a blank page. It might be interesting to try them from another HTTP client to see the full HTTP exchange between your client and your server. You can use, for example, cURL (http://curl.haxx.se/):

$ curl -v http://localhost:9000/items
> GET /items HTTP/1.1
> User-Agent: curl/7.35.0
> Host: localhost:9000
> Accept: */*
>
< HTTP/1.1 501 Not Implemented
< Content-Length: 0
<

The preceding command makes an HTTP GET request on the /items path and gets an HTTP response with the status code 501 (Not Implemented). Try requesting other paths such as /items/42, /itemss/foo, or /foo and compare the response status codes you get.

Routes are the way to expose your business logic endpoints as HTTP endpoints; your Shop service can now be used from the HTTP world!

What you will learn

Set up a unified development environment for both the clientside and serverside code

Understand the challenges of building a scalable web application and master the solutions provided by Play framework

Integrate the framework with existing clientside or serverside technologies such as persistence systems

Harness the reactive programming model to process data streams

Design robust, maintainable, and testable code

Be proficient in manipulating JSON data blobs

Deploy your application on a PaaS platform

What do you get with Print?

Instant access to your digital copy whilst your Print order is Shipped

Paperback book shipped to your preferred address

Redeem a companion digital copy on all Print orders

Access this title in our online reader with advanced features

DRM FREE - Read whenever, wherever and however you want

Frequently bought together

£41.99

£24.99

Total £ 66.98

Filter reviews by

All

Amazon verified reviews

Mike Feb 02, 2015

Excellent book with a lot of examples and tips. Provides a continuous learning form the beginning in a medium technical language which helps understanding everything, even if we are new at PLAY.Recomend it for sure. For deep knowledge the Cookbook is also a mandatory book to summarize, review and learn some new tricks.

Amazon Verified review

Abhishek Srivastava Jun 24, 2015

I love this book. I tried couple of play framework books on safari. I found that either they were were old and examples were obsolete or they were very poorly written.Finally I found this book and it is very recent. all examples work. nothing is obsolete.I also find that the book is comprehensive and well written.

Martin Nov 24, 2014

- Concise reading without long stories.- Short code snippets cover just the important parts of solution.- Includes everything important like session authentication, CSRF prevention and others. (I have not found these topics in few other books.)

Juraj Zachar Jan 01, 2015

The content of the book is great but the kindle format is hard to work with. The lack of navigable list of contents makes browsing of the book's chapters cumbersome. I was expecting much better usability and I wish I had gone for a hard cover.

Dustin Marx Nov 01, 2014

"Play Framework Essentials" provides a rapid introduction to the Play Framework. In 7 chapters and under 200 pages, "Play Framework Essentials" introduces Play Framework and covers details such as building and exposing web services with Play, building web application clients that integrate with Play, persisting data from a Play application to a relational database, testing a Play application, refactoring Play application code, and deploying a Play application. The book also describes how developers can take advantage of Play's concurrency model, security support, internationalization support, and caching support."Play Framework Essentials" provides numerous code listings. These are black font on white background with no line numbers and no color syntax. The examples demonstrate applying Play in both Java and Scala programming languages and explains the relatively small number of features that are only available in one language or the other. There are also several graphics in the book that are mostly grayscale but one or two of them has some color in it.Although there are fewer than 200 pages of substantive text in "Play Framework Essentials," the book still manages to cover a significant amount of technical detail. This is accomplished by spending very little time covering historical or background details of the Play Framework and jumping right into technical discussion.

Play Framework essentials: An intuitive guide to creating easy-to-build scalable web applications using the Play framework

What do you get with Print?

Play Framework essentials

Chapter 1. Building a Web Service

Play – a framework used to write web applications

Tip

Bootstrapping a Play application

Note

Play applications' layout

URL routing

Route path parameters

Parameters type coercion

Parameters with fixed values

Query string parameters

Default values of query string parameters

Trying the routes

Page 1 of 7

Description

What you will learn

Product Details

What do you get with Print?

Product Details

Frequently bought together

Table of Contents

Recommendations for you

Customer reviews

Filter reviews by

People who bought this also bought

About the author

FAQs

Play Framework essentials: An intuitive guide to creating easy-to-build scalable web applications using the Play framework

What do you get with Print?

Contact Details

Shipping Address

Billing Address

Description

What you will learn

Product Details

What do you get with Print?

Contact Details

Shipping Address

Billing Address

Product Details

Packt Subscriptions

Frequently bought together

Table of Contents

Recommendations for you

Customer reviews

Filter reviews by

People who bought this also bought

About the author

FAQs