org.kapott.hbci.manager
Class HBCIHandler

java.lang.Object
  |
  +--org.kapott.hbci.manager.HBCIHandler

public final class HBCIHandler
extends java.lang.Object

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:

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
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

HBCIHandler

public HBCIHandler(java.lang.String hbciversion,
                   HBCIPassport passport)
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:
passport - das zu benutzende Passport. Dieses muss vorher mit AbstractHBCIPassport.getInstance() erzeugt worden sein
Method Detail

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.


newMsg

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 customerids siehe addJob(String,HBCIJob).

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 zu 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).


newJob

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.

Parameters:
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.
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

public HBCIJob newLowlevelJob(java.lang.String gvname)
Erzeugt ein neues Lowlevel-Job-Objekt. Für eine Beschreibung des Unterschiedes zwischen High- und Lowlevel-Definition von Jobs siehe Package org.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

addJob

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.

Parameters:
customerId - die Kunden-ID, zu deren Dialog der Auftrag hinzugefügt werden soll
job - ein Job-Objekt, welches mit newJob() oder newLowlevelJob() erzeugt und mit HBCIJob.setParam() parametrisiert wurde.

addJob

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.

Parameters:
job - der hinzuzufügende Auftrag

execute

public 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.

Returns:
ein Status-Objekt, anhand dessen der Erfolg oder das Fehlschlagen der Dialoge festgestellt werden kann.

lockKeys

public void lockKeys()

Sperren der Nutzerschlüssel. Das ist nur dann sinnvoll, wenn zwei Bedinungen erfüllt sind:

  1. Das verwendete Passport erlaubt die Sperrung der Schlüssel des Nutzers (nur RDH)
  2. 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 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.


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

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.


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 mit execute() wird diese Methode automatisch aufgerufen.


getPassport

public HBCIPassport getPassport()
Gibt das Passport zurück, welches in diesem Handle benutzt wird.

Returns:
Passport-Objekt, mit dem dieses Handle erzeugt wurde

getSupportedLowlevelGVs

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.

Returns:
Sammlung aller vom aktuellen Passport unterstützten HBCI- Geschäftsvorfallnamen (Lowlevel).

getLowlevelGVParameters

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.

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() benutzt werden können

getLowlevelResultProperties

public 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.

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

isSupported

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.

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; ansonsten false