Die virtic Webservices
Ein virtic-Webservice ist eine Anwendung, auf die über das Internet mittels eines standardisierten Protokolls zugegriffen werden kann. Zur Zeit verfügt und unterstützt virtic Webservices, die auf SOAP basieren, hierbei werden Nachrichten im XML-Format zwischen der Client-Anwendung und dem Webservice ausgetauscht. Mittels WSDL-Dateien wird das öffentliche Interface veröffentlicht und beschrieben und in dem darin enthaltenen XML-Schema werden sowohl einfache wie auch komplexe Datentypen und auch die API- Methoden definiert und beschrieben.
WSDL Dateien
SOAP-Webservices veröffentlichen und beschreiben die öffentlichen Schnittstelle zur Anwendung in WSDL-Dateien. Sie geben Auskunft über die Syntax des Methodenaufrufs und die für die Client-Anwendung verbindlichen Anforderungen für den Zugriff darauf.
Die WSDL-Datei beschreibt den Dienst in mehreren Abschnitten, in denen unterschiedliche Operationen und Anforderungen definiert werden. Diese Abschnitte korrespondieren mit folgenden Elementen:
| Definitions | beschreibt den Webservice |
| Types | Enthält das XML-Schema für jeden Webservice und den SOAP-Fehler |
| Messages | Definiert die Anfrage- und Antwortnachricht |
| Port Types | enthält die Signaturen für die Operationen des Service, die den Methoden der Anwendung entsprechen |
| Bindings | Beschreiben die SOAP-Bindungen für alle Service Objekte und beschreiben wie eine Operation innerhalb eines Ports dem SOAP–Protokoll zugeordnet wird. |
| Services | beschreibt den Standort des Webservices |
Nicht alle Webservices verfügen über die oben genannten Abschnitte. Die Definitionen zum WSDL–Standard findet man auf der folgenden Webseite des W3C: http://www.w3.org/TR/wsdl
SOAP
Das SOAP-Protokoll wird verwendet, um Nachrichten zwischen einer Client-Anwendung und einem Webservice auszutauschen. Im Internet wird vom Fachpublikum über zahlreiche Szenarien hinsichtlich der Webservice-Kommunikation diskutiert, welche auf dieser Webseite beschrieben sind: http://www.w3.org/TR/ws-arch-scenarios.
Bei dem von virtic-Webservices unterstützten REQUEST-RESPONSE-Szenario sendet eine Client- Anwendung eine Anforderung, die vom Server entweder erfolgreich beantwortet oder mit einer Fehlermeldung quittiert wird.
Die folgende Tabelle enthält eine Übersicht über die drei momentan gebräuchlichen Formate einer SOAP-Nachricht(message).
SOAP message Formate
| Format | Bemerkungen |
|---|---|
| Document/Literal(Doc/Lit) | Das von virtic empfohlene Format. Es funktioniert gut für .Net, Java und OpenEdge-Clients |
| RPC/Encoded | Veraltet. Wird nicht von virtic unterstützt |
Die von virtic veröffentlichten Webservices liegen immer für je eine fachliche Anwendung in je einer Version in dem Format Doc/Lit und in einer Version mit dem Format RPC/Literal vor.
Die SOAP message document Struktur
SOAP Message verfügen über eine allgemeine, aus drei aufeinanderfolgen Elementen bestehende Struktur.
Der Envelope ist ein mandatorisches Element, welches ein optionales header-Element und ein mandatorisches body-Element enthält. virtic-Webservices enthalten das header-Element allerdings immer. Hierüber werden signifikante eindeutige Schlüsselwerte und Kontext-Informationen ausgetauscht. Darüber hinaus werden namespaces definiert, durch die Namenskonflikte in XML- Elementen vermieden werden. Das mandatorische body-Element enthält entweder die Daten eines Requests, eines Responses oder eine Fehlerinformation.
XML-Schema
SOAP-Webservices verwenden ein XML-Schema für die Deklaration sowohl einfacher(skalare Typen) als auch komplexer Daten der Anwendung(array, dataSets) innerhalb der WSDL-Datei. Nähere Informationen über das XML–Schema findet man auf dieser Webseite: http://www.w3.org/TR/xmlschema-0/
Architektur der virtic-Webservice
Entwicklung einer virtic SOAP-Webservice Client-Anwendung
Entwicklung in Microsoft® Visual Studio
Microsofts Visual Studio erzeugt automatisch Proxy-Code aus dem Verweis auf eine WSDL-Datei oder eine WSDL-URI und speichert diese in einer References-Datei.
Entwicklung in Java
Das Apache Axis-Toolkit enthält die Anwendung wsdl2Java, um einen Webservice anhand einer WSDL-Datei zu analysieren und daraus Klassen mit dem notwendigen Proxy-Code zu erzeugen.
Entwicklung in Progress OpenEdge
Für Entwicklungen in Progress OpenEdge kann der Progress OpenEdge WSDL Analyzer für die automatische Generierung der Proxy Objekte verwendet werden.
Entwicklung einer .NET Clientanwendung für den virtic Baustellen SOAP Webservice
Für die Erstellung einer .NET Webservice Client Anwendung wählt man zu Beginn der Entwicklung folgendes Standardverfahren:
- Auswahl der .NET Sprache
- Hinzufügen einer WebReference für den WebService durch die Angabe einer WSDL-Datei. Hierdurch werden automatisch die .NET Interface Objekte erzeugt
- Entwicklung der Anwendungslogik und der Schnittstellen für den Aufruf der WebService Methoden
Webreferences
Webreference virdocBaustelle
URL: https://www.virtic24.com/wsa/wsa1/wsdl?targetURI=virdocBaustelle
TargetNamespace: virdocbaustelle
oder alternativ
Webreference virsapBaustelle
TargetNamespace: https://www.virtic.com/xmlns/virsapBaustelle
Spezifikation eines Webservices für ein Beispiel in C#
Die folgende Tabelle enthält die im Beispielprogramm verwendeten Spezifikationen des virtic WebService für die Verwaltung von Baustellen.
| Eigenschaft/Komponente | Wert/Name | Objekttyp |
|---|---|---|
| Webreference | wsBaustelle | - |
| URL | bitte anfragen | - |
| TargetNamespace | urn:virtic:baustelleSvc:wsBaustelle | |
| WSDL Objekte | wsBaustelleObj | Server Objekt |
| baustelleObj | Anwendung-Objekt | |
| baustelleID | Anwendungs-Object | |
| baustelleV100InRow | Struktur mit skalaren Typen | |
| baustelleV100OutRow | Struktur mit skalaren Typen |
Je nach eingesetzter .NET Version wird die Webreferenz durch die Verwendung mehrerer Dialoge dem Projekt hinzugefügt. In Visual Studio 2010 verfährt man folgendermaßen:
Im Solution-Explorer der .NET IDE das C#-Object auswählen und dann das Kontext-Menü öffnen und dort die Option Add Service Reference auswählen. Im folgenden Dialog den Button Advanced… klicken, wodurch sich ein weiterer Dialog öffnet. Hier den Button Add Web Reference klicken und im dann folgenden Dialog im Eingabefeld URL diesen Wert eingeben:
https://www.virtic24.com/wsa/wsa1/wsdl?targetURI=virdocBaustelle
Bei Verlassen des Feldes wird der SOAP-Webservice analysiert und das zusammenfassende Ergebnis im Textfenster angezeigt. Ein Klick auf den Button Add Reference erzeugt alle notwendigen Klassen für unterschiedlichen Objekttypen.
Beispielprogramm
Ein kleines Konsolenprogramm für die Verwendung des virtic Baustellen-Webservices schrittweise erklärt
Nachdem auf Datei • Neu ein Dialog zur Neuanlage eine Projektes geöffnet wurde, muss hier zunächst die Vorlage Console Application ausgewählt und ein Name eingegeben werden.
In diesem Beispiel verwenden wir den Projektnamen virBaustelle. Anschließend muss zunächst die Webreferenz wie oben beschrieben hinzugefügt werden.
Im automatisch erzeugten Programm sollen jetzt folgende Aufgaben erfüllt werden:
1. Verbindung mit dem Server herstellen
2. Anwendungs-Objekt auf dem Server erzeugen
3. Die Operation fetchV100 zur Selektion der Baustellen ausführen
4. Die Operation updateV100 zum Insert bzw. Update eines Tupels ausführen
5. Anwendungs-Objekt auf dem Server freigeben
6. Verbindung zum Server abbauen
Aus dem Main-Block heraus wird die Methode connectfetchandupdate() aufgerufen. Hier sind die oben beschrieben Aufgaben implementiert. Das gesamte, recht kurze Programm kann hier heruntergeladen werden. (Je nach dem tatsächlich verwendeten Webservice muss ggf. die URI usw. editiert werden.)
Entwicklung einer JAVA Clientanwendung für den virtic Baustellen SOAP Webservice
Für die Erstellung der Proxy-Klassen wird das Apache Axis Toolkit Version 1.4 eingesetzt.
Es wird das folgende Standardverfahren für die Generierung der notwendigen Klassen eingesetzt.
In einem neu zu erstellenden Betriebssystemverzeichnis virticSOAP werden die JAR-Archive der Axis Distribution innerhalb eines Unterverzeichnisses gespeichert.
Es steht dann zunächst folgende Verzeichnis- und Dateistruktur bereit:
virticSOAP/
axis_1_4\lib\wsdl4j-1.5.1.jar
axis_1_4\lib\axis.jar
axis_1_4\lib\axis-ant.jar
axis_1_4\lib\commons-discovery-0.2.jar
axis_1_4\lib\commons-logging-1.0.4.jar
axis_1_4\lib\jaxrpc.jar
axis_1_4\lib\log4j.properties
axis_1_4\lib\log4j-1.2.8.jar
axis_1_4\lib\saaj.jar
Mit der Ausführung der folgenden Kommandos werden dann die notwendigen Klassen im Verzeichnis virticBaustelle durch die Analyse des SOAP-Services erzeugt:
- zunächst den Klassenpfad erzeugen:set cp=axis_1_4/lib/wsdl4j-1.5.1.jar;axis_1_4/lib/commons-logging-1.0.4.jar;axis_1_4/lib/commons-discovery-0.2.jar;axis_1_4/lib/jaxrpc.jar;axis_1_4/lib/axis.jar;axis_1_4/lib/saaj.jar;axis_1_4/lib/log4j-1.2.8.jar
- dann das Axisprogramm WSDL2Java starten:%JAVA_HOME%/bin/java -cp %cp% org.apache.axis.wsdl.WSDL2Java
https://www.virtic24.com/wsa/wsa1/wsdl?targetURI=http://www.virtic.com/xmlns/virsapBaustelle
Die Angabe der WSDL Datei als Parameter hinter dem Aufruf org.apache.axis.wsdl.WSDL2Java ist obligatorisch.
Anschließend sind vier neue Ordner im Verzeichnis vorhanden:
baustelle\
virsapBaustelle\
details\
wsBaustelle\
Im nächsten Schritt wird ein neues Javaprojekt in Eclipse mit dem Namen virBaustelle angelegt, wodurch unter anderem ein Ordner src für die Quellen erzeugt wird. In diesen Ordner werden die vier oben genannten Ordner per Drag&Drop hineinkopiert, außerdem wird der Axis-Ordner aus dem oben genannten Verzeichnis ebenfalls in den Projektordner hineinkopiert.
Als nächstes werden die Projekteigenschaften so geändert, dass zum Java-Build-Path die JAR-Archive aus dem AXIS-Ordner hinzugefügt werden.
Bevor mit der Erstellung eines Beispielprogramms begonnen werden kann, müssen noch zwei Dateien mit Helfer-Klassen in das Default Package kopiert werden:
Ein Beispielprogramm können Sie hier herunterladen: soap_baustelle.java (Je nach dem tatsächlich verwendeten Webservice muss ggf. die URI, service usw. editiert werden.)
