Ayant eu l’occasion de me remettre sur Play! ces derniers jours, je ne peux m’empêcher de vous faire partager le plaisir que j’ai eu à l’utiliser en vous parlant d’un aspect sympathique de ce framework : la gestion des entités.

Si vous avez déjà eu l’occasion de vous faire la main sur Play!, vous ne devriez rien apprendre ici. Il s’agit surtout de donner envie à ceux qui hésitent à se lancer dans l’aventure Play!.

L’entité User

Commençons par écrire notre entité, que nous appellerons User. Voici le code :

package models;

import javax.persistence.Entity;
import play.db.jpa.Model;

@Entity
public class User extends Model {

    public String name;
    public String email;
    public boolean isAdmin;

    public User() {
    }

    public User(String name, String email, boolean isAdmin) {
        this.name = name;
        this.email = email;
        this.isAdmin = isAdmin;
    }

}

Nous notons déjà deux choses importantes :

• Les propriétés de notre entité sont publiques, et nous ne polluons plus notre classe avec des getters et setters (en attendant les property de Java 8 ).
• L’entité étend la classe play.db.jpa.Model. C’est ce point que nous allons voir en détail juste après.

La super-classe Model

Cette super-classe Model (et ses parents) vont nous simplifier grandement la vie, car elle nous évitera l’écriture d’un DAO. En effet, nous disposons, simplement grâce à notre entité, des principales méthodes de CRUD (Create, Read, Update, Delete):

• count() pour compter le nombre d’entités, en fournissant éventuellement des paramètres pour affiner la requête ;
• save() pour sauver notre entité ;

Voyons quelques exemples basiques avec un test unitaire :

public class UserTest extends UnitTest {

    @Before
    public void clean() {
        Fixtures.deleteDatabase();
    }

    @Test
    public void testAddition() {
        assertEquals(0, User.count());
        new User("romain linsolas", "romain@example.com", true).save();
        assertEquals(1, User.count());
    }

}

On notera que nous nettoyons la base de données en mémoire avant chaque test, afin de ne pas fausser nos résultats. De plus, notre classe JUnit étendant la classe play.test.UnitTest afin de profiter de l'environnement de Play! : création de la base de données en mémoire et la structure des tables, par exemple.

    private void insertUsers() {
        new User("romain linsolas", "admin@example.com", true).save();
        new User("romain linsolas", "romain@example.com", false).save();
        new User("bob l'eponge", "bob.leponge@example.com", false).save();
        new User("romain gary", "romain.gary@example.com", false).save();
    }

    @Test
    public void testFindAll() {
        insertUsers();
        assertEquals(4, User.findAll().size());
    }

    @Test
    public void testFindOneArg() {
        insertUsers();
        List<User> list = User.find("byName", "romain linsolas").fetch();
        assertEquals(2, list.size());
        assertEquals("romain linsolas", list.get(0).name);
    }

    @Test
    public void testFindTwoArgs() {
        insertUsers();
        List<User> list = User.find("byNameAndIsAdmin", "romain linsolas", true).fetch();
        assertEquals(1, list.size());
        assertTrue(list.get(0).isAdmin);
    }

Dans le code précédent, nous insérons quatre utilisateurs, et nous vérifions que la méthode findAll() nous retourne le nombre correct d'éléments. Nous faisons également une autre vérification, où nous recherchons tous les utilisateurs selon la valeur d'une propriété, ici name. Le dernier test permet de montrer une utilisation un peu plus poussée de la méthode find("…"), où nous cherchons tous les utilisateurs ayant un nom donné et dont l'attribut isAdmin vaut true.

Nous pouvons encore améliorer les choses en fournissant encore plus de détails sur la recherche, par exemple comme ceci :

    @Test
    public void testFindAndOrder() {
        insertUsers();
        List<User> list = User.find("name = ? order by email desc", "romain linsolas").fetch();
        assertEquals(2, list.size());
        assertFalse(list.get(0).isAdmin);
    }

où nous cherchons les utilisateurs selon un nom donné, puis en les triant selon l'adresse mail. Nous aurions pu encore corsé les choses en mettant en place des jointures avec d'autres entités...

Bien entendu, cette fonctionnalité ne marche pas seulement avec les méthodes de comptage ou de recherche, on pourra l'utiliser avec la méthode delete() :

    @Test
    public void testDelete() {
        insertUsers();
        User.delete("name = ?", "romain linsolas");
        assertEquals(2, User.count());
    }

Ce ne sont là que quelques possibilités, la classe Model offre d'autres fonctionnalités permettant les opérations de CRUD.

Conclusion

Au final, il n'y rien de révolutionnaire ici, mais que de temps gagné grâce à ces méthodes si utiles ! C'est sans doute ça la force première de Play! : nous offrir un retour rafraichissant à la simplicité. Et ça, c'est bon !

Pour aller plus loin :

• Site de Play!
• Tutoriel que j'ai traduit en français sur Play!
• Les entités JPA de Play!

Start Slide Show with PicLens Lite

J’avais promis d’aller plus loin dans l’étude de ce framework, j’ai en fin de compte traduit l’intégralité du tutoriel présenté sur le site officiel. A travers ce tutoriel, vous pourrez découvrir plus de fonctionnalités de Play, d’apprendre la façon dont il gère la persistence, comment créer des pages complexes, d’ajouter de l’authentification, etc.

Vous pouvez lire ma prose sur mon site developpez.com !

Etape #1: Installons Play !

Pour installer Play!, rien de plus simple : il suffit de télécharger le ZIP (ici), puis de le décompresser sur son disque. C’est tout ! Pensons à ajouter le répertoire ainsi décompressé dans notre variable d’environnement Windows PATH, histoire de pouvoir taper la commande play en ligne de commande…

Etape #2 : Démarrons !

Allons à la racine de notre répertoire d’installation de Play!, et tapons la commande suivante :

d:\developpement\play-1.0> play new helloworld

La commande nous demande alors quelle est le nom de notre nouvelle application :

d:\developpement\play-1.0>play new helloworld
~        _            _
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/
~
~ play! 1.0, http://www.playframework.org
~
~ The new application will be created in d:\developpement\play-1.0\helloworld
~ What is the application name? HelloWorld
~
~ OK, the application is created.
~ Start it with : play run heloworld
~ Have fun!
~

Notre première application est prête ! Eh oui ! Voyons les choses plus en détails… Regardons le contenu du répertoire ainsi créé :

app/
conf/
lib/
public/
test/

Ces répertoires ont les rôles les suivants :

• app : contient le code de l’application elle-même, à savoir les classes Java ainsi que les pages HTML.
• conf : les fichiers de configuration, en particulier application.conf qui contient les paramètres de notre application (par exemple le port du serveur, la configuration de la connection à la base de données, etc.), le fichier routes, qui définit les liens entre les URL et les pages web. Enfin, ce répertoire contient le fichier messages utilisé pour l’internationalisation du projet.
• lib : ce répertoire contient les librairies Java optionnelles.
• public : place contenant les ressources publiques, à savoir les images, les fichiers Javascript ou CSS.
• test : le répertoire permet de stocker les fichiers de tests, qu’il s’agisse de tests JUnit ou Selenium.

Et ça marche ? Voyons voir… Lançons la commande suivante :

d:\developpement\play-1.0\helloworld> play run

d:\developpement\play-1.0\helloworld>play run
~        _            _
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/
~
~ play! 1.0, http://www.playframework.org
~
~ Ctrl+C to stop
~
Listening for transport dt_socket at address: 8000
20:15:17,611 INFO  ~ Starting d:\developpement\play-1.0\helloworld
20:15:20,579 WARN  ~ You're running Play! in DEV mode
20:15:22,111 INFO  ~ Listening for HTTP on port 9000 (Waiting a first request to start) ...

Rendons-nous sur l’adresse http://localhost:9000 (9000 étant le port par défaut du serveur Play !) pour visualiser la page par défaut :

Mais quelle est la magie ? Le fichier conf/routes définit le routage des requêtes au sein de notre application. En particulier :

# Home page
GET     /                                       Application.index

Cette ligne indique que lorsqu’un utilisateur se connecte à la racine de notre application (ici http://localhost:9000/), sa requête sera prise en charge la Application.index. Ce contrôleur est visible dans app/controlles/Application.java :

package controllers;

import play.mvc.*;

public class Application extends Controller {

  public static void index() {
    render();
  }

}

La première chose à constater ici c’est que notre contrôleur étend la classe play.mvc.Controller. Cette classe nous propose – entre autres – la méthode render() qui est ici utilisée dans l’action index. Cette action est par ailleurs définie comme une méthode publique et statique. C’est la façon de définir une action dans Play !. Dans cet exemple, cette dernière ne fait qu’afficher le contenu d’un template se trouvant dans app/views/Application/index.html (c’est le template utilisé par défaut, car nous n’en avons pas défini dans notre classe Java) :

#{extends 'main.html' /}
#{set title:'Home' /}

#{welcome /}

Ce template est divisé en trois parties. Tout d’abord, on y voit que notre template étend le main.html :

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <title>#{get 'title' /}</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <link rel="stylesheet" type="text/css" media="screen" href="@{'/public/stylesheets/main.css'}" />
    <link rel="shortcut icon" type="image/png" href="@{'/public/images/favicon.png'}" />
  </head>
  <body>
    #{doLayout /}
  </body>
</html>

Dans ce fichier, on y voit le tag #{doLayout /} qui marque l’endroit où sera inseré le contenu du fichier Application/index.html.

Ensuite, on constate la façon dont un paramètre du template (le title) est passé à la page parente, via les #{set …/} et #{get …/}.

Enfin, la partie #{welcome /} génère le message d’accueil que nous avons pu voir précédemment.

Etape #3 :Utilisons Eclipse

Pour faciliter le développement de notre application, nous utilisons Eclipse. Pour ce faire, utilisons la commande suivante :

d:\developpement\play-1.0> play eclipsify helloworld

Play ! se charge alors de créer les fichiers nécessaires à Eclipse :

d:\developpement\play-1.0>play eclipsify helloworld
~        _            _
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/
~
~ play! 1.0, http://www.playframework.org
~
~ OK, the application is ready for eclipse
~ Use File/Import/General/Existing project to import d:\developpement\play-1.0\helloworld into eclipse
~
~ Use eclipsify again when you want to update eclipse configuration files.
~ However, it's often better to delete and re-import the project into your workspace since eclipse keeps dirty caches...
~

Les fichiers nécessaires à l’importation du projet dans Eclipse sont désormais créés. Il s’agit du .project, .classpath et .settings/.

Voilà, nous avons notre première petite application Play ! qui tourne. On a vu deux ou trois concepts intéressants, mais il y a encore plein de jolies choses à découvrir sur ce framework (si vous avez suivi le lien du Touilleur que je vous ai donné en début de post, vous en avez déjà vu quelques unes) ! Nous les aborderons dans un prochain post, très bientôt !

Bonus

Voici la liste des options proposées par la commande play :

C:\developpement\play-1.0\>play help
~        _            _
~  _ __ | | __ _ _  _| |
~ | '_ \| |/ _' | || |_|
~ |  __/|_|\____|\__ (_)
~ |_|            |__/
~
~ play! 1.0, http://www.playframework.org
~
~ For all commands, if the application is not specified, the current directory is used
~ Use 'play help cmd' to get more help on a specific command
~
~ Available commands are:
~ ~~~~~~~~~~~~~~~~~~~~~~~
~ auto-test      Automatically run all application tests
~ classpath      Display the computed classpath
~ clean          Delete temporary files (including the bytecode cache)
~ eclipsify      Create all eclipse configuration files
~ help           Display help on a specific command
~ id             Define the framework ID
~ modules        Display the computed modules list
~ netbeansify    Create all netbeans configuration files
~ new            Create a new application
~ out            Follow logs/system.out file
~ pid            Show the pid of a running application
~ precompile     Precompile all Java sources and templates to speed up application start
~ run            Run the application in the current shell
~ restart        Restart the running application
~ secret         Generate a new secret key
~ status         Display the status of the running application
~ start          Start the application in background
~ stop           Stop the running application
~ test           Run the application in test mode in the current shell
~ war            Export the application as a standalone WAR archive
~
~ Also refer to documentation at http://www.playframework.org/documentation
~

Start Slide Show with PicLens Lite