Zum Hauptinhalt springen

wsclient

Die wsclient (Webservice-Client) Bibliotheken bieten eine standard Implementierungsbasis für Ihre eigene webPDF-Client Entwicklung in verschiedenen Programmiersprachen.

Eine wsclient Bibliothek vereinfacht und optimiert den Zugriff auf die webPDF REST- und SOAP-API:

  • Sie vereinfacht den Aufbau der Session (HTTP / HTTPS) mit dem webPDF Server und authentifiziert/authorisiert eine solche Session automatisch.
  • Sie serialisiert und deserialisiert XML/JSON Parameter und Payloads von und zu Objekten, sodass Sie sich auf die eigentliche Implementierung konzentrieren können, statt HTTP Messages zu parsen.
  • Sie abstrahiert die verschiedenen Funktionen und Endpunkte Ihres webPDF Servers zu einfachen Interface Typen, die eine komplett objektorientierte Nutzung der API gestatten.

Unterstützte Sprachen​

Der wsclient steht derzeit für die folgenden Programmiersprachen zur Verfügung:

Einschränkungen​

Eine wsclient Bibliothek bietet gemeinsame, gebrauchsfertige APIs für sowohl REST als auch SOAP und soll deren Verhalten und Ansprache vereinheitlichen - wo auch immer möglich.

Info

Einige Aspekte der SOAP und REST API lassen sich aber nicht vereinheitlichen. Beispielsweise wird der webPDF Server niemals einen "Dokumentenmanager" für eine SOAP "Session" anbieten, weshalb dies auch einer wsclient Bibliothek nicht möglich ist.

Vorsicht

Aus sprachspezifischen Gründen kann eine wsclient Implementierung von den hier gemachten Aussagen abweichen. Der Typescript wsclient wird beispielsweise allgemein niemals SOAP unterstützen.

Generalized Usage Pattern​

Jede wsclient Bibliothek soll Webserviceaufrufe zu einer linearen Abfolge standardisierter Schritte vereinfachen, die unabhängig von der gewählten Sprache möglichst gleichförmig definiert sein sollen.

Unser Ziel ist hierbei: Haben Sie einmal eine wsclient basierte Anwendung entwickelt, sollen Sie in der Lage sein, dieses Muster auch auf alle anderen unterstützten Sprachen zu übertragen.

Definition des SessionContext​

Der erste Schritt ist die Konfiguration des SessionContext, welcher Ihnen die Anpassung Ihrer webPDF Session erlaubt.

  • Sie wählen hierfür zunächst das Protokoll, das sie nutzen möchten (SOAP/REST).
  • Dann wählen Sie Port und URL des webPDF Servers, mit dem Sie sich verbinden wollen.
  • Sie können anschließend einen TLSContext setzen, um gesicherte HTTPS-Verbindungen aufzubauen.
  • Optional können Sie einen Client-Truststore bereitstellen, um Ihre Verbindung weiter zu sichern.
  • Schließlich können Sie einen clientseitigen Proxyserver konfigurieren, über den Ihre Verbindung umgeleitet werden soll.

Definition des AuthProvider​

Als Nächstes wählen Sie die Methode aus, die Sie für die Autorisierung Ihrer Session verwenden möchten, indem Sie einen AuthProvider auswählen:

  • Sie können eine klassische Benutzerauthentifizierung wählen
  • Eine OAuth2 JWT-Token basierte Autorisierung
  • Oder eine anonyme Session erstellen

Je nach den Anforderungen Ihres webPDF-Servers.

Aufbau der Session​

Ein "wsclient" verwendet den definierten SessionContext und AuthProvider, um die Verbindung zum webPDF-Server herzustellen.

Diese Aufgabe wird über eine SessionFactory gelöst, mit der Sie eine Session-Instanz erzeugen können. Mittels dieser können Sie alle folgenden Anweisungen an den webPDF Server ausführen.

Nutzung des REST DocumentManager​

Die Session ermöglicht für REST-Clients den Zugriff auf einen DocumentManager, mit dem Sie Dokumente in/aus dem Dokumentenspeicher hoch- und herunterladen können. Der DocumentManager ermöglicht auch die Verwaltung Ihres Dokumentenspeichers (Also das Umbenennen von Dokumenten, Löschen von Dokumenten usw.) und den Zugriff auf die "history" Ihrer Dokumente.

Erzeugung und Nutzung der Webservice Schnittstelle​

Sie können dann die wsclient Session verwenden, um einen Webservice-Schnittstellentyp für den aufzurufenden Webservice zu erstellen (z.B. bietet sie eine Schnittstelle für den Webservice "Converter").

Parameterisierung Ihres Webservice-Aufrufs​

Die erzeugte Webservice-Schnittstelle ermöglicht es, die Parameter Ihres Webservice-Aufrufs, unter Verwendung eines objektbasierten Parameterbaums, anzupassen.

In der Webservice-Schnittstelle finden Sie unter anderem auch die "process"-Methoden, die Sie aufrufen, um Ihren Webservice-Aufruf zur Ausführung zu bringen.

Abstraktion von Nutzlast, Anfragen und Antworten​

Schließlich wertet der "wsclient" automatisch die ein- und ausgehenden Nutzdaten und eventuell auftretende Server Fehlerzustände aus und überführt diese in Document- und Exception-Objekte.

Documents erlauben es Informationen über die verwalteten Dokumente abzurufen und - was noch wichtiger ist - ermöglichen das Schreiben der erzeugten Ergebnisdokumente in eine Datensenke Ihrer Wahl.

Exceptions stellen einfache Mittel bereit, um einen aufgetretenen Fehlerzustand auszuwerten, zu interpretieren und so die Fehlersuche zu vereinfachen.