Listeners de Entidade e Métodos de Retorno de Chamada

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:

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.

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:

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:
  1. 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.
  2. Superclasse do listener: Os métodos callback definidos na superclasse do listener de entidade são chamados antes dos filhos.
  3. 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.