Einleitung
----------
HBCI4Java ist ein Java-Paket, welches es ermöglicht, aus
Java-Anwendungen heraus HBCI-Funktionalität zu verwenden. Die
meisten existierenden HBCI-Bibliotheken haben einige gravierende
Probleme/Nachteile, die mit dieser Implementation behoben werden
sollen. Die besonderen Eigenschaften von HBCI4Java sind im folgenden
aufgeführt, eine bessere Übersicht befindet sich in der Datei FEATURES.
* API ist sehr anwendungsbezogen. Das heißt, zur Benutzung von
HBCI4Java sind im Prinzip keine Kenntnisse im HBCI-Bereich
nötig. Das API konzentriert sich auf die Beschreibung und
Auswertung der Geschäftsvorfälle, die auszuführen sind. Die
HBCI-spezifischen Details der Kommunikation mit einem
HBCI-Server werden dabei vollständig vom HBCI-Kernel übernommen.
* API ist unabhängig von der benutzten HBCI-Version. Je nachdem,
mit welcher HBCI-Version die Anwendung mit einem Kreditinstitut
kommunizieren will, müssen verschiedene Besonderheiten der
jeweiligen HBCI-Version berücksichtigt werden. Diese
Besonderheiten werden von HBCI4Java völlig gekapselt, so dass
der Anwendungsentwickler hier keine Unterscheidungen bzgl. der
verwendeten Version machen muss (außer evtl. der Tatsache, dass
einige Geschäftsvorfälle erst in neueren HBCI-Versionen existieren).
* HBCI4Java ist fast vollständig in reinem Java implementiert.
Daraus folgt, dass es tatsächlich auf allen Java-fähigen
Plattformen zum Einsatz kommen kann. Nur ein kleiner Teil für
die Ansteuerung des Chipkartenlesers ist in C++ implementiert.
Hierbei handelt es sich jedoch um sehr wenig und gut
portierbaren Code, so dass die Plattformunabhängigkeit immer
noch als gegeben angesehen werden kann.
Viele existierende HBCI-Implementationen werden ebenfalls als
"Java-Version" beworben, dabei handelt es sich allerdings oft um
in C/C++ geschriebene dynamische Bibliotheken für Windows
(DLL), über die einfach ein Java-Wrapper gesetzt wird, so dass
diese Implementationen trotz "Java-API" nur unter Windows laufen.
* Durch die starke Trennung der einzelnen Kernkomponenten
voneinander (Sicherheitsmechanismen, Kommunikationspfade,
Nachrichtensynthese und -analyse, Abstraktion der
Geschäftsvorfälle usw.) ist eine Anpassung des HBCI-Kernels
sehr leicht möglich.
* HBCI4Java stellt nicht nur eine Client-Bibliothek dar, sondern
bietet auch die Möglichkeit, einen HBCI-Server aufzusetzen.
Dazu wird ein Framework für den Server-Betrieb bereitgestellt.
Ein real zu implementierender Server müsste "nur" noch
entsprechende Backend-Systeme bereitstellen und an
entsprechende Callback-Methoden des HBCI-Server-Kernels
andocken.
Dieser Codeteil ist jedoch nicht in der Distribution enthalten,
sondern wird als separates Paket angeboten (hbci4java-server)
Installation von HBCI4Java
--------------------------
HBCI4Java benötigt mindestens Java Runtime Environment 1.4.2.
Das Java-Archiv hbci4java.jar muss in den CLASSPATH aufgenommen
werden. Das kann entweder durch Installation im Verzeichnis
<JRE_HOME>/lib/ext geschehen, oder indem der Dateiname in die
entsprechende Umgebungsvariable oder die Kommandozeile (Argument
-classpath) aufgenommen wird.
Für die Verwendung eines Chipkartenterminals wird eine
zusätzliche Bibliothek benötigt. Für einige Plattformen werden
die fertig kompilierten Bibliotheken bereits mitgeliefert,
auf allen anderen Plattformen muss die Bibliohek selbst kompiliert
werden (Quelltexte im src-Paket; Verzeichnis "chipcard/src").
Diese Bibliothek muss in einem Verzeichnis gespeichert werden,
auf das HBCI4Java zur Laufzeit Zugriff hat.
Außerdem wird für die Verwendung eines Chipkartenterminals eine
entsprechende CTAPI-Bibliothek benötigt. Diese wird i.d.R. vom
Hersteller des Chipkartenterminal mitgeliefert. Der Name der
jeweiligen Bibliothek (unter Linux und Solaris eine .so-Datei,
unter Windows eine .DLL) muss bekannt sein, und die Bibliothek
muss sich ebenfalls in einem Verzeichnis befinden, welches von
HBCI4Java zur Laufzeit gelesen werden kann.
Im folgenden werden für einige Hersteller die mir bekannten
CTAPI-Bibliotheksnamen unter den verschiedenen Betriebssystemen aufgeführt:
+-------------+---------------------------------+-----------+--------------+
| | Linux | Solaris | Windows |
+-------------+---------------------------------+-----------+--------------+
+-------------+---------------------------------+-----------+--------------+
| Reiner-SCT | libctapi-cyberjack.so | | ctrsct32.dll |
+-------------+---------------------------------+-----------+--------------+
| Kobil | libct_b1.so oder libct_kaan.so | libct.so | ct32.dll |
+-------------+---------------------------------+-----------+--------------+
| Towitoko | libtowitoko.so | | cttwkw32.dll |
+-------------+---------------------------------+-----------+--------------+
Für die Verwendung von SIZ-RDH-Schlüsseldateien mit HBCI4Java muss eine
zusätzliche Laufzeitbibliothek installiert werden, die separat erhältlich
ist. Siehe dazu die Datei README.SIZRDHFile.
Update auf neuere HBCI4Java-Version
-----------------------------------
Nach der Installation einer neuen HBCI4Java-Version können sämtliche
alten Passport-Dateien weiterverwendet werden.
Zu beachten ist nur folgendes:
* Auf keinen Fall vergessen, auch die neuen DDV-Bibliotheken aus dem
HBCI4Java-Archiv zu installieren (auch wenn die Dateigröße die gleiche
ist, sind die alten und neuen Dateien manchmal doch nicht identisch).
Stürzt eine HBCI-Anwendung beim Zugriff auf den Chipkartenleser hart
ab (mit Fehlermeldungen aus dem JNI), so ist das ein typisches Anzeichen
für die Verwendung einer falschen DDV-Bibliothek.
* Um evtl. neu hinzugekommene bzw. besser unterstützte Geschäftsvorfälle
nutzen zu können, sollten alle benutzten Passport-Medien einmal mit
dem Tool org.kapott.hbci.tools.InitAndTest reinitialisiert werden
(dabei gehen keine Schlüssel o.ä. verloren, es werden hauptsächlich die
BPD neu abgeholt).
Statt dessen kann eine HBCI-Anwendung das erneute Auswerten der unter-
stützten Geschäftsvorfälle auch erzwingen, indem die Methode
passport.clearBPD() _vor_ dem Initialiseren eines HBCIHandlers mit diesem
Passport aufgerufen wird (Beim Initialisieren des HBCIHandlers werden
die BPD mit den Geschäftsvorfalldaten dann automatisch aktualisiert).
Also:
...
HBCIPassport passport=AbstractHBCIPassport.getInstance();
passport.clearBPD();
HBCIHandler handle=new HBCIHandler(null,passport);
...
Tools
-----
Im Paket org.kapott.hbci.tools befindn sich einige Kommandozeilentools für
die Arbeit mit und die Demonstration der Verwendung von HBCI4Java. Eine
kleine Beschreibung der einzelnen Tools befindet sich in der API-Dokumentation.