Annotation Processing: @​Nailed("it")

Hands-On Devoxx 2015

• Installation de l’environnement
  • Prérequis
  • Récupérer les sources
  • Installer Java 8
  • Installer Maven
  • Ouvrir les README
• Structure du Hands-on
  • 3 niveaux
  • une présentation et des exercices
  • un README
  • philosophie
  • documentation
• Let’s dive in !

Ceci est le support du Hands-On de Devoxx France 2015 intitulé Annotation Processing: @​Nailed("it") créé par Florent Biville et Sébastien Lesaint.

Installation de l’environnement

Prérequis

1. un terminal

2. Java 8

3. Maven 3.1.1 ou 3.2.5 ou 3.3.1

4. l’IDE de votre choix

Récupérer les sources

Pour suivre ce hands-on, vous avez besoin des sources. Vous pouvez les récupérer :

1. en faisant un clone du répository Git sur GitHub

   $ mkdir ~/devoxx_2015
   $ git clone https://github.com/fbiville/annotation-processing-ftw.git ~/devoxx_2015/annotation-processing-ftw

2. en copiant le repértoire annotation-processing-ftw présent sur la clé USB

Installer Java 8

Sur la clé USB, vous trouverez dans le répertoire binaries les fichiers d’installation pour :

• linux 32 bits (jdk-8u40-linux-i586.tar.gz) ou 64 bits (jdk-8u40-linux-x64.tar.gz)

  • créez un répertoire pour Java (par exemple ~/java)

    $ mkdir ~/java

  • décompressez l’archive pour votre architecture, dans votre répertoire d’installation

    $ cp [chemin_vers_votre_copie_des_sources_du_hands-on]/binaries/jdk-8u40-linux-[votre_archi].tar.gz ~/java
    $ cd ~/java
    $ tar xvfz jdk-8u40-linux-[votre_archi].tar.gz

  • ajoutez le répertoire bin de Java à votre PATH

    • de façon temporaire

      $ export JAVA_HOME="~/java/jdk1.8.0_40" && export PATH="$JAVA_HOME/bin:$PATH"

    • de façon définitive en modifiant votre fichier .bashrc ou .zshrc

      $ cp ~/.bashrc ~/.bashrc_save
      $ echo "export JAVA_HOME=\"~/java/jdk1.8.0_40\"" >> ~/.bashrc
      $ echo "export PATH=\"$JAVA_HOME/bin:$PATH\"" >> ~/.bashrc

• Mac OS (jdk-8u40-macosx-x64.dmg)

  • double-cliquez sur le fichier et suivez les écrans d’installation

  • si vous aviez déjà un JDK d’une version antérieure installé précédemment, assurez-vous d’exécuter :

    • de façon temporaire

      $ export JAVA_HOME="/Library/Java/JavaVirtualMachines/jdk1.8.0_40.jdk" && export PATH="$JAVA_HOME/bin:$PATH"

    • de façon définitive en modifiant votre fichier .bashrc ou .zshrc

• Windows 32 bits (jdk-8u40-windows-i586.exe) ou 64 bits (jdk-8u40-windows-x64.exe)

  • lancez le .exe qui correspond à votre architecture et suivez les instructions de l’installeur (prenez garde à ne pas installer Ask)

Installer Maven

Sur la clé USB, vous trouverez dans le répertoire binaries les fichiers d’installation pour Maven 3.3.1 (apache-maven-3.3.1-bin.zip) mais aussi pour Maven 3.2.5 et 3.1.1 qui sont présents pour votre divertissement.

Installation sous Linux & Mac OS

• créez un répertoire pour Maven (par exemple ~/maven)

  $ mkdir ~/maven

• décompressez l’archive apache-maven-3.3.1-bin.zip, dans votre répertoire d’installation

  $ cp [chemin_vers_votre_copie_des_sources_du_hands-on]/binaries/apache-maven-3.3.1-bin.zip ~/maven
  $ cd ~/maven
  $ unzip apache-maven-3.3.1-bin.zip

• ajoutez le répertoire bin de Maven à votre PATH et définissez la variable globale M2_HOME

  • de façon temporaire

    $ export M2_HOME="~/maven/apache-maven-3.3.1" && export PATH="$M2_HOME/bin:$PATH"

  • de façon définitive en modifiant votre fichier .bashrc ou .zshrc

    $ cp ~/.bashrc ~/.bashrc_save
    $ echo "export M2_HOME=\"~/maven/apache-maven-3.3.1\"" >> ~/.bashrc
    $ echo "export PATH=\"$M2_HOME/bin:$PATH\"" >> ~/.bashrc

Installation sous Windows

• décompressez l’archive apache-maven-3.3.1-bin.zip, dans votre répertoire d’installation (e.g. C:\Program Files\)

• exportez C:\Program Files\apache-maven-3.3.1 (ou équivalent) dans Path (pour y accéder : clic-droit sur Ordinateur dans le menu démarrer puis "Paramètres avancés")

• démarrez un terminal (saisissez cmd.exe dans le menu démarrer) et exécutez mvn -version pour vérifier que votre configuration fonctionne

Utiliser le repo fourni

Sur la clé USB fournie, vous trouverez un repository Maven préalimenté avec les dépendances nécessaires pour résoudre les exercices.

Pour l’utiliser, il suffit de créer/modifier le fichier ${user.home}/.m2/settings.xml de votre compte utilisateur pour pointer vers votre copie de ce repository.

<?xml version="1.0" encoding="UTF-8"?>

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository>[path_vers_votre_copie_du_contenu_de_la_clé_USB]/maven/repository</localRepository>

  <!-- whatever -->

</settings>

Ouvrir les README

Pour suivre ce hands-on, suivez les instructions présentées dans les fichiers README.html.

1. ouvrez le README.html (oui, oui, la page que vous êtes en train de lire) à la racine du repo dans votre navigateur

2. ouvrez le README.html du répertoire doc dans un autre onglet

   • nous vous fournissons les documentations qui vous permettront de résoudre la plupart des exercices

   • régulièrement, nous vous orienterons même vers la bonne documentation (trop sympa)

Structure du Hands-on

3 niveaux

Ce hands-on est structuré en 3 niveaux. Ceux-ci vont progressivement vous amener à apprécier les capacités des annotation processors et de leurs usages.

une présentation et des exercices

Chaque niveau est précédé d’une courte présentation (5 à 10 minutes max) et découpé en plusieurs exercices. Chacun se réalise en quelques étapes successives.

un README

Chaque niveau possède un README.asciidoc et un README.html qui décrit les exercices et les étapes. Il est à nouveau conseillé de visualiser la version HTML en local (meilleur rendu) que le rendu du ASCIIDOC sur GitHub.

L’essentiel de l’information qui vous permettra de compléter les exercices se trouve dans le README:

• objectif du niveau

• objectif, structure de répertoire et description de chaque exercice

• objectif de chaque étape

• actions à réaliser, celles-ci sont spécifiquement identifiées par des blocs de la forme suivante :

  Important

  Dans la classe InjectedPropertyProcessor, implémentez la méthode process.

• extraits de documentation et indications vers la solution

Le niveau 2 fait exception car vous trouverez beaucoup plus d’informations dans la javadoc. Dans le cas de ce niveau, c’était beaucoup plus pertinent.

philosophie

Les niveaux sont conçus de manière assez directive: ceux-ci comportent de nombreux problèmes mais les solutions sont courtes. On pourrait parler d’exercices unitaires.

Si vous vous retrouvez à écrire plus de 50 lignes de code, levez la main, vous faites probablement fausse route et nos indications n’étaient probablement pas assez bonnes.

L’objectif est de faire découvrir le traitement d’annotation par petits lots, qui, enchaînés les uns aux autres, vous en donneront une vision d’ensemble. On en profite au passage pour vous diriger vers la solution la plus efficace, celle promulguée par les concepteurs de l’API.

documentation

Nous vous fournissons hors-ligne les documentations qui vous permettront de résoudre la plupart des exercices. Bien évidemment, rien ne vous empêche de les consulter en ligne ou même d’utiliser Google.

Le README du répertoire doc vous permettra d’accéder facilement à chaque documentation (en ligne et hors-ligne) et propose même quelques raccourcis vers les documentations indispensables.

Let’s dive in !

Niveau 1

Comprendre les bases et mettre les mains dans le cambouis : html local ou Asciidoc GitHub

Niveau 2

Comprendre le modèle des sources Java : html local ou Asciidoc GitHub

Niveau 3

Générer des erreurs de compilation et des fichiers : html local ou Asciidoc GitHub