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,6 +18,181 @@
18	é apenas injetar o recurso adequado em seu código e o Framework Demoiselle se encarregará de	18	é apenas injetar o recurso adequado em seu código e o Framework Demoiselle se encarregará de
19	produzi-lo e configurá-lo.	19	produzi-lo e configurá-lo.
20	</para>	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	<section>	197	<section>
23		198
	@@ -251,12 +251,34 @@		@@ -251,12 +251,34 @@
251	<entry>frameworkdemoiselle.persistence.default.unit.name</entry>	251	<entry>frameworkdemoiselle.persistence.default.unit.name</entry>
252	<entry>	252	<entry>
253	<para>	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	</para>	256	</para>
257	</entry>	257	</entry>
258	<entry></entry>	258	<entry></entry>
259	</row>	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	</tbody>	282	</tbody>
261	</tgroup>	283	</tgroup>
262	</table>	284	</table>
	@@ -135,7 +135,7 @@ public class AbacaxiException {		@@ -135,7 +135,7 @@ public class AbacaxiException {
135	<para>	135	<para>
136	Esta estratégia, que está disponível na extensão <literal>demoiselle-jpa</literal>, delega o	136	Esta estratégia, que está disponível na extensão <literal>demoiselle-jpa</literal>, delega o
137	controle das transações para o <literal>javax.persistence.EntityManager</literal> da	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	com JPA e utilizando apenas uma base de dados em sua aplicação. Como um <literal>EntityManager</literal>	139	com JPA e utilizando apenas uma base de dados em sua aplicação. Como um <literal>EntityManager</literal>
140	acessa apenas uma unidade de persistência, não há como fazer o controle transacional de unidades distintas.	140	acessa apenas uma unidade de persistência, não há como fazer o controle transacional de unidades distintas.
141	</para>	141	</para>