Zum Inhalt springen

LJC Lightning Talk: „JaVers: Easy Audit Logs in Java“

Veröffentlicht am · Aktualisiert am · 8 Min. Lesezeit
Audit-Log vergleicht zwei Versionen von Kundendaten

Teilen

Vortrag

Die London Java Community (LJC) veranstaltete regelmäßig Lightning Talks. Am Freitag, den 2. Oktober 2020, sprach ich dort darüber, wie JaVers Audit-Logs in Java einfach macht.

Ich danke Dominique Carlo und Barry Cranford von RecWorks dafür, dass sie diese Lightning Talks möglich machten! Wenn Sie Java-Entwickler in London suchen, ziehen Sie RecWorks in Betracht.

Video

Mein Vortrag steht auf YouTube im LJC-Kanal:

Video ansehen (YouTube)

Folien & Code

Die Folien stehen als PDF zur Verfügung:

Folien herunterladen (PDF)

Historischer Hinweis (Stand: Oktober 2020): Damals gab es die Folien zusätzlich im Original-Keynote-Format mit Animationen zum Download; diese Datei ist heute nicht mehr verfügbar.

Einstieg

Sie wollen Ihrer Anwendung mit JaVers ein Audit-Log hinzufügen? Wunderbar! Sie sind hier genau richtig!

Bibliothek & Konfiguration

Die „Getting Started“-Dokumentation von JaVers zeigt, wie Sie die Bibliothek in Ihre Anwendung einbinden. Es gibt drei Wege, JaVers einzubinden:

  • Spring Boot Starter — mit Abstand der einfachste Weg zu JaVers, und der, den ich in meiner Anwendung nutzte. Sie müssen eine Speicheroption für Ihre Versionen wählen: eine relationale Datenbank oder MongoDB. Stand 1. Oktober 2020 brauchte die aktuelle Spring-Boot-Starter-Version 5.12.0 Spring Boot 2.3. Wer noch Spring Boot 2.2 nutzte, brauchte JaVers-Version 5.9.4. Ich änderte keine der Konfigurationsoptionen.
  • Spring Integration — die Option für Spring ohne Spring Boot. Das habe ich nie genutzt.
  • Vanilla JaVers — funktioniert für alle Nicht-Spring-Umgebungen. Auch das habe ich nicht genutzt.

Der folgende Code nutzt die damals aktuelle Version des Spring Boot Starters, 5.12.0, mit einer relationalen Datenbank.

Eine Version erstellen

Wir erinnern uns: Wir versionieren die DTOs, die unsere Business-Schicht von der Benutzeroberfläche empfängt und an sie sendet. Nehmen wir also an, wir haben ein Kunden-DTO namens Customer1:

public class Customer1 {

  private Long id;
  private String firstName;
  private String lastName;

Jedes Objekt, das JaVers versioniert, braucht eine eindeutige ID. Zum Glück haben unsere DTOs die schon! Der einfachste Weg ist, das ID-Feld in unserem DTO mit der Annotation org.javers.core.metamodel.annotation.Id zu markieren, in Zeile 3:

public class Customer1 {

  @Id
  private Long id;
  private String firstName;
  private String lastName;

Jetzt sind wir bereit, eine erste Version dieses Kunden zu erstellen. Neben dem DTO brauchen wir nur einen Benutzernamen. Wir nehmen „joebloggs“:

private Javers javers;

  [...]

  Customer1 customer = new Customer1(50L, "Karsten", "Silz");
  this.javers.commit("joebloggs", customer);
  • Wir bekommen die Javers-Instanz per Dependency Injection.
  • Wir erstellen unser DTO.
  • Der Aufruf von commit() wandelt das customer-Objekt in JSON um und speichert eine Version in den JaVers-Tabellen.

Herzlichen Glückwunsch — wir haben unsere erste Version mit JaVers erstellt!

Die JaVers-Tabellen

JaVers nutzt vier Tabellen. Wir sehen uns die beiden wichtigsten an. Die erste heißt JV_COMMIT. Sie speichert einen Datensatz pro Version. Hier sind die wichtigen Spalten:

COMMIT_PK AUTHOR COMMIT_DATE COMMIT_ID
100 joebloggs 2020-10-01 18:46:27.567 1.0
  • COMMIT_PK ist die global eindeutige ID unserer Objektversion: Über alle Objekte und Versionen hinweg hat nur eine bestimmte Version die COMMIT_PK 100.
  • AUTHOR ist der Benutzername, den wir oben an den JaVers-Aufruf commit() übergeben haben.
  • COMMIT_DATE ist der Zeitpunkt, zu dem die Version erstellt wurde. JaVers setzt diesen Wert für uns.
  • COMMIT_ID ist die lokal eindeutige Versionsnummer unseres Objekts: Nur eine Version unseres Kunden mit der ID 50 hat diese COMMIT_ID.

JV_SNAPSHOT speichert die JSON-Daten:

SNAPSHOT_PK TYPE STATE CHANGED_PROPERTIES MANAGED_TYPE
100 INITIAL { "firstName": "Karsten", "lastName": "Silz", "id": 50 } ["firstName", "lastName", "id"] com.company.product.dto.Customer1
  • SNAPSHOT_PK ist die COMMIT_PK aus der JV_COMMIT-Tabelle oben.
  • TYPE ist INITIAL, weil dies die erste Version ist. Spätere Versionen haben den Typ UPDATE.
  • STATE ist unsere Customer1-Instanz von oben, als JSON.
  • CHANGED_PROPERTIES listet auf, welche Felder unseres Objekts sich gegenüber der letzten Version geändert haben. Da dies die erste Version ist, haben sich alle Felder geändert.
  • MANAGED_TYPE ist der vollständige Name unserer Klasse.

Alle Versionen abfragen

Jetzt, wo wir eine Version mit JaVers erstellt haben — wie fragen wir Versionen ab? JaVers gibt uns eine Abfragesprache mit sogenannter fluider Notation. Holen wir uns zunächst alle Versionen unseres Kunden-DTOs. Wir könnten das Ergebnis unseren Anwendern in einer Liste oder Tabelle zeigen:

JqlQuery allVersionsQuery =
    QueryBuilder.byInstanceId(50L, Customer1.class)
        .withShadowScope(ShadowScope.SHALLOW)
        .build();
List<CdoSnapshot> versions = this.javers.findSnapshots(allVersionsQuery);

for (CdoSnapshot aVersion : versions) {
  String versionNumber = aVersion.getCommitId().value();
  CommitMetadata commitMetadata = aVersion.getCommitMetadata();
  String author = commitMetadata.getAuthor();
  LocalDateTime time = commitMetadata.getCommitDate();
  System.out.println(
      "Version details: versionNumber=" + versionNumber
          + ", author=" + author
          + ", time=" + time);
}

Hier ist die Ausgabe mit nur einer Version:

Version details: versionNumber=1.00, author=joebloggs, time=2020-10-01T18:46:27.567

Was haben wir hier also gemacht?

  • Wir haben die Abfrage auf die Version der Klasse Customer1 mit der ID 50 eingeschränkt.
  • Unsere Objekte könnten verschachtelt sein und andere Objekte enthalten. Hier wollten wir nur einen Überblick, wir wollten diese verschachtelten Objekte nicht abrufen. Deshalb haben wir ShadowScope.SHALLOW angegeben.
  • Die eigentliche Abfrage liefert das, was JaVers einen Snapshot nennt. Er enthält unser versioniertes Objekt als Property-Map. Da wir hier nicht auf das versionierte Objekt zugreifen mussten, war das für uns in Ordnung.
  • JaVers liefert eine Liste von CdoSnapshot. Diese enthalten sowohl die Versionsinformationen als auch die eigentlichen Objekte.
  • Die Versionsnummer ist die sogenannte Commit-ID — COMMIT_ID aus JV_COMMIT. Obwohl sie in der Datenbank 1.0 ist, liefert getCommitId().value() 1.00. Nach meiner Erfahrung können Sie die Nachkommastellen ignorieren, da die nächsten Versionen 2.0, 3.0 und so weiter wären.
  • Wir bekommen den Autor der Version und den Zeitpunkt der Erstellung.

Eine einzelne Version abfragen

Im vorigen Abschnitt haben wir gesehen, wie wir alle Versionen unserer DTOs abrufen. Wie bekommen wir eine einzelne Version? Fast auf dieselbe Weise:

CommitId commitId = CommitId.valueOf("1.0");
JqlQuery oneVersionQuery =
    QueryBuilder.byInstanceId(50L, Customer1.class)
        .withCommitId(commitId)
        .withShadowScope(ShadowScope.DEEP_PLUS)
        .build();
List<Shadow<Customer1>> singleVersion = this.javers.findShadows(oneVersionQuery);

for (Shadow<Customer1> aVersion : singleVersion) {
  String versionNumber = aVersion.getCommitId().value();
  CommitMetadata commitMetadata = aVersion.getCommitMetadata();
  String author = commitMetadata.getAuthor();
  LocalDateTime time = commitMetadata.getCommitDate();
  Customer1 customer = aVersion.get();
  System.out.println(
      "Version details: versionNumber=" + versionNumber
          + ", author=" + author
          + ", time=" + time
          + ", customer=" + customer);
}

Hier ist die Ausgabe:

Version details: versionNumber=1.00, author=joebloggs, time=2020-10-01T18:46:27.567, customer=Customer1{id=50, firstName='Karsten', lastName='Silz'}

So haben wir für eine einzelne Version anders vorgegangen:

  • Wir haben die Commit-ID 1.0 angegeben.
  • Wir haben JaVers angewiesen, verschachtelte Objekte mit ShadowScope.DEEP_PLUS wiederherzustellen. Unsere Klasse Customer1 hatte keine verschachtelten Objekte, aber Objekte in echten Anwendungen haben das wahrscheinlich schon.
  • Wir haben nun nach sogenannten Shadows abgefragt. Sie enthalten unser versioniertes Objekt.

Versionen vergleichen

Die komplexeste Operation ist der Vergleich zweier Objekte. Warum? Weil es viele verschiedene Arten von Änderungen geben kann, jede als eigene Klasse in JaVers ausgedrückt. Der Vergleich zweier Objekte selbst ist einfach. Im folgenden Beispiel ändern sich sowohl Vor- als auch Nachname:

Customer1 oldOne = new Customer1(50L, "Karsten", "Silz");
Customer1 newOne = new Customer1(50L, "Joe", "Cool");
Diff differences = this.javers.compare(oldOne, newOne);
System.out.println("Differences: " + differences.prettyPrint());

Erwartungsgemäß fand JaVers beide Änderungen:

Differences: Diff:
* changes on com.betterprojectsfaster.talks.javers.customer1.Customer1/50 :
  - 'firstName' value changed from 'Karsten' to 'Joe'
  - 'lastName' value changed from 'Silz' to 'Cool'

In unseren Anwendungen brauchen wir meist die Details der Änderungen. So bekommen wir sie:

Customer1 oldOne = new Customer1(50L, "Karsten", "Silz");
Customer1 newOne = new Customer1(50L, "Joe", "Cool");
Diff differences = this.javers.compare(oldOne, newOne);
Changes listOfDifferences = differences.getChanges();

for (Change aChange : listOfDifferences) {
  System.out.println("  Change: " + aChange.toString());
}

Das ist die Ausgabe:

Change: ValueChange{ 'firstName' value changed from 'Karsten' to 'Joe' }
Change: ValueChange{ 'lastName' value changed from 'Silz' to 'Cool' }

In diesem Beispiel haben wir nur eine Art von Änderung bekommen — ValueChange-Instanzen. Hier sind einige der Änderungen, die Ihnen in Ihrer eigenen Arbeit begegnen, jede als eigene JaVers-Klasse ausgedrückt:

  • ValueChange — zeigt eine einzelne Feldänderung an. Sie bekommen den Feldnamen mit getPropertyName(), den alten Wert mit getLeft() und den neuen mit getRight().
  • NewObject — die neue Version enthält ein komplett neues Objekt. Klassennamen und ID des neuen Objekts bekommen Sie mit getAffectedGlobalId().
  • ObjectRemoved — die neue Version enthält ein bestimmtes Objekt nicht mehr. Auch hier bekommen Sie Klassennamen und ID mit getAffectedGlobalId().
  • ListChange — eine oder mehrere Änderungen sind in einer Liste der neuen Version passiert. getChanges() liefert diese als List<ContainerElementChange>. Diese ContainerElementChange-Instanzen können sein:
    • ElementValueChange — ein Element hat sich geändert. getIndex() liefert die Position in der Liste, getLeftValue() den alten Wert, getRightValue() den neuen.
    • ValueAdded — ein neues Element in der neuen Version. getIndex() liefert die Position, getAddedValue() den hinzugefügten Wert.
    • ValueRemoved — ein gelöschtes Element in der neuen Version. getIndex() liefert die Position, getRemovedValue() den entfernten Wert.

Verschachtelte Objekte

Unsere Klassen enthalten oft andere Klassen. Erweitern wir also unser Kunden-DTO um ein Kontaktinformations-DTO, das selbst eine Liste von E-Mail-Adressen-DTOs enthält:

public enum EmailType { PRIVATE, WORK }

public class EmailAddress {
  @Id private final Long id;
  private final EmailType type;
  private final String address;

  [...]
}

public class ContactInfo {
  @Id private final Long id;
  private final List<EmailAddress> emailAddresses;

  [...]
}

public class Customer2 {

  @Id private final Long id;
  private final String firstName;
  private final String lastName;
  private final ContactInfo contactInfo;

  [...]
}
  • Unsere neue Kunden-DTO-Klasse heißt Customer2. Sie hat ein Feld contactInfo.
  • Die Klasse ContactInfo hat eine Liste von EmailAddress-Instanzen.
  • EmailAddress hat ein Feld type und ein Feld address.

Erstellen wir also eine Version mit verschachtelten Objekten:

EmailAddress address1 = new EmailAddress(20L, EmailType.PRIVATE, "private@provider.com");
EmailAddress address2 = new EmailAddress(21L, EmailType.WORK, "work@provider.com");
ContactInfo info = new ContactInfo(63L, List.of(address1, address2));
Customer2 myCustomer = new Customer2(50L, "Karsten", "Silz", info);
this.javers.commit("runner1", myCustomer);

Was ergibt das in der Tabelle JV_SNAPSHOT? Da jedes verschachtelte Objekt ein ID-Feld hat, erwarten wir für jedes einen eigenen Eintrag. Und genau das passiert:

SNAPSHOT_PK TYPE STATE CHANGED_PROPERTIES MANAGED_TYPE
100 INITIAL { "address": "work@provider.com", "id": 21, "type": "WORK" } ["address", "id", "type"] com.company.product.dto.EmailAddress
200 INITIAL { "address": "private@provider.com", "id": 20, "type": "PRIVATE" } ["address", "id", "type"] com.company.product.dto.EmailAddress
300 INITIAL { "firstName": "Karsten", "lastName": "Silz", "contactInfo": { "entity": "com.company.product.dto.ContactInfo", "cdoId": 63 }, "id": 50 } ["firstName", "lastName", "contactInfo", "id"] com.company.product.dto.Customer2
400 INITIAL { "emailAddresses": [ { "entity": "com.company.product.dto.EmailAddress", "cdoId": 20 }, { "entity": "com.company.product.dto.EmailAddress", "cdoId": 21 } ], "id": 63 } ["emailAddresses", "id"] com.company.product.dto.ContactInfo
  • Die beiden E-Mail-Adressen belegen die ersten beiden Datensätze (SNAPSHOT_PK 100 und 200).
  • Der Kunde ist die dritte Zeile (SNAPSHOT_PK 300). Sie enthält die Kontaktinformation als Referenz:
"contactInfo": { "entity": "com.company.product.dto.ContactInfo", "cdoId": 63 }
  • Die referenzierte Kontaktinformation ist Datensatz Nummer vier (SNAPSHOT_PK 400). Er enthält ebenfalls die beiden E-Mail-Adressen als Referenzen:
{ "emailAddresses": [
  { "entity": "com.company.product.dto.EmailAddress", "cdoId": 20 },
  { "entity": "com.company.product.dto.EmailAddress", "cdoId": 21 }
] }

Bekommen wir nun, wenn wir eine Instanz von Customer2 mit JaVers abrufen, auch alle verschachtelten Objekte?

CommitId commitId = CommitId.valueOf("1.0");
JqlQuery oneVersionQuery =
    QueryBuilder.byInstanceId(50L, Customer2.class)
        .withCommitId(commitId)
        .withShadowScope(ShadowScope.DEEP_PLUS)
        .build();
List<Shadow<Customer2>> singleVersion = this.javers.findShadows(oneVersionQuery);

for (Shadow<Customer2> aVersion : singleVersion) {
  Customer2 customer = aVersion.get();
  System.out.println("Customer=" + customer);
}

Ja, das tun wir (zur Anzeige formatiert):

Customer: Customer2{id=50, firstName='Karsten', lastName='Silz',
  contactInfo=ContactInfo{id=63, emailAddresses=[
    EmailAddress{id=20, type=PRIVATE, address='private@provider.com'},
    EmailAddress{id=21, type=WORK, address='work@provider.com'}
  ]}
}

Versionierung anpassen

In diesem letzten Abschnitt nehmen wir ein paar sinnvolle Anpassungen vor. Erinnern wir uns an die erste Klasse, die wir versioniert haben:

public class Customer1 {

  @Id
  private Long id;
  private String firstName;
  private String lastName;

Sie erzeugte diesen Versionseintrag in JV_SNAPSHOT:

SNAPSHOT_PK TYPE STATE CHANGED_PROPERTIES MANAGED_TYPE
100 INITIAL { "firstName": "Karsten", "lastName": "Silz", "id": 50 } ["firstName", "lastName", "id"] com.company.product.dto.Customer1

Die JSON-Daten sind ziemlich ausführlich. Da wir in echten Anwendungen viele Versionen speichern würden, spart eine Verkleinerung der JSON-Größe Datenbankplatz. Was können wir also tun?

Ich habe tatsächlich einen Artikel bei Baeldung darüber geschrieben, wie man genau das macht. Ich frage mich, was mich da wohl inspiriert hat? 🤔 Die eine Technik, die hier zutrifft, ist die Verwendung kurzer Feldnamen. Statt "firstName": "Karsten" bekommen wir also "f": "Karsten". Im Artikel reduzierte das die JSON-Datengröße um mehr als 25 %. Da die Feldnamen auch in der Spalte CHANGED_PROPERTIES erscheinen, verringert das ebenfalls den Datenbankplatz, den unsere Versionen belegen!

Wenden wir also kurze Feldnamen in unserer neuen DTO-Klasse Customer3 an. JaVers gibt uns die Annotation org.javers.core.metamodel.annotation.PropertyName, um den Feldnamen in der Datenbank festzulegen:

public class Customer3 {

  @Id
  @PropertyName("i")
  private Long id;
  @PropertyName("f")
  private String firstName;
  @PropertyName("l")
  private String lastName;

Das ergibt folgenden Eintrag in JV_SNAPSHOT:

SNAPSHOT_PK TYPE STATE CHANGED_PROPERTIES MANAGED_TYPE
101 INITIAL { "f": "Karsten", "l": "Silz", "i": 50 } ["f", "l", "i"] com.company.product.dto.Customer3

Wie Sie sehen, verwenden sowohl STATE als auch CHANGED_PROPERTIES die einbuchstabigen Feldnamen. Schöne Ersparnis!

Über die Platzersparnis hinaus ist das spätere Refactoring unserer Java-Klassen ein weiterer Grund für angepasste Feldnamen. Stellen wir uns vor, wir benennen lastName in unserer Java-Klasse in familyName um. Das würde den Abruf alter Versionen zerstören: Die JSON-Daten in der Datenbank haben lastName für die alten Versionen und familyName für die neuen. Aber mit der Annotation @PropertyName("l") speichern alle Versionen den Feldnamen als l im JSON.

Eine Sache fällt im obigen Datenbankeintrag noch auf: Der Wert in der Spalte MANAGED_TYPE ist der vollständig qualifizierte Klassenname com.company.product.dto.Customer3. Dafür gibt es ebenfalls eine Annotation — org.javers.core.metamodel.annotation.TypeName:

@TypeName("C3")
public class Customer3 {

  @Id
  @PropertyName("i")
  private Long id;
  @PropertyName("f")
  private String firstName;
  @PropertyName("l")
  private String lastName;

Jetzt wird’s gut:

SNAPSHOT_PK TYPE STATE CHANGED_PROPERTIES MANAGED_TYPE
101 INITIAL { "f": "Karsten", "l": "Silz", "i": 50 } ["f", "l", "i"] C3

Kompakter geht es nicht!

Eine weitere Anpassung ist der Ausschluss von Feldern aus der Versionierung. Sagen wir, wir fügen der Klasse selbst die Anzahl der Versionen hinzu, berechnet durch eine Abfrage der Versionen, bevor wir das Objekt an unser Front-End senden. Dieses Feld wollen wir nicht in unseren Versionsdaten. Zu unserem Glück lässt uns die Annotation org.javers.core.metamodel.annotation.DiffIgnore Felder von JaVers ignorieren:

@TypeName("C2")
public class Customer2 {

  @Id
  @PropertyName("i")
  private Long id;
  @PropertyName("f")
  private String firstName;
  @PropertyName("l")
  private String lastName;
  @DiffIgnore
  private Integer numberOfVersions;

Fazit

Damit ist unsere Code-Einführung abgeschlossen. Fassen wir zusammen:

  • Wir haben damit begonnen, wie man JaVers zu seinen Projekten hinzufügt.
  • Wir haben eine Klasse genommen und eine Version davon erstellt.
  • Dann haben wir JaVers nach allen Versionen und nach einer einzelnen Version abgefragt.
  • Als Nächstes haben wir zwei Instanzen einer Klasse verglichen.
  • Verschachtelte Objekte und ihre Versionierung waren die nächste Station unserer Tour.
  • Zum Schluss haben wir uns die Anpassung der Versionierung angesehen.

Besuchen Sie JaVers und bauen Sie ein großartiges Audit-Log in Ihre Java-Anwendung ein!