Saturday, July 30, 2011

Eager Fetching and Mapping Entities with Scala

Note: This post assumes you are doing the sql-results to objects mapping manually. Which I find it is the best approach (we'll leave the reasons for another post).

Lets say we have an Employee entity that is related (in the database) to a few other entities.
case class Employee (firstName: String, lastName :String)
case class Department (name:String)
case class Project (name:String)

To model the relationship, we COULD create a field on the Employee entity that references the department and the project:
case class Employee (
  firstName :String, 
  lastName :String, 
  department :Department,  // <---
  project :Project         // <---
)
But when displaying a page it might turn out that we only need the employee info, not the department or project. When retrieving them from the database, we might choose to leave those null, but that will mean we'll get an NPE (at runtime of course: very bad) if we happen to reference one of the related entities on the page. We might also choose to use Option but that's not entirely accurate, since they are not "Optional" fields, we KNOW that for a particular page we WILL need, say, the Department to be there.

This is where traits and the ability to apply them at instantiation comes in handy.

As an example, let say I would like to display a list of employees with their respective departments. I can create traits that specify that an entity comes with a related entity:
trait HasDepartment {
  val department :Department
}
trait HasProject {
  val project :Project
}
Now, when rendering the table of employees with their departments, I can use the trait to specify the required entity:
def listEmployees (projects:List[Employee with HasDepartment]) = {
  <table>
    <tr>
      <th>Name</th>
      <th>Department</th>
    </tr>
    {for (e <- employees) yield
      <tr>
        <td>{e.firstName} {e.lastName}</td>
        <td>{e.department.name}</td>
      </tr>
    }
  </table>
}
The requirement only specifies that the Employee must have its related Department. If we try to display the related Project using {e.project.name} we will get a compile-time error complaining about the missing "project" property right away (very good).

Now, how do we actually add the related Department to the Employee when querying the database? Like this:
// let's assume we are using some basic db wrapper, like anorm
val employees = queryResults.map(row => {
  new Employee ( row[String]("employee.first_name"), row[String]("employee.last_name") ) 
      with HasDepartment {
    val department = Department( row[String]("department.name") )
  }
})
It is now encoded on the type that this Employee entity has its related Department entity (eagerly fetched). You can now decide on a case by case basis when to include related entities, and have it checked by the compiler that you are only able to use them when they have been included.

As an extra example, here is the same code that actually requires that the Project entity also be there:
def listEmployees (projects:List[Employee with HasDepartment with HasProject]) = {
  <table>
    <tr>
      <th>Name</th>
      <th>Department</th>
      <th>Project</th>
    </tr>
    {for (e <- employees) yield
      <tr>
        <td>{e.firstName} {e.lastName}</td>
        <td>{e.department.name}</td>
        <td>{e.project.name}</td>
      </tr>
    }
  </table>
}
And the code to map the employee from the database:
// let's assume we are using some basic db wrapper, like anorm
val employees = queryResults.map(row => {
  new Employee ( row[String]("employee.first_name"), row[String]("employee.last_name") ) 
      with HasDepartment with HasProject {
    val department = Department( row[String]("department.name") )
    val project = Project( row[String]("project.name") )
  }
})

Tuesday, March 22, 2011

Play! Framework and Templating with Scala: XML Literals

As you know from the previous post, I have been developing using the Play! / Scala / Scalate / Squeryl combination as my platform. Everything has been working well, but I haven't been that happy with Scalate. I am not a fan of the syntax (ssp or any of the others), the fact that the play plugin is outdated (must compile from source), and that eclipse won't compile it and let me know of errors like it does for plain scala files.

This got me thinking, since Scala supports XML literals, there should be some way to take advantage of them for templating. I had considered it before but had dismissed the idea because:
  • It required some sort of compilation unit (class, object) for each template.
  • It was not designer friendly (see above).
  • I wasn't familiar enough with Scala to really try it.
Well, after some time has passed, it turns out I don't care about designer friendliness (not sure why I cared about it before, I've always gotten a PSD file that I end up turning into a templates myself) and I am more comfortable with scala now. So it was time to consider it again.

So I gave it a try and I am REALLY surprised at how well it works. And you get TONs of benefits: Compile time checks, auto-complete in the IDE, full power of scala, familiar syntax, etc.

Layouts

Layouts were the first thing I needed. A way to create a widget that takes parameters (like html attributes) and that wraps around template code. So I started with an object to hold my layout templates. One method for each template. We can also leverage default values, multiple parameter lists, and by-name parameters to make the syntax for the client code extra nice:

object Templates {
  // a page template
  def page (title:String="Default title")(content: => xml.Elem) = {
    <html>
    <head>
      <title>{title}</title>
    </head>
    <body>
      {content}
    </body>
    </html>
  }

  // a panel template, just as an example
  def panel (label:String="Some label")(content: => xml.Elem) = {
    <div class="panel">
      <div class="panel-label">{label}</div>
      <div>{content}</div>
    </div>
  }
}

[Note: As you can see, the syntax highlighter in this blog is unfortunately not as sophisticated as the scala compiler when it comes to XML literals]

Now you can use these directly on your controllers:

import util.Templates._

object Application extends Controller {
  def index = 
    page(title="Welcome to my Page!") {
      <div>
        <h1>Hello</h1>
        
        <p>Some template markup</p>

        {panel(label="Dashboard panel")(
          <div>
            Panel content
          </div>
        )}
      </div>
    }
}

Loops and Ifs

Within your XML, you can use "for" and "if" as you would in plain scala:
...
<div>
{for (user <- users if user.isAdmin) yield
  <div>
    {user.name} 
    {if (user.isAvailable) 
      <img src="available.png"/> 
      else 
      <img src="unavailable.png"/>
    }
  </div>
}
</div>
...

Intra-Application Links

Play! comes with a really cool way to go from a method-call-to-controller to a url (reverse routing), but there's no equivalent way to do that from scala. But it turns out it is really easy to create a method that will do that for you. I'll put it in a Utils object I can import on my pages:
import play.mvc.results._
object Utils {
    def Url (action: => Any) = new ScalaAction(action).actionDefinition.url    
}
We can now use it like this:
import util.Utils._ // import Url method and others

object Application extends Controller {
  def users = 
    page(title="Users page") {
      <div>
        <a href={Url( Application.user(24) )}>Click to see user page</a>
      </div>
    }

  def user (userId:Int) = {
    ...
  }
}

As you can see, XML literals can work great as the templating solution for a web app.