Wo beginnt man am besten?
Startpunkt: www.chipkarte.at/de/javadoc
In der folgenden dreigeteilten Ansicht der Startseite findet sich zur Navigation (1) eine Auflistung der Java Packages nach e‑card Service (SOAP), (2) eine Auflistung der jeweiligen Klassen und (3) der dynamische Lesebereich (mit u.a. Detail-/Fließtext-Beschreibungen der einzelnen Funktionen).
Eine Übersicht ALLER e-card Services und deren Packages befindet sich unter dem Reiter "Overview" in der oberen Menüleiste.
Scrollt man in der Hauptansicht gleich zu Beginn runter, findet man eine Reihe von Hinweisen für Software-Hersteller:
- Begriffsdefinitionen
- Endpoint-URLs
- Hinweise zur Einbindung der Software in das e‑card System
- Informationen zur Funktionsweise des e‑card Systems
- Informationen zu den Laufzeitgruppen
- Informationen zur Replayfunktionalität
Wo finde ich die Beschreibung eines bestimmten e-card Service?
Quick Guide
- Auswahl des gewünschten Service in (1)
- Einfach-Klick auf das dazugehörige Interface in (2)
Anhand vom Beispiel e‑Rezept (REZ):
Die JavaDoc enthält zwei wichtige Informationen zu einem Service:
- im Bereich "CLASS" (Default):
Funktions-/Methoden-Beschreibungen - im Bereich "PACKAGE":
Fachliche Übersicht über das Service (inkl. Voraussetzungen zur Nutzung, Workflows & Abhängigkeiten, technische Hinweise)
CLASS
Im Bereich Class (Default-Auswahl in (3)) findet sich eine Übersicht der Funktionen und deren Beschreibung in (3) (Tabelle "Method Summary"):
Klickt man auf den Funktionsnamen selbst, gelangt man zur ausführlichen Funktionsbeschreibung weiter unten auf der gleichen Seite. Diese enthält u.a. eine Auflistung der:
- Voraussetzungen
- Rückgabe-Parameter
- Übergabe-Parameter (inkl. Beschreibung und ggf. Bedingungen)
- Fehler-Konstanten, die als Antwort auf den Funktionsaufruf zurückgeliefert werden können
Entspricht ein Parameter keinem "primitiven" Datentypen (String, Bool, Int, ...), sondern einem zusammengesetzten Objekt, ist dieser mit einem Link zur beschreibenden Klasse hinterlegt. Diese enthalten wiederum eine Tabelle "Method Summary", in der mit einem Einfach-Klick auf die Funktionsnamen zur Detailbeschreibung auf der selben Seiten navigiert werden kann.
Jede Detailbeschreibung enthält zusätzlich einen "Throws"-Bereich, in welchem die für diese Funktion möglichen Exceptionsklassen und Fehlercodes angeführt sind.
PACKAGE
Aus dem CLASS-Bereich kann über die Navigationsleiste am oberen Rand zur PACKAGE-Übersicht navigiert werden:
Unter den Tabellen "Interface Summary" und "Class Summary" (in (3)) findet sich eine ausführliche Freitextbeschreibung zum jeweiligen Service:
In der Package-Beschreibung finden sich wichtige technische und fachliche Anforderungen, die für die Implementierung der Services ausschlaggebend sind.
Wo sind Konstanten definiert?
In der JavaDoc findet sich immer wieder der Verweis auf Konstanten,
- mit Verweis auf den Konstanten-Typen (oder die "Gruppe"), z.B.
oder - oder mit direktem Link auf den Konstanten-Namen in der Gruppe (siehe Fehler-Konstanten):
Klickt man auf den Konstanten-Namen, gelangt man zur Feld-Beschreibung. Dort wiederum wird auf die "Constant Field Values" verlinkt:
Folgt man diesem Link findet man die komplette Liste aller möglichen Konstanten in diesem Service und den tatsächlichen Werten, die der Schnittstelle übergeben werden müssen (bzw. zurückgeliefert werden):
Wie exportiere ich Service-Funktionen und -Felder in meine Software?
Die Funktionen und Datenfelder können mithilfe der WSDLs importiert werden, welche der JavaDoc beigelegt sind. Alternativ können die WSDLs auch mittels <Endpoint-URL des Service>/<Service-Version>?wsdl abgerufen werden (empfohlen!).
Im jeweiligen WSDLs befinden sich im Schema mit dem targetNameSpace "http://soap.rez.client.chipkarte.at" alle Definitionen der Funktionen und Datenfelder als complexType. Aus diesen können Code-Stubs (bzw. Klassen) generiert und angelegt werden, die durch die Software nurmehr entsprechend befüllt werden müssen.
...