Running Play Framework + Scala Apps on Heroku

Building Play Framework apps with Scala is all the rage right now. And for good reason… It’s never been easier to build and deploy JVM-based web apps! Lets walk through how to build a Play app with Scala and then deploy it on the cloud with Heroku.

Step 1) Install the Play Framework (make sure you have at least version 1.2.3)

Step 2) Install the Play Scala module:

play install scala

Step 3) Create a new Play app with Scala support:

play new playwithscala --with scala

Step 4) Start the app:

cd playwithscala
play run

Step 5) Open the app in your browser:
http://localhost:9000

That was easy! Lets spice this up a bit before we deploy it on Heroku by adding a custom model, view, and controller.

Step 1) Create a new app/models/Widget.scala file containing:

package models
 
case class Widget(id: Int, name: String)

Step 2) Create a new app/views/Widget/list.scala.html file containing:

@(widgets: Vector[models.Widget])
 
<!DOCTYPE html>
<html>
    <body>
        @widgets.map { widget => 
            Widget @widget.id = @widget.name</br>
        }
    </body>
</html>

Step 3) Create a new app/controllers/WidgetController.scala file containing:

package controllers
 
import play._
import play.mvc._
 
object WidgetController extends Controller {
 
    import views.Widget._
    import models.Widget
 
    def list = {
        val widget1 = Widget(1, "The first Widget")
        val widget2 = Widget(2, "A really special Widget")
        val widget3 = Widget(3, "Just another Widget")
        html.list(Vector(widget1, widget2, widget3))
    }
 
}

Step 4) Test out the new code by going to:
http://localhost:9000/WidgetController/list

It works! And we didn’t even need to reload the server! But lets clean up that URL a bit. Edit the conf/routes file and change “Application.index” to “WidgetController.list”:

GET     /                                       WidgetController.list

Now load the new URL:
http://localhost:9000/

That was easy but now we want to show our friends. So lets deploy it on Heroku.

Step 1) Install the Heroku command line client on Linux, Mac, or Windows

Step 2) Login to Heroku from the command line:

heroku auth:login

Step 3) Heroku uses git for application upload, so create a .gitignore file containing:

/modules
/tmp

Step 4) Create a git repo, add the files to it, and commit them:

git init
git add .
git commit -m init

Step 5) Create the new application on Heroku:

heroku create -s cedar

This provisions a new application on Heroku and assigns a random name / URL to the app.

Step 6) Deploy the application:

git push heroku master

The application will now be assembled and deployed on Heroku.

Step 7) Open the application in the browser:

heroku open

Tada! Your Play + Scala app is now running on the cloud!

At JavaOne I showed this to Bill Venners (creator of ScalaTest). He then moved the scalatest.org website (a Play + Scala app) to Heroku! Cool stuff!

Let me know if you have any questions.

Posted in Play Framework, Scala | 14 Comments

Learning Scala: Function Literals

I’ve gradually been learning Scala over the past few months and I really have been enjoying it. For me Scala is like Shakespeare. It seems familiar and totally foreign at the same time. I don’t enjoy Shakespeare plays nearly as much as someone who has taken the time to learn the language of Shakespeare. Some have interpreted Scala being “familiar yet totally foreign” as Scala being “hard” but I’d say it’s just different. With Scala there is probably more about programming that I need to unlearn than to learn. My perspectives on programming languages have been shaped by the ones I’ve used most (Java, ActionScript, etc). And now my perspecives are being reshaped. It might take some time and work but I believe that using Scala will soon be very enjoyable for me.

Ok, enough fluff lets see some code!

My friend Mike Slinn and I have been learning BlueEyes – a lightweight Scala web 3.0 framework. We encountered a piece of Scala that seemed strange and unfamiliar to us:

get { request =>
  // do something
}

To a Java developer like me this was pretty foreign. I was able to understand this after I encountered Function Literals in the free Scala for the Impatient book. So let me break down what is happening here with another example. Lets start with writing a regular function that takes a Char parameter and returns a Boolean if the provided Char was the letter “l”:

def lls(p: Char): Boolean = { p == 'l' }

This is a pretty straight forward (albeit slightly verbose) function definition. Oh, and I should mention that if you download Scala and run the REPL (a command line interpreter), then you can actually try this code yourself. To start the Scala REPL just run the “scala” command.

Ok, lets test out that function:

lls('p') // outputs false
lls('l') // outputs true

That should all be somewhat familiar looking for a Java developer. But here is where things begin to look more foreign. The StringOps class in Scala has a count method that takes something very peculiar looking. From the ScalaDoc:

def count (p: (Char) ⇒ Boolean): Int

That is saying that count takes a function as an argument. Scala is this wonderful blend of Object Oriented and Functional so this is instantly strange to the Java developer in me. In this case the function that count is taking must have a single parameter of type Char and then return a Boolean. So lets try to pass the lls function to count on a StringOps instance. Somehow with Scala’s Type Inference system we can just use a regular double-quoted String and Scala will figure out that we need a StringOps instead. So let’s create a StringOps object and call count on it passing it the lls function:

"Hello".count(lls) // outputs 2

I could have assigned “Hello” to a variable and done it that way but opted to just make the count call without assigning it. So count correctly took the lls function and used it to count the number of “l” Chars in the String (or SpringOps). That all works as expected.

But, there is another (prettier) way to do the same thing:

"Hello" count lls // outputs 2

We can drop the dot operator and parenthesis and everything still works. But there is another way… Instead of referencing a function we can just pass the function definition directly into the count method:

"Hello" count { p:Char => p == 'l' } // outputs 2

This is a Function Literal – or as Dick Wall tells me, a predicate in this case since it returns a Boolean. A Function Literal is a short way to define a function that takes only one parameter and returns what is needed by whatever the function is being passed to. In this case the function parameter is still a Char with an identifier of “p” and the function body simply compares “p” with the ‘l’ Char. In Scala the value of the last statement in a function is returned. So the Boolean is returned from the function. That type is inferred. And the Char type declaration on “p” could have been left off and inferred making it:

"Hello" count { p => p == 'l' } // outputs 2

Now that code I started with is making a lot more sense!

But it doesn’t stop there. With Scala we can be even more concise:

"Hello" count { _ == 'l' } // still outputs 2

Now I must admit that I haven’t really learned what that “_” thing does. So I don’t totally understand this code yet. But like learning to understand Shakespeare we have to take it one step at a time. I will leave that to another day and maybe another blog post. I hope this was helpful for other Scala noobs. Let me know what you think and if you have any questions.

Posted in Scala | 1 Comment

Heroku Java User Group Tour Part 1: Los Angeles and Salt Lake City

This week I’m starting a Java User Group tour where I’ll be travelling to JUGs around the US (or maybe world). On the tour I’ll be giving a talk about Running Java, Play! and Scala Apps on the Cloud. Here is the description:

Heroku is a Polyglot Cloud Application Platform that makes it easy to deploy Java, Play! and Scala apps on the cloud. Deployment is as simple as doing a “git push”. This session will teach you how to instantly deploy and scale Java, Play! and Scala apps on Heroku.

I’m still scheduling JUGs but here are the first two I’ll be doing:

There will be more to come and if you’d like this talk at your local Java User Group, let your leader know and have them email me: jw <at> heroku <dot> com

Hopefully see you at your local JUG!

Posted in Heroku, Java, Play Framework, Scala | 3 Comments

Heroku is Hiring

It’s been four months since I started working at Heroku as a Developer Evangelist. Now it is clear to me that I got really lucky. Heroku is a top-notch place to work. The product is sexy. The people are all rock stars. Heroku is owned by Salesforce.com so there is the stability of a large company but the start-up culture remains in place.

Heroku is looking to hire lots of people (engineers, marketing, etc) but of particular interest to my readers might be the Java Developer Evangelist position. Come work with me to help educate Java developers about Heroku!

BTW: Check out how the application asks for your GitHub URL. I love this place!

Posted in Heroku | 5 Comments

Getting Started with Scala on Heroku

Over the past year I’ve been gradually learning Scala and I think it’s fantastic! So I’m incredibly excited that Scala now runs on Heroku! Of course you can use the standard Java on Heroku / Maven method of running Scala on Heroku. But as of today you can also use sbt (the Scala Build Tool) to run Scala apps on Heroku. If you are new to Heroku, it is a Polyglot Cloud Application Platform. Put very simply:

Heroku = Polyglot + Platform as a Service (PaaS) + Cloud Components

If you want to try out Scala on Heroku, here are a few quick steps to get you started:

  1. Create a Heroku account
  2. Install the Heroku command line client on Linux, Mac, or Windows.
  3. Install git and setup your SSH key
  4. Install sbt 0.11.0
  5. Login to Heroku from the command line:

    heroku auth:login
  6. Create a file named build.sbt containing:
    scalaVersion := "2.9.1"
     
    {
      val stage = TaskKey[Unit]("stage", "Prepares the project to be run, in environments that deploy source trees rather than packages.")
      stage in Compile := {}
    }

    This adds the “stage” task which is used for the build on Heroku.

  7. Create a project/build.properties file containing:
    sbt.version=0.11.0

    This tells sbt which version of sbt to use.

  8. Create a very simple Scala app in src/main/scala/Hello.scala containing:
    object Hello extends App {
      println("hello, world")
    }
  9. Test the app locally by running:
    sbt run

    You should see something like:

    [info] Set current project to default-0c17d0 (in build file:/home/jamesw/projects/helloscala/)
    [info] Running Hello 
    hello, world
    [success] Total time: 1 s, completed Sep 7, 2011 4:17:01 AM
  10. Create a .gitignore file containing:
    target
    project/boot
    project/target
  11. Create a git repo, add the files to it, and commit them:
    git init
    git add .
    git commit -m init
  12. Create a new app on Heroku using the Cedar stack:
    heroku create -s cedar
  13. Upload your app to Heroku using git:
    git push heroku master
  14. Run the app on Heroku:
    heroku run "sbt run"

    Voilà! You just ran Scala on the Cloud!

You can get the full code for this project on github:
https://github.com/jamesward/helloscala

That was a very simple example to get you started. Visit the Heroku Dev Center to continue learning about how to use Scala on Heroku. And let me know if you have any questions.

Posted in Heroku, Scala | Comments closed

Java Concurrency with Akka: Composing Futures

I’ve been intrigued by Akka for a while but finally I was able to take it for a spin. The first thing I wanted to learn was how to compose Futures. Composing Futures provides a way to do two (or more) things at the same time and then wait until they are done. Typically in Java this would be done with a CyclicBarrier ExecutorService. But setting up the code to manage a CyclicBarrier is challenging. (UPDATE: Turns out it’s not very challenging, I just didn’t know how to do it. I’m new to concurrency in Java and didn’t find much on this stuff – probably because I didn’t even know what to search for.) So I put together a quick little demo that shows how to do the same thing with Futures in Akka.

All of the code for this demo is on github:
http://github.com/jamesward/AkkaFun

First I setup a Gradle build that pulls in the Akka dependency and will allow me to easily launch the demo app. Here is the build.gradle file:

apply plugin:"application"
mainClassName = "com.jamesward.akkafun.SimpleFutures"
 
repositories {
    mavenCentral()
}
 
dependencies {
  compile "se.scalablesolutions.akka:akka-actor:1.2-RC6"
}

For this demo I also wanted to increase the Akka timeout to 1 minute (the default is 5 seconds). To do this I created a src/main/resources/akka.conf file containing:

akka {
    actor {
        timeout = 60
    }
}

I then setup a Callable class that does some work and then returns it’s result. For this example the work is just to pause for a random amount of time and the result is the amount of time it paused for. Here is the src/main/java/com/jamesward/akkafun/RandomPause.java file:

package com.jamesward.akkafun;
 
import java.util.concurrent.Callable;
 
public class RandomPause implements Callable<Long>
{
 
    private Long millisPause;
 
    public RandomPause()
    {
        millisPause = Math.round(Math.random() * 8000) + 2000; // 2,000 to 10,000
        System.out.println(this.toString() + " will pause for " + millisPause + " milliseconds");
    }
 
    public Long call() throws Exception
    {
        Thread.sleep(millisPause);
        System.out.println(this.toString() + " was paused for " + millisPause + " milliseconds");
        return millisPause;
    }
}

I used a simple Java app to compose the RandomPause futures. Here is the src/main/java/com/jamesward/akkafun/SimpleFutures.java file:

package com.jamesward.akkafun;
 
import java.util.ArrayList;
import java.util.List;
 
import akka.dispatch.Future;
import static akka.dispatch.Futures.future;
import static akka.dispatch.Futures.sequence;
 
public class SimpleFutures
{
    public static void main(String[] args)
    {
        List<Future<Long>> futures = new ArrayList<Future<Long>>();
 
        System.out.println("Adding futures for two random length pauses");
 
        futures.add(future(new RandomPause()));
        futures.add(future(new RandomPause()));
 
        System.out.println("There are " + futures.size() + " RandomPause's currently running");
 
        // compose a sequence of the futures
        Future<Iterable<Long>> futuresSequence = sequence(futures);
 
        // block until the futures come back
        Iterable<Long> results = futuresSequence.get();
 
        System.out.println("All RandomPause's are complete");
 
        Long totalPause = 0L;
        for (Long result : results)
        {
            System.out.println("One pause was for " + result + " milliseconds");
            totalPause += result;
        }
 
        System.out.println("Total pause was for " + totalPause + " milliseconds");
    }
}

Lets walk through the pieces of this.

First, a place to store the list of Futures is created:

List<Future<Long>> futures = new ArrayList<Future<Long>>();

The Future object is parameterized with the type of result the Future will return – a Long in this case. (I’m using the Akka Future not the regular Java Future.)

The Futures.future static method is used to create a new Future from an instance of a Callable object and that Future is added to the list of Futures:

futures.add(future(new RandomPause()));

In this case a RandomPause instance is created. This is done twice to add two futures to the list.

You may have noticed in RandomPause that Callable is parameratized with a Long:

public class RandomPause implements Callable<Long>

The result of the work (the call method) returns a Long so the Callable and the Future must be parameratized with a Long.

In order to compose the futures together, another Future will be created containing the sequence of the list of futures:

Future<Iterable<Long>> futuresSequence = sequence(futures);

The Future is parameratized with an Iterable which is parameratized with a Long to match the result of the Callable. The Futures.sequence method is used to create the new Future from the list of Futures.

Using the futuresSequence the applicaiton can wait (or block) until the RandomPause objects in futures list have all returned, or the timeout was reached:

Iterable<Long> results = futuresSequence.get();

Each result is now available. That seems too easy! Thanks Akka!

Let me know if you have any questions about this example.

Posted in Akka, Java | 9 Comments

Video: Running Java Web Apps on the Cloud

Here is a quick screencast that shows how to instantly deploy Java web applications on the cloud with Heroku.

If you want more than a quick introduction check out a recording of my presentation at JavaZone. And visit heroku.com/java for more details on how to get started running Java apps on Heroku.

Posted in Cloud, Heroku, Java | 1 Comment

Flex AOP and Puzzlers at Flash Camp Italy

Next week I’ll be speaking at the Flex Camp in Rimini, Italy. On September 23, Mike Labriola and I will be doing two sessions. First is “Planet of the AOPs” where we will show how Aspect Oriented Programming can be implemented in Flex using runtime bytecode modification. Mike and I will also be doing a little “Flex Puzzlers” session where you will discover some very peculiar things about Flex and Flash Player. It’s going to be a blast and I hope to see you there! Also, there will be a raffle for a copy of Creative Suite 5.5 and a Playbook. So go sign up NOW!

Posted in Flex | Leave a comment

Sending Play Framework File Uploads to Amazon S3

UPDATE: I’ve released a S3 Play Module based on this project.

A couple of questions [1, 2] on StackOverflow.com led me to look into how we can send file uploads in a Play Framework application to Amazon S3 instead of the local disk. For applications running on Heroku this is especially important because the local disk is not persistent. Persistent disk storage makes it hard to scale apps. Instead of using the file system, it’s better to use an external service which is independent of the web tier.

While at JavaZone I sat down with Peter Hilton and Nicolas Leroux to come up with a way to handle this. It only took us 30 minutes to get something working – start to finish – including setup time. This is what is so compelling about Play Framework. I’ve built many Java web apps and it always seems like I spend too much time setting up builds, IDEs, and plumbing. With Play we were setup and working on the actual app in less than a minute. After getting everything working locally it took another minute to actually run it on the cloud with Heroku. The combination of Play Framework and Heroku is a developer’s dream for fast-paced development and deployment.

All of the code for the sample application is on github:
https://github.com/jamesward/plays3upload

The basics of what we did was this:

public static void doUpload(String comment, File attachment)
{
    AWSCredentials awsCredentials = new BasicAWSCredentials(System.getenv("AWS_ACCESS_KEY"), System.getenv("AWS_SECRET_KEY"));
    AmazonS3 s3Client = new AmazonS3Client(awsCredentials);
    s3Client.createBucket(BUCKET_NAME);
    String s3Key = UUID.randomUUID().toString();
    s3Client.putObject(BUCKET_NAME, s3Key, attachment);
    Document doc = new Document(comment, s3Key, attachment.getName());
    doc.save();
    listUploads();
}

This uses a JPA Entity to persist the metadata about the file upload (for some reason we named it ‘Document’) and a reference to the file’s key in S3. But there was a sexier way, so my co-worker Tim Kral added a new S3Blob type that could be used directly in the JPA Entity. Tim also cleaned up the configuration to make it more Play Framework friendly. So lets walk through the entire app so you can see the pieces.

The app/models/Document.java JPA Entity has three fields – the file being of type S3Blob:

package models;
 
import javax.persistence.Entity;
 
import play.db.jpa.Model;
import s3.storage.S3Blob;
 
@Entity
public class Document extends Model
{
    public String fileName;
    public S3Blob file;
    public String comment;
}

The S3Blob is now doing all of the work to talk to the Amazon S3 APIs to persist and fetch the actual file.

Configuration of S3 is done by adding a plugin to the conf/play.plugins file:

0: s3.storage.S3Plugin

The S3Plugin handles reading the AWS credentials from the conf/application.conf file, setting up the S3Client, and creating the S3 Bucket – if necessary.

In the conf/application.conf file, environment variables are mapped to the configuration parameters in the Play application:

aws.access.key=${AWS_ACCESS_KEY}
aws.secret.key=${AWS_SECRET_KEY}
s3.bucket=${S3_BUCKET}

The values could be entered into the conf file directly but I used environment variables so they would be easier to change when running on Heroku.

The Amazon AWS API must be added to the conf/dependencies.yml file:

require:
    - play
    - com.amazonaws -> aws-java-sdk 1.2.7

The sample application has a new controller in app/controllers/Files.java that can display the upload form, handle the file upload, display the list of uploads, and handle the file download:

package controllers;
 
import java.io.File;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.util.List;
 
import models.Document;
import play.libs.MimeTypes;
import play.mvc.Controller;
import s3.storage.S3Blob;
 
public class Files extends Controller
{
 
  public static void uploadForm()
  {
    render();
  }
 
  public static void doUpload(File file, String comment) throws FileNotFoundException
  {
    final Document doc = new Document();
    doc.fileName = file.getName();
    doc.comment = comment;
    doc.file = new S3Blob();
    doc.file.set(new FileInputStream(file), MimeTypes.getContentType(file.getName()));
 
    doc.save();
    listUploads();
  }
 
  public static void listUploads()
  {
    List<Document> docs = Document.findAll();
    render(docs);
  }
 
  public static void downloadFile(long id)
  {
    final Document doc = Document.findById(id);
    notFoundIfNull(doc);
    response.setContentTypeIfNotSet(doc.file.type());
    renderBinary(doc.file.get(), doc.fileName);
  }
 
}

The uploadForm() method just causes the app/views/Files/uploadForm.html page to be displayed.

The doUpload() method handles the file upload and creates a new Document object that stores the file in S3 and the comment in a database. After storing the file and comment it runs the listUploads() method. Of-course a database must be configured in the conf/application.conf file. For running on Heroku the database is provided and just needs to be configured with the following values:

db=${DATABASE_URL}
jpa.dialect=org.hibernate.dialect.PostgreSQLDialect
jpa.ddl=update

The listUploads() method fetches all Document objects out of the database and then displays the apps/views/files/listUploads.html page.

If a user selects a file from the list then the downloadFile() method is called which finds the file in S3 and sends it back to the client as a binary stream. An alternative to this would be to get the file directly from Amazon using either the S3 generatePresignedUrl() method or via CloudFront.

Finally in the conf/routes file, requests to “/” have been mapped to the Files.uploadForm() method:

GET     /                                       Files.uploadForm

That’s it! Now we have an easy way to persist file uploads in an external system!

Running the Play! app on Heroku

If you’d like to run this example on Heroku, here is what you need to do:

Install the heroku command line client on Linux, Mac, or Windows.

Login to Heroku via the command line:

heroku auth:login

Clone the git repo:

git clone git@github.com:jamesward/plays3upload.git

Move to the project dir:

cd plays3upload

Create the app on Heroku:

heroku create -s cedar

Set the AWS environment vars on Heroku:

heroku config:add AWS_ACCESS_KEY="YOUR_AWS_ACCESS_KEY" AWS_SECRET_KEY="YOUR_AWS_SECRET_KEY" S3_BUCKET="AN_AWS_UNIQUE_BUCKET_ID"

Upload the app to Heroku:

git push heroku master

Open the app in the browser:

heroku open

Let me know if you have any questions or problems. And thanks to Peter, Nicolas, and Tim for helping with this!

Posted in Heroku, Java, Play Framework | 9 Comments