BISDAO Legacy

O BISKernel oferece uma estrutura de persistência combinada com os recursos da JPA para simplificar, ou mesmo evitar, a camada de persistência dos módulos. Essa estrutura prevê métodos para insert, update, delete e "find".

Seu funcionamento compreende os seguintes itens:

• BISVO - Um herdeiro de BISVO que represente a entidade principal a ser persistida. O objeto a ser manipulado no banco de dados.
• BISMO - MatchObject para os métodos de find. O MatchObject representa um objeto de filtro para a busca no banco de dados.
• BISOrderBy - Objeto usado nos métodos de find que retornam mais de 1 item para descrever a ordem dos objetos.
• BISVO_ - O MetaObject deve ser utilizado para indicar os atributos que queremos que o método de find busque automaticamente para popular cada objeto. Normalmente os métodos de find já trazem o atributos do VO populado, mas não os atributos das entidades relacionadas (relacionamento marcados como Lazy no JPA). Quando o carregamento deste objeto for desejado o herdeiro do BISVO_ correspondente ao herdeiro do BISVO passado no construtor do BISDAO deve ser utilizado para indicar o caminho das propriedades que obrigatoriamente devem ser populadas. Em geral, se uma propriedade de um VO é solicitada todas as outras propriedades do mesmo VO que estão na mesma tabela serão poluladas automaticamente.

Padrão de Nomes Para simplificação da programação em equipe e manutenção posterior lembre-se do padrão de nome dos objetos e classes adotados no BIS descritos no tópico Convenção de Nome do BIS.

Extensão da BISDAO Normalmente não é necessário estender BISDAO em outra classe. Bastando a instância-la e passando a classe adequada em seu construtor os métodos padrões do BISDAO já se tornam acessíveis. Ainda assim, é possível estender BISDAO em uma classe específica para a criação de métodos mais específicos que interagem diretamente com o JPA. Em geral estes métodos só serão necessários para ganhos de performance para métodos de consulta ou atualização do banco de dados.

Tratamento do Relacionamentos das Entidades

Este tópico relaciona o comportamento do BISDAO com às entidades relacionadas à entidade principal. Mas lembre-se que não cabe ao BISDAO realizar validações, o objeto que chega aqui deve estar pronto para ser persistido, para validar consulte o BISValidator.

O BISDAO se orienta pelas annotations do JPA e do BISMeta Annotations, logo seu correto funcionamento depende da informação correta informada nessas annotations. Veja a sessão de exemplos nesta página.

Inserção

Ao inserir uma nova entidade no banco de dados o BISDAO simplesmente fará a inserção em cascata de todos as entidades de composição, e a associação dos IDs das entidades associadas.

Atualização

A atualização é uma operação um tanto mais delicada pois já temos informações persistidas no banco de dados e temos de garantir que nenhum "lixo" ficará no banco ao persistir um objeto. Inclusive desfazer relacionamentos que antes existiam e agora não existem mais, e em caso de relacionamentos de composição que deixaram de existir deve excluir os objetos filhos (deletar os objetos órfãos). Assim:

• O BIS atualizará os atributos da entidade como de costume;
• Atributos com relacionamento de composição:
  • Caso o objeto no banco ainda não tenha um relacionamento, deixamos o JPA criar a nova entidade;
  • Caso o objeto no banco já tenha um relacionamento, e:
    • O novo objeto tem um relacionamento, verificamos:
      • Se ambos têm o mesmo ID, deixamos seguir para que o JPA atualize o mesmo objeto;
      • Se não tem ID, excluímos o objeto do relacionamento atual do banco e deixamos que o JPA insira o novo;
      • Se o ID for diferente, CriticalException, já que IDs não são aceitos para inserir um novo objeto!
• Atributos com relacionamento de associação:
  • CriticalException caso o objeto não tenha um ID definido.

Todos os relacionamentos do tipo composição serão analisados e persistidos recursivamente conforme as regras acima.

findForFullUpdate Note que a ausência de relacionamento é tratado pelo BISDAO como "sem relacionamento" e não como "não mexer neste relacionamento". Por isso ao enviar um objeto para o BISDAO todos os relacionamentos de composição devem ser carregados recursivamente, já os relacionamentos de associação devem ser informados no mínimo com o ID do objeto. Assim, se carregar um objeto de forma incompleta e o enviar para atualizar, o BISDAO removerá as associações e ainda excluirá as composições não mais utilizadas. Um carregamento incompleto pode ocorrer por exemplo se o objeto que seja atualizado em diversas partes do sistema sofre mudanças em seus relacionamentos e em algum ponto do sistema se esquece de atualizar o método que busca o objeto no banco, causando não só um BUG como perda de dados do cliente. Para evitar isso sempre que obtiver um objeto para manipulação e para atualização no banco de dados sempre utilize o método findForUpdate() disponibilizado pelo BISDAO. Este método fará uma varredura automática no objeto e retornará sempre o objeto completo. De forma que se submetido logo em seguida para atualização nenhuma alteração será feita.

Mapeamentos JPA

Esta sessão traz exemplos de como definir os mapeamentos entre as entidades para o correto funcionamento do JPA e do BISDAO.

Composição

CascadeType.ALL Os relacionamentos do tipo composição sempre terão o cascade em ALL. Deste modo o JPA fará a persistência em cadeia nos objetos associados.

Objeto dependente sempre tem uma relação de Associação Note nos relacionamentos que apenas o objeto principal tem a relação definida como Composição já que é ele quem manda na persistência e existência do objeto filho/dependente. No mapeamento do objeto filho/dependente o relacionamento é definido apenas como Associação. Isso porque como ele não é o foco da existência da entidade como um todo, ele simplesmente fica associado à entidade principal.

OneToMany - Mapeado com Lista Ordenada

OneToMany entre PersonVO.personfieldList e PersonFieldVO

PersonVO @OneToMany(cascade = CascadeType.ALL, mappedBy = "personvo", fetch = FetchType.LAZY, orphanRemoval = true) @OrderBy("indexorder") @BISMetaRelationshipField(caption = "Contatos", relationship = RelationshipTypes.COMPOSITION, required = false, targetRelationship = PersonFieldVO.class) private List<PersonFieldVO> personfieldlist = null;

PersonFieldVO @ManyToOne(cascade = CascadeType.REFRESH, fetch = FetchType.LAZY, optional = false) @JoinColumn(name = "idperson") @BISMetaRelationshipField(caption = "Pessoa", relationship = RelationshipTypes.ASSOCIATION, required = true) private PersonVO personvo = null;

Associação

CascadeType.REFRESH Os relacionamentos do tipo associação sempre terão o cascade em REFRESH. Deste modo o JPA não fará alterações no objeto associado.

ManyToOne

ManyToOne entre CompanyVO.locationcityvo e LocationCityVO

CompanyVO @ManyToOne(cascade = CascadeType.REFRESH, fetch = FetchType.LAZY, optional = true) @JoinColumn(name = "idcore_locationcity") @BISMetaRelationshipField(caption = "Município", required = false, relationship = RelationshipTypes.ASSOCIATION) private LocationCityVO locationcityvo = null;