Démarrer un projet avec RESTX

Un framework Java REST léger.

Préambule

Cet article a été rédigé après avoir reçu une demande d'aide de la part d'un ami pour mettre en place un projet Java utilisant RESTX, un framework Java REST léger, rapide et riche en fonctionnalités. Vous trouverez plus d'informations à son sujet sur le site officiel.

Installer le shell RESTX

Le shell RESTX s'installe en trois étapes. Cette installation permet ensuite d'installer et d'utiliser différents plugins. Il est nécessaire d'ouvrir un terminal puis d'exécuter trois instructions. Ces trois commandes permettent respectivement de :

créer un répertoire qui va accueillir le shell RESTX ;
télécharger le shell RESTX et décompresser l'archive dans le répertoire ;
créer un lien symbolique pour pouvoir l'exécuter n'importe où à la ligne de commande.

mkdir ~/.restx
curl --progress-bar --fail "http://repo1.maven.org/maven2/io/restx/restx-package/0.34.1/restx-package-0.34.1.tar.gz" | tar -xzf - -C ~/.restx
sudo ln -s ~/.restx/restx /usr/local/bin/restx

Installer le plugin restx-core-shell

Une fois notre shell installé, nous devons installer le plugin core du shell RESTX. Celui-ci nous permettra de créer nos applications. Pour y parvenir, lançons le shell RESTX à l'aide de la commande restx, peu importe le répertoire dans lequel nous nous trouvons.

nhumblot@debian:~$ restx
===============================================================================
== WELCOME TO RESTX SHELL - 0.34.1 - type `help` for help on available commands
===============================================================================
restx>

Pour installer un plugin, utilisons la commande shell install qui va nous lister les plugins disponibles :

restx> shell install
:: loading settings :: url = jar:file:/home/nhumblot/.restx/lib/restx-shell-0.34.1.jar!/restx/shell/ivysettings.xml
looking for plugins...
found 3 available plugins
 [  1] io.restx:restx-core-shell:0.34.1
        core commands: generate new app, ...
 [  2] io.restx:restx-build-shell:0.34.1
        build commands: generate pom, ivy, ...
 [  3] io.restx:restx-specs-shell:0.34.1
        specs commands: run a specs server, ...
Which plugin would you like to install (eg '1 3 5')?
You can also provide a plugin id in the form ::
 plugin to install:

Comme indiqué, le plugin restx-core-shell permet la génération de nouvelles applications, entrons 1 dans le terminal et validons. Le programme va installer une série de dépendances puis redémarrer le shell RESTX. Nous pouvons fermer le shell RESTX en réalisant la combinaison de touches ctrl + C.

Créer un projet RESTX

Nous avons désormais tous les outils pour générer notre première application RESTX. Dans le terminal, il nous faut nous placer dans le répertoire parent de notre futur projet. Dans cet exemple, il s'agit de ~/dev/wkspace.

nhumblot@debian:~$ cd dev/wkspace/
nhumblot@debian:~/dev/wkspace$ restx
===============================================================================
== WELCOME TO RESTX SHELL - 0.34.1 - type `help` for help on available commands
===============================================================================
restx>

L'installation du plugin restx-core-shell nous permet de générer une nouvelle application à l'aide de la commande app new. RESTX va alors nous poser une série de questions pour générer notre application.

restx> app new
Welcome to RESTX APP bootstrap!
This command will ask you a few questions to generate your brand new RESTX app.
For any question you can get help by answering '??' (without the quotes).

App name?

Nous choisissons de la nommer MyFirstRestxApp.

App name? MyFirstRestxApp
target directory [myfirstrestxapp]?

RESTX nous demande ensuite le nom du répertoire que nous souhaitons créer pour le projet. Pour plus de lisibilité, nous utilisons une notation my-first-restx-app. En cas d'appuit sur la touche entrée sans saisie, RESTX prendra la valeur située entre les crochets (ici myfirstrestxapp).

target directory [myfirstrestxapp]? my-first-restx-app
group id [myfirstrestxapp]?

RESTX demande ensuite le nom du group id du projet. On utilise fr.nicolashumblot.

group id [myfirstrestxapp]? fr.nicolashumblot
artifact id [myfirstrestxapp]?

RESTX demande ensuite le nom de l'artifact id du projet. On utilise la même notation my-first-restx-app que pour le répertoire.

artifact id [myfirstrestxapp]? my-first-restx-app
main package [my.first.restx.app]?

RESTX demande ensuite le nom du package principal Java. On prend un très original fr.nicolashumblot.myfirstrestxapp.

main package [my.first.restx.app]? fr.nicolashumblot.myfirstrestxapp
version [0.1-SNAPSHOT]?

RESTX demande ensuite le numéro de version, on prend le choix par défaut 0.1-SNAPSHOT en appuyant directement sur la touche entrée.

version [0.1-SNAPSHOT]? 
generate module descriptor (ivy/pom/none/all) [all]?

Nous voici ensuite devant le choix du descripteur de module, nous souhaitons générer un pom.xml.

generate module descriptor (ivy/pom/none/all) [all]? pom
java version [1.7]?

RESTX nous demande ensuite la version de Java à utiliser. RESTX nécessite au moins Java 1.7 pour pouvoir fonctionner. Nous sélectionnons ici la version 1.7 proposée car il s'agit de la version Java standard de la distribution Debian stable mais il est tout à fait possible d'utiliser Java 1.8.

java version [1.7]? 
restx version [0.34.1]?

Le shell demande la version de RESTX à utiliser, la version 0.34.1 est la version recommandée.

restx version [0.34.1]? 
signature key (to sign cookies) [my-first-restx-app -6555598190121822122 MyFirstRestxApp 2b7a2080-1821-4c3d-8de6-b5a4b8f512e8]?

RESTX demande ensuite de déterminer la signature des cookies à utiliser. Nous laissons là aussi le choix par défaut et appuyons sur entrée directement. Par mesure de sécurité, il vous est conseillé de ne pas divulguer les signatures de vos applications.

signature key (to sign cookies) [my-first-restx-app -6555598190121822122 MyFirstRestxApp 2b7a2080-1821-4c3d-8de6-b5a4b8f512e8]? 
admin password (to authenticate on restx console) [417]?

RESTX nous demande ensuite le mot de passe par défaut du compte administrateur permettant de se connecter à la console RESTX. Nous saisissons un mot de passe admin. Il est toutefois possible de le modifier par la suite, voir de désactiver ce compte une fois en exploitation.

admin password (to authenticate on restx console) [417]? admin
default port [8080]?

RESTX nous demande ensuite le port utilisé par l'application. À moins que le port 8080 proposé par défaut ne soit déjà utilisé, nous le choisissons.

default port [8080]? 
base API path [/api]?

RESTX nous demande la base de l'uri utilisée pour effectuer les appels REST, nous laissons le choix par défaut, nos urls commenceront par http://localhost:8080/api.

base API path [/api]? 
generate hello resource example [Y/n]?

RESTX nous propose de générer une ressource rest en guise d'exemple, nous acceptons en entrant Y ou en appuyant directement sur la touche entrée.

generate hello resource example [Y/n]? Y
include stats module and share anonymous stats on your app [Y/n]?

RESTX nous propose par défaut d'envoyer des statistiques anonymes pour obtenir un retour d'information sur le produit. Il est possible de désactiver cette commuication en saisissant n.

include stats module and share anonymous stats on your app [Y/n]? Y
do you want to use srv/ui layout [y/N]?

RESTX propose de mettre en place une sous-structure de deux modules, un module srv qui contiendra le code Java du serveur. Et un module ui pour contenir le code client. Nous choisissons d'utiliser cette architecture en sélectionnant Y.

do you want to use srv/ui layout [y/N]?Y
How do you want to bootstrap your UI (yo/restx/none) [restx]?

Restx nous permet de gérer l'amorçage de la partie cliente, on le laisse faire et on valide le choix par défaut.

How do you want to bootstrap your UI (yo/restx/none) [restx]?
Select the template you want to use:
 [ 1] HTML5 Boilerplate
      Use this if you want a very basic HTML5 bootstrap, with no additional tool required.
 [ 2] Angular, Twitter Bootstrap
      Use this if you want a more convenient bootstrap, with no additional tool required.
 [ 3] Angular, Twitter Bootstrap. Use grunt for building and bower to manage dependencies.
      Use this if you want a convenient bootstrap using the very popular frontend tools.
      You will need:
         - nodejs: http://nodejs.org/download/
         - grunt:  http://gruntjs.com/getting-started
         - bower:  http://bower.io/

 Which template do you want [1]?

RESTX nous propose trois types de génération du code de la partie cliente. Nous sélectionnons la troisième option.

 Which template do you want [1]? 3
scaffolding app to `/home/nhumblot/dev/wkspace/my-first-restx-app` ...
scaffolding ui with restx in `/home/nhumblot/dev/wkspace/my-first-restx-app/ui` ...
downloading UI template
downloading [...]/github.com/restx/angular-bootstrap-grunt-bower/archive/restx.zip
[======================================================================] 100%
scaffolding srv with restx in `/home/nhumblot/dev/wkspace/my-first-restx-app/srv` ...
generating pom.xml ...
generating hello resource ...
Congratulations! - Your app is now ready in /home/nhumblot/dev/wkspace/my-first-restx-app

Your app has 2 modules: ui and srv
In srv, you can:
  - open the module in your IDE by importing the Maven pom, and run the 
       `fr.nicolashumblot.myfirstrestxapp.AppServer` class to launch
  - run it from restx shell, using:
      deps install
              to install its dependencies
      app run
              to run it

In ui you can:
  - open and edit your front end source files with your favorite editor
  - install local grunt with
      npm install
  - install app frontend dependencies listed in bower.json with
      bower install
  - run development server with:
      grunt server

At root level you can:
  - build a production ready war using Maven (Linux/MacOS only):
      mvn package
Enjoy!
Do you want to install its deps and run it now? [y/N]

Pour finir, RESTX nous propose de télécharger toutes les dépendances. Nous refusons.

Do you want to install its deps and run it now? [y/N]N
my-first-restx-app>

Le processus de création du projet est terminé, nous pouvons quitter le shell RESTX en appuyat sur ctrl + C. Notre répertoire est créé et contient le code source de notre projet.

my-first-restx-app> 
nhumblot@debian:~/dev/wkspace$ ls
my-first-restx-app