Os aplicativos podem ser notificados quando o estado de uma entidade
é alterado de estado para estado. Dois mecanismos de retorno de chamada existem para
os eventos de alteração de estado: os métodos de retorno de chamada do ciclo de vida,
que são definidos em uma classe de entidade e são chamados sempre que o estado da
entidade for alterado, e os listeners de entidade que são mais genéricos porque
o listener da entidade pode ser registrado em várias entidades.
Ciclo de Vida de uma Instância de Entidade
Uma instância de entidade apresenta os seguintes estados:
- Novo: Uma instância da entidade recentemente criada que não existe no cache
do eXtreme Scale.
- Gerenciado: A instância da entidade existe no cacho do eXtreme Scale
e é recuperada ou persistida utilizando o entity manager. É preciso que uma entidade esteja associada
a uma transação ativa para ficar no estado gerenciado.
- Separado: A instância da entidade existe no cache do eXtreme Scale, mas não é mais associada com uma transação ativa.
- Removido: A instância da entidade é removida ou está planejada para ser removida
do cache do eXtreme Scale quando ocorre o flush ou o
commit da transação.
- Invalidado: A instância da entidade está invalidada ou está planejada para ser
invalidada no cache do eXtreme Scale quando a ocorre
o flush ou o commit da transação.
Quando as entidades são alteradas de estado
para estado, é possível chamar métodos life cycle e callback.
As seções
a seguir descrevem com mais detalhes os significados dos estados Novo, Gerenciado, Separado,
Removido e Invalidado à medida que os estados se aplicam a uma entidade.
Métodos do Retorno de Chamada do Ciclo de Vida da Entidade
Os métodos do
retorno de chamada do ciclo de vida da entidade podem ser definidos na classe de entidade
e são chamados quando o estado da entidade for alterado. Estes métodos
são úteis para validar campos de entidade e atualizar o estado temporário que
normalmente não é persistido com a entidade. Os métodos do
retorno de chamada do ciclo de vida da entidade também podem ser definidos nas classes que não estão
usando as entidades. Tais classes são classes de listener da entidade,
que podem ser associadas a vários tipos de entidades. Os métodos do retorno de chamada do ciclo de vida podem
ser definidos usando as anotações de metadados e um arquivo descritor XML de metadados da entidade.
- Anotações: Os métodos do retorno de chamada do ciclo de vida podem
ser denotados usando as anotações PrePersist, PostPersist, PreRemove, PostRemove, PreUpdate,
PostUpdate e PostLoad em uma classe de entidade.
- Descritor XML de Entidade: Os métodos do retorno de chamada do ciclo
de vida podem ser descritos usando o XML quando as anotações não estiverem disponíveis.
Listeners de Entidade
Uma classe de listener
de entidade é uma classe que não usa as entidades que definem um
ou mais métodos do retorno de chamada do ciclo de vida da entidade. Os listeners de entidade são úteis para aplicativos de auditoria e
criação de log com propósito geral. Listeners de entidade podem ser
definidos utilizando anotações de metadados e um arquivo descritor
XML de metadados da entidade:
- Anotação: A anotação EntityListeners pode ser utilizada
para denotar uma ou mais classes do listener de entidade em uma
classe de entidade.
Se vários listeners de entidade estiverem definidos, a ordem na
qual eles são chamados é determinada pela ordem na qual estão
especificados na anotação EntityListeners.
- Descritor XML da entidade: O descritor XML pode ser utilizado
como uma alternativa para especificar a ordem de chamada dos listeners
de entidade ou para substituir a ordem que é especificada nas anotações
de metadados.
Requisitos do Método de Retorno de Chamada
Qualquer
subconjunto ou combinação de anotações pode ser especificado em uma classe
de entidade ou uma classe de listener. Uma única classe não pode ter mais que um
método de retorno de chamada do ciclo de vida para o mesmo evento do ciclo de vida. Entretanto, o mesmo método pode ser utilizado para vários
eventos de retorno de chamada. A classe de listener de entidade deve ter um
construtor no-arg público. Listeners de entidade não têm definição de estado.
O ciclo de vida de um listener de entidade não é especificado. O eXtreme Scale não suporta
herança de entidades, portanto, os métodos callback podem
ser definidos apenas na classe de entidade, mas não na superclasse.
Assinatura de Método callback
Os métodos do
retorno de chamada do ciclo de vida da entidade podem ser definidos em uma classe de listener
de entidade, diretamente em uma classe de entidade, ou em ambos. Os métodos do retorno de chamada do ciclo de vida da entidade podem ser definidos usando as anotações de metadados e o arquivo descritor XML da entidade.
As anotações utilizadas para métodos callback de entidade
e na classe de listener da entidade são as mesmas. As assinaturas dos
métodos callback são diferentes quando definidas em uma classe
de entidade versus uma classe de listener de entidade. Os métodos callback
definidos em uma classe de entidade ou superclasse
mapeada possuem a seguinte assinatura:
void <METHOD>()
Os métodos callback que são definidos em uma classe de
listener de entidade possuem a seguinte assinatura:
void <METHOD>(Object)
O argumento Object é a instância da entidade para a qual o método de retorno
de chamada é chamado.
O argumento Object pode ser declarado como um objeto java.lang.Object ou
o tipo de entidade real.
Os métodos callback podem ter nível de acesso público,
privado, protegido ou de pacote, mas não devem ser estáticos ou finais.
As seguintes anotações são definidas para designar os métodos de retorno de chamada de evento do ciclo
de vida dos tipos correspondentes:
- com.ibm.websphere.projector.annotations.PrePersist
- com.ibm.websphere.projector.annotations.PostPersist
- com.ibm.websphere.projector.annotations.PreRemove
- com.ibm.websphere.projector.annotations.PostRemove
- com.ibm.websphere.projector.annotations.PreUpdate
- com.ibm.websphere.projector.annotations.PostUpdate
- com.ibm.websphere.projector.annotations.PostLoad
Consulte a
Documentação da API para obter mais detalhes. Cada anotação possui um
atributo XML equivalente definido no arquivo descritor XML de metadados
de entidade.
Semântica do Método do Retorno de Chamada do Ciclo de
Vida
Cada método
do retorno de chamada do ciclo de vida diferente possui uma finalidade diferente
e é chamado nas fases diferentes do ciclo de vida da entidade:
- PrePersist
- Chamado para uma entidade antes da entidade ter sido persistida para
o armazém, o que inclui entidades que foram persistidas devido a uma
operação em cascata. Este método é chamado no encadeamento da operação
EntityManager.persist.
- PostPersist
- Chamado para uma entidade após a entidade ter sido persistida para o
armazém, o que inclui entidades que foram persistidas devido a uma operação
em cascata. Este método é chamado no encadeamento da operação
EntityManager.persist. Ele é chamado após o EntityManager.flush ou EntityManager.commit
ser chamado.
- PreRemove
- Chamado para um entidade antes da entidade ter sido removida, o que inclui
entidades que foram removidas devido a uma operação em cascata.
Este método é chamado no encadeamento da
operação EntityManager.remove.
- PostRemove
- Chamado para uma entidade após a entidade ter sido removida, o que inclui
entidades que foram removidas devido a uma operação em cascata.
Este método é chamado no encadeamento da
operação EntityManager.remove.
Ele é chamado após o EntityManager.flush ou EntityManager.commit
ser chamado.
- PreUpdate
- Chamado para uma entidade antes da entidade ter sido atualizada no
armazém. Este método é chamado no encadeamento da operação flush ou
commit da transação.
- PostUpdate
- Chamado para uma entidade após a entidade ter sido atualizada no
armazém. Este método é chamado no encadeamento da operação flush ou
commit da transação.
- PostLoad
- Chamado para uma entidade após a entidade ter sido carregada do armazém,
o que inclui quaisquer entidades que são carregadas através de uma associação.
Este método é chamado no encadeamento da operação de carregamento, tal como
EntityManager.find ou uma consulta.
Duplicata dos Métodos do Retorno de Chamada do Ciclo de Vida
Se vários métodos
do retorno de chamada forem definidos para um evento de ciclo de vida da entidade, a
ordem de chamada desses métodos será a seguinte:
- Métodos de retorno de chamada do ciclo de vida definidos nos listeners de entidade: Os métodos
do retorno de chamada do ciclo de vida, que são definidos nas classes de listener
de entidade para uma classe de entidade, são chamados na mesma ordem que a especificação
das classes de listener de entidade na anotação EntityListeners ou no descritor XML.
- Superclasse do listener: Os métodos callback definidos
na superclasse do listener de entidade são chamados antes dos filhos.
- Métodos do ciclo de vida da entidade: O WebSphere eXtreme
Scale não suporta herança de entidade, portanto, os métodos do ciclo de vida da entidade podem
ser definidos apenas na classe de entidade.
Exceções
Os métodos de retorno de chamada do ciclo de vida podem resultar
em exceções de tempo de execução. Se um método de retorno de chamada do
ciclo de vida causar uma exceção de tempo de execução em uma transação,
a transação será recuperada. Nenhum outro método de retorno de chamada do ciclo de vida será chamado depois
que ocorrer uma exceção no tempo de execução.