Die DVDV-Bibliothek ist eine Client-Library, die es einem Fachverfahren ermöglicht, an der REST-Schnittstelle des DVDV2-Server Abfragen auszuführen. Sie ist der Nachfolger des DVDV1-SDK und nicht zu diesem kompatibel.

Einbinden der DVDV-Bibliothek in den Build-Prozess

Fügen Sie die Datei dvdv-api-<VERSION>.jar dem Build- und Laufzeit-Classpath hinzu, aber die Datei dvdv-impl-<VERSION>.jar nur dem Laufzeit-Classpath.

Fügen Sie die abhängigen Libraries (in einer jeweils aktuellen Version) ebenfalls dem Classpath hinzu. Die zum jetzigen Zeitpunkt aktuellen Versionen der unmittelbar abhängigen Libraries finden Sie im Auslieferungsverzeichnis lib/ext/.

Beispielanwendung

Im Auslieferungsverzeichnis samples finden Sie das Beispiel DVDV-SDK-sample mit einer kurzen Anleitung.

Kurz-Einführung

Einsatz-Szenarien und Initialisierung

Sie können diese DVDV-Bibliothek in drei Szenarien einsetzen:

1. Rechenzentrumsinterne Schnittstelle: Dazu benötigen Sie die URL(s) zu (mindestens) einem DVDV2-Server, dessen rechenzentrumsinterne Schnittstelle "/dvdv2-backend/intern/*" Sie im Netzwerk erreichen können. Dies ist insbesondere für die Entwicklung sehr nützlich, da es die Abhängigkeit zu fremden Systemen verringert.
2. Mit Authentifizierung am Kernsystem ("Standalone-Authentifizierung"): Dazu benötigen Sie die URL(s) zu (mindestens) einem DVDV2-Server. Dies ist das Standard-Szenario für Produktivumgebungen und Authentifizierung von Behörden.
3. Mit IAM/Keycloak-basierten Authentifizierung: Dazu benötigen Sie außerdem noch die URL zu einer Instanz des IAM/Keycloak sowie verschiedene Authentifizierungsparameter. Dies ist das Standard-Szenario für Produktivumgebungen, in denen Standalone-Authentifizierung nicht möglich ist.

Bemerkung: In den ersten beiden Szenarien spielt es keine Rolle, ob Ihr DVDV2-Server in der für Test-Zwecke gedachten sogenannten "noauth-Variante" oder in der üblichen authentifizierungspflichtigen Variante installiert ist. Für das dritte Szenario muss es sich aber um die authentifizierungspflichtige Variante handeln. Einstiegspunkt für die API ist in jedem Fall die Klasse DVDV2ManagerFactory. Die zentrale Schnittstelle in DVDVManager. Nähere Informationen finden Sie abhängig von Einsatzszenario in DVDV2ManagerFactory.createDVDV2ServerConnectionParamsBuilderIntern(), in DVDV2ManagerFactory.createDVDV2ServerConnectionParamsBuilderStandalone() bzw. in DVDV2ManagerFactory.createDVDV2ServerConnectionParamsBuilderIam().

Failover

Beim Auruf der Methode DVDV2ManagerFactory.initialize(java.util.List<de.dvdv2.manager.DVDV2ServerConnectionParams>) können Sie mehrere DVDV2-Serververbindungen angeben. Der Eintrag mit Index 0 ist der Standard-DVDV2-Server. Die folgenden Einträge werden nur benutzt, wenn alle vorangegangenen ausgefallen sind ("Failover"). In diesem Fall wird die DVDV-Bibliothek in gewissen Abständen versuchen, wieder auf den Standard-DVDV2-Server zu wechseln ("Recover").

Wenn Ihr Fachverfahren auf Failover-Ergeignisse reagieren soll, verwenden Sie die Methode DVDVManager.addFailoverListener(de.dvdv2.events.FailoverListener)

Fachliche Logik

Die fachliche Logik des DVDV2-Servers, die über die DVDV2-Bibliothek angeboten werden, erreichen Sie z.B. über die folgenden Funktionen des Interface DVDVManager:

• DVDVManager.findServiceDescription(de.dvdv2.message.FindServiceDescriptionRequest)
• DVDVManager.findOrganizationDescription(de.dvdv2.message.FindOrganizationDescriptionRequest) (bzw. funktionsgleich: DVDVManager.findAuthorityDescription(de.dvdv2.message.FindOrganizationDescriptionRequest)
• DVDVManager.verifyCategory(de.dvdv2.message.VerifyCategoryRequest)
• DVDVManager.findCategories(de.dvdv2.message.FindCategoriesRequest)

Vergleich DVDV1-SDK mit der DVDV2-Bibliothek

Konzept

Folgendes sind einige der Unterschiede zwischen dem DVDV1-SDK und der DVDV2-Bibliothek:

• Die Kommunikation zum Server basierte im Falle des DVDV1-SDK auf OSCI und durch die damit verbundene Latenz sehr langsam. Im Falle der DVDV2-Bibliothek findet die Kommunikation per HTTP(S) statt und ist somit deutlich schneller.
• Infolgedessen ist bei der DVDV2-Bibliothek zunächst auf die Implementierung eines Caches verzichtet worden.
• Die Kommunikation im Falle von DVDV1-SDK basierte auf XML. Zur Kommunikation mit dem DVDV-Server war u.a. eine wsdl-Datei nötig. Im Unterschied dazu basiert die Kommunikation im Falle der DVDV2-Bibliothek auf JSON, aber dies bleibt Ihrem Anwendungscode verborgen.
• Im Gegensatz zu DVDV1 bietet die DVDV2-Bibliothek die Möglichkeit, im Falle von Verbindungsproblemen transparent auf einen zweiten (oder ggf. sogar weiteren) DVDV2-Server und später wieder zurückzuwechseln. Dies war bei DVDV1 in der Verantwortung des Fachverfahrens.

Migration von DVDV1-basierten Fachverfahren.

Um ein bestehendes DVDV1-Fachverfahren auf DVDV2 zu migrieren, werden tiefgreifende Änderungen nötig sein. In einigen Punkten gibt es aber Entsprechungen zwischen der Schnittstellen des DVDV1-SDK und der der DVDV2-Bibliothek, z.B.:

Gegenüberstellung DVDV1 und DVDV2

DVDV1	DVDV2
de.dvdv.manager.DVDVManager	DVDVManager
de.dvdv.object.message.DVDVRequest	DVDVRequest
de.dvdv.object.ServiceData	ServiceBase
de.dvdv.object.ServiceData.getUuid()	ServiceBase.getDvdv1Uuid()
de.dvdv.object.ServiceData.getValidFrom()	ServiceBase.getValidFrom()
de.dvdv.object.ServiceData.getValidUntil()	ServiceBase.getValidTo()
de.dvdv.object.ServiceElement	ServiceElementInfo
de.dvdv.object.CipherCertificateElement	ServiceElementInfo mit ServiceElementInfo.getServiceElementType() == ServiceElementType.CIPHER_CERTIFICATE
de.dvdv.object.SignatureCertificateElement	ServiceElementInfo mit ServiceElementInfo.getServiceElementType() == ServiceElementType.SIGNATURE_CERTIFICATE
de.dvdv.object.osci.OsciAddresseeElement	ServiceElementInfo mit ServiceElementInfo.getServiceElementType() == ServiceElementType.OSCI_ADDRESSEE
de.dvdv.object.CipherCertificateElement.getCertificate() bzw. de.dvdv.object.SignatureCertificateElement.getCertificate()	ServiceElementInfo.getCipherCertificate() nebst Certificate.getContent()
de.dvdv.object.Authority	OrganizationDescription nebst Organization
de.dvdv.object.Authority.getName()	LightweightOrganization.getNameDe()
de.dvdv.object.Authority.getAuthorityProxies()	OrganizationDescription.getRepresentatives()
de.dvdv.object.Authority.getOwnClientCertificates()	Organization.getClientCertificates()
de.dvdv.object.Authority.getAllClientCertificates()	OrganizationDescription.getAllClientCertificates()
de.dvdv.object.Authority.getOwnServices()	Organization.getServices()
de.dvdv.object.Authority.getAllServices()	OrganizationDescription.getAllServices()
de.dvdv.DVDVException	DVDVException
de.dvdv.http.DVDVHttpException	DVDVHttpException

Packages

Package	Description
de.dvdv2	Nur die unterhalb dieses Root-Packages liegenden Packages und Klassen sind als Compile-Abhängigkeit zugelassen.
de.dvdv2.events	Interfaces zur Reaktion auf (Failover-)Events.
de.dvdv2.manager	Beschreibungen und Kapselung für den Verbindungsaufbau eines Fachverfahrens für die verschiedenen Varianten der Authentifizierung für die Abfrage der fachlichen DVDV2 Objekte
de.dvdv2.message	Interfaces der fachlichen Objekte für die Anfrage des DVDV2 Backends.
de.dvdv2.object	Interfaces der fachlichen Objekte im DVDV2 Kontext.