Package de.dvdv2.manager

Interface DVDVManager

public interface DVDVManager

Zentrale Klasse der DVDV-Bibliothek, kapselt die Kommunikation mit dem IAM/Keycloak (falls beteiligt) und dem DVDV2-Server sowie das Failover, also den Wechsel zu einem anderen DVDV2-Server im Fehlerfall.
Ein typisches Fachverfahren wird genau ein Objekt dieses Typs erzeugen und das dann in der ganzen Anwendung dauerhaft verwenden, also ggf. auch in verschiedenen Threads. Wenn Sie davon abweichen, sollten Sie bedenken, dass verschiedene Objekte dieses Typs unabhaengig voneinander (und damit i.d.R. ueberfluessige) Authentifizierungsrequests machen.
Entspricht in etwa der DVDV1-Klasse de.dvdv.manager.DVDVManager.

Method Summary

Modifier and Type	Method	Description
void	addFailoverListener(FailoverListener listener)	Registriert den angegebenen FailoverListener, damit diese im Failover-Fall benachrichtigt wird.
CategoryRequest	createCategoryRequest(String category)	Erzeugt Instanz für den Aufruf von findServiceSpecificationUrisByCategory(CategoryRequest),
FindOrganizationDescriptionRequest	createFindAuthorityDescriptionRequest(String organizationKey, String category)	Diese Methode wird mittelfristig zugunsten der funktionsgleichen Methode createFindOrganizationDescriptionRequest(String, String) entfernt werden.
FindCategoriesRequest	createFindCategoriesRequest(String fingerPrint, String organizationKey)	Erzeugt Instanz für den Aufruf von findCategories(de.dvdv2.message.FindCategoriesRequest).
FindOrganizationDescriptionRequest	createFindOrganizationDescriptionRequest(String organizationKey, String category)	Erzeugt Instanz für den Aufruf von findOrganizationDescription(de.dvdv2.message.FindOrganizationDescriptionRequest).
FindOrganizationDescriptionsRequest	createFindOrganizationDescriptionsRequest(String organizationKey)	Erzeugt Instanz für den Aufruf von findOrganizationDescriptions(de.dvdv2.message.FindOrganizationDescriptionsRequest) und benötigt daher im Gegensatz zu createFindOrganizationDescriptionRequest(String, String) keinen Kategorienamen als Parameter.
FindOrganizationsByServiceElementRequest	createFindOrganizationsByCustomServiceElementRequest(String customServiceElementType, ParameterType parameterType, String parameterValue)	wie createFindOrganizationsByServiceElementRequest(de.dvdv2.object.ServiceElementType, de.dvdv2.object.ParameterType, java.lang.String), aber für konfigurierbare Dienstelementtypen.
FindOrganizationsByServiceElementRequest	createFindOrganizationsByServiceElementRequest(ServiceElementType serviceElementType, ParameterType parameterType, String parameterValue)
FindServiceDescriptionRequest	createFindServiceDescriptionRequest(String organizationKey, String serviceSpecificationUri)	Erzeugt Instanz für den Aufruf von findServiceDescription(de.dvdv2.message.FindServiceDescriptionRequest).
FingerPrintRequest	createFingerPrintRequest(String fingerPrint)	Erzeugt Instanz für den Aufruf von findCertificateByFingerprint(FingerPrintRequest),
VerifyCategoryRequest	createVerifyCategoryRequest(String fingerPrint, String category)	Erzeugt Instanz für den Aufruf von verifyCategory(de.dvdv2.message.VerifyCategoryRequest).
OrganizationDescription	findAuthorityDescription(FindOrganizationDescriptionRequest request)	Diese Methode wird mittelfristig zugunsten der funktionsgleichen Methode findOrganizationDescription(FindOrganizationDescriptionRequest) entfernt werden.
List<String>	findCategories(FindCategoriesRequest request)	Liefert Liste aller Organisationskategorien, für die es eine Organisation gibt, die ein Client-Zertifikat mit dem angegebenen Fingerprint besitzt und den angegebenen Organisationsschlüssel besitzt. Das Ergebnis ist eine Liste von Kategoriennamen (typischerweise mit höchstens einem Eintrag).
List<List<String>>	findCategories(List<FindCategoriesRequest> requests)	batch-Variante von findCategories(FindCategoriesRequest).
Certificate	findCertificateByFingerprint(FingerPrintRequest request)	Ermittelt die Zertifikatsmetadaten des Zertifikats mit dem angegebenen Fingerprint, falls es mindestens einmal in der Datenbank hinterlegt ist.
OrganizationDescription	findOrganizationDescription(FindOrganizationDescriptionRequest request)	Liefert die (einzige) Organisation mit der angegebenen Kategory und dem angegebenen Organisationsschlüssel.
List<? extends OrganizationDescription>	findOrganizationDescription(List<FindOrganizationDescriptionRequest> requests)	batch-Variante von findOrganizationDescription(FindOrganizationDescriptionRequest).
List<? extends OrganizationDescription>	findOrganizationDescriptions(FindOrganizationDescriptionsRequest request)	Ähnlich wie findOrganizationDescription(FindOrganizationDescriptionRequest), aber ohne Angabe der Kategorie.
List<? extends LightweightOrganization>	findOrganizationsByServiceElement(FindOrganizationsByServiceElementRequest request)	Hiermit können Sie Organisationen suchen anhand bestimmter Eigenschaften eines ihrer Dienstelementzertifikate.
List<? extends List<? extends LightweightOrganization>>	findOrganizationsByServiceElement(List<FindOrganizationsByServiceElementRequest> requests)	batch-Variante von findOrganizationsByServiceElement(FindOrganizationsByServiceElementRequest).
ServiceDescription	findServiceDescription(FindServiceDescriptionRequest request)	Liefert die (einzige) aktuell gültige Dienstbeschreibung der angegebenen Organisation mit der angegebenen Dienstbeschreibungs-URI.
List<? extends ServiceDescription>	findServiceDescription(List<FindServiceDescriptionRequest> requests)	batch-Variante von findServiceDescription(FindServiceDescriptionRequest).
List<String>	findServiceSpecificationUrisByCategory(CategoryRequest request)	Liefert eine Liste aller Werte von ServiceBase.getServiceSpecificationUri() von solchen Dienstbeschreibungen, die eine Organisation anbieten darf, wenn sie die angegebene Kategorie hat.
List<List<String>>	findServiceSpecificationUrisByCategory(List<CategoryRequest> requests)	batch-Variante von findServiceSpecificationUrisByCategory(CategoryRequest).
List<? extends OrganizationCategory>	getCategories()	Liefert den Baum aller im DVDV verzeichneten Kategorien.
List<? extends SummaryServiceElement>	getIntermediaries()	Ermittelt alle Intermediäre im DVDV.
VersionInfo	getVersionInfo()	Fragt beim DVDV2-Server Versionsinformationen ab.
void	removeFailoverListener(FailoverListener listener)	Das Gegenstueck zu addFailoverListener(FailoverListener).
Map<String,Boolean>	verifyCategory(VerifyCategoryRequest request)	Prüft, ob es für die übergebene Behördenkategorie ein passendes Client-Zertifikat gibt.
List<Map<String,Boolean>>	verifyCategory(List<VerifyCategoryRequest> requests)	batch-Variante von verifyCategory(VerifyCategoryRequest).

Method Details

createFindServiceDescriptionRequest

FindServiceDescriptionRequest createFindServiceDescriptionRequest(String organizationKey,
 String serviceSpecificationUri)

Erzeugt Instanz für den Aufruf von findServiceDescription(de.dvdv2.message.FindServiceDescriptionRequest).
Entspricht in etwa der DVDV1-Methode de.dvdv.manager.DVDVManager.createFindServiceDescriptionRequest.

Parameters:

organizationKey - DVDV-Organisationsschlüssel

Returns:

passende Instanz für den Aufruf von findServiceDescription(FindServiceDescriptionRequest)

createFindOrganizationDescriptionRequest

FindOrganizationDescriptionRequest createFindOrganizationDescriptionRequest(String organizationKey,
 String category)

Erzeugt Instanz für den Aufruf von findOrganizationDescription(de.dvdv2.message.FindOrganizationDescriptionRequest).
Entspricht in etwa der DVDV1-Methode de.dvdv.manager.DVDVManager.createFindAuthorityDescriptionRequest.

Parameters:

organizationKey - DVDV-Organisationsschlüssel

category - DVDV-Kategorie, z.B. 'Meldebehörde'

Returns:

passende Instanz für den Aufruf von findOrganizationDescription(FindOrganizationDescriptionRequest)

createFindOrganizationDescriptionsRequest

FindOrganizationDescriptionsRequest createFindOrganizationDescriptionsRequest(String organizationKey)

Erzeugt Instanz für den Aufruf von findOrganizationDescriptions(de.dvdv2.message.FindOrganizationDescriptionsRequest) und benötigt daher im Gegensatz zu createFindOrganizationDescriptionRequest(String, String) keinen Kategorienamen als Parameter.

Parameters:

organizationKey - DVDV-Organisationsschlüssel

Returns:

passende Instanz für den Aufruf von findOrganizationDescriptions(FindOrganizationDescriptionsRequest)

createFindOrganizationsByServiceElementRequest

FindOrganizationsByServiceElementRequest createFindOrganizationsByServiceElementRequest(ServiceElementType serviceElementType,
 ParameterType parameterType,
 String parameterValue)

Parameters:

serviceElementType - built-in Dienstelementtyp

Returns:

passende Instanz für den Aufruf von findOrganizationsByServiceElement(FindOrganizationsByServiceElementRequest)

createFindOrganizationsByCustomServiceElementRequest

FindOrganizationsByServiceElementRequest createFindOrganizationsByCustomServiceElementRequest(String customServiceElementType,
 ParameterType parameterType,
 String parameterValue)

wie createFindOrganizationsByServiceElementRequest(de.dvdv2.object.ServiceElementType, de.dvdv2.object.ParameterType, java.lang.String), aber für konfigurierbare Dienstelementtypen.

Returns:

passende Instanz für den Aufruf von findOrganizationsByServiceElement(FindOrganizationsByServiceElementRequest)

createFindAuthorityDescriptionRequest

FindOrganizationDescriptionRequest createFindAuthorityDescriptionRequest(String organizationKey,
 String category)

Diese Methode wird mittelfristig zugunsten der funktionsgleichen Methode createFindOrganizationDescriptionRequest(String, String) entfernt werden.

Parameters:

organizationKey - DVDV-Organisationsschlüssel

category - DVDV-Kategorie, z.B. 'Meldebehörde'

createVerifyCategoryRequest

VerifyCategoryRequest createVerifyCategoryRequest(String fingerPrint,
 String category)

Erzeugt Instanz für den Aufruf von verifyCategory(de.dvdv2.message.VerifyCategoryRequest).
Entspricht in etwa der DVDV1-Methode de.dvdv.manager.DVDVManager.createVerifyCategoryRequest.

Parameters:

fingerPrint - Fingerprint Zertifikats. Der Fingerprint für ein X509-Zertifikat cert kann mithilfe des Bibliothek commons-codec berechnet werden wie folgt

           fingerprint = org.apache.commons.codec.digest.DigestUtils.sha1Hex(cert.getEncoded())
           

category - DVDV-Kategorie, z.B. 'Meldebehörde'

Returns:

passende Instanz für den Aufruf von verifyCategory(VerifyCategoryRequest)

createFindCategoriesRequest

FindCategoriesRequest createFindCategoriesRequest(String fingerPrint,
 String organizationKey)

Erzeugt Instanz für den Aufruf von findCategories(de.dvdv2.message.FindCategoriesRequest).

Parameters:

fingerPrint - Fingerprint Zertifikats. Der Fingerprint für ein X509-Zertifikat cert kann mithilfe des Bibliothek commons-codec berechnet werden wie folgt:

           fingerprint = org.apache.commons.codec.digest.DigestUtils.sha1Hex(cert.getEncoded())
           

organizationKey - DVDV-Organisationsschlüssel

Returns:

passende Instanz für den Aufruf von findCategories(FindCategoriesRequest)

createFingerPrintRequest

FingerPrintRequest createFingerPrintRequest(String fingerPrint)

Erzeugt Instanz für den Aufruf von findCertificateByFingerprint(FingerPrintRequest),

Parameters:

fingerPrint - fingerprint Zertifikats. Der Fingerprint für ein X509-Zertifikat cert kann mithilfe des Bibliothek commons-codec berechnet werden wie folgt

           fingerprint = org.apache.commons.codec.digest.DigestUtils.sha1Hex(cert.getEncoded())
           

Returns:

passende Instanz für den Aufruf von findCertificateByFingerprint(FingerPrintRequest)

createCategoryRequest

CategoryRequest createCategoryRequest(String category)

Erzeugt Instanz für den Aufruf von findServiceSpecificationUrisByCategory(CategoryRequest),

Returns:

passende Instanz für den Aufruf von findServiceSpecificationUrisByCategory(CategoryRequest)

getVersionInfo

VersionInfo getVersionInfo()
                    throws DVDVIOException,
DVDVConfigurationException

Fragt beim DVDV2-Server Versionsinformationen ab.

Throws:

DVDVIOException

DVDVConfigurationException

findServiceDescription

ServiceDescription findServiceDescription(FindServiceDescriptionRequest request)
                                   throws DVDVException

Liefert die (einzige) aktuell gültige Dienstbeschreibung der angegebenen Organisation mit der angegebenen Dienstbeschreibungs-URI. Gültig ist ein Dienst, wenn die Serverzeit zum Zeitpunkt der Abfrage in dem für den Dienst hinterlegten Gültigkeitszeitraum liegt. Im Unterschied zu findOrganizationDescription(FindOrganizationDescriptionRequest) hängt dieses Methode also vom aktuellen Zeitpunkt ab.
Entspricht in etwa der DVDV1-Methode de.dvdv.manager.DVDVManager.processRequest mit einem Parameter von Typ de.dvdv.object.message.FindServiceDescriptionRequest.

Throws:

DVDVNoHitsException - falls es keine entsprechende Dienstbeschreibung gibt

DVDVException

findServiceDescription

List<? extends ServiceDescription> findServiceDescription(List<FindServiceDescriptionRequest> requests)
                                                   throws DVDVException

batch-Variante von findServiceDescription(FindServiceDescriptionRequest). Der Aufruf

    serviceDescriptions = dvdvManager.findServiceDescription(requests);
 

ist weitgehend äquivalent zu

    serviceDescriptions = new ArrayList<>(requests.size());
    for (FindServiceDescriptionRequest request : requests) {
       try {
         serviceDescriptions.add(dvdvManager.findServiceDescription(request));
       } catch (DVDV2NoHitsException exc) {
         serviceDescriptions.add(null);
       }
    }
 

Im Unterschied zu findServiceDescription(FindServiceDescriptionRequest) wirft diese Methode in dem Fall, dass es keine entsprechende Dienstbeschreibung gibt, keine Exception, sondern trägt einen null-Wert an der entsprechenden Position der Ergebnisliste ein.

Parameters:

requests - standardmäßig darf diese Liste maximal 200 Einträge haben

Throws:

DVDVException

findOrganizationDescription

OrganizationDescription findOrganizationDescription(FindOrganizationDescriptionRequest request)
                                             throws DVDVException

Liefert die (einzige) Organisation mit der angegebenen Kategory und dem angegebenen Organisationsschlüssel. Im Unterschied zu findServiceDescription(FindServiceDescriptionRequest) hängt dieses Methode nicht vom aktuellen Zeitpunkt ab und erlaubt Zugriff auch auf aktuell ungültige Dienste.
Entspricht in etwa der DVDV1-Methode de.dvdv.manager.DVDVManager.processRequest mit einem Parameter von Typ de.dvdv.object.message.FindAuthorityDescriptionRequest.

Throws:

DVDVNoHitsException - falls es keine entsprechende Organisation gibt

DVDVException

findOrganizationDescriptions

List<? extends OrganizationDescription> findOrganizationDescriptions(FindOrganizationDescriptionsRequest request)
                                                              throws DVDVException

Ähnlich wie findOrganizationDescription(FindOrganizationDescriptionRequest), aber ohne Angabe der Kategorie. Liefert die Organisationen, die den angegebenen Organisationsschlüssel haben. Das ist fast immer höchstens eine.

Parameters:

request - kapselt den Organisationsschlüssel.

Throws:

DVDVException

findOrganizationDescription

List<? extends OrganizationDescription> findOrganizationDescription(List<FindOrganizationDescriptionRequest> requests)
                                                             throws DVDVException

batch-Variante von findOrganizationDescription(FindOrganizationDescriptionRequest). Der Aufruf

    organizationDescriptions = dvdvManager.findOrganizationDescription(requests);
 

ist weitgehend äquivalent zu

    organizationDescriptions = new ArrayList<>(requests.size());
    for (FindOrganizationDescriptionRequest request : requests) {
       try {
         organizationDescriptions.add(dvdvManager.findOrganizationDescription(request));
       } catch (DVDV2NoHitsException exc) {
         organizationDescriptions.add(null);
       }
    }
 

Im Unterschied zu findOrganizationDescription(FindOrganizationDescriptionRequest) wirft diese Methode in dem Fall, dass es keine entsprechende Organisation gibt, keine Exception, sondern trägt einen null-Wert an der entsprechenden Position der Ergebnisliste ein.

Parameters:

requests - standardmäßig darf diese Liste maximal 200 Einträge haben

Throws:

DVDVException

findAuthorityDescription

OrganizationDescription findAuthorityDescription(FindOrganizationDescriptionRequest request)
                                          throws DVDVException

Diese Methode wird mittelfristig zugunsten der funktionsgleichen Methode findOrganizationDescription(FindOrganizationDescriptionRequest) entfernt werden.

Throws:

DVDVException

verifyCategory

Map<String,Boolean> verifyCategory(VerifyCategoryRequest request)
                            throws DVDVException

Prüft, ob es für die übergebene Behördenkategorie ein passendes Client-Zertifikat gibt.
Entspricht in etwa der DVDV1-Methode de.dvdv.manager.DVDVManager.processRequest mit einem Parameter von Typ de.dvdv.object.message.VerifyCategoryRequest.
Die Schnittstelle liefert zu einem gegebenen Zertifikat-Fingerprint und der zugeordneten Organisationskategorie ein Prüfergebnis true oder false, und zwar true genau dann, wenn es eine Organisation mit der angegebenen Organisationskategorie gibt, für die das übermittelte Zertifikat als Client-Zertifikat hinterlegt ist.

Das Ergebnis ist zurzeit eine Map, in der es genau einen Eintrag gibt. Dieser hat als Schlüssel den speziellen String verifyCategory und als Wert der o.a. Boolean.

Throws:

DVDVException

verifyCategory

List<Map<String,Boolean>> verifyCategory(List<VerifyCategoryRequest> requests)
                                  throws DVDVException

batch-Variante von verifyCategory(VerifyCategoryRequest). Der Aufruf

    results = dvdvManager.verifyCategory(requests);
 

ist weitgehend äquivalent zu

    results = new ArrayList<>(requests.size());
    for (VerifyCategoryRequest request : requests) {
       results.add(dvdvManager.verifyCategory(request));
    }
 

Parameters:

requests - standardmäßig darf diese Liste maximal 200 Einträge haben

Throws:

DVDVException

findCategories

List<String> findCategories(FindCategoriesRequest request)
                     throws DVDVException

Liefert Liste aller Organisationskategorien, für die es eine Organisation gibt, die

1. ein Client-Zertifikat mit dem angegebenen Fingerprint besitzt und
2. den angegebenen Organisationsschlüssel besitzt.

Das Ergebnis ist eine Liste von Kategoriennamen (typischerweise mit höchstens einem Eintrag).

Throws:

DVDVException

findCategories

List<List<String>> findCategories(List<FindCategoriesRequest> requests)
                           throws DVDVException

batch-Variante von findCategories(FindCategoriesRequest). Der Aufruf

    results = dvdvManager.findCategories(requests);
 

ist weitgehend äquivalent zu

    results = new ArrayList<>(requests.size());
    for (FindCategoriesRequest request : requests) {
       results.add(dvdvManager.findCategories(request));
    }
 

Parameters:

requests - standardmäßig darf diese Liste maximal 200 Einträge haben

Throws:

DVDVException

findServiceSpecificationUrisByCategory

List<String> findServiceSpecificationUrisByCategory(CategoryRequest request)
                                             throws DVDVException

Liefert eine Liste aller Werte von ServiceBase.getServiceSpecificationUri() von solchen Dienstbeschreibungen, die eine Organisation anbieten darf, wenn sie die angegebene Kategorie hat.

Throws:

DVDVException

findServiceSpecificationUrisByCategory

List<List<String>> findServiceSpecificationUrisByCategory(List<CategoryRequest> requests)
                                                   throws DVDVException

batch-Variante von findServiceSpecificationUrisByCategory(CategoryRequest). Der Aufruf

    results = dvdvManager.findServiceSpecificationUrisByCategory(requests);
 

ist weitgehend äquivalent zu

    results = new ArrayList<>(requests.size());
    for (CategoryRequest request : requests) {
       results.add(dvdvManager.findServiceSpecificationUrisByCategory(request));
    }
 

Parameters:

requests - standardmäßig darf diese Liste maximal 200 Einträge haben

Throws:

DVDVException

findOrganizationsByServiceElement

List<? extends LightweightOrganization> findOrganizationsByServiceElement(FindOrganizationsByServiceElementRequest request)
                                                                   throws DVDVException

Hiermit können Sie Organisationen suchen anhand bestimmter Eigenschaften eines ihrer Dienstelementzertifikate. Dazu geben Sie im zugehörigen FindOrganizationsByServiceElementRequest drei Parameter an: ServiceElementType, ParameterType, ParameterValue.

Folgende Kombinationen sind zurzeit unterstützt:

• ServiceElementType==OSCI_ADDRESSEE, ParameterType==CIPHER_CERTIFICATE, ParameterValue==<FINGERPRINT>
  Mit dieser Kombination erhalten Sie die Liste der Organisationen, die einen Dienst anbieten, der mit einem Dienstelement vom Typ OSCI-Empfänger (OSCI_ADDRESSEE) verknüpft ist, in dem ein Zertifikat mit dem angegebenen Fingerprint als Empfänger-Zertifikat (d.h. CIPHER_CERTFICATE) eingetragen ist.
• customServiceElementType==<KONFIGURIERBARER_DIENSTELEMENT_TYP>, ParameterType==URI, ParameterValue==<WERT>
  

Throws:

DVDVException

findOrganizationsByServiceElement

List<? extends List<? extends LightweightOrganization>> findOrganizationsByServiceElement(List<FindOrganizationsByServiceElementRequest> requests)
                                                                                   throws DVDVException

batch-Variante von findOrganizationsByServiceElement(FindOrganizationsByServiceElementRequest). Der Aufruf

    results = dvdvManager.findOrganizationsByServiceElement(requests);
 

ist weitgehend äquivalent zu

    results = new ArrayList<>(requests.size());
    for (FindOrganizationsByServiceElementRequest request : requests) {
       results.add(dvdvManager.findOrganizationsByServiceElement(request));
    }
 

Parameters:

requests - standardmäßig darf diese Liste maximal 200 Einträge haben

Throws:

DVDVException

findCertificateByFingerprint

Certificate findCertificateByFingerprint(FingerPrintRequest request)
                                  throws DVDVException

Ermittelt die Zertifikatsmetadaten des Zertifikats mit dem angegebenen Fingerprint, falls es mindestens einmal in der Datenbank hinterlegt ist.

Parameters:

request - siehe createFingerPrintRequest(String)

Returns:

Informationen aus den Binärdaten des angegebenen X.509-Zertifikats

Throws:

DVDVNoHitsException - falls es kein entsprechendes Zertifikat gibt

DVDVException

getIntermediaries

List<? extends SummaryServiceElement> getIntermediaries()
                                                 throws DVDVException

Ermittelt alle Intermediäre im DVDV.

Returns:

Liste aller Intermediäre

Throws:

DVDVException

getCategories

List<? extends OrganizationCategory> getCategories()
                                            throws DVDVException

Liefert den Baum aller im DVDV verzeichneten Kategorien. Das DVDV-Datenmodell bis wenigstens inklusive DVDV 2.7.0 lässt eine maximale Tiefe von 4 zu. Im aktuellen Datenbestand (Feb. 2023) beträgt die maximale Tiefe 2.

Returns:

top-level Knoten im Baum aller im DVDV verzeichneten Kategorien

Throws:

DVDVException

addFailoverListener

void addFailoverListener(FailoverListener listener)

Registriert den angegebenen FailoverListener, damit diese im Failover-Fall benachrichtigt wird. Auf diese Weise kann Ihr Anwendungscode auf Failover-Ereignisse reagieren, etwa für Profiling-Zwecke.

removeFailoverListener

void removeFailoverListener(FailoverListener listener)

Das Gegenstueck zu addFailoverListener(FailoverListener).