Tutorial: Getting started with scala and scalatra - Part I

In this series of tutorials we’re going to look a bit closer at scalatra. Scalatra is a lightweight scala based micro-web framework, that can be used to create high performance websites and APIs. In this first tutorial we’ll just get started with the installation of scalatra and import our test project into Eclipse.

SBT and giter8

Before you can get started you need to install a couple of tools (I’m assuming you’ve got a JDK 1.6+ installed). I’ll give you the condensed installation instructions, and extensive version of this can be found at the following scalatra page (http://www.scalatra.org/getting-started/first-steps.html). This approach should work for most environments, for my own however, it didn’t work… It downloaded old versions of giter8 and an old version of sbt. For sbt I used macports to get the latest version:

port install sbt

And I also downloaded giter8 manually.

curl https://raw.github.com/n8han/conscript/master/setup.sh | sh
cs n8han/giter8

This last command will install g8 in your /bin directory. I've tested this with this g8 version:

~/bin/g8

giter8 0.5.0
Usage: g8 [TEMPLATE] [OPTION]...
Apply specified template.

OPTIONS
    -b, --branch
        Resolves a template within a given branch
    --paramname=paramvalue
        Set given parameter value and bypass interaction.


Apply template and interactively fulfill parameters.
    g8 n8han/giter8

Or
    g8 git://github.com/n8han/giter8.git

Apply template from a remote branch
    g8 n8han/giter8 -b some-branch

Apply template from a local repo
    g8 file://path/to/the/repo

Apply given name parameter and use defaults for all others.
    g8 n8han/giter8 --name=template-test

Create initial project

Go to the root directory where you keep you projects and run the following:

jos@Joss-MacBook-Pro.local:~/dev/scalatra/firststeps$ g8 scalatra/scalatra-sbt
organization [com.example]: org.smartjava
package [com.example.app]: org.smartjava.scalatra     
name [scalatra-sbt-prototype]: hello-scalatra
servlet_name [MyScalatraServlet]: HelloScalatraServlet
scala_version [2.9.1]: 
version [0.1.0-SNAPSHOT]:

This will create a hello-scalatra folder in the directory your in that contains the project.

./build.sbt
./project
./project/build.properties
./project/plugins.sbt
./README.md
./src
./src/main
./src/main/resources
./src/main/resources/logback.xml
./src/main/scala
./src/main/scala/org
./src/main/scala/org/smartjava
./src/main/scala/org/smartjava/scalatra
./src/main/scala/org/smartjava/scalatra/HelloScalatraServlet.scala
./src/main/scala/Scalatra.scala
./src/main/webapp
./src/main/webapp/WEB-INF
./src/main/webapp/WEB-INF/layouts
./src/main/webapp/WEB-INF/layouts/default.scaml
./src/main/webapp/WEB-INF/views
./src/main/webapp/WEB-INF/views/hello-scalate.scaml
./src/main/webapp/WEB-INF/web.xml
./src/test
./src/test/scala
./src/test/scala/org
./src/test/scala/org/smartjava
./src/test/scala/org/smartjava/scalatra
./src/test/scala/org/smartjava/scalatra/HelloScalatraServletSpec.scala

To test if everything is working, go into this directory and use sbt to start the application from sbt with ‘container:start’. This will download a lot of stuff, and finally start the application:

jos@Joss-MacBook-Pro.local:~/dev/scalatra/firststeps/hello-scalatra$ sbt
[info] Loading project definition from /Users/jos/Dev/scalatra/firststeps/hello-scalatra/project
[info] Set current project to hello-scalatra (in build file:/Users/jos/Dev/scalatra/firststeps/hello-scalatra/)
> container:start
[info] jetty-8.1.5.v20120716
[info] NO JSP Support for /, did not find org.apache.jasper.servlet.JspServlet
[info] started o.e.j.w.WebAppContext{/,[file:/Users/jos/Dev/scalatra/firststeps/hello-scalatra/src/main/webapp/]}
[info] started o.e.j.w.WebAppContext{/,[file:/Users/jos/Dev/scalatra/firststeps/hello-scalatra/src/main/webapp/]}
15:12:44.604 [pool-6-thread-4] INFO  o.scalatra.servlet.ScalatraListener - Initializing life cycle class: Scalatra
[info] started o.e.j.w.WebAppContext{/,[file:/Users/jos/Dev/scalatra/firststeps/hello-scalatra/src/main/webapp/]}
15:12:44.727 [pool-6-thread-4] INFO  o.f.s.servlet.ServletTemplateEngine - Scalate template engine using working directory: /var/folders/mc/vvzshptn22lg5zpp7fdccdzr0000gn/T/scalate-5609005579304140836-workdir
[info] Started SelectChannelConnector@0.0.0.0:8080
[success] Total time: 1 s, completed Sep 7, 2012 3:12:44 PM
>
[success] Total time: 1 s, completed Sep 7, 2012 3:10:05 PM

To test if everything is correct point the browser to localhost:8080 and you’ll see the following screen:

Import in Eclipse

I usually develop with Eclipse, so in this case, lets make sure we can edit the source code in Eclipse. For this we can use sbt eclipse plugin. Adding this plugin is very easy. Go to the ‘project’ folder and add the following (with an empty line before it) to the plugins.sbt file.

addSbtPlugin("com.typesafe.sbteclipse" % "sbteclipse-plugin" % "2.1.0")

When you next run sbt, you’ll see a lot of stuff being downloaded. From sbt run ‘eclipse’ and eclipse configuration files (.classpath and .project) will be created. Now start up the Eclipse IDE and you can import the project you just created (make sure you also install the scala-ide for Eclipse).

Now we can start the container, and let sbt listen for changes in our resources.

$ sbt
> container:start
> ~ ;copy-resources;aux-compile

Any time we save a file in Eclipse, sbt will copy and recompile the resources. So we can directly see our changed files in the browser. Open the file HelloScalatraServlet and change the welcome text. If you save this, sbt will reload the application and you’ll directly see the changed files.

That’s it for part one of this tutorial. Next week we’ll look at how we can use scalatra to create a REST based service.