Nutzungsvorgaben Util

Java Bibliothek / IT-System

Name Art Version

Name	Art	Version
`isy-util`	Bibliothek	5.0.0

isy-util

Bibliothek

5.0.0

Die Bibliothek isy-util bietet nützliche Hilfsmittel, die von den Anwendungen der IsyFact genutzt werden können. Es handelt sich dabei um kleinere Utility-Klassen, welche die Implementierung vereinfachen. Diese werden im Folgenden überblicksartig beschrieben. Details sind den JavaDoc der einzelnen Klassen zu entnehmen.

1. Aufbau von `isy-util`

1.1. Package logging

In de.bund.bva.isyfact.util.logging sind Klassen enthalten, die für das Logging einzusetzen sind:

CombinedMarkerFactory: Mit dieser Klasse können zusammengesetzte Marker erzeugt werden, die beim Logging mit slf4j verwendet werden können, um Log-Einträge mit Markierungen zu versehen.

1.2. Package text

Das Package text enthält Werkzeuge für die Erzeugung standardisierter Ausgabe-Nachrichten:

RecursiveToStringBuilder: Diese Klasse erzeugt eine Textausgabe für Objekte, die keine geeignete toString-Methode implementieren.

1.3. Package persistence

Das Package de.bund.bva.isyfact.util.persistence enthält unterstützende Klassen für den Umgang mit Datenbanken:

Das Unterpaket datasource enthält die Klassen DataSourceCheckRunner und DataSourceCheck mit der die Schema-Version gegen eine Datenbanktabelle geprüft werden kann.
- Mit der Klasse DataSourcCheck kann diese Prüfung manuell durchgeführt werden.
- Mit der Klasse DataSourceCheckRunner kann diese Prüfung beim Start einer Spring-Anwendung automatisiert werden.
- Weitere Details: Prüfen der DB Schema-Version.
Die Unterpakete annotation und usertype enthalten Klassen zum Umgang mit Enum-Entitäten.

2. Utility-Klassen von `isy-util`

2.1. Logging-Marker

Mithilfe der statischen Methoden aus der CombinedMarkerFactory können Standard-Log-Ausgaben aus slf4j markiert werden.

Listing 1. Markierung einer Log-Ausgabe

class Demo {

    void demo() {
        Logger logger = LoggerFactory.getLogger(Demo.class);
        logger.info(createSchluesselMarker("SCHLUESSEL"),"Diese Info-Nachricht ist mit dem Wert aus SCHLUESSEL markiert");
    }

}

2.2. Prüfen der DB Schema-Version

Die hier beschriebenen Klassen bewahren die Abwärtskompatibilität zur ehemals in der IsyFact vorhandenen Schema-Versionierung in Form einer Eigenentwicklung. Die aktuelle Version der IsyFact-Referenzarchitektur empfiehlt hingehen den Einsatz von Liquibase.

2.2.1. Voraussetzungen

Der DataSourceCheck setzt eine Datenbank-Tabelle voraus, welche die aktuelle Schema-Version enthält. Die Tabelle wird mittels eines vordefinierten SQL-Statements abgefragt.

Listing 2. Abfrage der Schema-Tabelle

SELECT version_nummer FROM m_schema_version WHERE version_nummer = ? AND status = 'gueltig'

Der Abfrage der Schema-Tabelle liegt eine Tabelle in folgender Gestalt zugrunde.

Tabelle 1. Vorlage Schema-Tabelle
Spalte	Typ	Beschreibung
`version_nummer`	Zeichenkette (25 Zeichen)	Versionsnummer des Datenbankschemas. Diese Versionsnummer entspricht der Versionsnummer der Anwendung, mit der sich das Schema geändert hat.
`update_nummer`	Zeichenkette (5 Zeichen)	Update-Zähler, der jedes Mal hochgezählt wird, wenn sich das Datenbankschema ändert, aber die Anwendung unverändert bleibt.
`status`	Zeichenkette (25 Zeichen)	`gueltig` Das Schema wurde korrekt installiert bzw. aktualisiert und kann verwendet werden. `ungueltig` Das Schema befindet sich im Aufbau bzw. in der Änderung oder die Installation wurde nur teilweise durchgeführt und wurde mit Fehlern abgebrochen. Das Schema kann nicht verwendet werden und muss überprüft werden.

2.2.2. Automatische Prüfung beim Start

Die Bean DataSourceCheckRunner führt beim Anwendungsstart automatisch eine Datenbank-Schema-Validierung durch, wenn die Property isy.util.datasource.schema-version gesetzt ist.

Standardverhalten:

Bei einer inkorrekten Schema-Version schlägt der Anwendungsstart fehl.

Alternatives Verhalten:

Um bei einer inkorrekten Schema-Version lediglich eine Log-Nachricht auszugeben, muss die Property isy.util.datasource.schema-invalid-version-action auf warn gesetzt werden.

2.2.3. Manuelle Prüfung (optional)

Die Klasse DataSourceCheck stellt die Methode checkSchemaVersion() bereit. Diese gibt einen boolean-Wert zurück, auf den die Applikation entsprechend reagieren kann.

Listing 3. Durchführung einer Schema-Prüfung

class Demo {
    void startUp(DataSource dataSource, String version) {
        DataSourceCheck dsc = new DataSourceCheck();
        if(!dsc.checkSchemaVersion(dataSource, version)){
            // handle errors, do logging etc
        }
    }
}

2.2.4. Properties

Tabelle 2. Konfigurationsparameter des DataSource-Check
Parameter	Wertebereich	Default	Beschreibung
`isy.util.datasource.schema-version`	`String`	`null`	Die in der Datenbank konfigurierte Schema-Version
`isy.util.datasource.schema-invalid-version-action`	`String`	`fail`	Legt das Verhalten bei inkorrekter Schema-Version fest: * `fail`: Die Anwendung startet nicht. * `warn`: Die Anwendung loggt lediglich eine Warnung.

2.3. Enum-Variablen und Annotations

Zum vereinfachten Umgang mit Enum-Variablen im Zusammenhang mit Datenbanken steht die Annotation PersistentValue zur Verfügung.

public enum Richtung {

    @PersistentValue("L")
    LINKS,
    @PersistentValue("R")
    RECHTS,
    @PersistentValue("G")
    GERADEAUS

}

Die Klasse EnumWithIdUserType erlaubt die Persistierung von Enums, die einen fachlichen Schlüssel besitzen.

Listing 4. Definition eines Enums zur Verwendung mit EnumWithIdUserType

public enum RichtungMitId {

    LINKS("L"),
    RECHTS("R"),
    GERADEAUS("G");

    private final String id;

    RichtungMitId(String id) {
        this.id = id;
    }

    @EnumId
    public String getId() {
        return id;
    }

}

Das folgende Beispiel zeigt die Verwendung dieser Enums in einer Entität.

Listing 5. Verwendung von Enums in Entitäten

@Entity
public class MyEntity {

  @Column(nullable = false, length = 1)
  @Type(type = "de.bund.bva.isyfact.persistence.usertype.EnumUserType",
    parameters = { @Parameter(name = "enumClass",value = "<package>.Richtung") })
  private Richtung richtung;

  @Column(nullable = false, length = 1)
  @Type(type = "de.bund.bva.isyfact.persistence.usertype.EnumWithIdUserType",
    parameters = { @Parameter(name = "enumClass",value = "<package>.RichtungMitId") })
  private RichtungMitId richtungMitId;

}