jFachwert, Architektur

Diese Bibliothek greift die Idee von damals (s.o.) wieder auf, ist aber nicht auf den Bankbereich beschränkt:

Im März 2017 wurde jfachwert im Maven-Repository aufgenommen (OSSRH-29910). Die Bibliothek setzt auf Java 8 auf. Ab Oktober 2019 wurde die die Bibliothek auf Kotlin umgestellt, während die JUnit-Tests in Java verblieben (um die Kompatibilität mit Java sicherzustellen).

Ursprünglich setzte jFachwert auf Java 8 auf, wurde aber ab Oktober 2019 auf Kotlin umgstellt. Dennoch sollte jFachwert sowohl mit Java 8 und Java 11 laufen. Dies wird durch JUnit-Tests sichergestellt, die in Java verblieben sind und die mit Java 8 und Java 11 ausgeführt werden.

Die Abhängigkeiten zu anderen Bibliotheken werden auf ein Minimum reduziert. Dies erleichtert den Einsatz von jFachwert für andere Projekte.

jFachwert wird nach dem GitFlow-Modell. D.h. die eigentliche Entwicklung findet auf dem develop-Zweig statt. Releases werden mit dem jgitflow-maven-plugin gebaut, wie in der Entwickler-Dokumentation beschrieben.

Fachwerte konzentrieren sich auf den deutschsprachigen Raum und es wird (bis auf wenige Ausnahmen) der in Deutschland übliche Begriff verwendet. So heißt es im Deutschen Kontonummer und nicht AccountNumber.

jFachwert benötigt mindestens Java 8 und verwendet Optional für optionale Parameter und Rückgabewerte. Damit sind null als Parameter nicht erlaubt und können auch nicht als Rückgabewert vorkommen.

Da Fachwerte immutable (unveränderlich) sind, kommt der Erzeugung eine wichtige Bedeutung zu. Prinzipiell bieten sich dabei folgende Verfahren an:

Builder-Pattern bieten sich eher dann dafür an, wenn die Erzeugung eines Objekts komplexer ist. Da Fachwerte aber tendenziell einfach aufgebaut sind und oft nur mit einem Argument für den Konstruktor auskommen, wird nur der Konstruktor für die Erzeugung eines Objekts angeboten.

Die Erzeugung über eine statische of(..)-Methode hat den Vorteil, dass Objekte, die oft benötigt werden, in einem Cache vorgehalten werden können. Dies beschleunigt die Erzeugung von Objekten, vor allem aber reduziert es den Speicherverbrauch. Deswegen werden ab v1.2 bereits erzeugte Objekte in einen Cache gelegt, um Duplikate zu vermeiden.

Da ungültige Objekte verhindert werden sollen, muss die Validierung im Konstruktor erfolgen. Um den Konstruktor übersichtlich zu halten, werden die Prüfung in eigene Validatoren ausgelagert.

Auch sind Prüfziffer-Verfahren, die zur Erkennung fehlerhafter Fachwerte dienen, eine Art der Validierung. Deswegen befinden sich Validatoren und Prüfziffer-Verfahren im selben Package.

Viele Klassen bieten auch eine statische validate-Methode an, um auch ohne Kreierung von Fachwerten eine Überprüfung der Parameter durchführen zu können. Mit Umstellung auf Kotlin in v4.0 ist die validate-Methode in ein Companion-Objekt gewandert. Druch ändert sich der Aufruf von UStdIdNr.validate("DE136695970") in UStIdNr.Companion.validate("DE136695970").

Mit Throwable.getLocalizedMessage() gibt es seit JDK 1.1 die Möglichkeit, sprach-spezifische Fehlermeldungen zur Verfügung zu stellen. Dies wird verwendet, um für den deutschsprachigen Raum eine entsprechende Fehlermeldung für die Anzeige anzubieten.

Als Encoding wird UTF-8 verwendet. Um Encoding-Probleme zu vermeiden, wird im Source-Code und in Resourcen keine Umlaute, sondern stets die Ersatzdarstellung (z.B. Pr\u00fcfziffer) verwendet.

Auch in Kommentaren im Source-Code werden keine Umlaute verwendet. Hier werden Umlaute ausgeschrieben, z.B. /* Pruefziffer */). Dies hat Auswirkungen auf die Javadoc-Generierung. Dies wird aber in Kauf genommen, um Probleme mit falschen Encoding zu vermeiden.

Das pruefung-Package enthält Klassen zur Validierung und zu verschiedenen Pruefzifferverfahren. So enthalten manche Fachwerte wie IBAN eine Pruefziffer, um Fehleingaben zu erkennen.

Alles, was mit Prüfungen und Validierung zu tun hat, ist im pruefung-Package abgelegt. Dazu gehoeren:

Ab 1.0 kam die Geldbetrag-Klasse im bank-Paket (de.jfachwert.bank) hinzu, die das MonetaryAmount-Interface aus JSR-354 implementiert. Geldbetrag vereinfacht den Umgang mit der Erzeugung von MonetaryAmount-Instanzen durch

Bei der Erzeugung eines Fachwerts (z.B. einer IBAN) werden ein oder mehrere Validatoren (auch Prüfziffer-Verfahren) aufgerufen, um ungültige Parameter mit einer ValidationException abzuweisen. Sind keine Prüfverfahren oder Prüfregeln bekannt, wird mindestens der NullValidator aufgerufen. Er sorgt dafür, dass null als Parameter zurückgewiesen wird.

Mit der FachwertFactory, die mit Version 0.5 eingeführt wurde, kann ein beliebiger Fachwert erzeugt werden. Damit kann die FachwertFactory auch zur Validierung von Fachwerten eingesetzt werden, ohne dass dieser explizit erzeugt werden muss.

Dies ist vor allem für die automatisierte Validierung gedacht, wenn der Fachwert erst zur Laufzeit bekannt ist. Damit lassen sich dann Anforderungen wie "validierte das Eingabefeld 'Bankverbindung'". In gdv.xport wird dies z.B. zur Validierung von importierten Datensätze verwendet.

jFachwert wird als JAR-Datei ins zentrale Maven-Repository hochgeladen. Dort kann sie über folgende Maven-Koordinaten als Abhängigkeit in ein Projekt hinzugefügt werden:

Externe Abhängigkeiten zu andere Bibliotheken beschränkt sich auf commons-lang3 und der Kotlin-Standard-Bibliothek. Bei Verwendung von Maven oder Gradle werden diese Abhängigkeiten automatisch hinzugefügt.

Viele Fachwerte wie IBAN oder BIC sind nur ein dünner Wrapper um die String-Klasse. Für diese Fachwerte werden die Gemeinsamkeiten in AbstractFachwert zusammengefasst.

Validierung von Fachwerten findet im Konstruktor statt. Zur Unterstützung gibt es eine Reihe von Validatoren und Prüfziffer-Verfahren, die im pruefung-Package zu finden sind. Will man die Validierung direkt ausführen, bitten die meisten Klassen eine validate-Methode im Companion-Objekt an. Ansonsten kann man für die Validierung auch direkt auf die Validatoren zugreifen.

Ein Grund für die Migration auf Kotlin war die Unterbindung von null-Werten. Damit kann schon auf Aufruf-Ebene schon garantiert werden, dass null-Werte nicht weitergegeben werden, sondern sofort zum Fehler führen ("fail fast").

Mit v2.2 wurden NULL-Konstanten eingeführt. Damit können Variablen mit diesem Wert vorbelegt werden.

Um nicht von einem bestimmten Log-Framework abhängig zu sein, wurde auf Logging weitgehend verzichtet. Das bedeutet, dass in einem Falle eines Fehlers oder fehlerhaften Aufrufs eine hilfreiche Exception ausgelöst wird. Diese Exception stellt alle Informationen zur Verfügung, um die Ursache des Fehlers zu finden. Exceptions, die abgefangen und behandelt werden, werden ueber das Logging-Framework des JDKs protokolliert. Um diese Meldungen sichtbar zu machen, muss der Log-Level FINE oder FINER (für den Stacktrace) konfiguriert werden.

Um sich nicht weitere unerwünschte Abhängigkeiten bei der Verwendung von jFachwert einzufangen, werden die Abhängigkeiten zu anderen Bibiotheken auf ein Minimum reduziert. Die einzigen Abhängigkeiten, die in Kauf genommen werden, sind:

Mit v4.4 wurde die Abhänigkeit zu commons-text und commons-collections4 wieder entfernt, da Kotlin hierfür genügend Unterstützung anbietet, um die fehlende Funktionalität selbst zu implementieren. Auch wurde die ValidationException aus der validation-api-Bibliothek durch eine gleichnamige Exception aus de.jfachwert.pruefung.exception ersetzt, um die Abhängigkeit zu JavaEE zu vermeiden. Andernfalls hätte diese Abhängigkeit auf JakartaEE geändert werden müssen.

Um für Fachklassen auch eigene Logik hinterlegen zu können, können die Klassen abgeleitet werden. Deswegen sind die Klassen nicht final.

Jede Klasse besitzt einen Konstruktor, der als letztes Argument einen Validator (z.B. in Form eines Pruefzifferverfahrens) hat. Damit ist sichergestellt, dass

Mit v2.0 wurde mit einer Reihen von Massnahmen der Speicherverbrauch reduziert:

Der minimale Footprint wird teilweise durch eine aufwendigere Objekt-Erzeugung oder/und Methoden-Zugriff erkauft. Dies kann evtl. bei Massenverarbeitung zum Flaschenhals werden. Hier kann man aber durch parallele Zugriffe entgegensteuern.

Damit sind Fachwerte auch für große Datenmengen geeignet, die im Hauptspeicher gehalten und parallel verarbeitet werden sollen.

Die equals- und hashCode-Methode wurden jeweils überschrieben. Zwei Fachwerte sind gleich, wenn sie jeweils die gleichen Werte besitzen.

Bei Klassen im post-Paket findet ein fachlicher Vergleich statt (ab v2.1). So werden bei der Adresse "Göthestraße", "Goethestrasse" und "Göthestr." jeweils als die gleiche Straße angesehen. Möchte man es exakt, gibt es in diesen Klasse eine equalsExact(..)-Methode.

Jeder Fachwert hat eine aussagekräftige toString-Implementierung. Meist ist dies der Wert selbst.

Mit 1.0 kam die Geldbetrag-Klasse hinzu, die das MonetaryAmount-Interface aus "javax.money" implementiert. Gründe für eine eigene Implementierung waren:

Der letzte Punkt ist auch der Grund, warum die Geldbetrag-Klasse zusätzlich zur of(..)-Methoden auch valueOf(..)-Methoden besitzen. Dabei werden die gleichen Parameter wie bei BigDecimal akzeptiert.

Wegen KT-6653 ist das Kotlin Interface ILocalizedException nicht identisch zur Java-Variante LocalizedException. Da dieses Interface aber nur für den internen Gebrauch gedacht ist, wurde diese Inkompatibilität in Kauf genommen.

Einige weitere Interfaces wie Fachwert sind in Java verblieben, da Interfaces mit Default-Implementierung nicht 100%-ig kompatibel sind (s. KT-4779). Für die Verwendung in Kotlin gibt es das Interface mit vorangestelltem 'K' (KFachwert).

Ansosten wird die Kompatilität zur Java Version (v3) dadurch sichergestellt, das die Unit-Tests in Java verbleiben und auch in Java weiterentwickelt werden. Daneben wurden einige Klassen aus anderen Projekte, bei denen es Kompatibiltätsprobleme gab, als zusätzliche Testfälle hinzugefügt.