Route order

The first matching route is invoked. Routes are matched from the bottom up. This is the opposite of Sinatra. Route definitions are executed as part of a Scala constructor; by matching from the bottom up, routes can be overridden in child classes.

Path patterns

Path patterns add parameters to the params map. Repeated values are accessible through the multiParams map.

Obligatory scolding: the REPL is not a substitute for proper unit tests!

Rails-like pattern matching

By default, route patterns parsing is based on Sinatra. Rails has a similar, but not identical, syntax, based on Rack::Mount's Strexp. The path pattern parser is resolved implicitly, and may be overridden if you prefer an alternate syntax:

The route block is immediately exited and control continues with the next matching route. If no matching route is found, a 404 is returned.

Accessing the Servlet API

HttpServletRequest

The request is available through the request variable. The request is implicitly extended with the following methods:

body: to get the request body as a string

isAjax: to detect AJAX requests

cookies and multiCookies: a Map view of the request's cookies

Implements scala.collection.mutable.Map backed by request attributes

HttpServletResponse

The response is available through the response variable.

HttpSession

The session is available through the session variable. The session implicitly implements scala.collection.mutable.Map backed by session attributes. To avoid creating a session, it may be accessed through sessionOption.

ServletContext

The servlet context is available through the servletContext variable. The servlet context implicitly implements scala.collection.mutable.Map backed by servlet context attributes.

Configuration

The environment is defined by:
1. The org.scalatra.environment system property.
2. The org.scalatra.environment init property.
3. A default of development.

If the environment starts with "dev", then isDevelopmentMode returns true. This flag may be used by other modules, for example, to enable the Scalate console.

Error handling

Error handlers run within the same context as routes and before filters.

Not Found

Whenever no route matches, the notFound handler is invoked:

notFound {
<h1>Not found. Bummer.</h1>
}

Error

The error handler is invoked any time an exception is raised from a route block or a filter. The throwable can be obtained from the caughtThrowable instance variable. This variable is not defined outside the error block.

Flash scope

Flash scope is available by mixing in FlashMapSupport, which provides a mutable map named flash. Values put into flash scope during the current request are stored in the session through the next request and then discarded. This is particularly useful for messages when using the Post/Redirect/Get pattern.

Templating with Scalate

Scalatra provides optional support for Scalate, a Scala template engine.

Depend on scalatra-scalate.jar and a slf4j binding. In your SBT build:

When you want to use websockets with jetty the sbt build tool gets in the way and that makes it look like the websocket stuff isn't working. If you deploy the war to a jetty distribution everything should work as expected.

Testing Your Scalatra Applications

Scalatra includes a test framework for writing the unit tests for your Scalatra application. The framework lets you send requests to your app and examine the response. It can be mixed into the test framework of your choosing; integration with ScalaTest and Specs is already provided. ScalatraTests supports HTTP GET/POST tests with or without request parameters and sessions. For more examples, please refer to core/src/test/scala.

FAQ

It looks neat, but is it production-ready?

A project is in currently development to support a site with over one million unique users.

Are you using Scalatra in production? Tell us your story on the mailing list.

ScalatraServlet vs. ScalatraFilter

The main difference is the default behavior when a route is not found. A filter will delegate to the next filter or servlet in the chain (as configured by web.xml), whereas a ScalatraServlet will return a 404 response.

Another difference is that ScalatraFilter matches routes relative to the WAR's context path. ScalatraServlet matches routes relative to the servlet path. This allows you to mount multiple servlets under in different namespaces in the same WAR.

Use ScalatraFilter if:

You are migrating a legacy application inside the same URL space

You want to serve static content from the WAR rather than a dedicated web server

Use ScalatraServlet if:

You want to match routes with a prefix deeper than the context path.

Migration Guide

scalatra-2.0.0.M1 to scalatra-2.0.0.M2

Session has been retrofitted to a Map interface. get now returns an option instead of the value.

ScalaTest support has been split off into scalatra-scalatest module. ScalatraSuite moved to org.scalatest.test.scalatest package, and no longer extends FunSuite in order to permit mixing in a BDD trait. You may either use ScalatraFunSuite or explicitly extend FunSuite yourself.

Step to Scalatra

Scalatra was renamed from Step to Scalatra to avoid a naming conflict with (an unrelated web framework)[http://sourceforge.net/stepframework]. scalatra-1.2.1 is identical to step-1.2.0 with the following exceptions:

The package has changed from com.thinkminimo.step to org.scalatra.

The Step class has been renamed to ScalatraServlet.

All other Step* classes have been renamed to Scalatra*.

Related Projects

SSGI: Work in progress. Will provide an abstraction layer allowing a future version of Scalatra to run on web servers other than Servlet containers.

Bowler: A RESTful, multi-channel ready web framework in Scala with a functional flavour, built on top of Scalatra and Scalate.