W4 Connectors for Java - Manuel du kit de

Transcription

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
MANUEL DU KIT
DE DEVELOPPEMENT
DE CONNECTEURS
© 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
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
Déploiement 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.
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 :
8
Fig 2.1
2.2
Organisation du kit de développement (1/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
2.3
Organisation du kit de développement (2/2)
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.
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
Développement du fooConnector
3
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.
12
3.1.2
Etendre la classe TWFconnector
Déclaration de classe :
import
import
import
import
public
{
...
}
3.1.3
fr.w4.connector.foo.*;
java.util.*;
java.io.*;
fr.w4.utils.log.TWFlog;
class TWFfooConnector extends TWFconnector
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
}
3.1.5
return "1.00.00";
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;
=
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
{
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).
N O TE
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();
16
}
3.1.9
logWriter = null;
}
catch(Exception e)
{
TWFlog.log("can not close logWriter");
TWFlog.log(e);
}
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
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).
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.
N O TE
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
19
Console du serveur de connecteurs
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
Ce noeud est assigné au fooConnector et l'activité associée à ce noeud s'appelle
fooConnector_activity. Cette activité ne contient aucune variable.
20
Fig 3.4
Pour tester cette procédure, utilisez l'interface classique de W4 Engine.
21
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).
I M PO R T A N T
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.
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
I M PO R T A N T
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.
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
Communication inter-connecteurs 23
26
27
Illustrations
Index
C
connector.jar 6
CSDK, W4 Java Connectors 8, 12
K
Kit de développement de connecteurs, W4 Java Connectors 8, 12
28
29
Index
MANUEL DU KIT
DE DEVELOPPEMENT
DE CONNECTEURS
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 : [email protected]
 Par téléphone : +33 (0) 820 320 762

W4 Connectors for Java - Manuel du kit de

Transcription

Documents pareils

Alimentation ATX GlacialTech Real Power - 650W

Alimentation ATX ECO 480W

JEU D`EMPREINTES EXTRACTION FICHES DE CONNEXION

Configuration Celeron 2533 GHz Asus P4S800-MX SE

Adaptateur DVI-I/VGA HD 15 F (cable 15 cm)

Caractéristiques techniques des connecteurs

Adaptateur DVI-I/VGA HD 0,15 M

Rallonge clavier PC99 PS/2 MDin6 M/F - 1,80m

Offres d`emploi de Jobingé - Forum Entreprises JAVA DEVELOPER

Développeur Java Google App Engine (H/F)