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

https://demoiselle.atlassian.net/browse/FWK-123

issue FWK-123: Revisar e atualizar documentação do Framework 2.4.0
https://demoiselle.atlassian.net/browse/FWK-123
Dancovich
1 parent 682975f9
Showing 3 changed files with 200 additions and 3 deletions Show diff stats
documentation/reference/pt-BR/persistencia.xml
documentation/reference/pt-BR/properties.xml
documentation/reference/pt-BR/transacao.xml
@@ -18,6 +18,181 @@
 		&eacute; apenas injetar o recurso adequado em seu c&oacute;digo e o Framework Demoiselle se encarregar&aacute; de
 		produzi-lo e configur&aacute;-lo. 
 	</para>
+	
+	<section>
+		<title>JPA</title>
+		
+		<para>
+			O Framework Demoiselle fornece um produtor padrão para contextos de persistência da JPA. Esse produtor lê o arquivo
+			de configuração <code>persistence.xml</code> de seu projeto e toma as providências necessárias para fabricar uma instância
+			da classe <code>EntityManager</code> que pode ser usada para gerenciar as entidades de sua aplicação. Além disso, instâncias
+			de <code>EntityManager</code> produzidas pelo Framework Demoiselle participam automaticamente de transações abertas através da
+			anotação <code>@Transactional</code>, conforme apresentado no capítulo sobre <link linkend="transacao">Transações</link>.
+		</para>
+		
+		<tip>
+	 		<para>
+	 			Para acrescentar a dependência à extensão <literal>demoiselle-jpa</literal>, adicione esse código
+	 			em seu arquivo <literal>pom.xml</literal>, na seção <literal>dependencies</literal>.
+	 		</para>
+	 	
+	 		<programlisting role="XML"><![CDATA[<dependency>
+	<groupId>br.gov.frameworkdemoiselle</groupId>
+	<artifactId>demoiselle-jpa</artifactId>
+	<scope>compile</scope>
+</dependency>]]></programlisting>
+		</tip>
+		
+		<section>
+			<title>Introdução ao mecanismo</title>
+			
+			<para>
+				Para injetar uma instância de <code>EntityManager</code> em sua aplicação, basta usar a anotação <code>@Inject</code>.
+			</para>
+			
+			<programlisting role="JAVA">@PersistenceController
+public class BookmarkDAO extends JPACrud&lt;Bookmark, Long&gt; {
+	
+	private static final long serialVersionUID = 1L;
+	
+	@Inject
+	private EntityManager entityManager;
+	
+	public void persistBookmark(Bookmark bookmark){
+		entityManager.persist(bookmark);
+	}
+	
+}</programlisting>
+
+			<para>
+				O produtor padrão injetará o <code>EntityManager</code> configurado no arquivo <code>persistence.xml</code>. Se houver
+				mais de um contexto de persistência configurado em <code>persistence.xml</code>, será necessário especificar qual será
+				injetado no ponto de injeção. Para isso use a anotação <code>@Name</code>.
+			</para>
+			
+			<programlisting role="JAVA">@PersistenceController
+public class BookmarkDAO extends JPACrud&lt;Bookmark, Long&gt; {
+	
+	private static final long serialVersionUID = 1L;
+	
+	@Inject
+	@Name("persistence_unit_1")
+	private EntityManager entityManager;
+	
+	public void persistBookmark(Bookmark bookmark){
+		entityManager.persist(bookmark);
+	}
+	
+}</programlisting>
+
+			<para>
+				É possível invocar o utilitário <code>Beans</code> para injetar instâncias de <code>EntityManager</code> programaticamente. 
+			</para>
+			
+			<programlisting role="JAVA">@PersistenceController
+public class BookmarkDAO extends JPACrud&lt;Bookmark, Long&gt; {
+	
+	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);
+	}
+	
+}</programlisting>
+		</section>
+		
+		<section>
+			<title>Configuração</title>
+			
+			<para>
+				Alguns comportamentos do produtor podem ser configurados através das propriedades abaixo, que devem ser configuradas
+				no arquivo <code>demoiselle.properties</code>.
+			</para>
+			
+			<informaltable width="100%">
+				<tgroup cols="3">
+					<colspec align="left"/>
+					<colspec align="left"/>
+					<colspec align="right"/>
+					
+					<thead>
+						<row valign="top">
+							<entry><emphasis role="bold">Propriedade</emphasis></entry>
+							<entry><emphasis role="bold">Descrição</emphasis></entry>
+							<entry><emphasis role="bold">Padrão</emphasis></entry>
+						</row>
+					</thead>
+					
+					<tbody>
+						<row valign="top">
+							<entry>frameworkdemoiselle.&#8203;persistence.&#8203;default.&#8203;unit.&#8203;name</entry>
+							<entry>
+								<para>
+									Define o nome da unidade de persistência padrão (configurada em <code>persistence.xml</code>) que será injetada
+									caso a anotação <code>@Name</code> não seja usada. Não é necessário se apenas uma unidade de persistência for configurada.
+								</para>
+							</entry>
+							<entry></entry>
+						</row>
+						
+						<row valign="top">
+							<entry>frameworkdemoiselle.&#8203;persistence.&#8203;entitymanager.&#8203;scope</entry>
+							<entry>
+								<para>
+									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 <code>EntityManager</code>.
+								</para>
+								<para>
+									Os valores possíveis são:
+									<simplelist type="inline">
+										<member>request</member>
+										<member>session</member>
+										<member>view</member>
+										<member>conversation</member>
+										<member>application</member>
+										<member>noscope</member>
+									</simplelist>
+								</para>
+							</entry>
+							<entry>request</entry>
+						</row>
+					</tbody>
+				</tgroup>
+			</informaltable>
+			
+			<tip>
+				<para>
+					O escopo especial <emphasis>noscope</emphasis> desliga o gerenciamento de escopo de instâncias de <code>EntityManager</code>
+					produzidas pelo Framework Demoiselle. Isso permite ao desenvolvedor controlar totalmente o ciclo de vida de um
+					<code>EntityManager</code> injetado e ainda reter o recurso do produtor padrão. 
+				</para>
+				<para>
+					Note que ao usar a opção <emphasis>noscope</emphasis>, 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 <code>@Transactional</code> (transações JTA funcionam normalmente)
+					e multiplos pontos de injeção durante uma requisição receberão múltiplas instâncias de <code>EntityManager</code>.
+				</para>
+			</tip>
+			
+			<caution>
+				<para>
+					Deve-se usar cautela ao alterar o escopo padrão das instâncias de <code>EntityManager</code>. Na grande maioria dos casos o escopo
+					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
+					de cada escopo.
+				</para>
+				<para>
+					Dê especial atenção aos escopos que podem ser serializados pelo servidor de aplicação (<emphasis>session</emphasis>, <emphasis>view</emphasis>
+					e <emphasis>conversation</emphasis>) pois a especificação não define o comportamento de instâncias de <code>EntityManager</code> que são
+					serializadas.
+				</para>
+			</caution>
+		</section>
+	</section>
  
 	<section>
  
@@ -251,12 +251,34 @@
 						<entry>frameworkdemoiselle.&#8203;persistence.&#8203;default.&#8203;unit.&#8203;name</entry>
 						<entry>
 							<para>
-								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 <code>persistence.xml</code>) que será injetada
+								caso a anotação <code>@Name</code> não seja usada. Não é necessário se apenas uma unidade de persistência for configurada.
 							</para>
 						</entry>
 						<entry></entry>
 					</row>
+					
+					<row valign="top">
+						<entry>frameworkdemoiselle.&#8203;persistence.&#8203;entitymanager.&#8203;scope</entry>
+						<entry>
+							<para>
+								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 <code>EntityManager</code>.
+							</para>
+							<para>
+								Os valores possíveis são:
+								<simplelist type="inline">
+									<member>request</member>
+									<member>session</member>
+									<member>view</member>
+									<member>conversation</member>
+									<member>application</member>
+									<member>noscope</member>
+								</simplelist>
+							</para>
+						</entry>
+						<entry>request</entry>
+					</row>
 				</tbody>
 			</tgroup>
 		</table>
@@ -135,7 +135,7 @@ public class AbacaxiException {
 		<para>
 			Esta estratégia, que está disponível na extensão <literal>demoiselle-jpa</literal>, delega o
 			controle das transações para o <literal>javax.persistence.EntityManager</literal> 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 <literal>EntityManager</literal>
 			acessa apenas uma unidade de persistência, não há como fazer o controle transacional de unidades distintas.
 		</para>
...	...	@@ -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<Bookmark, Long> {
	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<Bookmark, Long> {
	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<Bookmark, Long> {
	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.persistence.default.unit.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.persistence.entitymanager.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
...	...
...	...	@@ -251,12 +251,34 @@
251	251	<entry>frameworkdemoiselle.persistence.default.unit.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.persistence.entitymanager.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>
...	...
...	...	@@ -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>
...	...