Structure de mappage de la commande de contrôleur et des beans de données basée sur la configuration

La structure de mappage de la commande de contrôleur et des beans de données basée sur la configuration permet l'activation de beans de données ou l'exécution des commandes de contrôleur à l'aide des services REST. La structure réduit considérablement la quantité de code personnalisé nécessaire. Elle fournit un moyen de décrire les entrées et sorties requises à partir d'une commande de contrôleur ou un bean de données à travers un fichier de mappage. Un fichier de mappage représente un bean de données ou une commande de contrôleur. Il est ensuite subdivisé en profils, permettant à plusieurs ressources REST ayant des propriétés différentes de fonctionner sur le même bean de données ou la même commande de contrôleur. Le code personnalisé requis pour écrire un gestionnaire de ressources pour une seule ressource REST peut être aussi simple qu'une seule ligne. Le mappage d'entrée, la conversion de type, l'activation, l'exécution et les réponses sont tous gérés par la structure. Pour aider à générer un gestionnaire et un fichier et de mappage personnalisés, un outil générateur est fourni (restClassicSampleGen), réduisant encore l'effort de création de ressources REST personnalisées.

Remarque : Cette structure n'utilise pas l'objet des propriétés de requête (méthode setRequestProperties) pour les commandes de contrôleur. Vous devez définir des méthodes individuelles d'accès set et d'accès get dans la commande de contrôleur. Si vous devez utiliser les propriétés de la requête, utilisez directement AbstractClassicResourceHandler.

La structure de mappage de la commande de contrôleur et des beans de données basée sur la configuration utilisent les concepts suivants :

AbstractConfigBasedClassicHandler: Le point d'entrée principal (superclasse) à partir duquel tous les gestionnaires basés sur la configuration s'étendent.; L'extrait est lui-même une sous-classe AbstractClassicResourceHandler, qui est la classe de base d'un gestionnaire de ressources REST.; Vous y trouverez les méthodes d'activation des beans de données et d'exécution des commandes de contrôleur.
Modèles de bean de données et de commande de contrôleur: En interne, les beans de données et les commandes de contrôleur sont analysés sur demande dans les modèles, qui sont ensuite mis en cache et utilisés par la structure.
Configuration des mappages du bean de données et du contrôleur de commande à REST: Pour effectuer des appels REST vers des beans de données et des commandes de contrôleur, des fichiers de configuration de mappage sont utilisés.; Ces fichiers de configuration de mappage sont divisés en profils, qui permettent différents types d'appels pour le même bean de données ou la même commande de contrôleur. Par exemple, pour spécifier différentes valeurs de sortie par profil.; Les profils sont inclus par défaut pour les services du contrôleur de commande et du bean de données REST, tandis que vous pouvez ajouter vos propres profils à un répertoire d'extension de personnalisation.; Chaque fichier de configuration existe pour un seul bean de données ou une seule commande de contrôleur. Ils décrivent le mappage des noms d'entrée (depuis l'appel REST) à la méthode d'accès de type set du bean de données ou de la commande de contrôleur correspondant. Pour chaque profil du fichier, des mappages de sortie sont fournis. Ils décrivent comment les propriétés et les méthodes d'accès de type get du bean de données de données ou de la commande de contrôleur doivent être mappés à une sortie d'entité REST. Par exemple, au format JSON.

Le diagramme suivant montre la structure de mappage de commande et de bean de données basée sur la configuration :
Structure de mappage de la commande de contrôleur et des beans de données basée sur la configuration

Structure de mappage de la commande de contrôleur et des beans de données basée sur la configuration

Où :

Un appel REST est effectué pour accéder à un bean de données (GET) ou à une commande de contrôleur (POST).
Le gestionnaire de commande de contrôleur ou de beans de données du contrôleur intercepte l'appel. Il demande à la structure REST basée sur la configuration de définir les propriétés pour le bean de données ou la commande de contrôleur, d'activer et de renvoyer la réponse.
La structure exécute les tâches suivantes :
1. Introspecte la classe du bean de données ou de la commande de contrôleur pour générer son modèle. Ce modèle est ensuite mis en cache. Une exception RestException se produit en cas de problème avec le modèle.
  Remarque : Les méthodes d'accès set qui ont le même nom mais prennent des paramètres différents, par exemple Chaîne versus Long, sont prises en compte. Le paramètre idéal est choisi, en fonction du type de données transmis pour la méthode d'accès set.
2. Analyse le profil de mappage, afin qu'il puisse déterminer comment mapper entre l'appel REST et le bean de données ou la commande de contrôleur. Ensuite, il mappe à nouveau la réponse au format HTTP demandé. Par exemple, JSON. Le profil de mappage est ensuite mis en cache. Une exception RestException se produit en cas de problème avec le fichier de mappage.
3. Instancie le bean de données ou la commande de contrôleur.
4. Rempli les méthodes d'accès set en fonction du fichier de mappage et des données fournies depuis l'appel REST.
5. Active le bean de données ou exécute la commande de contrôleur.
6. Construit la réponse à l'aide du modèle de mappage pour déterminer quelles méthodes de réponse (méthodes d'accès de type get) faire appel au bean de données ou à la commande de contrôleur.
Une fois que toutes les valeurs sont récupérées, la réponse est renvoyée au gestionnaire principal, puis transmise au client.

Points d'entrée de la structure

Un appel REST nécessite toujours la création d'un gestionnaire, basé sur Apache Wink/JAX-RS. Le gestionnaire est relativement petit. Il est généralement requis pour définir les annotations d'Apache Wink pour comprendre comment effectuer l'appel REST au gestionnaire et fournir les informations demandées. Le code contenu dans le gestionnaire est généralement une ligne de code, qui constitue le point d'entrée dans le gestionnaire classique basé sur la configuration. Les points d'entrée suivants sont disponibles par défaut :

public Response executeConfigBasedBeanWithContext(String beanClassName, String profileName, String responseFormat, Map<String, Object> paramOverrideMap)
Cette méthode définit la requête de démarrage {@link BusinessContextService}, puis délègue à {@link #executeConfigBasedBean(String, String, String, Map)}, et termine finalement la requête BCS.
Les paramètres suivants sont disponibles par défaut :

beanClassName

Le nom de la classe de bean de données.

profileName

Le nom de profil du bean de données dans la configuration.

responseFormat

Le format de réponse à utiliser pour générer le résultat.

paramOverrideMap

Définit tous les paramètres que vous souhaitez ajouter ou remplacer à partir de l'objet de requête associé à ce gestionnaire.

Généralement utilisé s'il y a des paramètres de chemin d'accès ou des données d'entité que vous souhaitez inclure lorsqu'il mappe les paramètres de la requête à l'entrée de la commande.

La clé doit être une chaîne. La valeur peut être n'importe quel objet type.

Il est possible que la valeur soit nulle.
public JSONObject executeConfigBasedBean(String beanClassName, String profileName, String responseFormat, Map<String, Object> paramOverrideMap) throws Exception
Cette méthode traite une requête de bean de données à l'aide des mappages de profil basés sur la configuration. Elle suppose que {@link BusinessContextService} est traité par l'appleant.
Les paramètres d'entrée sont automatiquement complétés en fonction des paramètres de chemin d'accès spécifiés dans l'URL, suivis de n'importe quel paramètre de requête.
Une mappe de remplacement peut être fournie pour injecter plus de paramètres ou remplacer les paramètres préexistants.
Les paramètres suivants sont disponibles par défaut :

beanClassName

Le nom de la classe de bean de données.

profileName

Le nom de profil du bean de données dans la configuration.

responseFormat

Le format de réponse à utiliser pour générer le résultat.

paramOverrideMap

Définit tous les paramètres que vous souhaitez ajouter ou remplacer à partir de l'objet de requête associé à ce gestionnaire.

Généralement utilisé s'il y a des paramètres de chemin d'accès ou des données d'entité que vous souhaitez inclure lorsqu'il mappe les paramètres de la requête à l'entrée de la commande.

La clé doit être une chaîne. La valeur peut être n'importe quel objet type.

Il est possible que la valeur soit nulle.
public Response executeConfigBasedCommandWithContext(String commandInterfaceName, String profileName, String responseFormat, String storeId, Map<String, Object> paramOverrideMap)
Cette méthode définit la requête de démarrage {@link BusinessContextService}, puis délègue à * {@link #executeControllerCommand(String, String, TypedProperty, String)}, et termine finalement la requête BCS.
Les paramètres suivants sont disponibles par défaut :

commandInterfaceName

Le nom de l'interface de commande de contrôleur.

profileName

Le nom de profil de la commande de contrôleur dans la configuration.

responseFormat

Le format de réponse à utiliser pour générer le résultat.

paramOverrideMap

Définit tous les paramètres que vous souhaitez ajouter ou remplacer à partir de l'objet de requête associé à ce gestionnaire.

Généralement utilisé s'il y a des paramètres de chemin d'accès ou des données d'entité que vous souhaitez inclure lorsqu'il mappe les paramètres de la requête à l'entrée de la commande.

La clé doit être une chaîne. La valeur peut être n'importe quel objet type.

Il est possible que la valeur soit nulle.
public JSONObject executeConfigBasedCommand(String pCmdInterfaceName, String profileName, String responseFormat, String storeId, Map<String, Object> paramOverrideMap) throws Exception
Cette méthode traite une requête de commande de contrôleur à l'aide des mappages de profil basés sur la configuration. Elle suppose que {@link BusinessContextService} est traité par l'appleant
Les paramètres d'entrée sont automatiquement complétés en fonction des paramètres de chemin d'accès spécifiés dans l'URL, suivis de n'importe quel paramètre qui se trouve dans le corps de la requête.
Une mappe de remplacement peut être fournie pour injecter plus de paramètres ou remplacer les paramètres préexistants.
Bien que l'ID de magasin soit spécifié dans l'appel de méthode, il n'est pas automatiquement inclus dans la liste des paramètres fournis pour remplir les méthodes d'accès set de la commande. Vous devez l'ajouter explicitement à la mappe de remplacement ou l'inclure avec les paramètres du chemin d'accès de l'URL ou le corps de la requête.

pCmdInterfaceName

Le nom de l'interface de commande du contrôleur.

profileName

Le nom de profil de la commande de contrôleur dans la configuration.

responseFormat

Le format de réponse à utiliser pour générer le résultat.

storeId

ID du magasin.

paramOverrideMap

Définit tous les paramètres que vous souhaitez ajouter ou remplacer à partir de l'objet de requête associé à ce gestionnaire.

Généralement utilisé s'il y a des paramètres de chemin d'accès ou des données d'entité que vous souhaitez inclure lorsqu'il mappe les paramètres de la requête à l'entrée de la commande.

La clé doit être une chaîne. La valeur peut être n'importe quel objet type.

Il est possible que la valeur soit nulle.

Fichiers de mappage

Les points intégrés et d'extension sont composés de quatre répertoires :

Rest.war/WebContent/WEB-INF/config/beanMapping: Réservé à un usage interne HCL. Contient les profils de beans de données par défaut.
Rest.war/WebContent/WEB-INF/config/beanMapping-ext: Utilisé pour publier de nouveaux beans de données et étendre les beans de données par défaut.
Rest.war/WebContent/WEB-INF/config/commandMapping: Réservé à un usage interne HCL. Contient les profils de commande contrôleur par défaut.
Rest.war/WebContent/WEB-INF/config/commandMapping-ext: Utilisé pour publier de nouvelles commandes de contrôleur et étendre les commandes de contrôleur par défaut.

Les fichiers de configuration sont nommés d'après le nom entièrement qualifié du bean de données ou de la commande de contrôleur qu'ils exposent. Tous les profils des répertoires d'extension sont prioritaires sur ceux des répertoires par défaut. Cela vous permet de remplacer les profils par défaut. Toutefois, la méthode préférée consiste à sous-classer un bean de données ou à créer une nouvelle interface de commande de contrôleur qui en étend une autre et à se référer au profil d'origine dans son propre profil.

Création de fichiers de mappage

Vous pouvez créer les fichiers de mappage XML à l'aide de l'utilitaire restClassicSampleGen ou manuellement.

Pour plus d'informations sur son utilisation, voir Création de services REST à l'aide de la structure de mappage de la commande de contrôleur et des beans de données basée sur la configuration.

Exemple de fichier de mappage de beans de données

Le fragment suivant est un exemple de fichier de mappage de bean de données pour un exemple de profil. Les entrées de méthode de sortie peuvent être imbriquées, pour permettre la récupération de données imbriquées à partir du résultat d'une autre méthode :

com.ibm.commerce.common.beans.StoreDataBean.xml


<?xml version="1.0" encoding="UTF-8"?>
<bean>
   <profiles>
      <profile name="IBM_Store_Summary">
         <inputs>
            <input methodName="setStoreId" inputName="storeId"/>
            <input methodName="setStoreRelationshipTypeName" inputName="storeRelationshipTypeName"/>
            <input methodName="setJspStoreDir" inputName="jspStoreDir"/>
         </inputs>
         <outputs>
            <output methodName="getStoreLevel" outputName="storeLevel"/>
            <output methodName="getFilePath" outputName="filePath"/>
            <output methodName="getJspPath" outputName="jspPath"/>
            <output methodName="getJspStoreDirFilePath" outputName="jspStoreDirFilePath"/>
            <output methodName="getJspStoreDir" outputName="jspStoreDir"/>
            <output methodName="getStoreLevel" outputName="storeLevel"/>
            <output methodName="getStoreType" outputName="storeType"/>
            <output methodName="getDirectory" outputName="directory"/>
            <output methodName="getRelatedStoresByStoreRelationshipTypeName" outputName="relatedStores"/>
            <output methodName="getStoreEntityDescriptionDataBean" outputName="storeEntityDescription">
               <output methodName="getDisplayName" outputName="displayName"/>
            </output>
         </outputs>
      </profile>
      <profile name="IBM_Store_DisplayName">
         <inputs>
            <input methodName="setStoreId" inputName="storeId"/>
            <input methodName="setStoreRelationshipTypeName" inputName="storeRelationshipTypeName"/>
            <input methodName="setJspStoreDir" inputName="jspStoreDir"/>
         </inputs>
         <outputs listName="resultList" >
            <output methodName="getStoreEntityDescriptionDataBean" outputName="storeEntityDescription">
               <output methodName="getDisplayName" outputName="displayName"/>
            </output>
         </outputs>
      </profile>
   </profiles>
</bean>

Exemple de fichier de mappage de commande de contrôleur

Le fragment suivant est un exemple de fichier de mappage de commande de contrôleur pour un exemple de profil :

com.ibm.commerce.catalogmanagement.commands.CatalogEntryUpdateCmd.xml


<?xml version="1.0" encoding="UTF-8"?>
<command>
   <inputs>
      <input inputName="auxdescription1" methodName="setAuxdescription1"/>
      <input inputName="auxdescription2" methodName="setAuxdescription2"/>
      <input inputName="catentryId" methodName="setCatentryId"/>
   </inputs>
   <profiles>
      <profile name="sample">
         <outputs>
            <output methodName="getCatentryId" outputName="catentryId"/>
         </outputs>
      </profile>
   </profiles>
</command>

Structure de fichiers de mappage

Les fichiers de mappage utilisent la structure suivante :

bean ou commande

Elément racine du fichier de configuration.

entrées: Liste des entrées du bean de données ou du contrôleur de commande. Les entrées sont fusionnées entre la version par défaut et la version d'extension du fichier.
profiles: Liste des profils exposés sous forme de sortie du bean de données ou de la commande de contrôleur.

entrée

Elément qui représente une entrée au niveau d'un beau de données ou d'une commande de contrôleur.

methodName: Nom de la méthode pour appeler le bean de données ou le contrôleur de commande pour définir la propriété d'entrée. Par exemple : setCatalogId.
inputName: Le nom de l'entrée qui est lue à partir de la requête.
required: Spécifie si l'entrée est obligatoire (true ou false). Les entrées obligatoires manquantes entraînent des échecs de requête.

profil

Un profil représente un sous-ensemble des zones de sortie d'un bean de données ou d'une commande de contrôleur qui sont exposées. Les différents profils ont des noms différents. Tous les profils par défaut ont un nom ayant comme préfixe IBM_.

nom: Nom du profil.
sorties: Une liste des sorties du profil.

sorties

Entoure une liste d'éléments de sortie.

listName: Un attribut facultatif qui vous permet d'entourer la réponse REST avec un tableau du nom fourni. Généralement utilisé dans les profils par défaut avec un nom resultList pour les appels REST qui renvoient un seul objet pour créer une cohérence avec les appels REST de type liste qui renvoient un tableau resultList.

sortie

Une sortie représente une zone qui est complétée par la réponse.

methodName: Nom de la méthode pour appeler le bean de données ou le contrôleur de commande pour obtenir la valeur de sortie. La méthode doit renvoyer un type simple, tel qu'un nombre, une valeur booléenne, une date ou une chaîne. Sinon, il doit s'agir d'une étape vers une sortie imbriquée Le non-respect de cette consigne entraîne une exception.
outputName: Nom de la sortie telle qu'elle apparaît dans la réponse JSON ou XML.
liste des autres nœuds de sortie: Les résultats peuvent examiner plus en profondeur les relations entre les beans de données pour obtenir les propriétés de leurs objets intégrés.

extend

Identifie un profil que le profil actuel étend. Toutes les entrées et sorties du profil sont ajoutées au profil actuel. Généralement utilisé pour la personnalisation.

profileName: Nom du profil.
profileClass: Le nom de classe entièrement qualifié qui contient le profil à étendre. La valeur par défaut porte le même nom que la classe représentée par le profil actuel. Permet à une extension d'étendre un profil par défaut.