Class HBCIHandler

java.lang.Object
org.kapott.hbci.manager.HBCIHandler
All Implemented Interfaces:
AutoCloseable, IHandlerData

public final class HBCIHandler extends Object implements IHandlerData, AutoCloseable

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 Details

  • Constructor Details

    • HBCIHandler

      public HBCIHandler(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:
      • 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 mit AbstractHBCIPassport.getInstance() erzeugt worden sein
    • HBCIHandler

      public HBCIHandler(String hbciversion, HBCIPassport passport, boolean lazyInit)
      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 mit AbstractHBCIPassport.getInstance() erzeugt worden sein
      lazyInit - 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 per initThreaded() zu laden (zum Handling der eventuellen TAN-Abfrage)
  • Method Details

    • initThreaded

      public HBCIExecThreadedStatus 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 von initThreaded() 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 der callback()-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.

    • registerInstitute

      private void registerInstitute()
      Macht die anonyme Initialisierung und ruft die BPD ab.
    • registerUser

      private void registerUser()
      Ruft die UPD ab.
    • sync

      public void sync(boolean force)
      Description copied from interface: IHandlerData
      Fuehrt eine Neu-Synchronisierung durch.
      Specified by:
      sync in interface IHandlerData
      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 interface AutoCloseable
    • fixUnspecifiedCustomerId

      private String fixUnspecifiedCustomerId(String customerId)
    • getDialogFor

      private HBCIDialog getDialogFor(String customerId)
    • newMsg

      public void newMsg(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 HBCIJob.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 zu newMsg(String), nur dass hier die customerid mit der Kunden-ID vorbelegt ist, wie sie im aktuellen Passport gespeichert ist. Siehe dazu auch HBCIJob.addToQueue(String).
    • newJob

      public HBCIJob newJob(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(String,String) gesetzt werden. Anschließend kann der Job mit HBCIJob.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 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(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(String customerId, HBCIJob job)
      Do NOT use! Use HBCIJob.addToQueue(String) instead
    • addJob

      public void addJob(String customerId, HBCIJob job)
      Deprecated.
    • addJob

      public void addJob(HBCIJob job)
      Deprecated.
    • createEmptyDialog

      public void createEmptyDialog(String customerId)
      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()
    • 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 HBCIJob.addToQueue(String) zur Auftragsliste hinzugefügt wurden, auszuführen.

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

      public HBCIExecThreadedStatus executeThreaded()

      Entspricht execute(), allerdings können Callbacks hier auch synchron behandelt werden. Bei einem Aufruf von executeThreaded() anstelle von execute() 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 der callback()-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

      public HBCIExecThreadedStatus continueThreaded(String retData)

      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 dass executeThreaded() terminierte und der Rückgabewert anzeigte, dass Callback-Daten benötigt werden (HBCIExecThreadedStatus.isCallback()==true), dann müssen die benötigten Callback-Daten mit continueThreaded(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 ein HBCIExecThreadedStatus-Objekt (analog zu executeThreaded()), 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 via continueThreaded(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:

      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(java.security.KeyPair,java.security.KeyPair) 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(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

      public void setKeys(KeyPair sigKey, 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.

    • verifyTAN

      public HBCIExecStatus verifyTAN(String customerId)
      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

      public HBCIExecStatus verifyTAN()
      Entspricht verifyTAN(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 mit execute() wird diese Methode automatisch aufgerufen.
    • getPassport

      public HBCIPassport 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 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 (siehe getHBCIVersion()) 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
    • getHBCIVersion

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

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

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

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

      public boolean isSupported(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 newJob(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; ansonsten false
    • refreshXPD

      public HBCIDialogStatus refreshXPD(int selectX)
      Abholen der BPD bzw. UPD erzwingen. Beim Aufruf dieser Methode wird automatisch ein HBCI-Dialog ausgeführt, der je nach Wert von selectX 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 Werte REFRESH_BPD und REFRESH_UPD bestehen
      Returns:
      Status-Objekt, welches Informationen über den ausgeführten HBCI-Dialog enthält