Traitement de message

L'adaptateur prend en charge deux opérations principales :

  1. L'extraction des messages à partir d'une destination JMS
  2. La livraison d'un message à une destination JMS

L'adaptateur réalise ces opérations en établissant une connexion auprès d'un fournisseur JMS (tel que WebSphere MQ) puis en utilisant l'API JMS pour :

Ces deux opérations sont décrites en détail dans Traitement des messages d'événement et Traitement des messages de requête.

Traitement des messages d'événement

Le connecteur vérifie régulièrement si des messages ont été livrés à une ou plusieurs destinations JMS. A chaque cycle d'interrogation, le connecteur :

  1. Utilise l'API JMS pour extraire tout message en attente.
  2. Appelle un gestionnaire de données configuré pour convertir le contenu du message en un objet métier.
  3. Livre ou publie l'objet métier d'événement au courtier d'intégration configuré, afin qu'il soit traité par tout processus métier souscripteur.

Ces étapes sont illustrées dans la figure 1 et décrites en détail dans :

Figure 1. Flot de message d'événement

Détection d'événement

Pendant chaque cycle d'interrogation d'événement, le connecteur procède à une lecture non bloquante des messages, sur la destination précisée par la propriété de connecteur InputDestination (pour plus d'informations sur les propriétés du connecteur, voir Configuration des propriétés du connecteur). Le connecteur extrait les messages puis les publie sur le courtier.

Le connecteur utilise la méthode pollForEvents() pour détecter d'éventuels messages, à intervalles réguliers. Pour chaque cycle d'interrogation, l'extraction de message est limitée au nombre maximal indiqué par la propriété de connecteur PollQuantity. S'il extrait tous les messages disponibles avant d'atteindre le maximum indiqué, le connecteur n'attend pas de messages supplémentaires mais revient immédiatement du cycle d'interrogation.

Si plusieurs destinations sont précisées dans la propriété de connecteur InputDestination, le connecteur interroge chacune de façon circulaire. Il extrait et publie sur le courtier un nombre maximum PollQuanity de messages à partir de chaque destination. S'il vide toutes les destinations avant d'atteindre le maximum indiqué par PollQuantity, le connecteur revient immédiatement du cycle d'interrogation.

Par exemple, dans un scénario où

l'adaptateur extrairait les messages dans l'ordre suivant au cours d'un cycle d'interrogation unique :

  1. Le premier message de la file d'attente A (laissant 1 message restant)
  2. Le premier message de la file d'attente B (non vide)
  3. Le premier message de la file d'attente C (laissant 4 messages restants)
  4. Le message suivant de la file d'attente A (à présent vide)
  5. Le connecteur contrôle la file d'attente B, mais elle est toujours vide.
  6. Le message suivant de la file d'attente C (laissant 3 messages restants)

L'adaptateur revient ensuite du cycle d'interrogation car il a à présent interrogé un maximum de 2 messages dans chaque file d'attente (tel que défini par PollQuanity).

Statut de l'événement et reprise sur incident

L'extraction d'un message d'événement fait partie d'une transaction. Si le connecteur s'arrête de façon inattendue avant de valider la transaction, celle-ci est annulée et le message d'origine est restauré. L'architecture du connecteur ne prenant actuellement pas en charge les transactions réparties, le connecteur peut publier un événement sur le courtier mais s'arrête de façon inattendue ou perd la communication avant réception d'un accusé de réception de la part du courtier. Dans de tels cas, le connecteur ne dispose d'aucune information permettant de déterminer si l'événement a été reçu ou non par le courtier. Pour éviter la perte de messages d'événement, le connecteur ne valide la transaction qu'une fois que le connecteur a reçu une réponse du courtier confirmant la réception de l'événement. En cas de panne entre le moment où le connecteur publie un événement et celui où il reçoit un accusé de réception, la transaction est annulée automatiquement et le message d'origine est restauré. Puisqu'il est impossible de savoir si le message a été traité par le courtier ou non, ces événements sont désignés comme étant des événements en attente de validation.

Au redémarrage, le connecteur commencera à traiter les messages émis par la destination d'entrée et soumettra de nouveau l'événement en attente de validation. Bien que cette stratégie élimine tout risque de perte d'un événement, elle ne peut pas empêcher le fait que le même événement soit publié deux fois.

Il existe deux moyens de réduire ou d'éliminer le risque de livraison d'événement en double : utiliser une destination en cours (voir Reprise sur incident avec une destination en cours) ou la livraison d'événement garantie (voir Recovery with guaranteed event delivery).

Reprise sur incident avec une destination en cours

Pour contrôler la gestion des événements en attente de validation, vous pouvez créer une destination temporaire séparée en définissant la propriété de connecteur InProgressDestination.

Remarque :
La reprise sur incident avec une destination en cours n'est pas prise en charge par la messagerie Pub/Sub.

Avant de publier un événement sur le courtier, le connecteur déplace le message d'événement depuis la destination d'entrée vers la destination en cours. Une fois qu'il a reçu l'accusé de réception du courtier, le connecteur supprime le message de la destination en cours. Ceci a pour effet d'isoler les messages en attente de validation qui n'ont pas été traités. Au démarrage, si le connecteur trouve des messages dans la destination en cours, il peut supposer en toute sécurité que ceux-ci proviennent d'une instance précédente du connecteur qui s'est arrêté de façon inattendue. Vous pouvez préciser différentes actions prises par le connecteur sur de tels messages (si la notification d'événement en double est inacceptable). Pour cela, indiquez l'une des quatre options suivantes pour la propriété de configuration InDoubtEvents :

Pour plus d'informations, voir InDoubtEvents.

Recovery with guaranteed event delivery

La fonctionnalité de livraison garantie d'événement permet à l'architecture du connecteur de s'assurer que les événements ne sont jamais perdus ni envoyés deux fois. L'architecture du connecteur prend en charge la livraison d'événement garantie via deux mécanismes : les événements gérés par le conteneur (CME) et l'élimination d'événements en double (DEE).

Evénements gérés par le conteneur (CME)

Vous pouvez utiliser le mécanisme CME lorsque le connecteur est configuré pour la messagerie PTP. Pour utiliser CME, WebSphere MQ doit être votre fournisseur JMS et les files d'attente source et de destination doivent être sur un gestionnaire de files d'attente.

Remarque :
Lorsqu'il est configuré pour la messagerie Pub/Sub, le connecteur ne prend pas en charge CME. Pour plus d'informations sur le fonctionnement de cette méthode de livraison d'événement garantie, voir Connector Development Guide for Java. Pour plus d'informations sur la propriété de connecteur ContainerManagedEvents, voir ContainerManagedEvents.
Elimination des événements en double (DEE)

DEE est l'approche recommandée pour mettre en oeuvre la livraison d'événement garantie pour l'adaptateur JMS. DEE est également la seule approche prise en charge par la messagerie Pub/Sub.

Avec DEE, un connecteur inclut un ID unique à chaque événement publié sur le courtier. L'architecture vérifie que le connecteur ne soumet pas plusieurs fois de suite le même ID d'événement. Si cela se produit, l'architecture suppose que le connecteur publie le même événement deux fois et élimine la deuxième soumission. Pour la messagerie PTP, DEE réduit la surcharge importante résultant de la copie des messages depuis et vers une destination en cours.

Ce connecteur inclut l'ID de message pour tous les événements lors de la publication d'objets métier sur le courtier. Si le connecteur ne parvient pas à poster un événement sur le courtier, en raison d'un problème de communication ou d'un arrêt inattendu, le message d'origine est remis dans la file d'attente d'entrée, tel que décrit précédemment. Au redémarrage, le connecteur commence à soumettre de nouveau les événements depuis la file d'attente, y compris les messages en attente de validation. Si DEE est activé, tout message en attente de validation qui a bien atteint le courtier dans le passé sera annulé. Ceci garantit que chaque message soit soumis une fois et une seule au courtier.

Avec DEE, évitez de changer l'ordre des messages dans les destinations pendant que le connecteur est hors ligne. DEE n'enregistre que le dernier ID de message extrait par l'adaptateur. DEE échouera dans le cas où, par exemple, de nouveaux messages de priorité supérieure font reculer le message en attente de validation dans la file d'attente, avant que l'adaptateur ne puisse redémarrer.

Pour plus d'informations sur DEE et sur son activation, voir Connector Development Guide for Java. Pour plus d'informations sur la propriété de connecteur DuplicateEventElimination, voir DuplicateEventElimination.

Extraction des événements

L'extraction d'événements couvre le traitement général des événements par le connecteur. Elle commence avec la détection d'un événement entrant et s'achève avec sa conversion dans un format adapté à l'application cible, et sa livraison réussie au courtier d'intégration désigné. Le connecteur au courtier livre tous les événements de façon asynchrone ("en aveugle").

Les sections qui suivent traitent de l'extraction des événements :

Métadonnées et méta-objets

Pour que le connecteur parvienne à convertir des messages en objets métier et vice-versa, il a besoin d'informations supplémentaires appelées métadonnées. Les métadonnées décrivent de quelle façon les données d'un objet, d'un message ou d'une application sont représentées ou doivent être traitées. Les métadonnées indiquent notamment l'objet métier à créer si le connecteur extrait un message d'une destination XYZ, ou le gestionnaire de données à utiliser pour sérialiser un objet métier de requête de type Customer avec l'instruction Create.

Attributs, propriétés, instructions et informations spécifiques à l'application constituent les métadonnées d'une définition d'objet métier. De plus, vous pouvez préciser un ou plusieurs méta-objets pouvant contenir des méta-données concernant les destinations, formats de données, gestionnaires de données, etc.

Il existe deux types de méta-objets : statiques et dynamiques. Vous créez un méta-objet statique pendant l'implémentation. Il contient des attributs qui fournissent des méta-données pour chaque type d'objet métier devant être pris en charge par le connecteur. Le méta-objet statique est spécifié dans les propriétés propres au connecteur. Il est lu par celui-ci pendant l'initialisation. Pour une présentation des propriétés du méta-objet et pour savoir comment elles affectent la transformation des messages, voir Mappage d'objet métier et Présentation du mappage de l'en-tête du message.

Le second type de méta-objet est dynamique. Il permet de modifier les métadonnées utilisées par l'adaptateur pour traiter un objet métier requête par requête, pendant le traitement des requêtes. Pendant le traitement des événements, le méta-objet dynamique agit en tant que conteneur pour proposer les informations de transfert relatives à l'événement (par exemple, message, ID, priorité, etc.) afin que les processus métier en aval puissent utiliser les informations dans leur logique métier. Le méta-objet dynamique est représenté en tant qu'objet enfant spécialement marqué dans l'objet de niveau supérieur (ou la requête) de l'événement.

Vous pouvez choisir d'utiliser un ou les deux types de méta-objets dans la même implémentation. Les valeurs fournies dans un méta-objet dynamique sont généralement prioritaires sur les valeurs fournies dans le méta-objet statique. Pour plus d'informations sur les métadonnées, voir Connector Development Guide for Java. Pour plus d'informations sur la configuration de méta-objets statiques et dynamiques, voir Configuration des méta-objets.

Mappage d'objet métier

Lors de l'extraction d'un message, le connecteur tente de déterminer sur quel objet métier le message doit être mappé.

Par défaut, le connecteur autorise le gestionnaire de données, configuré dans les propriétés du connecteur, à déterminer le type d'objet métier. Il transmettra le corps du message au gestionnaire de données et publiera l'objet métier retourné au courtier par le gestionnaire de données. Si le gestionnaire de données ne peut déterminer l'objet métier approprié, le connecteur fait échouer l'événement.

Si un méta-objet statique est précisé pour la propriété de configuration du connecteur ConfigurationMetaObject, le connecteur examine cet objet pour trouver une règle correspondant au message en termes de format et de destination d'entrée. Si la règle précisée dans le méta-objet précise à la fois le format et la destination de l'entrée, le connecteur observe cette règle, mais uniquement si le message correspond aux deux propriétés. Si l'une des deux propriétés est manquante, le connecteur utilise uniquement la propriété spécifiée.

Par exemple, un message dont le format d'entrée est Cust_In et la destination d'entrée est MyInputDest correspond aux règles de méta-objet statique :

  1. InputFormat=Cust_In;InputDestination=MyInputDest
  2. InputFormat=Cust_In
  3. InputDestination=MyInputDest

S'il peut faire correspondre le message d'événement à une seule règle, le connecteur détermine l'objet métier en créant une nouvelle instance de cet objet métier et en la transmettant avec le corps du message, au gestionnaire de données précisé dans la règle. Si aucun gestionnaire de données n'est précisé dans la règle, le connecteur utilisera le gestionnaire de données par défaut, indiqué dans les propriétés de configuration du connecteur.

Si l'adaptateur peut faire correspondre le message d'événement avec plusieurs règles ou aucune, le connecteur autorise le gestionnaire de données à déterminer le type d'objet métier, en transmettant uniquement le corps du message au gestionnaire de données indiqué dans les propriétés de configuration du connecteur.

Présentation du mappage de l'en-tête du message

Pour transformer un message d'événement en objet métier, le connecteur compare les métadonnées relatives à l'objet métier avec les métadonnées du message, en les mappant les unes sur les autres. Comme décrit dans Métadonnées et méta-objets, les métadonnées relatives aux objets métier résident dans les définitions d'objet métier (les informations spécifiques à l'application et les méta-objets enfants dynamiques), les propriétés du connecteur et les méta-objets statiques. Les méta-données du message sont contenues dans les en-têtes.

Pour accéder aux informations de l'en-tête du message spécifiques au transfert, et pour obtenir plus d'informations et de contrôle sur le transfert, vous pouvez ajouter des attributs à un méta-objet dynamique qui est un enfant d'une définition d'objet métier. Le fait d'ajouter ces attributs vous permet de lire et éventuellement d'écrire dans les en-têtes des messages et de modifier ainsi leurs métadonnées. De telles changements peuvent inclure la modification des propriétés JMS, le contrôle de la destination sur une base par requête (plutôt que d'utiliser la destination par défaut précisée dans les propriétés de l'adaptateur), le reciblage d'un CorrelationID de message, etc. Lorsque vous précisez de telles propriétés dans un méta-objet dynamique qui est un enfant d'une définition d'objet métier, le connecteur contrôle leurs équivalents dans les en-têtes de messages et renseigne un méta-objet dynamique basé sur le contenu de l'en-tête du message. Vous pouvez définir un ou tous les attributs de méta-objet dynamiques pris en charge, le connecteur renseignera le méta-objet en conséquence. Pour plus d'informations, y compris pour une liste des propriétés d'en-têtes de message que vous pouvez lire et écrire, voir Alimentation du méta-objet enfant dynamique pendant l'interrogation.

Archivage

Si vous précisez la propriété spécifique au connecteur ArchiveDestination, le connecteur place une copie de tous les messages dont le traitement a réussi dans cette destination. Si ArchiveDestination n'est pas défini, les messages dont le traitement a réussi sont éliminés. Pour plus d'informations, voir Configuration des propriétés spécifiques au connecteur.

Reprise après erreur

S'il rencontre des erreurs pendant la lecture depuis les destinations d'entrée, le connecteur retourne immédiatement la constante APPRESPONSETIMEOUT au courtier, entraînant l'arrêt et l'éventuel redémarrage du connecteur. De telles erreurs irrémédiables sont généralement dues à une perte de connexion avec le fournisseur JMS, ou à des erreurs internes rapportées par le fournisseur JMS et que le connecteur ne reconnaît pas, ou reconnaît mais juge irrémédiables (par exemple, un échec de transaction).

S'il rencontre des erreurs lors de la conversion du message entrant en un objet métier d'événement (par exemple, si le gestionnaire de données fait état d'un format de message incorrect), le connecteur fait échouer l'événement et consigne un message d'erreur approprié expliquant le motif. Si la propriété du connecteur ErrorDestination est définie et valide, le connecteur place une copie du message qui a échoué dans cette destination d'erreur. Dans le cas contraire, le message est éliminé.

Si le courtier rapporte une erreur une fois que le connecteur a publié l'objet métier d'événement, le connecteur fait échouer l'événement et consigne le message d'erreur rapporté par le courtier. Si la propriété du connecteur ErrorDestination est définie et valide, le connecteur place une copie du message qui a échoué dans cette destination. Dans le cas contraire, le message est éliminé.

Si le connecteur ne parvient pas à déterminer un objet métier pour un message, ou s'il publie un message sur un courtier et que le courtier rapporte que le message n'est pas pris en charge, le connecteur le considère comme non souscrit. Si la propriété du connecteur, UnsubscribedDestination est définie et valide, le connecteur place une copie du message non souscrit dans cette destination. Dans le cas contraire, le message est éliminé.

Traitement des messages de requête

Lorsqu'une requête d'objet métier est envoyée au connecteur, il crée un nouveau message dans la destination cible. L'en-tête du message est complété par une combinaison de valeurs définies par l'utilisateur et précisées dans les méta-objets de requête et les paramètres par défaut indiqués par les propriétés du connecteur. Le corps du message est complété par le contenu résultant du passage de l'objet métier de requête par le gestionnaire de données configuré.

La figure 2 illustre une communication de requête de message. Lorsque la méthode doVerbFor() reçoit un objet métier d'un courtier, le connecteur transmet l'objet métier au gestionnaire de données. Le gestionnaire de données convertit l'objet métier en un message convenable, qui est ensuite émis en tant que message vers une destination.

Figure 2. Flot de requête

Le connecteur peut avoir deux comportements pendant le traitement de la requête. Dans le premier, décrit ci-dessous en tant que traitement asynchrone, le connecteur place un message dans la destination cible et revient en indiquant sa réussite. Ce fonctionnement est dit "en aveugle". Dans le second, décrit ci-dessous en tant que traitement synchrone, le connecteur place de nouveau un message dans l'application cible mais attend qu'elle lui retourne une réponse.

Le mode de traitement est déterminé par la propriété numérique ResponseTimeout, précisée dans le méta-objet dynamique ou statique de la requête d'objet métier. Si cette propriété n'est pas définie ou est égale à -1, le connecteur livre la requête de façon asynchrone. Si cette propriété est supérieure ou égale à 0, l'adaptateur traite la requête de façon synchrone et attend au moins ce nombre de millisecondes pour qu'un message de réponse soit retourné par l'application cible. Le traitement de requête illustré dans la figure 2 est décrit en détail dans :

Prise en charge de l'instruction

Le connecteur n'accorde aucune valeur sémantique à l'instruction précisée dans l'objet métier de la requête. Il exécute la même action, plaçant un message dans une destination JMS, quelle que soit l'instruction spécifiée.

Traitement asynchrone

Pendant un traitement asynchrone, le connecteur convertit l'objet métier de requête en message, place celui-ci dans la destination cible puis retourne immédiatement au courtier. La réussite ou l'échec de la requête dépend entièrement de la capacité du connecteur à placer le message dans la destination JMS. Notez que la réussite de cette livraison n'implique pas que l'application cible a reçu ou recevra le message. En raison de la nature asynchrone des systèmes de messagerie, un message peut rester indéfiniment sur le fournisseur JMS, jusqu'à ce que l'application cible soit capable de le traiter ou jusqu'à ce qu'il expire (selon la configuration).

Le connecteur transforme d'abord l'objet métier de requête, en texte à l'aide du gestionnaire de données configuré. Le connecteur utilise le gestionnaire de données indiqué, de préférence dans l'ordre suivant 

  1. le méta-objet dynamique
  2. le méta-objet statique
  3. les propriétés de configuration du connecteur

Le connecteur crée un nouveau message, avec les données d'objet métier mises en série comme corps du message. Il renseigne les en-têtes de messages comme indiqué dans le tableau ci-après. Dans tous les cas où une propriété peut être précisée dans le méta-objet dynamique ou statique, la valeur indiquée dans le méta-objet dynamique est prioritaire sur toute valeur définie dans le méta-objet statique. Pour obtenir une description et une liste des propriétés possibles dans les méta-objets, voir Configuration des méta-objets.

Tableau 1. Renseignement de l'en-tête de message JMS pendant le traitement de requête asynchrone
Propriété de méta-objet Action par défaut si la propriété n'est pas définie Action entreprise si la propriété est définie
OutputFormat
Le connecteur ne précise pas le format du message Le connecteur indique cette valeur comme format du message.
CorrelationID
Le connecteur laisse cette valeur vierge dans l'en-tête du message. Le connecteur précise cette valeur pour l'ID de corrélation, dans l'en-tête du message de requête.
ReplyToDestination
Le connecteur laisse cette valeur vierge dans l'en-tête du message. Le connecteur précise cette valeur pour la destination de la réponse dans l'en-tête du message de la requête.
Priority (Priorité)
Le connecteur autorise le fournisseur JMS à utiliser la priorité par défaut. Le connecteur définit une priorité de message numérique à l'aide de cette valeur.
JMSProperties Aucune Le connecteur mappe les propriétés JMS précisées sur celles de l'en-tête de message.

Les attributs suivants du méta-objet déterminent le mode de livraison du message :

Tableau 2. Livraison asynchrone à la destination
Propriété de méta-objet Action par défaut si la propriété n'est pas définie Action entreprise si la propriété est définie
OutputDestination
Il est indispensable d'indiquer une valeur. Destination cible du message.
DeliveryMode
Le connecteur autorise le fournisseur JMS à définir la persistance du message. Le connecteur écrit le message de façon persistante/non persistante, comme indiqué par l'utilisateur.

En fonction de la capacité du connecteur à réussir à livrer le message de requête à la destination de sortie (cible), un des codes suivants est retourné au courtier :

Tableau 3. Codes de retour asynchrones
Action du connecteur Code de retour vers le courtier
A réussi à livrer le message à une destination cible. SUCCEED
Ne parvient pas à livrer le message en raison d'erreurs remédiables telles que des méta-données incorrectes ou incomplètes, un incident sur le gestionnaire de données, ou des problèmes généraux de traitement. FAIL
Ne parvient pas à livrer le message en raison d'erreurs irrécupérables rapportées par le fournisseur JMS, telles qu'un incident de connexion APPRESPONSETIMEOUT

Traitement synchrone

Dans le traitement synchrone, le connecteur fournit la requête à la destination cible puis attend un message de réponse sur la seconde destination. La création du message de requête est identique à celle décrite dans le traitement asynchrone. Toutefois, le connecteur vérifie également la présence d'attributs supplémentaires dans le méta-objet :

Tableau 4. Propriétés de méta-objet synchrone
Propriété de méta-objet Action par défaut si la propriété n'est pas définie Action entreprise si la propriété est définie
ResponseTimeout
Il est indispensable d'indiquer une valeur. Durée minimale (exprimée en millisecondes) pendant laquelle l'adaptateur doit attendre le retour d'un message de réponse.
TimeoutFatal
S'il ne reçoit pas de réponse dans le délai précisé par ResponseTimeout, le connecteur retourne APPRESPONSETIMEOUT au courtier, ce qui entraîne généralement l'arrêt du connecteur. S'il ne reçoit pas de réponse, le connecteur fait échouer la requête (il retourne FAIL au courtier) mais ne s'arrête pas.

La livraison du message à la destination cible est identique à celle décrite pour le traitement asynchrone, à l'exception des points suivants :

Tableau 5. Livraison synchrone à la destination
Propriété de méta-objet Action par défaut si la propriété n'est pas définie Action entreprise si la propriété est définie
ReplyToDestination
Même chose que pour le traitement asynchrone. Le connecteur complète cette zone du message de requête avec la valeur de la propriété spécifique au connecteur ReplyToDestination.

Le connecteur attend un message de réponse émis par l'application cible précisée par ReplyToDestination, pendant une durée au moins égale au temps indiqué par l'attribut de méta-objet ResponseTimeout. Si une réponse n'est pas retournée dans cet intervalle, le connecteur indique une erreur.

Critères de réponse

Le connecteur ne suppose pas que le premier message de la destination de la réponse est le message de réponse correct. A la place, il suit les conventions de réponse aux requêtes JMS et examine le premier message dont l'ID de corrélation correspond à l'ID de message de la requête. En d'autres termes, l'application qui reçoit le message de requête doit créer un message de réponse dont l'ID de corrélation est identique à l'ID de message de requête. Elle doit ensuite placer ce message dans la destination de réponse précisée par le message de requête.

Toutes les applications n'appliquent pas la convention d'utilisation de l'ID de corrélation pour mapper les messages de requête et de réponse. Le connecteur accepte alors des critères personnalisés permettant d'identifier un message de réponse.

Dès réception d'un objet métier de traitement de requête asynchrone, le connecteur vérifie la présence de la paire nom-valeur response_selector= dans les informations spécifiques à l'application de l'instruction. Si aucune paire nom-valeur n'existe, le connecteur identifie le message de réponse à l'aide de l'ID de corrélation de message, tel qu'indiqué ci-dessus.

Si une paire nom-valeur de sélecteur de réponse est définie, le connecteur considère que la valeur représente une chaîne de sélecteur de message JMS capable d'identifier le message de réponse. Voici quelques exemples d'utilisation. Pour plus d'informations sur la syntaxe du sélecteur de message JMS, voir la spécification de l'API JMS. Notez que le connecteur ne procède pas à l'analyse syntaxique du sélecteur de message JMS. Par contre, la syntaxe est comprise par le fournisseur JMS. Le connecteur rend le sélecteur disponible au fournisseur JMS, en tant que moyen de filtrage des messages (un peu comme une requête de base de données).

Par exemple, des informations spécifiques à l'application contenant la paire nom-valeur

response_selector=JMSType = 'xmlResponse'

informent le connecteur que le message de réponse doit correspondre à la chaîne de sélecteur JMSType = 'xmlResponse'. Le connecteur transmet ce sélecteur au fournisseur JMS, puis retourne le premier message fourni à la destination de réponse, où la zone de type JMS du message est égale à xmlResponse.

Dans tous les cas, la chaîne du sélecteur de message doit être capable d'identifier de façon unique une réponse et une seule. Si plusieurs messages répondant aux critères du sélecteur de réponse ont été livrés à la destination de réponse, l'adaptateur n'extraira que le premier. Tout autre message de réponse correspondant aux critères sera ignoré.

Pour autoriser un sélecteur de message unique lors de l'exécution, le connecteur prend en charge les remplacements dynamiques de valeurs d'attribut dans le sélecteur de message lui-même. Pour ce faire, vous devez indiquer dans le sélecteur de réponse un paramètre blanc, sous forme d'un nombre entier entre accolades ("{1}"). Il doit être suivi d'un caractère ":" et d'une liste d'attributs séparés par des virgules à utiliser pour la substitution. Le nombre entier de la marque de réserve a un rôle d'index utilisé par l'attribut pour le remplacement.

Par exemple, le sélecteur de message suivant

response_selector=JMSCorrelationID LIKE '{1}':MyDynamicMO.CorrelationID

indique au connecteur de remplacer le repère {1} par la valeur de l'attribut CorrelationID, dans l'objet enfant MyDynamicMO. Si l'attribut CorrelationID avait la valeur 123ABC, le connecteur générerait et utiliserait le sélecteur de message

JMSCorrelation LIKE '123ABC'

Vous pouvez également préciser plusieurs substitutions, comme indiqué ci-dessous :

response_selector=Name LIKE '{1}'AND Zip LIKE '{2}':PrimaryID,Address[4].AddressID

Dans cet exemple, le connecteur remplace '{1}' par la valeur de l'attribut PrimaryID à partir de l'objet métier de niveau supérieur, et '{2}' par la valeur de AddressID à partir de la cinquième position (base 0) de l'objet de conteneur enfant Address. Grâce à cette approche, vous pouvez référencer n'importe quel attribut de l'objet métier et méta-objet du sélecteur de message de réponse.

Pour préciser la valeur littérale "{" dans le sélecteur de message, utilisez "{{". Par exemple, le sélecteur suivant

response_selector=PrimaryID LIKE {{1}

sera reconnu par l'adaptateur en tant que la valeur littérale

PrimaryID LIKE {1}

Dans ce cas, le connecteur n'effectuera aucune substitution sur la valeur '{1}'.

Lorsque le connecteur rencontre dans des valeurs d'attributs des caractères spéciaux tels que "{", "}", ":" ou ";", ils sont insérés directement dans la chaîne de requête. Ceci vous permet d'inclure dans une chaîne de requête des caractères spéciaux, servant également de délimiteurs d'informations spécifiques à l'application. Par exemple, le sélecteur suivant

Response_selector=PrimaryID = '{1}':Foo

lorsque l'attribut Foo a une valeur égale à {A:B};{C:D}, est converti en un sélecteur de message littéral tel que

PrimaryID = '{A:B};{C:D}'
Traitement des réponses

Pour savoir comment réagir à réception du message de réponse, le connecteur contrôle la propriété de résultat JMS précisée par la propriété de connecteur MessageResponseResultProperty. En fonction de la valeur de cette propriété JMS, le connecteur s'attend à ce que le corps du message de réponse contienne un objet métier ou un message d'erreur (voir tableau ci-dessous). Dans tous les cas, le connecteur renvoie au courtier le code de retour correspondant. Par exemple, si la propriété de résultat JMS est égale à VALCHANGE dans le message, le connecteur agit comme indiqué pour VALCHANGE, et retourne au courtier la valeur numérique correspondant à la constante de courtier VALCHANGE.

Tableau 6. Traitement des messages de réponse
Valeur de la propriété de résultat JMS Action du connecteur
SUCCESS Ne modifie pas l'objet métier de requête et le retourne simplement au courtier.
VALCHANGE
MULTIPLE_HITS
undefined value
Renseigne de nouveau l'objet métier de requête avec le contenu du corps du message de réponse. Si le corps du message de réponse est vide, l'objet métier de requête est laissé inchangé.
Renseigne de nouveau le méta-objet dynamique de l'objet métier de requête avec les zones de l'en-tête JMS du message de réponse.
FAIL FAIL_RETRIEVE_BY_CONTENT BO_DOES_NOT_EXIST UNABLE_TO_LOGIN VALDUPES Si la réponse est renseignée, le connecteur suppose qu'il s'agit d'un message d'erreur et le retourne au courtier. Si le corps du message de réponse est vide, le connecteur retourne un message d'erreur générique au courtier.
APPRESPONSETIMEOUT Même chose que ci-dessus, sauf que le retour de APPRESPONSETIMEOUT au courtier provoque l'arrêt de l'agent de l'adaptateur.
unrecognized value Le connecteur fait échouer la requête.
Gestion des erreurs

Si le connecteur rencontre des erreurs lorsqu'il lit ou écrit le message de requête dans la destination cible ou contrôle le message de réponse (le cas échéant), il retourne immédiatement APPRESPONSETIMEOUT au courtier. Ceci entraîne l'arrêt ou le redémarrage possible de l'adaptateur. De telles erreurs irrémédiables sont généralement dues à une perte de connexion au fournisseur JMS ou à des erreurs internes rapportées par le fournisseur JMS et que le connecteur ne reconnaît pas, ou reconnaît mais juge irrémédiables (par exemple, un échec de transaction).

S'il rencontre des erreurs lors de la conversion d'un objet métier en message ou vice-versa (par exemple, si le gestionnaire de données rapporte un format de message incorrect), le connecteur fait échouer la requête et consigne un message d'erreur expliquant le motif.

Pour plus d'informations, et pour consulter des scénarios d'incident sur événement, voir Gestion des erreurs.

Copyright IBM Corp. 2003, 2005