Category Archives: Play Framework

Play Framework(12)-template engine


Templates are complied as standard Scala functions, following a simple naming convention. If you create a views/Application/index.scala.html template file, it will generate a views.html.Application.index class that has an apply() method.

Special Character :

Scala template uses @ as the single special character. Every time this character is encountered, it indicates the beginning of a dynamic statement. If you want to insert a multi-token statement, explicitly mark it using brackets/curly brackets. Because @ is a special character, you’ll sometimes need to escape it by using @@.

Make sure that { is on the same line with for to indicate that expression continues to next line.


A template is like a function, so it needs parameters, which must be declared at the top of the template file.

You can write server side block comments in templates using @@.

Dynamic content parts are escaped according to the template type’s (e.g. HTML or XML) rules. If you want to output a raw content fragment, wrap it in the template content type.


Slick (3) – connection pool

Before talking into detailed knowledge about connection pool in Slick, we need to figure out two things: One is about Slick. Slick does not provide a connection pool implementation of its own. The other thing is about JDBC, which not provides asynchronous database driver for JVM. So we need to thread pool in Play Framework application to help improve performance.

1. Add connection pool to Slick:

Event Database contains an AsyncExecutor that manages the thread pool for asynchronous execution of Database I/O Actions. Its size is the main parameter to tune for the best performance of the Database object. It should be set to the value that we would use for the size of the connection pool in traditional, blocking application. For Slick, its default connection pool is HikariCP, which is a “zero-overhead” production-quality connection pool.

import play.api.db.DB
import play.api.Play.current
import slick.driver.MySQLDriver.simple._
object Contexts {
  def withSession[Res](f: Session => Res) = {
      AsyncExecutor(<executor_name>, <num_threads>, <queue_size>)) withSession f

2. connection pool configuration

There’re some important default configuration which we need to know. Of course, we can override them to optimize.

# HikariCP connection pool configure
play.db.hikaricp.connectionTimeout=30 seconds
play.db.hikaricp.maxLifetime=30 minutes

3. thread pool vs connection pool

There is dependency between these two pool setting is in maximum attribute.Let us assume that your database can support maximum of 50 connections then it is straight forward to configure the connection pool maximum attribute as 50. But how this setting going to impact thread pool setting? Configure application server thread pool as maximum of 100. In this scenario application server will allow 100 request to be processed simultaneously however database have only 50 connection. So only 50 thread will get connection another 50 thread will fight to get database connection hence connections will be switched between threads frequently that slow down overall application performance.

Just adding database connections will not improve performance, and can compromise availability because of the need to reestablish all the connections during failover.

Let us assume we set thread pool maximum setting same as connection pool maximum setting of 500. Application server will allow 50 thread to be processed simultaneously the remaining thread will be in wait state. All the 50 thread will get database connection immediately hence it will processed quickly.

The above example assumed each thread will use one database connection (may be multiple connections but sequentially); if your application uses two database connections parallels by each thread then configure thread pool maximum setting as half of the connection pool maximum.

Setting the thread pool size too large can cause performance problems because if there are too many concurrent threads, task switching overhead becomes a serious bottleneck. Any more threads than the number of connections available could be wasteful given contention for the connections. Fewer threads will not consume the number of connections available. 

4. number of processor core vs the size of a thread pool

  • More threads mean more memory usage. Each thread requires a thread stack. For recent HotSopt JVMs, the minimum thread stack size is 64KB, and the default can be as much as 1MB. That can be significant. In addition, any thread that is alive is likely to own or share objects in the heap whether or not it is currently runnable. Therefore it is reasonable to expect that more threads mean a larger memory working set.
  • A JVM cannot have more threads actually running than their cores (or hyperthreaded cores) on the execution hardware.

5. Involve connection pool to database querying

def delete(userID: Int): Boolean = Contexts.withSession { implicit session =>
  val users = TableQuery[Users]
  val filterInfo = users.filter( === userID)

  if ( {
  } else false

6. Reuse session within one logic

We know the more sessions we use, the much easier the connection pool uses up. So within one logic, we suggestion to pass session around to finish one purpose. In order to reuse session, we need to pass session as implicit.

def save(implicit session: Session, traitInfo: TraitInfo): Int = {
  val traits = TableQuery[Traits]
  (traits returning += traitInfo

7. Additional important things to know

Some Concepts on Slick we need to know/understand:

  1. For every database session (withSession blocks), Slick is opening a new connection to the database server.
  2. Session Handling:
    1. The Database object’s withSession method creates a Session, passes it to a given function and closes it afterward. If we use a connection pool, closing the Session returns the connection to the pool.
    2. Only the method actually executing the query in the database requires a Session. The executing methods are made available via implicit conversions.
    3. It is not recommended to handle the lifetime of a Session manually.
  3. All methods that execute a query take an implicit Session value. Of course, you can also pass a session explicit if you prefer.

Basic Knowledge on connection pool:

  1. Connection pools are common in network applications and they’re often tricky to implement. For example, it is often desirable to have timeouts on acquisition from the pool since various clients have different latency requirement.
  2. Pools are simple in principle: we maintain a queue of connections and we satisfy waiters as they come in. With additional synchronization primitives this typically involves keeping two queues: one of waiters (when there are no connections), and one of connections (when there are no waiters).

8. Todo In Future:

There are some points we can optimize.

  1. Slick uses prepared statements wherever possible but it does not cache them on its own. We should therefore enable prepared statement caching in the connection pool’s configuration and select a sufficiently large pool size.

Play Framework (1) – WebSocket

Even though Play uses async method to communicate with front-end and back-end. But sometimes, we still need to call third-party restful api to do something else. Especially, third-party restful api takes too long time to return data. In this case, it is wasteful to wait there and always ask whether it is ok or not. Good way to handle it is to make use of third-party callback and web socket to deal with this case.

So it is very clear that we have three sides: one is third-party api, the other is our back-end, another is our front-end.

What we need to do is that front-end builds a WebSocket with back-end. And then back-end requests data from third-party api. When third-party api returns data,  back-end sends data back to front-end.

  1. Build a web socket between front-end and back-end.
  2. front-end sends data to back-end
  3. back-end calls third-party api
  4. third-party api returns data back to back-end
  5. back-end returns data back to front-end by web socket

So, there are two routes, one is for web socket, another is for callback. The connection between the two is to store actorRef to keep the bridge. You also needs to ask callback to append special token back in order to figure out this actor.

  • Javascript code to send web socket to build connection between front-end and back-end.
  • var myWebSocket = new WebSocket("ws://<your_domain_name>/<your_ws_route>/");
    myWebSocket.onopen = function() { myWebSocket.send(<your_data>); }; 
    myWebSocket.onmessage = function(event) { alert(; // to render data }; 
    myWebSocket.onclose = function() { console.log("wsconnect close."); };
  • Nginx configuration to build connection. Please note: Here if you don’t configure “

    proxy_read_timeout” attribute, your websocket default connection time is 60 seconds and then it is closed automatically. So here normally I set it as 1d.

  • location /daoApp/websocket/create/ {
      proxy_pass  http://<your_domain_name>;
      proxy_http_version 1.1;
      proxy_set_header Host $host;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "upgrade";
      proxy_read_timeout 1d;
  • Play routes to accept web socket request and another one is to accept callback request
  • POST    /<your_callback_route>/ controllers.WebSocketApp.apiCallback
    GET     /<your_ws_route>/       controllers.WebSocketApp.create
  • And next I have one global variable to store actorRef for each connect between front-end and back-end. For each web socket request, I will store unique key combining the actorRef and trigger call to third-party api. For each callback request, I will to find its mapping actorRef to send data back to front-end.
  • object WebSocketApp extends Controller {
      // remember to build a map to store your actorRef
      // here we use ConcurrentHashMap which is to avoid memory leak in multiple cores device
      var channels = new ConcurrentHashMap[String, ChannelMsg]().asScala
      def apiCallback = Action {
        request =>
          val requestBody = request.body.asFormUrlEncoded
          requestBody match {
            case Some(s) =>
              if (s.contains("parentID")) {
                val parentID = s("parentID").head
                val channelInfo = channels.get(parentID)
                channelInfo match {
                  case Some(info) =>
                    val yourParsedData = <deal_with_data_from_api>
                    actorInfo match {
                      case Some(actor) =>
                        actor ! <your_parse_data>
                      case None =>
                  case None =>
            case None =>
      def create = WebSocket.acceptWithActor[String, String] { request => out =>
        Props(new DAOWSCreateActor(out, request))
    class DAOWSCreateActor(out: ActorRef, request: RequestHeader) extends Actor {
      override def receive = {
        case topicName: String =>
          val queryTokenInfo = <your_send_request_to_third_party>
          // remember to involve your actorRef to channelMsg which will be used to parse actor 
          valchannelMsg = <construct_your_channel_msg>
          // remember to involve your key to callback on post which will be used to find actor back to send data back to front-end
          WebSocketApp.channels.put(<your_key>, channelMsg)
        case _ =>

Play Framework (2) -Security (especially for web application)

Here we talk about how to make our web application much safer. Even though most front-end codes can be detected by any developers, we still can use back-end to protect each request’s security. I will list the method which attackers might be used to hack your system and then I give out basic and simple solution. Here I need to say something in advance: First, the solution here targets play framework. But i think the solution’s idea/view is general for other website framework. Second, because play framework already has multiple versions, i can’t try all of them and here we use 2.3.x . So if you use other play version, please consider how to implement solution in your own version. All in all, I will give out problem first and talk about my solution’s idea, and at last give code snippet to explain idea.

1. problem

we all know front-end uses router to connect with back-end in order to get some data or post data to store. Once the router is recognized by attacker. It is quite easy for other developers to send requests to back-end without requiring to login the system or in website. There are many public tools which can do this thing, like postman, etc.

2. solution

The solution is easy to think out: authentication. The authentication is already greatly used in many places and there are many mature libraries which already provide packaged class/object to call, like social-auth, play2-auth, etc.

But there are too complex, if you want simpler one, you just need to consider how to make sure “Action” is safe in your code. As we all know, each router mapping to back-end is Action, no matter GET or POST. If we can make sure “Action” is a safe action, our router is safe. So we try to re-define a double check Action which needs to check each request’s header whether it contains the authenticated info. If not, we treat this request is not authenticated, the request can’t be finished. For browser, this means the page needs to guide back to login page to force user login or signup. Only when user logins or signs up, we assign the authentication to the user. After the user is authenticated, the other requests are allowed from this user.

Here we list the logic:

  1. user login/signup, back-end will set the user authenticated
  2. user does other requests, back-end will treat it as authenticated
  3. if user not login/signup or already logout, the next request will be treated as unauthenticated, 401 will be returned.

3. code snippet

Define a useraction:

package controllers

import play.api.http.Status
import play.api.mvc._

import scala.concurrent.Future

object UserAction extends ActionBuilder[Request] {
  def invokeBlock[A](request: Request[A], block: (Request[A]) => Future[Result]) = {
    if (request.session.get("WWW-Authenticate").isDefined)
      Future { Results.Status(Status.UNAUTHORIZED) }

Login/signup with an authentication:

Ok(resultInfo).withSession("WWW-Authenticate" -> "user")



Other router using defined useraction:

 * Delete one user back to front-end
def delete = UserAction {
  request => {
      // do your things

4. Additional Info

(1) CSRF(cross-site-request-forgery)

Problem: If the attacker uses false info to signup, he/she still can use this authenticated user to do some dangerous things.

Solution: Of course, we can assign different levels of authentication. For example, for admin operations, only use who knows admin’s right or has admin’s authentication, he/she can obtain the operation.

But there is another easy way to solve it: filter.

To allow simple protection for non browser requests, such as requests made through AJAX, Play also supports the following:

  • If an X-Requested-With header is present, Play will consider the request safe. X-Requested-With is added to requests by many popular Javascript libraries, such as jQuery.
  • If a Csrf-Token header with value nocheck is present, or with a valid CSRF token, Play will consider the request safe.

(2) ActionBuilder

Action is just an implementation of ActionBuilder[Request]; we can extend ActionBuilder to use in place of Action as above codes in snippet.

ActionBuilder requires that we implement invokeBlock, which takes two parameters, the first is the incoming request, and the second is the function body, taking Request[A] as a parameter and returning a Future[Result]

block(request) means request processing continues as expected. (Don’t confuse the world “block” to mean the request gets blocked, it is actually executing the code block or function body it was passed earlier)

5. Recommend Links

(1) Here is link about how to use play header to fix CSRF: 

(2) Action Composition in Play Framework: and (this link’s knowledge is a little old, but really useful and completely. And it also provides more integral solution than mine. Strongly suggest to read. )



Play Framework (5) – performance optimization (1)

It is a long way on this road. When you finish one feature, it is just a start. The rest thing is to make it better and better. You will need to care more about performance. Servals things which I experience here I write down.

  1. Deployment method

    1. Don’t use start or run to deploy your production. It is totally wrong. You need to use:
      activator clean; activator dist

      to package your project and then unzip it which is under

      unzip #your_project_path/target/universal/  

      and then cd to this folder. you will find under /bin/ there is script which can run. My normal jvm parmaters like this: (Please note here my project uses Nginx as web server and New Relic to collect application performance info. You need to modify jvm parameters according to your project. )

      nohup bin/#YourApp -Dhttp.port=9081 -Dhttp.address=#MyPrivateServerIP -J-Xms4096m -J-Xmx4096m -J-Xmn2048m -J-javaagent:../../../newrelic/newrelic.jar &
  2. Third-party Tool

    1. check cpu and memory usage by New Relic (I have another post which tell you how to use free New Relic)
  3. Command Tool

    When you really meet problem, New Relic just tells you that your app is not normal. It is not enough to solve the problem. So the rest thing for you is to dig out the real cause. Here are some useful commands which will help you a lot.

    1. htop     This is more detailed info than New Relic. You can do some actions on your application and monitory by htop to see whether these actions will cause performance changes.
    2. jcmd     This will list all jvm applications and you will get each PID. Or jps -l 
    3. jcmd <PID> help  This will list commands to tell you how to use it to get which info you want.
      • The following commands are available:
        1. VM.native_memory
        2. VM.commercial_features
        3. GC.rotate_log
        4. ManagementAgent.stop
        5. ManagementAgent.start_local
        6. ManagementAgent.start
        7. Thread.print
        8. GC.class_histogram
        9. GC.heap_dump
        10. GC.run_finalization
        11. GC.runVM.uptime
        12. VM.flags
        13. VM.system_properties
        14. VM.command_line
        15. VM.version
        16. GC.class_stats    : print the name of the ClassLoader
    4. jcmd <PID> ###     Here ### is getting from the list in above command’s result. I care about cpu usage, so normally I use Thread.print to check which threads are using.
    5. jstack This directly outputs running threads. You also can output to local file by jstack > #YourFile
  4. Problems which I met

    When you already find root cause, the last thing is to solve it.

    1. Today my problem is that I use Akka to do some tasks, but each time scheduler finishes task and doesn’t shutdown its ActorSytem. The more tasks it does, the more threads it opens. Finally my cpu usage reaches 100% and then the project doesn’t have any response.(All of them are analyzed by above commands) I use above commands to find which actors are running and shutdown them when they finish. Now my project’s cpu usage is only 1.0% or so.
    2. Everything seems perfect. I also though my code would not meet performance in future. But nothing is perfect enough. So I come back to update this post to add more problems which I met. Today problem appears when I migrate application from old single-cpu server to new 8-cores server. The cpu usage for my application in old single-cpu server is only 0.5% every day. But for new high configuration cpu it is almost 400% (because it is 8 cores, it is equal to use up half of cpu). I use the method in above: and find root cause is HashMap.
      The easy method is to change hashmap to ConcurrentHashMap. After this modification, cpu usage goes to normal, 0.5%.

      var schedulerIDs = new ConcurrentHashMap[String, Cancellable]().asScala

      ConcurrentHashMap can solve the HashMap’s thread 100% cpu issue. HashMap doesn’t support multiple threads. Detailed info please read here:
      ConcurrentHashMap concurrency is the size of segment, by default it is 16. This means at most there are 16 threads operates ConcurrentHashMap. This is great benefit for ConcurrentHashMap, not for HashTable.

    3. My performance issue continues, now it is hard to find the root cause. I try to read more to understand them better. But it is really hard. This time, my memory is always increasing triggering by some actions which are hard to find role. To be honest, I find some hit in Thread.print which mentions lots of time of “ForkJoinPool”. So I go back to my code to check which thread will be created by forkjoinpool and how does forkjoinpool manage memory. Here I read these following words. In fact, in my old code, i used scala standard library, it caused increasing memory problem. When i change it to play.api.libs, thing becomes better.
    4. In Play 2.3.x and prior, play.core.Execution.Implicits.internalContext is a ForkJoinPool with fixed constraints on size, used internally by Play. You should never use it for your application code. From the docs: 
      Play Interval Thread Pool - This is used internally by Play. No application code should ever be executed by a thread in this thread pool, and no blocking should ever be done in this thread pool. Its size can be configured by setting internal-threadpool-size in application.conf, and it defaults to the number of available processors.
      Instead, you would use play.api.libs.concurrent.Execution.Implicits.defaultContext , which uses an ActorSytem.
      In 2.4.x, they both use the same ActorSystem. This means that Akka will distribute work among its own pool of threads, but in a way this is invisible to you (other than configuration). Several Akka actors can share the same thread. is an ExecutionContext defined in the Scala standard library. It is a special ForkJoinPool that using the blocking method to handle potentially blocking code in order to spawn new threads in the pool. You really shouldn't use this in Play application, as Play will have no control over it. It also has the poential to spawn a lot of threads and use a ton of memory, if you're not careful.

To be honest, there is no general method to optimize performance. The more experiences you have, the less errors you create. When you meet performance issue, don’t be afraid and pay attention on finding root cause step by step. Only when you know what’s the cause, you can find right solution to fix it. Before that, any guess or others’ method is only useless.

Play Framework (3) – evolutions

First if all, I need to explain why I use evolutions in Play Framework and why I write down this post. The reason is that when you design your database schema at the beginning of the project, you can’t expect everything. Your table schema might be needed to add new field, or change its length or other unpredictable operations. Of course, you can go to DB to change it directly, but in different env which is already deployed your project, how can they do? Change all of table schema by hand? Is it too stupid? In fact, before I really understand evolutions in Play Framework, I do it by hand :(. No worry, evolutions will remove all of the pains which I experienced before.

When you want to update your database design, you just need to write codes under evolutions folder and then, when you go to deploy your code to some env, it will automatically help you update the changes on database. Is it magic?

Let’s see how to really use evolutions.

1. Create evolutions scripts

mkdir conf/evolutions

Your scripts will be under this folder, like 1.sql, 2.sql, 3.sql, etc

The configuration of evolution is under application.conf. Default setting:


Of course, you can disable it by setting its value as disabled.

2. Syntax

Each script contains two parts: one is Ups that describe the required transformations, the other is Downs which describe how to revert them.

# Users schema
# --- !Ups
  id bigint(20) NOT NULL AUTO_INCREMENT,
  email varchar(255) NOT NULL,
  password varchar(255) NOT NULL,
  fullname varchar(255) NOT NULL,
  isAdmin boolean NOT NULL,
# --- !Downs

Play splits your .sql files into a series of semicolon-delimited statement before executing them one-by-one against database. So if you need to use a semicolon within a statement, escape it by enttering :: instead of ;.

3. Deployment

If you want to apply UP evolution automatically, you should set the system property


Or set


in application.conf.

If you want to run UP and DOWN evolutions automatically, you should set the system property


It is not recommended to have this setting in application.conf.

Play Framework (7) – Application Monitor Tool: New Relic

I want to find a way to make monitoring Play Application as simple as possible. Now I find one tool, named “New Relic” which already supports Play Framework. Here is a summary about how to involve New Relic to your application.

  • Step1: you need to login New Relic. (you need to see monitor result on your own account)
  • Step2: you need to download java agent.
    • please note: you’d better unzip this agent’s zip to /path/to/appRoot/
  • Step3: you need to use “activator dist” to re-build your application. Please note: third command: if you want to make it simple, you just need to add “-J-javaagent” to your command. Others are just configure JVM. If you want to configure New Relic, you just go to newrelic/newrelic.yml to modify your application’s name or others.
    • activator clean dist && unzip target/universal/*.zip
    • cd target/universal/YourUnzipFolder/
    • ./bin/YourApplicationName -J-javaagent:../../../newrelic/newrelic.jar -Duser.timezone=GMT -Dhttp.port=9081 -J-Xms4096m -J-Xmx4096m -J-Xmn2048m
  • Step4: done. you just need to go back to your New Relic Account to see the result. If you don’t know where to see your result. You can go to /newrelic/logs/newrelic_agent.log to see its log, like “Reporting to:″. Of course, different application has different id.