LJC Lightning Talk: „JaVers: Easy Audit Logs in Java“
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:
Folien & Code
Die Folien stehen als PDF zur Verfügung:
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 dascustomer-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_PKist die global eindeutige ID unserer Objektversion: Über alle Objekte und Versionen hinweg hat nur eine bestimmte Version dieCOMMIT_PK100.AUTHORist der Benutzername, den wir oben an den JaVers-Aufrufcommit()übergeben haben.COMMIT_DATEist der Zeitpunkt, zu dem die Version erstellt wurde. JaVers setzt diesen Wert für uns.COMMIT_IDist die lokal eindeutige Versionsnummer unseres Objekts: Nur eine Version unseres Kunden mit der ID50hat dieseCOMMIT_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_PKist dieCOMMIT_PKaus derJV_COMMIT-Tabelle oben.TYPEistINITIAL, weil dies die erste Version ist. Spätere Versionen haben den TypUPDATE.STATEist unsereCustomer1-Instanz von oben, als JSON.CHANGED_PROPERTIESlistet 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_TYPEist 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
Customer1mit der ID50eingeschrä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.SHALLOWangegeben. - 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_IDausJV_COMMIT. Obwohl sie in der Datenbank1.0ist, liefertgetCommitId().value()1.00. Nach meiner Erfahrung können Sie die Nachkommastellen ignorieren, da die nächsten Versionen2.0,3.0und 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.0angegeben. - Wir haben JaVers angewiesen, verschachtelte Objekte mit
ShadowScope.DEEP_PLUSwiederherzustellen. Unsere KlasseCustomer1hatte 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 mitgetPropertyName(), den alten Wert mitgetLeft()und den neuen mitgetRight().NewObject— die neue Version enthält ein komplett neues Objekt. Klassennamen und ID des neuen Objekts bekommen Sie mitgetAffectedGlobalId().ObjectRemoved— die neue Version enthält ein bestimmtes Objekt nicht mehr. Auch hier bekommen Sie Klassennamen und ID mitgetAffectedGlobalId().ListChange— eine oder mehrere Änderungen sind in einer Liste der neuen Version passiert.getChanges()liefert diese alsList<ContainerElementChange>. DieseContainerElementChange-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 FeldcontactInfo. - Die Klasse
ContactInfohat eine Liste vonEmailAddress-Instanzen. EmailAddresshat ein Feldtypeund ein Feldaddress.
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_PK100 und 200). - Der Kunde ist die dritte Zeile (
SNAPSHOT_PK300). Sie enthält die Kontaktinformation als Referenz:
"contactInfo": { "entity": "com.company.product.dto.ContactInfo", "cdoId": 63 }
- Die referenzierte Kontaktinformation ist Datensatz Nummer vier (
SNAPSHOT_PK400). 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!