|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--org.kapott.hbci.manager.HBCIHandler
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:
Passport
, welches die Nutzeridentifikationsdaten
sowie die Zugangsdaten zum entsprechenden HBCI-Server enthältAlle 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 handle.addJob(jobSaldo); HBCIJob jobUeb=handle.newJob("Ueb"); jobUeb.setParam("src.number","1234567890"); jobUeb.setParam("dst.number","9876543210"); // ... handle.addJob(jobUeb); // ... HBCIExecStatus status=handle.execute(); // Auswerten von status // Auswerten der einzelnen job-Ergebnisse handle.close();
Constructor Summary | |
HBCIHandler(java.lang.String hbciversion,
HBCIPassport passport)
Anlegen eines neuen HBCI-Handler-Objektes. |
Method Summary | |
void |
addJob(HBCIJob job)
Hinzufügen eines Jobs zu einem Dialog. |
void |
addJob(java.lang.String customerId,
HBCIJob job)
Hinzufügen eines Jobs zu einem Dialog. |
void |
close()
Schließen des Handlers. |
HBCIExecStatus |
execute()
Ausführen aller bisher erzeugten Aufträge. |
java.util.ArrayList |
getLowlevelGVParameters(java.lang.String gvname)
Gibt alle Parameter zurück, die für einen Lowlevel-Job gesetzt werden können. |
java.util.ArrayList |
getLowlevelResultProperties(java.lang.String gvname)
Gibt eine Liste mit Strings zurück, welche Bezeichnungen für die einzelnen Rückgabedaten eines Lowlevel-Jobs darstellen. |
HBCIPassport |
getPassport()
Gibt das Passport zurück, welches in diesem Handle benutzt wird. |
java.util.Properties |
getSupportedLowlevelGVs()
Gibt die Namen aller unterstützten Lowlevel-Jobs zurück. |
boolean |
isSupported(java.lang.String jobnameHL)
Überprüfen, ein bestimmter Highlevel-Job von der Bank angeboten wird. |
void |
lockKeys()
Sperren der Nutzerschlüssel. |
HBCIJob |
newJob(java.lang.String jobname)
Erzeugen eines neuen Highlevel-HBCI-Jobs. |
void |
newKeys()
Erzeugen neuer kryptografischer Schlüssel für den Nutzer. |
HBCIJob |
newLowlevelJob(java.lang.String gvname)
Erzeugt ein neues Lowlevel-Job-Objekt. |
void |
newMsg()
Erzwingen einer neuen Nachricht im Dialog für die aktuelle Kunden-ID. |
void |
newMsg(java.lang.String customerId)
Beginn einer neuen HBCI-Nachricht innerhalb eines Dialoges festlegen. |
void |
reset()
Zurücksetzen des Handlers auf den Ausgangszustand. |
void |
setKeys(java.security.KeyPair sigKey,
java.security.KeyPair encKey)
Setzen der Nutzerschlüssel auf vorgegebene Daten. |
Constructor Detail |
public HBCIHandler(java.lang.String hbciversion, HBCIPassport passport)
hbciversion
- zu benutzende HBCI-Version. gültige Werte sind:
null
- es wird die HBCI-Version benutzt, die bei der
letzten Verwendung dieses Passports benutzt wurde201
" für HBCI 2.01210
" für HBCI 2.1220
" für HBCI 2.2plus
" für HBCI+300
" für FinTS 3.0passport
- das zu benutzende Passport. Dieses muss vorher mit
AbstractHBCIPassport.getInstance()
erzeugt worden seinMethod Detail |
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.
public void newMsg(java.lang.String customerId)
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 und
customerid
s siehe addJob(String,HBCIJob)
.
customerId
- die Kunden-ID, für deren Dialog eine neue Nachricht
begonnen werden sollpublic void newMsg()
newMsg(String)
, nur dass hier
die customerid
mit der Kunden-ID vorbelegt ist, wie sie
im aktuellen Passport gespeichert ist. Siehe dazu auch
addJob(String,org.kapott.hbci.GV.HBCIJob)
.
public HBCIJob newJob(java.lang.String jobname)
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()
gesetzt werden.
Anschließend kann der Job mit addJob()
zum
HBCI-Dialog hinzugefügt werden.
Eine Beschreibung aller unterstützten Geschäftsvorfälle befindet sich im Package org.kapott.hbci.GV.
jobname
- der Name des Jobs, der erzeugt werden soll. Gültige
Job-Namen sowie die benötigten Parameter sind in der Beschreibung des Packages
org.kapott.hbci.GV zu finden.
public HBCIJob newLowlevelJob(java.lang.String gvname)
gvname
- der Lowlevel-Name des zu erzeugenden Jobs
public void addJob(java.lang.String customerId, HBCIJob job)
Hinzufügen eines Jobs zu einem Dialog. Nachdem alle
Jobparameter mit
HBCIJob.setParam()
gesetzt wurden, kann der komplett spezifizierte Job mit dieser Methode
zur Auftragsliste eines Dialoges hinzugefügt werden.
Die customerId
gibt an, unter welcher Kunden-ID dieser Job
ausgeführt werden soll. Existiert für eine HBCI-Nutzerkennung (ein Passport)
nur genau eine Kunden-ID (wie das i.d.R. der Fall ist), so kann der
customerId
-Parameter weggelassen werden - HBCI4Java
verwendet dann automatisch die richtige Kunden-ID (als Kunden-ID wird in diesem
Fall der Wert von HBCIPassport.getCustomerId()
verwendet). Gibt es aber mehrere
gültige Kunden-IDs für einen HBCI-Zugang, so muss die Kunden-ID,
die für diesen Job verwendet werden soll, mit angegeben werden.
Jeder Auftrag (=Job) ist i.d.R. an ein bestimmtes Konto des Auftraggebers gebunden (Überweisung: das Belastungskonto; Saldenabfrage: das abzufragende Konto usw.). Als Kunden-ID für einen Auftrag muss die Kunden-ID angegeben werden, die für dieses Konto verfügungsberechtigt ist.
I.d.R. liefert eine Bank Informationen über alle Konten, auf die
via HBCI zugegriffen werden kann. Ist das der Fall, so kann die Menge
dieser Konten mit HBCIPassport.getAccounts()
ermittelt werden.
In jedem zurückgemeldeten Konto
-Objekt
ist im Feld customerid
vermerkt, welche Kunden-ID für
dieses Konto verfügungsberechtigt ist. Diese Kunden-ID müsste dann also
beim Hinzufügen eines Auftrages angegeben werden, welcher das jeweilige
Konto betrifft.
Liefert eine Bank diese Informationen nicht, so hat die Anwendung selbst eine Kontenverwaltung zu implementieren, bei der jedem Nutzerkonto eine zu verwendende Kunden-ID zugeordnet ist.
Ein HBCI-Dialog kann aus beliebig vielen HBCI-Nachrichten bestehen. HBCI4Java versucht zunächst,
alle Jobs in einer einzigen Nachricht unterzubringen. Kann ein Job nicht mehr zur aktuellen
Nachricht hinzugefügt werden (weil sonst bestimmte vorgegebene Bedingungen nicht eingehalten
werden), so legt HBCI4Java automatisch eine neue Nachricht an, zu der der Job schließlich
hinzugefügt wird. Beim Ausführen des HBCI-Dialoges (siehe execute()
) werden dann
natürlich alle erzeugten Nachrichten zum HBCI-Server gesandt.
Der HBCI-Kernel bestimmt also automatisch, ob ein Auftrag noch mit in die aktuelle Nachricht
aufgenommen werden kann, oder ob eine separate Nachricht erzeugt werden muss. Der manuelle
Aufruf von newMsg()
ist deshalb im Prinzip niemals notwendig, es sei denn,
es soll aus anderen Gründen eine neue Nachricht begonnen werden.
customerId
- die Kunden-ID, zu deren Dialog der Auftrag hinzugefügt werden solljob
- ein Job-Objekt, welches mit newJob()
oder
newLowlevelJob()
erzeugt und mit
HBCIJob.setParam()
parametrisiert wurde.public void addJob(HBCIJob job)
Hinzufügen eines Jobs zu einem Dialog. Diese Methode arbeitet analog zu
addJob(String,org.kapott.hbci.GV.HBCIJob)
, nur dass hier
die customerid
mit der Kunden-ID vorbelegt ist, wie sie
im aktuellen Passport gespeichert ist.
job
- der hinzuzufügende Auftragpublic HBCIExecStatus execute()
Ausführen aller bisher erzeugten Aufträge. Diese Methode veranlasst den HBCI-Kernel,
die Aufträge, die durch die Aufrufe der Methode
addJob()
zur Auftragsliste hinzugefügt wurden, auszuführen.
Beim Hinzufügen der Aufträge zur Auftragsqueue (mit addJob(org.kapott.hbci.GV.HBCIJob)
oder addJob(String,org.kapott.hbci.GV.HBCIJob)
) 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 via addJob()
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 Methode execute()
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.
public void lockKeys()
Sperren der Nutzerschlüssel. Das ist nur dann sinnvoll, wenn zwei Bedinungen erfüllt sind:
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 Methode
setKeys()
oder newKeys()
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()
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.
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.
public void setKeys(java.security.KeyPair sigKey, java.security.KeyPair encKey)
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.
public void reset()
execute()
wird diese Methode
automatisch aufgerufen.
public HBCIPassport getPassport()
public java.util.Properties getSupportedLowlevelGVs()
Gibt die Namen aller unterstützten Lowlevel-Jobs zurück. Alle hier
zurückgegebenen Job-Namen können als Argument beim Aufruf der Methode
newLowlevelJob()
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 benutzen wird. Diese Information ist für den Anwendungsentwickler kaum von Bedeutung und dient mehr zu Debugging-Zwecken.
Zum Unterschied zwischen High- und Lowlevel-Jobs siehe die Beschreibung im Package org.kapott.hbci.GV.
public java.util.ArrayList getLowlevelGVParameters(java.lang.String gvname)
Gibt alle Parameter zurück, die für einen Lowlevel-Job gesetzt
werden können. Wird ein Job mit newLowlevelJob(gvname)
erzeugt, so kann der gleiche gvname
als Argument dieser
Methode verwendet werden, um eine Liste aller Parameter zu erhalten, die
für diesen Job durch Aufrufe der Methode
HBCIJob.setParam()
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.
Zur Beschreibung von High- und Lowlevel-Jobs siehe auch die Dokumentation im Package org.kapott.hbci.GV.
gvname
- der Lowlevel-Jobname, für den eine Liste der Job-Parameter
ermittelt werden soll
HBCIJob.setParam()
benutzt werden könnenpublic java.util.ArrayList getLowlevelResultProperties(java.lang.String gvname)
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 mit HBCIJob.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 getLowlevelResultProperties()
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
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.
gvname
- Lowlevelname des Geschäftsvorfalls, für den die Namen der Rückgabedaten benötigt werden.
public boolean isSupported(java.lang.String jobnameHL)
Ü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 von
HBCIHandler.newJob(jobname)
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
HBCIHandler.getSupportedLowlevelGVs()
zu verwenden.
jobnameHL
- der Highlevel-Name des Jobs, dessen Unterstützung überprüft werden soll
true
, wenn dieser Job von der Bank unterstützt wird und
mit HBCI4Java verwendet werden kann; ansonsten false
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |