In the following sections, we will give make reference to an artist model. It is a simple class with a companion object, defined as follows:

case class Artist(name: String, country: String)

object Artist {
  val availableArtist = Seq(Artist("Wolfgang Amadeus Mozart", "Austria"), 
    Artist("Ludwig van Beethoven", "Germany"), 
    Artist("Johann Sebastian Bach", "Germany"), 
    Artist("Frédéric François Chopin", "Poland"), 
    Artist("Joseph Haydn", "Austria"), 
    Artist("Antonio Lucio Vivaldi", "Italy"), 
    Artist("Franz Peter Schubert", "Austria"), 
    Artist("Franz Liszt", "Austria"), 
    Artist("Giuseppe Fortunino Francesco Verdi", "Austria")) 

  def fetch: Seq[Artist] = {
    availableArtist 
  } 

  def fetchByName(name: String): Seq[Artist] = {
    availableArtist.filter(a => a.name.contains(name)) 
  } 

  def fetchByCountry(country: String): Seq[Artist] = {
    availableArtist.filter(a => a.country == country) 
  } 

  def fetchByNameOrCountry...

An Action in Play defines how a server should respond to a request. The methods, which define an Action, are mapped to a request in the routes file. For example, let's define an Action which displays the information of all the artists as a response:

def listArtist = Action {
  Ok(views.html.home(Artist.fetch))
}

Now, to use this Action, we should map it to a request in the routes file.

GET     /api/artist       controllers.Application.listArtist

In this example, we fetch all the artists and send them with the view, as the response to the request.

Run the application and access http://localhost:9000/api/artist from the browser. A table with the available artist is visible.

Action takes a request and yields a result. It is an implementation of the EssentialAction trait. It is defined as:

trait EssentialAction extends (RequestHeader => Iteratee[Array[Byte], Result]) with Handler {
 
  def apply() = this

...

Consider the most common POST request in any application—the request sent for logins. Will it be sufficient if the request body has the user's credentials in, say, a JSON or XML format? Will the request handler be able to extract this data and process it directly? No, since the data in the request has to be understood by the application code, it must be translated into a compatible type. For example, XML sent in a request must be translated to Scala XML for a Scala application.

There are several libraries, such as Jackson, XStream, and so on, which can be used to achieve this task, but we wouldn't need them as Play supports this internally. Play provides request body parsers to transform the request body into equivalent Scala objects for some of the frequently used content types. In addition to this, we can extend existing parsers or define new ones.

Every Action has a parser. How do I know this ? Well, the Action object, which we used to define how our app should respond...

Let's extend the JSON parser so that we get a subscription model. We will assume that the Subscription model is defined as follows:

case class Subscription(emailId: String, interval: String) 

Now, let's write a parser that transforms the request body into a subscription object. The following code should be written in a controller:

val parseAsSubscription = parse.using {
    request => 
      parse.json.map {
        body => 
          val emailId:String = (body \ "emailId").as[String] 
          val fromDate:Long = (body \ "fromDate").as[Long] 
          Subscription(emailId, fromDate)
      }
  }

  implicit val subWrites = Json.writes[Subscription]
  def getSub = Action(parseAsSubscription) {
    request => 
      val subscription: Subscription = request.body
      Ok(Json.toJson(subscription))
   } 

There are also tolerant parsers. By tolerant, we mean that errors in a format are not ignored. This simply means that it ignores the content type header in the request...

In Play, the response to a request is a result. A result has two components: the response header and the response body. Let's look at a simple example of this:

def plainResult = Action {
  Result( 
    header = ResponseHeader(200, Map(CONTENT_TYPE -> "text/plain")), 
    body = Enumerator("This is the response from plainResult method".getBytes())
  )
}

Notice that we used an enumerator for the response body. An enumerator is a means to provide data to an iteratee. We will discuss these in detail in Chapter 6, Reactive Data Streams.

Apart from this, a result has additional functions that equips us with better means to handle response headers, sessions, cookies, and so on.

A result can send JSON, XML, and images as a response, apart from a String content. An easier way of generating a result is to use the result helpers. A result helper is used for most of the HTTP response status. As an example, let's see how the TODO Action that comes built in with Play is implemented...

Suppose that we are at a food court and place an order to eat something at a kiosk, we are given a token and a bill. Later, when the order is ready, the kiosk flashes the token number, and upon noticing it, we collect the order.

This is similar to a request with an asynchronous response cycle, where the kiosk acts like the server, the order acts similar to a request, and the token as a promise, which gets resolved when the order is ready.

Most operations are better handled asynchronously. This is also mostly preferred since it does not block server resources until the operation is completed.

Play Action is a helper object, which extends the ActionBuilder trait. The apply method of the ActionBuilder trait implements the Action trait, which we saw earlier. Let's take a look at the relevant code from the ActionBuilder trait:

trait ActionBuilder[+R[_]] extends ActionFunction[Request, R] { 
  self => 

  final def apply[A](bodyParser: BodyParser[A])(block: R[A] => 
   ...