Configuration des méta-objets

Le connecteur pour JMS peut reconnaître et lire deux types de méta-objets :

Les valeurs d'attribut du méta-objet enfant dynamique dupliquent et supplantent celles du méta-objet statique. Pour une présentation des métadonnées et de la différence entre méta-objets statiques et dynamiques, voir Métadonnées et méta-objets.

Pour déterminer le méta-objet le mieux adapté à votre implémentation, tenez compte des points suivants :

Propriétés du méta-objet

Le tableau 10 fournit une liste complète des propriétés prises en charge dans les méta-objets. Reportez-vous à ces propriétés lors de l'implémentation de méta-objets.

Toutes les propriétés ne sont pas disponibles pour les deux types d'objets. Elles n'ont pas non plus toutes la possibilité d'être lues ou écrites dans l'en-tête de message. Pour déterminer comment une propriété spécifique est interprétée et utilisée par le connecteur, voir les sections appropriées sur le traitement des requêtes et des événements au Présentation de Adapter for JMS.

Tableau 10. Propriétés de méta-objet JMS
Nom de la propriété Définissable dans un méta-objet statique Définissable dans un méta-objet dynamique Description
DataHandlerConfigMO
Oui Oui Méta-objet transmis au gestionnaire de données pour fournir des informations de configuration. Si elle est indiquée dans le méta-objet statique, cette propriété remplacera la valeur précisée dans la propriété du connecteur DataHandlerConfigMO. Utilisez cette propriété de méta-objet statique lorsque différents gestionnaires de données sont requis pour traiter différents types d'objet métier. Utilisez le méta-objet enfant dynamique pour traiter la requête lorsque le format des données peut dépendre des données métier réelles. L'objet métier précisé doit être pris en charge par l'agent du connecteur. Voir la description dans Configuration des propriétés spécifiques au connecteur.
DataHandlerMimeType
Oui Oui Permet de lancer une requête sur un gestionnaire de données, en fonction d'un type MIME particulier. Si elle est indiquée dans le méta-objet statique, cette propriété remplacera la valeur précisée dans la propriété du connecteur DataHandlerMimeType.
Utilisez cette propriété de méta-objet statique lorsque différents gestionnaires de données sont requis pour traiter différents types d'objet métier. Utilisez le méta-objet enfant dynamique pour traiter la requête lorsque le format des données peut dépendre des données métier réelles. L'objet métier précisé dans DataHandlerConfigMO doit avoir un attribut correspondant à la valeur de cette propriété. Voir la description dans Configuration des propriétés spécifiques au connecteur.
DataHandlerClassName
Oui Oui Voir la description dans Configuration des propriétés spécifiques au connecteur.
InputFormat
Oui Oui Format ou type des messages (événement) entrants. Cette valeur aide à identifier le contenu du message. Elle est précisée par l'application qui a généré le message. La zone que le connecteur considère comme définissant le format dans le message peut être définie par l'utilisateur via la propriété MessageFormatProperty spécifique au connecteur.
OutputFormat
Oui Oui Format à renseigner dans les messages sortants. Si OutputFormat n'est pas précisé, le format d'entrée est utilisé, s'il est disponible.
InputDestination Oui Oui Cette propriété est utilisée pour faire correspondre les messages entrants et les objets métier uniquement. A l'inverse, la propriété InputDestination spécifique au connecteur définit les destinations interrogées par l'adaptateur. C'est la seule propriété utilisée par l'adaptateur pour déterminer les destinations à interroger. Dans l'objet géré, les propriétés InputDestination et InputFormat peuvent servir de critère pour que l'adaptateur mappe un message donné sur un objet métier spécifique. Pour mettre en oeuvre cette fonctionnalité, utilisez des propriétés spécifiques au connecteur afin de configurer plusieurs destinations d'entrées, et éventuellement de mapper différents gestionnaires de données sur chacune en fonction des formats d'entrée des messages entrants.

Ne définissez pas cette propriété à l'aide des propriétés de conversion par défaut. C'est sa valeur qui est utilisée.
OutputDestination
Oui Oui Destination où sont écrits les messages sortants.
ResponseTimeout
Oui Oui Indique la durée d'attente d'un réponse avant expiration (en millisecondes), dans un traitement de requête synchrone. Si cette propriété n'est pas précisée ou si elle contient une valeur inférieure à zéro, le connecteur retourne SUCCESS immédiatement, sans attendre de réponse.
DataEncoding Oui Oui

DataEncoding indique si les données du messages sont traitées par l'adaptateur comme étant de type texte, binaire ou objet. Si cette propriété n'est pas spécifiée dans le méta-objet statique, le connecteur tente de lire les messages sans utiliser de code spécifique. La propriété DataEncoding définie dans un méta-objet enfant dynamique remplace la valeur définie dans le méta-objet statique. La valeur par défaut est Text. Le format de la valeur de cet attribut est messageType[:enc]. Par exemple Text:ISO8859_1, Text:UnicodeLittle, Text, Object ou Binary. Cette propriété est liée en interne à la propriété InputFormat : vous précisez un et un seul DataEncoding per InputFormat.
Pour plus d'informations sur DataEncoding, voir DataEncoding.

Ci-dessous figurent des zones mappées spécifiquement sur l'en-tête du message JMS. Pour obtenir des explications précises, savoir comment interpréter les valeurs et etc., voir les spécifications de l'API JMS. Il est possible que les fournisseurs JMS interprètent certaines zones de façon différente. Par conséquent, consultez également la documentation de votre fournisseur JMS pour connaître les éventuelles différences.
ReplyToDestination Oui Destination à laquelle doit être envoyé un message de réponse à une requête.
Type Oui Type de message. Généralement défini par l'utilisateur, en fonction du fournisseur JMS.
MessageID Oui ID unique du message (spécifique au fournisseur JMS).
CorrelationID Oui Oui Utilisé dans les messages de réponse pour indiquer l'ID du message de requête qui a émis cette réponse.
Delivery Mode Oui Oui Indique si le message est conservé ou non dans le système MOM. Valeurs acceptées :
1 = non persistant
2 = persistant
D'autres valeurs peuvent exister selon le fournisseur JMS.
Priority (Priorité) Oui Priorité numérique du message. Valeurs acceptées : 0 à 9 inclus (priorité faible à élevée).
Destination Oui Emplacement en cours ou dernier emplacement (en cas de suppression) dans un système MOM.
Expiration Oui Durée de vie du message.
Redelivered Oui Indique que le fournisseur JMS a très probablement déjà tenté de livrer le message au client, mais qu'aucun accusé de réception n'a été reçu.
Timestamp Oui Heure à laquelle le message a été distribué au fournisseur JMS.
UserID Oui Identité de l'émetteur du message.
AppID Oui Identité de l'application qui envoie le message.
DeliveryCount Oui Nombre de tentatives de livraison.
GroupID Oui Identité du groupe de messages.
GroupSeq Oui Séquence de ce message dans le groupe de messages indiqué par GroupID.
JMSProperties Oui Voir Propriétés JMS.

DataEncoding

Le standard JMS définit différents types de messages permettant de conserver différents types de données. Par exemple, un message texte peut contenir un document XML, tandis que des données binaires peuvent contenir une image. Le fait de préciser de façon explicite le codage attendu des données, par le biais de la propriété de méta-objet DataEncoding, aide l'adaptateur à savoir quels types de messages il doit attendre et comment il doit les traiter.

Par défaut, l'adaptateur suppose que tous les messages sont de type texte. Toutefois, l'adaptateur pour JMS prend en charge les messages de types texte, binaire et objet Java. Pendant le traitement de la requête, l'adaptateur utilise le gestionnaire de données configuré pour convertir l'objet métier de la requête en texte, qu'il livre ensuite sous forme de message texte. Pendant la notification d'événement, l'adaptateur extrait le texte d'un message et le transmet au gestionnaire de données pour créer l'objet métier de l'événement. Si l'adaptateur reçoit un message binaire, il convertit le corps binaire en texte à l'aide du codage par défaut du JVM, avant de transmettre le contenu au gestionnaire de données.

Dans certains cas, ces procédures ne sont pas appropriés. Si vous voulez traiter des messages binaires et qie votre gestionnaire de données est conçu pour les données binaires, vous devez utiliser la propriété DataEncoding. Cette propriété accepte une des trois valeurs possibles suivantes :

Lorsque c'est possible, il est recommandé d'envoyer les données de contexte dans des messages texte JMS plutôt que d'obliger l'adaptateur à gérer la conversion du format texte au format binaire (ou vice-versa). Un codage incorrect pouvant altérer subtilement les données, il est difficile de le détecter ou de le diagnostiquer. Toutefois, il est possible de préciser comment vous souhaitez que l'adaptateur effectue la conversion entre les format binaire et texte (ou vice-versa), à l'aide d'un modificateur supplémentaire indiqué par la propriété DataEncoding. Si vous ajoutez un caractère ":" au nom d'un codage Java pris en charge, l'adaptateur utilisera le codage précisé pour la conversion. Le format est text:encoding.

Par exemple, DataEncoding=text;ISO8859_1 informe l'adaptateur qu'en cas de réception d'un message binaire, il doit convertir le corps du message en texte à l'aide du codage ISO8859_1, avant de le transmettre au gestionnaire de données. Si le type de message correspond au codage des données, cette valeur n'aura aucun effet (par exemple, si le message binaire et le codage binaire indiquent binaire ou texte, et si le codage des données indique un type texte).

Conception du gestionnaire de données pour les données binaires

Si vous envisagez de concevoir et d'utiliser un gestionnaire de données personnalisé avec l'adaptateur, tenez compte des points suivants :

Configuration d'un méta-objet statique

Le méta-objet statique de configuration JMS contient une liste de propriétés de conversion définies pour différents objets métier. Pour afficher un exemple de méta-objet statique, lancez Business Object Designer et ouvrez l'exemple suivant fourni avec l'adaptateur : connectors\JMS\Samples\Sample_JMS_MO_Config.xsd.

A un moment donné, le connecteur ne prend en charge qu'un seul méta-objet statique. Vous implémentez un méta-objet statique en indiquant son nom dans la propriété du connecteur ConfigurationMetaObject.

La structure du méta-objet statique est telle que chaque attribut représente une combinaison unique d'objet métier et d'instruction, ainsi que toutes les méta-données associées au traitement de cet objet. Le nom de chaque attribut doit être le nom du type d'objet métier et l'instruction, séparés par un caractère souligné, par exemple Customer_Create. Les informations spécifiques à l'application de l'attribut doivent consister en une ou plusieurs paires nom-valeur, séparées par un caractère ";", et représentant les propriétés de méta-données que vous souhaitez préciser pour cette combinaison objet-instruction unique.

Tableau 11. Structure de méta-objet statique
Nom de l'attribut Texte spécifique à l'application
<business object type>_<verb>
    property=value;property=value;...
<business object type>_<verb>
    property=value;property=value;...

Prenons l'exemple du méta-objet suivant 

Tableau 12. Exemple de structure de méta-objet statique
Nom de l'attribut Informations spécifiques à l'application
Customer_Create
    OutputFormat=CUST;OutputDestination=QueueA
Customer_Update
OutputFormat=CUST;OutputDestination=QueueB
Order_Create
OutputFormat=ORDER;OutputDestination=QueueC

Le méta-objet de cet exemple informe le connecteur que lorsqu'il reçoit un objet métier de requête de type Customer avec une instruction Create, il doit le convertir en un message de format CUST, et le placer dans la destination QueueA. Si par contre l'objet client avait une instruction Update, le message serait placé dans QueueB. Si le type d'objet était Order et l'instruction Create, le connecteur convertirait l'objet et le livrerait à QueueC, au format ORDER. Tout autre objet métier transmis au connecteur serait traité comme étant non souscrit.

Si vous le souhaitez, vous pouvez nommer un attribut Default et lui affecter une ou plusieurs propriétés dans l'ASI. Pour tous les attributs contenus dans le méta-objet, les propriétés de l'attribut par défaut sont combinées avec celles des attributs objet-instruction spécifiques. Ceci s'avère utile lorsque vous appliquez une ou plusieurs propriétés de façon universelle (quelle que soit la combinaison objet-instruction). Dans l'exemple suivant, le connecteur considérerait les combinaisons objet-instruction Customer_Update et Order_Create comme ayant OutputDestination=QueueA, en plus de leurs propriétés de méta-données individuelles :

Tableau 13. Exemple de structure de méta-objet statique
Nom de l'attribut Informations spécifiques à l'application
Valeur par défaut
    OutputDestination=QueueA
Customer_Update
OutputFormat=CUST
Order_Create
OutputFormat=ORDER

Voir tableau 10 dans Propriétés du méta-objet, qui décrit les propriétés disponibles en tant qu'informations spécifiques à l'application dans le méta-objet statique.

Pour implémenter un méta-objet statique :

  1. Lancez Business Object Designer. Pour plus d'informations, voir Business Object Development Guide.
  2. Ouvrez l'exemple de méta-objet connectors\JMS\Samples\Sample_JMS_MO_Config.xsd.
    Figure 3. Exemple de méta-objet statique
  3. Modifiez les attributs et l'ASI en fonction de vos besoins, en consultant le tableau 10, puis enregistrez le fichier du méta-objet.
  4. Précisez le nom de ce fichier de méta-objet comme étant la valeur de la propriété du connecteur ConfigurationMetaObject.

Mappage des gestionnaires de données sur les destinations d'entrée

Vous pouvez utiliser la propriété InputDestination dans l'ASI du méta-objet statique, pour associer un gestionnaire de données à une destination d'entrée. Cette fonctionnalité est utile pour travailler avec plusieurs partenaires d'échange dont les exigences en matière de format et de conversion diffèrent.

Pour mapper un gestionnaire de données sur une destination d'entrée :

  1. Lancez Connector Configurator. Pour plus d'informations, voir l'Annexe B. Connector Configurator.
  2. Utilisez les propriétés spécifiques au connecteur (voir InputDestination) pour configurer une ou plusieurs destinations d'entrée. Les noms de destination doivent être séparés par un caractère ";".
  3. Pour chaque destination d'entrée, précisez dans l'ASI la destination (gestionnaire de file d'attente si vous implémentez une messagerie PTP) et un nom de destination d'entrée, ainsi que le nom de classe du gestionnaire de données et le type mime.

Par exemple, l'attribut suivant dans un méta-objet statique associe un gestionnaire de données à un InputDestination nommé CompReceipts :

[Attribute]
 Name = Customer_Create
 Type = String
 Cardinality = 1
 MaxLength = 1
 IsKey = false
 IsForeignKey = false
 IsRequired = false
 AppSpecificInfo =
 InputDestination=//queue.manager/CompReceipts;DataHandlerClassName=com.crossworlds.
 DataHandlers.MQ.disposition_notification;DataHandlerMimeType=message/
 disposition_notification
 IsRequiredServerBound = false
 [End]

Configuration d'un méta-objet enfant dynamique

S'il est difficile ou infaisable de préciser les méta-données nécessaires via un méta-objet statique, le connecteur a la possibilité d'accepter les métadonnées livrées lors de l'exécution pour chaque instance d'objet métier.

Les méta-objet dynamiques vous permettent de modifier les méta-données utilisées par le connecteur pour traiter un objet métier en fonction de chaque requête, lors du traitement de celle-ci, et d'extraire des informations sur un message d'événement pendant le traitement de l'événement.

La structure du méta-objet dynamique est telle que chaque attribut représente une propriété et une valeur de méta-données uniques :meta-object property name =meta-object property value

Pour implémenter un méta-objet dynamique, ajoutez-le en tant qu'enfant à votre objet de niveau supérieur et incluez la paire nom-valeur cw_mo_conn=<MO attribute> à votre ASI d'objet de niveau supérieur, où <MO attribute> est le nom de l'attribut de votre objet de niveau supérieur représentant le méta-objet dynamique. Par exemple :

Customer (ASI = cw_mo_conn=MetaData)
   |-- Id
   |-- FirstName
   |-- LastName
   |-- ContactInfo
   |-- MetaData
         |-- OutputFormat = CUST
         |-- OutputDestination = QueueA

Dès réception d'une requête renseignée comme indiqué ci-dessus, le connecteur convertit l'objet Customer en un message au format CUST , puis le place dans la file d'attente QueueA.

Les objets métier peuvent utiliser des méta-objets dynamiques identiques ou différents, ou n'en utiliser aucun.

Remarque :
Tous les gestionnaires de données IBM WebSphere standard sont conçus pour ignorer cet attribut de méta-objet dynamique en reconnaissant la balise cw_mo_. Vous devez procéder de la même façon lors du développement de gestionnaires de données personnalisés à utiliser avec l'adaptateur.

Le connecteur reconnaît et lit les propriétés de conversion à partir d'un méta-objet dynamique ajouté en tant qu'enfant à l'objet métier de niveau supérieur transmis au connecteur. Les valeurs d'attribut du méta-objet enfant dynamique dupliquent les propriétés de conversion que vous pouvez préciser par le biais du méta-objet statique utilisé pour configurer le connecteur.

Comme les propriétés de méta-objet enfant dynamique remplacent celles des méta-objets statiques, si vous spécifiez un méta-objet enfant dynamique, vous devez inclure une propriété de connecteur qui indique le méta-objet statique. Par conséquent, vous pouvez utiliser un méta-objet enfant dynamique indépendamment du méta-objet statique et vice-versa.

Voir tableau 10 dans Propriétés du méta-objet, qui décrit les propriétés disponibles en tant qu'informations spécifiques à l'application dans le méta-objet dynamique.

Les attributs suivants, qui reflètent les propriétés de l'en-tête JMS, sont reconnues dans le méta-objet dynamique.

Tableau 14. Attributs d'en-tête du méta-objet dynamique
Nom de l'attribut d'en-tête Mode En-tête JMS correspondant
CorrelationID
Lecture/écriture JMSCorrelationID
ReplyToQueue
Lecture/écriture JMSReplyTo
DeliveryMode
Lecture/écriture JMSDeliveryMode
Priority (Priorité)
Lecture/écriture JMSPriority
Destination
Lecture JMSDestination
Expiration
Lecture JMSExpiration
MessageID
Lecture JMSMessageID
Redelivered
Lecture JMSRedelivered
TimeStamp
Lecture JMSTimeStamp
Type
Lecture JMSType
UserID
Lecture JMSXUserID
AppID
Lecture JMSXAppID
DeliveryCount
Lecture JMSXDeliveryCount
GroupID
Lecture JMSXGroupID
GroupSeq
Lecture JMSXGroupSeq
JMSProperties
Lecture/écriture

Les attributs en lecture seule sont lus à partir d'un en-tête de message pendant la notification d'événement, et écrits dans le méta-objet dynamique. Ces propriétés renseignent également le MO dynamique lorsqu'un message de réponse est émis au cours du traitement d'une requête.Les attributs en lecture/écriture sont définis dans les en-tête de messages créés au cours du traitement de la requête. Pendant la notification d'événement, les attributs en lecture/écriture sont lus à partir des en-têtes de messages pour renseigner le méta-objet dynamique.

Pour implémenter un méta-objet dynamique :

  1. Lancez Business Object Designer. Pour plus d'informations, voir Business Object Development Guide.
  2. Ouvrez l'exemple de méta-objet connectors\JMS\Samples\Sample_JMS_DynMO.xsd.
    Figure 4. Exemple de méta-objet dynamique
  3. Modifiez les attributs et propriétés en fonction de vos besoins pour cet objet métier, et enregistrez-le.
  4. Ajoutez le méta-objet dynamique en tant qu'enfant à votre objet de niveau supérieur, et insérez une paire nom-valeur cw_mo_conn=<MO attribute> dans votre ASI d'objet de niveau supérieur, où <MO attribute> est le nom de l'attribut dans votre objet de niveau supérieur représentant le méta-objet dynamique.

Alimentation du méta-objet enfant dynamique pendant l'interrogation

Pour fournir des collaborations dotées d'informations plus nombreuses sur les messages extraits lors de l'interrogation, le connecteur renseigne des attributs spécifiques du méta-objet dynamique, s'ils ont déjà été définis pour l'objet métier créé.

Le tableau 15 montre comment structurer un méta-objet enfant dynamique en vue de l'interrogation.

Tableau 15. Structure de méta-objet enfant dynamique JMS pour interrogation
Nom de l'attribut Exemple de valeur
InputFormat
CUST_IN
InputQueue
MYInputQueue
OutputFormat
CxIgnore
OutputQueue
CxIgnore
ResponseTimeout
CxIgnore
TimeoutFatal
CxIgnore

Comme indiqué au tableau 15, vous pouvez définir dans un méta-objet enfant dynamique les attributs supplémentaires Input_Format et Inputdestination. L'attribut Input_Format est renseigné avec le format du message extrait, tandis que l'attribut InputDestination contient le nom de la destination d'où a été extrait un message donné. Si ces propriétés ne sont pas définies dans le méta-objet enfant, elles ne sont pas renseignées.

Exemple de scénario :

En-têtes JMS et attributs de méta-objet enfant dynamique

Vous pouvez ajouter des attributs à un méta-objet dynamique pour obtenir plus d'informations sur le transfert des messages, ainsi qu'un meilleur contrôle. La présente section décrit ces attributs et la façon dont ils affectent la notification d'événement et le traitement des requêtes.

Propriétés JMS

Contrairement aux autres attributs du méta-objet dynamique, JMSProperties doit définir un objet enfant à cardinalité unique. Chaque attribut de cet objet enfant doit définir une propriété unique, afin qu'elle soit lue/écrite dans la partie variable de l'en-tête de message JSM, de la façon suivante :

  1. Le nom de l'attribut n'a aucune valeur sémantique.
  2. Le type de l'attribut doit toujours être String, quel que soit le type de propriété JMS.
  3. Les informations spécifiques à l'application de l'attribut doivent contenir deux paires nom-valeur, définissant le nom et le format de la propriété du message JMS auquel l'attribut est mappé. Le nom est défini par l'utilisateur. La valeur doit appartenir à un des types suivants :

Le tableau ci-dessous montre les propriétés des informations spécifiques à l'application que vous devez définir pour les attributs de l'objet JMSProperties.

Tableau 16. Informations spécifiques à l'application des attributs de propriété JMS
Attribut Valeurs possibles ASI Commentaires
Nom Tout nom de propriété JMS valide (valide = compatible avec le type défini dans l'ASI) name=<JMS property name>;type=<JMS property type> Certains fournisseurs réservent certaines propriétés pour apporter une fonctionnalité étendue. En général, les utilisateurs ne doivent pas définir de propriétés personnalisées qui commencent par JMS, à moins qu'ils ne cherchent à accéder à ces fonctionnalités spécifiques au fournisseur.
Type String type=<voir commentaires> Type de la propriété JMS. L'API JMS propose plusieurs méthodes pour définir des valeurs dans le message JMS : setIntProperty, setLongProperty, setStringProperty, etc. Le type de propriété JMS indiqué ici détermine laquelle de ces méthodes est utilisée pour paramétrer la valeur de propriété dans le message.

Dans l'exemple ci-dessous, un objet enfant JMSProperties est défini pour que l'objet Customer autorise l'accès aux zones définies par l'utilisateur de l'en-tête du message :

Customer (ASI = cw_mo_conn=MetaData)
   |-- Id
   |-- FirstName
   |-- LastName
   |-- ContactInfo
   |-- MetaData
         |-- OutputFormat = CUST
         |-- OutputDestination = QueueA
         |-- JMSProperties
              |-- RoutingCode = 123 (ASI= name=RoutingCode;type=Int)
              |-- Dept = FD (ASI= name=RoutingDept;type=String)

Pour illustrer un autre exemple, la figure 5 montre l'attribut JMSProperties dans le méta-objet dynamique ainsi que des définitions pour quatre propriétés dans l'en-tête de message JMS : ID, GID, RESPONSE et RESPONSE_PERSIST. Les informations spécifiques à l'application de ces attributs définissent le nom et le type de chacun. Par exemple, l'ID d'attribut se mappe sur la propriété JMS ID de type String.

Figure 5. Attribut de propriétés JMS dans un méta-objet dynamique

Copyright IBM Corp. 2003, 2005