Table des matières
1      Présentation du squelette d’application
2      Configuration du squelette
2.1         Fichier de configuration Maven (pom.xml)
2.2         Fichier de propriétés Open the Box (src/main/resources/OSGI-INF/otb.properties)
2.3         Fichier de configuration Declarative Services (src/main/resources/OSGI-INF/component-devices.xml)
3      Code Java
4      IHM

1 Présentation du squelette d’application

Le fichier template.zip ci-joint contient le squelette complet d’une application Open the Box, permettant au lecteur de construire sa propre application en partant de celle-ci (le projet est pré-installé dans le workspace Eclipse de la VM Open the Box).

Nous présenterons dans un premier temps les quelques modifications de configuration qui doivent être apportées (noms & titres par exemple), puis nous décrirons le code existant.

La page Guide du développeur fournit une présentation complète et de référence du concept d’application Open the Box.

2 Configuration du squelette

2.1 Fichier de configuration Maven (pom.xml)

Nous n’allons pas détailler entièrement ce fichier, notons simplement qu’il est nécessaire d’en modifier certains champs :

<artifactId> donne l’identifiant de l’application (et du jar/bundle qui sera construit).
<name> donne le nom de l’application.
La section maven-bundle-plugin contient les instructions qui serviront à construire un bundle, au sens OSGi, et notamment un manifeste adéquat :
- <plugin/configuration/instructions/Bundle-Author> indique le nom du champ Bundle-Author qui sera écrit dans le manifeste du bundle construit. Attention à ne pas modifier le champ Bundle-Vendor (valeur hackathon), il est utilisé pour la connexion au site d’administration des fournisseurs de services.
- <plugin/configuration/instructions/Application-Icon> si vous voulez fournir une image (png 72×72 pixels) pour servir de logo à votre application (sinon elle sera représentée par une icône par défaut).

Il est bien sûr possible de modifier ce fichier, par exemple pour ajouter des dépendances vers des librairies externes ou pour enrichir la configuration du maven-bundle-plugin (sachant que celle fournie par défaut est auto-suffisante).

2.2 Fichier de propriétés Open the Box (src/main/resources/OSGI-INF/otb.properties)

Ce fichier contient les propriétés propres à l’application au sens Open the Box, elle est donc laissée entièrement au développeur. Notons simplement les champs les plus importants :

otb.label : c’est par cette valeur qu’apparaitra l’application dans l’AppStore et sur le dashboard.
otb.config.url=/TemplateApp/index.html : chemin vers la page web de configuration de l’application (voir la section IHM).

2.3 Fichier de configuration Declarative Services (src/main/resources/OSGI-INF/component-devices.xml)

Ce fichier contient les dépendances vers des services OSGi utilisés par l’application, notamment l’éligibilité des équipements requis.

On commence par spécifier la classe implémentant le composant, ici com.orange.openthebox.hab.hackathon.template.FakeApp (qui peut bien sûr être refactorisée mais doit correspondre à une vraie classe du bundle).

On doit également laisser le lien vers le fichier otb.properties.

Exemple de dépendance vers un service OSGi du framework, le service http :

<reference name="httpService" cardinality="1..1"
   interface="org.osgi.service.http.HttpService"
   bind="setHttpService" unbind="unsetHttpService" />

Les champs bind et unbind seront utilisés par le framework pour fournir le service demandé, ils doivent donc correspondre exactement aux méthodes associées dans la classe d’implémentation du composant, ici public void setHttpService(final HttpService httpService)

Exemple de dépendance vers un équipement Zigbee :

<reference name="zigbeeDevice" cardinality="0..n" policy="dynamic"
   interface="org.osgi.service.zigbee.ZigBeeEndpoint"
   bind="setZigbeeDevice" unbind="unsetZigbeeDevice" />
   <!--target="(DEVICE_FRIENDLY_NAME=<a zigbee device>)"    -->

En l’état actuel, cette dépendance n’est pas filtrée, c’est-à-dire que tout service implémentant l’interface « Zigbee end point » du driver Zigbee (org.osgi.service.zigbee.ZigBeeEndpoint) sera lié à l’application. Si l’on souhaite se limiter à des équipements Zigbee précis, dont on connait le « friendly name », on peut dé-commenter la ligne target et indiquer (éventuellement en utilisant le symbole *) le ou les équipement(s) que l’on veut ainsi capturer (et exclure donc les équipements Zigbee ne correspondant pas). Par exemple, pour sélectionner des alarmes de nom IAS Warning Device… :

<reference name="zigbeeDevice" cardinality="0..n" policy="dynamic"
   interface="org.osgi.service.zigbee.ZigBeeEndpoint"
   bind="setZigbeeDevice" unbind="unsetZigbeeDevice"
   target="(DEVICE_FRIENDLY_NAME=IAS Warning Device*)" />

Rappels :

pour plus d’informations sur la manipulation des équipements, voir le Guide des équipements.
pour le cycle de vie debug / déploiement / test de l’application, voir sur le Guide du développeur.

3 Code Java

L’application proposée est une simple servlet qui a pour but de montrer comment récupérer et afficher la liste de tous les équipements présents sur la plate-forme.

Elle est composée des classes suivantes :

FakeApp est le point d’entrée du composant (champ implementation du fichier component-devices.xml) :
- Conformément à la spécification Declarative Services, elle possède des méthodes activate/deactivate/modified permettant de recevoir le ComponentContext du framework.
- C’est ici que sont définies les méthodes de bind/unbind des services OSGi requis. Les équipements ainsi détectés sont stockés dans des listes, une liste par type de technologie.
- Quand le service OSGi http est lié à l’application, celle-ci en profite pour
  - enregistrer en servlet la classe ApiServlet ;
  - enregistrer en tant que ressources statiques (sur l’alias "/TemplateApp") le répertoire correspondant à l’IHM de l’application.
ApiServlet est la classe implémentant la servlet Java (javax.servlet.http.HttpServlet) de configuration de l’application. Elle est enregistrée dans le service OSGi http avec l’alias "/TemplateApp/myapi" (valeur bien sûr modifiable, mais à garder cohérente avec la propriété otb.config.url dans le fichier otb.properties). Elle répond simplement à la requête GetDevices, sans paramètre, en renvoyant un tableau JSon des équipements reconnus, avec leurs caractéristiques, en fonction des technologies implémentées.

4 IHM

La partie IHM de l’application est on ne peut plus basique et n’a pour but que d’illustrer comment il faut créer une page web liée à l’application.

Nous fournissons simplement une page index.html, située dans le répertoire WEB-INF (nom utilisé dans l’enregistrement des ressources statiques auprès du service OSGi http) qui propose un lien vers la requête GetDevices de la servlet de l’application : <a href="./myapi/GetDevices">Get current devices</a>.

Squelette d’application