
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.

