org.kapott.hbci.manager

Class HBCIHandler

java.lang.Object

org.kapott.hbci.manager.HBCIHandler

All Implemented Interfaces:

IHandlerData

public final class HBCIHandler
extends Object
implements 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();
 

Constructor Summary

Constructors

Constructor and Description
HBCIHandler(HBCIDialog hbciDialog) Anlegen eines neuen HBCI-Handler-Objektes.

Method Summary

Modifier and Type	Method and Description
void	addJobToDialog(HBCIJob job)
void	callback(int closeConnection, String callb_close_conn, int typeNone, StringBuffer stringBuffer)
HBCIExecStatus	execute(boolean closeDialog) Ausführen aller bisher erzeugten Aufträge.
HBCIDialog	getDialog()
org.kapott.hbci.manager.HBCIKernel	getKernel() Gibt das HBCI-Kernel-Objekt zurück, welches von diesem HBCI-Handler benutzt wird.
List<String>	getLowlevelJobParameterNames(String gvname) Gibt alle Parameter zurück, die für einen Lowlevel-Job gesetzt werden können.
List<String>	getLowlevelJobResultNames(String gvname) Gibt eine Liste mit Strings zurück, welche Bezeichnungen für die einzelnen Rückgabedaten eines Lowlevel-Jobs darstellen.
MsgGen	getMsgGen()
HBCIPassportInternal	getPassport() Gibt das Passport zurück, welches in diesem Handle benutzt wird.
Object	getProperty(String key)
HBCIJob	newLowlevelJob(String gvname) Erzeugt ein neues Lowlevel-Job-Objekt.
void	status(int statusMsgSend, Object o)
void	updateMetaInfo() Ruft die SEPA-Infos der Konten sowie die TAN-Medienbezeichnungen ab.
void	updateSEPAInfo() Deprecated. Bitte updateMetaInfo verwenden. Das aktualisiert auch die TAN-Medien.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HBCIHandler

public HBCIHandler(HBCIDialog hbciDialog)

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.

Method Detail

getProperty

public Object getProperty(String key)

updateMetaInfo

public void updateMetaInfo()

Ruft die SEPA-Infos der Konten sowie die TAN-Medienbezeichnungen ab. unterstuetzt wird und speichert diese Infos in den UPD.

updateSEPAInfo

public void updateSEPAInfo()

Deprecated. Bitte updateMetaInfo verwenden. Das aktualisiert auch die TAN-Medien.

Wenn der GV SEPAInfo unterstützt wird, heißt das, dass die Bank mit SEPA-Konten umgehen kann. In diesem Fall holen wir die SEPA-Informationen über die Konten von der Bank ab - für jedes SEPA-fähige Konto werden u.a. BIC/IBAN geliefert

getDialog

public HBCIDialog getDialog()

newLowlevelJob

public HBCIJob newLowlevelJob(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

addJobToDialog

public void addJobToDialog(HBCIJob job)

execute

public HBCIExecStatus execute(boolean closeDialog)

Ausführen aller bisher erzeugten Aufträge. Diese Methode veranlasst den HBCI-Kernel, die Aufträge, die durch die Aufrufe auszuführen.

Beim Hinzufügen der Aufträge zur Auftragsqueue 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 addToQueue() 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.

getPassport

public HBCIPassportInternal getPassport()

Gibt das Passport zurück, welches in diesem Handle benutzt wird.

Specified by:

getPassport in interface IHandlerData

Returns:

Passport-Objekt, mit dem dieses Handle erzeugt wurde

getKernel

public org.kapott.hbci.manager.HBCIKernel 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 implementierten Geschäftsvorfälle abzufragen.

Returns:

HBCI-Kernel-Objekt, mit dem der HBCI-Handler arbeitet

getMsgGen

public MsgGen getMsgGen()

Specified by:

getMsgGen in interface IHandlerData

getLowlevelJobParameterNames

public List<String> getLowlevelJobParameterNames(String gvname)

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 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(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 mit newLowlevelJob(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 an HBCIKernel.getLowlevelJobParameterNames(String, String) übergeben (nämlich die Versionsnummer, die HBCI4Java auch beim Anlegen eines Jobs via newLowlevelJob(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

public List<String> getLowlevelJobResultNames(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 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 an HBCIKernel.getLowlevelJobResultNames(String, String) übergeben (nämlich die Versionsnummer, die HBCI4Java auch beim Anlegen eines Jobs via newLowlevelJob(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

status

public void status(int statusMsgSend,
                   Object o)

callback

public void callback(int closeConnection,
                     String callb_close_conn,
                     int typeNone,
                     StringBuffer stringBuffer)