Download as
Browse Code »

Commit 9c3cb596dda97c93ebd58a80d3ffb22ef487555f

Authored by Dancovich
1 parent 682975f9
Exists in master

issue FWK-123: Revisar e atualizar documentação do Framework 2.4.0 

https://demoiselle.atlassian.net/browse/FWK-123
Showing 3 changed files with 200 additions and 3 deletions   Show diff stats
documentation/reference/pt-BR/persistencia.xml
  Diff comments   View file @9c3cb59
... ... @@ -18,6 +18,181 @@
18 18 é apenas injetar o recurso adequado em seu código e o Framework Demoiselle se encarregará de
19 19 produzi-lo e configurá-lo.
20 20 </para>
  21 +
  22 + <section>
  23 + <title>JPA</title>
  24 +
  25 + <para>
  26 + O Framework Demoiselle fornece um produtor padrão para contextos de persistência da JPA. Esse produtor lê o arquivo
  27 + de configuração <code>persistence.xml</code> de seu projeto e toma as providências necessárias para fabricar uma instância
  28 + da classe <code>EntityManager</code> que pode ser usada para gerenciar as entidades de sua aplicação. Além disso, instâncias
  29 + de <code>EntityManager</code> produzidas pelo Framework Demoiselle participam automaticamente de transações abertas através da
  30 + anotação <code>@Transactional</code>, conforme apresentado no capítulo sobre <link linkend="transacao">Transações</link>.
  31 + </para>
  32 +
  33 + <tip>
  34 + <para>
  35 + Para acrescentar a dependência à extensão <literal>demoiselle-jpa</literal>, adicione esse código
  36 + em seu arquivo <literal>pom.xml</literal>, na seção <literal>dependencies</literal>.
  37 + </para>
  38 +
  39 + <programlisting role="XML"><![CDATA[<dependency>
  40 + <groupId>br.gov.frameworkdemoiselle</groupId>
  41 + <artifactId>demoiselle-jpa</artifactId>
  42 + <scope>compile</scope>
  43 +</dependency>]]></programlisting>
  44 + </tip>
  45 +
  46 + <section>
  47 + <title>Introdução ao mecanismo</title>
  48 +
  49 + <para>
  50 + Para injetar uma instância de <code>EntityManager</code> em sua aplicação, basta usar a anotação <code>@Inject</code>.
  51 + </para>
  52 +
  53 + <programlisting role="JAVA">@PersistenceController
  54 +public class BookmarkDAO extends JPACrud&lt;Bookmark, Long&gt; {
  55 +
  56 + private static final long serialVersionUID = 1L;
  57 +
  58 + @Inject
  59 + private EntityManager entityManager;
  60 +
  61 + public void persistBookmark(Bookmark bookmark){
  62 + entityManager.persist(bookmark);
  63 + }
  64 +
  65 +}</programlisting>
  66 +
  67 + <para>
  68 + O produtor padrão injetará o <code>EntityManager</code> configurado no arquivo <code>persistence.xml</code>. Se houver
  69 + mais de um contexto de persistência configurado em <code>persistence.xml</code>, será necessário especificar qual será
  70 + injetado no ponto de injeção. Para isso use a anotação <code>@Name</code>.
  71 + </para>
  72 +
  73 + <programlisting role="JAVA">@PersistenceController
  74 +public class BookmarkDAO extends JPACrud&lt;Bookmark, Long&gt; {
  75 +
  76 + private static final long serialVersionUID = 1L;
  77 +
  78 + @Inject
  79 + @Name("persistence_unit_1")
  80 + private EntityManager entityManager;
  81 +
  82 + public void persistBookmark(Bookmark bookmark){
  83 + entityManager.persist(bookmark);
  84 + }
  85 +
  86 +}</programlisting>
  87 +
  88 + <para>
  89 + É possível invocar o utilitário <code>Beans</code> para injetar instâncias de <code>EntityManager</code> programaticamente.
  90 + </para>
  91 +
  92 + <programlisting role="JAVA">@PersistenceController
  93 +public class BookmarkDAO extends JPACrud&lt;Bookmark, Long&gt; {
  94 +
  95 + private static final long serialVersionUID = 1L;
  96 +
  97 + public void persistBookmark(Bookmark bookmark){
  98 + EntityManager entityManager = Beans.getReference(EntityManager.class);
  99 + entityManager.persist(bookmark);
  100 + }
  101 +
  102 + public void persistBookmarkInHistory(Bookmark bookmark){
  103 + EntityManager entityManager = Beans.getReference(EntityManager.class , new NameQualifier("history_persistence_unit"));
  104 + entityManager.persist(bookmark);
  105 + }
  106 +
  107 +}</programlisting>
  108 + </section>
  109 +
  110 + <section>
  111 + <title>Configuração</title>
  112 +
  113 + <para>
  114 + Alguns comportamentos do produtor podem ser configurados através das propriedades abaixo, que devem ser configuradas
  115 + no arquivo <code>demoiselle.properties</code>.
  116 + </para>
  117 +
  118 + <informaltable width="100%">
  119 + <tgroup cols="3">
  120 + <colspec align="left"/>
  121 + <colspec align="left"/>
  122 + <colspec align="right"/>
  123 +
  124 + <thead>
  125 + <row valign="top">
  126 + <entry><emphasis role="bold">Propriedade</emphasis></entry>
  127 + <entry><emphasis role="bold">Descrição</emphasis></entry>
  128 + <entry><emphasis role="bold">Padrão</emphasis></entry>
  129 + </row>
  130 + </thead>
  131 +
  132 + <tbody>
  133 + <row valign="top">
  134 + <entry>frameworkdemoiselle.&#8203;persistence.&#8203;default.&#8203;unit.&#8203;name</entry>
  135 + <entry>
  136 + <para>
  137 + Define o nome da unidade de persistência padrão (configurada em <code>persistence.xml</code>) que será injetada
  138 + caso a anotação <code>@Name</code> não seja usada. Não é necessário se apenas uma unidade de persistência for configurada.
  139 + </para>
  140 + </entry>
  141 + <entry></entry>
  142 + </row>
  143 +
  144 + <row valign="top">
  145 + <entry>frameworkdemoiselle.&#8203;persistence.&#8203;entitymanager.&#8203;scope</entry>
  146 + <entry>
  147 + <para>
  148 + Permite determinar o escopo de unidades de persistência injetadas. Dentro do escopo determinado, todos os pontos
  149 + de injeção receberão a mesma instância de <code>EntityManager</code>.
  150 + </para>
  151 + <para>
  152 + Os valores possíveis são:
  153 + <simplelist type="inline">
  154 + <member>request</member>
  155 + <member>session</member>
  156 + <member>view</member>
  157 + <member>conversation</member>
  158 + <member>application</member>
  159 + <member>noscope</member>
  160 + </simplelist>
  161 + </para>
  162 + </entry>
  163 + <entry>request</entry>
  164 + </row>
  165 + </tbody>
  166 + </tgroup>
  167 + </informaltable>
  168 +
  169 + <tip>
  170 + <para>
  171 + O escopo especial <emphasis>noscope</emphasis> desliga o gerenciamento de escopo de instâncias de <code>EntityManager</code>
  172 + produzidas pelo Framework Demoiselle. Isso permite ao desenvolvedor controlar totalmente o ciclo de vida de um
  173 + <code>EntityManager</code> injetado e ainda reter o recurso do produtor padrão.
  174 + </para>
  175 + <para>
  176 + Note que ao usar a opção <emphasis>noscope</emphasis>, o desenvolvedor é o responsável por controlar o ciclo de vida do gerenciador
  177 + de persistência. Ele não participará de transações JPA abertas através da anotação <code>@Transactional</code> (transações JTA funcionam normalmente)
  178 + e multiplos pontos de injeção durante uma requisição receberão múltiplas instâncias de <code>EntityManager</code>.
  179 + </para>
  180 + </tip>
  181 +
  182 + <caution>
  183 + <para>
  184 + Deve-se usar cautela ao alterar o escopo padrão das instâncias de <code>EntityManager</code>. Na grande maioria dos casos o escopo
  185 + padrão <emphasis>request</emphasis> é o suficiente e alterar esse padrão deve ser feito apenas após extensa análise dos prós e contras
  186 + de cada escopo.
  187 + </para>
  188 + <para>
  189 + Dê especial atenção aos escopos que podem ser serializados pelo servidor de aplicação (<emphasis>session</emphasis>, <emphasis>view</emphasis>
  190 + e <emphasis>conversation</emphasis>) pois a especificação não define o comportamento de instâncias de <code>EntityManager</code> que são
  191 + serializadas.
  192 + </para>
  193 + </caution>
  194 + </section>
  195 + </section>
21 196  
22 197 <section>
23 198  
... ...
documentation/reference/pt-BR/properties.xml
  Diff comments   View file @9c3cb59
... ... @@ -251,12 +251,34 @@
251 251 <entry>frameworkdemoiselle.&#8203;persistence.&#8203;default.&#8203;unit.&#8203;name</entry>
252 252 <entry>
253 253 <para>
254   - Define a unidade de persistência padrão para aplicações que possuem mais
255   - de um persistence-unit definido no arquivo persistence.xml.
  254 + Define o nome da unidade de persistência padrão (configurada em <code>persistence.xml</code>) que será injetada
  255 + caso a anotação <code>@Name</code> não seja usada. Não é necessário se apenas uma unidade de persistência for configurada.
256 256 </para>
257 257 </entry>
258 258 <entry></entry>
259 259 </row>
  260 +
  261 + <row valign="top">
  262 + <entry>frameworkdemoiselle.&#8203;persistence.&#8203;entitymanager.&#8203;scope</entry>
  263 + <entry>
  264 + <para>
  265 + Permite determinar o escopo de unidades de persistência injetadas. Dentro do escopo determinado, todos os pontos
  266 + de injeção receberão a mesma instância de <code>EntityManager</code>.
  267 + </para>
  268 + <para>
  269 + Os valores possíveis são:
  270 + <simplelist type="inline">
  271 + <member>request</member>
  272 + <member>session</member>
  273 + <member>view</member>
  274 + <member>conversation</member>
  275 + <member>application</member>
  276 + <member>noscope</member>
  277 + </simplelist>
  278 + </para>
  279 + </entry>
  280 + <entry>request</entry>
  281 + </row>
260 282 </tbody>
261 283 </tgroup>
262 284 </table>
... ...
documentation/reference/pt-BR/transacao.xml
  Diff comments   View file @9c3cb59
... ... @@ -135,7 +135,7 @@ public class AbacaxiException {
135 135 <para>
136 136 Esta estratégia, que está disponível na extensão <literal>demoiselle-jpa</literal>, delega o
137 137 controle das transações para o <literal>javax.persistence.EntityManager</literal> da
138   - especificação JPA. Você deve escolher esta estratégia quando estiver persisteindo dados
  138 + especificação JPA. Você deve escolher esta estratégia quando estiver persistindo dados
139 139 com JPA e utilizando apenas uma base de dados em sua aplicação. Como um <literal>EntityManager</literal>
140 140 acessa apenas uma unidade de persistência, não há como fazer o controle transacional de unidades distintas.
141 141 </para>
... ...