Class HBCIHandler
- All Implemented Interfaces:
AutoCloseable
,IHandlerData
Ein Handle für genau einen HBCI-Zugang. Diese Klasse stellt das Verbindungsglied zwischen der Anwendung und dem HBCI-Kernel dar. Für jeden HBCI-Zugang, den die Anwendung benutzt, muss ein entsprechender HBCI-Handler angelegt werden. Darin sind folgende Daten zusammengefasst:
- Ein
HBCIPassport
, welches die Nutzeridentifikationsdaten sowie die Zugangsdaten zum entsprechenden HBCI-Server enthält - Die zu benutzende HBCI-Versionsnummer
- interne Daten zur Verwaltung der Dialoge bei der Kommunikation mit dem HBCI-Server
Alle Anfragen der Anwendung an den HBCI-Kernel laufen über einen solchen Handler, womit gleichzeit eindeutig festgelegt ist, welche HBCI-Verbindung diese Anfrage betrifft.
Die prinzipielle Benutzung eines Handlers sieht in etwa wiefolgt aus:
// ... HBCIPassport passport=AbstractHBCIPassport.getInstance(); HBCIHandler handle=new HBCIHandler(passport.getHBCIVersion(),passport); HBCIJob jobSaldo=handle.newJob("SaldoReq"); // nächster Auftrag ist Saldenabfrage jobSaldo.setParam("number","1234567890"); // Kontonummer für Saldenabfrage jobSaldo.addToQueue(); HBCIJob jobUeb=handle.newJob("Ueb"); jobUeb.setParam("src.number","1234567890"); jobUeb.setParam("dst.number","9876543210"); // ... jobUeb.addToQueue(); // ... HBCIExecStatus status=handle.execute(); // Auswerten von status // Auswerten der einzelnen job-Ergebnisse handle.close();
-
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionHBCIHandler
(String hbciversion, HBCIPassport passport) Anlegen eines neuen HBCI-Handler-Objektes.HBCIHandler
(String hbciversion, HBCIPassport passport, boolean lazyInit) Anlegen eines neuen HBCI-Handler-Objektes. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Deprecated.void
Deprecated.useHBCIJob.addToQueue()
insteadvoid
addJobToDialog
(String customerId, HBCIJob job) Do NOT use! UseHBCIJob.addToQueue(String)
insteadvoid
close()
Schließen des Handlers.continueThreaded
(String retData) Setzt bei Verwendung des threaded-callback-Mechanismus einen noch aktiven HBCI-Dialog fort.void
EntsprichtcreateEmptyDialog(null)
void
createEmptyDialog
(String customerId) Erzeugen eines leeren HBCI-Dialoges.execute()
Ausführen aller bisher erzeugten Aufträge.Entsprichtexecute()
, allerdings können Callbacks hier auch synchron behandelt werden.Gibt die HBCI-Versionsnummer zurück, für die der aktuelle HBCIHandler konfiguriert ist.Gibt das HBCI-Kernel-Objekt zurück, welches von diesem HBCI-Handler benutzt wird.getLowlevelJobParameterNames
(String gvname) Gibt alle Parameter zurück, die für einen Lowlevel-Job gesetzt werden können.getLowlevelJobRestrictions
(String gvname) Gibt für einen Job alle bekannten Einschränkungen zurück, die bei der Ausführung des jeweiligen Jobs zu beachten sind.getLowlevelJobResultNames
(String gvname) Gibt eine Liste mit Strings zurück, welche Bezeichnungen für die einzelnen Rückgabedaten eines Lowlevel-Jobs darstellen.Gibt das Passport zurück, welches in diesem Handle benutzt wird.Gibt die Namen aller vom aktuellen HBCI-Zugang (d.h.Führt die Abfrage von BPD und UPD aus, die normalerweise inHBCIHandler(String, HBCIPassport)
bzw.boolean
isSupported
(String jobnameHL) Überprüfen, ein bestimmter Highlevel-Job von der Bank angeboten wird.void
lockKeys()
Sperren der Nutzerschlüssel.Erzeugen eines neuen Highlevel-HBCI-Jobs.void
newKeys()
Erzeugen neuer kryptografischer Schlüssel für den Nutzer.newLowlevelJob
(String gvname) Erzeugt ein neues Lowlevel-Job-Objekt.void
newMsg()
Erzwingen einer neuen Nachricht im Dialog für die aktuelle Kunden-ID.void
Beginn einer neuen HBCI-Nachricht innerhalb eines Dialoges festlegen.refreshXPD
(int selectX) Abholen der BPD bzw.void
reset()
Zurücksetzen des Handlers auf den Ausgangszustand.void
Setzen der Nutzerschlüssel auf vorgegebene Daten.void
sync
(boolean force) Fuehrt eine Neu-Synchronisierung durch.EntsprichtverifyTAN(null)
.Key-Management: Überprüfen einer TAN (nur für PinTan-Passports!).
-
Field Details
-
REFRESH_BPD
public static final int REFRESH_BPD- See Also:
-
REFRESH_UPD
public static final int REFRESH_UPD- See Also:
-
-
Constructor Details
-
HBCIHandler
Anlegen eines neuen HBCI-Handler-Objektes. Beim Anlegen wird überprüft, ob für die angegebene HBCI-Version eine entsprechende Spezifikation verfügbar ist. Außerdem wird das übergebene Passport überprüft. Dabei werden - falls nicht vorhanden - die BPD und die UPD vom Kreditinstitut geholt. Bei Passports, die asymmetrische Verschlüsselungsverfahren benutzen (RDH), wird zusätzlich überprüft, ob alle benötigten Schlüssel vorhanden sind. Gegebenenfalls werden diese aktualisiert.- Parameters:
hbciversion
- zu benutzende HBCI-Version. gültige Werte sind:null
- es wird die HBCI-Version benutzt, die bei der letzten Verwendung dieses Passports benutzt wurde- "
201
" für HBCI 2.01 - "
210
" für HBCI 2.1 - "
220
" für HBCI 2.2 - "
plus
" für HBCI+ - "
300
" für FinTS 3.0
passport
- das zu benutzende Passport. Dieses muss vorher mitAbstractHBCIPassport.getInstance()
erzeugt worden sein
-
HBCIHandler
Anlegen eines neuen HBCI-Handler-Objektes. Beim Anlegen wird überprüft, ob für die angegebene HBCI-Version eine entsprechende Spezifikation verfügbar ist. Außerdem wird das übergebene Passport überprüft. Dabei werden - falls nicht vorhanden und falls- Parameters:
hbciversion
- zu benutzende HBCI-Version. gültige Werte sind:null
- es wird die HBCI-Version benutzt, die bei der letzten Verwendung dieses Passports benutzt wurde- "
201
" für HBCI 2.01 - "
210
" für HBCI 2.1 - "
220
" für HBCI 2.2 - "
plus
" für HBCI+ - "
300
" für FinTS 3.0
passport
- das zu benutzende Passport. Dieses muss vorher mitAbstractHBCIPassport.getInstance()
erzeugt worden seinlazyInit
- nicht auf true gesetzt ist - die BPD und die UPD vom Kreditinstitut geholt. Bei Passports, die asymmetrische Verschlüsselungsverfahren benutzen (RDH), wird zusätzlich überprüft, ob alle benötigten Schlüssel vorhanden sind. Gegebenenfalls werden diese aktualisiert.lazyInit
- auf true setzen, um den UPD nachgelagert perinitThreaded()
zu laden (zum Handling der eventuellen TAN-Abfrage)
-
-
Method Details
-
initThreaded
Führt die Abfrage von BPD und UPD aus, die normalerweise in
HBCIHandler(String, HBCIPassport)
bzw.HBCIHandler(String, HBCIPassport, boolean)
mit lazyInit=false durchgeführt wird, allerdings können Callbacks hier auch synchron behandelt werden. Bei einem Aufruf voninitThreaded()
wird der eigentliche HBCI-Dialog in einem separaten Thread geführt. Bei evtl. auftretenden Callbacks wird geprüft, ob diese synchron oder asynchron zu behandeln sind. Im asynchronen Fall wird der Callback wie gewohnt durch Aufruf dercallback()
-Methode des registrierten "normalen" Callback-Objektes behandelt. Soll ein Callback synchron behandelt werden, terminiert diese Methode.Das zurückgegebene Status-Objekt zeigt an, ob diese Methode terminierte, weil ein synchron zu behandelnder Callback aufgetreten ist oder weil die Ausführung aller HBCI-Dialoge abgeschlossen ist.
Mehr Informationen dazu in der Datei
README.ThreadedCallbacks
. -
sync
public void sync(boolean force) Description copied from interface:IHandlerData
Fuehrt eine Neu-Synchronisierung durch.- Specified by:
sync
in interfaceIHandlerData
- Parameters:
force
- true, wenn die Neu-Synchronisierung forciert werden soll.- See Also:
-
close
public void close()Schließen des Handlers. Diese Methode sollte immer dann aufgerufen werden, wenn die entsprechende HBCI-Verbindung nicht mehr benötigt wird.
Beim Schließen des Handlers wird das Passport ebenfalls geschlossen. Sowohl das Passport-Objekt als auch das Handler-Objekt können anschließend nicht mehr benutzt werden.
- Specified by:
close
in interfaceAutoCloseable
-
newMsg
Beginn einer neuen HBCI-Nachricht innerhalb eines Dialoges festlegen. Normalerweise muss diese Methode niemals manuell aufgerufen zu werden!
Mit dieser Methode wird der HBCI-Kernel gezwungen, eine neue HBCI-Nachricht anzulegen, in die alle nachfolgenden Geschäftsvorfälle aufgenommen werden. Die
customerId
legt fest, für welchen Dialog die neue Nachricht erzeugt werden soll. Für eine genauere Beschreibung von Dialogen undcustomerid
s sieheHBCIJob.addToQueue(String)
.- Parameters:
customerId
- die Kunden-ID, für deren Dialog eine neue Nachricht begonnen werden soll
-
newMsg
public void newMsg()Erzwingen einer neuen Nachricht im Dialog für die aktuelle Kunden-ID. Diese Methode arbeitet analog zunewMsg(String)
, nur dass hier diecustomerid
mit der Kunden-ID vorbelegt ist, wie sie im aktuellen Passport gespeichert ist. Siehe dazu auchHBCIJob.addToQueue(String)
. -
newJob
Erzeugen eines neuen Highlevel-HBCI-Jobs. Diese Methode gibt ein neues Job-Objekt zurück. Dieses Objekt wird allerdings noch nicht zum HBCI-Dialog hinzugefügt. Statt dessen müssen erst alle zur Beschreibung des jeweiligen Jobs benötigten Parameter mit
HBCIJob.setParam(String,String)
gesetzt werden. Anschließend kann der Job mitHBCIJob.addToQueue(String)
zum HBCI-Dialog hinzugefügt werden.Eine Beschreibung aller unterstützten Geschäftsvorfälle befindet sich im Package
org.kapott.hbci.GV
.- Parameters:
jobname
- der Name des Jobs, der erzeugt werden soll. Gültige Job-Namen sowie die benötigten Parameter sind in der Beschreibung des Packagesorg.kapott.hbci.GV
zu finden.- Returns:
- ein Job-Objekt, für das die entsprechenden Job-Parameter gesetzt werden müssen und welches anschließend zum HBCI-Dialog hinzugefügt werden kann.
-
newLowlevelJob
Erzeugt ein neues Lowlevel-Job-Objekt. Für eine Beschreibung des Unterschiedes zwischen High- und Lowlevel-Definition von Jobs siehe Packageorg.kapott.hbci.GV
.- Parameters:
gvname
- der Lowlevel-Name des zu erzeugenden Jobs- Returns:
- ein neues Job-Objekt, für das erst alle benötigten Lowlevel-Parameter gesetzt werden müssen und das anschließend zum HBCI-Dialog hinzugefügt werden kann
-
addJobToDialog
Do NOT use! UseHBCIJob.addToQueue(String)
instead -
addJob
Deprecated.useHBCIJob.addToQueue(String)
instead -
addJob
Deprecated.useHBCIJob.addToQueue()
instead -
createEmptyDialog
Erzeugen eines leeren HBCI-Dialoges.Im Normalfall werden HBCI-Dialoge automatisch erzeugt, wenn Geschäftsvorfälle mit der Methode
HBCIJob.addToQueue(String)
zur Liste der auszuführenden Jobs hinzugefügt werden.createEmptyDialog()
kann explizit aufgerufen werden, wenn ein Dialog erzeugt werden soll, der keine Geschäftsvorfälle enthält, also nur aus Dialog-Initialisierung und Dialog-Ende besteht.Ist die angegebene
customerId=null
, so wird der Dialog für die aktuell im Passport gespeicherte Customer-ID erzeugt.- Parameters:
customerId
- die Kunden-ID, für die der Dialog erzeugt werden soll.
-
createEmptyDialog
public void createEmptyDialog()EntsprichtcreateEmptyDialog(null)
-
execute
Ausführen aller bisher erzeugten Aufträge. Diese Methode veranlasst den HBCI-Kernel, die Aufträge, die durch die Aufrufe der Methode
HBCIJob.addToQueue(String)
zur Auftragsliste hinzugefügt wurden, auszuführen.Beim Hinzufügen der Aufträge zur Auftragsqueue (mit
HBCIJob.addToQueue()
oderHBCIJob.addToQueue(String)
) wird implizit oder explizit eine Kunden-ID mit angegeben, unter der der jeweilige Auftrag ausgeführt werden soll. In den meisten Fällen hat ein Benutzer nur eine einzige Kunden-ID, so dass die Angabe entfallen kann, es wird dann automatisch die richtige verwendet. Werden aber mehrere Aufträge viaaddToQueue()
zur Auftragsqueue hinzugefügt, und sind diese Aufträge unter teilweise unterschiedlichen Kunden-IDs auszuführen, dann wird für jede verwendete Kunden-ID ein separater HBCI-Dialog erzeugt und ausgeführt. Das äußert sich dann also darin, dass beim Aufrufen der Methodeexecute()
u.U. mehrere HBCI-Dialog mit der Bank geführt werden, und zwar je einer für jede Kunden-ID, für die wenigstens ein Auftrag existiert. Innerhalb eines HBCI-Dialoges werden alle auszuführenden Aufträge in möglichst wenige HBCI-Nachrichten verpackt.Dazu wird eine Reihe von HBCI-Nachrichten mit dem HBCI-Server der Bank ausgetauscht. Die Menge der dazu verwendeten HBCI-Nachrichten kann dabei nur bedingt beeinflusst werden, da HBCI4Java u.U. selbstständig Nachrichten erzeugt, u.a. wenn ein Auftrag nicht mehr mit in eine Nachricht aufgenommen werden konnte, oder wenn eine Antwortnachricht nicht alle verfügbaren Daten zurückgegeben hat, so dass HBCI4Java mit einer oder mehreren weiteren Nachrichten den Rest der Daten abholt.
Nach dem Nachrichtenaustausch wird ein Status-Objekt zurückgegeben, welches zur Auswertung aller ausgeführten Dialoge benutzt werden kann.
- Returns:
- ein Status-Objekt, anhand dessen der Erfolg oder das Fehlschlagen der Dialoge festgestellt werden kann.
-
executeThreaded
Entspricht
execute()
, allerdings können Callbacks hier auch synchron behandelt werden. Bei einem Aufruf vonexecuteThreaded()
anstelle vonexecute()
wird der eigentliche HBCI-Dialog in einem separaten Thread geführt. Bei evtl. auftretenden Callbacks wird geprüft, ob diese synchron oder asynchron zu behandeln sind. Im asynchronen Fall wird der Callback wie gewohnt durch Aufruf dercallback()
-Methode des registrierten "normalen" Callback-Objektes behandelt. Soll ein Callback synchron behandelt werden, terminiert diese Methode.Das zurückgegebene Status-Objekt zeigt an, ob diese Methode terminierte, weil ein synchron zu behandelnder Callback aufgetreten ist oder weil die Ausführung aller HBCI-Dialoge abgeschlossen ist.
Mehr Informationen dazu in der Datei
README.ThreadedCallbacks
. -
continueThreaded
Setzt bei Verwendung des threaded-callback-Mechanismus einen noch aktiven HBCI-Dialog fort. Trat bei der Ausführung eines HBCI-Dialoges via
executeThreaded()
ein synchroner Callback auf, so dassexecuteThreaded()
terminierte und der Rückgabewert anzeigte, dass Callback-Daten benötigt werden (HBCIExecThreadedStatus.isCallback()
==true
), dann müssen die benötigten Callback-Daten mitcontinueThreaded(String)
an den HBCI-Kernel übergeben werden.Das führt dazu, dass der HBCI-Kernel die übergebenen Callback-Daten an den wartenden HBCI-Thread übergibt (der immer noch mit der Ausführung des HBCI-Dialoges beschäftigt ist und auf Daten von der Anwendung wartet).
Der Rückgabewert von
continueThreaded(String)
ist wieder einHBCIExecThreadedStatus
-Objekt (analog zuexecuteThreaded()
), welches anzeigt, ob weitere Callback- Daten benötigt werden oder ob der HBCI-Dialog nun beendet ist. Falls weitere Callback-Daten benötigt werden, sind diese wiederum viacontinueThreaded(String)
an den HBCI-Kernel zu übergeben, und zwar so lange, bis der HBCI-Dialog tatsächlich beendet ist.Mehr Informationen zu threaded callbacks in der Datei
README.ThreadedCallbacks
. -
lockKeys
public void lockKeys()Sperren der Nutzerschlüssel. Das ist nur dann sinnvoll, wenn zwei Bedinungen erfüllt sind:
- Das verwendete Passport erlaubt die Sperrung der Schlüssel des Nutzers (nur RDH)
- Im verwendeten Passport sind auch tatsächlich bereits Nutzerschlüssel hinterlegt.
Ist mindestens eine der beiden Bedingungen nicht erfüllt, so wird diese Methode mit einer Exception abgebrochen.
Nach dem erfolgreichen Aufruf dieser Methode muss dieses HBCIHandler-Objekt mit
close()
geschlossen werden. Anschließend muss mit dem gleichen Passport-Objekt ein neues HBCIHandler-Objekt angelegt werden, damit das Passport neu initialisiert wird. Bei dieser Neu-Initialisierung werden neue Nutzerschlüssel für das Passport generiert.// ... hbciHandle.lockKeys(); hbciHandle.close(); hbciHandle=new HBCIHandle(hbciversion,passport); // ...
Um die Nutzerschlüssel eines Passport nur zu ändern, kann die MethodesetKeys(java.security.KeyPair,java.security.KeyPair)
odernewKeys()
aufgerufen werden.Ab Version 2.4.0 von HBCI4Java muss der HBCIHandler nach dem Schlüsselsperren nicht mehr geschlossen werden. Statt dessen können direkt nach der Schlüsselsperrung neue Schlüssel erzeugt oder manuell gesetzt werden (mit den Methoden
setKeys(java.security.KeyPair,java.security.KeyPair)
bzw.newKeys()
.In jedem Fall muss für die neuen Schlüssel, die nach einer Schlüsselsperrung erzeugt werden, ein neuer INI-Brief generiert und an die Bank versandt werden.
-
newKeys
public void newKeys()Erzeugen neuer kryptografischer Schlüssel für den Nutzer. Mit dieser Methode wird für den Nutzer sowohl ein neues Signier- als auch ein neues Chiffrierschlüsselpaar erzeugt. Die neuen Schlüsseldaten werden anschließend automatisch an die Bank übermittelt. Sofern diese Aktion erfolgreich verläuft, werden die neuen Schlüssel in der Passport-Datei (Schlüsseldatei) gespeichert.
ACHTUNG! Vor dieser Aktion sollte unbedingt ein Backup der aktuellen Schlüsseldatei durchgeführt werden. Bei ungünstigen Konstellationen von Fehlermeldungen seitens des Kreditinstitutes kann es nämlich passieren, dass die neuen Schlüssel trotz eingegangener Fehlermeldung gespeichert werden, dann wären aber die alten (noch gültigen) Schlüssel überschrieben.
ACHTUNG! In noch ungünstigeren Fällen kann es auch vorkommen, dass neue Schlüssel generiert und erfolgreich an die Bank übermittelt werden, die neuen Schlüssel aber nicht in der Schlüsseldatei gespeichert werden. Das ist insofern der ungünstigste Fall, da die Bank dann schon die neuen Schlüssel kennt, in der Passport-Datei aber noch die alten Schlüssel enthalten sind und die soeben generierten neuen Schlüssel "aus Versehen" weggeworfen wurden.
-
setKeys
Setzen der Nutzerschlüssel auf vorgegebene Daten. Mit dieser Methode wird für den Nutzer sowohl ein neues Signier- als auch ein neues Chiffrierschlüsselpaar gesetzt. Die neuen Schlüsseldaten werden anschließend automatisch an die Bank übermittelt. Sofern diese Aktion erfolgreich verläuft, werden die neuen Schlüssel in der Passport-Datei (Schlüsseldatei) gespeichert.
ACHTUNG! Vor dieser Aktion sollte unbedingt ein Backup der aktuellen Schlüsseldatei durchgeführt werden. Bei ungünstigen Konstellationen von Fehlermeldungen seitens des Kreditinstitutes kann es nämlich passieren, dass die neuen Schlüssel trotz eingegangener Fehlermeldung gespeichert werden, dann wären aber die alten (noch gültigen) Schlüssel überschrieben.
-
verifyTAN
Key-Management: Überprüfen einer TAN (nur für PinTan-Passports!). Durch den Aufruf dieser Methode wird ein "leerer" HBCI-Dialog (also ein HBCI-Dialog, der nur aus Dialog-Initialisierung und Dialog-Ende besteht) gestartet. Im Verlauf dieses Dialoges wird über den Callback-Mechanismus nach einer TAN gefragt. Diese TAN wird serverseitig auf Gültigkeit überprüft, die Status-Information im Rückgabewert dieser Methode enthalten entsprechende Infos über das Ergebnis dieser Überprüfung.- Parameters:
customerId
- Kunden-ID, für die der Dialog ausgeführt werden soll (null
für aktuelle Kunden-ID)- Returns:
- ein Status-Objekt, anhand dessen der Erfolg oder das Fehlschlagen der TAN-Überprüfung festgestellt werden kann.
-
verifyTAN
EntsprichtverifyTAN(null)
. -
reset
public void reset()Zurücksetzen des Handlers auf den Ausgangszustand. Diese Methode kann aufgerufen werden, wenn alle bisher hinzugefügten Nachrichten und Aufträge wieder entfernt werden sollen. Nach dem Ausführen eines Dialoges mitexecute()
wird diese Methode automatisch aufgerufen. -
getPassport
Gibt das Passport zurück, welches in diesem Handle benutzt wird.- Specified by:
getPassport
in interfaceIHandlerData
- Returns:
- Passport-Objekt, mit dem dieses Handle erzeugt wurde
-
getKernel
Gibt das HBCI-Kernel-Objekt zurück, welches von diesem HBCI-Handler benutzt wird. Das HBCI-Kernel-Objekt kann u.a. benutzt werden, um alle für die aktuellen HBCI-Version (siehegetHBCIVersion()
) implementierten Geschäftsvorfälle abzufragen.- Returns:
- HBCI-Kernel-Objekt, mit dem der HBCI-Handler arbeitet
-
getMsgGen
- Specified by:
getMsgGen
in interfaceIHandlerData
-
getHBCIVersion
Gibt die HBCI-Versionsnummer zurück, für die der aktuelle HBCIHandler konfiguriert ist.- Returns:
- HBCI-Versionsnummer, mit welcher dieses Handler-Objekt arbeitet
-
getSupportedLowlevelJobs
Gibt die Namen aller vom aktuellen HBCI-Zugang (d.h. Passport) unterstützten Lowlevel-Jobs zurück. Alle hier zurückgegebenen Job-Namen können als Argument beim Aufruf der Methode
newLowlevelJob(String)
benutzt werden.In dem zurückgegebenen Properties-Objekt enthält jeder Eintrag als Key den Lowlevel-Job-Namen; als Value wird die Versionsnummer des jeweiligen Geschäftsvorfalls angegeben, die von HBCI4Java mit dem aktuellen Passport und der aktuell eingestellten HBCI-Version benutzt werden wird.
(Prinzipiell unterstützt HBCI4Java für jeden Geschäftsvorfall mehrere GV-Versionen. Auch eine Bank bietet i.d.R. für jeden GV mehrere Versionen an. Wird mit HBCI4Java ein HBCI-Job erzeugt, so verwendet HBCI4Java immer automatisch die höchste von der Bank unterstützte GV-Versionsnummer. Diese Information ist für den Anwendungsentwickler kaum von Bedeutung und dient hauptsächlich zu Debugging-Zwecken.)
Zum Unterschied zwischen High- und Lowlevel-Jobs siehe die Beschreibung im Package
org.kapott.hbci.GV
.- Returns:
- Sammlung aller vom aktuellen Passport unterstützten HBCI- Geschäftsvorfallnamen (Lowlevel) mit der jeweils von HBCI4Java verwendeten GV-Versionsnummer.
-
getLowlevelJobParameterNames
Gibt alle Parameter zurück, die für einen Lowlevel-Job gesetzt werden können. Wird ein Job mit
newLowlevelJob(String)
erzeugt, so kann der gleichegvname
als Argument dieser Methode verwendet werden, um eine Liste aller Parameter zu erhalten, die für diesen Job durch Aufrufe der MethodeHBCIJob.setParam(String,String)
gesetzt werden können bzw. müssen.Aus der zurückgegebenen Liste ist nicht ersichtlich, ob ein bestimmter Parameter optional ist oder gesetzt werden muss. Das kann aber durch Benutzen des Tools
ShowLowlevelGVs
ermittelt werden.Jeder Eintrag der zurückgegebenen Liste enthält einen String, welcher als erster Parameter für den Aufruf von
HBCIJob.setParam()
benutzt werden kann - vorausgesetzt, der entsprechende Job wurde mitnewLowlevelJob(String)
erzeugt.Diese Methode verwendet intern die Methode
HBCIKernel.getLowlevelJobParameterNames(String, String)
. Unterschied ist, dass diese Methode zum einen überprüft, ob der angegebene Lowlevel-Job überhaupt vom aktuellen Passport unterstützt wird. Außerdem wird automatisch die richtige Versionsnummer anHBCIKernel.getLowlevelJobParameterNames(String, String)
übergeben (nämlich die Versionsnummer, die HBCI4Java auch beim Anlegen eines Jobs vianewLowlevelJob(String)
verwenden wird).Zur Beschreibung von High- und Lowlevel-Jobs siehe auch die Dokumentation im Package
org.kapott.hbci.GV
.- Parameters:
gvname
- der Lowlevel-Jobname, für den eine Liste der Job-Parameter ermittelt werden soll- Returns:
- eine Liste aller Parameter-Bezeichnungen, die in der Methode
HBCIJob.setParam(String,String)
benutzt werden können
-
getLowlevelJobResultNames
Gibt eine Liste mit Strings zurück, welche Bezeichnungen für die einzelnen Rückgabedaten eines Lowlevel-Jobs darstellen. Jedem
HBCIJob
ist ein Result-Objekt zugeordnet, welches die Rückgabedaten und Statusinformationen zu dem jeweiligen Job enthält (kann mitHBCIJob.getJobResult()
ermittelt werden). Bei den meisten Highlevel-Jobs handelt es sich dabei um bereits aufbereitete Daten (Kontoauszüge werden z.B. nicht in dem ursprünglichen SWIFT-Format zurückgegeben, sondern bereits als fertig geparste Buchungseinträge).Bei Lowlevel-Jobs gibt es diese Aufbereitung der Daten nicht. Statt dessen müssen die Daten manuell aus der Antwortnachricht extrahiert und interpretiert werden. Die einzelnen Datenelemente der Antwortnachricht werden in einem Properties-Objekt bereitgestellt (
HBCIJobResult.getResultData()
). Jeder Eintrag darin enthält den Namen und den Wert eines Datenelementes aus der Antwortnachricht.Die Methode
getLowlevelJobResultNames()
gibt nun alle gültigen Namen zurück, für welche in dem Result-Objekt Daten gespeichert sein können. Ob für ein Datenelement tatsächlich ein Wert in dem Result-Objekt existiert, wird damit nicht bestimmt, da einzelne Datenelemente optional sind.Diese Methode verwendet intern die Methode
HBCIKernel.getLowlevelJobResultNames(String, String)
. Unterschied ist, dass diese Methode zum einen überprüft, ob der angegebene Lowlevel-Job überhaupt vom aktuellen Passport unterstützt wird. Außerdem wird automatisch die richtige Versionsnummer anHBCIKernel.getLowlevelJobResultNames(String, String)
übergeben (nämlich die Versionsnummer, die HBCI4Java auch beim Anlegen eines Jobs vianewLowlevelJob(String)
verwenden wird).Mit dem Tool
ShowLowlevelGVRs
kann offline eine Liste aller Job-Result-Datenelemente erzeugt werden.Zur Beschreibung von High- und Lowlevel-Jobs siehe auch die Dokumentation im Package
org.kapott.hbci.GV
.- Parameters:
gvname
- Lowlevelname des Geschäftsvorfalls, für den die Namen der Rückgabedaten benötigt werden.- Returns:
- Liste aller möglichen Property-Keys, für die im Result-Objekt eines Lowlevel-Jobs Werte vorhanden sein könnten
-
getLowlevelJobRestrictions
Gibt für einen Job alle bekannten Einschränkungen zurück, die bei der Ausführung des jeweiligen Jobs zu beachten sind. Diese Daten werden aus den Bankparameterdaten des aktuellen Passports extrahiert. Sie können von einer HBCI-Anwendung benutzt werden, um gleich entsprechende Restriktionen bei der Eingabe von Geschäftsvorfalldaten zu erzwingen (z.B. die maximale Anzahl von Verwendungszweckzeilen, ob das Ändern von terminierten Überweisungen erlaubt ist usw.).
Die einzelnen Einträge des zurückgegebenen Properties-Objektes enthalten als Key die Bezeichnung einer Restriktion (z.B. "
maxusage
"), als Value wird der entsprechende Wert eingestellt. Die Bedeutung der einzelnen Restriktionen ist zur Zeit nur der HBCI-Spezifikation zu entnehmen. In späteren Programmversionen werden entsprechende Dokumentationen zur internen HBCI-Beschreibung hinzugefügt, so dass dafür eine Abfrageschnittstelle implementiert werden kann.I.d.R. werden mehrere Versionen eines Geschäftsvorfalles von der Bank angeboten. Diese Methode ermittelt automatisch die "richtige" Versionsnummer für die Ermittlung der GV-Restriktionen aus den BPD (und zwar die selbe, die HBCI4Java beim Erzeugen eines Jobs benutzt).
Siehe dazu auch
HBCIJob.getJobRestrictions()
.- Parameters:
gvname
- Lowlevel-Name des Geschäftsvorfalles, für den die Restriktionen ermittelt werden sollen- Returns:
- Properties-Objekt mit den einzelnen Restriktionen
-
isSupported
Überprüfen, ein bestimmter Highlevel-Job von der Bank angeboten wird. Diese Methode kann benutzt werden, um vor dem Erzeugen eines
HBCIJob
-Objektes zu überprüfen, ob der gewünschte Job überhaupt von der Bank angeboten wird. Ist das nicht der Fall, so würde der Aufruf vonnewJob(String)
zu einer Exception führen.Eine Liste aller zur Zeit verfügbaren Highlevel-Jobnamen ist in der Paketbeschreibung des Packages
org.kapott.hbci.GV
zu finden. Wird hier nach einem Highlevel-Jobnamen gefragt, der nicht in dieser Liste enthalten ist, so wird eine Exception geworfen.Mit dieser Methode können nur Highlevel-Jobs überprüft werden. Zum Überprüfen, ob ein bestimmter Lowlevel-Job unterstützt wird, ist die Methode
getSupportedLowlevelJobs()
zu verwenden.- Parameters:
jobnameHL
- der Highlevel-Name des Jobs, dessen Unterstützung überprüft werden soll- Returns:
true
, wenn dieser Job von der Bank unterstützt wird und mit HBCI4Java verwendet werden kann; ansonstenfalse
-
refreshXPD
Abholen der BPD bzw. UPD erzwingen. Beim Aufruf dieser Methode wird automatisch ein HBCI-Dialog ausgeführt, der je nach Wert vonselectX
die BPD und/oder UPD erneut abholt. Alle bis zu diesem Zeitpunkt erzeugten (HBCIJob.addToQueue()
) und noch nicht ausgeführten Jobs werden dabei wieder aus der Job-Schlange entfernt.- Parameters:
selectX
- kann aus einer Kombination (Addition) der WerteREFRESH_BPD
undREFRESH_UPD
bestehen- Returns:
- Status-Objekt, welches Informationen über den ausgeführten HBCI-Dialog enthält
-
HBCIJob.addToQueue(String)
instead