Current [Play!] (http://www.playframework.com/) version is 2.2.1 (nov 2013)
What is this ?
A Play! app to serve JSon REST services without serving any web page. The app is configured for a MySQL db using JPA via Hibernate provider. We assume that a MySQL db is running on localhost in dev mode.
For what purpose ?
The main goal is to provide a full dev environment, a skeleton for a REST server, with some good practices for the most common problems encountered in that case.
I try to follow theses principles :
- [The 12 factors] (http://12factor.net/)
- [Heroku architecture advice] (https://devcenter.heroku.com/articles/architecting-apps)
- Service Oriented Architecture
What is done and you can read or pick ?
- [Play config for MySQL with JPA via Hibernate provider] (http://www.playframework.com/documentation/2.2.x/JavaJPA)
- [Play database evolution] (http://www.playframework.com/documentation/2.2.x/Evolutions)
- [Rest services crud demo] (http://www.restapitutorial.com/lessons/restfulresourcenaming.html)
- [Pojo validation via Play] (http://www.playframework.com/documentation/2.2.x/JavaForms)
- [Play testing] (http://www.playframework.com/documentation/2.2.x/JavaTest)
- [Play l18n] (http://www.playframework.com/documentation/2.2.x/JavaI18N)
- [Play dependencies management] (http://www.playframework.com/documentation/2.2.x/SBTDependencies)
- A home-made login system using [NIST recommendations] (http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf)
- [Play action composition example for controllers credentials] (http://www.playframework.com/documentation/2.2.1/JavaActionsComposition)
- [Dependency Injection] (http://en.wikipedia.org/wiki/Dependency_injection) with [Google Guice] (http://code.google.com/p/google-guice/)
- [CORS] (https://developer.mozilla.org/en-US/docs/HTTP/Access_control_CORS) support
- You need a MySQL working installation. (Just create a new user for that app, check config, then run the app or the
- You need to install Play! version 2.2.1+. (That config will not work with an inferior version due to framework last changes.)
Running the application locally and play with it
- Enter in your project root directory in the console.
- Run the app with
play runcommand. (
play "run 8080"to run it on the 8080 port)
- Go to http://localhost:9000/version with your favourite browser.
To manually run the app without a front-end, i use the [RESTClient plugin] (https://addons.mozilla.org/fr/firefox/addon/restclient/) for Firefox.
If you want install it, you can import some Rest requests from
In RESTClient menu, "Favorite requests" -> "Import favorite requests".
- Check database configuration in
conf/configure.shto set up shell before launching Play! console.
This project is set for IntelliJ by [mpeltonen sbt plugin] (https://github.com/mpeltonen/sbt-idea)
Open a play console then type
A valid IntelliJ project will be set up, at this point you can open project in IntelliJ.
Notices that each time you add a dependency in
build.sbt file you need to execute
gen-idea (no need to close IDEA).
- Tests can be run with the regular way through play console by typing
- Tests can be run manually with IntelliJ.
- Tests can be run manually with IntelliJ via the
run-tests-fullstackant task to generate a html report in
Tasks config are done on the top of
You will need to update properties value for db access and play directory.
See description of each tasks.
Version number management
We use [sbt-buildinfo plugin] (https://github.com/sbt/sbt-buildinfo).
Version number is set in
build.sbt in the Play! regular way.
Open a play console then type
reload to see changes.
We follow [SemVer] (http://semver.org/) convention.
- [heroku.com] (https://www.heroku.com/)
- We assume that you have installed the [Heroku Toolbelt] (https://toolbelt.heroku.com/).
- We assume that you have read the [related documentation] (https://devcenter.heroku.com/articles/play-support#play-2-2) on Heroku website.
- We assume that you know [how to run a Play application in production mode] (http://www.playframework.com/documentation/2.2.x/Production).
- I use [ClearDB] (https://addons.heroku.com/cleardb#ignite) and [SendGrid] (https://addons.heroku.com/sendgrid#starter) add-ons.
Related project files :
scripts/heroku-deploy-sample.sh(to set up the env)
Procfile(to configure the process (the dyno in heroku world) running the app)
system.properties(to run the app under 1.7 JRE)
Some useful tips :
- Once ClearDB is up, examine the
CLEARDB_DATABASE_URLenvironment variable to get the database name, username and password.
- Don't forget to examine the [Heroku dashboard] (https://dashboard.heroku.com/apps), each add-on have his own dashboard.
- [How to] (http://stackoverflow.com/questions/9822313/remote-connect-to-cleardb-heroku-database) connect to your MySQL db on Heroku with your SQL tools (like Workbench)
Some useful heroku shell commands (need to be in your source root directory) :
$ heroku createto create a new app. Name is auto-generated and can be changed in the dashboard settings panel.
$ heroku psto list the running dynos.
$ heroku configto display your app config.
$ git push heroku masterpush your current git code to heroku. Heroku app are built from source code.
$ heroku ps:scale web=1to run the app with only one dyno (free)
$ heroku logs > logs/heroku.logto get logs from heroku in your play logs dir locally.
Areas of improvements
- I would like to get comments on this, of any kind.
- I don't know how to run only unit tests without integration tests with Play! via Ant in a simple way.
- I don't know how to rollback the database after each integration test without deleting each record used manually.
- Transactions are functional but i have to work on [concurrency] (https://blogs.oracle.com/enterprisetechtips/entry/locking_and_concurrency_in_java).
- I need also to work on continuous integration.