TAD

Agenda

Idea
Data Model
Toolbox
Architecture
1. Security
2. Rendering
3. Routes
Tests
Retrospective
Demo
Sources

Idea - A diary for GPS tracks

A web-based diary for GPS tracks and activities!

Basic Functionality

user registration and login
management of basic entities (create, modify, delete)
different views (e.g. a dashboard)
statistics for various aspects (e.g. overall distance per month)

Must have

upload of KML files
visualization of KML files

Nice to have

upload of pictures (e.g. pictures of items)
some sort of API
support different KML formats (or other GPS formats)

Data Model

Problems

How to deal with date and time?
How to deal with KML?
How to deal with images?
How to generate statistics?
How to deal with redundant and optional values?

Toolbox

Back End

Database (e.g. Play! InMemory for development and MySQL for production)

Java

Play! Framework

Form Helper

Templates

ebeans

JUnit

Front End

HTML

HTML5 Input Types

Forms

CSS

Foundation 4

JavaScript

jQuery

Google Maps API

Full Calendar

DataTables

Chart.js

Note: Some HTML5 input types are only available in Google Chrome!

Architecture

Security

two different controllers (a public one and a private one)
the public controller serves the login page, the registration page, the about page etc.
the private controller serves user specific content (e.g. the dashboard)

handling via sessions (managed by Play!)

public class Application extends Controller {
	...
}

@Security.Authenticated(Secured.class)
public class Tad extends Controller {
	...
}

only logged-in users can call methods of the private controller
every method in the private controller has access to the current user

User.find.where().eq("email", request().username()).findUnique();

user password is salted and hashed

byte bytes[] = new byte[20];
random.nextBytes(bytes);
String salt = bytes.toString();
final MessageDigest messageDigest = MessageDigest.getInstance("SHA-256");
messageDigest.update((password + salt).getBytes());
String hashAndSalted = new String(messageDigest.digest());

Architecture

ORM

ebeans for ORM

models are just POJOs in a package called "models"

@Entity
public class Activity extends Model {

	@Id
	public Long id;

	@NotNull
	public Date createdAt = new Date();
	
	...
	
	@ManyToMany
	public List items = new ArrayList<>();
	
	public static Finder find = new Finder(Long.class, Activity.class); 
}

models provide basic methods for manipulation

Activity.find.where()
		.eq("items.id", item.id)
		.eq("kind_id", id)
		...
		.findList();
		
activity.save();
activity.update();
activity.delete();

annotations for constraints and relations

@Required
@Email
@MinLength(value=2)
@Min(value = 0)
@Max(value = 300)
...

Architecture

Rendering

a mix of template rendering on the server and JSON rendering on the client
editing/creating of entities relies on template rendering and form helpers

a lot of in-build functionality from Play! to deal with forms

@(user: User, itemForm: Form[Item])

@tad("Edit item", user) {
    
	@helper.form(action = routes.Tad.putItem()) {
	
		...
	
		@helper.input(itemForm("name"), '_label -> "") { (id, name, value, args) =>
			<input type="text" name="@name" value="@value" id="@id" @toHtmlArgs(args)>
		} 
		
		...
		
		<button type="submit" class="secondary">Submit</button>
	}
}

requesting of entities relies on a JSON API (e.g. to show statistics)
potentially usable by other clients

easy to use existing JavaScript libraries like Charts.js

$.getJSON('@routes.Tad.getStatistics()' + '?' + kind + "&" + item + ..., function(data) {

	var ctx = $("#distanceChart").get(0).getContext("2d");
	
	if( bar ) {
		new Chart(ctx).Bar(data, options);
	}
	else {
		new Chart(ctx).Line(data, options);
	}

	...
});

Architecture

Routes

no REST-API since a mix of template rendering, forms and JSON is used
structured routes reflecting their meaning
similar handling of all entities (exceptions: the user and file handling)
naming convention /tad/<action>/<entity>?<parameters>
entities are activity, item, kind
actions are put, delete, return, etc.
depending on the action, JSON or an HTML page is returned
can only be executed by logged-in users!
special routes to serve images from the database

GET		/tad/view/activity			controllers.Tad.viewActivity()
GET		/tad/view/kind				controllers.Tad.viewKind()
GET		/tad/view/item				controllers.Tad.viewItem()

GET		/tad/return/activity			controllers.Tad.getActivities()
GET		/tad/return/kind			controllers.Tad.getKinds()
GET		/tad/return/item			controllers.Tad.getItems()

...

http://tad.mi.hdm-stuttgart.de/tad/return/activity
http://tad.mi.hdm-stuttgart.de/tad/delete/activity?id=1
http://tad.mi.hdm-stuttgart.de/tad/clone/activity?id=1

Tests

A mix of common unit tests and functional tests!

Unit tests

simple unit tests for algorithms
don't depend on Play!

only a small use of mock-data

@Test
public void getDistanceTest() {
	
	String kml8 = new KmlReader().read("mocks/test_8_km.kml");
	double distance8 = new KmlReader().getDistance(kml8);
	Assert.assertEquals(8, distance8, 1);
}

Functional tests

functional tests for higher (business) logic
depend on Play! (e.g. requests to a fake application)
depend on mock data

complicated to maintain

@Test
public void getStatistics() {
	
	running(fakeApplication(inMemoryDatabase()), new Runnable() {

		public void run() {
		
			new Mocker().mock();

			User tad = User.find.byId(new Long(2));
			FakeRequest request = Helpers
						.fakeRequest("GET", "/tad/return/statistics")
						.withSession("email", tad.email);
			Result result = Helpers.routeAndCall(request);
			
			assertThat(Helpers.status(result)).isEqualTo(Status.OK);
			...
			
			String content = Helpers.contentAsString(result);
			JsonNode json = Json.parse(content);
			assertThat(json.size()).isEqualTo(2);
			...
		}
	});
}

Retrospective

General

very fast development with Play! and ebeans
to many features to really complete the application

ORM with eBeans

+ Pro

I didn't wrote any SQL!
I developed on an in-memory database, but migrating to MySQL was barely more than changing the configuration!
I didn't miss any feature!

- Con

Instead of fighting with SQL I was fighting with ebeans
I still need to know the database structure and can't do all refactoring in pure Java

Activity.find.where() .eq("kind_id", id) .findList();

Development with Play!

+ Pro

Easy and fast!
Good integration of ebeans (ORM)!
Some really good tools (for testing, development and so on...)

- Con

Differences between versions are confusing
Using forms to edit only parts of entities is complicated

Demo

http://tad.mi.hdm-stuttgart.de

Sources

Play! Framework - http://www.playframework.com/
Charts.js - http://www.chartjs.org/
GeoXML3 - https://code.google.com/p/geoxml3/
Google Maps API - https://developers.google.com/maps/
JS Fullcalendar - http://arshaw.com/fullcalendar/
eBeans - http://www.avaje.org/ebean/introduction.html
DataTables - http://www.datatables.net/
jQuery - http://jquery.com/
HTML5 inputs - http://www.w3schools.com/html/html5_form_input_types.asp