CAPSPOT

A Web Application for Capital Spotting

Vlad Manea1, Sebastian Codrin Dițu1

1 Faculty of Computer Science, Alexandru Ioan Cuza University

16 General Berthelot St., Iasi, Romania

{vlad.manea, sebastian.ditu}@info.uaic.ro

Abstract. The purpose of this paper is twofold. Firstly, we compare Play (rapid

development) Framework with other frameworks from the perspective of its

features. Secondly, we describe a sample application in Play. Our RESTful

application integrates the Google Maps [1], Geonames [2] and Picasa Web

services [3]. The aim of our application is to evaluate the precision with which

the user links a group of photos with their location.

Keywords: Play Framework, rapid development, REST, Web application, Web

services, Google, Geonames

Introduction

This paper is structured as follows.

In Section 1, we introduce the Play Framework as a resourceful rapid application

development framework. We briefly survey its main features in comparison with

other Java rapid development frameworks such as Wicket. We describe the steps a

developer must undertake to realize a simple demo application. We then provide our

reasons for selecting this framework in order to develop our application.

In Section 2, we present our Web sample application, with accent on the primary

use case, the REST service verbs and finally the web services integration. We then

present our conclusions and future work for our application.

1 The Play Framework

Play [4] is a rapid development MVC [5] framework tool implemented by Guillaume

Bort [6] and Zenexity [7]. Play allows developers to produce RESTful Web

applications [8] with Java. According to the official website, some of its features are:

On the fly reloading of sources. Suppose the developer has discovered a

bug in one of the sources. The developer is able to edit the sources on the

fly, and when the next request is issued, the code is interpreted and

compiled once again, such that there is no need to compile or deploy the

application after modifications are done to the sources. As developers, we

consider this as a major advantage.

Stateless model. Since applications developed with it are based on REST [9]

calls, The Play Framework aligns itself to the stateless property of the

underlying HTTP [10] protocol. Furthermore, the framework allows the

run of multiple instances on more than one server. Our application aligned

to this and solved requests by using the routed requests to controllers.

Templating system. Play has integrated the Groovy [11] template system for

the views. This system allows template inheritance. We realized one view

that used the template inheritance.

Full application stack. The framework allows the integration of third party

services, tools and protocols, such as the Hibernate [12] object relational

mapping tool. In our application, we used persistence on a local database

for one object by using this technology.

Pure Java. The framework allows all server code to be written in Java. It

also has scripts to create Netbeans [13] or Eclipse [14] projects. In our

case, we were able to integrate the simple Java toolkit for JSON [15] in our

application.

Error finder. The framework issues all errors to the output and to the line of

code where they appear. As (novice) developers in Play, we found this

feature useful.

Test framework. It has included JUnit [16] and Selenium [17] test

functionalities. By following the official sample application tutorial, we

developed unit (at the controller and model layers) and functional tests

(starting from the view layer throughout the full stack).

The competitor for this framework we are most accustomed with is Wicket [18].

We will briefly compare these two frameworks based on some standard features that

appear in most of the Java rapid web development frameworks:

MVC. Model View Controller pattern [2]. Both frameworks align to the

MVC pattern. We used this feature in our application to range our code

into low coupled packages and classes.

AJAX. Asynchronous Javascript And Xml [19]. Both frameworks allow

AJAX. In the quick overview movie of Play, an AJAX based view

example is shown. Since our client uses the REST Web services through

AJAX, we implemented the calls by using jQuery [20].

ORM. Object Relational Mapping [12]. Both frameworks have ORM. In the

case of Play, it uses the Hibernate tool to provide this feature. We used

this functionality in our application.

DB migration [21]. Due to the fact that ORM is provided by Hibernate, Play

supports this feature meanwhile Wicket does not.

Security. Both Play and Wicket offer security modules. Play uses a Security

Core Module while Wicket does not. Some other frameworks provide

specific security features (role based authentication and access, secrecy,

and other security properties

Templates. Template frameworks help developers to apply the DRY

principle [22] (Don’t Repeat Yourself) and build reusable components.

Both Play and Wicket provide Template Frameworks. We made use of

this feature by developing reusable components in our application. One

example is the main view that is inherited by the index view. Other

possible views may also inherit from the main view. Since our application

provided only one Controller that respond in the HTML format and all

others render their view in JSON format, our application does not have a

second view child.

Caching [23]. Both Play and Wicket provide this functionality. Our

application made use of this functionality in order to save user data that

did not have to be persistent for a long amount of time: the quiz Controller

generates a random unique token and stores it in the cache for a limited

amount of time. This is necessary in order to identify the correct answer,

the correct coordinate and capital city that need not to be accessible to the

client. A later call of the check controller with a token parameter yields to

a cache query in order to obtain the object retain with that token. If the

token exists (is found) the client receives from the server a response of

success. Before the response is sent, the token was deleted from cache.

Note that caching is used instead of sessions which are also available in

play but they were not necessarily for our project.

Form Validation. Both frameworks support validation. In the case of Play,

validation is made server side, in contrast Wicket it can be done in the

client. We used validation for the parameters that were sent to the

controllers. We used attributes such as required for our fields.

1.1 Hello World Tutorial

In order to create a demo Play Application one should do the following:

Step 1. Ensure that the computer has installed the latest Java version. In order to

function properly, Play requires Java 5 or later.

Step 2. Download and extract the framework archive located at its official website. It

is recommended that under the Windows operating system the path does not contain

spaces. In order to work easily from command line, Play must be added to working

path. If that it is not desired, in order to successfully interact with the framework

from command line, one should conversely navigate to the play framework route

before typing any play commands.

Step 3. Create a new play Project by typing play new <appname>, where

<appname> is the application name.

The play new <appname> command creates a new project template for

development in a new folder named <appname>. This folder has a folder structure

that aligns to the MVC pattern. An example application folder will contain:

The app directory; it contains the application core and it may also

contain other java classes or packages.

The conf directory; consists of the following files:

Application.conf, messages, routes.

Application.conf specifies configuration information for the

entire application.

The lib directory is the container for any Java library which a

developer want to use in his application, but not for any project in the

play framework. A lib folder also exists for play.

The public directory; contains all publicly available resources, such

as: image, scripts or styles.

The test directory; keeps all the application tests (written either with

JUnit or as Selenium tests).

Step 4. In order to view the new <appname> application one should navigate to the

<appname> directory and then type play run <appname>.

1.2 Reasons for selecting Play

In order to make a decision of developing a web application by using the Play

Framework, we have taken into account the following facts:

The Play Framework has all expected functionalities for a web

framework “out there in the market”. An important feature that we

considered very helpful, is the on the fly reloading of sources.

Throughout the development process, we may encounter various

problems whose solutions may be implemented in third party libraries.

Since the Play Framework aligned to this principle, we used in our

application the JSON Simple library [24], which was not the default

library for JSON objects management. Furthermore, we both had some

experience with the Java Framework. In this way, we knew how to

develop simple tasks and we focused on the relevant problems.

We took as an opportunity the learning of an entirely new rapid web

development framework for both of us.

2 Description of our Web application

In this section we will describe our web application focusing mainly on the primary

use case, the REST service verbs an last but not the least on the web services

integration.

The aim of our application is to evaluate the precision with which the user links a

group of photos with their location.

2.1 Primary use case

As the application name suggests the group of photos are not taken from any place on

the Globe, but from any existent country capital. Our application takes the form of a

playful quiz in which the final user receives a list of ten relevant photos from a

random capital, a Google Earth map, and an input in which he/she will type its

answer.

If the user doesn’t want to answer for the received photos, an option of try others is

available. The option provides him ten photos from another randomly chosen capital.

The user is fulfilling its task by typing the capital name of which he/she believes that

those pictures were taken.

After hitting the and I am sure! button, on the Google Earth Map is drawn line which

shows how accurate the user response was; the start and end point of the line are the

user attempt answer and the correct one.

2.2 The used REST service verbs

In order to create our own Capspot API [25], we integrated three third party Web

service suites: Geonames , Picasa Web Albums, and Google Earth.

Geonames. Geonames is a geographical database which provides various Web

services for querying and retrieving locations or places based on latitude, longitude,

weather, time zone or post codes. The Web services cover all countries. In order to

provide a random capital for each quiz, we invoked two Geonames Web services. The

algorithm for retrieving data about a random capital for each quiz is the following:

Algorithm RandomCapital

Input: none

Output: city

Begin

countries ← http.GET(countryInfoJSON)

index ← random(countries.size)

city ← http.GET(citiesJSON, countries{index})

End

According to the Geonames official website, the first Geonames Web service is

Country Info [28]. It receives a parameters the country (all is default) and the

language (English is default). The result contains country information, such as its

capital, population, area, bounding box of mainland. The output format (we know

of XML, which is the default, CSV and JSON, which we used) can be specified by

applying a suffix on the web service name. We invoked this Web service with no

country or language parameters, thus we stuck with their default values. An

example country request - response pair in JSON format about Romania and in

French is:

GET

http://api.geonames.org/countryInfoJSON?country=ro&lang

=fr&username=demo

{

"geonames":[

{

"bBoxWest":20.269972,

"countryName":"Roumanie",

"currencyCode":"RON",

"fipsCode":"RO",

"countryCode":"RO",

"isoNumeric":"642",

"capital":"Bucarest",

"continentName":"Europe",

"areaInSqKm":"237500.0",

"languages":"ro,hu,rom",

"bBoxEast":29.691055,

"isoAlpha3":"ROU",

"continent":"EU",

"bBoxNorth":48.266945,

"geonameId":798549,

"bBoxSouth":43.627304,

"population":"21959278"

}

]

}

On the Geonames website, the second Geonames Web service is called Cities and

Placenames [29], which is based on a bounding box. We use the bounding box of the

country we received from the first Web service. The result is a list with cities and

place names in the bounding box, ordered by their relevancy (capital and population).

Place names that are included in others are filtered out of the response. In our

application, we use the heuristic that in a bounding box the capital of the country will

appear in the first results. By knowing the capital name from the response from the

first Web service, we are now able to trace the exact capital among a list of place

names that are, according to Geonames, capitals of political entities. The output

format can be specified in a similar manner to the specifications of the first Web

service. An example country request - response pair in JSON format about the

bounding box given by coordinates [N=47,S=49,W=2,E=3] in French is (we

filtered out irrelevant data from the entries):

GET

http://api.geonames.org/citiesJSON?north=47&south=49&east

=2&west=3&maxRows=3&lang=fr&username=demo

{

"geonames":[

{

"fcodeName":"capital of a political entity",

"countrycode":"HU",

"name":"Budapest",

"lng":19.0399074554443,

"lat":47.4980099893041

},

{

"fcodeName":"capital of a political entity",

"countrycode":"AT",

"name":"Vienna",

"lng":16.3720750808716,

"lat":48.2084877601653

},

{

"fcodeName":"capital of a political entity",

"countrycode":"MN",

"name":"Ulaanbaatar",

"lng":106.883239746094,

"lat":47.9077125688913

}

]

}

Picasa Web Albums. The second Web service suite we used allows client

applications to upload, retrieve or update photos, albums that match particular criteria.

We used it in order to get 10 pictures for a certain capital as a hint for the quiz. We

obtained the photos by using the data feed API. A sample request for Iasi with a

maximum of 3 requested photos to be retrieved is

GET

https://picasaweb.google.com/data/feed/api/all?q=iasi&max

-results=3&alt=json

and its response is as follows:

{

"version":"1.0",

"encoding":"UTF-8",

"feed":{

"title":{

"$t":"Search Results",

"type":"text"

},

"entry":[

{

"media$group":{

"media$content":[

{

"url":"<removed for readability>",

"height":1083,

"width":1600,

"type":"image/jpeg",

"medium":"image"

}

],

"media$thumbnail":[

{

"url":"<removed for readability>",

"height":49,

"width":72

}

]

}

}

]

}

}

The third Web service suite we used is Google Earth. We used this service in order

to embed and use the Google map into our application. The main functionality that we

used is its reverse geo-location: given a place name, the exact geographic coordinates

are to be found by the service. The methods with their descriptions are:

Embed (in the initial stage) Map into Website

load() loads the plugin in order to instantiate Earth

init() creates the Earth instance

initCB(instance) configures the Earth instance

Position earth to a certain location (by geographic coordinates)

positionAt(latitude, longitude, range) moves the camera to that

point and range. The point is defined by its coordinates and the range is defined by a

zoom level.

Obtain the geographic coordinates for a location string

buttonClick() triggers the geocoder to perform its actions when the button is

clicked

geocoder.getLatLng(geocodeLocation, function(point)) returns

the point located at the provided latitude and longitude

Place a Mark on earth

createPlacemarkAt(latitude, longitude) creates a mark on Earth at

the coordinates.

2.2 Our Application architecture

The Capspot Application has the architecture provided by the Play Framework. We

first give an overview after we will focus on describing the main application

components separately. From a top view, our application encompasses:

The app directory, structured by the MVC pattern, contains the core:

from java bean entities to specific client implementation.

The conf directory consists of three files: the Application.conf,

messages and routes files. We modified Application.conf

with the database option of an in-memory database. In the routes

file, the application routes are specified as regular expressions. For

instance, we mapped the verb POST /check/{token}/{lat}/

{lng}/save to the application.save() controller method that

receives three parameters: a token, a latitude and a longitude.

The lib directory contains the Java toolkit for JSON [12] library.

The public directory contains the publicly available resources of our

application, such as: images, scripts and styles for the client application.

The test directory keeps all application tests, written in JUnit or Selenium.

By having aligned with the MVC pattern, the application core offers the integration

with the REST web services as previously described. Thus, in order to describe how

we performed the final integration with them, we will describe our application core:

Application Model

It consists of one (ORM) class: models/Result.java

ORM (object relational mapping) means that an instance of the class maps to

an entry in the corresponding table from the database. Hibernate provides

annotations for classes and fields to realize the mapping.

Application Controller

It consists of one class: controllers/Controller.java

There are four controller methods in this class, each mapped with a route.

Application View

It consists of the JSON outputs. On top of the view, a website with jQuery

[20] logic performs asynchronous requests.

2.4 Our controller methods

Each controller method returns data in JSON format.

quiz()

In this controller, we use the Cache Framework feature by saving in the application

cache a uniquely generated number and some relevant capital data which will be used

to verify the correctness of the user response, as in the algorithm:

Algorithm Quiz

Input: none

Output: JSON

Begin

capital(lat, lng, name) ← randomCapital.GET()

photos ← photos.GET(capital.name)

token ← randomTokenGenerator.GET()

Cache.SET(token, capital, time)

JSON ← quiz.BUILD(token, photos)

End

A common JSON response for a quiz request is:

{

"token":"2d3b75c2",

"relatedPhotos":[{"URL":"<removed for readability>"}],

"errors":[]

}

check(token, latitude, longitude)

This controller renders correctness or failure in JSON format. It has three parameters.

The check is performed by the following algorithm

Algorithm Check

Input: token, user.lat, user.lng

Output: JSON

Begin

errors ← Φ

capital ← Cache.GET(token)

If capital = Φ Then

errors ← errors U “invalid token”

End

Cache.SET(token, Φ)

JSON ← check.BUILD(capital.lat, capital.lng,

user.lat, user.lng, errors)

End

A common request – response pair of this service verb might be

POST

http://<srv>/check/2d3b75c2/12.03/34.1

{

"capitalName":"Willemstad",

"capitalLatitude":12.1083965959225,

"capitalLongitude":-68.9335441589355,

"yourGuessLatitude":12.03,

"yourGuessLongitude":34.1,

"errors":[]

}

save(token, latitude, longitude)

This controller calls the check controller and it saves the run in the database, i.e. it

saves by ORM the token, correct answer and user answer. Its response is similar to

the called controller. Its request is similar to the previous, but with the /save suffix.

share(token)

This controller shares the response an old check request generated by querying the

database via ORM for the token.

Fig. 1. Capspot application class diagram

Fig. 2. Capspot application sequence diagram

3 Conclusions and further development

In conclusion, we consider a good idea to use RAD tools and frameworks in the fast

development of Web applications. Furthermore, we consider a good decision of using

Play Framework in the development of our Capspot application.

Besides the Java experience (which was welcomed), the framework’s features have

provided us with great help in successfully rapidly finish our application. Our further

development directions include integration with social networks (like Twitter,

Facebook) and likewise with Scala [26], in order to get the benefits from both

object orientation programming and functional programming as well.

References

1. GeoNames, http://www.geonames.org/

http://www.geonames.org/export/web-services.html#countryInfo

http://www.geonames.org/export/JSON-webservices.html#citiesJSON

2. Picasa Web Albums Data API - Google Code,

http://code.google.com/intl/ro-RO/apis/picasaweb/overview.html

3. Google Earth API Reference - Google Earth API - Google Code,

http://code.google.com/intl/ro-RO/apis/earth/documentation/reference/

4. Play Framework,

http://www.playframework.org/

http://www.playframework.org/documentation/1.2.3/home

http://www.playframework.org/download

5. Reenskaug, T.: The Model View Controller (MVC) Its past and Present. University of

Oslo (2003),

http://folk.uio.no/trygver/2003/javazone-jaoo/MVC_pattern.pdf

6. Guillaume Bort, http://www.linkedin.com/pub/dir/Guillaume/Bort

7. Zenexity, http://www.zenexity.com/

8. Ramsey, B.: Designing RESTful Web Applications. benramsey.com (2007)

http://benramsey.com/media/talks/phpworks07-rest.pdf

9. Rodriguez, A.: RESTful Web services: The basics. developerWorks (2008),

https://www.ibm.com/developerworks/webservices/library/ws-restful/

10. Fielding, R., Getty, J.: RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1.The

Internet Society (1999),

http://www.ietf.org/rfc/rfc2616.txt

11. Groovy – A dynamic language for the Java Platform, http://groovy.codehaus.org/

12. Hibernate – Relational Persistence for Java and .NET, http://www.hibernate.org/

13. NetBeans IDE, http://netbeans.org/

14. Eclipse - The Eclipse Foundation open source community website,

http://www.eclipse.org/

15. JSON, http://www.json.org/

16. Jnit.org – Resources for Test Driven Development, http://www.junit.org/

17. SeleniumHQ – Web application testing system, http://seleniumhq.org/docs/

18. Apache Wicket, http://wicket.apache.org/

19. Garrett, J.: Ajax: A New Approach to Web Applications. adaptivepath.com (2005),

http://adaptivepath.com/ideas/ajax-new-approach-web-applications

20. jQuery – JavaScript Library, http://jquery.com/

21. Hoeven, V., Lohman, B., Verdegem, R.: Emulation for Digital Preservation in

Practice: The Results, pp. 123--132. The International Journal of Digital Curation 2.2

(2007)

22. Orthogonality and the DRY Principle, http://www.artima.com/intv/dry.html

23. Caching Tutorial for Web Authors and Webmasters,

http://www.mnot.net/cache_docs/

24. JSON.simple - A simple Java toolkit for JSON - Google Project Hosting,

http://code.google.com/p/json-simple/

25. PC Magazine: Definition of API. The Computer Language Company Inc.,

pcmag.com (1996),

http://www.pcmag.com/encyclopedia_term/0,2542,t=application+programming+inter

face&i=37856,00.asp#fbid=qfqxYatyoli

26. The Scala Programming Language, http://www.scala-lang.org/node/10780