WadRobotFramework : les robots Wave faciles

Cet article va vous apprendre à utiliser le WadRobotFramework (WRF) pour créer des robots destinés à Google Wave avec un minimum d'efforts.

Il n'a pas pour vocation d'expliquer l'utilisation de Google Wave.

WRF vous permettra d'écrire un robot simple en moins de cinq minutes.

Google Wave est un système de collaboration permettant une communication instantanée entre les participants. Ces participants pouvant être humains ou non.

Dans ce dernier cas, l'on nomme robots des programmes exécutés côté serveur, qui peuvent réagir à différents évènements d'une conversation.

Google fournit une API pour écrire des robots en Java (et en Python).

Un robot est un sous-ensemble d'une application Web, répondant à une URL établie.

Le mois de mars 2010 a vu arriver la v2 de l'API Java. Wave étant toujours un outil récent, son API n'est pas figée et susceptible de changements d'importance. Le WadRobotFramework est compatible avec cette nouvelle API. Les deux versions de l'API Robots de Google cohabiteront jusqu'au 30 juin 2010. Après cette date, seule la v2 sera utilisable en ligne.

Pour décrire Wave à l'emporte-pièce, disons que c'est un grand forum mondial qui possède des fonctionnalités proches de la messagerie instantanée et de la messagerie classique (e-mail). De ce fait, ce mélange novateur possède son propre vocabulaire.

La Wave, c'est le forum, chaque fil (thread) est nommé wavelet, et se compose de blips. Chaque wavelet possède un ou plusieurs participants, ce sont soit des humains soit des robots.

Incroyablement novateur non ? A première vue, non, mais notons pour ultérieurement la possibilité d'ajouter des gadgets dans une conversation, ce qui ouvre un large panorama de possibilités.

Les pré requis pour pouvoir utiliser le WRF sont les mêmes que ceux pour l'API de Google.

• Avoir accès à Google Wave (Depuis la conférence Google IO, GW est ouvert à tous sur inscription)
• Avoir un compte développeur sur App Engine Java
• Pouvoir y créer une application
• Disposer d'Eclipse et du plugin Google
• Télécharger l'API Google

Lors de Google I/O 2010, outre l'ouverture à tous et l'intégration à l'offre Google Apps Entreprise, il a été annoncé que désormais, les robots pour GW pourraient être hébergés en dehors de Google App Engine (GAE). Dans cet article, ce ne sera pas le cas.

La méthode pour écrire des robots est extrêmement bien décrite dans le tutoriel publié à cette adresse
http://code.google.com/intl/fr-FR/apis/wave/extensions/robots/java-tutorial.html

V-A. Exemple de code standard▲

package parroty;

import com.google.wave.api.*;
import com.google.wave.api.event.*;

public class ParrotyServlet extends AbstractRobot {

  @Override
  protected String getRobotName() {
    return "Parroty";
  }

  @Override
  protected String getRobotAvatarUrl() {
    return "http://code.google.com/apis/wave/extensions/robots/images/robot_avatar.png";
  }

  @Override
  protected String getRobotProfilePageUrl() {
    return "http://code.google.com/apis/wave/extensions/robots/java-tutorial.html";
  }

  @Override
  public void onWaveletSelfAdded(WaveletSelfAddedEvent event) {
    Blip blip = event.getWavelet().reply("\nHi everybody!");
  }

  @Override
  public void onWaveletParticipantsChanged(WaveletParticipantsChangedEvent event) {
    for (String newParticipant: event.getParticipantsAdded()) {
      Blip blip = event.getWavelet().reply("\nHi : " + newParticipant);
    }
  }
}

import org.wadael.waverobotfrmwrk.simple.BlipModifierRobot;
/**
 * Example robot that adds RTFM!! after each question mark.
 * It assumes there is a manual for the conversation's themes.
 * 
 * @author jerome baton : Wadael, http://blog.wadael.org
 */
@SuppressWarnings("serial")
public class RTFMRobotServlet extends BlipModifierRobot {
    @Override
    protected String modifyBlipText(String actualText)  {
        if(actualText.indexOf("?") == -1) return null;
        else {
           return actualText.replaceAll("?", "? (RTFM!!") ;
             }
        }
}

VI-A. Principe▲

VI-B. Historique▲

VI-C. API spécifique▲

VI-D. Générateur▲

Pour utiliser le générateur, il est préférable de d'abord le configurer.

VII-A. Configuration du générateur▲

VII-B. Exécuter le générateur▲

WRF définit plusieurs types de robots. A ce jour, il existe trois types de robots dont deux types simples et un type avancé.

VIII-A. Robots simples (RS)▲

protected abstract String modifyBlipText(String actualText) ;

protected abstract String getTextToAppend(String textOfTheBlipToReactFrom);

VIII-B. Robots avancés (RA)▲

public interface RobotWorker {
    /**
     * Returns a string identifying an instruction delimiting the scope of this robot.
     * Can be null, so that the worker is executed whatever the instruction. 
     */
    public String getInstruction();
    
    /**
     * Returns a description of the instruction's behaviour.
     * This description is used when the robot's usage is displayed. 
     * @return
     */
    public String getDescription();
    
    /**
     *  Entry-point for a worker.
     * You get all the objects you can use.
     * 
     * @param bundle
     * @param blip
     * @param event
     * @param parameters may be null
     * @return
     * 
     */
    public boolean doWork(RobotMessageBundle bundle, Blip blip, Event event, String parameters);
}
....

 package org.wadael.generated.advRobot.advAppender; 

import org.wadael.waverobotfrmwrk.advanced.RobotWorker; 
import org.wadael.waverobotfrmwrk.advanced.WithWorkersRobot; 
 
import com.google.wave.api.Blip; 
import com.google.wave.api.Event; 
import com.google.wave.api.RobotMessageBundle; 
/** 
 * AdvAppenderExample 
 * 
 * @author generated by the WadRobotFramework 
 * 
 */ 
@SuppressWarnings("serial") 
public class ExampleAjouteurAvanceServlet extends WithWorkersRobot { 

    public ExampleAjouteurAvanceServlet(){ 
        super(); 
        /* On ajoute ici le ou les workers */ 
        addRobotWorker( new LengthWorker() ); 
        addRobotWorker( new CapitalWorker() ); 
    } 
     
    @Override 
    public String getRobotIdentifier() { 
        return "RA"; 
        /* un identifiant identifie un RA dans une conversation, car il peut y en avoir plusieurs. 
        ASTUCE : FAIRE COURT ! 
        */ 
    } 

    @Override 
    protected String getRobotSelfIntroduction() { 
        /* TODO Renvoyer le texte retourné par le robot quand il est ajouté à une conversation */ 
        return "Salutations."; 
    } 
     
    @Override 
    protected String getDisplayName() { 
        return "Robot avancé d'exemple pour Developpez.com"; 
    } 
} 


/*  
    Premier worker 
*/ 
public class LengthWorker implements RobotWorker { 
    @Override 
    public String getInstruction() { 
        return "taille"; 
    } 

    @Override 
    public String getDescription() { 
        return "Affiche la taille du blip."; 
    } 

    @Override 
    public boolean doWork(RobotMessageBundle bun, Blip bli, Event eve,String params) 
    {     
        Blip lengthChild = bli.createChild(); 
        lengthChild.getDocument().append("taille : " + bli.getDocument().getText().length() + " caractères"); 
        return true; 
    } 
} 

/*  
    Deuxieme worker 
*/ 
public class CapitalWorker implements RobotWorker { 
    @Override 
    public String getInstruction() { 
        return "capi"; 
    } 

    @Override 
    public String getDescription() { 
        return "Capitalise le texte du blip"; 
    } 

    @Override 
    public boolean doWork(RobotMessageBundle bun, Blip bli, Event eve,String params) 
    {     
        Blip lengthChild = bli.createChild(); 
        String capiTexte = bli.getDocument().getText().toUpperCase(); 
        lengthChild.getDocument().replace(capiTexte); 
        return true; 
    } 
}

Pour continuer ce tutoriel, il est temps d'abandonner la théorie pour passer à la pratique et créer un robot via le générateur.

Le point de départ est que tous les pré-requis sont satisfaits. Sous Eclipse, vous avez donc un project WadRobotFramework ouvert, créé à partir d'une archive ZIP récupérée sur le site.

1/ Adapter le fichier build.properties

2/ Configurer le générateur pour un résultat personnalisé, en adaptant le fichier generator/generator.properties

3/ Choisir un type de robot

4/ Lancer la tache Ant voulue (revoir le paragraphe 7)

Après ces quatre premières étapes, vous verrez dans la console d'Eclipse un message vous indiquant où trouver le squelette de robot généré.

Votre écran ressemble à la capture ci-dessous.

Le projet du robot que vous venez de créer se trouve dans generated_Robots. Il faut maintenant créer un nouveau projet pour votre robot afin qu'il soit pris en compte dans votre workspace.

Si votre Eclipse est en anglais, faites un clic droit dans la partie " Package Explorer " (à gauche) et choisissez " Import ". Puis " Existing project into workspace ", comme sur la capture ci-dessous.

Choisissez en " root directory " la racine du répertoire de votre robot fraichement généré.

L'astuce est de cocher la case "Copy projects into workspace". Cela permet de dupliquer l'arborescence (qui est générée dans $WRF_HOME$/generated_robots) à l'endroit voulu du workspace.

Ci-dessus, choix du répertoire "racine" du robot généré.

Dans cet exemple, mon robot était nommé "dev" comme on peut le voir dans la zone "Projects".

En cliquant sur "Finish", vous avez désormais votre projet de robot prêt à être terminé puis déployé. Le déployement se fait comme pour les autres applications web à la Google, à savoir qu'il est initié par le bouton à l'icone d'avion.

J'ai réalisé une vidéo de l'utilisation du générateur, vous la trouverez à l'adresse suivante :
https://www.youtube.com/watch?v=sdcPWz5ILEY

Que va-t'il se passer pour le WRF dans l'avenir ?

Pour répondre à cette question, le wiki possede une page WhatsNext sur laquelle j'essaie de centraliser les différents points qui seront traités ultérieurement, qu'ils soient des ajouts ou des modifications.

De nouvelles fonctionnalités seront ajoutées, parmi lesquelles :

• ne répondre qu'à une liste limitée d'utilisateurs (mise en place souscription)
• les commandes d'administration correspondantes
• générer des bots XMPP (utilisables dans Google Chat) et des robots ajouteurs en même temps (avec le même code métier) via un nouveau type de robot.
• Effacer les commandes (ou non) des blips
• Éventuellement, intégrer de nouveaux développeurs sur le projet.
• la création d'un nouveau type de robot (schizophrène)

Inscrivez-vous au groupe pour avoir des informations fraîches et/ou poser des questions.

Utilisez SVN plutôt que les distributions car une fois que vous aurez créé un projet WadRobotFramework dans votre workspace, il sera si simple de mettre WRF à jour.

Le framework : http://code.google.com/p/wadrobotframework

Tutoriels en anglais, par Romin Irani :

• http://googlewaveexperiments.wordpress.com/2010/05/15/episode-2-writing-a-wave-robot-using-wadrobotframework/ (sans utiliser le générateur)
• http://gaejexperiments.wordpress.com/2009/12/03/episode-12-writing-an-advanced-google-wave-robot-using-wadrobotframework/

Je pense devoir préciser que Romin est un ami, mais cela ne change en rien la qualité de ses tutoriaux. Il a publié un PDF regroupant l'ensemble des tutoriels (en anglais) qu'il a écrit sur Google App Engine et ses APIs.
Ce PDF est disponible à l'adresse suivante :
http://gaejexperiments.wordpress.com/gaej-experiments-ebook/

Liste des articles sur la programmation Wave :
http://code.google.com/intl/fr/apis/wave/articles.html

Ma présentation sur la v1 de WRF (partiellement périmée):
https://www.slideshare.net/wadael/wad-robot-framework-pour-jump-camp4-it

Mon site : http://www.wadael.org

Mon Twitter : http://twitter.com/wadael

A vos commentaires sur le forum 3 commentaires

Je remercie chaleureusement Wachter d'avoir effectué la relecture de cet article, ainsi que l'équipe de la rédaction de Developpez.com, Eric Siber, Caro-Line, Ricky81 et Hornetbzz pour leur accueil et leur aide.