«…и мы должны иметь возможность видеть, когда, как и кто изменил данные» — распространённая хотелка при разработке приложения, работающего с БД.
Заказчик обычно хочет видеть, для некоторых таблиц, какие изменения в них вносились, когда вносились, кем вносились и какие были предыдущие значения. Существует множество решений этой задачи: можно обвесить необходимые таблицы триггерами, можно сохранять объекты с помощью хранимых процедур, можно перехватывать запросы к базе с помощью AOP и так далее. Hibernate предлагает собственно решение, envers, решающее задачу ведения истории с помощью одной аннотации.
Настройка envers
Чтобы включить автоматическое ведение истории изменений, необходимо выполнить два шага:
- Добавить библиотеку envers в classpath:
|
1
2
3
4
5
|
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-envers</artifactId>
<version>5.2.0.Final</version>
</dependency>
|
- Добавить аннотацию @Audited к классам, для которых требуется отслеживание истории изменении. Рекоменуется добавить эту аннотацию так же и к классам, имеющим связи с классами, уже помеченными @Audited. Далее в статье я буду использовать сущности из примера HQL.
|
1
2
3
4
5
6
7
8
9
|
@Entity
@Audited
public class Person extends AbstractIdentifiableObject {
@Getter
@Setter
private String firstName;
/* other fields */
}
|
- имя_сущности_AUD — для хранения исторических данных. Эти таблицы состоят из поля id отслеживамой сущности, поля rev, в котором хранится номер редакции, поля revtype, в котором хранится тип изменения (создано/модифицировано/удалено) и все отслеживаемые поля оригинальной сущности.
- REVINFO — для хранения списка ревизий. В этой таблице хранятся номера ревизий и время их создания. Так же в этой таблице можно хранить дополнительные данные, такие как имя пользователя, создавшего ревизию, например.
Когда
Для начала ответим на вопрос «Когда были изменены данные». Создадим пробную персону и проверим, как это отразилось в истории.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
|
Passport p = new Passport();
p.setSeries("AS");
p.setNo("123456");
p.setIssueDate(LocalDate.now());
p.setValidity(Period.ofYears(20));
Address a = new Address();
a.setCity("Kickapoo");
a.setStreet("Main street");
a.setBuilding("1");
Person person = new Person();
person.setFirstName("Test");
person.setLastName("Testoff");
person.setDob(LocalDate.now());
person.setPrimaryAddress(a);
person.setPassport(p);
Company c = new Company();
c.setName("Acme Ltd");
p.setOwner(person);
person.setWorkingPlaces(Collections.singletonList(c));
Session session = sessionFactory.openSession();
session.beginTransaction();
session.merge(person);
session.getTransaction().commit();
session.close();
|
|
1
2
3
4
5
6
7
8
|
Object[] result = (Object[]) AuditReaderFactory
.get(session)
.createQuery()
.forRevisionsOfEntity(Person.class, false, true)
.getSingleResult();
System.out.println(result[0]);
System.out.println(result[1]);
System.out.println(result[2]);
|
Запрос forRevisionsOfEntity() возвращает данные о изменениях сущности. Первый параметр задаёт класс сущности, второй параметр регулирует, хотим ли мы получить только ревизии ( true) или ревизии и данные сущностей ( false). В первом случае возвращаются объекты ревизий, во втором — массив из трех объектов: данные сущности в ревизии, ревизия, тип изменения. Наконец последний параметр регулирует, включать ли в вывод удалённые записи или нет.
|
1
2
3
|
Person{firstName='Test', lastName='Testoff', dob=2016-08-25, passport=Passport{series='AS', no='123456', issueDate=2016-08-25, validity=P20Y, owner=Testoff}, primaryAddress=Address{city='Kickapoo', street='Main street', building='1', tenants=Test}, workingPlaces=[Company{name='Acme Ltd', workers=Test}]}
DefaultRevisionEntity(id = 1, revisionDate = 25.08.2016 11:02:15)
ADD
|
В результате мы видим, что в ревизии 1, созданной сегодня, 25 августа, в 11:02, была добавлена сущность Person и отображены её данные.
Как
Когда изменились данные мы видим, но интересно было бы посмотреть в динамике — какие были значения, какие стали. Попробуем изменить ранее созданную персону:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
// Set new name
session = sessionFactory.openSession();
session.beginTransaction();
Person p = (Person) session
.createCriteria(Person.class)
.add(Restrictions.eq("firstName", "Test"))
.uniqueResult();
p.setFirstName("Johan");
p.setLastName("von Testow");
session.save(p);
session.getTransaction().commit();
session.close();
|
|
1
2
3
4
5
6
7
8
9
10
11
|
AuditReaderFactory
.get(session)
.createQuery()
.forRevisionsOfEntity(Person.class, false, true)
.getResultList()
.forEach(r -> {
Object[] v = (Object[])r;
System.out.println(v[0]);
System.out.println(v[1]);
System.out.println(v[2]);
});
|
|
1
2
3
4
5
6
|
Person{firstName='Test', lastName='Testoff', dob=2016-08-25, passport=Passport{series='AS', no='123456', issueDate=2016-08-25, validity=P20Y, owner=Testoff}, primaryAddress=Address{city='Kickapoo', street='Main street', building='1', tenants=Test}, workingPlaces=[Company{name='Acme Ltd', workers=Test}]}
DefaultRevisionEntity(id = 1, revisionDate = 25.08.2016 11:16:14)
ADD
Person{firstName='Johan', lastName='von Testow', dob=2016-08-25, passport=Passport{series='AS', no='123456', issueDate=2016-08-25, validity=P20Y, owner=von Testow}, primaryAddress=Address{city='Kickapoo', street='Main street', building='1', tenants=Johan}, workingPlaces=[Company{name='Acme Ltd', workers=Johan}]}
DefaultRevisionEntity(id = 2, revisionDate = 25.08.2016 11:16:14)
MOD
|
В этот раз я запрашиваю список ревизий и сразу вижу, что над сущностью Person было проведено две операции — создание записи и изменение данных. В обоих случаях видно когда была проведена операция и как стала выглядеть изменяемая сущность.
Очевидно, что выборка по всей истории изменений не так интересна, как выборка только по интересующему объекту. В AuditQuery можно задавать критерии выборки используя похожий на Criteria API подход. Создадим новую персону и проведём над ней несколько действий:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
|
session = sessionFactory.openSession();
session.beginTransaction();
Address address = p.getPrimaryAddress();
session.detach(address);
address.setId(null);
Passport passport = new Passport();
passport.setSeries("TT");
passport.setNo("250816");
passport.setIssueDate(LocalDate.now());
passport.setValidity(Period.ofYears(20));
Person person = new Person();
person.setFirstName("Brunhild");
person.setLastName("Testonkowski");
person.setDob(LocalDate.now());
person.setPrimaryAddress(p.getPrimaryAddress());
person.setPassport(passport);
passport.setOwner(person);
session.save(person);
session.getTransaction().commit();
session.close();
session = sessionFactory.openSession();
session.beginTransaction();
person.setLastName("von Testow");
person.getPassport().setSeries("VT");
person.getPassport().setNo("101731");
session.merge(person);
session.getTransaction().commit();
session.close();
|
|
1
2
3
4
5
6
7
8
9
10
11
12
|
AuditReaderFactory
.get(session)
.createQuery()
.forRevisionsOfEntity(Person.class, false, true)
.add(AuditEntity.property("firstName").eq("Brunhild"))
.getResultList()
.forEach(r -> {
Object[] v = (Object[])r;
System.out.println(v[0]);
System.out.println(v[1]);
System.out.println(v[2]);
});
|
В запросе к истории я делаю ограничение по значению поля firstName, что позволяет мне просмотреть не всю историю изменений, а только по персоне с именем Брунгильда.
|
1
2
3
4
5
6
|
Person{firstName='Brunhild', lastName='Testonkowski', dob=2016-08-25, passport=Passport{series='TT', no='250816', issueDate=2016-08-25, validity=P20Y, owner=Testonkowski}, primaryAddress=Address{city='Kickapoo', street='Main street', building='1', tenants=Brunhild}, workingPlaces=[]}
DefaultRevisionEntity(id = 3, revisionDate = 25.08.2016 11:16:14)
ADD
Person{firstName='Brunhild', lastName='von Testow', dob=2016-08-25, passport=Passport{series='VT', no='101731', issueDate=2016-08-25, validity=P20Y, owner=von Testow}, primaryAddress=Address{city='Kickapoo', street='Main street', building='1', tenants=Brunhild}, workingPlaces=[]}
DefaultRevisionEntity(id = 4, revisionDate = 25.08.2016 11:16:14)
MOD
|
Можно так же убедиться, что изменения в связанных таблицах так же записываются:
|
1
2
3
4
5
6
7
8
9
10
11
|
AuditReaderFactory
.get(session)
.createQuery()
.forRevisionsOfEntity(Passport.class, false, true)
.getResultList()
.forEach(r -> {
Object[] v = (Object[])r;
System.out.println(v[0]);
System.out.println(v[1]);
System.out.println(v[2]);
});
|
|
1
2
3
4
5
6
7
8
9
10
11
12
|
Passport{series='AS', no='123456', issueDate=2016-08-25, validity=P20Y, owner=Testoff}
DefaultRevisionEntity(id = 1, revisionDate = 25.08.2016 11:16:14)
ADD
Passport{series='TT', no='250816', issueDate=2016-08-25, validity=P20Y, owner=Testonkowski}
DefaultRevisionEntity(id = 3, revisionDate = 25.08.2016 11:16:14)
ADD
Passport{series='VT', no='101731', issueDate=2016-08-25, validity=P20Y, owner=von Testow}
DefaultRevisionEntity(id = 4, revisionDate = 25.08.2016 11:16:14)
MOD
Passport{series='null', no='null', issueDate=null, validity=null, owner=None}
DefaultRevisionEntity(id = 5, revisionDate = 25.08.2016 11:16:14)
DEL
|
Наконец, кроме просмотра истории ревизий, можно запросить и конкретную ревизию:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
session = sessionFactory.openSession();
session.beginTransaction();
System.out.println(
session
.createCriteria(Person.class)
.add(Restrictions.eq("firstName", "Johan"))
.uniqueResult()
);
System.out.println(
AuditReaderFactory
.get(session)
.createQuery()
.forEntitiesAtRevision(Person.class, 1)
.getSingleResult()
);
session.getTransaction().commit();
session.close();
|
|
1
2
|
Person{firstName='Johan', lastName='von Testow', dob=2016-08-25, passport=Passport{series='AS', no='123456', issueDate=2016-08-25, validity=P20Y, owner=von Testow}, primaryAddress=Address{city='Kickapoo', street='Main street', building='1', tenants=Johan}, workingPlaces=[Company{name='Acme Ltd', workers=Johan}]}
Person{firstName='Test', lastName='Testoff', dob=2016-08-25, passport=Passport{series='AS', no='123456', issueDate=2016-08-25, validity=P20Y, owner=Testoff}, primaryAddress=Address{city='Kickapoo', street='Main street', building='1', tenants=Test}, workingPlaces=[Company{name='Acme Ltd', workers=Test}]}
|
forEntitiesAtRevision() создаёт запрос, достающие значение сущности заданного класса для заданной ревизии. На него так же можно накладывать критерии, как и на предыдущий запрос. В примере выше мы видим, что текущее состояние сущности и её историческое состояние отличаются.
Кто
Самый интересный вопрос — кто же внёс изменения в таблицу. Hibernate сам не записывает такую информацию, так как не знаком со структурой кажжого приложения в мире, поэтому для записывания данных пользователя придётся немного потрудится.
В первую очередь расширим сущность ревизии с тем, чтобы добавить в неё дополнительное поле:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
|
/**
* Custom revision entity that holds additional data.
*/
@Entity
@RevisionEntity(UserRevisionListener.class)
class UserRevision extends DefaultRevisionEntity {
/**
* User who created that revision.
*/
@Getter
@Setter
private String username;
}
|
Аннотация @RevisionEntity ссылается на UserRevisionListener, который будет вызываться для заполнения дополнительных полей ревизии. Пока что я буду писать в него константную строку, но в реальной жизни там будет больше кода:
|
1
2
3
4
5
6
7
8
9
10
11
12
|
/**
* Custom revision entity processor.
*/
class UserRevisionListener implements RevisionListener {
private final static String USERNAME = "vpupkin";
@Override
public void newRevision(Object o) {
UserRevision r= (UserRevision) o;
r.setUsername(USERNAME);
}
}
|
Наконец, надо не забыть добавить собственную сущность ревизии в конфигурацию маппинга:
|
1
|
<mapping class="ru.easyjava.data.hibernate.envers.UserRevision"/>
|
Результат на лицо:
|
1
2
3
|
Person{firstName='Test', lastName='Testoff', dob=2016-08-25, passport=Passport{series='AS', no='123456', issueDate=2016-08-25, validity=P20Y, owner=Testoff}, primaryAddress=Address{city='Kickapoo', street='Main street', building='1', tenants=Test}, workingPlaces=[Company{name='Acme Ltd', workers=Test}]}
UserRevision(super=DefaultRevisionEntity(id = 5, revisionDate = 25.08.2016 12:10:08), username=vpupkin)
ADD
|
Envers и JPA
Механизм envers будет работать и при использовании Hibernate в качестве JPA Implementation, но с небольшими изменениями. При создании AuditQuery надо передавать объект EntityManager, а не Session и не требуется явно регистрировать собственную сущность ревизий.
Код примера доступен на github.