MANUEL DU KIT DE DEVELOPPEMENT DE CONNECTEURS Référence: W4JC_DEVKIT_020_FR

W4 CONNECTORS FOR JAVA MANUEL DU KIT DE DEVELOPPEMENT DE CONNECTEURS Référence: W4JC_DEVKIT_020_FR Les prochaines mises à jour de ce document seront disponibles sur www.myw4.com

W4 CONNECTORS FOR JAVA MANUEL DU KIT DE DEVELOPPEMENT DE CONNECTEURS Référence: W4JC_DEVKIT_020_FR

2003-2010 W4. Tous droits réservés. L'acquisition du présent document confère un droit d'utilisation incessible, non exclusif et personnel et non un droit de propriété. L'utilisation, la copie, la reproduction et la distribution du présent document sont permises à condition: 1. que la mention de droits d'auteur ci-dessus figure sur toutes les copies et que cette mention de droits d'auteur et la présente mention d'autorisation apparaissent conjointement ; 2. que le présent document ne soit utilisé qu'à des fins d'information et non commerciales ; 3. que le présent document ne soit modifié de quelque manière que ce soit. Tous les produits et marques cités sont la propriété de leurs titulaires respectifs. Les informations contenues dans ce document pourront faire l objet de modifications sans préavis.

Sommaire Conditions préalables 6 Architecture logicielle 8 Organisation du kit de développement 8 La classe TWFconnector 9 La classe TWFconnectorContext 10 La classe TWFmessage 11 Développement du fooconnector 12 Développement Java 12 Déploiement 17 Mise en place du répertoire projet (proposition) 12 Etendre la classe TWFconnector 13 Déclaration des variables globales 13 Nom et version du fooconnector 13 Utilisation d'un fichier de configuration (fooconnector.properties) 14 Initialisation du fooconnector 14 La méthode service(twfmessage message) 15 Arrêt du FooConnector 16 Filtrage des messages en provenance de W4 Engine 17 Compilation 17 Le "manifest file" 18 Construire l'archive Java 18 W4 Connectors for Java Manuel du kit de développement de connecteurs 4

Mise en place de l'archive Java et du fichier fooconnector.properties sur W4 Engine 18 Création du rôle fooconnector et de l'acteur fooagent 18 Tests de bon fonctionnement 19 La console du serveur de connecteurs 19 Développer une procédure de test 20 Fonctionnalités avancées 22 Utilisation d'un template W4 Engine 22 Communication inter-connecteurs 22 5 Sommaire

Chapitre 1 1 Conditions préalables Ce chapitre décrit les conditions requises pour utiliser le kit de développement de connecteurs. Sur le serveur W4 Engine Un serveur de connecteurs installé et configuré. Sur le poste de développement Un Java Development Kit 1.2.x ou supérieur. Ce produit est disponible à l'adresse suivante : http://java.sun.com Pour pouvoir développer un nouveau connecteur, vous devez disposer du package java connector.jar qui se trouve (après installation du serveur de connecteurs sur le serveur W4 Engine) dans le répertoire W4Engine_Home/connector/lib. Si le connecteur est amené à interagir avec W4 Engine, le Java Toolkit de W4 doit être installé. Niveau de compétences techniques requis Avoir une connaissance basique de Process Composer. Connaître le fonctionnement de W4 Engine (les concepts de procédure, noeud, dossier, tâche, etc.). Savoir créer un acteur et un rôle dans W4 ou être en liaison avec un administrateur W4 Engine. Maîtriser le langage Java (avoir, par exemple, déjà développé des objets Java serveur, comme des servlets). Connaître les API Java de W4 Engine (si le connecteur interagit avec le serveur W4 Engine). Eventuellement avoir une connaissance des standards XML/XSL. W4 Connectors for Java Manuel du kit de développement de connecteurs 6

7 Chapitre 1 Conditions préalables

Chapitre 2 2 Architecture logicielle Ce chapitre décrit les classes principales du kit de développement de connecteurs. 2.1 Organisation du kit de développement Cette section ne traite que des classes principales composant le CSDK. Pour une documentation complète, reportez-vous à la javadoc, disponible sous : W4JavaConnectors_Home\Docs\fr\javadoc\index.html Les classes principales du kit de développement sont les suivantes : W4 Connectors for Java Manuel du kit de développement de connecteurs 8

Fig 2.1 Organisation du kit de développement (1/2) 2.2 La classe TWFconnector La classe principale est la classe TWFconnector. C'est elle qu'il faudra étendre pour créer un nouveau connecteur. Comme le diagramme le montre, cette classe implémente les interfaces TWFiConnector, TWFiConnectorDesc, TWFiMessageListener. La première interface décrit les méthodes que tout connecteur doit déclarer. C'est l'implémentation de l'interface TWFiConnectorDesc qui permet de donner une visibilité d'un connecteur au niveau de la console 9 Chapitre 2 Architecture logicielle

du serveur de connecteurs. Enfin, c'est l'interface TWFiMessageFilter qui donne la possibilité au connecteur d'accepter les messages en provenance du serveur W4 Engine. Ce diagramme renseigne également sur le fonctionnement des connecteurs. Chaque connecteur dispose d'une file d'attente de messages. Les connecteurs traitent donc leurs tâches de façon séquentielle. Fig 2.2 Organisation du kit de développement (2/2) 2.3 La classe TWFconnectorContext Sur le diagramme ci-dessus, les classes TWFconnectorContext et TWFmessage sont également décrites. TWFconnectorContext représente le contexte dans lequel s'exécute le connecteur et plus largement le serveur de connecteurs. Elle fournit, notamment, les informations suivantes : nom de l'instance W4 Engine ; répertoire dans lequel W4 Engine est installé ; répertoire dans lequel le serveur de connecteurs est installé ; répertoire dans lequel se trouvent les fichiers de configuration des connecteurs. W4 Connectors for Java Manuel du kit de développement de connecteurs 10

2.4 La classe TWFmessage La classe TWFmessage représente un message en provenance de W4 Engine ou d'un autre connecteur. Elle permet de savoir si le message reçu est lié ou non à une tâche offerte au connecteur (si la méthode gettaskid() renvoie un entier > 0), de connaître l'identifiant ou le nom de l'acteur concerné par cette tâche.

Chapitre 3 3 Développement du fooconnector Ce chapitre décrit le développement pas à pas du connecteur fooconnector. Lorsqu'il aura une tâche workflow à effectuer, ce connecteur écrira l'identifiant de cette tâche dans un fichier (qui doit être paramétrable) puis la terminera. Il interagira donc à la fois avec une ressource externe - le fichier journal - et avec le serveur W4 Engine - la terminaison de la tâche. 3.1 Développement Java Les étapes suivantes vont vous permettre de développer le connecteur fooconnector en langage Java. 3.1.1 Mise en place du répertoire projet (proposition) L'organisation du projet est faite de manière classique : on crée un répertoire principal du nom de fooconnector. Sous ce répertoire, on ajoute quatre sous-répertoires : src qui contiendra le fichier TWFfooConnector.java ; lib dans lequel on placera le package connector.jar ; build qui accueillera le pseudo-code java ; dist dans lequel sera stockée l'archive java permettant le déploiement du fooconnector sur le serveur W4 Engine. W4 Connectors for Java Manuel du kit de développement de connecteurs 12

3.1.2 Etendre la classe TWFconnector Déclaration de classe : import fr.w4.connector.foo.*; import java.util.*; import java.io.*; import fr.w4.utils.log.twflog; public class TWFfooConnector extends TWFconnector... 3.1.3 Déclaration des variables globales On déclare ici une variable globale logwriter du type FileWriter. Le logwriter permettra d'écrire dans un fichier les identifiants des tâches assignées au fooconnector. import fr.w4.connector.foo.*; import java.util.*; import java.io.*; import fr.w4.utils.log.twflog; import fr.w4.session.*; import fr.w4.runtime.ref.*; import fr.w4.runtime.dynamic.*; public class TWFfooConnector extends TWFconnector /* logwriter permet d'écrire le journal du fooconnector */ private FileWriter logwriter = null;... 3.1.4 Nom et version du fooconnector Il s'agit ici de surcharger les méthodes getname() et getversion() de la classe mère TWFconnector. L'intérêt est que lorsque le fooconnector sera déployé sur le serveur W4 Engine, il sera possible de l'identifier dans la console du serveur de connecteurs sous le nom de fooconnector. Si vous ne surchargez pas la méthode getname(), le fooconnector apparaîtra dans la console sous le nom de UNKNOWN_CONNECTOR. Surcharge des méthodes getname() et getversion() : public final String getname() return "fooconnector"; public final String getversion() 13 Chapitre 3 Développement du fooconnector

return "1.00.00"; 3.1.5 Utilisation d'un fichier de configuration (fooconnector.properties) Le cahier des charges impose que le fichier journal du fooconnector soit paramétrable. On prépare donc un fichier de configuration du fooconnector que l'on appellera fooconnector.properties. Les fichiers de paramétrage des connecteurs sont à placer dans le répertoire W4Engine_Home/connector/lib/resources/. #logfile name w4adm.logfile.name=c:/temp/fooconnector.log 3.1.6 Initialisation du fooconnector La méthode init() de la classe TWFconnector est appelée lors du lancement du serveur de connecteurs. Dans le cadre du fooconnector, l'initialisation a pour objectif de créer le logwriter. Pour ce faire, il est tout d'abord nécessaire de récupérer le nom du fichier journal dans le fichier de configuration. Cela suppose de savoir où est stocké le fichier de configuration. A cette fin, il faut utiliser la classe TWFconnectorContext qui contient une méthode statique appelée getresourceshome(). Pour obtenir la valeur de la clé logfile.name, on utilise la classe java.util.propertyresourcebundle. A l'occasion de l'initialisation, on peut percevoir la problématique de la journalisation des erreurs. Si le fichier fooconnector.properties est introuvable ou mal formaté ou encore si un problème de droits d'écriture survient, il faudra journaliser ces exceptions. La classe fr.w4.utils.twflog est prévue à cet effet. En utilisant sa méthode log(), les exceptions ou les messages en provenance du fooconnector seront ajoutés au fichier de log du serveur de connecteurs : W4LOGHOME/System*.log. public void init() /* récupération du répertoire contenant les fichiers de configuration des connecteurs */ String resourceshome = TWFconnectorContext.getResourcesHome(); String configfilename = resourceshome+"/fooconnector.properties"; /* lecture du fichier de configuration récupération de la clé 'logfile.name' */ FileInputStream bundlestream = null; PropertyResourceBundle bundle = null; String logfilename = null; W4 Connectors for Java Manuel du kit de développement de connecteurs 14

try bundlestream = new FileInputStream(configFileName); bundle = new PropertyResourceBundle(bundleStream); logfilename = bundle.getstring(twfconnectorcontext.getinstancename() +".logfile.name"); logwriter = new FileWriter(logFileName,false); catch(filenotfoundexception fne) TWFlog.log("can not find file "+configfilename); catch (MissingResourceException mex) TWFlog.log("can not find resource " + configfilename + " or key logfile.name"); catch(ioexception ioe) TWFlog.log("can not write to file " + logfilename); catch(exception e) TWFlog.log("unexpected exception"); TWFlog.log(e); /* on s'assure de toujours refermer les flux ouverts */ finally try bundlestream.close(); bundlestream = null; catch (Exception ex) TWFlog.log("can not close bundle"); bundle = null; 3.1.7 La méthode service(twfmessage message) La méthode service(twfmessage message) est le coeur du connecteur. C'est elle qui est appelée lorsqu'une tâche est offerte au connecteur. public void service(twfmessage message) /* récupération de l'identifiant de la tâche à faire */ int taskid = message.gettaskid(); /* écriture de l'identifiant de la tâche dans le fichier journal */ try logwriter.write("taskid =["+taskid+"]\n"); logwriter.flush(); catch(ioexception e) 15 Chapitre 3 Développement du fooconnector

TWFlog.log("Exception occured while writing taskid to log file"); /* terminaison de la tâche */ TWFsession w4session = null; try w4session = new TWFnativeSession(); w4session.setinstancename(twfconnectorcontext.getinstancename() ); w4session.openconnection(); w4session.login("fooagent","fooagent"); TWFtaskRef taskref = new TWFtaskRef(taskId); taskref.wfendtask(null,null); catch(exception e) nberrors++; TWFlog.log("Exception occured while completing the task"); TWFlog.log(e); /* on s'assure de refermer le canal physique vers le serveur W4 */ finally if(w4session!= null && w4session.getsessionhandle() > 0) try w4session.closeconnection(); catch(exception e) nberrors++; TWFlog.log(e); 3.1.8 Arrêt du FooConnector La méthode stopconnector() est appelée à l'arrêt du serveur de connecteurs (ce qui correspond à l'arrêt du serveur W4 Engine). Il s'agit ici de s'assurer que l'on libère les ressources externes ouvertes (le logwriter). NOTE Lors de l'arrêt du serveur de connecteurs, celui-ci attend que tous les connecteurs s'arrêtent. Il octroie un certain délai, commun à tous les connecteurs, pour l'exécution de la méthode stopconnector(). Ce délai permet au connecteur de s'arrêter correctement. Passé ce délai, le connecteur est arrêté même s'il n'a pas fini son traitement. Le délai d'attente est renseigné dans le fichier W4Engine_Home/connector/lib/resources/connector.properties. public void stopconnector() try logwriter.close(); W4 Connectors for Java Manuel du kit de développement de connecteurs 16

logwriter = null; catch(exception e) TWFlog.log("can not close logwriter"); TWFlog.log(e); 3.1.9 Filtrage des messages en provenance de W4 Engine Il s'agit ici d'implémenter une règle pour savoir si un message doit être, ou non, traîté par le fooconnector. Ce mécanisme est simple à mettre en oeuvre dans le cadre de W4 puisque lorsque le moteur de workflow notifie au serveur de connecteurs qu'une tâche est attribuée à un connecteur ; il précise, dans le message envoyé, le nom du rôle cible. En d'autres termes, le fooconnector n'acceptera de traiter une tâche que si figure dans la liste des destinataires le rôle fooconnectorrole (la création de ce rôle est évoquée ci-dessous). public boolean acceptmessage(twfmessage message) return message.containstarget("fooconnectorrole"); 3.1.10 Compilation Si vous avez respecté l'organisation du répertoire projet proposée ci-dessus, la ligne de commande suivante est à utiliser pour la compilation : javac -classpath lib/connector.jar -sourcepath src -d build TWFfooConnector.java 3.2 Déploiement Les étapes suivantes vont vous permettre de déployer le connecteur fooconnector. 17 Chapitre 3 Développement du fooconnector

3.2.1 Le "manifest file" Le déploiement d'un nouveau connecteur sur le serveur W4 Engine se fait en déposant dans le répertoire W4Engine_Home/connector/lib/ext une archive java (*.jar) contenant le pseudo-code du connecteur. Pour que ce mécanisme d'extension fonctionne, il faut inclure dans l'archive un "manifest file" précisant le nom et la classe du connecteur. Le "manifest file" se présente comme suit : Manifest-Version: 1.0 Main-Class: TWFfooConnector Name: TWFfooConnector.class On le placera directement sous la racine du répertoire fooconnector. 3.2.2 Construire l'archive Java Pour produire l'archive fooconnector.jar dans le sous-répertoire dist, il suffit d'exécuter la ligne de commande suivante : jar -cfm dist/fooconnector.jar foomanifest.mf -C build TWFfooConnector.class 3.2.3 Mise en place de l'archive Java et du fichier fooconnector.properties sur W4 Engine Il vous suffit de déposer : une copie de l'archive fooconnector.jar dans le répertoire W4Engine_Home/connector/lib/ext ; et une copie du fichier fooconnector.properties dans le répertoire W4Engine_Home/connector/lib/resources. Au prochain redémarrage du serveur W4 Engine (et donc du serveur de connecteurs), le fooconnector sera automatiquement lancé. 3.2.4 Création du rôle fooconnector et de l'acteur fooagent Tel qu'évoqué ci-dessus, chaque connecteur est un acteur W4. Il faut donc créer sur le serveur W4 Engine un acteur fooagent. Pour ce faire, vous pouvez utiliser l'interface d'administration de W4 disponible à l'url http://w4server/w4public. Pour que cet acteur soit considéré par le serveur W4 Engine comme un connecteur, il faut lui assigner le rôle jconnector (créé à l'installation du serveur de connecteurs). W4 Connectors for Java Manuel du kit de développement de connecteurs 18

Il faut ensuite créer un rôle fooconnectorrole qui sera spécifique au fooconnector (cf. ci-dessus le paragraphe sur le filtrage des messages en provenance de W4 Engine). Enfin, il faut assigner le rôle fooconnectorrole à l'acteur fooagent. NOTE Il vous faut maintenant redémarrer W4 Engine pour que l'ensemble de ces changements soient pris en compte. 3.3 Tests de bon fonctionnement Pour vérifier le bon fonctionnement du connecteur fooconnector, nous allons utiliser les informations fournies par la console du serveur de connecteurs puis nous allons développer une procédure de test. 3.3.1 La console du serveur de connecteurs Après le déploiement du fooconnector et le redémarrage du serveur W4 Engine, il vous suffit de lancer la console pour vérifier que le fooconnector a bel et bien été chargé. Si tel est le cas, la ligne fooconnector doit apparaître dans la console. Fig 3.1 Console du serveur de connecteurs 19 Chapitre 3 Développement du fooconnector

3.3.2 Développer une procédure de test La procédure de test (nommée fooconnectortest) est composée d'un seul noeud, comme le montre le schéma ci-dessous : Fig 3.2 Procédure de test (1/3) Cette procédure n'a qu'une seule variable fooactor. Elle a comme valeur par défaut fooagent. Cette variable sera utilisée pour gérer l'assignation au fooconnector. Fig 3.3 Procédure de test (2/3) Ce noeud est assigné au fooconnector et l'activité associée à ce noeud s'appelle fooconnector_activity. Cette activité ne contient aucune variable. W4 Connectors for Java Manuel du kit de développement de connecteurs 20

Fig 3.4 Procédure de test (3/3) Pour tester cette procédure, utilisez l'interface classique de W4 Engine. 21 Chapitre 3 Développement du fooconnector

Chapitre 4 4 Fonctionnalités avancées Ce chapitre décrit la mise en oeuvre de fonctionnalités avancées, entre autres la génération dynamique de templates associés aux activités connecteurs. 4.1 Utilisation d'un template W4 Engine Lorsque W4 Engine envoie un message au serveur de connecteurs, il peut, dans le même temps, générer dynamiquement le template associé à l'activité. Pour indiquer à W4 Engine qu'il doit procéder de la sorte, il faut cocher la case informer par mail les propriétés du noeud qui est assigné au connecteur. Pour récupérer le nom du fichier généré lors de l'appel à la méthode service, il suffit d'invoquer la méthode gettemplatefile() sur l'objet message (instance de la classe TWFmessage). IMPORTANT Rappel sur le multi-instances : par défaut, le service wfmill recherche le template de l'activité dans le répertoire W4Engine_Home/Templates. Dans le cadre du multi-instances, vous pouvez spécifier un autre répertoire en rajoutant une entrée dans le fichier W4Engine_Home/sys/w4server.cfg. Par exemple : n instance : w4sup n répertoire des templates d'activités : C:\w4sup\Activities Rajouter alors dans w4server.cfg la ligne suivante : w4sup.alias.activities:c:/w4sup/activities 4.2 Communication inter-connecteurs Les connecteurs sont en mesure de communiquer les uns avec les autres. Le diagramme de séquence ci-dessous décrit le processus à appliquer. W4 Connectors for Java Manuel du kit de développement de connecteurs 22

Fig 4.1 Communication inter-connecteurs Imaginons que le connecteur1 souhaite faire interpréter un fichier XML par le connecteur XML. Pour ce faire, il suffit d'écrire le code suivant : TWFmessage message = new TWFmessage(); message.setblob(); message.setactorname("w4actorname"); message.setauthor("connector1"); message.setto(new String[] "xmlconnector"); TWFdispatcher.sendMessage(message); Il est également possible d'envoyer un message de façon synchrone. Il faut alors utiliser le code suivant : TWFmessage message = new TWFmessage(); message.setblob(); message.setactorname("w4actorname"); message.setauthor("connector1"); message.setto(new String[] "xmlconnector"); TWFdispatcher.sendSyncMessage(message); 23 Chapitre 4 Fonctionnalités avancées

IMPORTANT Il faut privilégier le mode synchrone pour les communications inter-connecteurs. En effet, cela évite de saturer la file d'attente d'un connecteur. W4 Connectors for Java Manuel du kit de développement de connecteurs 24

25 Chapitre 4 Fonctionnalités avancées

Illustrations Organisation du kit de développement (1/2) 9 Organisation du kit de développement (2/2) 10 Console du serveur de connecteurs 19 Procédure de test (1/3) 20 Procédure de test (2/3) 20 Procédure de test (3/3) 21 Communication inter-connecteurs 23 W4 Connectors for Java Manuel du kit de développement de connecteurs 26

27 Illustrations

Index C K connector.jar 6 CSDK, W4 Java Connectors 8, 12 Kit de développement de connecteurs, W4 Java Connectors 8, 12 W4 Connectors for Java Manuel du kit de développement de connecteurs 28

29 Index

W4 CONNECTORS FOR JAVA MANUEL DU KIT DE DEVELOPPEMENT DE CONNECTEURS Référence: W4JC_DEVKIT_020_FR Pour toute remarque ou suggestion concernant ce document, vous pouvez contacter le support technique W4, en précisant la référence du document : par le service de traitement des dossiers Supportflow sur MyW4.com, à l adresse suivante : http://support.myw4.com Par courrier électronique : support@w4global.com Par téléphone : +33 (0) 820 320 762