Approche RESTful

La classe com.example.service.rest.CustomService vous aide à comprendre l'implémentation de service basé sur REST.

Cette classe est une implémentation de l'interface RestService et représente donc un service basé sur REST. Etant donné que REST est entièrement basé sur des normes HTTP, l'interface RestService dans le SDK Content Integration est étendue à partir de l'interface HttpService et est définie comme une interface de marqueur. L'interface RestService ne déclare aucune autre méthode supplémentaire. Voici les méthodes déclarées dans l'interface HttpService, que l'implémentation de service basée sur REST doit implémenter. Toutes les méthodes ne sont pas obligatoires. Toutes les méthodes acceptent l'objet ExecutionContext, qui contient toutes les informations contextuelles nécessaires à chaque méthode pour effectuer sa tâche désignée. Le paramètre de type générique de la classe ExecutionContext représente le type d’entrée requis pour le service respectif lors de son appel.

• HttpRequest buildRequest(ExecutionContext<RQ> executionContext)
  Il s’agit d’une méthode obligatoire. Elle renvoie un objet de type com.hcl.unica.cms.model.request.HttpRequest. La classe HttpRequest fournit une API de génération pour construire l’objet avec les détails applicables. Cet objet comprend tous les détails requis pour la réalisation d’une requête HTTP, comme l'URL de nœud final, la méthode HTTP, les en-têtes HTTP et le corps de la requête HTTP. L'API de générateur HttpRequest accepte les arguments suivants :

  • String endpointUrl

    URL absolue vers l’API cible.

  • HttpMethod httpMethod

    Méthode HTTP à utiliser pour effectuer l’appel d’API. Doit correspondre à l’une des valeurs de l'énumération com.hcl.unica.system.integration.service.HttpMethod.

  • En-têtes <Mappe<Chaîne, Objet>> optionnels

    Une mappe facultative d’en-têtes HTTP. Elle peut inclure des en-têtes HTTP standard et personnalisés. Les noms d'en-tête doivent être spécifiés en termes de clés de mappe et les valeurs d'en-tête doivent être fournies en tant que valeurs correspondantes dans la mappe. En l'absence de cette valeur optionnelle, aucun en-tête personnalisé ne sera envoyé avec la requête HTTP sortante.

    Remarque : Bien que la mappe de l'en-tête accepte les valeurs de type Objet (ou ses sous-types), seuls les objets Chaîne sont pris en charge à compter de l'implémentation actuelle d'Content Integration Framework. Tout autre type de valeur sera ignoré et l'avertissement suivant sera consigné :

    Header '{HEADER_NAME}' with value ‘{TO_STRING_REPRESENTATION}' will not be set since it is not a String and no Converter is available. 

  • Charge<?> facultative

    Si le service cible attend un corps de requête, cette méthode peut être remplacée pour créer le corps de requête HTTP souhaité. Il peut s’agir de n’importe quel objet valide tant que l’en-tête Content-Type approprié est fourni dans la mappe d'en-têtes. En l'absence de cette argument, un corps de requête vide sera envoyé avec la requête HTTP sortante.

    Remarque : Prise en charge de Jackson et de JAXB : la sérialisation d'objets à l'aide de Jackson et de JAXB est entièrement prise en charge par Content Integration Framework. Ainsi, un objet correctement décoré avec des annotations Jackson ou JAXB peut être défini comme la charge de la requête. Dans ce cas, l'en-tête Content-Type approprié doit être spécifié dans la mappe d'en-têtes. La sérialisation de l'objet fourni dans le corps de la requête est gérée par Content Integration Framework. Aucune sérialisation explicite n'est donc requise.
• Object transformResponse(HttpResponse<RS> response, ExecutionContext<RQ> executionContext)

  Cette méthode facultative transforme la réponse HTTP au format souhaité. Le premier argument, com.hcl.unica.system.model.response.HttpResponse , de cette méthode, représente la réponse reçue du système cible. Le paramètre de type générique de la classe HttpResponse représente le type de corps de réponse ou la charge de réponse attendue de l’API distante. La charge de réponse peut être de n'importe quel type, comme une chaîne contenant le texte entier tel que reçu du service, un tableau d'octets comprenant le corps de la réponse ou un POJO désérialisé représentant le JSON/XML de la réponse. En plus de la charge de réponse, l'objet HttpResponse peut être utilisé pour obtenir des en-têtes de réponse, un code d’état et des cookies.

  Remarque : Prise en charge de Jackson et de JAXB : La désérialisation d'objets à l'aide de Jackson et de JAXB est entièrement prise en charge par Content Integration Framework. Ainsi, un objet correctement décoré avec des annotations Jackson ou JAXB peut être accepté en tant qu'argument adressé à cette méthode. La désérialisation du corps de la réponse en type spécifié est gérée par Content Integration Framework. Par conséquent aucune désérialisation explicite n'est requise pendant la transformation de la réponse à l'intérieur de cette méthode.

  En l'absence de cette implémentation, aucune transformation implicite n'est effectuée par Content Integration Framework.

  Hormis ces méthodes, il existe une autre méthode dont le getServiceInterface a hérité de com.hcl.unica.system.integration.service.AbstractService interface, qui doit être implémentée par le service. Cependant, son implémentation est plus pertinente pour l'appel de service que pour l'implémentation de service.

  Content Integration Framework se charge de l'interaction HTTP réelle avec le système cible et consulte simplement l'objet de service pour obtenir les détails mentionnés précédemment.

  Gestion des erreurs : Content Integration Framework gère les erreurs ou les exceptions reçues lors d'un appel HTTP. Les méthodes répertoriées ci-dessus ne doivent déclencher aucune exception vérifiée. Au besoin, il est possible de déclencher des exceptions non vérifiées.