Création et personnalisation des services REST avec la structure de mappage BOD

HCL Commerce fournit un Java Emitter Template (JET) appelé modèle de ressource RESTful JET dans la structure de mappage BOD. Le modèle de ressource RESTful JET génère une classe Java annotée JAX-RS qui fournit le service REST pour une ressource spécifique. Pour générer ces fichiers, vous devez créer un fichier d'entrée du modèle qui contient les spécifications requises pour implémenter le service REST à l'aide d'un nom BOD.

Conditions préalables à l'utilisation du modèle de ressources RESTful JET

Le modèle de ressource RESTful JET fonctionne sur Eclipse Modeling Framework (EMF) et utilise lava Emitter Templates (JET) pour générer le code source. Assurez-vous que EMF avec JET est installé dans votre environnement de développement avant de commencer.

Assurez-vous d'installer le package JET dans votre environnement HCL Commerce Developer. Pour plus d'informations, voir Installation du package Java Emitter Template (JET).

Assurez-vous que les ID de plug-in suivants sont installés :

org.eclipse.emf.codegen
com.ibm.commerce.toolkit.internal.pattern.rest

Format du fichier d'entrée de modèle

Les fichiers d'entrée de modèle fournissent les informations requises au modèle de ressource RESTful JET dans le format suivant :


<rest 
   componentName="component_name" 
   packageNamePrefix="package_name_prefix">
  <noun 
        name="noun_name" 
        pluralNounName="plural_noun_name" 
        resourceName="resource_name"
      actionExpression="action_expression" 
        actionExpressionSuffix="action_expression_suffix" 
        defaultAccessProfile="default_access_profile" 
        defaultExpression="default_get_xpath_expression">
       <findBy 
         expression="get_xpath_expression" 
         name="findby_name"
         accessProfile="get_access_profile"/>
       <delete 
         key="key_to_delete" 
         method="delete_method"/>
       <create 
         for="create_for" 
         method="create_method"/>
   <update 
         for="update_for" 
         method="update_method"/>
  </noun>
</rest>

Remarque : Il n'est pas obligatoire que la valeur resourceName corresponde au nom du nom dans un fichier XML d'entrée du modèle. Assurez-vous que le nom resourceName que vous spécifiez ne correspond à aucune des ressources REST par défaut.

La table suivante décrit des variables du fichier d'entrée du modèle XML :


Variable du fichier d'entrée	Obligatoire	Description
`component_name`	Oui	Nom du composant qui contient le service Web à partir duquel vous souhaitez créer un service REST. Si vous utilisez un service HCL Commerce existant, obtenez le nom du composant en affichant la liste dans le sujet suivant : HCL Commerce Services Web Exemples de noms de composant : Catalogue Marketing. Ordre Si vous créez un service REST à partir d'un service Web HCL Commerce personnalisé, utilisez le nom du composant qui contient le service Web personnalisé.
`package_name_prefix`	Oui	Préfixe du package qui contient la classe Java générée par ce modèle. Pour un service REST à partir d'un nom HCL Commerce, utilisez `com.ibm.commerce`. Pour un service REST à partir d'un nom personnalisé, utilisez `com.your_company_name.commerce`, par exemple, `com.mycompany.commerce`.
`noun_name`	Oui	Le nom du nom que vous souhaitez utiliser pour implémenter le service REST. Pour afficher les noms disponibles pour les composants HCL Commerce, voir Services Web de HCL Commerce.
`plural_noun_name`	Oui	La forme plurielle du nom que vous souhaitez utiliser pour implémenter le service REST. La convention consiste à spécifier la même valeur singulière dans une URL RESTful. Par exemple, si un nom est Person, `noun_name` et `plural_noun_name` doit être défini sur Person.
`resource_name`	Non	Le nom de la ressource REST que vous souhaitez spécifier pour un service REST.
`action_expression`	Non	L'expression d'action pour le nom ou son sous-nom. Par exemple : `AddressBook/Contact`.
`action_expression_suffix`	Non	Le suffixe d'expression d'action pour le nom ou son sous-nom. Par exemple : `[1]`.
`default_access_profile`	Oui	Nom du profil d'accès de la vitrine par défaut à utiliser pour la requête de service HCL Commerce. Le profil d'accès définit les données à inclure dans la réponse. Des profils d'accès sont définis pour chaque nom des services Web de HCL Commerce. Généralement, les profils d'accès de la vitrine commencent par `IBM_Store` au lieu de `IBM_Admin`.
`default_get_xpath_expression`	Non	L'expression XPath pour le service GET qui extrait toutes les instances d'un nom, au lieu de renvoyer une instance spécifique du nom en fonction de son identificateur. N'incluez ce paramètre dans votre fichier d'entrée de modèle que si vous avez besoin que la ressource JAX-RS obtienne toutes les instances d'un nom. Par exemple, le nom Catalogue contient une expression XPath GET qui extrait tous les catalogues de vente pour le magasin. Dans ce cas, l'attribut du fichier d'entrée de modèle est : `defaultExpression="/Catalog[@primary='false']"` Si votre URL RESTful ne contient pas d'identificateur, la ressource JAX-RS utilise l'`default_get_xpath_expression`.
`get_xpath_expression`	Oui 1	L'expression XPath pour le service GET qui extrait un nom à l'aide de l'identificateur interne ou externe que vous avez spécifié dans l'URL dans la procédure précédente. Exemple d'expression XPath utilisant un service Obtenir le catalogue-identificateur interne : `/Catalog[CatalogIdentifier[(UniqueID=)]]` Cette expression XPath extrait un catalogue en fonction de son ID unique et renvoie le catalogue qui correspond à l'identificateur. Important : Lorsque vous incluez l'expression XPath dans le fichier d'entrée du modèle, indiquez les caractères suivants pour la valeur UniqueID numérique, quel que soit le contenu de l'expression XPath documentée : `{0}` L'exemple précédent d'expression XPath doit ressembler à la chaîne suivante dans le fichier d'entrée du modèle : `/Catalog[CatalogIdentifier[(UniqueID={0})]]` Remarque : HCL Commerce ne fournit pas de service Web RESTful pour le nom Catalogue, mais vous pouvez en créer un en utilisant les procédures décrites dans cette section. Exemple d'expression XPath utilisant un service Obtenir MarketingSpotData-identificateur externe : `/MarketingSpotData[MarketingSpotIdentifier[ExternalIdentifier[(Name=)]]]` Cette expression XPath extrait les données d'un emplacement e-marketing en fonction de son identificateur externe (en l'occurrence, son nom) et renvoie les données à afficher pour un client. Important : Lorsque vous incluez l'expression XPath dans le fichier d'entrée du modèle, si la valeur de l'identificateur est une chaîne, indiquez les caractères suivants pour la valeur de chaîne, quel que soit le contenu de l'expression XPath documentée : `\"{0}\"` L'exemple précédent d'expression XPath doit ressembler à la chaîne suivante dans le fichier d'entrée du modèle : `/MarketingSpotData[MarketingSpotIdentifier[ExternalIdentifier[(Name=\"{0}\")]]]`
`findby_name`	Oui 1	Le suffixe du nom de méthode qui est appelé lorsque l'URL contient un identificateur. Le modèle crée une méthode en utilisant ce suffixe pour le nom. Dans la classe Java générée, le nom de méthode complet is `findByfindby_name`. L'élément `findby_name` doit correspondre à l'identificateur spécifié pour l'expression XPath pour le service Get. Par exemple, pour l'expression XPath Obtenir le catalogue de la ligne précédente, une valeur appropriée pour `findby_name` est `Id`.
`get_access_profile`	Oui 1	Nom du profil d'accès à utiliser pour la requête de service HCL Commerce. Le profil d'accès définit les données à inclure dans la réponse.
`key_to_delete`	Oui 1	La clé ou l'identificateur unique pour supprimer une ressource dans un service HCL Commerce.
`delete_method`	Oui 1	La méthode de suppression d'une classe de façade client de service HCL Commerce, qui prend comme `Map` paramètre. Par exemple : `MemberFacadeClient.deleteAddressForPerson(java.util.Map)`.
`create_for`	Oui 1	La ressource à créer à l'aide d'un service HCL Commerce.
`create_method`	Oui 1	La méthode de création d'une classe de façade client de service HCL Commerce, qui prend comme `Map` paramètre. Par exemple : `MemberFacadeClient.addAddressForPerson(java.util.Map)`.
`update_for`	Oui 1	La ressource à mettre à jour à l'aide d'un service HCL Commerce.
`update_method`	Oui 1	La méthode de mise à jour d'une classe de façade client de service HCL Commerce, qui prend comme `Map` paramètre. Par exemple : `MemberFacadeClient.updateAddressForPerson(java.util.Map)`.

Remarque : 1 Ces variables sont requises si les actions respectives (findBy, créer, mettre à jour et supprimer) sont définies. Au moins une définition d'action est requise pour le nom. Plusieurs noms et actions sont pris en charge dans le fichier de modèle XML d'entrée. Le fichier de modèle XML d'entrée doit contenir des valeurs uniques pour les noms des clé, des noms et des méthodes.

Exemple de fichier d'entrée de modèle

Cet exemple de fichier d'entrée génère les classes Java et les fichiers de propriétés qui sont nécessaires pour utiliser le service membre afin de créer, mettre à jour, récupérer et supprimer les ressources disponibles :


<rest 
   componentName="Member" 
   internal="false" 
   packageNamePrefix="com.ibm.commerce">
  <noun 
       name="Person" 
       pluralNounName="Person" 
       resourceName="Person"
     actionExpression="AddressBook/Contact" 
       actionExpressionSuffix="" 
       defaultAccessProfile="IBM_Store_Details" 
       defaultExpression="{self=true}/Person">
    <findBy 
      expression="/Person[PersonIdentifier[(UniqueID={0})]]" 
      name="UniqueID" 
      accessProfile="IBM_Store_Details"/>
    <findBy 
      expression="/Person[Credential[LogonID={0}]] " 
      name="LogonID" 
      accessProfile="IBM_Store_Details"/>
    <delete 
      key="ContextAttribute" 
      method="deleteContextAttributeForPerson"/>
    <create 
      for="Person" 
      method="registerPerson"/>
    <update 
      for="Person" 
      method="updatePerson"/>
  </noun>
</rest>

Génération de code source

Effectuez les étapes suivantes pour générer le code source des services REST :

Créez un fichier XML sous le répertoire de projet/emplacement de personnalisation (WebSphereCommerceServerExtensionsLogic) et copiez-y un exemple de fichier d'entrée. Effectuez les modifications requises au niveau du fichier en fonction de la table des spécifications d'entrée à partir de la section Format du fichier d'entrée du modèle.
Enregistrez le fichier avec vos modifications. Cliquez ensuite avec le bouton droit sur le fichier et sélectionnez Exécuté en tant que > Exécuter la configuration.
Sélectionnez Transformation JET, puis cliquez avec le bouton droit et sélectionnez Nouveau. Une nouvelle configuration est créée.
Le fichier XML généré apparaît dans la section Entrée de transformation. Sélectionnez l'ID de transformation sous com.ibm.commerce.toolkit.internal.pattern.rest :
Sélectionnez Appliquer > Exécuter pour lancer la transformation.
Après avoir réussi l'exécution de la transformation, les fichiers de sortie sont générés sous WebSphereCommerceServerExtensionsLogicproject.
Vérifiez les éventuelles erreurs de compilation dans les classes Java, qui pourraient se produire en raison de fichiers JAR manquants dans le chemin de classes, et corrigez-les.

Emplacement du fichier de sortie de modèle

Le modèle génère des fichiers dans les répertoires suivants :

Classes du gestionnaire de ressources: src\package_name.rest.extension.resource_name.handler
Classes d'aide aux ressources: src\package_name.rest.extension.bod.helpers
Fichiers XML de mappage BOD: WebContent\WEB-INF\config\bodMapping-ext
Fichier XML de la bibliothèque client du service: WebContent\WEB-INF\config\bodMapping-ext
Fichier des propriétés de ressource: WebContent\WEB-INF\config
Fichiers XML de configuration des ressources: WebContent\WEB-INF\config\com.ibm.commerce.rest-ext

Consommation du code généré

Effectuez les étapes suivantes pour consommer le code généré pour la personnalisation :

Copiez le fichier rest-resource_name-clientobjects.xml à l'emplacement similaire sous le projet REST dans votre espace de travail. Ajoutez un chemin XPath supplémentaire aux mappages d'attributs pour le nom que vous avez sélectionné dans le fichier XML d'entrée. Le chemin XPath est alimenté par les données de réponse en fonction des attributs mappés.
Copiez le fichier resources-ext.properties à l'emplacement similaire du projet REST ou fusionnez les entrées de fichiers pour la classe du gestionnaire de ressources nouvellement ajoutée.
Copiez le fichier wc-rest-resourceconfig.xml à l'emplacement similaire dans le projet REST. Créez le dossier WEB-INF\config\com.ibm.commerce.rest-ext, si celui-ci n'existe pas déjà.
Copiez le fichier wc-service-client-library.xml à l'emplacement similaire du projet REST ou fusionnez les entrées de fichiers pour la classe du gestionnaire de ressources nouvellement ajouté.

Test de la personnalisation

Redémarrez le serveur de test et invoquez l'URI pour la classe de gestionnaire de ressources nouvellement ajoutée.

L'URI doit ressembler à l'adresse suivante :

Pour une requête Get (Person à partir du contexte) :

http://host_name/wcs/resources/store/10101/person

Pour une requête Get (Person avec ID d'ouverture de session) :

http://host_name/wcs/resources/store/10101/person/byLogonId/personID