RESTful-Ansatz

Die com.example.service.rest.CustomService-Klasse hilft Ihnen, die REST-basierte Serviceimplementierung zu verstehen.

Diese Klasse ist eine Implementierung der RestService-Schnittstelle und stellt somit einen REST-basierten Service dar. Da REST vollständig auf HTTP-Standards basiert, wird die RestService-Schnittstelle im Content Integration SDK von der HttpService-Schnittstelle abgeleitet und als Markerschnittstelle definiert. Die RestService-Schnittstelle gibt keine zusätzliche Methode für sich selbst an. Im Folgenden sind die in der HttpService-Schnittstelle angegebenen Methoden aufgeführt, die eine REST-basierte Serviceimplementierung implementieren muss. Nicht alle Methoden sind obligatorisch. Alle Methoden akzeptieren ein ExecutionContext-Objekt, das alle Kontextinformationen enthält, die jede Methode benötigt, um die ihr zugewiesene Aufgabe zu erfüllen. Der generische Typenparameter für die ExecutionContext-Klasse stellt die Art der Eingabe dar, die für den entsprechenden Service für seinen Aufruf erforderlich ist.

• HttpRequest buildRequest(ExecutionContext<RQ> executionContext)
  Dies ist eine obligatorische Methode. Sie gibt ein Objekt vom Typ com.hcl.unica.cms.model.request.HttpRequest zurück. Die HttpRequest-Klasse stellt Builder API bereit, um das Objekt mit den anwendbaren Details zu erstellen. Dieses Objekt enthält alle erforderlichen Details für die Erstellung einer HTTP, z. B. Endpunkt URL, http, HTTP Header und HTTP-Anfragetext. Die HttpRequest Builder-API akzeptiert die folgenden Argumente:

  • Zeichenfolge endpointUrl

    Eine absolute URL zur Ziel-API.

  • HttpMethod httpMethod

    HTTP-Methode für die Erstellung von API-Aufrufen. Es muss sich um einen der Werte von com.hcl.unica.system.integration.service.HttpMethod enum handeln.

  • Optional<Map<Zeichenfolge, Objekt>> Header

    Eine optionale Map von HTTP-Headern. Sie kann sowohl Standard- als auch benutzerdefinierte HTTP Header enthalten. Headernamen müssen in Form von Map-Schlüsseln angegeben werden, und Headerwerte müssen als entsprechende Werte in der Map angegeben werden. In Ermangelung dieser dieses optionalen Wertes werden keine benutzerdefinierten Header zusammen mit der ausgehenden HTTP-Anfrage gesendet.

    Anmerkung: Obwohl die Header-Map Werte vom Typ Objekt (oder seiner Subtypen) akzeptiert, werden ab der aktuellen Implementierung von Content Integration Framework nur Zeichenkettenobjekte unterstützt. Jeder andere Werttyp wird ignoriert, und die folgende Warnmeldung wird protokolliert:

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

  • Optional<?> Nutzdaten

    Wenn der Zielservice irgendeinen Anfragekörper erwartet, dann kann dieses Argument mit dem gewünschten HTTP-Anfragekörper geliefert werden. Es kann sich um ein beliebtiges Objekt handelt, solange der entsprechende Content-Type-Header in der Header-Map angegeben ist. In Ermangelung dieses Arguments wird ein leerer Anfragekörper zusammen mit der ausgehenden HTTP-Anfrage gesendet.

    Anmerkung: Jackson- und JAXB-Unterstützung: Die Objektserialisierung mit Jackson und JAXB wird von Content Integration Framework vollständig unterstützt. So kann ein entsprechend dekoriertes Objekt mit Jackson- oder JAXB-Annotationen als Nutzdaten der Anfrage festgelegt werden. In diesem Fall muss der entsprechende Content-Type-Header in der Header-Map angegeben werden. Die Serialisierung des gelieferten Objekts in den Anfragekörper wird ebenfalls von Content Integration Frameworkselbst vorgenommen, daher ist keine explizite Serialisierung erforderlich.
• Objekt transformResponse(HttpResponse<RS> response, ExecutionContext<RQ> executionContext)

  Diese optionale Methode wandelt die HTTP-Antwort in ein gewünschtes Format um. Das erste Argument, com.hcl.unica.system.model.response.HttpResponse, für diese Methode stellt die Antwort dar, die vom Zielsystem empfangen wurde. Der generische Typenparameter der HttpResponse-Klasse stellt den Typ des Antwortkörpers oder der Antwortnutzdaten dar, der von der fernen API erwartet wird. Die Antwortnutzdaten können beliebigen Typs sein, z. B. eine Zeichenkette, die den gesamten vom Service empfangenen Text enthält, ein Byte-Array, das den Antwortkörper enthält, oder ein deserialisierter POJO, der die Antwort JSON/XML darstellt. Zusätzlich zu den Antwortnutzdaten kann das HttpResponse-Objekt zum Abrufen von Antwortheader, Statuscode und Cookies eingesetzt werden.

  Anmerkung: Jackson- und JAXB-Unterstützung: Die Objektdeserialisierung mit Jackson und JAXB wird von Content Integration Framework vollständig unterstützt. Daher kann ein entsprechend dekoriertes Objekt mit Jackson- oder JAXB-Annotationen als Argument für diese Methode akzeptiert werden. Die Deserialisierung des Antwortkörpers in einen bestimmten Typ wird von Content Integration Framework durchgeführt, daher ist bei der Antwortumwandlung innerhalb dieser Methode keine explizite Deserialisierung erforderlich.

  In Ermangelung dieser Implementierung wird von Content Integration Framework keine implizite Transformation durchgeführt.

  Zusätzlich zu diesen Methoden gibt es noch eine weitere Methode, die getServiceInterface von com.hcl.unica.system.integration.service.AbstractService interface übernommen hat und die vom Service implementiert werden muss. Ihre Implementierung ist jedoch eher für den Serviceaufruf als für die Implementierung des Service relevant.

  Content Integration Framework kümmert sich um die reale HTTP-Interaktion mit dem Zielsystem und konsultiert einfach das Serviceobjekt, um die oben genannten Details zu erhalten.

  Fehlerbehandlung Fehler oder Ausnahmen, die während eines HTTP-Aufrufs empfangen werden, werden von Content Integration Framework behandelt. Die oben aufgeführten Methoden dürfen keine überprüfte Ausnahme auslösen. Nicht überprüfte Ausnahmen können bei Bedarf ausgelöst werden.