org.kapott.hbci.GV
Interface HBCIJob


public interface HBCIJob

Schnittstelle für alle Aufträge, die via HBCI ausgeführt werden sollen. Ein HBCIJob-Objekt wird nur innerhalb von HBCI4Java verwaltet. Durch Aufruf einer der Methoden HBCIHandler.newJob(String) oder HBCIHandler.newLowlevelJob(String) wird eine neue Instanz eines HBCIJobs erzeugt. Die konkrete Klasse dieser Instanz ist für den Anwendungsentwickler nicht von Bedeutung.

Die Anwendung muss nur die für diesen Job benötigten Parameter setzen (mit setParam(String,String)). Falls dieser Job mehrere digitale Signaturen benötigt, können mit der Methode addSignaturePassport(HBCIPassport,String) weitere Passport-Objekte zu diesem Job hinzugefügt werden, die dann als Zweit-, Dritt-, ...-Signatur bei der Nachrichtenerzeugung verwendet werden. Anschließend kann der fertig spezifizierte Job zum aktuellen HBCI-Dialog hinzugefügt werden (addToQueue()).

Nach Ausführung des HBCI-Dialoges können die Rückgabedaten und Statusinformationen für diesen Job ermittelt werden. Dazu wird die Methoode getJobResult() benötigt, welche eine Instanz einer HBCIJobResult-Klasse zurückgibt. Die konkrete Klasse, um die es sich bei diesem Result-Objekt handelt, ist vom Typ des ausgeführten Jobs abhängig (z.B. gibt es eine Klasse, die Ergebnisdaten für Kontoauszüge enthält, eine Klasse für Saldenabfragen usw.). Eine Beschreibung der einzelnen Klassen für Result-Objekte findet sich im Package org.kapott.hbci.GV_Result. Eine Beschreibung, welcher Job welche Klasse zurückgibt, befindet sich in der Package-Dokumentation zu diesem Package (org.kapott.hbci.GV).


Method Summary
 void addSignaturePassport(HBCIPassport passport, java.lang.String role)
          Hinzufügen eines Passports, welches für eine zusätzliche Signatur für diesen Auftrag benutzt wird.
 void addToQueue()
          Hinzufügen dieses Jobs zu einem HBCI-Dialog.
 void addToQueue(java.lang.String customerId)
          Hinzufügen dieses Jobs zu einem HBCI-Dialog.
 java.util.List getJobParameterNames()
          Gibt alle möglichen Job-Parameter für einen Lowlevel-Job zurück.
 java.util.Properties getJobRestrictions()
          Gibt für einen Job alle bekannten Einschränkungen zurück, die bei der Ausführung des jeweiligen Jobs zu beachten sind.
 HBCIJobResult getJobResult()
          Gibt ein Objekt mit den Rückgabedaten für diesen Job zurück.
 java.util.List getJobResultNames()
          Gibt alle möglichen Property-Namen für die Lowlevel-Rückgabedaten dieses Jobs zurück.
 java.util.Properties getLowlevelParams()
          Gibt alle für diesen Job gesetzten Parameter zurück.
 int getMinSigs()
          Gibt zurück, wieviele Signaturen für diesen Job mindestens benötigt werden.
 java.lang.String getName()
          Gibt den internen Namen für diesen Job zurück.
 int getSecurityClass()
          Gibt zurück, welche Sicherheitsklasse für diesen Job mindestens benötigt wird.
 void setParam(java.lang.String paramName, java.util.Date date)
          Setzen eines Job-Parameters, bei dem ein Datums als Wert erwartet wird.
 void setParam(java.lang.String paramName, int i)
          Setzen eines Job-Parameters, bei dem ein Integer-Wert Da als Wert erwartet wird.
 void setParam(java.lang.String paramname, Konto acc)
          Setzen eines komplexen Job-Parameters (Kontodaten).
 void setParam(java.lang.String paramName, java.lang.String value)
          Setzen eines Job-Parameters.
 void setParam(java.lang.String paramname, Value v)
          Setzen eines komplexen Job-Parameters (Geldbetrag).
 

Method Detail

getName

public java.lang.String getName()
Gibt den internen Namen für diesen Job zurück.

Returns:
Job-Name, wie er intern von HBCI4Java verwendet wird.

getMinSigs

public int getMinSigs()

Gibt zurück, wieviele Signaturen für diesen Job mindestens benötigt werden. Diese Information wird den BPD entnommen. In einigen Fällen gibt es in den UPD aktuellere Informationen zu einem bestimmten Geschäftsvorfall, zur Zeit werden die UPD von dieser Methode aber nicht ausgewertet.

Wird für einen Job mehr als eine Signatur benötigt, so können mit der Methode addSignaturePassport(HBCIPassport, String) Passports bestimmt werden, die für die Erzeugung der zusätzlichen Signaturen verwendet werden sollen.

Es wird außerdem empfohlen, dass Aufträge, die mehrere Signaturen benötigen, jeweils in einer separaten HBCI-Nachricht versandt werden. Um das zu erzwingen, kann entweder ein HBCI-Dialog geführt werden, der definitiv nur diesen einen Auftrag enthält (also nur ein addToQueue() für diesen Dialog), oder es wird beim Zusammenstellen der Jobs für einen Dialog sichergestellt, dass ein bestimmter Job in einer separaten Nachricht gesandt wird (HBCIHandler.newMsg()).

Returns:
Mindest-Anzahl der benötigten Signaturen für diesen Job

getSecurityClass

public int getSecurityClass()

Gibt zurück, welche Sicherheitsklasse für diesen Job mindestens benötigt wird. Diese Information wird den BPD entnommen. Sicherheitsklassen sind erst ab FinTS-3.0 definiert. Falls keine Sicherheitsklassen unterstützt werden (weil eine geringere HBCI-Version als FinTS-3.0 verwendet wird), wird 1 zurückgegeben. Die Sicherheitsklasse ist nur die Sicherheitsmechanismen DDV und RDH relevant - bei Verwendung von PIN/TAN hat die Sicherheitsklasse keine Bedeutung.

Folgende Sicherheitsklassen sind definiert:

Returns:
Sicherheitsklasse, die für diese Job benötigt wird

getJobParameterNames

public java.util.List getJobParameterNames()
Gibt alle möglichen Job-Parameter für einen Lowlevel-Job zurück. Die Anwendung dieser Methode ist nur sinnvoll, wenn es sich bei dem aktuellen Job um einen Lowlevel-Job handelt (erzeugt mit HBCIHandler.newLowlevelJob(String)). Die zurückgegebenen Parameternamen können als erstes Argument der Methode setParam(String, String) verwendet werden.

Returns:
Liste aller gültigen Parameternamen (nur für Lowlevel-Jobs)

getJobResultNames

public java.util.List getJobResultNames()
Gibt alle möglichen Property-Namen für die Lowlevel-Rückgabedaten dieses Jobs zurück. Die Lowlevel-Rückgabedaten können mit getJobResult() und HBCIJobResult.getResultData() ermittelt werden. Diese Methode verwendet intern HBCIHandler.getLowlevelJobResultNames(String).

Returns:
Liste aller prinzipiell möglichen Property-Keys für die Lowlevel-Rückgabedaten dieses Jobs

getJobRestrictions

public java.util.Properties getJobRestrictions()

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.

Diese Methode verwendet intern HBCIHandler.getLowlevelJobRestrictions(String)

.

Returns:
Properties-Objekt mit den einzelnen Restriktionen

getLowlevelParams

public java.util.Properties getLowlevelParams()
Gibt alle für diesen Job gesetzten Parameter zurück. In dem zurückgegebenen Properties-Objekt sind werden die Parameter als Lowlevel-Parameter abgelegt. Außerdem hat jeder Lowlevel-Parametername zusätzlich ein Prefix, welches den Lowlevel-Job angibt, für den der Parameter gilt (also z.B. Ueb3.BTG.value

Returns:
aktuelle gesetzte Lowlevel-Parameter für diesen Job

setParam

public void setParam(java.lang.String paramname,
                     Konto acc)
Setzen eines komplexen Job-Parameters (Kontodaten). Einige Jobs benötigten Kontodaten als Parameter. Diese müssten auf "normalem" Wege durch fünf Aufrufe von setParam(String,String) erzeugt werden (je einer für die Länderkennung, die Bankleitzahl, die Kontonummer und optional das Unterkontomerkmal und Währung). Durch Verwendung dieser Methode wird dieser Weg abgekürzt. Es wird ein Kontoobjekt übergeben, für welches die entsprechenden fünf setParam(String,String)-Aufrufe automatisch erzeugt werden.

Parameters:
paramname - die Basis der Parameter für die Kontodaten (für "my.country", "my.blz", "my.number", "my.subnumber und my.curr" wäre das also "my")
acc - ein Konto-Objekt, aus welchem die zu setzenden Parameterdaten entnommen werden

setParam

public void setParam(java.lang.String paramname,
                     Value v)
Setzen eines komplexen Job-Parameters (Geldbetrag). Einige Jobs benötigten Geldbeträge als Parameter. Diese müssten auf "normalem" Wege durch zwei Aufrufe von setParam(String,String) erzeugt werden (je einer für den Wert und die Währung). Durch Verwendung dieser Methode wird dieser Weg abgekürzt. Es wird ein Value-Objekt übergeben, für welches die entsprechenden zwei setParam(String,String)-Aufrufe automatisch erzeugt werden.

Parameters:
paramname - die Basis der Parameter für die Geldbetragsdaten (für "btg.value" und "btg.curr" wäre das also "btg")
v - ein Value-Objekt, aus welchem die zu setzenden Parameterdaten entnommen werden

setParam

public void setParam(java.lang.String paramName,
                     java.util.Date date)
Setzen eines Job-Parameters, bei dem ein Datums als Wert erwartet wird. Diese Methode dient als Wrapper für setParam(String,String), um das Datum in einen korrekt formatierten String umzuwandeln. Das "richtige" Datumsformat ist dabei abhängig vom aktuellen Locale.

Parameters:
paramName - Name des zu setzenden Job-Parameters
date - Datum, welches als Wert für den Job-Parameter benutzt werden soll

setParam

public void setParam(java.lang.String paramName,
                     int i)
Setzen eines Job-Parameters, bei dem ein Integer-Wert Da als Wert erwartet wird. Diese Methode dient nur als Wrapper für setParam(String,String).

Parameters:
paramName - Name des zu setzenden Job-Parameters
i - Integer-Wert, der als Wert gesetzt werden soll

setParam

public void setParam(java.lang.String paramName,
                     java.lang.String value)

Setzen eines Job-Parameters. Für alle Highlevel-Jobs ist in der Package-Beschreibung zum Package org.kapott.hbci.GV eine Auflistung aller Jobs und deren Parameter zu finden. Für alle Lowlevel-Jobs kann eine Liste aller Parameter entweder mit dem Tool ShowLowlevelGVs oder zur Laufzeit durch Aufruf der Methode HBCIHandler.getLowlevelJobParameterNames(String) ermittelt werden.

Bei Verwendung dieser oder einer der anderen setParam()-Methoden werden zusätzlich einige der Job-Restriktionen (siehe getJobRestrictions()) analysiert. Beim Verletzen einer der überprüften Einschränkungen wird eine Exception mit einer entsprechenden Meldung erzeugt. Diese Überprüfung findet allerdings nur bei Highlevel-Jobs statt.

Parameters:
paramName - der Name des zu setzenden Parameters.
value - Wert, auf den der Parameter gesetzt werden soll

addToQueue

public void addToQueue()

Hinzufügen dieses Jobs zu einem HBCI-Dialog. Diese Methode arbeitet analog zu addToQueue(String), nur dass hier die customerid mit der Kunden-ID vorbelegt ist, wie sie im aktuellen Passport gespeichert ist.


addToQueue

public void addToQueue(java.lang.String customerId)

Hinzufügen dieses Jobs zu einem HBCI-Dialog. Nachdem alle Jobparameter mit setParam(String,String) 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 HBCIHandler.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 HBCIHandler.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

getJobResult

public HBCIJobResult getJobResult()
Gibt ein Objekt mit den Rückgabedaten für diesen Job zurück. Das zurückgegebene Objekt enthält erst nach der Ausführung des Jobs gültige Daten.

Returns:
ein Objekt mit den Rückgabedaten und Statusinformationen zu diesem Job

addSignaturePassport

public void addSignaturePassport(HBCIPassport passport,
                                 java.lang.String role)
Hinzufügen eines Passports, welches für eine zusätzliche Signatur für diesen Auftrag benutzt wird. role gibt dabei die Rolle an, die der Eigentümer des zusätzlichen Passports in Bezug auf diesen Job (bzw. die aktuelle Nachricht) einnimmt. Gültige Werte sind in HBCIPassport beschrieben. Mit der Methode getMinSigs() kann ermittelt werden, wieviele Signaturen für einen Job mindestens benötigt werden.

Parameters:
passport - das hinzuzufügende Passport-Objekt, welches für eine zusätzliche Signatur benutzt werden soll
role - die Rolle, in der sich der Eigentümer des zusätzlichen Passport-Objektes bezüglich dieses Jobs befindet