diff --git a/documentation/reference/pt-BR/persistencia.xml b/documentation/reference/pt-BR/persistencia.xml index 88bb4b3..82a3807 100644 --- a/documentation/reference/pt-BR/persistencia.xml +++ b/documentation/reference/pt-BR/persistencia.xml @@ -18,6 +18,181 @@ é apenas injetar o recurso adequado em seu código e o Framework Demoiselle se encarregará de produzi-lo e configurá-lo. + +
+ JPA + + + O Framework Demoiselle fornece um produtor padrão para contextos de persistência da JPA. Esse produtor lê o arquivo + de configuração persistence.xml de seu projeto e toma as providências necessárias para fabricar uma instância + da classe EntityManager que pode ser usada para gerenciar as entidades de sua aplicação. Além disso, instâncias + de EntityManager produzidas pelo Framework Demoiselle participam automaticamente de transações abertas através da + anotação @Transactional, conforme apresentado no capítulo sobre Transações. + + + + + Para acrescentar a dependência à extensão demoiselle-jpa, adicione esse código + em seu arquivo pom.xml, na seção dependencies. + + + + br.gov.frameworkdemoiselle + demoiselle-jpa + compile +]]> + + +
+ Introdução ao mecanismo + + + Para injetar uma instância de EntityManager em sua aplicação, basta usar a anotação @Inject. + + + @PersistenceController +public class BookmarkDAO extends JPACrud<Bookmark, Long> { + + private static final long serialVersionUID = 1L; + + @Inject + private EntityManager entityManager; + + public void persistBookmark(Bookmark bookmark){ + entityManager.persist(bookmark); + } + +} + + + O produtor padrão injetará o EntityManager configurado no arquivo persistence.xml. Se houver + mais de um contexto de persistência configurado em persistence.xml, será necessário especificar qual será + injetado no ponto de injeção. Para isso use a anotação @Name. + + + @PersistenceController +public class BookmarkDAO extends JPACrud<Bookmark, Long> { + + private static final long serialVersionUID = 1L; + + @Inject + @Name("persistence_unit_1") + private EntityManager entityManager; + + public void persistBookmark(Bookmark bookmark){ + entityManager.persist(bookmark); + } + +} + + + É possível invocar o utilitário Beans para injetar instâncias de EntityManager programaticamente. + + + @PersistenceController +public class BookmarkDAO extends JPACrud<Bookmark, Long> { + + private static final long serialVersionUID = 1L; + + public void persistBookmark(Bookmark bookmark){ + EntityManager entityManager = Beans.getReference(EntityManager.class); + entityManager.persist(bookmark); + } + + public void persistBookmarkInHistory(Bookmark bookmark){ + EntityManager entityManager = Beans.getReference(EntityManager.class , new NameQualifier("history_persistence_unit")); + entityManager.persist(bookmark); + } + +} +
+ +
+ Configuração + + + Alguns comportamentos do produtor podem ser configurados através das propriedades abaixo, que devem ser configuradas + no arquivo demoiselle.properties. + + + + + + + + + + + Propriedade + Descrição + Padrão + + + + + + frameworkdemoiselle.​persistence.​default.​unit.​name + + + Define o nome da unidade de persistência padrão (configurada em persistence.xml) que será injetada + caso a anotação @Name não seja usada. Não é necessário se apenas uma unidade de persistência for configurada. + + + + + + + frameworkdemoiselle.​persistence.​entitymanager.​scope + + + Permite determinar o escopo de unidades de persistência injetadas. Dentro do escopo determinado, todos os pontos + de injeção receberão a mesma instância de EntityManager. + + + Os valores possíveis são: + + request + session + view + conversation + application + noscope + + + + request + + + + + + + + O escopo especial noscope desliga o gerenciamento de escopo de instâncias de EntityManager + produzidas pelo Framework Demoiselle. Isso permite ao desenvolvedor controlar totalmente o ciclo de vida de um + EntityManager injetado e ainda reter o recurso do produtor padrão. + + + Note que ao usar a opção noscope, o desenvolvedor é o responsável por controlar o ciclo de vida do gerenciador + de persistência. Ele não participará de transações JPA abertas através da anotação @Transactional (transações JTA funcionam normalmente) + e multiplos pontos de injeção durante uma requisição receberão múltiplas instâncias de EntityManager. + + + + + + Deve-se usar cautela ao alterar o escopo padrão das instâncias de EntityManager. Na grande maioria dos casos o escopo + padrão request é o suficiente e alterar esse padrão deve ser feito apenas após extensa análise dos prós e contras + de cada escopo. + + + Dê especial atenção aos escopos que podem ser serializados pelo servidor de aplicação (session, view + e conversation) pois a especificação não define o comportamento de instâncias de EntityManager que são + serializadas. + + +
+
diff --git a/documentation/reference/pt-BR/properties.xml b/documentation/reference/pt-BR/properties.xml index a76c6e5..48c92a1 100644 --- a/documentation/reference/pt-BR/properties.xml +++ b/documentation/reference/pt-BR/properties.xml @@ -251,12 +251,34 @@ frameworkdemoiselle.​persistence.​default.​unit.​name - Define a unidade de persistência padrão para aplicações que possuem mais - de um persistence-unit definido no arquivo persistence.xml. + Define o nome da unidade de persistência padrão (configurada em persistence.xml) que será injetada + caso a anotação @Name não seja usada. Não é necessário se apenas uma unidade de persistência for configurada. + + + frameworkdemoiselle.​persistence.​entitymanager.​scope + + + Permite determinar o escopo de unidades de persistência injetadas. Dentro do escopo determinado, todos os pontos + de injeção receberão a mesma instância de EntityManager. + + + Os valores possíveis são: + + request + session + view + conversation + application + noscope + + + + request + diff --git a/documentation/reference/pt-BR/transacao.xml b/documentation/reference/pt-BR/transacao.xml index 95a3603..48b5e62 100644 --- a/documentation/reference/pt-BR/transacao.xml +++ b/documentation/reference/pt-BR/transacao.xml @@ -135,7 +135,7 @@ public class AbacaxiException { Esta estratégia, que está disponível na extensão demoiselle-jpa, delega o controle das transações para o javax.persistence.EntityManager da - especificação JPA. Você deve escolher esta estratégia quando estiver persisteindo dados + especificação JPA. Você deve escolher esta estratégia quando estiver persistindo dados com JPA e utilizando apenas uma base de dados em sua aplicação. Como um EntityManager acessa apenas uma unidade de persistência, não há como fazer o controle transacional de unidades distintas. -- libgit2 0.21.2