artigo

José Yoshiriro Ajisaka Ramos

(jyoshiriro@gmail.com): bacharel em Sistema
de Informação (IESAM). Mestrando em
Ciência da Computação (UFPA). Instrutor na
Equilibrium Web e na UAB. Engenheiro de
software do Tribunal de Justiça do Pará. Possui
as certificações SCJP, SCWCD e SCBCD. Trabalha
com Java há 6 anos.

Márcia Amaral
(eme.amaral@gmail.com): bacharel em Ciência
da Computação (UFPA). Analista de Sistemas
do Tribunal de Justiça do Pará. "Java Girl" há
mais de 8 anos. Eterna estudante de novas
tecnologias.

Auditoria Avançada de Persistência

com Hibernate, JPA e Envers
Aprenda como implementar um robusto e completo sistema de
auditoria de persistência com o Hibernate em conjunto com o Envers

A auditoria sobre as operações de banco de dados é importantíssima, quando não,

indispensável em sistemas de porte corporativo. Essa importância surge a partir de
necessidades como correção de inconsistências de dados, detecção de incidentes
de segurança etc. Caso os requisitos de um sistema exijam muitos detalhes na
auditoria de persistência, torna-se necessário o uso de ferramentas de alto nível
para cumpri-los com eficiência. Este artigo visa apresentar o “caminho das pedras”
para implementar auditoria em persistência objeto relacional com Hibernate, JPA e
Envers, apresentando um grande leque de recursos para esse tipo de tarefa.

A uditar a persistência permite analisar operações que envolvem

o acesso a bancos de dados. Uma boa auditoria de persistência
deve fornecer informações sobre as operações nas tabelas envolvidas:
Muito provavelmente, o tipo de auditoria mais usado atualmente é o basea-
do em Stored Procedures e Triggers de bancos de dados. As técnicas aborda-
das neste artigo não entram em conflito com tais mecanismos, podendo até
t
RVFN
JOTFSJV
FEJUPV
FYDMVJV
PV
BUÏ
NFTNP
DPOTVMUPV
JOGPSNBÎÜFT
trabalhar em conjunto.
t
RVF
JOGPSNBÎÜFT
GPSBN
FOWPMWJEBT
t
DPNP
FTUBWBN
BOUFT
F
DPNP
mDBSBN
EFQPJT
Este artigo visa apresentar uma robusta e flexível ferramenta para implemen-
t
RVBOEP
GPJ
GFJUP tação de auditoria de persistência, composta pelos frameworks Hibernate,
JPA e Envers tendo como foco principal o último, que é quem possibilita que
O nível de detalhe das informações geradas pela auditoria deve ser suficiente a tecnologia de mapeamento objeto relacional dos demais possa contar com
para que seja possível “desfazer” operações sempre que necessário. um forte sistema de auditoria.

51
 "SUJHP
t
"VEJUPSJB
"WBOÎBEB
EF
1FSTJTUÐODJB
DPN
)JCFSOBUF
+1"
F
&OWFST

Hibernate e Envers
O Hibernate é um framework de mapeamento objeto relacional muito
popular entre os desenvolvedores Java. Atualmente, ele pode ser usado
de duas maneiras: como “Hibernate Core” ou provedor de persistência
JPA (Java Persistence API).
Na primeira, não se depende dos recursos da JPA, podendo lançar mão
de vários recursos exclusivos, como Criteria, por exemplo. Os recursos
exclusivos do Hibernate Core que possibilitam a implementação de
auditoria são os Interceptors e Events, que não fazem parte do escopo
deste artigo.
Na segunda, ele se comporta como uma implementação da JPA. A bi-
blioteca que permite que o Hibernate seja usado como provedor JPA é a
“Hibernate Entity Manager”. É só com esse tipo de uso que é possível usar
o framework Envers para auditoria de persistência.
O JPA é a tecnologia padrão de mapeamento objeto relacional do Java.
Na edição 37 da Mundoj, o artigo “Auditando persistência com JPA” apre-
sentou o mecanismo de Listeners de Callbacks, que permite a implemen-
tação de auditoria com JPA. Neste artigo, foram abordados os pontos
fracos de se implementar auditoria com JPA, que são a não “escuta” dos
Listaners aos métodos invocados de Query e a não-obtenção do estados
“antes e depois” dos objetos envolvidos na operação de persistência.
Conforme será apresentado nas próximas seções, o Envers supera essas
limitações e ainda oferece funcionalidades exclusivas.
O Envers é um framework que permite criar auditoria através do controle
de versões de persistência em mapeamentos objetos relacionais feitos
com o Hibernate como provedor JPA. A grande inovação é a geração e
alimentação automáticas de tabelas que permitem o controle de versões
dos conteúdos das tabelas mapeadas. Cada vez que uma tabela sofre al-
terações em seus registros, uma nova “versão” dela é gerada pelo Envers.
Assim, este framework torna opcional a criação de tabelas e programa-
ção de módulos de sistemas para armazenar as informações de auditoria.
O Hibernate e o Envers são mantidos pela JBoss.org e, em 30 de outubro
de 2008, o Envers tornou-se um módulo do Hibernate. Todavia, sua bi-
blioteca ainda não vem junto do Hibernate, sendo necessário fazer seu
download separadamente. Segundo o site da JBoss, o Hibernate 3.5 já
trará as bibliotecas do Envers juntos das suas, assim como já ocorre com
C3P0, Ehcache e outros frameworks. Nessa versão, provavelmente será
possível usar o Envers também em conjunto com o Hibernate Core e não
apenas com o Hibernate como provedor JPA.
Criando auditoria de persistência com o
framework Envers
Até o fechamento desta edição, a versão atual do Envers era 1.2.1 GA,
compatível com as versões 3.3.x do Hibernate. É com estas configurações
que este artigo irá apresentar sua proposta. A seguir, um passo-a-passo
de como configurar o Envers em seu projeto.

NBJT
BT
UBCFMBT
EF
VTP
EP
&OWFST


SFTQFDUJWBNFOUF

TVBT
UBCFMBT
EF
BVEJUPSJB


1BTTP Instalação de bibliotecas. A biblioteca do Envers é composta
de um único arquivo, o “envers-X.ga-hibernate-3.Y.jar”, em que X e Y são
as versões do Envers e Hibernate da biblioteca, respectivamente. Outras
bibliotecas necessárias são:
t
)JCFSOBUF
&OUJUZ
.BOBHFS



1BTTP Configuração do Hibernate. Deve-se configurar o Hibernate
para que ele trabalhe em conjunto com o Envers. Na Listagem 1 há um
exemplo de como isso pode ser feito em arquivo de configuração JPA.
Listagem 1. Configuração do Envers no persistence.xml de um projeto
Hibernate/JPA.
<persistence-unit ...>
...
<properties>
<!-- configurações comuns -->
<property name="hibernate.ejb.event.post-insert"
value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.post-update"
value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.post-delete"
value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.pre-collection-update"
value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.pre-collection-remove"
value="org.hibernate.envers.event.AuditEventListener" />
<property name="hibernate.ejb.event.post-collection-recreate"
value="org.hibernate.envers.event.AuditEventListener" />
</properties>
</persistence-unit>
Em seu modo padrão de configuração (o que está sendo apresentado até
agora), o Envers precisa de uma tabela auxiliar para cada tabela “oficial”
do sistema cuja classe de entidade for marcada para auditoria, além de
uma tabela auxiliar única por todo o projeto. Por isso, é uma boa prática
configurar a criação automática de tabelas com a propriedade “hbm2ddl.
auto” do Hibernate. A figura 1 mostra como seria um DER preparado para
o trabalho com o Envers se houvessem apenas duas tabelas no sistema
(tabela “jogador” e tabela “time_futebol”). Detalhes sobre essas tabelas
estão na seção “Armazenamento das Informações pelo Envers”.
'JHVSB

%&3
QBSB
EVBT
UBCFMBT
iKPHBEPSw
F
iUJNF@GVUFCPMw
"T
UBCFMBT
iKPHBEPS@BVEw
F
iUJNF@GVUFCPM@BVEw
TÍP
individual.
A tabela “revinfo” é usada por todas as tabelas com sufixo “_aud”. E existe
uma tabela com esse sufixo para cada tabela cuja entidade for marcada
t
)JCFSOBUF
 para auditoria com o Envers (veja como fazer isso no próximo passo).

52 www.mundoj.com.br
 "SUJHP
t
"VEJUPSJB
"WBOÎBEB
EF
1FSTJTUÐODJB
DPN
)JCFSOBUF

+1"
F
&OWFST

1BTTP Indicar quais tabelas serão auditadas. Com uma simples ano-
tação é possível indicar quais classes de entidade fiquem sob a escuta do
Envers e passarão a fazer parte de seu controle de versão. É a anotação @
import org.hibernate.envers.Audited. Na Listagem 2 há um exemplo de
como usá-la.
Listagem 2. Marcando a classe de entidade “Jogador” para auditoria com
o Envers.
import org.hibernate.envers.Audited;
@Audited
@Entity
@Table(name = "jogador")
public class Jogador implements java.io.Serializable {
// campos e métodos...
}
Se estes três passos forem executados corretamente, sua aplicação já
estará sob a auditoria e controle de versão de tabelas do Envers.
Armazenamento das informações pelo Envers
Vamos supor que na tabela “time_futebol” foram feitas as seguintes
operações a partir de um projeto que usa Hibernate, JPA e Envers confi-
gurado no modelo padrão:
1. dois times foram inseridos;
2. o registro de um time sofreu alterações;
3. o registro de um time foi excluído.
As figuras 2 e 3 mostram como ficariam as tabelas “time_futebol_aud” e
“revinfo”, respectivamente.
'JHVSB

5BCFMB
iUJNF@GVUFCPM@BVEw
BQØT
BMHVNBT
PQFSBÎÜFT
B
QBSUJS
EB
BQMJDBÎÍP
DPN

)JCFSOBUF
F
&OWFST

'JHVSB

5BCFMB
iSFWJOGPw
BQØT
BMHVNBT
PQFSBÎÜFT
B
QBSUJS
EB
BQMJDBÎÍP
DPN
)JCFSOBUF
F
&OWFST

Uma característica fantástica deste framework é que ele escuta tanto as
operações feitas os métodos CRUD da interface EntityManager (persist,
merge ,remove e find) quanto às operações feitas pelo uso do método
“executeUpdate()” da interface Query.
Como o leitor deve ter percebido, o Envers torna muito produtiva a cria-
ção de auditoria ao acesso a bancos de dados, uma vez que ele assume
a responsabilidade pelas tabelas de auditoria as quais formam históricos
parecidos com o que vemos em sistemas de controle de versão de arqui-
vos, como CVS e Subversion, por exemplo.
$BNQPT
EBT
UBCFMBT
JOEJWJEVBJT
EF
BVEJUPSJB
mHVSB
As tabelas de auditoria individuais, as que terminam com “_BVE” pos-
suem os mesmos campos das tabelas as quais auditam e mais estes:
i3&75:1&w indica o tipo de operação, em que:
iw
indica novo registro
iw indica edição de registro
iw indica exclusão
i3&7w faz a ligação com o campo de mesmo nome na tabela iSFWJOGPw.
$BNQPT
EB
UBCFMB
DFOUSBM
EF
DPOUSPMF
EF
PQFSBÎÜFT
mHVSB

O Envers usa uma tabela para centralizar o controle de operações, a “re-
WJOGP”. Ela possui os seguintes campos:

i3&7w faz a ligação com as tabelas de auditoria individuais (as de final
“_BVE”). O valor de REV é único por aplicação que usa o Envers, indepen-
dentemente de quantas tabelas estão sendo auditadas.
i3&7545.1w indica o momento exato (o “timestamp”) em que a ope-
ração ocorreu.
Recursos avançados de auditoria com Envers
Os recursos abordados até aqui são suficientes para um sistema mínimo de
auditoria, mas não para um sistema profissional em um ambiente corporati-
vo. Para tal, é necessário saber pelo menos que usuário foi responsável pelas
operações realizadas. É hora de "lançar mão" do recurso de escuta de revisão
(Revision Listener) do Envers e criar uma classe para ser a “entidade de revisão”
do projeto.
Uma “entidade de revisão” é a classe que será usada para representar a tabela
“revinfo”, portanto, deve estar mapeada como uma entidade JPA. Ela pode
ser criada estendendo a classe org.hibernate.envers.DefaultRevisionEntity e
criando os campos que achar importante para a auditoria. Essa classe também
deve ser anotada com @org.hibernate.envers.RevisionEntity para indicar qual
classe de escuta de revisões (Revision Listener) irá gerenciá-la. Há um exemplo
de entidade de revisão na Listagem 3.
Se você preferir que sua tabela central de auditoria não se chame “revinfo”,
basta usar outra palavra no atributo “name” na anotação @Entity ou mesmo
omiti-lo para aproveitar o nome da própria classe.
Caso não deseje estender a classe DefaultRevisionEntity para a entidade de
revisão, você deve criar pelo menos dois campos devidamente encapsulados
(com seus “get” e “set”):
1. do tipo Integer ou int, anotado com @org.hibernate.envers.Revision-
Number;
2. do tipo Long ou long, anotado com @org.hibernate.envers.RevisionTi-
mestamp.
Dependendo do tipo e da necessidade de um sistema, uma entidade de
revisão pode conter campos como um número IP, um “host name”, o sistema
operacional do usuário etc. A Listagem 4 mostra um exemplo de classe Revi-
sion Listener.
53
 "SUJHP
t
"VEJUPSJB
"WBOÎBEB
EF
1FSTJTUÐODJB
DPN
)JCFSOBUF

+1"
F
&OWFST
Listagem 3. Exemplo de classe de entidade de revisão.
import org.hibernate.envers.RevisionEntity;
import org.hibernate.envers.DefaultRevisionEntity;
@Entity(name="revinfo")
@RevisionEntity(AuditoriaFutebolListener.class) // classe de escuta de revisões
public class ExampleRevEntity extends DefaultRevisionEntity {
private Integer idUsuario;
// get e set de idUsuario
}
Listagem 4. Exemplo de classe de escuta de revisões.
import org.hibernate.envers. RevisionListener;
@Entity(name="revinfo")
@RevisionEntity(AuditoriaFutebolListener.class)
public class AuditoriaFutebolListener extends RevisionListener {
public void newRevision(Object revisionEntity) {
EntidadeRevisoes entidadeRevisoes = (EntidadeRevisoes) revisionEntity;
Integer idUsuario = ... ; //Recuperação do identificador do usuário
// conforme a tecnologia usada
entidadeRevisoes.setIdUsuario(idUsuario);
} Note que esse recurso não é indicado para estudar a operação em si
} se foi inclusão, exclusão ou alteração. O método newRevision(Object
$JDMP
EF
WJEB
EF
VNB
DMBTTF
EF
FTDVUB
EF
SFWJTÜFT
3FWJTJPO
-JTUFOFS
Uma classe que implementa PSHIJCFSOBUFFOWFST3FWJTJPO-JTUFOFS

possui uma instância Á/*$" por &OUJUZ.BOBHFS'BDUPSZ. Por isso, mui-
to cuidado com o uso de variáveis de instância.
No exemplo da Listagem 4 existem várias formas de recuperar o identi-
ficador do usuário, dependo da tecnologia usada. Na Listagem 5 há um
exemplo de como fazer isso com o framework JBoss Seam (através de
busca de componente) e na Listagem 6, de como fazer com o Apache
Struts2 (através de busca de atributo no escopo de sessão). Esse tipo de
classe tem comportamento parecido com o dos Interceptors do EJB3 e
do Struts2, afinal lida com uma “responsabilidade transversal”, no caso, a
auditoria de persistência.
54 www.mundoj.com.br
Listagem 5. Exemplo de recuperação de identificador usando o Seam.
import org.jboss.seam.security.Identity;
import org.jboss.seam.Component;
...
public void newRevision(Object revisionEntity) {
...
Identity identity = (Identity) Component.getInstance(
"org.jboss.seam.security.identity");
Integer idUsuario = new Integer(identity.getPrincipal().getName());
entidadeRevisoes.setIdUsuario(idUsuario);
}
Listagem 6. Exemplo de recuperação de identificador usando o Struts2.
import com.opensymphony.xwork2.ActionContext;
...
public void newRevision(Object revisionEntity) {
...
Integer idUsuario = (Integer)ActionContext.getContext().getSession().
get("idUsuarioAtual");
entidadeRevisoes.setIdUsuario(idUsuario);
}
revisionEntity) é o único método da interface org.hibernate.envers.
RevisionListener. O que interessa nesse tipo de classe é apenas atribuir
informações extras para o registro da operação. Para escuta das opera-
ções CRUD, deve-se usar o recurso de escuta de eventos do Envers, que
será apresentado na próxima seção.
Recursos de flexibilização e personalização
da auditoria com Envers
O Envers tem uma “proposta pronta” de arquitetura de tabelas para pro-
ver auditoria e versionamento de persistência. É uma arquitetura muito
inteligente e organizada que permite certas customizações como vistas
no tópico anterior. Todavia, pode ser necessário que a arquitetura de ta-
belas de auditoria seja diferente da proposta pelo Envers. Também pode
ser necessário usar outros recursos de registro de auditoria, como envio
de e-mails e criação de “logs” em arquivos-texto, por exemplo.
O mecanismo do Envers que permite esse tipo de flexibilização é a escuta
de eventos de auditoria (Audit Event Listener).
 "SUJHP
t
"VEJUPSJB
"WBOÎBEB
EF
1FSTJTUÐODJB
DPN
)JCFSOBUF

+1"
F
&OWFST
Escuta de eventos de auditoria (Audit Event Listener)
Para poder usar o Envers em seu modo “padrão”, é preciso configurá-lo no
JPA como visto no 2º passo do tópico “Criando auditoria de persistência
com o framework Envers”. O que é feito na verdade é o mapeamento dos
mecanismos de escuta de eventos de auditoria padrão do Envers. Para
personalizar essas escutas, basta criar uma ou mais classes que estendam
org.hibernate.envers.event.AuditEventListener (exemplo na Listagem 7)
e indicá-las na configuração do JPA (exemplo na Listagem 8).
Listagem 7. Exemplo de classe de escuta de eventos de auditoria personalizada.
package mj.projetoFutebol.listeners;
import org.hibernate.envers.event.AuditEventListener;
...
public class FutebolListener extends AuditEventListener{
@Override
public void onPostInsert(PostInsertEvent event) {
// faça o que quiser com as informações do evento “post insert”
}
@Override
public void onPostDelete(PostDeleteEvent event) {

TFN
WFSTJPOBNFOUP

TFN
FTDVUB
// faça o que quiser com as informações do evento “post delete""
} O Envers possui um mecanismo de prevenção de criação de versões
@Override
public void onPostUpdate(PostUpdateEvent event) {
// faça o que quiser com as informações do evento “post update”
} para o registro envolvido na operação, não será gerada uma nova versão
} da tabela em sua tabela de auditoria individual.
Todos os métodos de escuta de eventos de auditoria padrão do Envers
possuem como parâmetro um objeto que estende org.hibernate.event.
AbstractEvent. Esses objetos de evento permitem recuperar várias informa-
ções pertinentes sobre o evento e a entidade envolvida nele. Os principais
métodos desses objetos de eventos estão na tabela 1. A Listagem 9 possui
um pequeno exemplo de como usar alguns do métodos dessa tabela.
Se for invocada a versão da superclasse dos métodos de escuta de eventos,
o Envers tenta fazer seu procedimento padrão para a operação (registros
numa tabela “_aud” e na tabela central de controle de revisões). Assim,
caso seja necessário apenas acrescentar funcionalidades adicionais ao
Envers (como envio de e-mail, por exemplo) sem alterar seu mecanismo
padrão de armazenamento de dados de auditoria de persistência. Por
exemplo: se você quiser que toda vez que um registro de determinada
tabela seja excluído o administrador do sistema receba um e-mail, mas
deseja manter a auditoria padrão do Envers, basta implementar o código
de envio de e-mail no método “onPostDelete(PostDeleteEvent event)” e
depois chamar “super.onPostDelete(event)”.
Recuperação dos dados de auditoria gerados
pelo Envers
Além de assumir o “trabalho pesado” pela alimentação das tabelas de
auditoria, o Envers oferece um mecanismo robusto de recuperação de
versões das tabelas. Na Listagem 10 há um exemplo de recuperação de
versão com o uso da classe org.hibernate.envers.AuditReader.
Listagem 8. Configuração do Envers no persistence.xml de um projeto
Hibernate/JPA.
<persistence-unit ...>
...
<properties>
<!-- configurações comuns -->
<property name="hibernate.ejb.event.post-insert"
value="mj.projetoFutebol.listeners.FutebolListener" />
<property name="hibernate.ejb.event.post-update"
value="mj.projetoFutebol.listeners.FutebolListener " />
<property name="hibernate.ejb.event.post-delete"
value="mj.projetoFutebol.listeners.FutebolListener " />
</properties>
</persistence-unit>
4FN
NVEBOÎBT
inúteis nas tabelas de auditorias individuais. Se for feito um pedido de
atualização através do método NFSHF() ou de uma query +12- e os
valores enviados forem os mesmos dos que já estão no banco de dados
E todos os mecanismos de escuta do Envers também são ignorados
quando é feito um pedido de atualização que contém dados iguais aos
já persistidos.
A classe PSHIJCFSOBUFFOWFST"VEJU3FBEFS possui os recursos para
recuperação de versões de dados de tabelas auditadas. Seus métodos
estão na tabela 2.
Existem duas outras formas de consultar as informações de auditoria
geradas no banco de dados pelo Envers. Ambas utilizam a interface
PSHIJCFSOBUFFOWFSTRVFSZ"VEJU2VFSZ. Essa interface permite fazer
consultas mais complexas em cima dos dados que foram armazenados.
As queries do Envers são semelhantes às queries do Hibernate Criteria,
facilitando a vida dos leitores que já têm familiaridade com a interface
PSHIJCFSOBUF$SJUFSJB.
A primeira forma é consultar uma entidade em uma determinada revi-
são. A segunda é consultar as revisões de uma determinada entidade. A
Listagem 11 mostra um exemplo simples de uma consulta de entidade
dada uma revisão.
A consulta da Listagem 11 retorna uma lista de jogadores na revisão
"revisionNumber" e cuja propriedade "nome_em_campo" tem o valor
"Ronaldo".
A Listagem 12 possui um exemplo simples de consulta a uma das revi-
sões de uma entidade com AuditQuery.
55
 "SUJHP
t
"VEJUPSJB
"WBOÎBEB
EF
1FSTJTUÐODJB
DPN
)JCFSOBUF

+1"
F
&OWFST

Listagem 9. Exemplo de classe de escuta de eventos de auditoria Método Descrição Eventos

personalizada. Object getEntity() Retorna a instância da onPostInsert
entidade envolvida no onPostUpdate
public class FutebolListener extends AuditEventListener{ onPostDelete
evento. No caso de “onPos-
@Override tUpdate()”, os campos da
public void onPostInsert(PostInsertEvent event) { entidade recuperada por
Object entidade = event.getEntity(); este método vêm com os
valores alterados.
Serializable chave = event.getId();
Java.io.Serializable event. Retorna a chave da onPostInsert
// faça o que quiser com as informações do evento “post insert”
getId() entidade envolvida no onPostUpdate
}
evento. onPostDelete

Object[] getState() Retorna um vetor de onPostInsert

@Override objetos com os valores dos onPostUpdate
public void onPostDelete(PostDeleteEvent event) { campos da entidade já sob
Object[] estadoDeletado = event.getDeletedState(); os efeitos do evento.

// faça o que quiser com as informações do evento “post delete” Object[] getOldState() Retorna um vetor de onPostUpdate

} objetos com os valores dos

campos da “versão antiga”
da entidade (valores de an-
@Override tes de sofrer atualização).
public void onPostUpdate(PostUpdateEvent event) { Assim pode-se ter acesso
Object[] estadoNovo = event.getState(); ao registro “como estava”
Object[] estadoAntigo = event.getOldState(); antes da atualização.

// faça o que quiser com as informações do evento “post update” Object[]getDeletedState() Equivale ao getState(), onPostDelete
porém só se aplica à escuta
}
de “post-delete”
org.hibernate.collection. Retorna a coleção de onPostRecreateCollection
@Override onPreRemoveCollection
PersistentCollection instâncias das entidades
public void onPreUpdateCollection(PreCollectionUpdateEvent event) { envolvidas no evento. onPreUpdateCollection
PersistentCollection colecaoAfetada = event.getCollection(); getCollection()

Serializable chaveDaEntidadeQuePossuiAColecao = Serializable getAffectedOw- Retorna a chave da onPostRecreateCollection

nerIdOrNull() entidade à qual a coleção onPreRemoveCollection
event.getAffectedOwnerIdOrNull();
pertence. onPreUpdateCollection
String nomeEntidadeQuePossuiAColecao =
String getAffectedOwnerEn- Retorna o nome da onPostRecreateCollection
event.getAffectedOwnerEntityName(); onPreRemoveCollection
tityName entidade à qual a coleção
// faça o que quiser com as informações do evento “pre update collection” pertence. onPreUpdateCollection
} 5BCFMB

1SJODJQBJT
NÏUPEPT
EPT
FWFOUPT
EF
FTDVUB
EF
BVEJUPSJB
EP
&OWFST
}

Listagem 12. Recuperando uma determinada versão de registro com AuditQuery.

Listagem 10. Recuperando uma determinada versão de registro da tabela
“time_futebol”, sob a auditoria do Envers.
import org.hibernate.envers.AuditReader;
import org.hibernate.envers.AuditReaderFactory;
public void recuperarTimeDeAuditoria(Integer idTime, Integer versao) {
EntityManager em = .... ;
AuditReader leitorAuditoria = AuditReaderFactory.get(em);
TimeFutebol timeRecuperado = leitorAuditoria.find(TimeFutebol.class,
idTime, versao);
}
Listagem 11. Recuperando uma lista de versões de registro com AuditQuery.
Number revision = (Number) getAuditReader().createQuery()
.forRevisionsOfEntity(Jogador.class, false, true)
.setProjection(AuditEntity.revisionNumber().min())
.add(AuditEntity.id().eq(idjogador))
.add(AuditEntity.revisionNumber().gt(12))
.getSingleResult();
A consulta da Listagem 12 retorna a menor versão na qual uma entidade
da classe Jogador de id "idjogador" foi alterada, depois da versão 12.
A classe AuditQuery tem uma série de métodos que permitem especi-
ficar restrições, fazer ordenação, limitar o número de resultados, assim
como também é possível fazer uso de agregações e projeções.

List jogadores = getAuditReader().createQuery().
forEntitiesAtRevision(Jogador.class, revisionNumber)
.add(AuditEntity.property("nome_em_campo").eq("Ronaldo"))
.getResultList();
Abordar todos os seus métodos e combinações tornaria este trabalho
muito extenso. Por isso encorajamos o leitor a consultar sua documenta-
ção da API (link nas referências) a fim de conhecer melhor os métodos e
as possibilidades de utilização.

56 www.mundoj.com.br
 "SUJHP
t
"VEJUPSJB
"WBOÎBEB
EF
1FSTJTUÐODJB
DPN
)JCFSOBUF
+1"
F
&OWFST

Método
T find(Class<T> cls, Object prima-
ryKey, Number revision)
T findRevision(Class<T> cls, Number
revision)
Descrição
Recupera uma determinada
versão (parâmetro “revision”)
de certo registro (parâmetro
“primaryKey”) de uma
determinada classe de
entidade (parâmetro “cls”).
Recupera uma determinada
versão (parâmetro “revision”)
de certo registro (identificado
pelo parâmetro “prima-
ryKey”) de uma determinada
classe de entidade (parâmetro
“cls”).
Listagem 13. Recuperando instâncias de objetos mapeados para chaves
estrangeiras de entidades recuperadas pelo controle de versão do Envers.
import org.hibernate.Hibernate;
public void recuperarJogadorDeAuditoria(Integer idJogador, Integer versao) {
EntityManager em = .... ;
AuditReader leitorAuditoria = AuditReaderFactory.get(em);
Jogador jogadorRecuperado = leitorAuditoria.find(Jogador.class,
idJogador, versao);
// objeto em “Lazy eterno”
TimeFutebol timeRecuperado = jogadorRecuperado.getTimeFutebol();

T getCurrentRevision(Class<T>
revisionEntityClass, boolean persist)
java.util.List<Number>
getRevisions(Class<?> cls, Object
primaryKey)
Number
getRevisionNumberForDate(java.util.
Date date)
java.util.Date
getRevisionDate(Number revision)
5BCFMB

.ÏUPEPT
EF
PSHIJCFSOBUFFOWFST"VEJU3FBEFS
Pontos fracos da auditoria com Hibernate e
Envers
Recupera a versão atual da
entidade da classe indicada
(parâmetro “revisionEn-
tityClass”). O parâmetro
“persist” indica se o registro
retornado deve ou não ser
salvo no banco de dados caso
ainda não esteja efetivamente
salvo.
Retorna a lista de versões
existentes para um
determinado registro
(parâmetro “primaryKey”) de
uma determinada classe de
entidade (parâmetro “cls”).
Retorna a última versão de
uma determinada data.
Retorna a data de uma deter-
minada versão de entidade
(parâmetro “revision”).
// única maneira de fazer o objeto ser preenchido
Hibernate.initialize(timeRecuperado);
}
Impacto na performance com uso do Envers
Um trabalho de estudo do impacto na performance em uma apli-
cação com uso de Envers seria muito longo, mas, por dedução,
acredita-se que o impacto é diretamente proporcional ao número
de tabelas marcadas para auditoria e ao número de entidades en-
volvidas por operação.
Para cada entidade mapeada para auditoria com Envers, a cada
operação interceptada por ele, um método de escuta (seção “Escuta
de eventos de auditoria”) é invocado pelo menos uma vez. Caso a
entidade possua mapeamentos de um para muitos ou de muitos
para muitos em cascata com outras entidades também mapeadas
para auditoria, o número de chamadas aos métodos de escuta é
proporcional ao número de objetos envolvidos na operação.
Portanto, é uma boa prática evitar o mapeamento de todas as
classes de entidades e grandes projetos para evitar grandes perdas
de performance. Porém, se os requisitos exigirem isso, uma menor
performance é um preço a se pagar.
Considerações finais

Existe uma informação equivocada na documentação da API do
Envers. Nela diz que o método find(Class<T> cls, Object prima-
ryKey, Number revision) da classe AuditReader retorna “null” caso
seja passada como parâmetro uma versão inexistente na tabela de
auditoria individual da tabela. Todavia o que ocorre nesse caso é
que o método retorna a última versão da entidade.
Nos métodos de recuperação de versões anteriores das entidades
sob o controle de versão, os campos mapeados para objetos de ou-
tras entidades não são recuperados. É como se estivessem em modo
“Lazy” eternamente, pois o Hibernate não consegue recuperar seus
campos em runtime. Para isso, é preciso uma “técnica alternativa”
através do uso de recursos específicos do Hibernate, como mostra

FEJUPSB
.BOOJOH
1VCMJDBUJPOT
a Listagem 13.
Neste artigo foi abordado o framework Envers para auditoria de persis-
tência com o Hibernate. Foram mostrados a configuração básica, alguns
aspectos avançados e algumas dificuldades no uso deste framework. Os
recursos oferecidos pelo Envers para auditoria com Hibernate e JPA são
bem variados e poderosos, portanto, espera-se que este artigo estimule
a criação de sistemas de auditoria de persistência robustos que são im-
portantíssimos para a maioria dos tipos de sistema e indispensáveis em
sistemas corporativos.
Referências
t
4JUF
PmDJBM
EP
&OWFST
IUUQKCPTTPSHFOWFST
t
4JUF
PmDJBM
EP
)JCFSOBUF
IUUQXXXIJCFSOBUFPSH
t
4JUF
PmDJBM
EP
)JCFSOBUF
&OUJUZ
.BOBHFS
IUUQTFOUJUZNBOBHFSIJCFSOBUFPSH
t
)JCFSOBUF
JO
BDUJPO

57