<commit_before>[[section-design-decisions]]

== Entwurfsentscheidungen


=== Keine `null`-Werte

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").


=== NULL-Konstanten

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


=== Kein Logging / Minimale Abhängigkeiten

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.
Eine Ausnahme hiervon ist die FachwertFactory-Klasse, da hier Exceptions behandelt werden.
Dazu wird aber das Logging-Framework des JDKs im Log-Level FINE verwendet.

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:

* kotlin-stdlib: diese Bibliothek kam durch die Umstellung auf Kotlin in v4 hinzu
* commons-lang3: diese Bibliothek ist bereits als Abhängigkeit vieler anderer Bibliotheken vorhanden
* commons-collections4: aus dieser Bibliothek wurde die ReferenceMap verwendet, um Objekte, die oft gebraucht werden, vorhalten zu können
  (zur Reduktion des Speicherverbrauchs)
* commons-text: hieraus wurden die WordUtils für die Groß-/Kleinschreibung von Namensanteilen verwendet.
* validation-api: Basis-Bibliothek für Validierung
* money-api (JSR 354): diese API sowie einige weitere Bibliotheken dazu sind optional, da sie Java 9 Bestandteil des JDKs sind.
  Evtl. müssen sie unter Java 8 als Dependency mit aufgeführt werden, wenn diese Funktionalität benötigt wird.


=== Ableitung möglich

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


=== Konstruktor mit Validierung

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

* nur gültige Fachwerte erzeugt werden können,
* der Validator von der abgeleiteten Klasse ver- oder entschärft werden kann (je nach Anforderung).



=== Minimaler Footprint

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

* Minimierung der Anzahl interner Attribute
* Verwendung nativer Datentypen (soweit sinnvoll und möglich)
* Verwendung von PackedDecimal (soweit sinnvoll und möglich)<commit_msg>Doku zu commons-text aktualisiert<commit_after>[[section-design-decisions]]

== Entwurfsentscheidungen


=== Keine `null`-Werte

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").


=== NULL-Konstanten

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


=== Kein Logging / Minimale Abhängigkeiten

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.
Eine Ausnahme hiervon ist die FachwertFactory-Klasse, da hier Exceptions behandelt werden.
Dazu wird aber das Logging-Framework des JDKs im Log-Level FINE verwendet.

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:

* kotlin-stdlib: diese Bibliothek kam durch die Umstellung auf Kotlin in v4 hinzu
* commons-lang3: diese Bibliothek ist bereits als Abhängigkeit vieler anderer Bibliotheken vorhanden
* commons-collections4: aus dieser Bibliothek wurde die ReferenceMap verwendet, um Objekte, die oft gebraucht werden, vorhalten zu können
  (zur Reduktion des Speicherverbrauchs)
* validation-api: Basis-Bibliothek für Validierung
* money-api (JSR 354): diese API sowie einige weitere Bibliotheken dazu sind optional, da sie Java 9 Bestandteil des JDKs sind.
  Evtl. müssen sie unter Java 8 als Dependency mit aufgeführt werden, wenn diese Funktionalität benötigt wird.

Mit v4.4 wurde die Abhänigkeit zu commons-text wieder entfernt, da Kotlin hierfür genügend Unterstützung anbietet, um die fehlende Funktionalität selbst zu implementieren.



=== Ableitung möglich

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


=== Konstruktor mit Validierung

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

* nur gültige Fachwerte erzeugt werden können,
* der Validator von der abgeleiteten Klasse ver- oder entschärft werden kann (je nach Anforderung).



=== Minimaler Footprint

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

* Minimierung der Anzahl interner Attribute
* Verwendung nativer Datentypen (soweit sinnvoll und möglich)
* Verwendung von PackedDecimal (soweit sinnvoll und möglich)
{'fraction_non_alphanumeric': 0.04594835262689225, 'fraction_numerical': 0.004630454140694568, 'mean_word_length': 5.3386004514672685, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2970740', 'n_tokens_mistral': 1822, 'n_tokens_neox': 1864, 'n_words': 701}