Step 1) Create the app:

grails create-app grailbars

You’ll need to do the rest of this from inside the newly created “grailbars” directory:

cd grailbars

Step 2) Create a new domain object:

grails create-domain-class com.jamesward.grailbars.Bar

Step 3) Edit the grails-app/domain/com/jamesward/grailbars/Bar.groovy file so it looks like:

package com.jamesward.grailbars
 
class Bar {
    String name
}

Step 4) Create a controller for the Bar:

grails create-controller com.jamesward.grailbars.Bar

Step 5) Edit the grails-app/controllers/com/jamesward/grailbars/BarController.groovy file so it looks like:

package com.jamesward.grailbars
 
class BarController {
    def scaffold = Bar
}

Step 6) Run the app locally to test it out:

grails run-app

Now open it in your browser: http://localhost:8080/grailbars

Step 7) Update the data source configuration to use the free Postgres database on Heroku. First edit the grails-app/conf/DataSource.groovy file and replace the “production” section with:

production {
    dataSource {
        dbCreate = "update"
        driverClassName = "org.postgresql.Driver"
        dialect = org.hibernate.dialect.PostgreSQLDialect    
        uri = new URI(System.env.DATABASE_URL?:"postgres://test:test@localhost/test")
        url = "jdbc:postgresql://"+uri.host+uri.path
        username = uri.userInfo.split(":")[0]
        password = uri.userInfo.split(":")[1]
    }
}

Now add the Postgres JDBC driver as a dependency by adding the following to the “dependencies” section of the grails-app/conf/BuildConfig.groovy file:

runtime 'postgresql:postgresql:9.1-901-1.jdbc4'

Step 8) Setup a git repository for the project which will be used for transferring the files to Heroku:

grails integrate-with --git
git init
git add application.properties grails-app test web-app
git commit -m init

Step 9) Login with the Heroku CLI:

heroku login

Step 10) Ceate a new application using the “cedar” stack:

heroku create -s cedar

Step 11) Upload your application to Heroku:

git push heroku master

Now open the application running on Heroku in your browser (the URL was in the “heroku create” and “git push” output). Verify that it works. Awesome! You just built a Grails app and deployed it on the Cloud with Heroku! For more details on using Grails on Heroku, visit the Heroku Dev Center. Let me know if you have any questions. Thanks!

Web browser modernization has paved the way to move from the old “browser as a thin client” model to more of a Client/Server model where the client-side of the application actually runs in the browser. There are a lot of names for this new model, Ajax being a step along the way, and perhaps HTML5 being the full realization of Client/Server web apps.

There are hundreds of new libraries, tools, programming languages, and services that support the creation of these next generation web (and mobile) apps. One thing that is certainly lacking is one cohesive, end-to-end solution. I have no doubt that we will be seeing those crop up soon, but in the mean time lets pick a few libraries and build a couple simple apps to get a better understanding of what this new model looks like.

I’ve decided to try this with a stack consisting of Scala for my back-end code, BlueEyes for handling data access and serialization with transport over HTTP, MongoDB for data storage, and JavaScript with jQuery for the client-side. I’m going to keep this very simple and not pull in anything else. In future articles I’ll expand on this foundation.

So lets dive into some code. All of the code is on GitHub. If you want to get a local copy just do:

git clone git://github.com/jamesward/helloblueeyes.git

This project uses the Scala Build Tool (SBT) for downloading dependencies, compiling, and packaging. Follow the SBT setup instructions if you want to be able to compile the code on your machine. If you want to use IntelliJ or Eclipse then run one of the following commands:

sbt gen-idea

sbt eclipse

Lets start with some BlueEyes basics. BlueEyes is a lightweight web framework built on Netty (a really high performance, NIO-based HTTP library). BlueEyes makes it easy to define a tree of HTTP request handling patterns. I chose BlueEyes because it’s really lightweight and utilizes some nice features of the Scala language to make the code very concise. It’s kinda like a DSL for HTTP request handling.

To get started with BlueEyes we first need to create an AppServer that provides a way to start the server and a place to plug services into. Here is the code for the AppServer:

package net.interdoodle.example
 
object AppServer extends EnvBlueEyesServer with HelloHtmlServices with HelloJsonServices with HelloStartupShutdownServices with HelloMongoServices

My AppServer is an object which means it’s a singleton (that makes sense because I can’t have more than one of these in a single instance). The AppServer extends EnvBlueEyesServer which is a wrapper around the base BlueEyesServer that provides a way to get the HTTP port via an environment variable (this is necessary for running on Heroku – which we will get to later). The AppServer composes in a bunch of Services that actually setup HTTP request pattern trees.

Starting with the simplest one, HelloHtmlServices we have:

trait HelloHtmlServices extends BlueEyesServiceBuilder with BijectionsChunkString {
  val helloHtml = service("helloHtml", "0.1") { context =>
      request {
        path("/") {
          produce(text/html) {
            get { request =>
              val content = <html>
                <body>Hello, world!</body>
              </html>
              val response = HttpResponse(content = Some(content.buildString(true)))
              Future.sync(response)
          }
        }
      }
    }
  }
}

Using the BlueEyesServiceBuilder the HelloHtmlServices trait creates a service that consists of a big pattern match that goes something like this: For a request to path “/”, produce an HTML response when there is a HTTP GET request. Notice that the response is actually wrapped in a Future. This is an important part of the next generation web app architecture. Because the underlying HTTP server is NIO-based (non-blocking), the actual HTTP handling threads can be very efficiently managed so that a thread is only in use when actual IO is happening. BlueEyes supports this by using Future wrapped responses, allowing the HTTP thread to be unblocked by back-end processing.

If you want to try this out locally run the following to compile the app and create a Unix script that makes it easy to start the AppServer:

sbt stage

Now start the AppServer process:

target/start net.interdoodle.example.AppServer

Verify that HelloHtmlServices is working by opening the following URL in your browser:
http://localhost:8080/

Now lets walk through a few steps to deploy this application on the cloud with Heroku.
Step 1) Sign up for a Heroku account
Step 2) Install the Heroku Toolbelt
Step 3) Login to Heroku from the command line:

heroku login

Step 4) Create a new application on Heroku using the Cedar stack:

heroku create -s cedar

Step 5) Deploy the app on Heroku:

git push heroku master

Step 6) Verify that the app works in your browser:

heroku open

Great! We have an app built with Scala and BlueEyes running on the cloud. Now for the next piece of the architecture. The UI of the application will be written in JavaScript and will run on the client-side. But we need to have a way to transfer data between the client and the server. JSON has become the regular way to do this because it is parsed easily and quickly on the client. So a BlueEyes service will generate some JSON data that can then be consumed by a JavaScript application running on the client. But how do we get that JavaScript application running on the client? This is the next piece of the architecture.

Ideally the JSON services are served separately from the client-side of the application (where the client-side includes all HTML, JavaScript, CSS, images, and other static assets). It is also ideal to serve the client-side from a Content Delivery Network (CDN) so that it’s edge cached and loads super fast. Dynamic assets (the JSON services) can’t be edge cached so there is a logical (and functional) separation between the client-side and the server-side. But there is a problem with this approach.

The CDN and the JSON services hosts each have different DNS names and browsers don’t allow cross-origin requests (actually they don’t allow access to the responses). There are a few different ways to deal with this (JSONP, iframe hackery, etc) but the approach I’m taking is simple. The JSON services server will serve an entry point / thin shim web page. That shim then loads the rest of the client-side from the CDN and since the origin of the web page is the same as the JSON services, there is no need to make a cross-origin request. (Side note: There is a new way to do cross-origin requests cleanly and natively in the browser, but it’s not ubiquitously supported yet.)

Here is HelloJsonServices that illustrates these patterns:

trait HelloJsonServices extends BlueEyesServiceBuilder with BijectionsChunkJson with BijectionsChunkString {
  val helloJson:HttpService[ByteChunk] = service("helloJson", "0.1") { context:HttpServiceContext =>
    request {
      path("/json") {
        contentType(application/json) {
          get { request: HttpRequest[JValue] =>
            val jstring = JString("Hello World!")
            val jfield = JField("result", jstring)
            val jobject = JObject(jfield :: Nil)
            val response = HttpResponse[JValue](content = Some(jobject))
            Future.sync(response)
          }
        } ~
        produce(text/html) {
          get { request: HttpRequest[ByteChunk] =>
            val contentUrl = System.getenv("CONTENT_URL")
 
            val content = <html xmlns="http://www.w3.org/1999/xhtml">
              <head>
                <script type="text/javascript" src={contentUrl + "jquery-1.7.min.js"}></script>
                <script type="text/javascript" src={contentUrl + "hello_json.js"}></script>
              </head>
              <body>
              </body>
            </html>
            Future.sync(HttpResponse[String](content = Some(content.buildString(true))))
          }
        }
      }
    }
  }
}

This service handles requests to “/json” and if the requested content type is JSON then a simple JSON object is returned. If the requested content is HTML then the shim web page is returned. Inside the shim web page an environment variable, CONTENT_URL, is used to specify the URLs to load the JavaScript for the application.

The first JavaScript is the minified jQuery library. This abstracts some browser differences, makes doing the JSON request and modifying the webpage very simple. Here is the main client application hello_json.js:

$(function() {
    $.ajax("/json", {
        contentType: "application/json",
        success: function(data) {
            $("body").append(data.result);
        }
    });
});

This application has a function handler for when the page has loaded. That function makes an ajax request to “/json” with the “application/json” content type. Then on a successful response it just appends the result into the web page.

To run this locally first set the CONTENT_URL environment variable to the CDN where I’ve put the JavaScript files:

export CONTENT_URL=http://cdn-helloblueeyes.interdoodle.net/

Now start (or restart) the server and open:
http://localhost:8080/json

To test the JSON service locally run:

curl --header "Content-Type:application/json" http://localhost:8080/json

You can also use a local static file server for testing, just run net.interdoodle.example.httpstaticfileserver.HttpStaticFileServer and set CONTENT_URL accordingly.

If you want to try this on Heroku then set CONTENT_URL for your application:

heroku config:add CONTENT_URL=http://cdn-helloblueeyes.interdoodle.net/

This will set the environment variable and restart the application. Then navigate to the your Heroku application’s “/json” URL in your browser. Now both the server-side and client-side are cloudified!

Side Note: I’m using Amazon CloudFront as the CDN for this example. But any CDN would work fine. There are various ways to upload files to Amazon CloudFront (actually they get uploaded to Amazon S3) but one thing I’m looking into is a SBT plugin that will do this.

Now lets add some simple data access into the mix. I’ve chosen MongoDB because it has native support for JSON and we can take advantage of Hammersmith – a non-blocking MongoDB driver. In this example I’m not using Hammersmith since support for it hasn’t been officially added to BlueEyes (but at least there is the opportunity to easily switch to Hammersmith in the future).

Here is the code for HelloMongoServices:

trait HelloMongoServices extends BlueEyesServiceBuilder with MongoQueryBuilder with BijectionsChunkJson with BijectionsChunkString {
 
  val helloMongo = service("helloMongo", "0.1") {
    logging { log => context =>
      startup {
        // use MONGOLAB_URI in form: mongodb://username:password@host:port/database
        val mongolabUri = Properties.envOrElse("MONGOLAB_URI", "mongodb://127.0.0.1:27017/hello")
        val mongoURI = new MongoURI(mongolabUri)
 
        HelloConfig(new EnvMongo(mongoURI, context.config.configMap("mongo"))).future
      } ->
      request { helloConfig: HelloConfig =>
        path("/mongo") {
          contentType(application/json) {
            get { request: HttpRequest[JValue] =>
              helloConfig.database(selectAll.from("bars")) map { records =>
                HttpResponse[JValue](content = Some(JArray(records.toList)))
              }
            }
          } ~
          contentType(application/json) {
            post { request: HttpRequest[JValue] =>
              request.content map { jv: JValue =>
                helloConfig.database(insert(jv --> classOf[JObject]).into("bars"))
                Future.sync(HttpResponse[JValue](content = request.content))
              } getOrElse {
                Future.sync(HttpResponse[JValue](status = HttpStatus(BadRequest)))
              }
            }
          } ~
          produce(text/html) {
            get { request: HttpRequest[ByteChunk] =>
              val contentUrl = System.getenv("CONTENT_URL")
 
              val content = <html xmlns="http://www.w3.org/1999/xhtml">
                              <head>
                                <script type="text/javascript" src={contentUrl + "jquery-1.7.min.js"}></script>
                                <script type="text/javascript" src={contentUrl + "hello_mongo.js"}></script>
                              </head>
                              <body>
                              </body>
                            </html>
              Future.sync(HttpResponse[String](content = Some(content.buildString(true))))
            }
          }
        }
      } ->
      shutdown { helloConfig: HelloConfig =>
        Future.sync(())
      }
    }
  }
}

This service has a startup hook that creates a MongoDB connection based on the MONGOLAB_URI environment variable or a default value. Then there are three request handlers for the “/mongo” path. The first handles JSON HTTP GET requests by fetching some data from MongoDB and returning it. A JSON HTTP POST handler inserts the JSON that was sent into MongoDB. Then there is a HTML HTTP GET request handler that returns the web page shim that loads the JavaScript from the CDN.

Here is the client-side of the application hello_mongo.js:

$(function() {
 
    $("body").append('<h4>Bars:</h4>');
    $("body").append('<ul id="bars"></ul>');
    $("body").append('<input id="bar"/>');
    $("body").append('<button id="submit">GO!</button>');
 
 
    $("#submit").click(addbar);
    $("#bar").keyup(function(key) {
        if (key.which == 13) {
            addbar();
        }
    });
 
    loadbars();
 
});
 
function loadbars() {
    $.ajax("/mongo", {
        contentType: "application/json",
        success: function(data) {
            $("#bars").children().remove();
            $.each(data, function(index, item) {
                $("#bars").append("<li>" + item.name + "</li>");
            });
        }
    });
}
 
function addbar() {
    $.ajax({
        url: "/mongo",
        type: 'post',
        dataType: 'json',
        success: loadbars,
        data: '{"name": "' + $("#bar").val() + '"}',
        contentType: 'application/json'
    });
}

This JavaScript application starts by adding some elements to the page for displaying and entering “bars”. The loadbars() function makes a ajax GET request to the JSON service and then appends the result into the element on the page with the id of bars. The addbar() method makes a POST request to the JSON service, passing serialized JSON containing the name of the “bar” to the JSON service, then on success it calls loadbars().

If you want to run this locally then you will need a MongoDB server setup and running locally. Make sure CONTENT_URL is set correctly and if your MongoDB settings differ from the default, then set the MONGOLAB_URI environment variable. Start the AppServer process and then open:
http://localhost:8080/mongo

You should be able to add new “bars” and see them listed.

To run on Heroku you will need to add the MongoLab add-on. When the MongoLab add-on is added the MONGOLAB_URI environment variable on your Heroku application will be automatically set with the connection information for the newly provisioned MongoDB system. To add the MongoLab add-on just run:

heroku addons:add mongolab

Now open your Heroku app’s “/mongo” URL in your browser. Wahoo! You have a client/server browser app running on the cloud! Hopefully that has helped you to get a glimpse of where web application architecture is going. This is just part of the picture and I have a few other articles planned that will cover some of the other pieces. So keep watching here and let me know what you think.

Acknowledgments: Mike Slinn, a friend of mine that does Scala and Akka consulting, helped me understand BlueEyes and helped write some of the code for this project. Mike is also the author of the recently released book Composable Futures with Akka 2.0 with Java and Scala Code Examples.

On Thursday Feb 16 I will be at Spring I/O in Madrid speaking about Running Spring Apps on the Cloud with Heroku at 12:40.

Hope to see you there!

1. Signup for a Heroku account
   
   
2. Install the Heroku plugin locally:

   $ play install heroku

3. Create a Play (1.2.3 or 1.2.4) app:

   $ play new foo --with heroku

4. Deploy the app:

   $ play heroku:deploy foo

   You should see something like:

   ~        _            _ 
   ~  _ __ | | __ _ _  _| |
   ~ | '_ \| |/ _' | || |_|
   ~ |  __/|_|\____|\__ (_)
   ~ |_|            |__/   
   ~
   ~ play! 1.2.4, http://www.playframework.org
   ~
   ~ Deploying app to Heroku
   Listening for transport dt_socket at address: 8000
   Project directory: /home/jamesw/Desktop/foo
   Read Heroku API key from /home/jamesw/.heroku/credentials
   Created new ssh key pair (heroku_rsa) in: /home/jamesw/.ssh
   Added the heroku_rsa.pub ssh public key to your Heroku account
   Created a .git directory for your project
   Added and committed all of the local changes to the git repo
   Created app: cold-night-1511
   http://cold-night-1511.herokuapp.com/
   Added git remote: git@heroku.com:cold-night-1511.git
   Deploying application via git push
   Application deployed
   ~ App Deployed

   Note: I haven’t figured out how to pipe the git push output to the screen yet, so be patient when the app is being git pushed. It’s working, just takes a minute.

5. Check out your Play app running on the cloud! Use the URL in the “heroku:deploy” output. This should work with new and existing Play apps.

All of the code for the Heroku Play module is on GitHub. There is more I want to do with this (scaling, logs, etc) and your contributions are certainly welcome! Keep checking back here for updates and let me know how it goes!

• Cincinnati JUG on January 26th
• Detroit JUG on January 31st
• MongoDB Boulder on Febuary 1st

Hope to see you there!

Here are steps you can follow to get started running Java on Heroku with Eclipse and your browser:

Prerequisites) Install the EGit and Maven (m2e) Eclipse plugins into your Eclipse. In Eclipse select the “Help” menu, select “Install new Software”, from the “Work With” drop-down menu select “All Available Sites”, and enter “EGit” in the filter box. After the plugin list has loaded (could take a minute) then select the “Eclipse EGit” plugin, select “Next”, and finish walking through the wizard to the plugin. Then do the same for the Maven Plugin “m2e”.

Step 1) Go to java.herokuapp.com and select an application template. In the screencast I used the “Simple Java Web App with Maven and Tomcat” option since it uses the familiar WAR packaging and Tomcat. Enter your email address and click the “Go!” button. This will create a copy of the template, upload it to Heroku, and assign you as the owner of the app. When the app is created you will see some instructions and a link to the application running on Heroku.

Step 2) You should have received an email from Heroku indicating that an application has been shared with you. If this is your first time using Heroku you will need to click the account setup link in the email in order to set your password on Heroku.

Step 3) If this is the first time you have used Heroku then you will need to create and associate a ssh key with your Heroku account. This will be used to authenticate you for git file transfers (to copy the application to/from Heroku). One way to create a new ssh key and associate it with your Heroku account is via key.herokuapp.com. Just enter your Heroku username / password and a new ssh key will be created, associated with your account, and then downloaded. You will then need to setup Eclipse to use that key. Go to the “Window” menu -> “Preferences” -> search for “SSH”, select “Add Private Key…”, select the private key that was just downloaded, and then select “OK”.

Step 4) Now you are ready to import the created project into Eclipse. Select the “File” menu -> “Import”, select “Project from Git”, select “Clone…”, paste the git URL into the “URI” box (you will find the git URL in the java.herokuapp.com instructions or in the email from Heroku), and select “Next”.

Eclipse will fetch the branches of the remote git repository and should display just a master branch. Select “Next” and then “Finish”. A local copy of the project will now be on your computer. Now select “Next”, select “Import as general project, select “Next”, and then select “Finish” to complete the import. From here you can take a few other steps to setup the project for local development. First, install the m2e-wtp connector, create a new Tomcat server in Eclipse, change the web module context root to “/”, and then you can just right-click on the project and select “Run As” -> “Run on Server”.

Step 5) Make a change to the app that you will be able to see when the new version is pushed to Heroku. For instance, add something to the index.jsp file. If you have setup your Eclipse for local development then you should be able to test this change locally before pushing it to Heroku.

Step 6) To commit the changes to the local git repository, right-click on the project, select “Team” -> “Commit…”, enter a commit message, and select “Commit”.

Now that the changes are in the local git repository they can be pushed to Heroku. Right-click on the project, select “Team” -> “Push to Upstream”. This will send your change to Heroku and then Heroku will run the project’s Maven build and redeploy the changes. When the process has completed you will see the details of the push and the Maven build.

Now refresh (or load) the app in your browser and you should see the changes.

That should be enough to get you started. As you dive in further check out the Heroku Dev Center for a lot more details on using Java on Heroku. Let me know if you have any questions.

• San Diego Java User’s Group on Tuesday, January 17th
• Silicon Valley Web JUG on Wednesday, January 18th
• The Capital District Java Developers Network on Thursday January 19th

Hope to see you there!

• Boulder, Colorado – December 13
• Phoenix, Arizona – December 14
• Portland, Oregon – December 20

I hope to see you there!

Step 1) Download and install Play Framework 1.2.3

Step 2) Create a new Play app from the command line and then move to the new directory:

play new playbars
cd playbars

Optional Step 3) If you want to work in an IDE then you can run one of the following commands and then open the generated project in your IDE:

play idealize

play eclipsify

I won’t walk though the IDE specific steps here, but you can refer to the Play documentation on IDE integration if you want to get that setup. Note that IntelliJ IDEA has great support for Play Framework with a console right in the IDE.

Step 4) Start the Play server from the new project’s directory :

play run --%test

This starts Play in test mode which will automatically recompile any changes we make to the application. No packaging, redeploying, or restarting servers will be needed.

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

The default page provides you with great Play documentation on how to get started. But we will soon be changing that page. If you want to view the documentation locally after we change the page you can use these links:

• Documentation
• Play JavaDoc

Step 6) Lets start by creating a new JPA entity. Keeping it very simple, lets create a new “app/models/Bar.java” file containing:

package models;
 
import play.db.jpa.Model;
 
import javax.persistence.Entity;
 
@Entity
public class Bar extends Model {
 
    public String name;
 
}

This entity uses the standard JPA Entity annotation but also extends the Play Model class which provides some nice conveniences which you can read more about in the Play JPA docs. I’m using just a plain public property on this class but you can also use the Java Bean getter/setter stuff in you like.

Step 7) Create a simple unit / integration test for this Bar object by creating a “test/BarTest.java” file with the following contents:

import org.junit.*;
import java.util.*;
import play.test.*;
import models.*;
 
public class BarTest extends UnitTest {
 
    @Test
    public void integrationTest() {
        Bar bar = new Bar();
        bar.name = "a new bar";
        bar.save();
        assertNotNull(bar.id);
        assertTrue(Bar.findAll().size() >= 1);
        bar.delete();
        assertTrue(Bar.findAll().size() == 0);
    }
 
}

Step 8) Setup the default database by editing the “conf/application.conf” file and uncommenting the following line:

# db=mem

This sets up the default database to be an in-memory database.

Step 9) Run the application’s tests by opening the following URL in your browser:
http://localhost:9000/@tests

Select “BarTest” and then click the “Start!” button. The test should pass.

Step 10) Add the following two methods to the “app/controllers/Application.java” file:

    public static void addBar(Bar bar) {
        bar.save();
        index();
    }
 
    public static void listBars() {
        renderJSON(Bar.findAll());
    }

The addBar method takes a Bar, saves it, and then redirects back to the index page. Play will automatically parse request parameters and populate the Bar object. The listBars method queries for all of the Bars in the database and then outputs then as serialized JSON.

Step 11) Play has a very flexible model for mapping URLs to controllers. Lets setup two new routes that will map URLs to the new methods we’ve added to the Application controller. Add the following lines to the “conf/routes” file but make sure you either add them above the “Catch all” or simply remove the “Catch all” route:

POST    /                                       Application.addBar
GET     /bars.json                              Application.listBars

The first route handles HTTP POST requests to the “/” URL and handles them with the Application.addBar method. The second route handles requests to the “/bars.json” URL and handles them with the Application.listBars method.

Step 12) Lets add a FunctionalTest that will actually make requests to the Controller and test that our new routes and controller methods are working. Add the following method to the “test/ApplicationTest.java” file:

    @Test
    public void barTest() {
        Response addBarResponse = POST("/", APPLICATION_X_WWW_FORM_URLENCODED, "bar.name=foo");
        assertStatus(302, addBarResponse);
        Response listBarsResponse = GET("/bars.json");
        assertIsOk(listBarsResponse);
    }

This test adds a new Bar by doing an HTTP POST to “/” and passing it some form encoded data. Then a request is made to “/bars.json” and the response is checked to make sure there wasn’t an error. Since there isn’t a DELETE method (which could easily be added) there isn’t a good way to clean up what this test does.

Run the ApplicationTest Functional Test in the Play Framework Web Test Runner:
http://localhost:9000/@tests?select=ApplicationTest.class

Because the test didn’t clean up after itself you can now see the JSON from “/bars.json” in your browser by visiting:
http://localhost:9000/bars.json

Step 13) Now it is time to create the actual web UI for this application. A combination of plain HTML (via Play’s Groovy templates) and jQuery will be used. Play Framework uses a convention to render the HTML from the “app/views/Application/index.html” template when Application.index‘s render method is called. In the “index.html” file and you will see:

#{extends 'main.html' /}
#{set title:'Home' /}
 
#{welcome /}

You can also take a look at the referenced “app/views/main.html” file to see what the base template looks like. It does the standard HTML page stuff and then inserts the body of the “index.html” page into the “#{doLayout /}” section. The “main.html” template also loads jQuery and provides a way to insert some JavaScript into the head section of the page. In the “index.html” file, replace the “#{welcome /}” line with a form that will allow users to create new bars:

#{form @addBar()}
    <input type="text" name="bar.name"/>
    <input type="submit"/>
#{/form}

The “#{form @addBar()}” syntax is Groovy that creates a form tag and sets the form action to the URL that corresponds to the Application.addBar method. You can test this out by loading this page in your browser:
http://localhost:9000/

The form should be functional now. Enter the name of a bar and click the submit button. Because the “addBar” method calls the “index” method, after the POST, the browser is redirected back to the index page. You can verify that the data is being saved by loading the bars.json page again.

Now lets add some Ajax / jQuery to the “index.html” page that will get the JSON data and display it in the page. Add an empty ul tag with an id of “bars”:

<ul id="bars">
 
</ul>

Now we will insert the JavaScript into the correct place in the page by setting the “moreScripts” variable:

#{set 'moreScripts'}
<script type="text/javascript">
    $(function() {
        $.get("bars.json", function(data) {
            $.each(data, function(index, item) {
                $("#bars").append("<li>Bar " + item.name + "</li>");
            });
        });
    });
</script>
#{/set}

Using jQuery this bit of JavaScript adds a function handler for when the page is loaded, then in that function it makes a get request to “bars.json”. That request has a function handler for when the result comes back from the Ajax request. Inside that function handler the data is iterated through and each “bar” is appended into the page element with the id of “bars” – the ul tag.

Try out the application and make sure that you can still add new bars and see the list of all the bars in the database.

Now that everything works locally, lets deploy the app on the cloud using Heroku.

Step 1) Create an account on Heroku.com, install the Heroku Toolbelt and git and then login to Heroku from the command line:

heroku login

If this is the first time you’ve done this then new ssh keys for git will be created and associated with your Heroku account.

Step 2) Each application on Heroku has a Postgres database for testing. To use that database when running on Heroku we need to configure it. Play applications on Heroku run in “prod” mode. To set the database to use the Heroku database add the following lines to the “conf/application.conf” file:

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

The default way to provide database (and other resource) connection strings to an application on Heroku, is through environment variables. The DATABASE_URL environment variable will contain the database host, name, username, and password. Play Framework knows how to handle that information and setup the JDBC connections.

Step 3) Heroku uses git as a means to uploading applications. Whether or not you use git for your SCM tool you can use git as the tool to upload an app to Heroku. In the root directory of your project create git repo, add the files to it, and then commit the files:

git init
git add app conf public test
git commit -m init

Note: Instead of doing a selective “git add” you can create a “.gitignore” file containing the files to not add to the git repo.

Step 4) Now we will provision a new application on Heroku using the Heroku CLI. Each application you create gets 750 free “dyno” hours per month. So as a developer you can use Heroku for free and only pay when you need to scale beyond one dyno. On the command line create a new application using the “cedar” stack:

heroku create -s cedar

This creates an HTTP endpoint and a git endpoint for your application. You can also use a custom name and point your own domain names at the application.

Step 5) The application is ready to be deployed to the cloud. From a command line do a “git push” to the master branch on Heroku:

git push heroku master

Once the files have been received by Heroku, Play Framework’s precompiler will be run, Heroku will assemble a “slug file”, and then the “slug” will be deployed onto a dyno.

Step 6) You can now open the application in your browser by navigating to the domain outputted following the “heroku create” or by simply running:

heroku open

You’ve built a Play Framework application with JPA, JSON, & jQuery and then deployed that application on the cloud with Heroku! Now get the code and check out a demo on Heroku. Let me know if you have any questions.