Nimble Osgi

a workshop for SPA conference 2013 - London

The project is a simple example of a Rest-Api backend to serve a hypothetical conference.
On top of serving the list of talks, the api allows for users to register and define their own favorite talks list (schedule).

GET           /conferenceName/talks                  <= list of all talks
GET           /conferenceName/talk/talkId            <= detail of a single talk
POST          /conferenceName/schedule/              <= create user, redirect on userId/talks
PUT/DELETE    /conferenceName/schedule/userId/talkId      <= add/delete a talk to the user schedule
GET           /conferenceName/schedule/userId/talks       <= details of user and his schedule








Setup instructions
-----

Download and configure Maven 3.x

Download Groovy 2.x (tested with 2.1.4)
http://groovy.codehaus.org/Download

(optional) configure your ide for Groovy (plugin intellij/eclipse)

Download karaf 3.0.0-RC1
http://karaf.apache.org/index/community/download.html

unzip in a dir and launch it:
bin/karaf


From Karaf console type these 3 commands:

install -s mvn:org.codehaus.groovy/groovy-all
feature:install http
config:property-set -p org.ops4j.pax.web org.osgi.service.http.port 8080

We just installed groovy bundle, installed http support (pax-web) feature and configured jetty port (httpserver)

At this point it should show a jetty 404 page on localhost:8080 with a small "Powered by Jetty://" at the bottom.




Download (or clone) example code from github
https://github.com/uberto/nimble-osgi

Check execution permission:
chmod a+x gradlew

(optional) to generate IntelliJ project
./gradlew idea
or Eclipse project
./gradlew eclipse

to compile from command line (in the main dir)
./gradlew build install


to install bundles in karaf, from karaf console
install -s mvn:com.gama-soft.osgi/interfaces/1.0.0-SNAPSHOT
install -s mvn:com.gama-soft.osgi/domain/1.0.0-SNAPSHOT
install -s mvn:com.gama-soft.osgi/frontend/1.0.0-SNAPSHOT
install -s mvn:com.gama-soft.osgi/backend/1.0.0-SNAPSHOT


then, on karaf console
list

should return all 4 bundles as active with their bundleId


install -s is a shortcut for
install BUNDLE
start BUNDLE-ID
If bundle cannot start, no need to reinstall it, just try to start it again



At this point everything should work and (for example)
localhost:8080/conference/talks

Should return a list of talks
You can verify PUT/POST/DELETE calls with curl from command line or a browser plugin like Postman for Chrome



to autoupdate bundles
bundle:watch <bundleId> <bundleId>
(was dev:watch in karaf 2.x)


to compile and install (in maven) only a module, from the module dir
../gradlew install



------
Rest calls examples:


curl http://localhost:8080/conference/talks

curl http://localhost:8080/conference/talk/<talkId>

curl --data "userName=uberto&email=uberto@mymail.com" http://localhost:8080/conference/schedule/ -L

curl PUT http://localhost:8080/conference/schedule/<userId>

curl http://localhost:8080/conference/schedule/<userId>/talks

curl -X PUT http://localhost:8080/conference/schedule/<userId>/<talkId>

curl -X DELETE http://localhost:8080/conference/schedule/<userId>/<talkId>



------
Exercises:

1) Cache. Currently there talks are always retrieve from the backend, if backend bundle goes down list of talk doesn't work.
Since the list of talks are not supposed to change often, we can add a cache in the domain module.

2) Rooms. Currently there is no indication of room in the talks, add a room field in the talks, and a api to list only talks of a room.
/conference/talks/room/roomId

3) Logs. There are several "println" lines around the code, we can create a new bundle logging with a service for log and use it instead.


------
Gradle cheatsheet:

./gradlew tasks   <-- list of all available tasks
./gradlew build   <-- build project
./gradlew install <-- install bundle into maven rep
./gradlew test    <-- runs all unit tests



Karaf console cheatsheet:


help   <-- all possible commands

list   <-- list of all user bundle (threshold>50)
list -t 0   <-- list all bundles

start <bundleId>  <-- start a bundle (active)
stop  <bundleId>  <-- stop a bundle
install -s mvn:<maven reference>  <-- install and start a bundle

log:set      <-- set log level
log:display  <-- show log
log:display-exception   <-- show last exception
log:tail     <-- tail log


bundle:watch <bundleId> <bundleId> ...  <-- watch bundles from maven repo

shutdown       <-- shutdown karaf

All bundle are copied in:
data/cache/*