Circulation - My Geoconcept

Circulation
1
Circulation
Introduction ..................................................................................................................................... 3
Configuration ................................................................................................................................... 4
Chargement du fichier de configuration ..................................................................................... 4
Principe général simplifié ................................................................................................................. 5
Diagramme d’exemple d’import d’une demande de rendez-vous ........................................................ 6
Mediums ................................................................................................................................. 6
Forward-router ......................................................................................................................... 6
Lecture du diagramme d’exemple ............................................................................................. 7
Retours de traitements ............................................................................................................. 7
Fichier XML correspondant ...................................................................................................... 7
Référence : Format du fichier de configuration .................................................................................. 9
Circulation-config ..................................................................................................................... 9
Référence : Format de retour : schéma "circulation-result" ........................................................ 42
ANNEXE 1- Les Expressions Cron ................................................................................................. 45
Les informations figurant dans le présent document décrivent les fonctions et modes d’utilisation de la
« circulation »- au 1er juin 2011. Elles sont sujettes à révision sans préavis.
Le logiciel décrit dans ce document est diffusé dans le cadre d’un contrat de droit d’utilisation et ne
peut être utilisé, copié ou cédé qu’en conformité avec les stipulations de ce contrat. Toute copie de
l’application Opti-Time sur disque ou autre support à des fins autres que l’usage du programme par
l’acheteur pour ses besoins propres est interdite.
Opti-Time est une marque déposée de GeoConcept SA Les captures écran peuvent varier en fonction
des droits attribués et des options retenues.
2
Introduction
Introduction
Cette partie de la documentation concerne la fonctionnalité nommée « Circulation ». Il s’agit d’un module
qui gère la circulation et l'échange des données entre Opti-Time et l’extérieur. Ses applications sont
multiples et permettent de gérer par exemple :
• Sens extérieur → Opti-Time
L’import de demandes de rendez vous par des messages JMS.
L’import de données de référence par des fichiers placés dans un répertoire.
• Sens Opti-Time → extérieur
La notification d’une modification d’un rendez-vous par JMS.
3
Circulation
Configuration
Le module « Circulation » ne propose pas d’interface utilisateur. La configuration du module se fait par
élaboration d’un fichier « circulation_config.xml ».
Chargement du fichier de configuration
A l’initialisation
Le module démarre lors de la phase d’initialisation d’Opti-Time, après lecture du fichier
« circulation_config.xml ».
Par l’interface d’administration
Il est possible de redémarrer le module avec un autre fichier de circulation en se rendant dans l’interface
d’administration d’Opti-Time.
Note 1 : Le module circulation est arrêté, puis est redémarré avec la nouvelle configuration. Il s’agit d’un
remplacement, pas d’un ajout.
Note 2 : Le fichier d’initialisation circulation_config.xml n’est pas mis à jour. Si vous souhaitez que la
nouvelle configuration remplace l’ancienne lors du prochain redémarrage d’Opti-Time, vous devez le
placer dans le répertoire de configuration du serveur (typiquement placé dans d:\gss\nom_de_société
\config\param\circualtion_config.xml).
4
Principe général simplifié
Principe général simplifié
Voici un schéma expliquant le principe général de fonctionnement du module circulation. Toute la
circulation des données dans le module fonctionne selon ce principe.
Les flèches sur ce schéma représentent le flux de circulation des messages.
Les entités représentées ici sont des objets abstraits, lors de la configuration du module par le fichier
circulation_config.xml, vous allez travailler sur des objets concrets.
Par exemple, parmi les listeners concrets, existent :
• les « AppointmentListener » : écoutent tout ce qui se passe sur les rendez-vous (création, modification,
suppression)
• les « InputMediumListener » : écoutent l’arrivée d’un nouveau message sur un médium (repertoire,
JMS).
Configurer le module Circulation consiste à définir les différents objets intervenant dans la circulation des
données et à les relier entre eux.
5
Circulation
Diagramme d’exemple d’import d’une demande de rendez-vous
Voici un diagramme d’import d’une demande de rendez vous.
Sur ce diagramme, les objets concrets sont représentés en police fine, et les objets abstraits auxquels ils
correspondent sont en gras.
Les IDs donnés aux objets dans le fichier XML sont représentés entre guillemets.
Mediums
Ce diagramme introduit la notion de « médium ». Il en existe deux sortes : les input-mediums, permettant
la réception de messages, et les output-medium, permettant l’envoi de message. Ici on utilise les objets
concrets « jms-input-queue » (permettant la réception de message JMS), et « directory-output-medium »,
permettant l’envoi de message sur un répertoire disque.
Forward-router
On utilise ici un filter-router nommé « forward-router », dont le rôle est simplement de transférer le
message vers un autre « router ». Mais il offre une fonctionnalité supplémentaire : Si le message
transferé n’est pas pris en compte par le router (= le router renvoie une erreur), alors le message est
envoyé vers un autre router : dans notre cas, simple-medium-sender, qui va envoyer le message vers le
medium directory-output-medium.
6
Lecture du diagramme d’exemple
Lecture du diagramme d’exemple
L’objet outside-listener écoute les messages arrivant sur la jms-input-queue. Outside-listener envoie ces
messages vers forward-router, qui lui même les transmet à appointment-request-receiver. Ce dernier est
en bout de chaîne, c’est lui qui va réellement effectuer l’import du rendez-vous. Une fois le message pris
en compte, ce processor renvoie au forward-router le résultat de l’import, c’est à dire une valeur VRAI ou
FAUX, indiquant si le traitement s’est bien passé. Le forward-router, si le traitement s’est mal passé, va
alors transférer à nouveau le message au simple-medium-sender, qui lui va l'écrire sur le directory-inputmedium.
Retours de traitements
Tous les objets entrant en compte dans le traitement d’un message informent leur appelant de la bonne
prise en compte ou non (VRAI ou FAUX) de l'événement. Ce retour a donc lieu dans le sens inverse des
flèches.
Cela permet à l’appelant d’agir en conséquence. Par exemple, ici, si forward-router reçoit FAUX à la
fois de l’appointment-request-receiver puis de simple-medium-sender, alors il renverra FAUX à son
appelant, c’est à dire au listener, qui lui même le renverra au jms-input-queue. Ce dernier ne fera alors
pas d’Acknowledge JMS.
Si forward-router reçoit FAUX de l’appointment-request-receiver, puis VRAI de simple-medium-sender,
alors il renvoie vrai, considérant que le message a d’une façon ou d’une autre été pris en compte.
Certains routers peuvent aussi completer leur répoonse avec des données supplémentaires : le
ResultData.
Fichier XML correspondant
Voici un fichier XML correspondant à notre exemple.
Les parties de XML encadrées sont des references aux ids des objets du fichier. Les flèches montrent les
objets référencés.
<?xml version="1.0" encoding="UTF-8"?>
<circulation-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="schemas/circulation-config.xsd">
<circulation-block>
<listeners>
<inside-listeners>
</inside-listeners>
<outside-listeners>
<outside-listener>
<id>myOutsideListener</id>
<input-medium>myJMSQueue</input-medium>
<router>myForwardRouter</router>
<default-unmarshaller>defaultAppointmentUnmarshaller</default-unmarshaller>
</outside-listener>
</outside-listeners>
</listeners>
<routers>
<filter-routers>
7
Circulation
<forward-router>
<id>myForwardRouter</id>
<router>appointmentToGSSRouter</router>
<error-router>senderForAppointmentErrorMessage</error-router>
</forward-router>
</filter-routers>
<processor-routers>
<inside-processors>
<appointment-request-receiver>
<id>appointmentToGSSRouter</id>
</appointment-request-receiver>
</inside-processors>
<outside-processors>
<simple-medium-sender>
<id>senderForAppointmentErrorMessage</id>
<output-medium>mediumSenderForAppointmentErrorMessage</output-medium>
<marshaller>pseudoMarshaller</marshaller>
</simple-medium-sender>
</outside-processors>
</processor-routers>
</routers>
<mediums>
<input-mediums>
<jms-input-queue>
<id>myJMSQueue</id>
<jndi-name>serial://jms/queueGC02ToGSS</jndi-name>
<jms-connection>connectionAppointment</jms-connection>
</jms-input-queue>
</input-mediums>
<output-mediums>
<directory-output-medium>
<id>mediumSenderForAppointmentErrorMessage</id>
<location>c:\temp\gss\messages\appointment-error</location>
<prefix>ERROR</prefix>
<suffix>.xml</suffix>
</directory-output-medium>
</output-mediums>
</mediums>
<transformers>
<unmarshallers>
<by-class-appt-unmarshaller>
<id>defaultAppointmentUnmarshaller</id>
<classname>com.geoconcept.schedule.logic.circulation.impl.PseudoUnmarshaller</classname>
</by-class-appt-unmarshaller>
</unmarshallers>
<marshallers>
<by-class-appt-marshaller>
<id>pseudoMarshaller</id>
<classname>com.geoconcept.schedule.logic.circulation.impl.PseudoMarshaller</classname>
</by-class-appt-marshaller>
</marshallers>
</transformers>
<connections>
<jms-connection>
<id>connectionAppointment</id>
<factory-jndi-name>serial://jms/myQueueConnectionFactory</factory-jndi-name>
<reconnection-delay>10000</reconnection-delay>
</jms-connection>
</connections>
</circulation-block>
</circulation-config>
8
Référence : Format du fichier de configuration
Référence : Format du fichier de configuration
Le format du fichier de configuration XML est spécifié sous la forme d’un schéma XML W3C (XSD) :
« circulation-config.xsd ».
Voici le les premières balises du schéma :
Circulation-config
Cette balise est la racine de tout document circulation-config. Elle contient des circulation-block.
9
Circulation
Circulation-block
Un circulation-block est un ensemble d’objets de circulation décrivant un ou plusieurs flux cohérents, par
exemple : L’import de données de référence, ou la notification de mise à jour de rendez-vous.
Vous êtes libre de découper votre fichier de circulation en plusieurs blocs, ou de tout mettre dans un seul
et même bloc. Le comportement de l’application ne s’en trouvera pas changé.
Note importante : Les objets référencables à l’intérieur d’un block sont les objets de ce blocs, et les objets
des blocs précédents. Il n’est pas possible de référencer les objets des blocs suivants.
L’espace de nommage des objets est global : L’ID d’un objet doit être unique dans l’ensemble du fichier.
Listeners
Cette balise contient tous les listeners d’un bloc : d’abord tous les inside-listeners, ensuite tous les
outside-listeners.
Inside-listeners
Cette balise contient tous les inside-listeners d’un bloc :
Un inside-listener est un objet qui écoute les événements internes à Opti-Time.
Appointment-listeners
Un appointment-listener est un objet capable d'écouter les événements se produisant sur les rendez-vous
dans Opti-Time : Ajout, modification, suppression.
10
Circulation-config
A chaque événement reçu, la donnée envoyée vers le router est un Appointment.
L’appointment-listener informe de tous les évènements de création et mise à jour des rendez vous une
fois que ces évènements sont validés. Ces événements peuvent être filtrés en fonction d’une chaîne de
transition d'état qui est une liste de filtres pour les événements correspondant à un changement de statut
particulier. Les filtres sont séparés par des virgules et traités dans l’ordre de la liste. Chaque filtre est
un triplet définissant un code statut origine, un code statut nouveau, une valeur 1 ou 0 suivant que cette
transition est filtrée ou non.
Deux « wildcards » peuvent être utilisés pour
• * : correspond à tous les statuts
• # (dans le statut de destination) : signifie «vers le même statut »
Exemples :
<status-transition-filter>21:21:0,6:6:0</status-transition-filter>
laisse passer tous les événements sauf les modifications d’appointment de statut 21 (démandé) et 6
(suspendu) qui n’ont pas entraîné de changement de statut
<status-transition-filter>*:*:0,*:31:1</status-transition-filter>
ignore tous les évenements sauf les évenements à l’issue desquels l’appointment est à l'état confirmé.
<status-transition-filter>*:#:0</status-transition-filter>
ne laisse passer que les changements d'états
Optimization-listeners
Un optimization-listener est un objet capable d'écouter les événements se produisant sur le
module d’optimisation globale. A chaque evenement reçu, la donnée envoyée vers le router est un
OptimizationEvent.
Instant-inside-listener
Un instant-insied-listener écoute des évenements de calendrier programmés par un instant-trigger et
déclenche le routeur associé qui doit être un processeur autonome tel que les processeurs d’export. Il
permet de définir une route régulière d’export batch des entités manipulées par Opti-Time.
11
Circulation
Outside-listeners
Cette balise contient une liste d’oustide-listener et de bulk-outside-listeners :
Outside-listener
Un outside-listener est un objet qui écoute les événements venant de l’extérieur d’Opti-Time.
Il écoute les messages arrivant sur l’input-medium spécifié, et envoie le message vers le router spécifié.
Si le router ne traite pas le message (il renvoie FAUX), alors outside-listener renverra également FAUX à
l’input-medium, dont le comportement normal doit être de conserver le message pour un traitement futur.
12
Circulation-config
Optionnel : Il est possible de spécifier un timeout, ainsi qu’un timeout-router.
Le timeout indique le temps en minute maximal de prise en compte du message. Si le message a été
créé depuis plus de temps que la valeur du timeout, alors, après avoir été envoyé au router, et que
celui-ci renvoit FAUX, alors il est également envoyé au timeout-router. La date et l’heure de création du
message dépend de l’input-medium utilisé. Pour un « directory-input-medium », il s’agit de la date de
création du fichier, pour un « jms-input-queue », il s’agit du champ JMSTimestamp.
Il est possible de piloter le retour du listener : si "success-if-timeout-success" est positionné à true, (valeur
par défaut), alors le retour du listener sera VRAI quand le timeout-router est VRAI (alors que le premier
router a renvoyé FAUX). Sinon (si "success-if-timeout-success" est positionné à false), alors le retour du
listener est celui du premier router.
Optionnel : Il est possible de spécifier un diagnostic-router.
Ce routeur est appelé en cas d’erreur sur le router, et après appel éventuel au timeout-router.
Les données envoyées à ce timeout-router ne sont pas les données du message initial, mais
un objet de diagnostic, contenant les informations nécessaires au diagnostic de l’erreur de
traitement, c’est à dire typiquement un message d’erreur. Ces données de diagnostic peuvent être
marshallées par un com.geoconcept.schedule.logic.circulation.impl.DiagnosticDataMarshaller ou un
om.geoconcept.schedule.logic.circulation.impl.DiagnosticDataXMLMarshaller
Ceci sert par exemple à enregistrer les messages d’erreur dans un fichier de log.
En cas d’erreur dans ce traitement pour dignostique alors le listener renvoie FAUX.
Default-unmarshaller reference l’objet de décodage du message envoyé.
Bulk-outside-listener
Un bulk-outside-listener est un objet qui écoute les événements venant de l’extérieur d’Opti-Time, et qui
le découpe en plusieurs messages pour les envoyer au router. Une fois tous les messages envoyés un
rapport est envoyé au report-router.
13
Circulation
Cursor-factory : Ici doit être spécifié l’identifiant d’un CursorFactory, capable de découper le message.
(Voir le paragraphe CursorFactories)
Router : Router recevra comme message une sous-partie du message reçue par l’input-medium, telle
que découpée par Cursor-factory.
Report-router : Ce routeur recevra comme message un objet BulkReport, contenant le résultat de l’envoi
de tous les sous-message au router.
Error-router : Ce routeur recevra comme message une liste des sous messages non traités, ainsi u’une
cause d'échec.
Succes-router : Ce routeur recevra comme message une liste des sous messages traités avec succès,
ces sous messages puvant éventuellement avoir été augmentés par des informations supplémentaires
ajoutées par le routeur.
Jms-connection-listener
Un jms-connection-listener est un objet un peu particulier qui écoute les événements venant de la
connection JMS. Ces événements sont des notifications de connexion ou de déconnexion. Contrairement
aux listeners habituel, les événements reçus par un jms-connection-listener ne contiennent pas de
message (donnée) associé. Pour pouvoir envoyer un message en cas de connexion ou de déconnexion,
il va donc falloir créer le message. Vous ce faire, vous pourrez utiliser le router « message-changerrouter » qui créera remplacera le message vide par un contenu texte.
14
Circulation-config
Jms-connection-to-listen doit contenir l’id de la jms-connection à écouter.
Vous pouvez spécifier l’un ou l’autre ou les deux routers :
on-deconnection-router, qui sera appelé en cas de déconnexion, on-reconnection-router qui sera appelé
en cas de connection (la première) ou reconnexion.
Routers
La balise routers contient deux series de routers : les filter-routers et les processor-routers.
Filter-routers
Les filter-routers sont des routers qui peuvent s’emboîter les uns aux autres. Ils filtrent les messages, ou/
et les dispatchent vers d’autres routers.
15
Circulation
Custom-filter-router
Un custom-custom-processor permet de déclarer un filter personalisé.
Class-name doit indiquer le nom complet de la classe jouant le rôle de processor.
La classe doit respecter les conditions suivantes :
• Avoir un constructeur par défaut
• Implementer l’interface com.geoconcept.schedule.logic.circulation.Router.FilterRouter
• Etre thread-safe car ce tag ne crée qu’une instance, et que les processors peuvent être appellés en
parallèle lors de la reception simulatnée de messages.
Forward-router
Un forward router commence par envoyer le message à un autre router.
Selon le résultat, VRAI ou FAUX, il appelle respectivement success-router ou error-router.Enfin, resultrouter sera appelé avec comme données une un ForwardRouterResultData contenant les résultats des 2
routers précédents : router et success-router, ou router et error-router. Cette donnée peut être marshallée
grace à un com.geoconcept.schedule.logic.circulation.impl.ForwardResultDataXMLMarshaller, ou un
com.geoconcept.schedule.logic.circulation.impl.ForwardResultDataMarshaller.
Pour que le résultat final soit VRAI, il faut que le message ait été correctement traité par le dernier router
appelé, parmi les 3 routers « router », « success-router » et « error-router », result-router n’entrant pas en
ligne de compte.
Le resultat final renvoyé est VRAI dans les trois cas suivant :
• le message a bien été traité par le router :
16
Circulation-config
• et il n’y a pas de success router (1)
• et il y a un success router, et il réussit (2)
• le message n’a pas été traité par le router :
• mais il y a un error router et il réussit (3)
By-extapp-appointment-router
Il s’agit d’un objet spécifique au traitement de rendez-vous. Ce router va diriger le rendez-vous vers un
autre router en fonction de son champ « extapp ». Le champ « extapp », enregistré en base de données,
désigne l’application externe qui a initié le rendez-vous. Il faut donc configurer cet objet en spécifiant
dans extapp-router un router pour chaque valeur que peut prendre « extapp » en base de données.
Si un rendez-vous arrive sur ce router sans que son extapp ne puisse etre retrouvé dans la liste extapprouter, alors le default-router sera appellé.
By-extref-appointment-router
Il s’agit d’un objet spécifique au traitement de rendez-vous. Ce router va diriger le rendez-vous vers un
autre router en fonction de son champ « extref ». Extref est l’identifiant externe à Opti-Time du rendezvous : son identifiant dans un système tiers. (Application de gestion commerciale par exemple).
Le rôle simple de ce router est de séparer le traitement des rendez-vous selon s’ils ont ou non d’extref.
Avoir un extref signifie généralement que le rendez-vous doit être maintenu synchronisé avec une
application externe.
Check-status-appointment-router
17
Circulation
Il s’agit d’un objet spécifique au traitement de rendez-vous.
Ce router va filtrer le rendez-vous en fonction de son statut : Si son statut est inclus dans la liste
« include-status » alors il sera envoyé vers le router spécifié. Sinon, il sera ignoré.
Voici la liste des status-id disponibles :
0
Inconnu
21
Demandé
2
Planifié
6
Déplanifié
10
Annulé
40
Historisé
30
Réservé (« confirmé » pour K par K)
31
Confirmé («fixé » pour K par K)
3
Réalisé
Message-changer-router
Un message-changer-router, comme son nom l’indique est un routeur qui va remplacer le message en
cours de routage par un nouveau message texte, spécifié dans la balise « new-message ». Ce message
ne peut être que du texte.
Routers-distributor
Un routers-distributor distribue le même contenu alternativement à l’un des routers de la liste. Si l’un
des routeurs de renvoie pas un message de succes attendu, le message est alors émis vers le router
suivant (par exemple : une route peut ainsi être re-routée vers plusieurs Opti-Time, réalisant ainsi une
fonctionnalité élementaire de partage des charges ou failover).
18
Circulation-config
Appointment-notifier
Un appointment-notifier crée un message de toute pièce à partir des informations d’un appointment et
de ses différents membres configurés. Il inscrit dans le contexte de circulation les informations sur les
destinataires du message, le sujet du message et le message en lui même. Les sujets et messages
sont personnalisables avec des placeholders que l’appointment-notifier se chargera de remplacer par
les valeurs correspondantes parmi les membres de l’objet Appointment qui réside dans le membre
data du contexte de circulation. L’ensemble des placeholders disponibles est détaillé dans le document
Manuel_utilisateur_msg_de_notif.odt.
• L'élément origin-filter n’est actuellement pas pris en charge, il est défini dans l’intention de filtrer les
notifications sur leur provenance (la personne à l’origine de l'événement).
• L'élément dest permet de spécifier 3 sortes de destinataire du message qui doit être émis :
• CUSTOMER : le contact principal du site client
• CONTACT : le contact du rendez-vous
• RESOURCE : les ressources affectées au rendez-vous
• Les éléments msg et msg-subject contiennent tous deux des identifiants de ressources (messages
qui doivent être définis dans les fichiers notifier.properties). msg correspond à l’identifiant du message
principal, msg-subject correspond au sujet du message qui serait émis dans le cas d’un envoi d’email.
• L'élément output-medium défini le médium de sortie du message.
19
Circulation
Processor-routers
Un processor-router, par opposition aux filter-routers decrits précédemment sont des routers terminaux,
qui ne passent plus la main à d’autres router. Une chaine de router se termine toujours par un processorrouter. Il existe deux sortes de processor-routers : les indide-processors et les outside-processors.
Inside-processors
Les inside-processors sont des processor-routers qui ont une action à l’interieur d’Opti-Time.
Custom-inside-processor
Un custom-inside-processor permet de déclarer un processor personalisé.
Class-name doit indique le nom complet de la classe jouant le rôle de processor.
La classe doit respecter les conditions suivantes :
• Avoir un constructeur par défaut
• Implementer l’interface com.geoconcept.schedule.logic.circulation.Router
• Etre thread-safe car ce tag ne crée qu’une instance, et que les processors peuvent être appellés en
parallèle lors de la reception simulatnée de messages.
20
Circulation-config
Appointment-request-receiver
Un appointment-request-receiver est l’objet qui va traiter la demande de rendez-vous envoyée de
l’exterieur : elle va insérer, modifier ou supprimer le rendez-vous en base en fonction de la demande.
Appointment-request-receiver-new
Non documenté : Uniquement présent dans le XSD pour la mise au point du module. Ne doit pas être
utilisé.
Reference-data-receiver
Un appointment-request-receiver est l’objet qui va traiter la demande modification des données de
reference (resource humaine, site de travail, etc) : elle va insérer, modifier ou supprimer les données en
base en fonction de la demande.
csv-record-processor
Processeur d’import d’entités (resource humaine, site de travail, clients, rendez vous etc) à partir
d’enregistrements en mode texte csv. La première ligne définit les noms des champs, les lignes suivantes
les enregistrements à importer. Le typped’entité est détecté en fonction du nom des champs présents
(comme dans la fonction Importer CSV du module d’administration ). Ce routeur doit être associé à un
écouteur (listener) de type bulk-outside-listener , qui va lui transmettre un à un les lignes d’un fichier issu
d’un répertoire surveillé ou passé par une requête http.
Le processeur d’import doit être configuré selon la même logique que le dialogue d’import csv du module
d’administration (geocodage, worksite pour le geocodage par défaut, delimiter de texte, …)
sql-importer-processor
21
Circulation
Processeur d’import d’entités (resource humaine, site de travail, clients, rendez vous etc) à partir d’une
interrogation d’une table d’une base ou vue dans une base de donnée externe. Les enregistrements sont
obtenus par le texte de requête contenu dans l’attribut « select-clause ».
Les enregistrements retournés sont communiqués à un processeur d’import détecté d’après la
combinaison des noms de colonnes, suivant le modèle de l’import Opti-Time-CSV.
Un dictionnaire peut être associé au processor pour effectuer la correspondance entre nom de colonne
issu du select et nom de colonne du modèle d’import Opti-Time-CSV
Ce processeur permet également de modifier dynamiquement la requête, si la requête comporte des
ancrages (placeholders). Voir Le sous paragraphe suivant
Sql-script-processor
Permet d’exécuter des scripts SQL.
22
Circulation-config
On lui passe en paramètre une connexion SQL et l’emplacement d’un fichier script SQL.
Lorsqu’il est appelé, le script est exécuté sur la base de donnée définie dans la connexion SQL.
En cas d’erreur dans le traitement du script, on appelle le routeur d’erreur spécifié en paramètre « errorrouter ».
Le paramètre optionnel command-delimiter devrait permettre de spécifier le délimiteur entre 2
expressions SQL, mais il n’est encore implémenté.
Le paramétrage dynamique des imports sql (sql-script-processor, sql-importer-processor) .
Plusieurs méthodes et astuces existent pour la modification dynamique de la de la requête sql utilisée
dans un sql-importer-processor, ou dans un Sql-script-processor. Ces méthodes se basent sur la
détection, dans la chaine sql configurée pour le routeur, de balises d’insertions de paramètre, ou
« placeholders »
Placeholder implicite « ? » Si la requête comporte une where clause utilisant des « ? », ces points
d’interrogation sont remplacés par les paramètres portés par le contexte de circulation dans l’ordre où ils
ont été transmis à ce contexte:
Exemple :
select * from exch_customer where ordererid=? And requiredresources = ?
Dans cet exemple, les deux points d’interrogation sont remplacés par les deux premiers paramètres issus
du contexte de circulation qui les a recçu d’un maillon précédent de la chaîen de circualtion. Par exemple,
si le processeur est associé à une requête http (listener d’un http-medium ), et que l’utilisateur (via une
page web ) a invoquué ce médium
http://<serveur>/gss/circulation/mediumhttp?param1=a,param2=b.
On utilisera les paramètres successifs de la requête (a et b) pour les inscrire dans celle ci sous cette
forme
select * from exch_customer where ordererid='a' And requiredresources = 'b'
Note : les paramètres sont toujours remplacés avec un encadrement en quote simple, correspondant à la
norme sql pour les chaînes de caractères
L’usage des palceholder « ? » est assez limitatif (nommage implicite des paramètres) et on lui préfère
l’usage des placeholders nommés Placeholder « :<nomdeVariable »'Si la requête comporte des
placeholders nommés par des noms de variables connus du contexte de circulation, ils sont remplacés
par des valeurs correspondantes
Exemple :
select * from exch_customer where ordererid=:ordererid And requiredresources = :myresources
Dans ce cas, les châines :ordererid et :myresources sont remplacés par les deux premiers paramètres
issus du contexte de circulation , quels qu’ils soient, par exemple , si le processeur est associé à une
23
Circulation
requête http (listener d’un http-medium ), par exemple http://<serveur>/gss/circulation/mediumhttp?
ordererid=a,otherparam=c,myresources=b. on utilisera les paramètres a et b de la requête http pour
rédiger la requête sql suivante
select * from exch_customer where ordererid='a' And requiredresources = 'b'
L’utilisation des placeholders nommés est fortement recommandée car elle permet d’exploiter des
variables véhiculées automatiquement dans certains contextes de circulation comme :
• :AREAID : la référence externe de la région : forunie par les listeners d’optimisation, ou les listeners de
modification de rendez vous ou de customer
• :OPTIMIZATIONSTARTDATE la date de début de la période d’optimisation, fournie par le listener de
déclenchement des optimisations batch
• :OPTIMIZATIONENDDATE la date de fin de la période d’optimisation, fournie par le listener de
déclenchement des optimisations batch
• :ENTITYID la référence externe de l’entité, fournie les listeners de modification de rendez vous ou de
customer
• :APPOINTMENTID : la référence externe de l’entité,fournie par les listeners de modification de rendez
vous
• :RESOURCEID : la référence externe de la ressource assigéne au rendes vous ,fournie par les
listeners de modification de rendez vous
• :LastImportedDate : la date système , au format ODBC canonique « yyyy-MM-dd HH:mm:ss.sss »
recueillie jurste avant le lancement du dernier import par le processeur d’import sql…
Astuce : réalisation d’un import sql temps réel avec le paramètre :LastImporteddate
On peut utilemen combiner une table comportant une colonne d’horodatage des modifications (par
triggers ou valeur par défaut dynamique) avec le paramèrte :LastImportedDate, pour contraindre OptiTime a sélectionner les dernières lignes modifiées dans une table depuis le précédent import. Cette
méthode est robuste car le paramètre est stocké dans la table de configuration Opti-Time. Suivant
les moteurs de base de données, la difficulté réside dans la rédaction de la syntaxe en prenant en
compte les spécificités de format de chaque provider. Des scripts d’exemples sont fournis dans les
livraisons Opti-Time , pour les wher clause 'ODBC canoniques », et pour la constitution de champ
« LastUpdateDate » dans les tables d'échanges « modèles »
Exemple en Microsoft sql server
select * from exch_APPOINTMENT
where DATEDIFF(SECOND,lastUpdate,CONVERT(datetime,:LastImportedDate,121) ) < 0
Exemple en Oracle
select * from exch_APPOINTMENT
where ( lastUpdate > to_timestamp(:LastImportedDate,'YYYY-MM-DD HH24:mi:ss.ff4'); )
Opti-Time-services-processor
24
Circulation-config
Permet d’invoquer un sous-service interne identifié par un nom de service. Le comportement de ce
service peut être modulé par le paramètre passé dans l’attribut parameter. Cet outil est généralement
utilisé en terminaison d’une route recueillant une requête http (http-input-medium) et passant les données
XML postées dans la requête en entrée du service en question.
Parmi les services actuellement disponibles : le geocodage, l’obtention d’itinéraire, le « routage » (ou
ordonnacement ) calcul d’une route optimisée entre étapes d’une ressource pour une journée.
En règle générale, il s’agit de services de consultation qui ne modifient pas l'état interne de la base OptiTime. Leur incorporation à l’ensemble « inside-processor » est donc surtour formelle et historique.
command-processor
Permet d’exécuter une commande système. La commande est stockée dans l’attribut full-path. Des
arguments peuvent être données avec la liste de tag arguments.Prendre garde au fait que la commande
système doit être executable par l’utilisateur système agissant au travers d’un service ou démon. Ce
routeur peut être utilement utilisé pour traiter un fichier émis dans un répertoire par un simpel-medium
sender.
Outside-processors
Par opposition aux inside-processors, les outside-processors vont effectuer un traitement en direction de
l’exterieur d’Opti-Time.
Simple-medium-sender
Une instance de simple-medium-sender sert à envoyer un message vers un output-medium. Le
marshaller spécifié est l’objet capable de transformer les données à envoyer en flux de données pour le
output-medium.
25
Circulation
csv-record-export-processor
Routeur destiné à l’emission de données vers l’exterieu, au format csv, en réponse à une stimulation
interne programmée (instant-inside-listener ou optimization-listener).
Les données à exporter sont définis par la liste de champs fourni dans l’attribut listField. Cette liste fournit
une combinaison de champs qui permet de détecter un processeur d’export, conformément au modèle
Opti-Time-CSV. De nombreux attributs sont disponibles pour moduler le comportement et le périmètre de
l’export :
• separator : caractère de séparation des champs (par défaut ",")
• textDelimiter : caractère d’encadrement des données textuelles (par défaut ')
• valueListSeparator : caractère de séparation des valeurs des listes de valeurs exportées dans certains
champs (par défaut ;). Ce caractère doit évidemment être différent du caractère de séparation des
champs.
• dateFormat : format d'écrtiture souhaité pour les valeurs dates, rédigé suivant le pattern java
( default="yyyy/MM/dd" )
• timeFormat : format d'écrtiture souhaité pour les valeurs heures et durée (défaut hh:MM)
• useDurationTimeFormat : mettre à true/vrai/O/Y/1 pour indiquer que l’export des durées s’effectue
sous forme formattée comme une heure (utilisant timeFormat). Sinon, les durées sont exportées par un
entier, en nombre de minutes.
• extractionKind : mot clef définissant le sous-ensemble des entités à exporter, parmi les entités détectés
en fonction de la liste des champs. les valeurs existantes sont :
• ALL : exporte toutes les entités.
• LASTUPDATED : exporte les dernières entités crées ou modifiées (disponible pour certaines
collections d’entités comme les rendez vous ou les indisponibilités).
• extractionParam : paramètre additionnel passé au processeur. Par exemple « 1 » donne le nombre de
jours à rétro inspecter pour l’export des derniers modifiés dans la stratégie LASTUPDATED. Le default
est "1" (ce qui signifie depuis le dernier jour si la stratégie LASTUPDATED ). L’export est déclenché.
Par un listener d'évenement interne, (trigger periodic, AppointmentInsideListener) ou par une stimulation
externe (requête http par exemple). Comme pour un Simple-medium-sender, le résultat est communiqué
à un output-medium, à l’aide d’un marshaller standard (transformation de texte).
sql-exporter-processor
26
Circulation-config
Routeur destiné à l’emission de données vers l’exterieur, au moyen d’un ordre sql. Ce routeur est activé
et extrait les données Opti-Time comme le routeur csv-recors-export-processor. En revanche, il n’a pas
besoin de medium de sortie, car son flux sortant est directement émis via la connection sql.
On retrouve les paramètres permettant de délimiter le périmètre à exporter, lorsque le routeur n’est pas
situé en sortie d’un écouteur de notification de mise à jour d’une entité spécifique :
• list-field : liste (séparée par une virgule) des champs Opti-Time-CSV à exporter. La combinaison des
noms permet aussi la détection sans ambiguïté des classes d’entités à exporter.
• attribut extractionKind : mot clef définissant le sous-ensemble des entités à exporter, parmi les entités
détectés en fonction de la liste des champs. les valeurs existantes sont :
• ALL : exporte toutes les entités.
• LASTUPDATED : exporte les dernières entités crées ou modifiées (disponible pour certaines
collections d’entités comme les rendez vous ou les indisponibilités).
• attribut extractionParam : paramètre additionnel passé au processeur. Par exemple « 1 » donne le
nombre de jours à rétro inspecter pour l’export des derniers modifiés dans la stratégie LASTUPDATED.
Le default est "1" (ce qui signifie depuis le dernier jour si la stratégie LASTUPDATED). L’export est
déclenché.
On a ensuite les paramètres décrivant la cible
• table: le nom de la table externe à mettre à jour (il peut s’agir d’une vue).
• action : le type d’action à effectuer : les valeurs admises sont :
• UPDATE_INSERT (par défaut) Tente un update à l’aide du champ associé à l’ID (externe) puis, si
aucun enregistrement n’a été mis à jour, tente une insertion (la table doit posséder une clef primaire
en auto-increment, les séquences ne sont pas prises en compte pour le moment) ;
• UDPATE : Tente exlusivement un update ;
• INSERT : effectue exclusivement un insert ;
27
Circulation
• DELETE : détruit les lignes pour l’ID de chaque enregistrement exporté ;
• DELETEALL: détruit toutes les lignes.
• where-clause une where clause additionnelle ajoutée à l’ordre généré, qui comporte éventuellement
déjà une where clause, pour UPDATE et DELETE where ID=IdValue. IL est donc inutile de rajouter le
mot « WHERE ».
• dictionary référence à un dictionnaire pour effectuer la correspondance des champs.
Mediums
Les mediums sont des moyens de communications : ils sont soit input-medium, c’est à dire destinés à
être lus par Opti-Time, soit output, destinés à être écrits par Opti-Time.
Input-mediums
4 sortes d’inputs mediums sont proposés : jms-input-queue, directory-input-medium, mailbox-inputmedium et http-input-medium.
Jms-input-queue
Un jms-input-queue est un lien vers une queue JMS. Le nom JNDI de la queue doit être entrée dans la
balise « jndi-name ».
Il faut également associer une connection jms : La balise jms-connection doit contenir l’id de la
connection déclarée plus loin.
Directory-input-medium
Un directory-input-medium spécifie un répertoire à écouter, ou chaque fichier sera considéré comme un
message. Ce medium parcourt régulièrement le répertoire pour découvrir les fichiers.
28
Circulation-config
Les paramètres sont les suivants :
• location : le chemin complet du répertoire. Si le répertoire n’existe pas, il est automatiquement créé.
• Message-selector : l’une des valeurs suivantes : « addedFiles » , « allFiles » ou « filesList ».
• addedFiles signifie qu’a chaque parcours du répertoire, seuls les fichiers qui viennent d'être ajoutés
seront pris en compte
• allFiles signifie qu’a chaque lecture du répertoire, tous les fichiers présents seront pris en compte.
(optionnel, par defaut : addedFiles)
• filesList permet de définir une liste de mots clés qui représentent la "racine" que doivent contenir les
noms des fichiers présents dans le répertoire avant de déclencher leur notification. La liste de mots
clés doit être séparée par des |. L’ordre de notification des fichiers sera alors fixé par celui des mots
clés correspondants. Dans le cas où les noms de plusieurs fichiers contiendraient l’un des mots clés,
le fichier le plus ancien sera traité en premier dans le premier lot de notifications.
• scan-time-interval : l’espace de temps entre chaque parcours du répertoire, en millisecondes.
(optionnel : ne doit pas être specifié conjointement à directory-trigger ou instant-trigger)
• delete-on-success : ignoré (toujours à true)
• nb-max-try : nombre de tentatives maxi avant abandon et déplacement du fichier dans failure-trashlocation
• failure-trash-location : répertoire poubelle des fichiers qui ont été abandonnés à la suite de nb-max-try
tentatives.
29
Circulation
• directory-trigger : l’ID d’un directory-trigger (voir plus loin). Ne doit pas être utilisé conjointment à scantime-interval ou instant-trigger.
• Instant-trigger : l’ID d’un instant-trigger qui générera l'événement de scrutation du répertoire. Ne doit
pas être utilisé conjointment à scan-time-interval ou directory-trigger.
• Trigger-files-list : Une liste de mots clés permettant d’attendre que chacun des mots clés trouve un
fichier dans le répertoire du medium dont le nom le contienne, avant de lancer les notifications.
• charset-name : Le nom du charset à utiliser pour lire les fichiers.
Exemple de fonctionnement du mode « filesList » :
Si on a :
• mots clés : "gss_commandes|gss_clients|gss_absences_techniciens"
• et les fichiers :
• gss_commandes_05-06-11.csv datant du 05/06/11
• gss_commandes_06-06-11.csv datant du 06/06/11
• gss_clients_05-06-11.csv datant du 05/06/11
• gss_absences_techniciens_05-06-11.csv datant du 05/06/11
Seul l’import des fichiers du 05/06/11 sera déclenché … Le fichier gss_commandes du 06/06/11 devra
attendre l’arrivée de 2 autre fichiers contenant les mots clés gss_clients et gss_absences_techniciens
pour que son lot soit importé.
Mailbox-input-medium
Un mailbox-input-medium spécifie une boite à lettre à écouter, ou chaque mail reçu ou fichier attaché
sera considéré comme un message. Ce medium interroge régulierement le serveur de mail.
30
Circulation-config
Les paramètres sont les suivants :
• Une des deux balises suivantes doit être indiquée :
• Jndi-name contient le nom jndi de l’objet javax.mail.Session utilisé pour envoyer le mail.A utiliser
quand circulation est executé dans un serveur JEE.
• mail-session contient l’identifiant se referant à une balise mail-session déclaré dans la balise
« connections ». A utiliser lorsque le code est executé en dehors d’un serveur JEE. Par exemple
dans les tests unitaires.
• Folder : Le nom du dossier de mail à écouter. (optionnel, par défaut INBOX)
• Username : Le nom de l’utilisateur à utiliser pour s’authentifier auprès du serveur de mail.
• Password : Le mot de passe de l’utilisateur à utiliser pour s’authentifier auprès du serveur de mail.
• Cron-periodicity : L’expression « cron » permettant de spécifier la periodicité d’interrogation du serveur
de mail.Voir annexe « Expressions Cron »
Exemples :
• Toutes les dix secondes : 0/10 * * * * ?
• Tous les jours à midi : 0 0 12 * * ?
• Toutes les 5 minutes de 14 heures à 14h55 : 0 0/5 14 * * ?
• Delete-on-success : ignoré (toujours à true)
• handle-raw : valeur booleéene : true ou false. Indique si le corps du mail brut doit être traité comme un
message.
• handle-attachment : valeur booleéene : true ou false. Indique que les pièces attachées ayant des nom
de fichier doivent être traité comme des messages.
• handle-inline : valeur booleéene : true ou false. Indique que les pièces attachées sans nom de fichier
doivent être traité comme des messages.
Http-input-medium
Un http-input-medium permet d'écouter sur le port HTTP de l’application Web.
Si la page de login d’Opti-Time est accédée via :
http://myserver:myport/gss/
Alors circulation écoute tous les messages envoyés sur des url de la forme :
http://myserver:myport/gss/circulation/myInputMediumName
31
Circulation
Par exemple :
La déclaration de :
<http-input-medium>
<id>myInput</id>
<name>plateforme123</name>
</http-input-medium>
Entrainera l'écoute de :
http://myserver:8080/gss/circulation/plateforme123
• "Opti-Time" est le nom de l’application
• "circulation" est le préfixe non configurable
• "plateforme123" est le nom de l’input spécifié dans sa balise "name".
Fonctionnement
Un http-input-medium se comporte de façon similaire aux autres input-medium : il écoute les message et
le transmet à son listener déclaré par ailleurs. Le message est attendu dans le corps de la requete HTTP
en méthode POST (sans variable HTTP).
Il est possible de passer, pour des raisons de mise au point, le message en méthode GET dans la
variable "message", par exemple :
http://localhost:8080/gss2.5/circulation/KPK30?message=<request><info.....
Le retour de message
Le retour d’une requête HTTP auprès de de circulation est toujours un message XML, conforme au
schéma "circulation-result" (voir chapitre Référence : Format de retour : schéma "circulation-result", page
44). Ce document de retour contiendra toujours la valeur "success" (à true ou false). Et selon le type de
retour, des explications sommaires ("explanation") ou détaillées ("message-info").
Techniquement cet écouteur est implémenté par une servlet. Cette servlet "CirculationServlet" est
déclarée dans le fichier web.xml. Une telle servlet partage le pool de thread avec les autres servlets (et
donc l’ihm). Une seule servlet "CirculationServlet" peut être déclarée par Opti-Time. Les threads sont
synchronisés sur le nom spécifié par name : Les messages arrivant sur deux url différentes seront traités
en parallèle, ceux arrivant sur des url identiques seront traitées en série.
Element synch :
Sur versions > 3,31, l’element synch peut être positionné à false pour permettre de traiter en série les
messages arrivant sur une même url. Ce comportement ne doit être appliqué que pour des messages
sans effets de bords ni risques de concurrence d’accès (exemple une requête de geocodage, mais pas
une création de client)
32
Circulation-config
Output-mediums
Les output-mediums sont des moyens de communication en sortie.
jms-output-queue
Un jms-output-queue est un lien vers une queue JMS sur laquelle on souhaite envoyer des messages. Le
nom JNDI de la queue doit être entrée dans la balise « jndi-name ».
Il faut également associer une connection jms : La balise jms-connection doit contenir l’id de la
connection déclarée plus loin.
• Delivery-mode : Pas encore implementé : Tous les messages envoyés sont en mode « persistant ».
Directory-output-medium
Un directory-output-medium spécifie un répertoire sur lequel écrire, ou chaque message sera écrit sous
forme d’un fichier (un fichier par message).
Paramètre :
• location : le nom complet du répertoire dans lequel créer des fichier.
• Prefix : une chaîne préfixe de tous les fichiers.
• Suffix : une chaîne suffixe de tous les fichiers. (typiquement l’extension).
33
Circulation
Le nom du fichier est construit selon la forme suivante :[prefix][date, heure precise de la création du
fichier][suffix]
Exemple : Si prefix= « MESSAGE » et suffixe= « .XML », le fichier aura la forme suivante :
MESSAGE 2005.02.14 14h57m17s715ms.XML
• Filename-pattern : une chaîne libre représentant le nom du fichier, à l’intérieur de laquelle les souschaînes {0},{1},{2},{3},{4},{5},{6} sont respectivement remplacées par :
• la date du jour
• l’identitifant du message
• le nom du medium
• le nom du support
• l’indicateur du nombre de ligne (pour les messages « bulks »)
• le nom du contexte de circulation
• un numéro au hasard
Bien sûr, l’utilisation de filename-pattern est une alternative à celle des prefixe/suffixes
Exemple : Si filename-pattern =result-{0}-{3}-{6}.csv, le fichier aura la forme suivante :
result-2009.09.24_09h44m14s037ms-Simulation_priseRDV_40-577525.csv
file-output-medium
File-output-medium est un medium qui ecrit les messages dans un fichier unique, les messages étant
insérés les uns derrière les autres. C’est typiquement ce qui est utilisé pour remplir un fichier de logs.
• Location désigne le chemin complet du fichier.
• roll-size la taille maximale du fichier, en kilo octets : une fois atteinte cette taille, le fichier est recopié
(avec la date et l’heure dans le nom), et on repart sur un fichier vide.
Mail-output-medium
Mail-output-medium est le medium capable d’envoyer un email.
• Une des deux balises suivantes doit être indiquée :
• Jndi-name contient le nom jndi de l’objet javax.mail.Session utilisé pour envoyer le mail.A utiliser quand
circulation est executé dans un serveur JEE.
34
Circulation-config
• mail-session contient l’identifiant se referant à une balise mail-session déclaré dans la balise
« connections ». A utiliser lorsque le code est executé en dehors d’un serveur JEE. Par exemple dans
les tests unitaires.
• From doit contenir l’adresse de l’expéditeur des emails.
• To doit contenir l’adresse du destinataire.
• Subject doit contenir le texte qui apparaîtra dans le sujet du mail.
Le corps du mail sera rempli avec ce que le marshaller produit . (Le marshaller est celui designé dans le
simple-medium-sender associé à ce medium).
Http-output-medium
Un Http-output-medium permet d’envoyer sur une URL via la méthode POST.
Le message est considéré comme envoyé si l’URL a bien répondu et a répondu avec un status HTTP =
200 (OK).
Log
Log ecrit les message directement dans le fichier de log général d’Opti-Time.
• Prefix est un texte inséré devant chaque message loggué.
Mail2sms-output-medium
Un mail2sms-output-medium permet d’envoyer un SMS en passant par une interface
SMTP d’un fournisseur de SMS. En envoyant un email à l’adresse numero_de_tel@mail
[mailto:numero_de_tel@mail]_domain_name, le contenu du mail est envoyé au numéro de téléphone de
l’adresse email.
35
Circulation
Un mail2sms-output-medium est défini comme un mail-output-medium avec simplement le paramètre
mail-domain-name en plus qui permet de définir le nom de domaine du fournisseur de SMS.
Sms-output-medium
Un sms-output-medium permet d’envoyer un SMS au moyen d’une interface HTTP d’un fournisseur de
SMS.
• L'élément url défini l’URL du serveur ciblé en HTTP.
• L'élément verb permet de préciser si l’envoi des variables doit se faire en GET ou en POST.
36
Circulation-config
• L'élément respAnalyzer représente une routine d’analyse de la réponse du serveur (à une requête)
pour déterminer si l’envoi a été correctement effectué. Dans le cas d’utilisation d’un serveur Esendex,
utiliser la valeur « Esendex ».
• Chaque élément de query-params représente ensuite une variable de requête HTTP. Pour un queryparam donné, un élément var-name représente le nom de la variable HTTP concernée.
• Un élément var-marshaller permet de définir comment sera remplie cette variable. Les possibilités sont
les suivantes :
• LOGIN : l’utilisateur du compte chez le fournisseur d'énvoi de SMS sera récupéré dans l'élément varvalue
• PASSWORD : le mot de passe du compte chez le fournisseur d’envoi de SMS sera récupéré dans
l'élément var-value
• PHONE : le numéro de téléphone destinataire
• CIRC_MESSAGE : la variable doit être remplie avec le message provenant du contexte
• RESOURCE_MESSAGE : la variable doit être remplie avec message dont l’identifiant de ressource
sera récupéré dans l'élément var-value.
• UNKNOWN : pas de traitement particulier pour cette variable (on utilise la valeur fournie dans
l'élément var-value)
Url-output-medium
L’url-output-medium est défini et fonctionne de la même manière qu’un directory-output-medium. Avec la
possibilité supplémentaire de pouvoir prendre en charge des URL FTP.
Transformers
37
Circulation
Les transformers sont soit des « marshaller », soit des « unmarshallers », c’est à dire des objets dont le
role est de transformer respectivement des objets Java en flux texte, ou du flux texte en objets Java.
Une nouvelle catégorie de transformer existe depuis la version 1.3 de circulation : Les cursors-factories,
qui permettent de découper un message en plusieurs sous-messages.
Unmarshallers
Unmarshallers contient la liste des unmarshallers. Il n’existe aujourd’hui qu’une seule sorte
d’unmarshaller : les by-class-appt-unmarshallers.
By-class-appt-unmarshaller
Un by-class-appt-unmarshallers permet de créer un objet unmarshaller à partir d’un nom de classe Java.
Remarque : Aujourd’hui ce modèle de fonctionnement n’est pas toujours opérationnel, et la plupart du
temps, vous utiliserez des PseudoUnmarshaller. Appuyez vous sur le circulation-config fourni en exemple
pour savoir comment configurer ces objets.
Marshallers
By-class-appt-marshaller
Un by-class-appt-marshallers permet de créer un objet marshaller à partir d’un nom de classe Java.
Même remarque que pour les unmarshallers.
Quelques marshallers prédéfinis
38
Circulation-config
Cette partie de la documentation et du module de circulation restent à finaliser.
Aujourd’hui il est possible de spécifier les marshaller par nom de classe.
Les noms de classes disponibles sont :
• com.geoconcept.schedule.logic.circulation.impl.PseudoMarshaller
• A utiliser par défaut.
• com.geoconcept.schedule.logic.circulation.impl.appointment.AppointmentXMLMarshaller
• A utiliser en bout d’un circuit initié par un AppointmentInsideListener
• com.geoconcept.schedule.logic.circulation.impl.DiagnosticDataMarshaller ou
com.geoconcept.schedule.logic.circulation.impl.DiagnosticDataXMLMarshaller
• A utiliser au bout d’un circuit commençant par le diagnostic-router d’un outside-listener
• com.geoconcept.schedule.logic.circulation.impl.ForwardResultDataMarshaller ou
com.geoconcept.schedule.logic.circulation.impl.ForwardResultDataXMLMarshaller
• A utiliser au bout d’un circuit commençant par le result-router d’un forward-routed
Les deux marshallers com.geoconcept.schedule.logic.circulation.impl.DiagnosticDataXMLMarshaller
com.geoconcept.schedule.logic.circulation.impl.ForwardResultDataXMLMarshaller générent les données
qui respectent le même schéma XML : circulation-result.
Cursor-factories
Les cursors-factories permettent de découper un message en plusieurs sous-messages.
Il n’existe aujourd’hui qu’une seule sorte de cursor-factory : les line-by-line-cursor-factory
line-by-line-cursor-factory
Un line-by-line-cursor-factory comme son nom l’indique est capable de fabriquer un curseur de parcours
de texte ligne à ligne. Il permet donc de découper un message sous-messages constitués de chacune
des lignes du message initial.
Connections
Les connections referent des connections vers l'éxterieur d’Opti-Time. Il n’existe aujourd’hui deux sortes
de connection : Les connections JMS, et les connections aux serverur de mail (« mail-session »).
39
Circulation
Jms-connection
Les jms-connections représentent des connections JMS.
• Factory-jndi-name est le nom JNDI d’un ConnectionFactory.
• Reconnection-delay est le délai de tentative de reconnection en cas de perte de cette connection.
Mail-session
Les mail-session représentent des données de connections aux serveur de mail.
• Store-protocol est le protocole de stockage, c’est à dire « pop3 » ou « imap »
• transport-protocol est le protocole de transport, c’est à dire
sql-connection
Les sql-connections représentent des connections jdbc. Elles sont requises par les processeurs d’import
ou d’export SQL.
• driver : le nom de classe jdbc du driver
• ConnectionString : la chaîne de connection jdbc
• si nécessaire : le mot de passe et nom de compte d’authentification
40
Circulation-config
• L'élément synchronized optionnel (valeur par défaut = true ) permet de définir le comportement de la
conenciton sql si elle est sollicitée par plusierus routeurs. Si synchronized est à true, les processeurs
qui requière accès à cette connection sont mis en attente par le processeur qui l’utilise actuellement.
root-path-connection
Il permet de factoriser un chemin racine commun à plusieurs définitions de chemins relatifs dans les
routeurs directory-input-medium, directory-output-medium, url-input-medium, url-output-medium, fileoutput-medium. Bien sûr, si le tag <root-path-connection> n’est pas défini dans ces routeurs, on suppose
que les chemins saisis sont absolus.
Son utilisation repose sur le principe d’une concaténation des chemins définis dans les routeurs au
chemin racine.
Triggers
Les triggers sont des objets déclencheurs d'événements.
Directory-trigger
Un directory-trigger scanne un ou plusieurs répertoire toutes les N millisecondes, N spécifié dans scantime-interval.
A noter que l’on ne spécifie pas ici la liste des répertoires à scanner : Ce sont les directory-input-medium
qui demandent à leur directory-trigger de scanner leur répertoire.
Note : L’utilisation d’un trigger est optionnel dans directory-input-medium, mais est fortement conseillé
quand beaucoup de directory-input-medium sont configurés : Cela permet de mutualiser les opérations
de scan de répertoire, c’est à dire de ne consommer qu’une seule thread pour l’ensemble des répertoire,
au lieu d’une thread par répertoire.
Instant-trigger
Un instant-trigger permet de déclencher des événements à des dates programmées.
On peut les paramétrer soit avec un décompte de minutes avant départ plus une périodicité :
• startMinute : nombre de minutes à attendre avant le premier événement
• period : unité d’expression de la durée périodique
• InstantTrigger.UNIT_MINUTE = 0
• InstantTrigger.UNIT_DAY = 1
• InstantTrigger.UNIT_WEEK = 2
• periodLength : durée périodique entre chaque événement généré.
41
Circulation
Soit directement avec une expression cron (cf ANNEXE 1 : Les Expressions Cron) : * cron-periodicity :
chaîne expression cron
L'élément synchronized optionnel (valeur par défaut = true ) permet de définir le comportement du trigger
lordqu’il se déclenche tandis que l'évenement déclenché plus tôt n’est pas terminé. Si synchronized est à
true, on ne peut pas déclencher l'évenement si le précédent est toujours en cours. De ce fait, l'évenement
est simplement annulé, et se redéclenchera à la prochaine période. La synchronisation est hautement
recommandée pour les triggers de fréquence brève déclenchant des processeurs d’import (sql, csv…) de
façon quasi continue.
Interruptors
Les interruptors sont des objets capables d’interrompre et de redémarrer les listener. Il n’existe qu’une
seule sorte de déclencheur aujourd’hui : les business-lock-interruptors.
Business-lock-interruptors
Un business-lock-interruptor est un objet capable d’interrompre un listener en cas de verrouillage d’une
ressource de l’application, par exemple d’une région.
Il arrête le listener (et le médium associé) au moment du verrouillage et le redémarre au moment du
déverrouillage.
• Resource-type doit contenir le nom du type de « ressource » verrouillée. La seule valeur possible
aujourd’hui est LOCK_APPOINTMENTS_ON_REGION.
• Selector est le selecteur de resource. Dans le cas où resource-type =
LOCK_APPOINTMENTS_ON_REGION, selector doit contenir l’identifiant externe de la région.
• Listener-to-interrupt doit contenir l’id du Listener à interrompre.
Exemple :
<interruptors>
<business-lock-interruptor>
<id>KPK30LockInterruptor</id>
<resource-type>LOCK_APPOINTMENTS_ON_REGION</resource-type>
<selector>DRS30</selector><!--region extref-->
<listener-to-interrupt>KPK30listener</listener-to-interrupt>
</business-lock-interruptor>
</interruptors>
Référence : Format de retour : schéma "circulation-result"
Le format de retour généré par les masrshallers DiagnosticDataXMLMarshaller et
ForwardResultDataXMLMarshaller, ainsi que par tout listener branché sur un http-input-medium est
spécifié dans le schéma XML "circulation-result" :
42
Référence : Format de retour : schéma "circulation-result"
Un document circulation-result n’est composé que d’un seul router-result, contenant les balises
suivantes. Toutes ces balises sont optionnelles.
success
Type : Standard XMLSchema booléen, (true ou false).
43
Circulation
Indique si le traitement du message s’est déroulé correctement ou non.
error-explanation
Type : chaine de caractères Contient une éventuelle explication textuelle de l’erreur
error-code
Type : chaine de caractères Contient un éventuel code d’erreur, sous forme de chaine.
Cette chaîne dépend du traitement effectuée. Aujourd’hui l’une des valeurs suivantes :
• ERROR : Erreur générale, pas de code spécifique.
• PARSE_ERROR : Erreur pendant le parsing du message reçu.
• IMPORT_ERROR : Erreur pendant l’import du message.
• LOCK : Traitement impossible car verrouillage en cours.
message-info
Contient éventuellement des informations sur le message ayant provoqué une erreur. Voir schéma plus
haut pour les détails des balises internes.
briefs
Liste de message d’erreur ou de succès pour chaque element d’un traitement en lot.
message
non implémenté.
44
ANNEXE 1- Les Expressions Cron
ANNEXE 1- Les Expressions Cron
Issus de la documentation de la librairie Java « Quartz » :
A "Cron-Expression" is a string comprised of 6 or 7 fields separated by white space. The 6 mandatory and
1 optional fields are as follows:
Field Name
Allowed Values
Allowed Special Characters
Seconds
0-59
,-*/
Minutes
0-59
,-*/
Hours
0-23
,-*/
Day-of-month
1-31
,-*?/LWC
Month
1-12 or JAN-DEC
,-*/
Day-of-Week
1-7 or SUN-SAT
,-*?/LC#
Year (Optional)
empty, 1970-2099
,-*/
The character is used to specify all values. For example, "" in the minute field means "every minute".
The ? character is allowed for the day-of-month and day-of-week fields. It is used to specify no specific
value. This is useful when you need to specify something in one of the two fileds, but not the other. See
the examples below for clarification.
The - character is used to specify ranges For example "10-12" in the hour field means "the hours 10, 11
and 12".
The , character is used to specify additional values. For example "MON,WED,FRI" in the day-of-week
field means "the days Monday, Wednesday, and Friday".
The / character is used to specify increments. For example "0/15" in the seconds field means "the
seconds 0, 15, 30, and 45". And "5/15" in the seconds field means "the seconds 5, 20, 35, and 50". You
can also specify / after the character - in this case is equivalent to having 0 before the /.
The L character is allowed for the day-of-month and day-of-week fields. This character is short-hand for
"last", but it has different meaning in each of the two fields. For example, the value "L" in the day-of-month
field means "the last day of the month" - day 31 for January, day 28 for February on non-leap years. If
used in the day-of-week field by itself, it simply means "7" or "SAT". But if used in the day-of-week field
after another value, it means "the last xxx day of the month" - for example "6L" means "the last friday of
the month". When using the L option, it is important not to specify lists, or ranges of values, as you’ll get
confusing results.
The W character is allowed for the day-of-month field. This character is used to specify the weekday
(Monday-Friday) nearest the given day. As an example, if you were to specify "15W" as the value for the
day-of-month field, the meaning is: "the nearest weekday to the 15th of the month". So if the 15th is a
Saturday, the trigger will fire on Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the
16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th. However if you specify "1W" as the
value for day-of-month, and the 1st is a Saturday, the trigger will fire on Monday the 3rd, as it will not jump
45
Circulation
over the boundary of a month’s days. The W character can only be specified when the day-of-month is a
single day, not a range or list of days.
The L and W characters can also be combined for the day-of-month expression to yield LW, which
translates to "last weekday of the month".
The # character is allowed for the day-of-week field. This character is used to specify "the nth" XXX day
of the month. For example, the value of "6#3" in the day-of-week field means the third Friday of the month
(day 6 = Friday and "#3" = the 3rd one in the month). Other examples: "2#1" = the first Monday of the
month and "4#5" = the fifth Wednesday of the month. Note that if you specify "#5" and there is not 5 of the
given day-of-week in the month, then no firing will occur that month.
The C character is allowed for the day-of-month and day-of-week fields. This character is short-hand for
"calendar". This means values are calculated against the associated calendar, if any. If no calendar is
associated, then it is equivalent to having an all-inclusive calendar. A value of "5C" in the day-of-month
field means "the first day included by the calendar on or after the 5th". A value of "1C" in the day-of-week
field means "the first day included by the calendar on or after sunday".
The legal characters and the names of months and days of the week are not case sensitive.
Here are some full examples:
Expression
Meaning
"0 0 12 * * ?"
Fire at 12pm (noon) every day
"0 15 10 ? * *"
Fire at 10:15am every day
"0 15 10 * * ?"
Fire at 10:15am every day
"0 15 10 * * ? *"
Fire at 10:15am every day
"0 15 10 * * ? 2005"
Fire at 10:15am every day during the year 2005
"0 * 14 * * ?"
Fire every minute starting at 2pm and ending at 2:59pm, every
day
"0 0/5 14 * * ?"
Fire every 5 minutes starting at 2pm and ending at 2:55pm,
every day
"0 0/5 14,18 * * ?"
Fire every 5 minutes starting at 2pm and ending at 2:55pm,
AND fire every 5 minutes starting at 6pm and ending at
6:55pm, every day
"0 0-5 14 * * ?"
Fire every minute starting at 2pm and ending at 2:05pm, every
day
"0 10,44 14 ? 3 WED"
Fire at 2:10pm and at 2:44pm every Wednesday in the month
of March.
"0 15 10 ? * MON-FRI"
Fire at 10:15am every Monday, Tuesday, Wednesday,
Thursday and Friday
"0 15 10 15 * ?"
Fire at 10:15am on the 15th day of every month
"0 15 10 L * ?"
Fire at 10:15am on the last day of every month
"0 15 10 ? * 6L"
Fire at 10:15am on the last Friday of every month
"0 15 10 ? * 6L"
Fire at 10:15am on the last Friday of every month
"0 15 10 ? * 6L 2002-2005"
Fire at 10:15am on every last friday of every month during the
years 2002, 2003, 2004 and 2005
46
ANNEXE 1- Les Expressions Cron
"0 15 10 ? * 6#3"
Fire at 10:15am on the third Friday of every month
Pay attention to the effects of ? and * in the day-of-week and day-of-month fields!
• NOTES: *
• Support for the features described for the C character is not complete.
• Support for specifying both a day-of-week and a day-of-month value is not complete (you’ll need to
use the ? character in on of these fields).
• Be careful when setting fire times between mid-night and 1:00 AM - "daylight savings" can cause a
skip or a repeat depending on whether the time moves back or jumps forward.
47
48