As a bonus, Sonar Code Coverage will be enhanced with these tests.

Pre-requisites

Maven 3 is required because some of the below plugins have this requirement.
If you need to keep a Maven 2 build for your dev team, put all this configuration in a Maven profile dedicated to your Sonar build (ex: Profile integration).

Explanations

Here are the different plugins and configurations needed to succeed.

Cobertura dependency

<dependencies>
    <!-- needed to execute Integration tests instrumented with Cobertura -->
    <dependency>
        <groupId>net.sourceforge.cobertura</groupId>
        <artifactId>cobertura</artifactId>
        <version>1.9.4</version>
        <scope>test</scope>
    </dependency>
</dependencies>

This dependency is needed in order to instrument the classes with Cobertura.

Maven SoapUI plugin

The complete documentation for this plugin may be found here : Maven SoapUI plugin.

<plugin>
    <groupId>eviware</groupId>
    <artifactId>maven-soapui-plugin</artifactId>
    <version>4.5.1</version>
    <configuration>
        <junitReport>true</junitReport>
        <exportAll>true</exportAll>
        <projectFile>${project.build.directory}/test-classes/my-soapui-project.xml</projectFile>
        <outputFolder>${project.build.directory}/surefire-reports</outputFolder>
        <testSuite>myIntegrationTests</testSuite>
        <testFailIgnore>true</testFailIgnore>
    </configuration>
    <executions>
        <execution>
            <id>wsn-server-test</id>
            <phase>integration-test</phase>
            <goals>
                <goal>test</goal>
            </goals>
        </execution>
    </executions>
</plugin>

This plugin will execute a SoapUI test suite contained in a SoapUI project XML file.
If you want to filter (using Maven filtering) this file, use the projectFile property to load the project’s file from the target directory :

<projectFile>${project.build.directory}/test-classes/my-soapui-project.xml</projectFile>

Property testFailIgnore must be set to true in order to prevent a failing test to break the build.

In this example, the plugin will execute the myIntegrationTests test suite from the project file my-soapui-project.xml.

The plugin test execution must be bound to the integration-test phase.

Cobertura IT Maven plugin

The cobertura-it-maven-plugin is a fork of codehaus cobertura-maven-plugin which enable the so long waited integration test coverage feature MCOBERTURA-86.

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>cobertura-it-maven-plugin</artifactId>
    <version>2.5</version>
    <configuration>
        <formats>
            <format>xml</format>
            <format>html</format>
        </formats>
        <check>
            <haltOnFailure>false</haltOnFailure>
        </check>
    </configuration>
    <executions>
        <execution>
            <id>cobertura-clean</id>
            <phase>clean</phase>
            <goals>
                <goal>clean</goal>
            </goals>
        </execution>
        <execution>
            <id>cobertura-instrument</id>
            <phase>process-classes</phase>
            <goals>
                <goal>instrument</goal>
            </goals>
        </execution>
        <execution>
            <id>cobertura-report</id>
            <phase>pre-site</phase>
            <goals>
                <goal>report-only</goal>
            </goals>
        </execution>
    </executions>
</plugin>

The XML output report is mandatory for the Sonar analysis. The HTML one may be used by the development team but it’s optional.

Do not forget to set haltOnFailure in order to prevent a test failure to stop the build.

3 executions must be defined :

• Goal clean must be called to clear instrumenting in the clean Maven phase.
• Goal instrument must be executed in the process-classes in order to instrument the classes.
• Goal report-only must be executed in the pre-site phase.

Now, let’s configure a Jetty server to start just before integration test execution and stop just after them.

Jetty Maven plugin

Beware : this plugin must not be mixed with the maven-jetty-plugin.
This one is the new one, respecting the Maven convetion naming.

The complete documentation may be found here : jetty-maven-plugin.

<plugin>
    <groupId>org.mortbay.jetty</groupId>
    <artifactId>jetty-maven-plugin</artifactId>
    <version>8.1.2.v20120308</version>
    <configuration>
        <stopPort>18043</stopPort>
        <stopKey>STOP</stopKey>
        <connectors>
            <connector implementation="org.eclipse.jetty.server.nio.SelectChannelConnector">
                <port>18042</port>
            </connector>
        </connectors>
    </configuration>
    <executions>
        <execution>
            <id>start-jetty</id>
            <phase>pre-integration-test</phase>
            <goals>
                <goal>start</goal>
            </goals>
            <configuration>
                <!-- Needed in order to to code coverage on SoapUI tests -->
                <classesDirectory>${project.build.directory}/generated-classes/cobertura</classesDirectory>
                <useTestScope>true</useTestScope>
                <scanIntervalSeconds>0</scanIntervalSeconds>
                <daemon>true</daemon>
                <contextPath>/myIntegrationTestsContext</contextPath>
            </configuration>
        </execution>
        <execution>
            <id>stop-jetty</id>
            <phase>post-integration-test</phase>
            <goals>
                <goal>stop</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Attribute classesDirectory must be specified to use the instrumented classes.

The goal start is a new one introduced by the new version of the Jetty plugin. It starts a Jetty server without first executing the build up to “test-compile” phase.
Do not forget to set the attribute true in order to force Jetty to execute only while Maven is running, instead of running indefinitely.

Maven phases pre-integration-test and post-integration-test are used to start and stop the Jetty server.

Reporting

The reporting phase is mandatory to generate the Cobertura report. A bug prevents the Cobertura report to be generated in the integration-test phase.

<reporting>
    <plugins>
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>cobertura-it-maven-plugin</artifactId>
            <version>2.5</version>
            <configuration>
                <formats>
                    <format>html</format>
                    <format>xml</format>
                </formats>
            </configuration>
            <reportSets>
                <reportSet>
                    <reports>
                        <report>report-only</report>
                    </reports>
                </reportSet>
            </reportSets>
        </plugin>
    </plugins>
</reporting>

Sonar configuration

In order to make Sonar reuse reports, configure these properties in your Maven build :

<sonar.dynamicAnalysis>reuseReports</sonar.dynamicAnalysis>
<sonar.surefire.reportsPath>${project.build.directory}/surefire-reports</sonar.surefire.reportsPath>
<sonar.cobertura.reportPath>${project.build.directory}/site/cobertura/coverage.xml</sonar.cobertura.reportPath>

Jenkins configuration

A quite special configuration must be done in your Jenkins build : a Post Step must be added.
This step must launch mvn site command in order to produce the Cobertura report.

Complete code

<dependencies>
    <!-- needed to execute Integration tests instrumented with Cobertura -->
    <dependency>
        <groupId>net.sourceforge.cobertura</groupId>
        <artifactId>cobertura</artifactId>
        <version>1.9.4</version>
        <scope>test</scope>
    </dependency>
</dependencies>
<build>
    <plugins>
        <plugin>
            <groupId>eviware</groupId>
            <artifactId>maven-soapui-plugin</artifactId>
            <version>4.5.1</version>
            <configuration>
                <junitReport>true</junitReport>
                <exportAll>true</exportAll>
                <projectFile>${project.build.directory}/test-classes/my-soapui-project.xml</projectFile>
                <outputFolder>${project.build.directory}/surefire-reports</outputFolder>
                <testSuite>myIntegrationTests</testSuite>
                <testFailIgnore>true</testFailIgnore>
            </configuration>
            <executions>
                <execution>
                    <id>wsn-server-test</id>
                    <phase>integration-test</phase>
                    <goals>
                        <goal>test</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>cobertura-it-maven-plugin</artifactId>
            <version>2.5</version>
            <configuration>
                <formats>
                    <format>xml</format>
                    <format>html</format>
                </formats>
                <check>
                    <haltOnFailure>false</haltOnFailure>
                </check>
            </configuration>
            <executions>
                <execution>
                    <id>cobertura-clean</id>
                    <phase>clean</phase>
                    <goals>
                        <goal>clean</goal>
                    </goals>
                </execution>
                <execution>
                    <id>cobertura-instrument</id>
                    <phase>process-classes</phase>
                    <goals>
                        <goal>instrument</goal>
                    </goals>
                </execution>
                <execution>
                    <id>cobertura-report</id>
                    <phase>pre-site</phase>
                    <goals>
                        <goal>report-only</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>org.mortbay.jetty</groupId>
            <artifactId>jetty-maven-plugin</artifactId>
            <version>8.1.2.v20120308</version>
            <configuration>
                <stopPort>18043</stopPort>
                <stopKey>STOP</stopKey>
                <connectors>
                    <connector implementation="org.eclipse.jetty.server.nio.SelectChannelConnector">
                        <port>18042</port>
                    </connector>
                </connectors>
            </configuration>
            <executions>
                <execution>
                    <id>start-jetty</id>
                    <phase>pre-integration-test</phase>
                    <goals>
                        <goal>start</goal>
                    </goals>
                    <configuration>
                        <!-- Needed in order to to code coverage on SoapUI tests -->
                        <classesDirectory>${project.build.directory}/generated-classes/cobertura</classesDirectory>
                        <useTestScope>true</useTestScope>
                        <scanIntervalSeconds>0</scanIntervalSeconds>
                        <daemon>true</daemon>
                        <contextPath>/myIntegrationTestsContext</contextPath>
                    </configuration>
                </execution>
                <execution>
                    <id>stop-jetty</id>
                    <phase>post-integration-test</phase>
                    <goals>
                        <goal>stop</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
<reporting>
    <plugins>
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>cobertura-it-maven-plugin</artifactId>
            <version>2.5</version>
            <configuration>
                <formats>
                    <format>html</format>
                    <format>xml</format>
                </formats>
            </configuration>
            <reportSets>
                <reportSet>
                    <reports>
                        <report>report-only</report>
                    </reports>
                </reportSet>
            </reportSets>
        </plugin>
    </plugins>
</reporting>

Complement

Here is another article dealing with Integration Tests in Maven builds : Let’s Turn Integration Tests with Maven to a First-Class Citizen.

[INFO] Running the tests.
[INFO] A fatal exception occurred while running tests.  Possible causes include invalid test runner parameters and stack overflows.
[INFO] 	Gallio.Model.ModelException: An exception occurred while invoking a test driver. ---> Gallio.Model.ModelException: Gallio.Model.ModelException: Could not load test assembly from 'X:\XXXXX\MyDLL.dll'. ---> System.BadImageFormatException: Could not load file or assembly 'file:///X:\XXXXX\MyDLL.dll' or one of its dependencies. An attempt was made to load a program with an incorrect format.
[INFO] 	   at System.Reflection.RuntimeAssembly._nLoad(AssemblyName fileName, String codeBase, Evidence assemblySecurity, RuntimeAssembly locationHint, StackCrawlMark& stackMark, Boolean throwOnFileNotFound, Boolean forIntrospection, Boolean suppressSecurityChecks)
[INFO] 	   at System.Reflection.RuntimeAssembly.nLoad(AssemblyName fileName, String codeBase, Evidence assemblySecurity, RuntimeAssembly locationHint, StackCrawlMark& stackMark, Boolean throwOnFileNotFound, Boolean forIntrospection, Boolean suppressSecurityChecks)
[INFO] 	   at System.Reflection.RuntimeAssembly.InternalLoadAssemblyName(AssemblyName assemblyRef, Evidence assemblySecurity, StackCrawlMark& stackMark, Boolean forIntrospection, Boolean suppressSecurityChecks)
[INFO] 	   at System.Reflection.RuntimeAssembly.InternalLoadFrom(String assemblyFile, Evidence securityEvidence, Byte[] hashValue, AssemblyHashAlgorithm hashAlgorithm, Boolean forIntrospection, Boolean suppressSecurityChecks, StackCrawlMark& stackMark)
[INFO] 	   at System.Reflection.Assembly.LoadFrom(String assemblyFile)
[INFO] 	   at Gallio.Runtime.Loader.DefaultAssemblyLoader.LoadAssemblyFrom(String assemblyFile) in c:\Server\Projects\MbUnit v3.3\Work\src\Gallio\Gallio\Runtime\Loader\DefaultAssemblyLoader.cs:line 86
[INFO] 	   at Gallio.Model.DotNetTestDriver.ExploreOrRunTask.LoadAssembly(String assemblyPath) in c:\Server\Projects\MbUnit v3.3\Work\src\Gallio\Gallio\Model\DotNetTestDriver.cs:line 330
[INFO] 	   --- End of inner exception stack trace ---
[INFO] 	   at Gallio.Model.DotNetTestDriver.ExploreOrRunTask.LoadAssembly(String assemblyPath) in c:\Server\Projects\MbUnit v3.3\Work\src\Gallio\Gallio\Model\DotNetTestDriver.cs:line 337

After many attempts, I found the error : the build was being executed on a 64bits machine while the build was a 32bits.
The solution is to change the sonar.gallio.runner parameter :

 
    <sonar.gallio.runner>IsolatedProcess</sonar.gallio.runner>
 

Que la Force soit avec nous

C’est là que Joda Time intervient :

• Joda Time est facile à utiliser grâce à des méthodes simples : par exemple getYear() ou getDayOfWeek().
• L’implémentation des TimeZones se base sur la base de données publique. Les releases de Joda Time incorporent les mises à jour de cette base de données.
• 8 systèmes de calendrier.
• L’interopérabilité avec le JDK est simplifiée : la librairie utilise en interne la milliseconde, ce qui la rend facile interopérable avec les classes du JDK.
• Des calculs simplifiés : il est très facile de rajouter ou enlever une durée à une date.
• Joda Time est open source : sous licence.

La documentation est très complète et la Javadoc complète le reste de l’API.

Persistence de DateTime

Intéressons nous à la persistence d’une des classes de Joda Time : org.joda.time.DateTime.

DateTime sert à représenter une date avec une précision de la milliseconde. Il s’agit d’une des classes les plus utilisées dans la librairie Joda Time. De plus, elle est thread-safe et immutable.

Le projet Usertype for Hibernate Parent offre un moyen de persister en base de données via Hibernate (version 4.0 minimum) une instance de DateTime dans une colonne de type Date. Il s’agit du seul moyen de persister des objets Joda Time pour les versions supérieures à 2.x.

Du côté de Maven

Il faut tout d’abord ajouter les dépendances Joda Time et UserType à votre pom Maven :

<dependency>
    <groupId>joda-time</groupId>
    <artifactId>joda-time</artifactId>
    <version>2.1</version>
</dependency>
<dependency>
    <groupId>org.jadira.usertype</groupId>
    <artifactId>usertype.core</artifactId>
    <version>3.0.0.CR1</version>
</dependency>

Il suffit maintenant d’utiliser la classe DateTime comme attribut d’une entité Hibernate et de l’annoter avec UserType pour pouvoir la persister :

    ...
    @Column
    @Temporal(TemporalType.DATETIME)
    @Type(type="org.jadira.usertype.dateandtime.joda.PersistentDateTime")
    public DateTime date;
    ...

Du côté de Play! Framework 1.x

Attention : depuis la version 1.2.4 du framework Play!, Joda Time a été upgradé en version 2.x. Cet article traite de la seule façon de persister des objets Joda Time pour la librairie > 2.x.

Pour une application utilisant le framework Play! (> 1.2.4), il suffit de déclarer les dépendances dans son fichier dependencies.yml :

require:
    ...
    - org.jadira.usertype -> usertype.core 3.0.0.CR1:
        exclude:
          org.joda -> joda-money
    ...

Le code Java de l’entité reste inchangé :

    ...
    @Column
    @Temporal(TemporalType.DATETIME)
    @Type(type="org.jadira.usertype.dateandtime.joda.PersistentDateTime")
    public DateTime date;
    ...

Adaptez votre @Temporal en fonction de la précision souhaitée pour la colonne dans votre base de données.

Le code mort tu supprimeras !

Vous pouvez maintenant supprimer toutes vos classes DateUtils et supprimer le code mort qui servait à faire des conversions de dates à tout va !

Rappelez-vous : du code mort est du code supprimé !

Parmi eux, on retrouve très souvent les transferts de fichiers, habituellement rencontrés sur le protocole FTP. Or le protocole FTP n’est absolument pas sécurisé (données et mots de passe qui transitent en clair sur le réseau).

Le choix opérationnel se porte très souvent sur SFTP.
SFTP (SSH File Transfer Protocol), n’est pas FTP exécuté sur SSH, mais plutôt un nouveau protocole conçu dès le départ par le groupe de travail IETF SECSH.
STFP est un protocole de communication fonctionnant au-dessus de SSH à ne pas confondre avec File Transfer Protocol over SSL, abrégé FTPS.

L’objectif de cet article est d’écrire un bout de code pour se connecter à un serveur SFTP, uploader un fichier et télécharger un fichier.
Nous allons bien évidemment écrire un test unitaire et pour cela nous allons utiliser un serveur SFTP embarqué en mémoire.

Le client : Jsch

Jsch est une implémentation 100% Java de SSH2.

Cette librairie va nous permettre de communiquer avec un serveur SFTP.
L’authentification avec ce type de serveur peut se faire de 2 façons (n’oubliez pas que SFTP est du SSH, on retrouve donc beaucoup de choses en commun) :

• 1 login et 1 mot de passe.
• 1 login et 1 clé privée (dont la clé publique est enregistrée sur le serveur auparavant).

Dans cet article, nous utiliserons l’authentification par login/password (pour sa simplicité d’implémentation).

Un serveur SFTP pour les développements locaux

Pour les développements, je vous suggère d’utiliser un petit serveur SFTP à lancer sur votre poste :
miniSFTPServer est un mini-serveur SFTP ultra-léger vous permettant de travailler en local.

Il suffit de le lancer, puis de configurer un port, un login, un mot de passe et un chemin root pour le serveur.

La connection SFTP

Maintenant que le serveur SFTP est up&running en local, nous pouvons rentrer dans le vif du sujet.

La connection au serveur se fait sans encombre :

jsch = new JSch();
session = jsch.getSession(login, server, port);

// Java 6 version
session.setPassword(password.getBytes(Charset.forName("ISO-8859-1")));
            
// Java 5 version
// session.setPassword(password.getBytes("ISO-8859-1"));

Properties config = new java.util.Properties();
config.put("StrictHostKeyChecking", "no");
session.setConfig(config);

session.connect();

Il faut ensuite rajouter un com.jcraft.jsch.Channel de type “sftp” (qui est un com.jcraft.jsch.ChannelSftp une fois le channel accepté) :

// Initializing a channel
channel = session.openChannel("sftp");
channel.connect();
c = (ChannelSftp) channel;

L’upload de fichier

C’est encore tout simple : le Channel précédemment créé nous propose une méthode put :

c.put(sourceFile, destinationFile);

Il s’agit ici de la version prenant 2 Strings en paramètres. Cette méthode existe en une foultitude de déclinaisons, je vous invite à regarder la Javadoc pour coller à vos besoins.

Le téléchargement de fichier

Même chose que précédemment : le Channel propose une méthode get :

c.get(sourceFile, destinationFile);

La déconnection

Comme tout flux en Java, il est important de fermer le Channel puis la Session pour se déconnecter proprement !

Le test unitaire : Mina SSHD

Le projet Mina propose un sous-module très intéressant pour les tests unitaires de serveurs SFTP : SSHD.

Nous allons utiliser SSHD pour démarrer un serveur SFTP en mémoire qui nous servira à tester notre client SFTP écrit précédemment.

@Before

Dans une méthode setUp (annotée en @Before), nous allons démarrer un org.apache.sshd.SshServer:

@Before
public void setUp() throws IOException {
    // Init sftp server stuff
    sshd = SshServer.setUpDefaultServer();
    sshd.setPort(port);
    sshd.setPasswordAuthenticator(new MyPasswordAuthenticator());
    sshd.setPublickeyAuthenticator(new MyPublickeyAuthenticator());
    sshd.setKeyPairProvider(new SimpleGeneratorHostKeyProvider());
    sshd.setSubsystemFactories(Arrays.<NamedFactory<Command>>asList(new SftpSubsystem.Factory()));
    sshd.setCommandFactory(new ScpCommandFactory());

    sshd.start();
    ...
    ...
}

La méthode setUpDefaultServer() préconfigure automatiquement le SshServer.
Il ne reste qu’à rajouter le port d’écoute, implémenter un PasswordAuthenticator très simple, ainsi qu’un PublicKeyAuthenticator.

La partie touchy est la suivante : rajouter un ChannelSftp n’est pas trivial :

sshd.setSubsystemFactories(Arrays.<NamedFactory<Command>>asList(new SftpSubsystem.Factory()));

Une fois le serveur démarré, le test unitaire est très facile à écrire.

@After

N’oubliez pas d’éteindre le SshServer à la fin de l’exécution des tests unitaires :

sshd.stop();

Code complet

Vous pouvez retrouver tout ce code à peu près bien organisé, commenté avec des logs dans projet Maven :

https://github.com/jpbriend/sftp-example

Voici la configuration que j’applique lorsque mon poste de développement se situe derrière un proxy ultra-restrictif. Je pars du principe que vous êtes dans une entreprise, donc vous avez hélas un poste sous Windows.

Le principe est d’utiliser plink au lieu de la commande ssh fournie par défaut par msysgit.
Plink va permettre d’utiliser une clef stockée par pageant et de faire un tunnel SSH vers le repository git.

1ère étape : Télécharger plink, pageant et putty

Allez sur le site de putty et téléchargez les exécutables suivants :

• putty.exe
• plink.exe
• pageant.exe
• puttygen.exe

2ième étape : installer msysgit

Téléchargez la dernière version de msysgit sur le site officiel.
Suivez la procédure très bien décrite chez Github : Setup Git for Windows.
Rien de particulier à signaler ici.

3ième étape : changer l’agent SSH

Nous allons maintenant changer l’agent SSH utilisé par msysgit : ajoutez la variable d’environnement GIT_SSH et mettez en valeur le chemin vers plink.exe (exemple : C:\Program Files (x86)\PuTTY\plink.exe).

4ième étape : ppk-iser sa clé SSH

Je pars du principe que vous avez une clé SSH générée. Elle se présente sous la forme d’une paire de fichiers (par défaut id_rsa et id_rsa.pub) contenant votre clé privée et la clé publique associée.
A l’aide de puttygen, nous allons packager la clé au format .ppk (géré par pageant).

Lancez puttygen :

Utilisez le menu Conversions puis Import key.
Sélectionnez votre clé privée (par défaut id_rsa). Puttygen vous demande alors la passphrase pour accéder à votre clé.

Cliquez sur le bouton Save private key pour sauvegarder votre clé au format ppk.

5ième étape : charger sa clé dans pageant

Pageant doit tourner pour que plink puisse l’utiliser.
A chaque redémarrage du la machine, il faut rajouter la clé à pageant.

Lancer pageant : une icône apparait dans la barre des tâches.
Un clic droit dessus vous permet de rajouter une clé (Add key).
Sélectionnez votre clé au format ppk, entrez la passphrase et c’est tout.

6ième étape : ajouter ssh.github.com à putty

Maintenant, il faut configurer putty pour lui rajouter le site ssh.github.com.

Lancez putty et configurez le comme suit :

• Host name : ssh.github.com
• Port : 443
• Dans l’onglet Proxy, entrez les informations relatives à votre proxy : hostname, port et éventuellement login/password.
• Dans l’onglet Connection – SSH – Auth, chargez votre clé privé à l’aide du bouton Browse
• Revenez sur l’onglet Session et sauvegardez cette session avec un nom précis (par exemple gitproxy).

La configuration dans putty suffit.
Par contre, il faut se connecter une fois au serveur pour accepter la clé SSH du serveur : ouvrez une connection ssh avec putty grâce à la configuration précédemment créée et acceptez le certificat. Ceci n’est à faire qu’une seule fois.

7ième étape : cloner un repo dans Git ou ajouter un repo distant

La procédure est quasiment la même :

• Pour cloner un repository Git, récupérez l’URL du repository utilisant le protocole git (et non le http). Cette URL est au format : git@github.com:username/myRepo.git.
• Exécutez la commande suivante pour faire le clone Git : git clone git@gitproxy:username/myRepo.git. Notez le remplacement de github.com par le nom de la configuration Putty.

C’est tout : vous pouvez puller et pusher sur ce repository.
N’oubliez pas que pour que ceci fonctionne, il faut que pageant tourne et ait votre clé privée chargée.

L’astuce est dans le fait que lors d’une commande Git, ce dernier va exécuter plink pour se connecter en SSH au repository distant. Plink va alors regarder l’adresse dans l’URL, et chercher dans putty si une configuration existe avec ce nom. Comme c’est le cas, il va utiliser la configuration putty pour se connecter.

Pour ajouter un repository distant, faites de même avec :
git remote add monRepo git@gitproxy:username/myRepo.git
N’oubliez pas de substituer github.com par gitproxy.

Google AppEngine (GAE) propose une solution d’hébergement d’applications gratuites très pratiques pour des applications Java. La liste des fonctionnalités offertes par GAE peut-être consultée ici.
Le framework Play! fournit un module extrêmement bien fait pour déployer des applications sur Gae et un autre module est disponible pour gérer le Datastore Gae : Siena.

Google AppEngine

Google fournit un SDK complet pour développer des applications destinées à être hébergées par GAE. Dans le cas d’une application Play!, ce SDK est intégré au module GAE et le SDK n’est nécessaire que pour le déploiement final.
Il faut récupérer ce SDK à cette adresse : http://code.google.com/appengine/downloads.html.
La version Windows nécessite d’installer aussi Python (un lien est fourni via l’installeur du SDK).

Attaquons-nous à la partie applicative de cet article !

Play! Framework

Tout d’abord, il faut installer les modules GAE et Siena de Play! :

play install gae
play install siena

Une fois ces installations terminées, créons notre future application test-gae

play new test-gae

Enrichissons le conf/application.conf nouvellement créé avec les 2 modules précédents :

# ---- MODULES ----
module.gae=${play.path}/modules/gae-1.4
module.siena=${play.path}/modules/siena-1.3


Le Modèle

GAE sans stocker des données dans le Datastore, ça ne sert pas à grand chose.
Nous allons donc créer un objet modèle très simple que l’on retrouve dans quasiment toutes les applications : User !

package models;

import java.util.List;
import siena.Column;
import siena.Generator;
import siena.Id;
import siena.Max;
import siena.Model;
import siena.NotNull;
import siena.Query;

public class User extends Model {
	
    @Id(Generator.AUTO_INCREMENT)
    public Long id;

    @Column("login")
    @Max(15) @NotNull
    public String login;
	
    @Column("nickname")
    @Max(15) @NotNull
    public String nickname;
    ...
    ...
}

Il y a plusieurs choses importantes à noter :

• La classe User étend la classe siena.Model et non plus la classe play.Model du framework Play!.
  Logique : play.Model est destiné à JPA qui n’est pas utilisé par GAE.
• Il faut mettre un Id ! L’annotation @Id est obligatoire et elle doit pointer sur une variable de type Long nommée id.
• Les autres annotations sont optionnelles. Par défaut, la table créée prendra le nom de la classe et les colonnes prendront le nom des variables sur lesquelles elles pointent.

Il va maintenant falloir ajouter des méthodes à notre modèle afin de pouvoir récupérer des données :

...
static Query<User> all() {
    return Model.all(User.class);
}
	
public static List<User> findAll() {
    return all().fetch();
}
    
public static User findById(Long id) {
    return all().filter("id", id).get();
}
    
public static User findByLogin(String login) {
    return all().filter("login", login).get();
}

Nous avons ajouté une méthode protected all() qui créé une Query qui ramènera tous les Users.
A partir de cette méthode, nous allons appliquer différents filtres pour ramener les données qui nous intéressent :

• fetch() pour ramener toutes les données d’une Query.
• filter(“id”, id).get() pour filtrer les données dont l’attribut id est égal à id.
• filter(“login”, login).get() pour filtrer les données dont l’attribut login est égal à login.

Nous avons maintenant un petit modèle. Attaquons-nous au contrôleur dédié à User !

Le Contrôleur

Pour faire le plus simple possible, utilisons le contrôleur créé par défaut par Play! : Application.

package controllers;

import java.util.List;

import models.User;
import play.mvc.Controller;

public class Application extends Controller {

    public static void index() {
        List<User> users = User.findAll();
        render(users);
    }

    public static void add(String login, String nickname) {
        User add = new User();
        add.login = login;
        add.nickname = nickname;
        add.insert();

        index();
    }

    public static void delete(Long id) {
        notFoundIfNull(id);
        User toRemove = User.findById(id);
        toRemove.delete();

        index();
    }
}

Il s’agit d’un contrôleur tout ce qu’il y a de plus classique en Play!.
Une des méthodes va ramener la liste des Users, une autre va permettre d’en ajouter un et enfin la dernière permet d’en supprimer un.

Notre contrôleur est prêt, ajoutons-lui une page html pour pouvoir jouer avec !

La Vue

Contentons-nous d’utiliser le fichier index.html du contrôleur Application :

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

<p>
<h2>Liste des Users :</h2>
  #{list items:users, as:'user'}
    <div><label>[${user.id}] ${user.login} (${user.nickname})</label><label>#{a @Application.delete(user.id)}Delete#{/a}</label></div>
  #{/list}
</p>

<p>
#{form @Application.add()}
<h2>Add a User :</h2>
<div>
  <label>Login :</label>
  <input type="text" name="login" />
</div>

<div>
  <label>Nickname :</label>
  <input type="text" name="nickname" />
</div>
<div>
  <input type="submit" value="Add" />
</div>
#{/form}
</p>

Rien que du très classique Play! : une liste pour afficher tous les Users, un lien pour supprimer un User et enfin un formulaire pour créer un User.

Notre application est désormais prête à être déployée sur Google AppEngine !
Vous pouvez la tester avec un play run, elle devrait tourner parfaitement.

Le déploiement sur Google AppEngine

Lorsque nous avons créé l’application avec un play new test-gae, le module GAE a créé un répertoire war à la racine de notre application.
Celui-ci contient un fichier généré automatiquement : web.xml.
Il va être important de le modifier pour pouvoir déployer correctement sur GAE.

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application><!-- ID GAE de votre application --></application>
  <version>1</version>
</appengine-web-app>

La balise application doit contenir l’ID de votre application Google AppEengine.
Pour le déterminer, il faut créer une application dans Google AppEngine.

Créer une application dans Google AppEngine

Rendez-vous sur https://appengine.google.com/.
Vous devez vous identifier avec votre compte Gmail.
Lors de la création de votre première application, il vous demandera sûrement un numéro de téléphone portable pour vous envoyer un code.
Une fois cette étape passée, vous devriez pouvoir créer une application Google AppEngine :

C’est le champ Application Identifier qui contient l’id de votre application à mettre dans votre fichier web.xml.

Hop, votre application a dûe être déclarée dans Google AppEngine !

Déployer l’application sur Google AppEngine

Ma petite soeur peut le faire : en se plaçant dans le répertoire de notre application, il suffit de lancer :

play gae:deploy --gae={path_to_gae_sdk}

path_to_gae_sdk indique votre installation du SDK Google AppEngine.

Vous devriez voir Play! précompiler les classes, assembler un war puis tenter d’uploader votre application.
Il vous demanderas sûrement votre login et mot de passe Gmail pour vous identifier sur votre compte.
Une fois l’upload terminé, vous pouvez administrer votre application grâce à la console AppEngine :
https://appengine.google.com

Votre application est disponible à l’url indiquée par la console d’administration :

Voici l’archive du projet, prête à l’emploi : Zip.

L’objectif est d’intégrer dans une page un éditeur de texte riche au format Textile. Cette syntaxe est très simple à appréhender et la génération de code HTML à partir de code Textile est native dans Play! grâce à la librairie Wikitext.

En ce qui concerne l’éditeur en tant que tel, nous allons utiliser l’excellent MarkItUp. Il est basé sur jQuery, lui même nativement embarqué par Play!. MarkItUp propose un éditeur modulaire, permettant de gérer plusieurs syntaxes. L’ajout de syntaxes se fait par des sets.

MarkItUp

Commençons par télécharger MarkItUp! pack sur la page des téléchargements.
Il faut aussi prendre le Basic Textile Set.
L’archive MarkItUp contient un répertoire markitup : c’est celui-ci qu’il faut décompresser dans le répertoire public de votre application Play!.
Il faut ensuite décompresser l’archive contenant le Basic Textile Set dans le répertoire public/markitup/sets : un nouveau répertoire textile a dû apparaître.

L’installation des fichiers de MarkItUp est désormais terminée. Nous reviendrons plus tard pour la configuration et la customisation de l’éditeur.

Générateur Wikitext

Nous allons avoir besoin de 2 méthodes :

• une 1ère méthode pour générer le code destiné à l’iframe Preview. Qui dit iframe dit qu’il va falloir rajouter les feuilles css au code HTML généré.
• une 2ième méthode destinée à générer le code qui sera faire le rendu du code Textile saisi par l’utilisateur. Cette fois-ci, il ne faut pas que les css soient inclues dans le code html généré.

J’ai décidé de créer ces 2 méthodes dans un Controler :

package controllers;

import java.io.StringWriter;

import jj.play.org.eclipse.mylyn.wikitext.core.parser.MarkupParser;
import jj.play.org.eclipse.mylyn.wikitext.core.parser.builder.HtmlDocumentBuilder;
import jj.play.org.eclipse.mylyn.wikitext.core.parser.builder.HtmlDocumentBuilder.Stylesheet;
import jj.play.org.eclipse.mylyn.wikitext.textile.core.TextileLanguage;
import play.mvc.Controller;

public class Wikitext extends Controller {

    // Controller classique Play! qui sera appelé par l'iframe Preview de MarkItUp.
    public static void renderPreview(String wiki) {
        StringWriter writer = new StringWriter();
        HtmlDocumentBuilder builder = new HtmlDocumentBuilder(writer);

        // Ajout de mes 2 css.
        Stylesheet css = new Stylesheet("/public/stylesheets/main.css");
        builder.addCssStylesheet(css);
        css = new Stylesheet("/public/stylesheets/wiki.css");
        builder.addCssStylesheet(css);

        // Création du parser Textile
        MarkupParser parser = new MarkupParser(new TextileLanguage());
        parser.setBuilder(builder);
        parser.parse(wiki);

        String htmlContent = writer.toString();
        renderText(htmlContent);
    }

    // Méthode qui sera appelée par les templates Groovy de Play!.
    public static String render(String wiki) {
        StringWriter writer = new StringWriter();
        HtmlDocumentBuilder builder = new HtmlDocumentBuilder(writer);
        // Empêche la génération des balises html et body.
        builder.setEmitAsDocument(false);

        // Création du parser Textile
        MarkupParser parser = new MarkupParser(new TextileLanguage());
        parser.setBuilder(builder);
        parser.parse(wiki);

        return writer.toString();
    }
}

Ces 2 méthodes n’ont rien de spécial : elles utilisent Wikitext qui parse le code Textile de l’utilisateur et en fait un rendu HTML.
Notez dans l’une l’ajout de mes 2 css alors que l’autre méthode ne génère pas les tags html et body.

Afin de rendre ce controller un peu plus sexy, ajoutons lui une route pour le rendu de Preview :

 
*       /wikitext/renderPreview                 Wikitext.renderPreview
 

Installation de markItUp dans nos templates

Tout d’abord, il faut ajouter dans la page que vous voulez enrichier de notre éditeur riche le code suivant qui chargera markItUp :

<!--  Loading Markitup -->
<link rel="stylesheet" type="text/css" href="@{'/public/markitup/skins/markitup/style.css'}" />
<script type="text/javascript" src="@{'/public/markitup/jquery.markitup.js'}"></script>

<link rel="stylesheet" type="text/css" href="@{'/public/markitup/sets/textile/style.css'}" />
<script type="text/javascript" src="@{'/public/markitup/sets/textile/set.js'}"></script>

<script language="javascript">
$(document).ready(function()    {
    $('#wiki').markItUp(mySettings);
});
</script>
<!-- End markitup -->

Attention à modifier le code ci-dessus pour que l’identifiant ‘#wiki’ pointe bien vers l’id du textarea que vous voulez enrichir avec markItUp.
De plus, notez la variable mySettings. Celle-ci contient la configuration du plugin markItUp sous format JSON.

Voici un exemple de textarea qui va être enrichi par le plugin markItUp :

<textarea id="wiki" name="description" cols="70" rows="20">
    Bla Bla ...
</textarea>

Configuration et customisation de markItUp

Il va falloir maintenant configurer et customiser markItUp.

Pour cela, il va falloir commencer par éditer le fichier public/markitup/sets/textile/set.js :

mySettings = {
	previewParserPath:	'/wikitext/renderPreview', // path to your Wiki parser
	previewParserVar:	'wiki',
	onShiftEnter:		{keepDefault:false, replaceWith:'\n\n'},
	markupSet: [
		{name:'Heading 1', key:'1', openWith:'h1(!(([![Class]!]))!). ', placeHolder:'Your title here...' },
		{name:'Heading 2', key:'2', openWith:'h2(!(([![Class]!]))!). ', placeHolder:'Your title here...' },
		{name:'Heading 3', key:'3', openWith:'h3(!(([![Class]!]))!). ', placeHolder:'Your title here...' },
		{name:'Heading 4', key:'4', openWith:'h4(!(([![Class]!]))!). ', placeHolder:'Your title here...' },
		{name:'Heading 5', key:'5', openWith:'h5(!(([![Class]!]))!). ', placeHolder:'Your title here...' },
		{name:'Heading 6', key:'6', openWith:'h6(!(([![Class]!]))!). ', placeHolder:'Your title here...' },
		{name:'Paragraph', key:'P', openWith:'p(!(([![Class]!]))!). '},
		{separator:'---------------' },
		{name:'Bold', key:'B', closeWith:'*', openWith:'*'},
		{name:'Italic', key:'I', closeWith:'_', openWith:'_'},
		{name:'Stroke through', key:'S', closeWith:'-', openWith:'-'},
		{separator:'---------------' },
		{name:'Bulleted list', openWith:'(!(* |!|*)!)'},
		{name:'Numeric list', openWith:'(!(# |!|#)!)'}, 
		{separator:'---------------' },
		{name:'Picture', replaceWith:'![![Source:!:http://]!]([![Alternative text]!])!'}, 
		{name:'Link', openWith:'"', closeWith:'([![Title]!])":[![Link:!:http://]!]', placeHolder:'Your text to link here...' },
		{separator:'---------------' },
		{name:'Quotes', openWith:'bq(!(([![Class]!]))!). '},
		{name:'Code', openWith:'@', closeWith:'@'},
		{separator:'---------------' },
		{name:'Preview', call:'preview', className:'preview'}
	]
}

J’ai fais les modifications suivantes :

• Remplissage de la variable previewParserPath : on pointe vers le controller que nous avons écrit plus tôt.
• Ajout de la variable previewParserVar pour donner le nom du paramètre HTTP contenant le code à envoyer au controller.

Le reste du fichier sert à configurer l’apparence et les boutons de markItUp. Je vous laisse le soin de fouiller la documentation de ce plugin si vous le souhaitez.

Il ne reste qu’à terminer par un peu de customisation via une CSS.
J’ai modifié le fichier public/markitup/sets/textile/style.css et j’ai rajouté les lignes suivantes :

.markItUp  {
    width:500px;
}

.markItUpEditor {
    width:443px;
    height:220px;
}

Ces surcharges me servent uniquement à redimensionner markItUp.

Et voilà !
En une petite dizaine de minutes, nous avons réussi à transformer un simple Textarea en un éditeur riche supportant Textile avec un rendu aux petits oignons. Soignez votre CSS de rendu et vous êtes le roi du pétrole !

Bonus : Voici un projet Play! contenant le code de cet article. Lancez-le avec un play run et ça marche !
Télécharger le code.

Je vais plutôt vous faire un retour d’expérience de la mise en place des outils nécessaires pour intégrer des applications Play! à notre usine d’Intégration Continue.

Commençons par la description de notre environnement, très classique :

• tous les projets Java sont mavenisés (Maven 2).
• tous les projets définissent des tests unitaires (JUnit).
• certains projets ont des tests Selenium.
• tous les projets ont des builds lancés automatiquement par Bamboo.
• tous les projets sont analysés par Sonar chaque nuit

La tâche est de faire rentrer les futures applications écrites avec Play! dans cette chaîne d’Intégration Continue.

Mavenisation d’une application Play!

Il s’agit de l’étape qui fut la plus compliquée et surtout la plus longue. Le cahier des charges est le suivant :

• Gestion des dépendances applicatives (ie: remplir le répertoire /lib avec les dependencies Maven du projet).
• Gestion des librairies inclues dans le framework Play! (afin que la phase compile se passe correctement).
• Maven doit pouvoir faire exécuter les tests unitaires et en récupérer un rapport Surefire.
• Maven doit pouvoir exécuter Cobertura sur l’application et en extraire un rapport (à destination de Sonar).
• Une analyse Sonar doit être effectuée sur l’application.

Gestion des dépendances applicatives

Avec un peu de configuration Maven, (plugin dependency), il est assez facile de faire exporter les librairies applicatives dans le répertoires lib de l’application, ainsi que de les supprimer lors d’un mvn clean.

  <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>2.1</version>
        <executions>
          <execution>
            <id>default-cli</id>
            <configuration>
              <includeClassifiers>,sources</includeClassifiers>
              <outputDirectory>lib/</outputDirectory>
              <excludeScope>provided</excludeScope>
              <!-- To download sources jars without failing -->
              <failOnMissingClassifierArtifact>false</failOnMissingClassifierArtifact>
              <excludeArtifactIds>play-runtime,play</excludeArtifactIds>
            </configuration>
         ...

Gestion des dépendances du framework Play!

Là, le boulot est un peu plus long car j’ai dû référencer toutes les librairies du framework. Cependant les versions sont très standard (mis à part un patch sur Hibernate), donc le boulot se fait bien.
Petit écueil : certaines librairies n’existent pas dans les repository standards. Il y en a donc certaines qui doivent être uploadées dans votre Nexus d’entreprise.

Ces 2 étapes doivent vous permettre de compiler un projet Play! sous Maven sans encombre.

Maintenant que la compilation fonctionne, préparons l’exécution des tests unitaires via le runtime de Play!

Le Runtime de Play! pour les Tests unitaires

Je sais que la pratique suivante fera bondir certains, mais le runtime de Play! est tout simplement beaucoup trop puissant pour que l’on puisse s’en passer !
Nous ne voulions pas devoir gérer l’installation du runtime sur les différents environnements où les agents Bamboo sont déployés. Il faut donc le packager sous forme de ressources avec ses modules intégrés dans le repository Maven. Une tâche Ant se chargera de le dézipper afin que la commande play soit accessible.

  <dependency>
    <groupId>org.play</groupId>
    <artifactId>play-runtime</artifactId>
    <version>1.1</version>
    <type>zip</type>
  </dependency>

Les tests unitaires

Les tests unitaires de Play! framework sont des tests JUnit mais lancés par le runtime Play!.

La commande auto-test permet de lancer les tests unitaires et les tests Selenium automatiquement. Un reporting sous forme de fichier html est généré. J’ai donc dû enrichir le framework pour générer un rapport au format Surefire. Ce rapport contient le nombre de tests unitaires joués, le nombre d’erreurs, d’echecs, le temps passé ainsi qu’un détail des erreurs.
Un script ant permet de faire lancer par Maven le framework Play! en mode auto-test.

Voici une exécution Maven du plugin mavent-antrun-plugin :

<execution>
  <id>UnitTests</id>
  <phase>test</phase>
  <configuration>
    <target>
      <property name="maven.project.artifactId" value="${project.artifactId}" />
      <property name="maven.project.version" value="${project.version}" />
      <property name="maven.project.play-runtime" value="play-runtime-${play.version}" />

      <property name="play.runtime.path" value="${basedir}/target/dependency/${maven.project.play-runtime}" />
      <property name="play.runtime.file" value="${basedir}/target/dependency/${maven.project.play-runtime}.zip" />
      <property name="play.runtime.unzip.path" value="${basedir}/target/dependency" />

      <!-- Check zipped Play! runtime is present. Build fails if not present -->
      <available file="${play.runtime.file}" property="play.runtime.present" />
      <echo message="Is Play! runtime present : ${play.runtime.present}" />

      <fail message="Error : Play! runtime could not be found at : ${play.runtime.file}">
        <condition>
          <not>
            <isset property="play.runtime.present" />
          </not>
        </condition>
      </fail>

      <!-- Delete existing Play! runtime -->
      <echo message="Deleting any existing unzipped Play! runtime ..." />
      <delete dir="play.runtime.unzip.path" failonerror="false" verbose="true" />

      <!-- Unzip Play! runtime -->
      <echo message="Unzipping Play! runtime ..." />
      <unzip src="${play.runtime.file}" dest="${play.runtime.unzip.path}" />
      <echo message="Play! runtime unzipped successfully." />
      <chmod dir="${play.runtime.path}" perm="ugo+x" includes="play" />

      <!-- launch play mvn:up to retrieve libs in /lib folder -->
      <condition property="playExtension" value=".bat">
        <and>
          <os family="windows" />
        </and>
      </condition>
      <condition property="playExtension" value="">
        <and>
          <os family="unix" />
        </and>
      </condition>
      <exec executable="${play.runtime.unzip.path}/${maven.project.play-runtime}/play${playExtension}">
        <arg value="mvn:up" />
      </exec>

      <!-- Launch Play war command -->
      <condition property="playExtension" value=".bat">
        <and>
          <os family="windows" />
        </and>
      </condition>
      <condition property="playExtension" value="">
        <and>
          <os family="unix" />
        </and>
      </condition>
      <exec executable="${play.runtime.unzip.path}/${maven.project.play-runtime}/play${playExtension}">
        <arg value="auto-test" />
      </exec>
    </target>
  </configuration>
  <goals>
    <goal>run</goal>
  </goals>
</execution>

L’étape des Tests Unitaires est désormais ok !

L’analyse Cobertura

Que serait une analyse Sonar sans le plugin Cobertura !

Heureusement, il existe un module Cobertura pour la framework Play! Il est très bien intégré puisqu’il suffit de le configurer dans votre application.conf et il l’analyse Cobertura sera effectuée durant la phase des tests unitaires. Un rapport est généré. Le seul travail à faire est de référencer dans Sonar l’emplacement de ce rapport pour que ce dernier puisse l’exploiter.

Je vous conseille la documentation de ce très bon module Play! : Documentation module Cobertura.

Le packaging

Un gros morceau là aussi.

Le packaging d’une application Play! doit être fait sous forme de war pour pouvoir être uploadé dans un repository Maven.
L’idée retenue est que l’on va laisser Maven exécuter sa phase package qui buildera un war non fonctionnel, puis une tâche Ant branchée sur cette même phase va générer grâce à la commande play war un fichier war Play! fonctionnel. Le principal soucis rencontré fût l’exclusion du répertoire target du packaging fait par Play! (notre target contient notamment le runtime Play!). Un développement soumis sur Github nous a permis de rajouter un paramètre –exclude à la ligne de commande play war et d’exclure les répertoires que nous ne voulions pas builder.

Voici l’exécution Maven du plugin Antrun :

<execution>
  <id>Packaging</id>
  <phase>package</phase>
  <configuration>
    <target>
      <property name="maven.project.artifactId" value="${project.artifactId}" />
      <property name="maven.project.version" value="${project.version}" />
      <property name="maven.project.play-runtime" value="play-runtime-${play.version}" />

      <property name="play.runtime.path" value="${basedir}/target/dependency/${maven.project.play-runtime}" />
      <property name="play.runtime.file" value="${basedir}/target/dependency/${maven.project.play-runtime}.zip" />
      <property name="play.runtime.unzip.path" value="${basedir}/target/dependency" />

      <!-- Check zipped Play! runtime is present. Build fails if not present -->
      <available file="${play.runtime.file}" property="play.runtime.present" />
      <echo message="Is Play! runtime present : ${play.runtime.present}" />

      <fail message="Error : Play! runtime could not be found at : ${play.runtime.file}">
        <condition>
          <not>
            <isset property="play.runtime.present" />
          </not>
        </condition>
      </fail>

      <!-- Delete existing Play! runtime -->
      <echo message="Deleting any existing unzipped Play! runtime ..." />
      <delete dir="play.runtime.unzip.path" failonerror="false" verbose="true" />

      <!-- Unzip Play! runtime -->
      <echo message="Unzipping Play! runtime ..." />
      <unzip src="${play.runtime.file}" dest="${play.runtime.unzip.path}" />
      <echo message="Play! runtime unzipped successfully." />
      <chmod dir="${play.runtime.path}" perm="ugo+x" includes="play" />

      <!-- launch play mvn:up to retrieve libs in /lib folder -->
      <condition property="playExtension" value=".bat">
        <and>
          <os family="windows" />
        </and>
      </condition>
      <condition property="playExtension" value="">
        <and>
          <os family="unix" />
        </and>
      </condition>
      <exec executable="${play.runtime.unzip.path}/${maven.project.play-runtime}/play${playExtension}">
        <arg value="mvn:up" />
      </exec>

      <!-- Launch Play war command -->
      <condition property="playExtension" value=".bat">
        <and>
          <os family="windows" />
        </and>
      </condition>
      <condition property="playExtension" value="">
        <and>
          <os family="unix" />
        </and>
      </condition>
      <exec executable="${play.runtime.unzip.path}/${maven.project.play-runtime}/play${playExtension}">
        <arg value="war" />
        <arg value="${basedir}" />
        <arg value="-o" />
        <arg value="${basedir}/target/${maven.project.artifactId}-${maven.project.version}" />
        <arg value="--zip" />
        <arg value="--exclude" />
        <arg value="target" />
      </exec>
    </target>
  </configuration>
  <goals>
    <goal>run</goal>
  </goals>
</execution>

Nous avons donc les tests unitaires, l’analyse Cobertura, le packaging en War et le déploiement dans un repo Maven qui fonctionnent. Il ne nous reste plus qu’à attaquer l’analyse Sonar.

L’analyse Sonar

Avec un peu de configuration (emplacement des sources, des fichiers Surefire, Cobertura, etc…), la configuration du plugin Sonar s’est passée sans encombres.

Nous avons donc réussi à intégrer les applications Play! à notre usine d’Intégration Continue.
Les projets ont donc uniquement besoin d’un pom avec les bonnes dépendances pour pouvoir commencer leurs développements et qu’ils soient compatibles Usine de Développement.

Conclusion : malgré quelques difficultés, l’intégration du framework Play! s’est faite sans gros soucis. Nous avons ainsi pu rentrer dans le code du framework, autant du côté Python que du côté Java. Quelques Pull Request chez Github et nous sommes pleinement fonctionnels !

Merci à Play! framework et à toute son équipe !

Update 16/12/2010 :
Suite aux commentaires, voici le contenu du pom parent pour la version 1.1 de Play! :

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.play</groupId>
  <artifactId>play-parent</artifactId>
  <version>1.1</version>
  <packaging>pom</packaging>
  <name>Play's parent POM</name>
  
  <repositories>
    <!-- Repository containing Play! jars. If you have your own repo (ex: Nexus), upload missing libs in third-parties -->
    <repository>
      <id>infin-it</id>
      <url>http://nexus.infin-it.fr/content/groups/public</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
  </repositories>  
    
  <properties>
    <play.version>1.1</play.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>javax.activation</groupId>
      <artifactId>activation</artifactId>
      <version>1.1.1</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>antlr</groupId>
      <artifactId>antlr</artifactId>
      <version>2.7.6</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>com.ning</groupId>
      <artifactId>async-http-client</artifactId>
      <version>1.2.0</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.bouncycastle</groupId>
      <artifactId>bcprov-jdk15</artifactId>
      <version>1.45</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>c3p0</groupId>
      <artifactId>c3p0</artifactId>
      <version>0.9.1.2</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>cglib</groupId>
      <artifactId>cglib-nodep</artifactId>
      <version>2.2</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>commons-beanutils</groupId>
      <artifactId>commons-beanutils</artifactId>
      <version>1.8.3</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>commons-codec</groupId>
      <artifactId>commons-codec</artifactId>
      <version>1.4</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>commons-collections</groupId>
      <artifactId>commons-collections</artifactId>
      <version>3.1</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.apache.commons</groupId>
      <artifactId>commons-email</artifactId>
      <version>1.2</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>commons-fileupload</groupId>
      <artifactId>commons-fileupload</artifactId>
      <version>1.2</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>commons-io</groupId>
      <artifactId>commons-io</artifactId>
      <version>1.4</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>commons-lang</groupId>
      <artifactId>commons-lang</artifactId>
      <version>2.5</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>commons-logging</groupId>
      <artifactId>commons-logging</artifactId>
      <version>1.1.1</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>dom4j</groupId>
      <artifactId>dom4j</artifactId>
      <version>1.6.1</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>net.sf.ehcache</groupId>
      <artifactId>ehcache-core</artifactId>
      <version>2.0.0</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>net.sf.ezmorph</groupId>
      <artifactId>ezmorph</artifactId>
      <version>1.0.3</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.codehaus.groovy</groupId>
      <artifactId>groovy-all</artifactId>
      <version>1.7.1</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>1.4</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-core</artifactId>
      <version>3.5.6-Final</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-annotations</artifactId>
      <version>3.5.6-Final</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-commons-annotations</artifactId>
      <version>3.2.0.Final</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-entitymanager</artifactId>
      <version>3.5.6-Final</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.hibernate.javax.persistence</groupId>
      <artifactId>hibernate-jpa-2.0-api</artifactId>
      <version>1.0.0.Final</version>
      <scope>provided</scope>
    </dependency>
    <!-- This lib must be added to your repository (comes from Sourceforge)-->
    <dependency>
      <groupId>hsqldb</groupId>
      <artifactId>hsqldb</artifactId>
      <version>1.8.1.2</version>
      <scope>provided</scope>
    </dependency>
    <!-- This lib must be added to your repository (comes from Sourceforge)-->
    <dependency>
      <groupId>com.jamonapi</groupId>
      <artifactId>jamon</artifactId>
      <version>2.7</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>javax.mail</groupId>
      <artifactId>mail</artifactId>
      <version>1.4.3</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>javassist</groupId>
      <artifactId>javassist</artifactId>
      <version>3.9.0.GA</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>jaxen</groupId>
      <artifactId>jaxen</artifactId>
      <version>1.1</version>
      <scope>provided</scope>
    </dependency>
    <!-- This lib must be added to your repository -->
    <dependency>
      <groupId>org.play.jj</groupId>
      <artifactId>imaging</artifactId>
      <version>1.1</version>
      <scope>provided</scope>
    </dependency>
    <!-- This lib must be added to your repository -->
    <dependency>
      <groupId>org.play.jj</groupId>
      <artifactId>simple-captcha</artifactId>
      <version>1.1</version>
      <scope>provided</scope>
    </dependency>
    <!-- This lib must be added to your repository -->
    <dependency>
      <groupId>org.play.jj</groupId>
      <artifactId>textile</artifactId>
      <version>1.1</version>
      <scope>provided</scope>
    </dependency>
    <!-- This lib must be added to your repository -->
    <dependency>
      <groupId>org.play.jj</groupId>
      <artifactId>wikitext</artifactId>
      <version>1.1</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>joda-time</groupId>
      <artifactId>joda-time</artifactId>
      <version>1.6</version>
      <scope>provided</scope>
    </dependency>
    <!-- This lib must be added to your repository (comes from Sourceforge)-->
    <dependency>
      <groupId>jregex</groupId>
      <artifactId>jregex</artifactId>
      <version>1.2_01</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>net.sf.jsr107cache</groupId>
      <artifactId>jsr107cache</artifactId>
      <version>1.0</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>javax.transaction</groupId>
      <artifactId>jta</artifactId>
      <version>1.1</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.8.1</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>log4j</groupId>
      <artifactId>log4j</artifactId>
      <version>1.2.16</version>
      <scope>provided</scope>
    </dependency>
    <!-- This lib must be added to your repository -->
    <dependency>
      <groupId>net.spy</groupId>
      <artifactId>memcached</artifactId>
      <version>2.4.2</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>mysql</groupId>
      <artifactId>mysql-connector-java</artifactId>
      <version>5.1.13</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.jboss.netty</groupId>
      <artifactId>netty</artifactId>
      <version>3.2.2.Final</version>
      <scope>provided</scope>
    </dependency>
    <!-- This lib must be added to your repository -->
    <dependency>
      <groupId>org.play</groupId>
      <artifactId>org.eclipse.jdt.core</artifactId>
      <version>3.6.0</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>net.sf.oval</groupId>
      <artifactId>oval</artifactId>
      <version>1.50</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.apache.geronimo.specs</groupId>
      <artifactId>geronimo-servlet_2.5_spec</artifactId>
      <version>1.2</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>oauth.signpost</groupId>
      <artifactId>signpost-core</artifactId>
      <version>1.2</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-api</artifactId>
      <version>1.6.1</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-log4j12</artifactId>
      <version>1.6.1</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.yaml</groupId>
      <artifactId>snakeyaml</artifactId>
      <version>1.6</version>
      <scope>provided</scope>
    </dependency>
    
    <!-- Play! framework dependency -->
    <dependency>
      <groupId>org.play</groupId>
      <artifactId>play</artifactId>
      <version>1.1</version>
    </dependency>
    
    <dependency>
      <groupId>org.play</groupId>
      <artifactId>play-runtime</artifactId>
      <version>1.1</version>
      <type>zip</type>
    </dependency>
  </dependencies>
  
  <build>
    <sourceDirectory>app</sourceDirectory>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-war-plugin</artifactId>
          <version>2.1.1</version>
          <configuration>
            <failOnMissingWebXml>false</failOnMissingWebXml>
          </configuration>
        </plugin>

        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-dependency-plugin</artifactId>
          <version>2.1</version>
          <executions>
            <execution>
              <id>default-cli</id>
              <configuration>
                <includeClassifiers>,sources</includeClassifiers>
                <outputDirectory>lib/</outputDirectory>
                <excludeScope>provided</excludeScope>
                <!-- To download sources jars without failing -->
                <failOnMissingClassifierArtifact>false</failOnMissingClassifierArtifact>
                <excludeArtifactIds>play-runtime,play</excludeArtifactIds>
              </configuration>
            </execution>
            <execution>
              <id>packaging</id>
              <phase>package</phase>
              <goals>
                <goal>copy-dependencies</goal>
              </goals>
              <configuration>
                <includeArtifactIds>play-runtime</includeArtifactIds>
              </configuration>
            </execution>
          </executions>
        </plugin>

        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-antrun-plugin</artifactId>
          <version>1.6</version>
          <executions>
            <execution>
              <phase>package</phase>
              <configuration>
                <target>
                  <property name="maven.project.artifactId" value="${project.artifactId}" />
                  <property name="maven.project.version" value="${project.version}" />
                  <property name="maven.project.play-runtime" value="play-runtime-${play.version}" />

                  <property name="play.runtime.path" value="${basedir}/target/dependency/${maven.project.play-runtime}" />
                  <property name="play.runtime.file" value="${basedir}/target/dependency/${maven.project.play-runtime}.zip" />
                  <property name="play.runtime.unzip.path" value="${basedir}/target/dependency" />

                  <!-- Check zipped Play! runtime is present. Build fails if not present -->
                  <available file="${play.runtime.file}" property="play.runtime.present" />
                  <echo message="Is Play! runtime present : ${play.runtime.present}" />

                  <fail message="Error : Play! runtime could not be found at : ${play.runtime.file}">
                    <condition>
                      <not>
                        <isset property="play.runtime.present" />
                      </not>
                    </condition>
                  </fail>

                  <!-- Delete existing Play! runtime -->
                  <echo message="Deleting any existing unzipped Play! runtime ..." />
                  <delete dir="play.runtime.unzip.path" failonerror="false" verbose="true" />

                  <!-- Unzip Play! runtime -->
                  <echo message="Unzipping Play! runtime ..." />
                  <unzip src="${play.runtime.file}" dest="${play.runtime.unzip.path}" />
                  <echo message="Play! runtime unzipped successfully." />
                  <chmod dir="${play.runtime.path}" perm="ugo+x" includes="play" />

                  <!-- launch play mvn:up to retrieve libs in /lib folder -->
                  <condition property="playExtension" value=".bat">
                    <and>
                      <os family="windows" />
                    </and>
                  </condition>
                  <condition property="playExtension" value="">
                    <and>
                      <os family="unix" />
                    </and>
                  </condition>
                  <exec executable="${play.runtime.unzip.path}/${maven.project.play-runtime}/play${playExtension}">
                    <arg value="mvn:up" />
                  </exec>

                  <!-- Launch Play war command -->
                  <condition property="playExtension" value=".bat">
                    <and>
                      <os family="windows" />
                    </and>
                  </condition>
                  <condition property="playExtension" value="">
                    <and>
                      <os family="unix" />
                    </and>
                  </condition>
                  <exec executable="${play.runtime.unzip.path}/${maven.project.play-runtime}/play${playExtension}">
                    <arg value="war" />
                    <arg value="${basedir}" />
                    <arg value="-o" />
                    <arg value="${basedir}/target/${maven.project.artifactId}-${maven.project.version}" />
                    <arg value="--zip" />
                  </exec>
                </target>
              </configuration>
              <goals>
                <goal>run</goal>
              </goals>
            </execution>
          </executions>
        </plugin>

        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-clean-plugin</artifactId>
          <version>2.4.1</version>
          <configuration>
            <filesets>
              <fileset>
                <directory>${project.basedir}/lib</directory>
                <includes>
                  <include>**/*.jar</include>
                  <include>**/*.zip</include>
                </includes>
                <followSymlinks>false</followSymlinks>
              </fileset>
            </filesets>
          </configuration>
        </plugin>
        
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>2.3.1</version>
          <configuration>
            <source>1.5</source>
            <target>1.5</target>
          </configuration>
        </plugin>

      </plugins>
    </pluginManagement>

  </build>
  
</project>

A ce moment là, JMX pose problème pour la remontée d’informations.

L’idée que je vais vous proposer est la suivante :

• Une JVM hébergeant un MBeanServer tourne en continu (éventuellement hébergé dans un serveur d’application).
• Chacun des traitements se connectera à cette JVM en utilisant un JMX Connector et invoquera à distance des Notifications JMX à destination du MBeanServer.

Grâce à cette architecture, les ports des JVM ‘clientes’ ne sont plus un problème : on laisse le mécanisme par défaut de JMX se débrouiller pour en trouver un libre.

Les personnes souhaitant monitorer ces traitements n’ont qu’à lancer JConsole et se connecter sur la JVM ‘serveur’ qui héberge le MBeanServer.

Le schéma suivant présente le principe :

JMX Notifier va être un objet faisant appel au NotificationPublisher de JMX.
Ce NotificationPublisher envoi des notifications au serveur MBean.

Le JMX Notifier va être exposé par des JMX Connectors aux clients et sera proxyfié.
Le traitement peut alors utiliser de façon invisible cet objet pour envoyer des évènements à la JVM distante.

Passons maintenant au code !

JMX Notifier (serveur) :

@ManagedResource(objectName="batch:name=BatchJMX", description="JMX Notifier")
public class JmxNotifierImpl implements JmxNotifier, NotificationPublisherAware {

  protected NotificationPublisher publisher;

  @ManagedOperation(description="Annonce Début batch.")
  @ManagedOperationParameters(
  @ManagedOperationParameter(name="id", description= "Batch ID."))
  public void annonceDebut(String id) {
    super.publisher.sendNotification(
                    new Notification("Debut du Batch " + id,
                                           this,
                                           0,
                                           Calendar.getInstance().getTimeInMillis()));
  }

  public void setNotificationPublisher(NotificationPublisher publisher) {
    this.publisher = publisher;
  }
}

On notera l’utilisation de l’interface NotificationPublisherAware afin de se faire injecter le NotificationPublisher par Spring.

JMX Notifier Service (client) :

public class JmxNotifierServiceImpl implements InitializingBean {
	
  private String objectName;
  private String url;
  private JMXConnector jmxConnector;
  private JmxNotifier notifier;
	
  public void afterPropertiesSet() {
    try {
      ObjectName objectName = new ObjectName(this.objectName);
      JMXServiceURL jmxUrl = new JMXServiceURL(this.url);
      this.jmxConnector = JMXConnectorFactory.connect(jmxUrl);
      MBeanServerConnection mbsc = this.jmxConnector.getMBeanServerConnection();

      this.notifier = (JmxNotifier)MBeanServerInvocationHandler.newProxyInstance(
                                                                                           mbsc,
                                                                                           objectName,
                                                                                           JmxNotifier.class,
                                                                                           false);
    } catch (MalformedObjectNameException e) {
      System.err.println("Warning : could not connect to 
                                     JMX server. JMX Notifications will not be sent.");
      System.err.println("Reason : " + e.getMessage());
    } catch (MalformedURLException e) {
      System.err.println("Warning : could not connect to
                                     JMX server. JMX Notifications will not be sent.");
      System.err.println("Reason : " + e.getMessage());
    } catch (IOException e) {
     System.err.println("Warning : could not connect to
                                     JMX server. JMX Notifications will not be sent.");
     System.err.println("It seems that remote server is
                                     not up and not running.");
    }
  }
}

  public void close() throws IOException {
    if ( this.jmxConnector != null ) {
      this.jmxConnector.close();
  }

  public void annonceDebu(String id) {
    if ( this.notifier != null ) {
      this.notifier.annonceDebut(id);
    }
  }
}

Une meilleure gestion des exceptions levées permettrait de gérer les cas où le serveur distant n’est pas disponible.

Côté serveur, il va vous falloir la configuration Spring suivante :

<context:annotation-config />

<bean id="jmxNotifier" class="JmxNotifierImpl" />

<bean id="registry" class="org.springframework.remoting.rmi.RmiRegistryFactoryBean" />

<bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean">
	<property name="locateExistingServerIfPossible" value="true" />
</bean>

<bean id="serverConnector" class="org.springframework.jmx.support.ConnectorServerFactoryBean">
  <property name="objectName" value="connector:name=rmi"/>
  <property name="serviceUrl" value="service:jmx:rmi://localhost/jndi/rmi://localhost:1099/standaloneJmxServer"/>
  <property name="threaded" value="true"/>
	<property name="daemon" value="true"/>
</bean>
  
<bean class="org.springframework.jmx.export.MBeanExporter" lazy-init="false">
	<property name="autodetect" value="true" />
	<property name="namingStrategy" ref="namingStrategy" />
	<property name="assembler" ref="assembler" />
</bean>

<bean id="attributeSource" class="org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource"/>

<bean id="assembler" class="org.springframework.jmx.export.assembler.MetadataMBeanInfoAssembler">
	<property name="attributeSource" ref="attributeSource" />
</bean>

<bean id="namingStrategy" class="org.springframework.jmx.export.naming.MetadataNamingStrategy">
	<property name="attributeSource" ref="attributeSource" />
</bean>

Les points marquants sont la présence de la MBeanServerFactory, la ConnectorServerFactoryBean et la RMIRegistryFactoryBean.

Et c’est tout !
Votre code n’a plus qu’à appeler JMXNotifierService.
Après, à vous d’enrichir les 2 JMX Notifier en fonction du fonctionnel de votre application.

Les équipes responsables du monitoring n’ont qu’à connecter leur JConsole sur la JVM contenant le MBeanServer.

Ce sample se divise en 2 parties :

• la 1ère montre un exemple de génération de document PDF from scratch.
• la 2ième partie va générer un document à partir d’un template que nous allons créer dans Open-Office.

Générer un document PDF ‘from scratch’ :

• 1ère étape : générer un projet Java.

Pour cela, utilisons la commande mvn archetype:generate et choisissons de créer un maven-archetype-quickstart.
Dans notre exemple, le projet est configuré comme suit :

  <groupId>fr.infinit.sample.generationpdf</groupId>
  <artifactId>generationpdf</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <name>Sample Generation PDF</name>

• 2ième étape : ajouter la dépendance Maven à iText.

Ajoutons le repository iText ainsi que la dépendance pour iText :

<repositories>
  <repository>
    <id>itextpdf.com</id>
    <name>Maven Repository for iText</name>
    <url>http://maven.itextpdf.com/</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>itextpdf</artifactId>
    <version>5.0.2</version>
    <scope>compile</scope>
  </dependency>
</dependencies>

• 3ième étape : Créer un document PDF vide.

Nous allons utiliser la classe com.itextpdf.text.Document :

    /**
     * Crée un Document vide.
     *
     * @param file Chemin du fichier à créer.
     * @return Document s'il n'y a pas eu d'erreur.
     * @throws IOException s'il y a eu une erreur avec le nom de fichier fourni.
     * @throws DocumentException s'il y a eu une erreur côté iText.
     */
    private Document creerDocument(String file) throws DocumentException, IOException {
        Document document = new Document();

        PdfWriter pdfWriter = PdfWriter.getInstance(document, new FileOutputStream(file));
        pdfWriter.setPageEvent(this);
        // Préférence de lecture : 2 pages en colonne.
        pdfWriter.setViewerPreferences(PdfWriter.PageLayoutTwoColumnLeft);
        document.open();

        return document;
    }

Attention à ne pas oublier de fermer l’objet Document après avoir travaillé sur cet objet !

• 4ième étape : Ajouter des informations Metadata.

L’ajout de ces informations se fait via la classe com.itextpdf.text.Document :

    /**
     * Ajout de données de type Metadata au document.
     *
     * @param document Document auquel il faut rajouter les metadatas.
     */
    private void addMetaData(Document document) {
        document.addTitle("Sample PDF");
        document.addSubject("Utilisant iText");
        document.addKeywords("Java, PDF, iText");
        document.addAuthor(System.getProperty("user.name"));
        document.addCreator(System.getProperty("user.name"));
    }

• 5ième étape : Ajouter des lignes vides.

L’ajout de lignes vides se fait en ajoutant des paragraphes avec des espaces :

    /**
     * Ajoute une ligne vide number fois dans le Paragraph passé en paramètre.
     *
     * @param paragraph A remplir avec les lignes vides.
     * @param number Nombre de lignes vides à ajouter.
     */
    private void ajouterLigneVide(Paragraph paragraph, int number) {
        for (int i = 0; i < number; i++) {
            paragraph.add(new Paragraph(" "));
        }
    }

• 6ième étape : Ajouter des paragraphes avec des polices différentes.

Commençons par définir différentes polices :

    /** Times Roman 18 Bold */
    private static final Font CATFONT = new Font(Font.getFamily("TIMES_ROMAN"), 18, Font.BOLD);

    /** Times Roman 12 Normal */
    private static final Font REDFONT = new Font(Font.getFamily("TIMES_ROMAN"), 12, Font.NORMAL);

    /** Times Roman 16 Bold */
    private static final Font SUBFONT = new Font(Font.getFamily("TIMES_ROMAN"), 16, Font.BOLD);

    /** Times Roman 12 Bold */
    private static final Font SMALLBOLD = new Font(Font.getFamily("TIMES_ROMAN"), 12, Font.BOLD);

Ensuite, ajoutons différents paragraphes à notre document :

    /**
     * Ajoute 4 paragraphes / - Titre du document. - Rapport généré par ... - Ce
     * document décrit ... - Ce document est ...
     *
     * @param document Document à enrichir
     * @throws DocumentException Si un problème survient lors de l'ajout des
     *             données.
     */
    private void addTitlePage(Document document) throws DocumentException {
        Paragraph preface = new Paragraph();

        // Ajout d'une ligne vide
        ajouterLigneVide(preface, 1);

        // Ecriture du header
        preface.add(new Paragraph("Titre du document", CATFONT));
        ajouterLigneVide(preface, 1);

        preface.add(new Paragraph("Rapport généré par: " + System.getProperty("user.name") + ", " + new Date(), SMALLBOLD));
        ajouterLigneVide(preface, 3);

        preface.add(new Paragraph("Ce document décrit quelque chose de très important ", SMALLBOLD));
        ajouterLigneVide(preface, 8);

        preface.add(new Paragraph("Ce document est une version préliminaire et n'est sujet à aucune restriction.", REDFONT));
        document.add(preface);

        // Debut d'une nouvelle page
        document.newPage();
    }

• 7ième étape : Ajouter du contenu (Chapitre, Section, Sous-section, Anchor).

Les objets Anchor, Chapter, Section permettent de définir différentes zones de contenu dans un document.

Anchor anchor = new Anchor("Premier Chapitre", CATFONT);
anchor.setName("Premier Chapitre");

// Le 2ième paramètre est le numero du chapitre
Chapter catPart = new Chapter(new Paragraph(anchor), 1);

Paragraph subPara = new Paragraph("Sous-Catégorie 1", SUBFONT);
Section subCatPart = catPart.addSection(subPara);
subCatPart.add(new Paragraph("Coucou (pour ne pas mettre toto...)."));

subPara = new Paragraph("Sous-catégorie 2", SUBFONT);
subCatPart = catPart.addSection(subPara);
subCatPart.add(new Paragraph("Paragraphe 1"));
subCatPart.add(new Paragraph("Paragraphe 2"));
subCatPart.add(new Paragraph("Paragraphe 3"));

• 8ième étape : Ajouter un tableau.

Un tableau se créé avec la classe com.itextpdf.text.pdf.PdfPTable.
Il se compose de com.itextpdf.text.pdf.PdfPCell :

/**
 * Crée un tableau de 3 colonnes et l'ajoute à la Section passée en
 * paramètre.
 * 
 * @param subCatPart Section à remplir avec le tableau.
 * @throws BadElementException Si une erreur survient lors de l'ajout d'un
 *             élément dans la PdfPTable.
 */
private void createTable(Section subCatPart) throws BadElementException {
    // Creation d'une PdfPTable avec 3 colonnes
    final PdfPTable table = new PdfPTable(3);

    // Creation d'une PdfPCell avec un paragraphe
    final PdfPCell cell = new PdfPCell(new Paragraph("header with colspan 3"));

    // Changement du colspan de la PdfCell
    cell.setColspan(3);

    // Ajout de la PdfCell custom à la PdfPTable
    table.addCell(cell);

    // Ajout d'objets String à la PdfPTable
    table.addCell("1.1");
    table.addCell("2.1");
    table.addCell("3.1");
    table.addCell("1.2");
    table.addCell("2.2");
    table.addCell("3.2");

    // Ajout d'un espace entre la PdfPTable et l'élément précédent.
    table.setSpacingBefore(15f);

    subCatPart.add(table);
}

• 9ième étape : Ajouter une liste à puce.

Une liste à puce dans un document PDF se créé avec l’objet com.itextpdf.text.List.
En voici un exemple :

/**
 * Crée une liste et l'ajoute dans la Section passée en paramètre.
 * 
 * @param subCatPart Section à remplir avec la liste.
 */
private void createList(Section subCatPart) {
    final List list = new List(true, false, 10);
    list.add(new ListItem("Premier point"));
    list.add(new ListItem("Deuxième point"));
    list.add(new ListItem("Troisième point"));
    subCatPart.add(list);
}

• 10ième étape : Ajouter des numéros de pages.

L’ajout des numéros de page se fait en utilisant la classe com.itextpdf.text.pdf.PdfPageEventHelper.
Elle s’utilise en l’ajoutant comme PageEvent sur le PdfWriter (méthode setPageEvent).
Il suffit ensuite de surcharger les méthodes que l’on souhaite utiliser : onOpenDocument, onEndPage, etc…

Dans notre exemple, la méthode onOpenDocument est utilisée pour créer un com.itextpdf.text.pdf.PdfTemplate qui contiendra le texte des numéros de page.

/**
 * Création du template destiné à recevoir les numéros de page.
 * 
 * @param writer PdfWriter à utiliser.
 * @param document Document à enrichir.
 */
@Override
public void onOpenDocument(PdfWriter writer, Document document) {
    total = writer.getDirectContent().createTemplate(100, 100);
    total.setBoundingBox(new Rectangle(-20, -20, 100, 100));
    try {
        helv = BaseFont.createFont(BaseFont.HELVETICA, BaseFont.WINANSI, BaseFont.NOT_EMBEDDED);
    } catch (DocumentException e) {
        LOG.error(e.getMessage(), e);
        // TODO : gérer l'exception.
    } catch (IOException e) {
        LOG.error(e.getMessage(), e);
        // TODO : gérer l'exception.
    }
}

Note : total est un com.itextpdf.text.pdf.PdfTemplate.

La méthode onEndPage est responsable du remplissage du PdfTemplate pour chaque page via un com.itextpdf.text.pdf.PdfContentByte.

Dans l’exemple suivant, les numéros de page paires sont écrits en bas à gauche et les impaires sont écrits en bas à droite :

/**
 * Ajoute des numeros de page automatiquement. Les numeros paires sont mis
 * en bas à gauche. Les numéros impaires sont mis en bas à droite.
 * 
 * @param writer Pdfwriter à utiliser.
 * @param document Document à utiliser.
 */
@Override
public void onEndPage(PdfWriter writer, Document document) {
    LOG.info("Generation des numeros de page ...");
    final PdfContentByte directcontent = writer.getDirectContent();

    directcontent.saveState();
    final String text = "Page " + writer.getPageNumber();
    final float textBase = document.bottom() - 20;
    final float textSize = helv.getWidthPoint(text, 12);

    directcontent.beginText();
    directcontent.setFontAndSize(helv, 11);

    // Ecriture du numero de page a gauche pour les pages impaires.
    if ((writer.getPageNumber() % 2) == 1) {
        directcontent.setTextMatrix(document.left(), textBase);
        directcontent.showText(text);
        directcontent.endText();
        directcontent.addTemplate(total, document.left() + textSize, textBase);
    } else {
        // Ecriture du numero de page a droite pour les pages paires.
        final float adjust = helv.getWidthPoint("0", 12);
        directcontent.setTextMatrix(document.right() - textSize - adjust, textBase);
        directcontent.showText(text);
        directcontent.endText();
        directcontent.addTemplate(total, document.right() - adjust, textBase);
    }
    directcontent.restoreState();
}