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: 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: 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

Document/Literal(Doc/Lit)	Das von virtic empfohlene Format
RPC/Encoded

Die von virtic veröffentlichten Webservices liegen immer für jede fachliche Anwendung in je einer Version in dem Format Document/Literal und in einer Version mit dem Format RPC/Encoded 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:
1. Auswahl der .NET Sprache
2. Hinzufügen einer WebReference für den WebService durch die Angabe einer WSDL-Datei. Hierdurch werden automatisch die .NET Interface Objekte erzeugt
3. 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:

1. 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

2. 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:
HandlerControlBlock.java
PscObjectIDHandler.java

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.)