Personnalisation des services REST pour prendre en charge les nouveaux formats de réponse personnalisés

Par défaut, la structure REST HCL Commerce prend en charge les formats JSON et XML. Vous étendrez les gestionnaires de ressources JAX-RS par défaut pour personnaliser les services REST afin de prendre en charge les nouveaux formats de réponse personnalisés.

Avant de commencer

Assurez-vous d'être au courant des hypothèses suivantes pour ce scénario de personnalisation :
  • Le nouveau format de réponse personnalisé est de type application/custom+xml pour la classe de gestionnaire de ressources com.ibm.commerce.rest.search.handler.ProductViewHandler par défaut.
  • Le modèle d'URL suivant est utilisé :
    • store/storeID/productview/partNumber
    Par exemple : http://host_name/wcs/resources/store/10101/productview/MW-0090
  • Le format de réponse application/custom+xml est le même que le format XML personnalisé. Toutefois, pour les besoins de ce scénario de personnalisation, il est désigné sous le nom de format de réponse personnalisé.
L'exemple d'archive de code suivant illustre les tâches décrites dans ce sujet CustomEntityProvider_Sample_Assets. L'exemple d'archive de code contient l'arborescence de répertoires suivante :
Exemple d'arborescence de répertoires d'archivage

Procédure

  1. Ouvrez HCL Commerce Developer et basculez vers la vue Explorateur d'entreprise.
  2. Ajoutez un fournisseur d'entités pour prendre en charge le format de réponse personnalisé :

    Chaque fournisseur d'entités met en forme une entité dans un format de réponse spécifique. Etant donné que la personnalisation consiste à ajouter un format de réponse, un nouveau fournisseur d'entités doit être ajouté pour mettre en forme l'entité dans le nouveau format de réponse personnalisé.

    1. Dans le projet WebSphereCommerceServerExtensionsLogic, créez une classe appelée com.mycompany.commerce.foundation.rest.providers.CustomXMLEntityProvider qui étend com.ibm.commerce.foundation.rest.providers.AbstractEntityProvider.
    2. Ajoutez l'annotation suivante dans la classe entity afin d'enregistrer le fournisseur d'entités pour le format de réponse application/custom+xml dans l'exécution JAX-RS : 
      
@Produces(value = { "application/custom+xml" })
      Pour plus d'informations, consultez l'exemple de classe fourni. L'exemple de classe contient des commentaires en ligne pour vous aider à implémenter le fournisseur d'entités.
    3. Enregistrez vos modifications et fermez le fichier.
    4. Ajoutez le nom de la classe du fournisseur d'entités dans le fichier Rest/WebContent/WEB-INF/config/providers-ext.properties pour enregistrer le nouveau fournisseur d'entités.
    5. Enregistrez vos modifications et fermez le fichier.
  3. Ajoutez un raccourci de format de réponse pour le format de réponse personnalisé ou utilisez Accepter l'en-tête de requête HTTP :

    Les raccourcis de format de réponse sont des raccourcis de type média demandés qui peuvent être facilement spécifiés par un client dans l'URL de requête en tant que paramètre de requête. Vous ajoutez un raccourci de format de réponse pour votre nouveau format de réponse personnalisé application/custom+xml, en créant le fichier s'il n'existe pas. Sinon, vous ajoutez le raccourci de format personnalisé.

    1. Créer le fichier suivant Rest/WebContent/WEB-INF/config/com.ibm.commerce.rest-ext/wc-rest-responseformat.xml
    2. Ajoutez un raccourci pour le format de réponse "application/custom+xml" au fichier tel qu'illustré dans le fragment de code suivant. 
      
<responseFormatMappings>

  <!-- Define response format and Internet media type mapping. -->
  <!-- Internet media type was originally called a MIME type. -->
  <!-- When default attribute is defined to true, the response format is the default format -->

  <formatMapping responseFormat="custom" mediaType="application/custom+xml"/>
    
</responseFormatMappings>
    3. Enregistrez vos modifications et fermez le fichier.
    Si un raccourci de format de réponse n'est pas spécifié, vous pouvez spécifier le format de réponse qui utilise Accepter l'en-tête de requête HTTP, au lieu d'utiliser le paramètre de requête responseFormat. Dans Accepter l'en-tête de requête, vous devez spécifier le format de réponse sous une forme complète, par exemple application/custom+xml. Toutefois, l'utilisation de l'option Accepter l'en-tête de requête nécessite les étapes suivantes pour étendre le gestionnaire de ressources REST existant. Pour simplifier la procédure, il est recommandé d'ajouter un raccourci au format de réponse personnalisé à wc-rest-responseFormat.xml afin qu'un client puisse utiliser le paramètre de requête responseFormat pour obtenir le format de réponse personnalisé :
    1. Dans le projet WebSphereCommerceServerExtensionsLogic, créez une nouvelle classe com.mycompany.commerce.rest.catalog.handler.ProductViewHandlerExt qui étend la classe com.ibm.commerce.rest.search.handler.ProductViewHandler.
    2. Dans la classe ProductViewHandlerExt, assurez-vous d'ajouter la même annotation de chemin d'accès qui existe dans la superclasse. Cela garantit que, lorsque l'URL par défaut est appelée, le gestionnaire de ressources personnalisé ProductViewHandlerExt est utilisé au lieu du gestionnaire de ressources par défaut. Remplacer la méthode de superclasse findProductByPartNumber par le contenu suivant :
      
@GET
@Path("{partNumber}")
@Produces( { "application/json", "application/xml", "application/custom+xml" })// additionally add custom response format
@Override
public Response findProductByPartNumber(
@PathParam("storeId") String storeId,
@PathParam("partNumber") String partNumber,
@QueryParam(value = "responseFormat") String responseFormat)
{
// write custom logic here
return super.findProductByPartNumber(storeId, partNumber, responseFormat);
}

      Pour plus d'informations, consultez l'exemple de classe fourni dans l'archive CustomEntityProvider_Sample_Assets. L'exemple de classe contient des commentaires en ligne qui vous aident à étendre le gestionnaire de ressources par défaut.

  4. Implémentez un nouveau fichier JSP pour mettre en forme les objets de données dans le format de réponse personnalisé.

    Les fichiers JSP peuvent être utilisés pour mettre en forme une entité. Pour plus d'informations, consultez com.ibm.commerce.foundation.rest.providers.AbstractEntityProvider. Dans cette personnalisation, les fichiers JSP sont utilisés en raison de la nature dynamique du format XML personnalisé.

    1. Créez un fichier JSP pour mettre en forme l'objet de données à l'emplacement suivant :
      • Rest/WebContent/jsp/commerce/catalog/custom/SerializeShowCatalogNavigationViewDataAreaTypeCustom.jsp
      L'instruction de codage de fichiers JSP est identique aux fichiers JSP de vitrine qui formatent un objet de données. Le fichier JSP peut inclure d'autres fragments JSP, tels que SerializeShowCatalogEntryViewCustom.jspf, qui formate des parties du nom dans l'objet de données. Pour plus d'informations, consultez l'exemple de fichiers JSP fourni.
    2. Enregistrez vos modifications et fermez le fichier.
    3. Ajoutez une action struts dans le fichier struts Rest/WebContent/WEB-INF/struts-extension.xml pour enregistrer le JSP.
      Par exemple :
      
<action path="/ShowCatalogNavigationViewCustom/0" 
forward="/jsp/commerce/catalog/custom/SerializeShowCatalogNavigationViewDataAreaTypeCustom.jsp"/>
      Remarque : Le format d'action struts doit correspondre au nom du groupe de mise en forme renvoyé dans le gestionnaire de ressources ProductViewHandlerExt personnalisé. Pour plus d'informations, consultez l'interface IResourceHandler.
      Lorsque vous lancez l'URL par défaut indiquant le format de réponse personnalisé application/custom+xml :
      • http://localhost/wcs/resources/store/10101/productview/MW-0090?responseFormat=custom
      Elle exécute /jsp/commerce/catalog/custom/SerializeShowCatalogNavigationViewDataAreaTypeCustom.jsp qui formate l'objet de données ShowCatalogNavigationViewDataAreaType dans le format personnalisé application/custom+xml.
    4. Enregistrez vos modifications et fermez le fichier.
  5. Implémentez un nouveau fichier JSP d'erreur pour le format de réponse personnalisé :

    En cas d'erreur, la structure REST exécute un fichier JSP d'erreur spécifique au format de réponse, en transmettant les paramètres d'erreur.

    1. Créer un fichier JSP pour mettre en forme la réponse d'erreur à l'emplacement suivant Rest/WebContent/jsp/commerce/foundation/custom/Error.jsp
    2. Enregistrez vos modifications et fermez le fichier.
    3. Ajoutez une action struts dans le fichier struts Rest/WebContent/WEB-INF/struts-extension.xml pour enregistrer le JSP. 
      
<action path="/ErrorCustom/0" forward="/jsp/commerce/foundation/custom/Error.jsp"/>
      Remarque : Le format d'action struts doit correspondre au nom du groupe de mise en forme renvoyé dans le gestionnaire de ressources ProductViewHandlerExt personnalisé.
      Lorsque vous lancez l'URL par défaut indiquant le format de réponse personnalisé application/custom+xml :
      • http://localhost/wcs/resources/store/10101/productview/MW-0090?responseFormat=custom
      Elle exécute :
      • /Rest/WebContent/jsp/commerce/foundation/custom/Error.jsp en cas d'erreurs ou d'exceptions.
      Qui formate les paramètres Error transmis au fichier JSP d'erreur au format personnalisé application/custom+xml.
  6. Vérifiez votre personnalisation en redémarrant le serveur HCL Commerce et en lançant les URL créées dans cette tâche.