Simplificação no texto da documentação de referência

Cleverson Sacramento
1 parent 6e0e58db
Showing 4 changed files with 21 additions and 20 deletions Show diff stats
documentation/reference/pt-BR/arquitetura.xml
documentation/reference/pt-BR/excecao.xml
documentation/reference/pt-BR/security.xml
documentation/reference/pt-BR/transacao.xml
@@ -41,10 +41,8 @@
 		<para>
 			As boas práticas de programação nos alertam para que nunca sejamos dependentes de implementações, mas sempre de
 			interfaces ou, como alguns costumam dizer, <quote>depender de contratos</quote>.
-			As interfaces existem para isto: definem um contrato, enquanto as implementações deste contrato ficam à parte, de
-			preferência, distante do programador da aplicação. O mecanismo de injeção de dependência fortalece ainda mais esta
-			ideia. Sua aplicação precisará apenas depender das interfaces que o Demoiselle provê. A implementação específica será
-			injetada automaticamente pelo CDI.
+			Portanto a sua aplicação precisará apenas depender das interfaces que o Demoiselle provê. As implementações específicas
+			e internas do Framework serão injetadas automaticamente pelo CDI.
 		</para>
 		<tip>
 			<para>
@@ -53,14 +51,13 @@
 		</tip>
 		<para>
 			Qual o motivo de toda esta explicação? Os programadores mais curiosos irão encontrar classes do framework que estão
-			inseridas no pacote <literal>internal</literal>. 
-			Cabe alertar que as classes aí contidas não devem ser usadas diretamente pela aplicação, caso contrário, você
-			estará acoplando-a com a implementação interna do framework, que pode sofrer mudanças sem aviso prévio. A equipe do
+			inseridas no pacote <literal>br.gov.frameworkdemoiselle.internal</literal>. 
+			As classes deste pacote não devem ser usadas diretamente pela sua aplicação, caso contrário você
+			estará acoplando-a com a implementação interna do Framework. A equipe do
 			Demoiselle possui atenção especial quanto às suas interfaces (contratos) e não irá modificá-las sem antes tornar
-			públicas as mudanças. Contudo, tudo que consta no pacote
-			<literal>internal</literal>
-			pode sofrer mudanças repentinas. Isto significa que sua aplicação pode deixar de funcionar de uma versão para outra
-			caso você esteja usando diretamente classes internas.
+			públicas as mudanças. Contudo, tudo que consta no pacote <literal>br.gov.frameworkdemoiselle.internal</literal>
+			pode sofrer mudanças repentinas. Se você referenciar tais classes internas, a sua aplicação pode deixar
+			de funcionar ao atualizar a versão do Demoiselle.
 		</para>
 	</section>
  
@@ -77,14 +74,14 @@
 			apresentação, regras de negócio e persistência. O Demoiselle já fornece estereótipos que visam tornar esta 
 			separação mais clara, respectivamente:
 			<literal>@ViewController</literal>, <literal>@BusinessController</literal> e <literal>@PersistenceController</literal>. 
-			Maiores detalhes sobre cada anotação desta serão dados no decorrer desta documentação.
+			Maiores detalhes sobre cada anotação serão dados no decorrer desta documentação.
 		</para>
 		<!-- TODO: explicar melhor cada um dos estereótipos, se possível exemplificando com códigos -->
 		<para>
-			Cabe destacar que estamos falando de uma macro-visão arquitetural. Cada camada desta pode ser organizada
+			Cabe destacar que estamos falando de uma macro-visão arquitetural. Cada camada pode ser organizada
 			internamente da melhor forma possível, ou conforme os padrões vigentes no mercado. Para uma aplicação Swing, por
 			exemplo, o padrão de projeto <emphasis>Presentation Model</emphasis>
-			é bastante indicado e pode ser adotado em aplicações nesta plataforma. Para aplicações Web, os frameworks
+			é bastante indicado. Para aplicações Web, os frameworks
 			especialistas geralmente aplicam o padrão MVC (Model/View/Controller).
 		</para>
 	</section>
@@ -22,7 +22,7 @@ xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;
 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
 			        http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
 	<interceptors>
-		<class>br.gov.frameworkdemoiselle.internal.interceptor.ExceptionHandlerInterceptor</class>
+		<class>br.gov.frameworkdemoiselle.exception.ExceptionHandlerInterceptor</class>
 	</interceptors>
 </beans>]]></programlisting>
     </section>
@@ -27,8 +27,8 @@ xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;
 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
 			        http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
 	<interceptors>
-		<class>br.gov.frameworkdemoiselle.internal.interceptor.RequiredPermissionInterceptor</class>
-		<class>br.gov.frameworkdemoiselle.internal.interceptor.RequiredRoleInterceptor</class>
+		<class>br.gov.frameworkdemoiselle.security.RequiredPermissionInterceptor</class>
+		<class>br.gov.frameworkdemoiselle.security.RequiredRoleInterceptor</class>
 	</interceptors>
 </beans>]]></programlisting>
     </section> 
@@ -34,7 +34,7 @@
 			               http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
  
 	   <interceptors>
-	   		<class>br.gov.frameworkdemoiselle.internal.interceptor.TransactionalInterceptor</class>
+	   		<class>br.gov.frameworkdemoiselle.transaction.TransactionalInterceptor</class>
 	   </interceptors>
 </beans>]]></programlisting>
     </section>
@@ -77,11 +77,15 @@ public class AbacaxiException {
 	<section>
 		<title>O objeto Transaction</title>
 		<para>
-			Para ter acesso à instância da transação corrente, basta injetá-la em sua classe.
+			Para ter acesso à instância da transação corrente, basta injetar <literal>TransactionContext</literal> em sua classe e obter a transação corrente.
 		</para>
 		<programlisting role="JAVA"><![CDATA[public class Simples {
 	@Inject
-	private Transaction transaction;
+	private TransactionContext transactionContext;
+
+	public void experimento() {
+		Transaction transaction = transactionContext.getCurrentTransaction();
+	}
 }]]></programlisting>
 	</section>
...	...	@@ -41,10 +41,8 @@
41	41	<para>
42	42	As boas práticas de programação nos alertam para que nunca sejamos dependentes de implementações, mas sempre de
43	43	interfaces ou, como alguns costumam dizer, <quote>depender de contratos</quote>.
44		- As interfaces existem para isto: definem um contrato, enquanto as implementações deste contrato ficam à parte, de
45		- preferência, distante do programador da aplicação. O mecanismo de injeção de dependência fortalece ainda mais esta
46		- ideia. Sua aplicação precisará apenas depender das interfaces que o Demoiselle provê. A implementação específica será
47		- injetada automaticamente pelo CDI.
	44	+ Portanto a sua aplicação precisará apenas depender das interfaces que o Demoiselle provê. As implementações específicas
	45	+ e internas do Framework serão injetadas automaticamente pelo CDI.
48	46	</para>
49	47	<tip>
50	48	<para>
...	...	@@ -53,14 +51,13 @@
53	51	</tip>
54	52	<para>
55	53	Qual o motivo de toda esta explicação? Os programadores mais curiosos irão encontrar classes do framework que estão
56		- inseridas no pacote <literal>internal</literal>.
57		- Cabe alertar que as classes aí contidas não devem ser usadas diretamente pela aplicação, caso contrário, você
58		- estará acoplando-a com a implementação interna do framework, que pode sofrer mudanças sem aviso prévio. A equipe do
	54	+ inseridas no pacote <literal>br.gov.frameworkdemoiselle.internal</literal>.
	55	+ As classes deste pacote não devem ser usadas diretamente pela sua aplicação, caso contrário você
	56	+ estará acoplando-a com a implementação interna do Framework. A equipe do
59	57	Demoiselle possui atenção especial quanto às suas interfaces (contratos) e não irá modificá-las sem antes tornar
60		- públicas as mudanças. Contudo, tudo que consta no pacote
61		- <literal>internal</literal>
62		- pode sofrer mudanças repentinas. Isto significa que sua aplicação pode deixar de funcionar de uma versão para outra
63		- caso você esteja usando diretamente classes internas.
	58	+ públicas as mudanças. Contudo, tudo que consta no pacote <literal>br.gov.frameworkdemoiselle.internal</literal>
	59	+ pode sofrer mudanças repentinas. Se você referenciar tais classes internas, a sua aplicação pode deixar
	60	+ de funcionar ao atualizar a versão do Demoiselle.
64	61	</para>
65	62	</section>
66	63
...	...	@@ -77,14 +74,14 @@
77	74	apresentação, regras de negócio e persistência. O Demoiselle já fornece estereótipos que visam tornar esta
78	75	separação mais clara, respectivamente:
79	76	<literal>@ViewController</literal>, <literal>@BusinessController</literal> e <literal>@PersistenceController</literal>.
80		- Maiores detalhes sobre cada anotação desta serão dados no decorrer desta documentação.
	77	+ Maiores detalhes sobre cada anotação serão dados no decorrer desta documentação.
81	78	</para>
82	79	<!-- TODO: explicar melhor cada um dos estereótipos, se possível exemplificando com códigos -->
83	80	<para>
84		- Cabe destacar que estamos falando de uma macro-visão arquitetural. Cada camada desta pode ser organizada
	81	+ Cabe destacar que estamos falando de uma macro-visão arquitetural. Cada camada pode ser organizada
85	82	internamente da melhor forma possível, ou conforme os padrões vigentes no mercado. Para uma aplicação Swing, por
86	83	exemplo, o padrão de projeto <emphasis>Presentation Model</emphasis>
87		- é bastante indicado e pode ser adotado em aplicações nesta plataforma. Para aplicações Web, os frameworks
	84	+ é bastante indicado. Para aplicações Web, os frameworks
88	85	especialistas geralmente aplicam o padrão MVC (Model/View/Controller).
89	86	</para>
90	87	</section>
...	...
...	...	@@ -22,7 +22,7 @@ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
22	22	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
23	23	http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
24	24	<interceptors>
25		- <class>br.gov.frameworkdemoiselle.internal.interceptor.ExceptionHandlerInterceptor</class>
	25	+ <class>br.gov.frameworkdemoiselle.exception.ExceptionHandlerInterceptor</class>
26	26	</interceptors>
27	27	</beans>]]></programlisting>
28	28	</section>
...	...
...	...	@@ -27,8 +27,8 @@ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
27	27	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
28	28	http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
29	29	<interceptors>
30		- <class>br.gov.frameworkdemoiselle.internal.interceptor.RequiredPermissionInterceptor</class>
31		- <class>br.gov.frameworkdemoiselle.internal.interceptor.RequiredRoleInterceptor</class>
	30	+ <class>br.gov.frameworkdemoiselle.security.RequiredPermissionInterceptor</class>
	31	+ <class>br.gov.frameworkdemoiselle.security.RequiredRoleInterceptor</class>
32	32	</interceptors>
33	33	</beans>]]></programlisting>
34	34	</section>
...	...
...	...	@@ -34,7 +34,7 @@
34	34	http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
35	35
36	36	<interceptors>
37		- <class>br.gov.frameworkdemoiselle.internal.interceptor.TransactionalInterceptor</class>
	37	+ <class>br.gov.frameworkdemoiselle.transaction.TransactionalInterceptor</class>
38	38	</interceptors>
39	39	</beans>]]></programlisting>
40	40	</section>
...	...	@@ -77,11 +77,15 @@ public class AbacaxiException {
77	77	<section>
78	78	<title>O objeto Transaction</title>
79	79	<para>
80		- Para ter acesso à instância da transação corrente, basta injetá-la em sua classe.
	80	+ Para ter acesso à instância da transação corrente, basta injetar <literal>TransactionContext</literal> em sua classe e obter a transação corrente.
81	81	</para>
82	82	<programlisting role="JAVA"><![CDATA[public class Simples {
83	83	@Inject
84		- private Transaction transaction;
	84	+ private TransactionContext transactionContext;
	85	+
	86	+ public void experimento() {
	87	+ Transaction transaction = transactionContext.getCurrentTransaction();
	88	+ }
85	89	}]]></programlisting>
86	90	</section>
87	91
...	...