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 Klasse DataSourceCheck, mit der Datenbanktabellen auf die richtige Schema-Version geprüft werden können. Mit der Klasse ApplicationRunnerDbSchemaCheck kann diese Prüfung beim Start einer Spring-Anwendung automatisiert werden.
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. Datasource-Check

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.

Eine Anfrage mit dem DataSourceCheck erfolgt über eine der Methoden checkSchemaVersionCriticalDataSource oder checkSchemaVersionNonCriticalDataSource. Beide Methoden liefern ein boolean zurück, auf das die Applikation entsprechend regieren kann.

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

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

Voraussetzung ist die Existenz einer Datenbank-Tabelle, die die aktuelle Schema-Version enthält. Der DataSourceCheck fragt die Tabelle mit einem voreingestellten SQL-Statement ab.

Listing 3. Abfrage der Schema-Tabelle (Standard)

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

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

Tabelle 1. Beispielhafte 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.

Andere Formen der Schema-Tabelle können ebenfalls verwendet werden. In diesem Fall muss bei der Erzeugung das DataSourceCheck die geeignete SQL-Abfrage als Parameter angegeben werden.

Für Spring-Anwendungen existiert der Wrapper ApplicationRunnerDbSchemaCheck, der als Spring-Komponente hinzugefügt wird und als Implementierung eines ApplicationRunner nach vollständiger Initialisierung der Spring-Anwendung den Check automatisch durchführt.

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;

}