[MAJ Décembre 2020] Vous voilà donc avec votre beau BlueMind flambant neuf. Vous avez entendu parler de notre grand plan d’architecture, des possibilités d’extension, de la plateforme p2, de l’API REST, mais vous ne savez pas par où commencer. Réjouissez-vous ! Cet article a été écrit pour vous !
Il vous faut juste connaître un peu de java et être plus ou moins familier avec Maven.
Objectif : une simple tâche planifiée.
Notre add-on sera une tâche planifiée.
Vous pouvez voir le gestionnaire des tâches de BlueMind comme un CRON interne, qui va exécuter les tâches au moment où elles sont programmées, ce qui est plutôt pratique pour vous assister dans l’administration de votre serveur.
Cette tâche va seulement loguer quelques statistiques – en gros, nous allons seulement réaliser une coquille (presque) vide pour montrer comment faire tourner les briques de l’API REST. Faire quelque chose de plus significatif vous sera laissé comme exercice 🙂
Votre tâche planifiée listera les appareils mobiles de tous les utilisateurs pour tous les domaines gérés par votre serveur BlueMind. Nous l’appellerons MobileDevicesListingJob.
Prudence est mère de sûreté
N’oubliez pas que lorsque vous utilisez l’API REST avec un serveur BlueMind, vous traitez de vraies données d’utilisateurs et il est plutôt facile de faire des erreurs puisque tout ce que vous pouvez faire dans BlueMind peut être fait via l’API REST. Il n’y aura pas d’écran de confirmation comme lorsque vous utilisez la console d’administration : si vous avez un doute, alors ne faites pas. Mais comme vous utilisez certainement un environnement de développement, je n’ai aucune crainte ! Quoi qu’il en soit, nous ne modifierons pas de données dans ce tutoriel.
Amorcer un projet maven
Si vous jetez un coup d’œil aux entrailles de BlueMind, vous verrez des bundles OSGi partout, plus précisément la variante eclipse/equinox.
BlueMind publie pour toutes ses releases une « target-platform » qui comprend tous les outils nécessaires pour s’intégrer avec votre serveur de messagerie favori : votre librairie va donc aller piocher ses dépendances dans cette plateforme cible. La dernière version publiée est disponible sous forme de dépôt p2 à l’adresse suivante : http://pkg.blue-mind.net/p2/latest/
Cette URL est bien pratique, mais afin de ne pas construire sur du sable je vous conseille d’utiliser le numéro technique de la version de BlueMind que vous utilisez plutôt que latest (soit http://pkg.blue-mind.net/p2/4.1.51252/ au moment de la révision de cet article). Le numéro technique est celui que portent les paquets de votre installation, et il est différent du numéro commercial d’une release (ici 4.3.16 pour la 4.1.51252).
Mais ?!? Comment utiliser ce dépôt depuis mon projet maven ? Excellente question ! C’est précisément l’objectif de Tycho, qui fait la jonction entre les univers maven et eclipse/equinox.
Vous trouverez ici la structure du projet de base. Téléchargez-la et extrayez l’archive quelque part. Ce projet est réduit au strict minimum. Je ne vais pas rentrer dans les détails des fichiers de configuration, vu qu’ils ne sont pas spécifiques à BlueMind, mais je voudrais souligner deux points :
- pom.xml est le fichier de configuration maven que vous connaissez certainement déjà. Il contient la déclaration de l’emplacement de la plateforme cible de BlueMind, que je vous suggère de modifier afin de remplacer la version par le numéro technique qui vous intéresse. La configuration de tycho est incluse.
- plugin.xml contient la déclaration du point d’extension que nous utiliserons, soit scheduledjob_provider, avec le nom de notre future classe java : org.example.mobiledeviceslistingjob.MobileDevicesListingJob
Le reste n’est que de la configuration standard.
Dans le répertoire du projet, vous pouvez lancer :
mvn install
Et voilà !
Vous avez construit votre projet ! Vous pouvez le déployer dans votre BlueMind, mais il ne se passera rien pour le moment, et pour cause : il n’y a pas encore de code.
Eclipse à la rescousse
Vous pouvez évidemment écrire votre code java avec votre éditeur favori et compiler le code comme indiqué en ligne de commande. Eclipse a cependant quelques arguments à faire valoir pour travailler sur ce genre de projet, voici donc quelques instructions spécifiques :
- Importez votre projet maven dans votre espace de travail
- Indiquez à Eclipse la plateforme cible de BlueMind : allez dans Preferences, cherchez « Target Platform » et ajoutez une nouvelle définition de plateforme cible. Vous devez commencer avec une définition de cible vierge, choisissez un nom (par exemple tout simplement « BM target platform ») puis ajouter l’URL indiquée précédemment comme nouveau Software Site :
(Attention encore une fois à remplacer latest par le numéro technique de préférence !)
Sélectionnez tout (les cases « Uncategorized » dans l’écran ci-dessus), cliquez sur Finish et c’est fini ! Attention, vous devez sélectionner la plateforme cible que nous venons de créer avant de fermer la fenêtre Preferences.
Mettre en place les dépendances
Nous devons déclarer quelles parties de la plateforme cible de BlueMind nous utiliserons effectivement dans le fichier MANIFEST.MF. Notre documentation en ligne de l’API REST vous aidera à sélectionner les parties dont vous aurez besoin. Si vous avez installé le paquet optionnel bm-docs et donné la permission Api docs à votre utilisateur, cette documentation est directement accessible dans BlueMind :
Cerise sur le gâteau : cette documentation en ligne est interactive, ainsi vous pouvez exécuter les appels depuis le client javascript. Attention, l’avertissement précédent concernant la perte possible de données s’applique toujours ! Et les dégâts que vous pourrez faire dépendront des droits accordés à l’utilisateur connecté.
Voici les dépendances dont vous aurez besoin, ajoutez simplement ces lignes à la fin du fichier META-INF/MANIFEST.MF :
Require-Bundle: net.bluemind.domain.api, net.bluemind.user.api, net.bluemind.device.api, net.bluemind.scheduledjob.scheduler, net.bluemind.core.rest, slf4j.api
- net.bluemind.*.api : les APIs REST servant à explorer les domaines, utilisateurs et appareils mobiles
- net.bluemind.scheduledjob.scheduler : pour bénéficier des fonctionnalités des tâches planifiées
- net.bluemind.core.rest : nécessaire à la mécanique d’authentification des appels à l’API REST
- slf4j.api : « façade » pour le logging, utilisée partout dans BlueMind
Premiers pas avec l’API REST
Créons donc la classe que nous avons déclarée dans plugin.xml : org.example.mobiledeviceslistingjob.MobileDevicesListingJob. Elle doit implémenter IScheduledJob pour scheduledjob_provider pour pouvoir se brancher dessus. Voici le code complet, je copie ici la logique métier seulement :
// logger will write in bm core logs (/var/log/bm/core.log)
logger.info("Executing MobileDevicesListingJob");
// sched will write in the execution report, that you can send by mail in the Job setup UI
sched.info(slot, "en", "Collecting mobile devices data for all users...\n");
// write header row for the data to come
sched.info(slot, "en", "device; isWipe; lastSync; user; domain");
// initialize client for domain service
IDomains domainService = ServerSideServiceProvider.getProvider(SecurityContext.SYSTEM)
.instance(IDomains.class);
// loop on all domains
domainService.all().stream().forEach(domain -> {
// initialize client for user service
IUser userService = ServerSideServiceProvider.getProvider(SecurityContext.SYSTEM)
.instance(IUser.class, domain.uid);
// loop on all users
userService.allUids().stream().forEach(userUID -> {
// grab full details for user
ItemValue<User> user = userService.getComplete(userUID);
// initialize device service for each user
try {
IDevice deviceService = ServerSideServiceProvider.getProvider(SecurityContext.SYSTEM)
.instance(IDevice.class, userUID);
// loop on all devices
deviceService.list().values.stream().forEach(device -> {
// collect info for this device
List<String> deviceInfo = new ArrayList<>();
deviceInfo.add(device.displayName);
deviceInfo.add(Boolean.toString(device.value.isWipe));
deviceInfo.add(device.value.lastSync.toString());
deviceInfo.add(user.displayName);
deviceInfo.add(domain.displayName);
// write a line in the report
sched.info(slot, "en", String.join("; ", deviceInfo));
});;
} catch (ServerFault exception){
// Skipping this user since she doesn't have a "device" container
}
});
});
Déployer dans votre serveur BlueMind
Compilez votre code :
mvn clean install
Puis déposez le jar produit (target/org.example.mobiledeviceslistingjob-1.0.0-SNAPSHOT.jar) dans le dossier /usr/share/bm-core/extensions de votre serveur BlueMind.
Enfin, redémarrez le service bm-core :
/etc/init.d/bm-core restart
Votre tâche devrait apparaître parmi les tâches planifiées de la console d’administration. Vous pouvez l’exécuter, la programmer, envoyer le rapport à votre meilleur ami, elle est à vous !
Avertissement : si vous devez recompiler/redéployer votre extension, vous aurez peut-être besoin d’effacer le cache de bm-core pour vous assurer que la dernière version du jar est utilisée :
rm -Rf /var/lib/bm-core
bluemind-samples et bluemind itself
Afin d’enrichir fonctionnellement votre add-on, quoi de mieux que de piocher dans des exemples existants ? Un bon point de départ est le projet bluemind-samples, disponible ici. Last but not least, le code source de BlueMind lui-même peut vous donner des idées.
Parler REST depuis le monde extérieur
Vous avez remarqué que nous avons utilisé un fournisseur de service ServerSideServiceProvider pour initialiser les services de l’API REST, mais vous pouvez bien sûr parler REST depuis l’extérieur, par exemple en utilisant un client python. Pour cela il vous faudra une clef d’API BlueMind.
Partagez votre travail !
Vous n’avez fait que le premier pas. Lorsque vous aurez concrétisé vos idées et serez prêt à partager le second, le MarketPlace BlueMind est la destination tout indiquée. Nous attendons avec impatience vos contributions !
