Vier nicht programmierbare Web-Services stehen bereits zur Verfügung, die das Protokoll „SOAP“ für entfernte Aufrufe verwenden. Das sind zum einen der Datenexport, der Datenimport und die entfernte Suche als spezialisierte Web-Services. Darüber hinaus kann jede Hintergrund-Anwendung über „CallApplication“ als Web-Service zustandslos aufgerufen werden. Diese Web-Services-Schnittstelle verwendet die frei erhältliche Web-Service-Bibliothek „Apache Axis“.
Zusätzlich steht Ihnen eine weitere Schnittstelle für programmierbare Web-Services zur Verfügung. Damit können Sie eigene Web-Services bei Bedarf als SOAP-Service oder als REST-Service implementieren. Diese Web-Service-Schnittstelle verwendet die frei erhältliche Web-Service-Bibliothek „Apache CXF“. Mehr Informationen über CXF erhalten Sie auf folgender Website:
http://cxf.apache.org/[1]
Mit der Auslieferung erhalten Sie sowohl Beispiel-SOAP- und -REST-Services als auch ein Beispiel-SOAP-Client, die in Java implementiert sind.
In dieser Dokumentation werden die Schritte beschrieben, die für die Entwicklung eigener programmierter Web-Services erforderlich sind, sowie Beispiel-Web-Services und -Clients. Auch das Tool „Soap Ui“ zum Testen von SOAP- und REST-Services wird kurz erklärt.
1 Zielgruppe
2 Begriffsbestimmung
Hypermedia
Die textbasierte Verknüpfung von Hypertext und Multimediadaten. Hypermedia beruht auf dem Konzept von Verknüpfungen (Hyperlinks). Diese sind vor allem aus der HTML bekannt und ermöglichen dem Benutzer, im Web zu navigieren oder eingebundene Daten wie PDF-Dokumente zu öffnen.
JAXB
Abkürzung für „Java Architecture for XML Binding“. Eine Java-Schnittstelle, die beschreibt, wie die Daten aus einer XML-Schema-Instanz automatisch an Java-Klassen gebunden werden, und wie diese Java-Klassen aus einem XML-Schema generiert werden.
JAX-RS
Abkürzung für „Java API for RESTful Web Services“: Die Spezifikation der Java-Schnittstelle, die die Verwendung des REST-Architekturstils im Rahmen von Webservices ermöglicht und vereinheitlicht.
JAX-WS
Abkürzung für „Java API for XML Web Services“: Die Spezifikation der Java-Schnittstelle für die Erstellung von Web-Services.
Repräsentation
Eine Repräsentation ist jede nützliche Information über den Zustand einer Ressource. Die Repräsentation stellt eine Ressource in einem definierten Format dar. Die Repräsentation einer Ressource kann auf weitere Ressourcen verweisen. Folgende Repräsentationen können zum Einsatz kommen: XML, HTML, CSV, Binäre Formate, den Text ohne definierte Sturktur (text/plain).
Request
Eingaben oder Interaktionen des Benutzers werden durch den Computer des Benutzers, den so genannten Client, über das Netzwerk an den Server geschickt. Die vom Server empfangenen Daten werden als Request bezeichnet. Nach der Datenverarbeitung schickt der Server dem Client als Antwort eine Bestätigung oder neue Daten (Response). Die Kommunikation zwischen Client und Server besteht somit immer aus Request und Response.
Response
Eingaben oder Interaktionen des Benutzers werden durch den Computer des Benutzers, dem so genannten Client, über das Netzwerk an den Server geschickt. Der Server verarbeitet einen Request und schickt dem Client als Antwort eine Bestätigung oder neue Daten. Diese Antwort wird als Reponse bezeichnet. Die Kommunikation zwischen Client und Server besteht somit immer aus Request und Response.
REST
Abkürzung für „Representational State Transfer“. Ein Architekturstil für den Austausch von Nachrichten in verteilten Hypermedia-Informationssystemen auf HTTP-Basis. Es besitzt keinen Protokollcharakter und ist momentan nicht standardisiert. Es müssen keine Protokoll-Konventionen im Unterschied zum SOAP bekannt sein, damit Client und Server sich verständigen können. Die zentrale Rolle spielen die folgenden Grundprinzipien:
- Adressierbarkeit der Ressourcen.
- Verwendung von Hypermedia auf Basis von HTML oder XML.
- Nutzung der Standard-HTTP-Operationen.
- Zustandslosigkeit der Kommunikation, die sich nicht etwa auf den serverseitigen Zustand bezieht. REST schreibt vor, dass dieser Zustand entweder vom Client gehalten oder vom Server in einen Ressourcenstatus umgewandelt wird. Nicht gewollt ist ein serverseitig abgelegter, transienter, clientspezifischer Status über die Dauer eines Requests hinweg.
REST-konforme HTTP-Nutzung
Englisch „RESTful http“. Die Nutzung der HTTP-Operationen wie folgt:
- GET: Anfordern von Daten vom Server.
- POST: neue Daten auf dem Server ablegen.
- PUT: vorhandene Daten aktualisieren.
- DELETE: Daten löschen.
- HEAD: Metadaten zu einer Ressource anfordern.
- OPTIONS: prüfen, welche Operationen auf einer Ressource zur Verfügung stehen.
REST-Service
Ein Web-Service, bei dem der REST-Architekturstil eingesetzt wird.
(Web)-Ressource
Der Begriff „Web-Ressource“ (auch „Ressource“ genannt) wird verwendet für eine Quelle an einer beliebigen Stelle im Web, die durch einen URI eindeutig identifizierbar ist (siehe auch Norm RFC 3986). Als Beispiele der Web-Ressourcen sind Dateien, Grafiken, Internet-Dienste und Servlets zu nennen sowie Sammlungen von anderen Ressourcen, die über URIs adressiert und angesprochen werden können. Eine Ressource kann mehrere Repräsentationen haben.
SOAP
Abkürzung für „Simple Object Access Protocol“. Ein XML-basiertes Protokoll für den Austausch von Nachrichten in verteilten Systemen. SOAP wird zur Kommunikation zwischen Web-Services-Clients und –Servern verwendet.
SOAP-Service
Ein Web-Service, der das Protokoll „SOAP“ für entfernte Aufrufe verwendet.
WADL
Abkürzung für „Web Application Description Language“. Die Beschreibungssprache für REST-konforme Web-Services.
WSDL
Abkürzung für „Web-Services Description Language“. Die Beschreibungssprache für die Schnittstelle zu einem Web-Service.
3 Beschreibung
Mit der Schnittstelle für programmierbare Web-Services können Sie einen Web-Service als SOAP-Service oder als REST-Service entwickeln. Die Entscheidung, ob ein SOAP- oder REST-Service zum Einsatz kommt, hängt von den konkreten Anforderungen ab.
3.1 Voraussetzungen
Der SAS, auf dem ein programmierbarer Web-Service ausgeführt wird, muss mit dem Web-Server gestartet werden. Dadurch wird auch der Web-Service-Server gestartet. Dies ist der Normallfall im System. Der Web-Service-Server kann nicht getrennt vom Web-Server gestartet werden.
3.2 Einen programmierbaren Web-Service entwickeln
Die Entwicklung eines programmierbaren Web-Services besteht aus mehreren Schritten: vom Erfassen des Entwicklungsobjektes „Anwendung“ bis zum Implementieren der inneren Java-Klasse, in der die Funktionalitäten des Web-Services realisiert sind.
3.2.1 Entwurf der Web-Service-Schnittstelle
Die Schnittstelle eines zu programmierenden Web-Services muss gemäß den technischen und betriebswirtschaftlichen Anforderungen entworfen werden. Dabei ist zu beachten, dass die Infrastruktur, die für die Realisierung eines Web-Services im System zur Verfügung steht, nicht geeignet ist, große Datenmengen zu transportieren. Die empfangenen oder gesendeten Daten müssen unter Umständen vollständig im Hauptspeicher des Application-Servers aufbereitet werden. Dies kann den Application-Server stark belasten und erhebliche Leistungseinbussen verursachen.
Hinweis:
Da die Schnittstelle für programmierbare Web-Services mithilfe von „Apache CXF“ realisiert ist, können Sie für Debug-Zwecke die Informationen unter folgender Website benutzen:
http://cxf.apache.org/docs/debugging-and-logging.html[2]
Falls während der Anfrage des Clients innerhalb der Web-Service-Implementierung Meldungen in der Message-Queue entstehen, werden diese nicht automatisch an den Client zurückgegeben. Die Web-Service-Implementierung hat die Aufgabe, diese Meldungen bei Bedarf an den Client zurückzugeben.
3.2.2 Entwicklungsobjekte vom Typ „Java-Klasse“ und „Anwendung“ erfassen
Erfassen Sie ein Entwicklungsobjekt vom Typ „Java-Klasse“. Wir empfehlen, die Java-Klasse und die Anwendung identisch zu nennen und den Suffix „Service“ zu verwenden.
Der Namensraum sollte wie der entsprechende .log-Namensraum beginnen, und statt auf „.log“ auf „.soap“ oder „.rest“ enden.
Die Java-Klasse muss von der abstrakten Klasse CisWebServiceApplication abgeleitet sein. Diese Oberklasse definiert die Methode init(). Die weitere Implementierung ist abhängig davon, ob ein SOAP- oder ein REST-Service entwickelt wird.
Danach muss ein Entwicklungsobjekt „Anwendung“ erfasst werden. Der voll qualifizierte Name der Anwendung dient als die Identifikation des Web-Services.
Der Typ der Anwendung muss „RPC-Dienst“ sein. Als Besondere Verwendung muss entweder „SOAP-Service“ oder „REST-Service“ ausgewählt werden.
Hinweis:
Falls der Anwendung mit der besonderen Verwendung „REST-Service“ die Java-Klasse zugeordnet ist, in der ein SOAP-Service definiert und implementiert wurde, oder umgekehrt, dann wird das erst beim Aufruf des Services festgestellt und eine Fehlermeldung ausgegeben.
3.2.3 Anfrage-URI
3.2.3.1 Anfrage-URI eines Web-Services
Um die Web-Services aufzurufen muss ein eigener, für den jeweiligen Web-Service spezifischer URI aufgerufen werden. Die Struktur dieses URI sieht wie folgt aus:
- Für einen SOAP-Service
https://<basis-url>/services/soap/<vollqualifizierter Name der Anwendung>?oltp=<Datenbankname>
Der Bestandteil „services/soap“ des Anfrage-URI signalisiert dem Web-Service-Server, dass ein SOAP-Service angesprochen wird.
- Für einen REST-Service
https://<basis-url>/services/rest/<vollqualifizierter Name der Anwendung>/<Ressource>/<mögliche Parameter>/?oltp=<Datenbankname>
Der Bestandteil „services/rest“ des Anfrage-URI signalisiert dem Web-Service-Server, dass ein REST-Service angesprochen wird. Durch den Bestandteil <Ressource> wird die gewünschte Funktionalität angesprochen, die bei Bedarf mit den erforderlichen Parametern aufgerufen wird.
3.2.3.2 Generische Query-Parameter des Anfrage-URI
Folgende generische Query-Parameter können verwendet werden:
| Query-Parameter | Beschreibung |
| displayLanguage | Gibt die gewünschte Anzeigesprache an. |
| contentLanguage | Gibt die gewünschte Inhaltssprache an. |
| oltp | Name der OLTP-Datenbank. |
| context | Code der gewünschten Organisation. |
| wsdl | Signal an den Web-Service-Server, die WSDL-Datei für einen SOAP-Service bereitzustellen. „wsdl“ muss als erster Query-Parameter angegeben werden. |
| _wadl | Signal an den Web-Service-Server, die WADL-Datei für einen REST-Service bereitzustellen. |
Wenn Sie mehrere Query-Parameter verwenden, dann werden diese durch ein kaufmännisches „und“ (&) oder ein Semikolon (;) getrennt.
3.2.4 Einen SOAP-Service entwickeln
In der erfassten Java-Klasse muss eine innere Klasse vorhanden sein, die durch die folgende JAX-WS-Annotation gekennzeichnet ist:
@WebService
Diese Annotation benötigt keine Werte. Die innere Klasse dient als Definition und Implementierung eines SOAP-Services. Der Name der inneren Klasse definiert den Namen des Services in der WSDL-Datei. Wir empfehlen, die innere Klasse nicht auf „Service“ enden zu lassen.
Alle öffentlichen Methoden, die Sie in dieser inneren Klasse implementieren, stehen dem SOAP-Client als funktionale Bestandteile des SOAP-Services zur Verfügung.
Weitere Informationen zu JAX-WS, insbesondere zur Verwendung der Annotation, finden Sie in http://cxf.apache.org/docs/developing-a-service.html[3]
3.2.5 Beispiel eines SOAP-Services
Sie erhalten mit der Auslieferung die folgende Anwendung und die gleichnamige Java-Klasse:
com.cisag.app.system.webservices.service.soap.SOAPExampleService
Die init()-Methode enthält die Initialisierung des internen Object- und Transaction-Managers. Die innere Klasse SOAPExample enthält die Definition und die Implementierung des SOAP-Services. Die Klasse wird durch die Annotation @WebService gekennzeichnet.
Die folgende Methode bietet die Möglichkeit, das Begrüßungswort „Hello“ mit dem Parameter name zu konkatenieren und zurückzugeben:
String sayHello(String name)
Durch die folgende Methode können Sie abfragen, ob ein Vertriebsauftrag mit definierter Art und Nummer existiert.
boolean existSalesOrder(String type, String number)
Durch die folgende Methode wird das Bean SalesOrderResult anhand der definierten Art und Nummer zurückgegeben, das die Information über den Status des Vertriebsauftrages und den Namen des zuständigen Mitarbeiters enthält. Beachten Sie bitte, dass das Bean als statische Java-Klasse programmiert werden muss.
public SalesOrderResult getSalesOrderByBusinessKey(String type, String number)
Hinweis:
Mithilfe der Annotation @WebParam(<“Name eines Parameters>) können Sie die Eingabeparameter der Methoden genauer beschreiben. Dann enthalten die WSDL-Datei und die generierten Klassen nicht Namen wie „argX“, sondern die angegebenen Parameternamen.
3.2.6 SOAP-Version
Standardmäßig verwenden programmierbare SOAP-Services die SOAP-Version 1.2 in der WSDL-Datei. SOAP-Rückgaben werden in der SOAP-Version geschickt, die der Client für die SOAP-Anfrage verwendet hat (SOAP 1.1 oder SOAP 1.2).
Sie können in einem SOAP-Service angeben, dass der SOAP-Service nur SOAP 1.1 unterstützen soll. In dem Fall wird SOAP 1.1 in der WSDL-Datei verwendet. Geben Sie dazu zusätzlich die folgende Annotation an der inneren Klasse an:
@javax.xml.ws.BindingType(value = javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_BINDING)
Beachten Sie, dass die im Dokument Web-Services-Schnittstelle beschriebenen nicht-programmierbaren Web-Services SOAP 1.1 verwenden.
3.2.7 Zustandsbehaftete SOAP-Services
SOAP-Services können auch zustandsbehaftet aufgerufen werden. Je Service, der in einer Session aufgerufen wird, wird eine Instanz der Anwendung mit zugehörigem Service-Objekt erzeugt. Weitere Aufrufe an denselben Service innerhalb derselben Session werden auf dem bereits erzeugten Service-Objekt aufgerufen.
Ein Service kann daher einen Zustand zwischen verschiedenen Aufrufen speichern, in dem er Attribute in der Anwendungsinstanz oder des Service-Objekts verwendet.
Beachten Sie, dass Sessions bei Nichtbenutzung nach Ablauf einer Wartezeit automatisch beendet werden. Um eine Session offen zu halten, muss daher innerhalb der Wartezeit mindestens ein Aufruf eines beliebigen Web-Services für dieselbe Session erfolgen. Das System bietet hierfür auch die parameterlose Methode „ping“ am SOAP-Service an:
com.cisag.sys.tools.webservices.log.Session
3.2.8 Einen REST-Service entwickeln
In der erfassten Java-Klasse muss eine innere Klasse vorhanden sein, die durch die folgende JAX-RS-Annotation gekennzeichnet ist:
@Path(„Vollqualifizierter Name der REST-Anwendung“)
Diese Annotation benötigt als Wert den voll qualifizierten Namen der erfassten Anwendung, für die der Typ „RPC-Dienst“ und die besondere Verwendung „REST-Service“ festgelegt ist. Dieser Name repräsentiert die Root-Ressource, ein erforderlicher Bestandteil des Anfrage-URI des REST-Services. Des Weiteren muss die innere Klasse einen öffentlichen Konstruktor haben.
Hinweis:
Falls die Annotation nicht den Namen der Anwendung enthält, kann der Service nicht aufgerufen werden.
Die einem REST-Client zur Verfügung stehenden Funktionalitäten des REST-Services werden durch die öffentlichen Methoden (Resource-Methoden) repräsentiert, die mit den JAX-RS-Annotationen gegenzeichnet sind:
- Request-Method Designator (@GET oder @PUT oder @POST oder @DELETE)
- @Path („Name der Ressource und ggf. weitere Parameter“)
Die Werte, die der @Path-Annotation zugeordnet sind, bilden weitere Bestandteile des Anfrage-URI, die relativ zur Root-Ressource sind. Die Werte können Platzhalter in geschweiften Klammern enthalten.
Hinweis:
Die Namen der Platzhalter, die Parameter des Anfrage-URI repräsentieren, müssen laut Konvention mit einem Großbuchstaben anfangen.
Während der Programmierung der Resource-Methoden sollten Sie das Folgende in Bezug auf HTTP-Operationen beachten:
- GET
GET fragt die Repräsentation einer Ressource ab. Anfragen sollten frei von Seiteneffekten sein.
- POST
Mit POST kann einer Ressource etwas hinzugefügt werden. POST ist nicht frei von Seiteneffekten.
- PUT
Neue Ressourcen können mit PUT erzeugt oder der Inhalt bestehender Ressourcen kann mit PUT ersetzt werden.
- DELETE
Ressourcen können mit DELETE gelöscht werden.
Beachten Sie bitte dabei auch die folgende Beschreibung der JAX-RS:
Java™ API for RESTful Web Services http://jsr311.java.net/nonav/releases/1.1/spec/spec.html[4]
Hinweise:
Weitere nützliche Informationen über die Annotationen, die zum Einsatz bei der Realisation eines REST-Services kommen können, finden Sie unter der Seite http://cxf.apache.org/docs/jax-rs-basics.html[5]. Einige der Annatotionen werden in im Beispiel der vorliegenden Dokumentation erklärt.
In den Kommentaren von Resource-Methoden finden Sie Informationen darüber, wie eine Funktionalität des REST-Services aufgerufen werden kann. Alle Funktionalitäten die durch die HTTP-Operation „GET“ gekennzeichnet sind, können direkt im Internet-Explorer aufgerufen werden. Für weitere HTTP-Operationen kann das Tool „Soap Ui“ verwendet werden.
3.2.9 Beispiel eines REST-Services
Sie erhalten mit der Auslieferung folgende Anwendung und die gleichnamige Java-Klasse:
com.cisag.app.system.webservices.service.rest.RESTExampleService
Die init()-Methode enthält die Initialisierung des Object- und Transaction-Managers. Die innere Klasse RESTExample enthält die Definition und die Implementierung des REST-Services. Die Klasse wird durch folgende Annotation gekennzeichnet:
@Path(“com.cisag.app.system.webservices.service.rest.RESTExampleService”)
Die folgende Resource-Methode bietet die Möglichkeit, das Begrüßungswort „Hello“ mit gegebenem Parameter name zu konkatenieren und die Repräsentation standardmäßig als plain/text zurückzugeben:
@GET
@Path(“sayhello/{Name}”)
public String sayHello(@PathParam(“Name”) String name)
Die Annotation @GET gibt an, dass die HTTP-GET-Methode für die Anfrage verwendet werden muss. Die Annotation @Path enthält den Wert “sayhello/{Name}”, dabei ist „sayhallo“ die Identifikation der Funktionalität, {Name} ist der erforderliche Platzhalter, der durch die weitere Annotation @PathParam(„Name“) mit dem Resource-Methoden-Parameter „Name“ verknüpft ist.
Durch die folgende Resource-Methode können Sie anfragen, ob ein Vertriebsauftrag mit definierter Art und Nummer existiert.
@GET
@Path(“salesOrderAvailable/{Type}/{Number}”)
public String existSalesOrder(@PathParam(“Type”) String type, @PathParam(“Number”) String number)
Die folgende Resource-Methode liefert das Bean SalesOrderBean anhand der definierten Art und Nummer zurück, das die Information über die Art, die Nummer, den Status des Vertriebsauftrages und den Namen des zuständigen Mitarbeiters enthält:
@GET
@Path(“getSalesOrder/{Type}/{Number}”)
@Produces(MediaType.APPLICATION_XML)
public SalesOrderBean getSalesOrderByBusinessKey(@PathParam(“Type”) String type, @PathParam(“Number”) String number)
Die Annotation @Produces beschreibt die Repräsentation als XML-Form. Beachten Sie, dass das Bean für die JAXB-Unterstützung mit der Annotation @XmlRootElement(name = “SalesOrderBean”) gekennzeichnet wird.
Die folgende Resource-Methode erzeugt im Arbeitsspeicher eine neue Instanz des Beans SalesOrderBean mit der angegebenen Art, der Nummer und den Status und gibt die Repräsentation als HTML zurück.
@POST
@Path(“newSalesOrderBean/{Type}/{Number}/{orderStatus}”)
@Produces(MediaType.TEXT_HTML)
public SalesOrderBean newSalesOrder(@PathParam(“Type”) String type, @PathParam(“Number”) String number, @PathParam(“OrderStatus”) short orderStatus)
Die Instanz wird nicht gemerkt. Im Unterschied zu anderen Resource-Methoden ist diese Methode durch die Annotation @POST gekennzeichnet.
Hinweis:
Neben der Annotation @PathParam steht auch die Annotation @QueryParam zur Verfügung, mit der auf Query-Parameter des Anfrage-URI zugegriffen werden kann. Auf diese Weise kann der Service eigene Query-Parameter definieren, die ein Client als Query-Zeichenkette übergeben kann. Verwenden Sie dafür als erstes Zeichen des Query-Parameternamens einen Großbuchstaben. Query-Parameternamen, die mit Kleinbuchstaben beginnen, sind für die System-Engine reserviert.
3.3 Abrufen der WSDL-/WADL-Datei
Die WSDL- oder die WADL-Datei wird für die Entwicklung eines Web-Service-Clients benötigt. Die Struktur des jeweiligen Anfrage-URIs sieht wie folgt aus:
- Für SOAP-Services:
https://<basis-uri>/services/soap/<vollqualifizierter Name der Anwendung>?wsdl
Der Bestandteil des Anfrage-URIs „wsdl“ signalisiert dem Semiramis-Web-Service-Server, dass eine WSDL-Datei vorbereitet und zur Verfügung gestellt werden muss. Nach der Angabe des Anfrage-URI in der Adressleiste des Internet Explorers erscheint dazu das Authentifizierungsdialogfenster. Nach der erfolgreichen Authentifizierung wird die WSDL-Datei angezeigt. Sie können diese mithilfe der „Speichern unter…“-Aktion des Internet Explorers speichern.
- Für REST-Services:
https://<basis-url>/services/soap/<vollqualifizierter Name der Anwendung>?_wadl
Der Bestandteil des Anfrage-URIs „_wadl“ signalisiert dem Semiramis-Web-Service-Server, dass eine WADL-Datei vorbereitet und zur Verfügung gestellt werden muss. Nach der Angabe des Anfrage-URIs in der Adressleiste des Internet Explorers erscheint dazu das Authentifizierungsdialogfenster. Nach der erfolgreichen Authentifizierung erscheint das Dateidownload-Dialogfenster. Sie können die WADL-Datei speichern. Beachten Sie, dass die WADL-Datei unter Umständen unvollständig ist, beispielsweise könnten Parameter fehlen. Das hängt von der Programmierung des jeweiligen REST-Services ab.
3.4 Authentifizierung und Berechtigungen
Um einen Web-Service aufrufen zu können, muss ein Client sich am Web-Server authentifizieren. Die Authentifizierung erfolgt durch Digest-Kennwort-Authentifizierung oder durch ein Client-Zertifikat. In der Beschreibung des Beispiel-Clients in Kapitel 4.6.1 Beispiel SOAP-Service-Client erfolgt die Authentifizierung per Client-Zertifikat.
Programmierbare Web-Services sind Anwendungen. Daher muss ein Benutzer die Berechtigung für das Öffnen der Anwendung besitzen, um den Web-Service aufrufen zu können.
3.5 Unterstützung zur Fehlersuche
Der Semiramis-Web-Service-Server bietet die Möglichkeit, Informationen über Anfragen von Clients auszugeben. Dies gilt sowohl für die nicht programmierbaren wie für die programmierbaren Web-Services.
Aktivieren Sie hierzu das Klassendebugging der Javaklasse com.cisag.sys.kernel.webservices.CisWebServicesResource auf dem SAS, der von Clients aufgerufen wird. Auf der Toolshell erscheinen abhängig von der Debuggingstufe folgende Ausgaben:
| Debuggingstufe | Ausgaben |
| INFO | Für jeden Aufruf eines Web-Services erfolgt eine Ausgabe beim Beginn und am Ende der Verarbeitung im SAS.
Ausgegeben werden: Session-Nummer, HTTP Method, Anfrage-URI, Verarbeitungszeit. |
| FINEST | Zusätzlich zu den Ausgaben in der Debuggingstufe „INFO“ wird mit der Stufe „FINEST“ der Inhalt (HTTP Body) der Anfrage des Clients und der Antwort des Web-Services ausgegeben. |
Die Ausgaben können über den Toolshell-Befehl Klasse debuggen (dbgcls) für einen laufenden SAS ein- und ausgeschaltet werden.
3.6 Beispiele für Web-Service-Clients
3.6.1 Beispiel SOAP-Service-Client
Sie erhalten mit der Auslieferung folgendes Beispiel für einen SOAP-Service-Client. In diesem Client wird geprüft, ob ein Vertriebsauftrag existiert oder nicht.
Die folgende Klasse enthält die eigentliche Client-Implementierung:
com.cisag.app.system.webservices.service.soap.client.SOAPExampleClient
Zusätzlich werden die folgenden Klassen für die Client-Programmierung benötigt:
com.cisag.app.system.webservices.service.soap.client.ExistSalesOrder
com.cisag.app.system.webservices.service.soap.client.ExistSalesOrderResponse
com.cisag.app.system.webservices.service.soap.client.GetSalesOrderByBusinessKey
com.cisag.app.system.webservices.service.soap.client.GetSalesOrderByBusinessKeyResponse
com.cisag.app.system.webservices.service.soap.client.ObjectFactory
com.cisag.app.system.webservices.service.soap.client.SalesOrderResult
com.cisag.app.system.webservices.service.soap.client.SayHello
com.cisag.app.system.webservices.service.soap.client.SayHelloResponse
com.cisag.app.system.webservices.service.soap.client.SOAPExample
com.cisag.app.system.webservices.service.soap.client.SOAPExampleService
Diese Klassen werden durch das Tool wsimport aus der WSDL-Datei generiert. Das Tool wsimport ist seit Java 6 Bestandteil des JDK.
Die WSDL-Datei wird durch folgende Angabe erzeugt:
https://<basis-uri>/services/soap/com.cisag.app.system.webservices.service.soap.SOAPExampleService?wsdl
Statt des Platzhalters <basis-uri> wird die reale Adresse angegeben.
Danach wird das Tool wsimport wie folgt unterhalb von <JDK-Verzeichnis>/bin aufgerufen:
wsimport -p com.cisag.app.system.webservices.service.soap.client -d <Pfad für die .class Dateien> -s <Pfad für die Quell-Dateien> <Pfad mit dem Namen der WSDL-Datei> -Xnocompile -extension
Statt den „Pfad“-Platzhaltern werden die realen Pfade angegeben.
Die folgende Klasse enthält nach der Generierung den Pfad zur WSDL-Datei:
com.cisag.app.system.webservices.service.soap.client.SOAPExampleService
Dieser Pfad wird durch den folgenden URI ersetzt:
<basis-uri>/services/soap/com.cisag.app.system.webservices.service.soap.SOAPExampleService?wsdl&oltp=<oltpname>
Hinweis:
Sie müssen die Platzhalter <basis-uri> und <oltpname> durch die konkreten Werte des Basis-URIs und des Namens der OLTP-Datenbank ersetzen.
Die folgende Klasse enthält die main-Methode, in der die Prüfungen der Parameter stattfinden:
com.cisag.app.system.webservices.service.soap.client.SOAPExampleClient
In dieser Methode wird Folgendes ausgeführt:
- eine Instanz von SOAPExampleService wird erstellt
- ein Serviceobjekt wird erstellt
- eine Authentifizierung wird durchgeführt
- die Methode des SOAP-Services existSalesOrder(salesOrderType, salesNumber) wird aufgerufen
Der Aufruf des Clients muss außerhalb des Systems wie folgt erfolgen:
com.cisag.app.system.webservices.service.soap.client.SOAPExampleClient SOAPServiceAddress userCertificateFileName userCertificateFilePassword serverCertificateFileName salesOrderType salesNumber
Geben Sie statt SOAPServiceAddress die vollständige Adresse des SOAP-Services inklusive dem Namen der OLTP-Datenbank an, z. B. https://qas.kauftreu.com/services/soap/com.kauftreu.app.system.webservices.service.soap.SOAPExampleService?oltp=QAS51000
Geben Sie statt salesOrderType und salesNumber die Art des Vertriebsauftrages und dessen Nummer an.
Geben Sie statt userCertificateFileName und serverCertificateFileName den vollständigen Pfad und den Dateinamen der JKS-Datei an.
Hinweis:
Der Beispiel-SOAP-Client darf nicht innerhalb des Systems gestartet werden. Die betreffenden Klassen müssen kopiert und kompiliert werden (z. B. in einem eigenen Eclipse-Projekt). Des Weiteren darf die CXF-Bibliothek nicht im Klassenpfad vorhanden sein. Wenn Sie versuchen, den Client im System zu starten, dann wird die folgende Ausnahme ausgegeben:
Exception in thread “main” com.sun.xml.internal.ws.client.ClientTransportException: HTTP transport error: javax.net.ssl.SSLException: Unrecognized SSL message, plaintext connection? at com.sun.xml.internal.ws.transport.http.client.HttpClientTransport.getOutput(HttpClientTransport.java:121) at com.sun.xml.internal.ws.transport.http.client.HttpTransportPipe.process(HttpTransportPipe.java:142)at com.sun.xml.internal.ws.transport.http.client.HttpTransportPipe.processRequest(HttpTransportPipe.java:83)at com.sun.xml.internal.ws.transport.DeferredTransportPipe.processRequest(DeferredTransportPipe.java:105)
Der Beispiel-SOAP-Client ist so programmiert, dass alle Anfragen denselben Sessions zugeordnet sind.
3.6.2 Beispiel-REST-Service Client
Sie können das Tool „Soap Ui“ für die einzelnen Anfragen verwenden, das im Kapitel Tool „Soap Ui“ zum Testen von Web-Services beschrieben ist.
4 Tool „Soap Ui“ zum Testen von Web-Services
Das Tool „Soap Ui“ bietet Ihnen die Möglichkeit, sowohl SOAP- als auch REST-Services zu testen. Die weitere Beschreibung bezieht sich auf die Version 3.6.1. Die ausführliche Dokumentation sowie die Installationsanleitungen zum Tool finden Sie unter folgender Adresse:
http://soapui.org/REST-Testing/getting-started.html[6]
Soap-Ui-Einstellungen
Bevor Sie einen Web-Service testen benötigen Sie eine WSDL- oder WADL-Datei. Sie benötigen auch die JKS-Datei eines Benutzerzertifikates für die Authentifizierung mit dem Kennwort für diese Datei. Das Benutzerzertifikat muss dem jeweiligen Benutzer zugeordnet werden, der den Web-Service testet. Den Pfad zur Datei und das Kennwort geben Sie unter der Rubrik „SSL Settings“ des Dialoges „SoapUi Preferences“ an.
Empfehlung:
Wir empfehlen, dass Sie unter der Rubrik „HTTP Settings“ den Wert 120000 für „Socket Timeout“ eingeben.
Das Dialog-Fenster „SoapUi Preferences“ können Sie aufrufen, indem Sie entweder die Tastenkombination „CTRL+ALT+P“ drücken oder unterhalb von dem Menü „File“ den Menüeintrag „SoapUi Preferences“ auswählen.
Neues Soap-Ui-Projekt
Nachdem Sie die Soap-Ui-Einstellungen vorgenommen haben, legen Sie ein neues Soap-Ui-Projekt an, indem Sie die Tastenkombination „CTRL+N“ drücken oder unterhalb von dem Menü „File“ den Menüeintrag „New SoapUi Project“ auswählen. Ein Dialog-Fenster erscheint, in das Sie den Namen des Projektes und den Pfad zur WSDL- oder WADL-Datei angeben. Nachdem Sie „OK“ gedrückt haben, entsteht ein Projekt, das hierarchisch aufgebaut ist. Einzelne Knoten repräsentieren entweder den ganzen Web-Service oder einzelne Funktionalitäten oder deren HTTP-Operationen (nur für REST-Service).
Bitte beachten Sie, dass die Namen der generischen Query-Parameter (z. B. „oltp“ bzw. „context“) nicht Bestandteil der WSDL- oder WADL-Datei sind. Sie müssen diese Parameter manuell eingeben:
- Für SOAP-Service klappen Sie die Knoten mit zu testenden Funktionalitäten auf, bis Sie zum Knoten „Request<Nummer>“ wechseln können. Dann markieren Sie die Adressleiste des Dialog-Fensters, wählen den Punkt „[edit current…] und fügen den gewünschten Parameter dem URI hinzu.
- Für REST-Service klappen Sie den Knoten auf, der den Namen des Web-Services trägt. Das sollte der Name der Anwendung sein, die Sie in Semiramis erfasst haben. Doppelklicken Sie darauf. Ein Dialog-Fenster erscheint, in dem Sie weitere Parameter hinzufügen können.
Um auf einen Web-Service zugreifen zu können, klappen Sie die Knoten mit zu testenden Funktionalitäten auf, bis Sie zum Knoten „Request<Nummer>“ wechseln können. Klicken Sie auf den Knoten, dann erscheint ein Dialog-Fenster, in das Sie sowohl die Anfragen (Requests) an Web-Services stellen als auch die Antworten (Response) des Web-Services ansehen können.
Hinweis:
Der SAS, dessen URI bei der Abfrage der WSDL- oder WADL-Datei verwendet wurde, muss gestartet sein. Wenn Sie sicher sind, dass auf einem anderen Applicaton-Server derselbe Web-Service ausgeführt wird, dann können Sie im „Request“-Dialog-Fenster den URI editieren, indem Sie die Adressleiste des Dialog-Fensters markieren und den Punkt „[edit current…] auswählen.
Unter Umständen kann vorkommen, dass die WADL-Datei nicht vollständig ist, z. B. können die notwendigen Parameter für die Abfrage fehlen. In diesem Fall fügen Sie die notwendigen Parameter manuell hinzu.
Mit dem Tool „Soap Ui“ können diverse Logdateien angezeigt werden. Im unteren Bereich des Hauptfensters werden z. B. die Karteireiter „Soap Ui log“ und „error log“ angezeigt.
[1] Stand der Quelle: 31.01.2011
[2] Stand der Quelle: 31.01.2011
[3] Stand der Quelle: 31.01.2011
[4] Stand der Quelle: 31.01.2011
[5] Stand der Quelle: 31.01.2011
[6] Stand der Quelle: 31.01.2011