Mappeurs de message

Un mappeur de messages est un mécanisme qui prend un message XML et le convertit en objet CommandProperty. Il fournit une interface commune permettant la conversion des messages en objets CommandProperty et leur utilisation par tous les composants HCL Commerce.

L'objet CommandProperty représente une commande de contrôleur. L'objet contient le nom de commande à exécuter, les propriétés de commande lors de l'exécution de la commande et les paramètres de la commande. Le but des mappeurs de message est de convertir les messages de requête entrants en commandes de contrôleur à exécuter par un adaptateur. Bien qu'ils puissent être utilisés par tous les composants de HCL Commerce pour mapper des données vers un objet TypedProperty étendu, le but principal des mappeurs de messages est de convertir des objets XML en objets Java courants représentant les commandes du contrôleur.

Le type de données CommandProperty se compose des trois parties suivantes :

commandName: Nom de la commande à exécuter, sous la forme d'une chaîne.
requestProperties: Les propriétés de la commande lors de l'exécution de la commande, sous la forme d'un objet TypedProperty.
executionProperties: Les données de contrôle pour l'exécution de la commande sous la forme d'un objet TypedProperty.

Les adaptateurs pris en charge, tels que l'adaptateur de programme, et les composants HCL Commerce, peuvent tous deux appeler un mappeur de message. Pour les deux, le mappeur de message effectue les tâches suivantes :

Reçoit un message XML.
Convertit le message en un objet CommandProperty.
Renvoie null si le message XML ne peut pas être converti.

Les messages entrants sont envoyés à HCL Commerce par des systèmes back-end ou des systèmes externes pour demander un type d'action. Pour que HCL Commerce effectue cette action, le message XML doit être traité par le mappeur de messages afin de déterminer l'action qui a été demandée. HCL Commerce inclut deux mappeurs de messages lors de l'installation : le mappeur de messages XML permettant d'analyser les messages d'intégration XML et le mappeur de messages hérité permettant d'analyser les messages hérités d'intégration back-end.

L'objet CommandProperty représente une commande HCL Commerce visant à répondre aux exigences des adaptateurs de périphériques pris en charge. D'autres composants peuvent également utiliser le mécanisme du mappeur de message pour convertir des messages en objets CommandProperty.

Le cycle de vie d'un mappeur de messages existe tout au long de l'instance HCL Commerce. Il est initialisé lorsqu'une instance est démarrée et dure tant que l'instance s'exécute. HCL Commerce fournit trois mappeurs de messages : le mappeur de messages XML, le mappeur de messages XML pour les messages SOAP et le mappeur de messages hérité.

Le fichier de configuration HCL Commerce répertorie tous les mappeurs de messages possibles et inclut leur nom, leur classe, leur format de périphérique, leur option et leurs paramètres de configuration spécifiques. Pour localiser les paramètres d'un mappeur de messages spécifique, recherchez le nom du composant dans MessageMapperGroup. Chaque mappeur de messages pouvant présenter des attributs de configuration différents, chacun possède un élément MessageMapperGroup distinct. La seule exigence pour le format de l'élément des paramètres de configuration est que les attributs doivent être des paires valeur-nom. Cela permet de convertir facilement les paramètres de configuration du mappeur de messages en un objet TypeProperty.

Ce qui suit répertorie les paramètres de chaque mappeur de message individuel :

nom

Nom du mappeur de message. Ce nom sera utilisé par la commande qui s'attend à analyser un message uniquement avec ce mappeur de message. Pour utiliser le mappeur de messages avec HTTP ou IBM MQ, définissez l'attribut d'activation du mappeur sur true. Vous devez également ajouter le nom du mappeur à la section d'adaptateur correspondante.

<HttpAdapters display="false"> <HttpAdapter deviceFormatTypeId="-10000" enabled="false" deviceFormatType="XmlHttp" deviceFormatId="-10000" name="XML/HTTP" factoryClassname="com.ibm.commerce.programadapter.HttpProgramAdapterImpl"> <ProgramAdapter> <SessionContext class="com.ibm.commerce.messaging.programadapter.security.CredentialsSpecifiedProgramAdapterSessionContextImpl"> <SessionContextConfig /> </SessionContext> <Configuration supportedMessageMappers="WCS.SOAPINTEGRATION, WCS.INTEGRATION" supportedMethods="POST, M-POST" supportedContentTypes="text/xml, text/xml; charset=UTF-8, text/xml-SOAP, text/xml; charset=utf-8" supportedCharacterEncoding="ISO8859-1, UTF-8, utf-8" /> </ProgramAdapter> </HttpAdapter> </HttpAdapters>

Classe

Nom de classe qui contient l'implémentation de l'interface du mappeur de message.

messageMapperId

ID du mappeur de message. Chaque ID de mappeur de message doit être unique.

enable

Indique si le mappeur de message doit être utilisé et initialisé ou non. Si cette valeur est définie sur true, le mappeur de messages est initialisé au démarrage de l'instance et est disponible. Si cette valeur est définie sur false, le mappeur de messages est désactivé.

EcInboundMessageDtdFiles

Liste des fichiers DTD utilisés pour analyser un message XML entrant.

EcInboundMessageDtdPath

L'emplacement du fichier où se trouvent les fichiers DTD répertoriés dans cInboundMessageDtdFiles.

EcSystemTemplateFile

Le fichier modèle du système livré avec HCL Commerce. Elle est généralement définie sur "" pour les mappeurs de messages personnalisés.

EcTemplatePath

Emplacement où le fichier modèle du système peut être trouvé.

isValidating

L'analyseur XML livré avec HCL Commerce dispose d'une fonctionnalité permettant de valider un message XML entrant avec son DTD correspondant ou non. Cette fonctionnalité est activée (définie sur true) par défaut. Pour la désactiver, définissez-la sur false.

Note: Pour HCL Commerce 9.1.12.0, le paramètre isValidating du mappeur WCS.INTEGRATION est défini sur true par défaut. La valeur ParserFeatureList est également mise à jour. Cette configuration empêche l'analyseur syntaxique XML d'analyser des entités générales externes et des entités de paramètre externes.

EcTemplatePath

L'emplacement où le fichier modèle de message défini par l'utilisateur peut être trouvé.

EcUserTemplateFile

Nom de fichier du fichier modèle de message défini par l'utilisateur.

EcSaxParserClass

Spécifie le nom de classe de l'analyseur à utiliser. Par défaut, il utilisera org.apache.xerces.parsers.SAXParser.

DebugMode

Option de débogage pour messagemapper. Par défaut, elle est définie sur false. Lorsque la valeur est définie sur true, tous les fichiers de définition de modèles de messages (par exemple, user_template.xml, sys_template.xml) et les fichiers DTD sont rechargés lorsqu'un message entrant est reçu par le programme d'écoute IBM MQ.

EmptyElementClearsData

Indicateur qui spécifie comment les éléments vides des messages XML entrants doivent être traités. Par défaut, il est défini sur false. Lorsque cet indicateur est défini sur false, les éléments vides des messages XML entrants sont ignorés et ne sont pas transmis à la commande cible. Lorsqu'il est défini sur true, tous les éléments vides des messages XML entrants sont traités comme transmettant des chaînes vides à la commande cible.

DuplicateCreatesArray

Indicateur qui spécifie comment les éléments en double avec les mêmes entrées XPath trouvées dans le XML d'entrée doivent être gérés. Par défaut, il est défini sur false. Lorsque cet indicateur est défini sur false, les éléments en double trouvés dans le XML d'entrée écrasent la valeur précédente. Lorsqu'il est défini sur true, les éléments en double trouvés dans le XML d'entrée sont convertis en tableaux de valeurs sous la clé utilisée par les propriétés de la requête.

ParserFeatureList

Spécifiez la fonction de l'analyseur. Par défaut, ParserFeatureList="http://apache.org/xml/features/nonvalidating/load-external-dtd=false". Pour plus d'informations, voir Apache Xerces2. Pour spécifier plusieurs fonctions, utilisez une liste séparée par des virgules. Par défaut, la valeur de l'attribut isValidating dans notre mappeur de message est true. Si l'attribut isValidating est faux et que la valeur de ParserFeatureList est http://apache.org/xml/features/nonvalidating/load-external-dtd=false,http://xml.org/sax/features/validation=true, la valeur ParserFeatureList remplace la valeur de l'attribut isValidating.

Note: Pour HCL Commerce 9.1.12.0 et 9.1.13.0, le paramètre ParserFeatureList du mappeur WCS.INTEGRATION est défini sur

"http://apache.org/xml/features/nonvalidating/load-external-dtd=false,http://xml.org/sax /features/external-general-entities=false,http://xml.org/sax/features/external-parameter-entities=false"

. Le paramètre isValidating est également mis à jour. Cette configuration empêche l'analyseur syntaxique XML d'analyser des entités générales externes et des entités de paramètre externes.

Amélioration de l'analyseur XML

La sécurité du traitement XML dans les services Web entrants utilisant l'adaptateur de programme et le mappeur de messages WCS.INTEGRATION a été renforcée.

La configuration du mappeur de messages dans wc-server.xml est la suivante :

<configuration isValidating="true" ParserFeatureList="" isSanitizationEnabled="true" WhiteListSchemes="http,https,ftp,sftp" WhiteListDomains="xml.cxml.org" isLocalEntityEnabled="true"/>

La nouvelle fonctionnalité offre un moyen plus flexible d'empêcher les utilisateurs d'accéder à des ressources distantes hébergées par des sites non fiables. L'analyseur validera et autorisera uniquement les requêtes conformes aux propriétés WhiteListSchemes et WhiteListDomains. Si vous souhaitez désactiver cette fonctionnalité, il suffit de définir isSanitizationEnabled sur false.

Ci-dessous sont répertoriées les quatre configurations nouvellement ajoutées :

isSanitizationEnabled: Indicateur spécifiant si une vérification de la charge utile des requêtes entrantes doit être effectuée. Lorsque cet indicateur est activé, le nouveau mécanisme de validation est déclenché, ce qui valide la requête et autorise uniquement celle qui est conforme aux propriétés WhiteListSchemes et WhiteListDomains.
WhiteListSchemes: Les systèmes autorisés. Les systèmes suivants sont autorisés : http, https, ftp et sftp. Ces valeurs sont définies dans le wc-server et peuvent être mises à jour en conséquence.
WhiteListDomains: La liste séparée par des virgules répertoriant les domaines autorisés, xml.cxml.org, est le seul domaine autorisé. Ces valeurs sont définies dans le wc-server et peuvent être mises à jour en conséquence.
isLocalEntityEnabled: Indicateur utilisé lors de la résolution de l'entité. Lorsque cet indicateur est activé, l'analyseur essaie de trouver et de résoudre l'entité localement avant d'essayer de résoudre l'URI (Uniform Resource Identifier).

mappeur de message XML

Le mappeur de messages XML est chargé de convertir les données XML des messages XML entrants en objets CommandProperty. Il s'agit d'une extension de l'analyseur ECSAX. Le mappeur de message XML trouvé dans le fichier de configuration HCL Commerce doit ressembler à ce qui suit :

<MessageMapper messageMapperId="-1" classname="com.ibm.commerce.messaging.programadapter.messagemapper.ecsax.ECSAXMessageMapper" enable="true" name="WCS.INTEGRATION"> <configuration/> </MessageMapper>

Lorsque le mappeur de message XML analyse un message XML entrant, il obtient le type de document, la version si elle est disponible et le nom de l'élément, un par un à partir des documents XML dans le message. Le mappeur de messages recherche le document modèle défini dans l'élément ECTemplate du fichier de définition de modèle. Le document de modèle indique au mappeur de message les informations suivantes :

À partir de quel élément le mappage de balise doit être démarré.
Quel modèle de balise utiliser.
Le nom de la commande qui sera appelée par le message entrant. La commande peut être une commande de contrôleur HCL Commerce existante ou une nouvelle commande que vous avez créée.

Une fois le mappage de balises démarré, le mappeur de messages recherche dans TemplateTag, tel que défini dans le fichier ECTemplate, afin de déterminer le nom et le type de champ sur la base du XPath généré à partir du message XML entrant, puis définit une valeur pour ce champ. Les paires de champs et de valeurs sont stockées dans une table de hachage TypedProperty de commandProperty ou messageProperty en fonction de la valeur de l'attribut FieldInfo pour ce champ. Une fois que l'ensemble du message entrant est analysé avec succès, un objet PropertyCommand est renvoyé, qui contient le nom de commande ainsi que les objets commandProperty et messageProperty.

Pour prendre en charge différentes versions d'un message, plusieurs modèles de document peuvent être spécifiés. Par exemple,

<TemplateDocument> <DocumentType version='1.0'>Update_NC_ProductInventory</DocumentType> <StartElement>Update_NC_ProductInventory</StartElement> <TemplateTagName>ProductInventory10Map</TemplateTagName> <CommandMapping> <Command CommandName='ProductInventoryUpdate' /> </CommandMapping> </TemplateDocument> <TemplateDocument> <DocumentType version='2.0'>Update_WCS_ProductInventory</DocumentType> <StartElement>Update_WCS_ProductInventory</StartElement> <TemplateTagName>ProductInventory20Map</TemplateTagName> <CommandMapping> <Command CommandName='ProductInventoryUpdate' /> </CommandMapping> </TemplateDocument>

Si l'élément de configuration est vide, l'élément Messagerie sera utilisé. La messagerie se trouve dans le fichier de configuration HCL Commerce.

mappeur de message XML pour les messages SOAP

Le mappeur de messages XML pour les messages SOAP est chargé d'extraire les données XML des messages SOAP entrants et de les convertir en objets CommandProperty. Il s'agit d'une extension de l'analyseur ECSAX. Le mappeur de message trouvé dans le fichier de configuration HCL Commerce doit ressembler à ce qui suit :

<MessageMapper classname="com.ibm.commerce.messaging.programadapter.messagemapper.ecsax.ECSAXMessageMapper" enable="false" messageMapperId="-3" name="WCS.SOAPINTEGRATION"> <configuration EcInboundMessageDtdFiles="" EcInboundMessageDtdPath="messaging" EcSystemTemplateFile="webservice_template.xml" EcTemplatePath="messaging" isValidating="false" DebugMode="FALSE" EmptyElementClearsData="FALSE" /> </MessageMapper>

mappeur de message existant

Le mapper de messages hérité est responsable de la conversion des données des messages hérités entrants en objets CommandProperty. Le mappeur de message hérité trouvé dans le fichier de configuration HCL Commerce doit ressembler à ce qui suit :

<MessageMapper messageMapperId="-2" classname="com.ibm.commerce.messaging.programadapter.messagemapper.nclegacy.NetCMessageMapper" enable="true"> name="NC.LEGACY"> <configuration/> </MessageMapper>