
Einleitung
----------

HBCI4Java ist ein Java-Paket, welches es ermglicht, aus 
Java-Anwendungen heraus HBCI-Funktionalitt 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
aufgefhrt, eine bessere bersicht befindet sich in der Datei FEATURES.

* API ist sehr anwendungsbezogen. Das heit, zur Benutzung von 
  HBCI4Java sind im Prinzip keine Kenntnisse im HBCI-Bereich 
  ntig. Das API konzentriert sich auf die Beschreibung und 
  Auswertung der Geschftsvorflle, die auszufhren sind. Die 
  HBCI-spezifischen Details der Kommunikation mit einem 
  HBCI-Server werden dabei vollstndig vom HBCI-Kernel bernommen.

* API ist unabhngig von der benutzten HBCI-Version. Je nachdem, 
  mit welcher HBCI-Version die Anwendung mit einem Kreditinstitut 
  kommunizieren will, mssen verschiedene Besonderheiten der 
  jeweiligen HBCI-Version bercksichtigt werden. Diese 
  Besonderheiten werden von HBCI4Java vllig gekapselt, so dass 
  der Anwendungsentwickler hier keine Unterscheidungen bzgl. der 
  verwendeten Version machen muss (auer evtl. der Tatsache, dass 
  einige Geschftsvorflle erst in neueren HBCI-Versionen existieren).

* HBCI4Java ist fast vollstndig in reinem Java implementiert. 
  Daraus folgt, dass es tatschlich auf allen Java-fhigen 
  Plattformen zum Einsatz kommen kann. Nur ein kleiner Teil fr 
  die Ansteuerung des Chipkartenlesers ist in C++ implementiert. 
  Hierbei handelt es sich jedoch um sehr wenig und gut 
  portierbaren Code, so dass die Plattformunabhngigkeit 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 fr 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 
  Geschftsvorflle usw.) ist eine Anpassung des HBCI-Kernels 
  sehr leicht mglich. 

* HBCI4Java stellt nicht nur eine Client-Bibliothek dar, sondern 
  bietet auch die Mglichkeit, einen HBCI-Server aufzusetzen. 
  Dazu wird ein Framework fr den Server-Betrieb bereitgestellt. 
  Ein real zu implementierender Server msste "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 bentigt 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.

Fr die Verwendung eines Chipkartenterminals wird eine 
zustzliche Bibliothek bentigt. Fr 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.

Auerdem wird fr die Verwendung eines Chipkartenterminals eine 
entsprechende CTAPI-Bibliothek bentigt. 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 fr einige Hersteller die mir bekannten 
CTAPI-Bibliotheksnamen unter den verschiedenen Betriebssystemen aufgefhrt:

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


Fr die Verwendung von SIZ-RDH-Schlsseldateien mit HBCI4Java muss eine 
zustzliche Laufzeitbibliothek installiert werden, die separat erhltlich 
ist. Siehe dazu die Datei README.SIZRDHFile.


Update auf neuere HBCI4Java-Version
-----------------------------------

Nach der Installation einer neuen HBCI4Java-Version knnen smtliche
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 Dateigre die gleiche
    ist, sind die alten und neuen Dateien manchmal doch nicht identisch).
    
    Strzt eine HBCI-Anwendung beim Zugriff auf den Chipkartenleser hart
    ab (mit Fehlermeldungen aus dem JNI), so ist das ein typisches Anzeichen
    fr die Verwendung einer falschen DDV-Bibliothek.
    
  * Um evtl. neu hinzugekommene bzw. besser untersttzte Geschftsvorflle
    nutzen zu knnen, sollten alle benutzten Passport-Medien einmal mit
    dem Tool org.kapott.hbci.tools.InitAndTest reinitialisiert werden
    (dabei gehen keine Schlssel o.. verloren, es werden hauptschlich die
    BPD neu abgeholt).
    
    Statt dessen kann eine HBCI-Anwendung das erneute Auswerten der unter-
    sttzten Geschftsvorflle 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 Geschftsvorfalldaten 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 fr
die Arbeit mit und die Demonstration der Verwendung von HBCI4Java. Eine
kleine Beschreibung der einzelnen Tools befindet sich in der API-Dokumentation.

