Download as
Browse Code »

Commit 024b3776cbf78da6f7557ed0b351adb62ee30a92

Authored by Emerson Oliveira
1 parent ff0beac2
Exists in master

Atualização da documentação de referência, relativa as mudanças do 

framework para a versão 2.3.0-RC3.
Showing 17 changed files with 173 additions and 96 deletions   Show diff stats
documentation/reference/pt-BR/arquetipo.xml
  Diff comments   View file @024b377
... ... @@ -6,9 +6,9 @@
6 6 <title>Arquétipos</title>
7 7  
8 8 <para>
9   - Como o projeto Demoiselle recomenda e usa a ferramenta <ulink url="http://maven.apache.org/">Apache-Maven</ulink> , para gerenciamento do ciclo de vida do desenvolvimento
  9 + O projeto Demoiselle recomenda e usa a ferramenta <ulink url="http://maven.apache.org/">Apache-Maven</ulink> , para gerenciamento do ciclo de vida do desenvolvimento
10 10 de projeto. Baseada nesta ferramenta, além do fornecimento dos POMs Parentes, também fornece as estruturas chamadas <ulink url="http://maven.apache.org/archetype/maven-archetype-plugin/">arquétipos</ulink>
11   - para facilitar a criação de aplicações, garantido a estrutura recomendada pelo framework e conceito de gerenciamento do próprio Maven.
  11 + para facilitar a criação de aplicações, garantido a estrutura recomendada pelo framework e o conceito de gerenciamento do próprio Maven.
12 12 Atualmente estão disponíveis os seguintes artefatos:
13 13 </para>
14 14  
... ... @@ -27,7 +27,7 @@
27 27 é baseado no Demoiselle-JSF-Parent,
28 28 e que já traz uma estrutura padrão de pacotes e todas
29 29 as dependências necessárias para rodar a aplicação. Ao usar este
30   - arquétipo, você já terá uma pequena aplicação de
  30 + arquétipo, você terá uma pequena aplicação de
31 31 Bookmarks já pronta para rodar. Para isto, basta instalá-la em um
32 32 servidor da sua preferência! Para mais detalhes
33 33 sobre esta aplicação de exemplo e em como usar o arquétipo, acesse
... ...
documentation/reference/pt-BR/arquitetura.xml
  Diff comments   View file @024b377
... ... @@ -30,7 +30,9 @@
30 30 Já os Componentes são artefatos separados e que, portanto, não são dependentes diretamente do Core. Aliás, os
31 31 Componentes podem até mesmo existir sem referenciar o Core. Desta forma, o seu ciclo de vida é totalmente
32 32 independente do Core e Extensões. Um componente não precisa, necessariamente, estender o comportamento do Core, mas
33   - permitir disponibilizar novas funcionalidades ao usuário. Um exemplo é o <literal>demoiselle-validation</literal>.
  33 + permitir disponibilizar novas funcionalidades ao usuário. Outra diferença importante é que, diferente de Core e
  34 + Extensões, os Componentes não necessariamente são aderentes a alguma especificação. Um exemplo é o
  35 + <literal>demoiselle-validation</literal>.
34 36 </para>
35 37 </section>
36 38  
... ...
documentation/reference/pt-BR/authorgroup.xml
  Diff comments   View file @024b377
... ... @@ -8,9 +8,17 @@
8 8 </author>
9 9 <author>
10 10 <firstname>Emerson</firstname>
  11 + <surname>Oliveira</surname>
  12 + </author>
  13 + <author>
  14 + <firstname>Emerson</firstname>
11 15 <surname>Saito</surname>
12 16 </author>
13 17 <author>
  18 + <firstname>Luciano</firstname>
  19 + <surname>Borges</surname>
  20 + </author>
  21 + <author>
14 22 <firstname>Marlon</firstname>
15 23 <surname>Carvalho</surname>
16 24 </author>
... ... @@ -34,12 +42,4 @@
34 42 <firstname>Wilson</firstname>
35 43 <surname>Guimarães</surname>
36 44 </author>
37   - <author>
38   - <firstname>Emerson</firstname>
39   - <surname>Oliveira</surname>
40   - </author>
41   - <author>
42   - <firstname>Luciano</firstname>
43   - <surname>Borges</surname>
44   - </author>
45 45 </authorgroup>
... ...
documentation/reference/pt-BR/bookinfo.xml
  Diff comments   View file @024b377
... ... @@ -3,11 +3,11 @@
3 3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" []>
4 4 <bookinfo>
5 5  
6   - <title>Framework Demoiselle 2.2.0</title>
  6 + <title>Framework Demoiselle 2.3.0</title>
7 7 <subtitle>Guia de Referência</subtitle>
8 8  
9   - <abstract>Demoiselle 2.2.0: Framework de Código Aberto para o Desenvolvimento de Aplicações Java EE 6</abstract>
10   - <titleabbrev>Demoiselle 2.2.0 - Guia de Referência</titleabbrev>
  9 + <abstract>Demoiselle 2.3.0: Framework de Código Aberto para o Desenvolvimento de Aplicações Java EE 6</abstract>
  10 + <titleabbrev>Demoiselle 2.3.0 - Guia de Referência</titleabbrev>
11 11  
12 12 <xi:include href="revhistory.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
13 13 <xi:include href="authorgroup.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
... ...
documentation/reference/pt-BR/configuracao.xml
  Diff comments   View file @024b377
... ... @@ -46,6 +46,7 @@
46 46 </para>
47 47 </section>
48 48  
  49 + <!--
49 50 <section>
50 51 <title>Configurando</title>
51 52 <para>
... ... @@ -64,6 +65,7 @@
64 65 ]]>
65 66 </programlisting>
66 67 </section>
  68 + -->
67 69  
68 70 <section>
69 71 <title>As classes de configuração</title>
... ... @@ -233,7 +235,8 @@ general.load.initial.data = true
233 235 <para>
234 236 Além de <literal>String</literal> e <literal>boolean</literal>, existe a possibilidade de se recuperar valores de qualquer
235 237 tipo primitivo do Java (i.e., <literal>int, byte, short, char, long, float, double</literal> e <literal>boolean</literal>)
236   - e também arrays desses tipos.
  238 + e também arrays desses tipos e de alguns tipos complexos (i.e., <literal>Integer, BigDecimal, BigInteger, Calendar, Date,
  239 + Color, Locale, URL</literal> e <literal>String</literal>).
237 240 </para>
238 241 </tip>
239 242 </section>
... ...
documentation/reference/pt-BR/controlador.xml
  Diff comments   View file @024b377
... ... @@ -42,7 +42,7 @@
42 42 public @interface SeuController {
43 43 }]]></programlisting>
44 44 <para>
45   - Neste exemplo foi criado um controlador chamado <literal>SeuController</literal> quem tem a característica de ter um escopo de
  45 + Neste exemplo foi criado um controlador chamado <literal>SeuController</literal> que tem a característica de ter um escopo de
46 46 View. Isto quer dizer que toda classe que seja desse tipo de controlador, também terá o escopo de View.
47 47 </para>
48 48 <!-- TODO: qual a vantagem em se criar um controlador customizado? incluir um exemplo possível e prático de utilização disso -->
... ...
documentation/reference/pt-BR/excecao.xml
  Diff comments   View file @024b377
... ... @@ -122,10 +122,10 @@ public class Simples {
122 122 <section>
123 123 <title>Exceção de Aplicação</title>
124 124 <para>
125   - Imagine que você precise informar que caso um determinado tipo de exceção seja lançado através do seu método, a transação atual sofrerá um <emphasis>rollback</emphasis>.
126   - Ou, então, que haja necessidade de informar o grau de severidade da exceção, de forma que uma camada de apresentação específica a trate de forma
127   - diferenciada. Estas duas opções são possíveis através do uso da anotação <literal>@ApplicationException</literal>. Utilize-a em suas exceções e informe
128   - os atributos <literal>rollback</literal> e <literal>severity</literal> para alcançar os objetivos acima.
  125 + Imagine que você precise informar que caso um determinado tipo de exceção seja lançado através do seu método, a transação atual sofrerá um
  126 + <emphasis>rollback</emphasis>. Ou, então, que haja necessidade de informar o grau de severidade da exceção, de forma que uma camada de apresentação
  127 + específica a trate de forma diferenciada. Estas duas opções são possíveis através do uso da anotação <literal>@ApplicationException</literal>.
  128 + Utilize-a em suas exceções e informe os atributos <literal>rollback</literal> e <literal>severity</literal> para alcançar os objetivos acima.
129 129 </para>
130 130 <programlisting role="JAVA"><![CDATA[@ApplicationException(rollback=true, severity=SeverityType.INFO)
131 131 public class MinhaException extends Exception {
... ... @@ -141,14 +141,15 @@ public class MinhaException extends Exception {
141 141 <section>
142 142 <title>Tratamento Padrão</title>
143 143 <para>
144   - As exceções lançadas a partir da camada de negócio, ou de persistência, não causam a interrupção de sua aplicação. Muito menos, apresentam a tela padrão de erro do JSF ou
145   - de outra tecnologia de visão. Qualquer exceção lançada, e que chega até a camada de apresentação, recebe um tratamento especial. Inicialmente, ela é encapsulada de forma
146   - que possa ser exibida de forma elegante para o usuário. No caso do JSF, é utilizado o mecanismo de Messages próprio desta tecnologia.
  144 + As exceções lançadas a partir da camada de negócio, ou de persistência, não causam a interrupção de sua aplicação. Muito menos, apresentam a tela
  145 + padrão de erro do JSF ou de outra tecnologia de visão. Qualquer exceção lançada, e que chega até a camada de apresentação, recebe um tratamento
  146 + especial. Inicialmente, ela é encapsulada de forma que possa ser exibida de forma elegante para o usuário. No caso do JSF, é utilizado o mecanismo
  147 + de Messages próprio desta tecnologia.
147 148 </para>
148 149 <para>
149   - No caso do Vaadin, o tratamento é bem semelhante, contudo, a exceção é tratada de forma que possa ser exibida adotando os mecanismos próprios da tecnologia. No caso de
150   - exceções que não usam a anotação <literal>@ApplicationException</literal>, um <emphasis>rollback</emphasis> é realizado de forma automática. Por último, sem o uso desta
151   - anotação, toda exceção é vista como tendo nível de gravidade igual a <literal>ERROR</literal>.
  150 + No caso do Vaadin, o tratamento é bem semelhante, contudo, a exceção é tratada de forma que possa ser exibida adotando os mecanismos próprios da
  151 + tecnologia. No caso de exceções que não usam a anotação <literal>@ApplicationException</literal>, um <emphasis>rollback</emphasis> é realizado
  152 + de forma automática. Por último, sem o uso desta anotação, toda exceção é vista como tendo nível de gravidade igual a <literal>ERROR</literal>.
152 153 </para>
153 154 </section>
154 155  
... ...
documentation/reference/pt-BR/inicializacao.xml
  Diff comments   View file @024b377
... ... @@ -36,25 +36,27 @@
36 36 <para>
37 37 As instruções contidas em um método anotado com <literal>@Startup</literal> serão executadas automaticamente quando a aplicação
38 38 Java for inicializada, seja ela hospedada em um contêiner Web ou executada através de um método <literal>main()</literal>.
39   - Nenhum outro arquivo ou classe precisa ser definido. A anotação <literal>@Startup</literal> permite a indicação do argumento
40   - <literal>priority</literal>, um número inteiro que serve para definir a prioridade de execução do respectivo método na existência
41   - de mais de um inicializador para a aplicação.
  39 + Nenhum outro arquivo ou classe precisa ser definido. A anotação <literal>@Startup</literal> pode ser utilizada em conjunto com a anotação
  40 + <literal>@Priority</literal>, que recebe como parametro um número inteiro que serve para definir a prioridade de execução do respectivo
  41 + método, na existência de mais de um inicializador para a aplicação.
42 42 </para>
43 43 <para>
44 44 De maneira análoga, um método anotado com <literal>@Shutdown</literal> será executado no momento de finalização de uma aplicação,
45   - obedecendo também à ordem de prioridade definida com o argumento <literal>priority</literal>.
  45 + obedecendo também à ordem de prioridade definida com a anotação <literal>@Priority</literal>.
46 46 </para>
47 47 <para>
48 48 Eis um exemplo de implementação de inicializador em uma aplicação:
49 49 </para>
50 50 <programlisting role="JAVA"><![CDATA[public class BookmarkInitializer {
51 51  
52   - @Startup(priority = 1)
  52 + @Startup
  53 + @Priority(1)
53 54 public void initialize() {
54 55 ...
55 56 }
56 57  
57   - @Shutdown(priority = 5)
  58 + @Shutdown
  59 + @Priority(5)
58 60 public void finalize() {
59 61 ...
60 62 }
... ... @@ -64,7 +66,7 @@
64 66 <para>
65 67 Para a definição de prioridade de execução de um método na inicialização ou finalização, podem ser
66 68 utilizadas as constantes <literal>MIN_PRIORITY</literal> ou <literal>MAX_PRIORITY</literal> presentes em
67   - <literal>br.gov.frameworkdemoiselle.annotation.Startup</literal>.
  69 + <literal>br.gov.frameworkdemoiselle.annotation.Priority</literal>.
68 70 </para>
69 71 </tip>
70 72 </section>
... ... @@ -75,11 +77,11 @@
75 77 Eis um interessante caso de uso de inicialização e finalização: rodar um servidor de modo standalone em paralelo à
76 78 execução da aplicação principal. Eis o código referente à essa implementação:
77 79 </para>
78   - <programlisting role="JAVA"><![CDATA[import br.gov.frameworkdemoiselle.annotation.Shutdown;
79   -import br.gov.frameworkdemoiselle.annotation.Startup;
  80 + <programlisting role="JAVA"><![CDATA[import br.gov.frameworkdemoiselle.lifecycle.Shutdown;
  81 +import br.gov.frameworkdemoiselle.lifecycle.Startup;
80 82  
81   -import static br.gov.frameworkdemoiselle.annotation.Startup.MAX_PRIORITY;
82   -import static br.gov.frameworkdemoiselle.annotation.Startup.MIN_PRIORITY;
  83 +import static br.gov.frameworkdemoiselle.annotation.Priority.MAX_PRIORITY;
  84 +import static br.gov.frameworkdemoiselle.annotation.Priority.MIN_PRIORITY;
83 85  
84 86 public class DatabaseServer {
85 87  
... ... @@ -93,12 +95,14 @@ public class DatabaseServer {
93 95 server.setSilent(true);
94 96 }
95 97  
96   - @Startup(priority = MAX_PRIORITY)
  98 + @Startup
  99 + @Priority(MAX_PRIORITY)
97 100 public void startup() {
98 101 server.start();
99 102 }
100 103  
101   - @Shutdown(priority = MIN_PRIORITY)
  104 + @Shutdown
  105 + @Priority (MIN_PRIORITY)
102 106 public void shutdown() {
103 107 server.stop();
104 108 }
... ...
documentation/reference/pt-BR/intro.xml
  Diff comments   View file @024b377
... ... @@ -18,16 +18,13 @@
18 18 <para>
19 19 O nome <emphasis>Demoiselle</emphasis>
20 20 é uma homenagem à série de aeroplanos construídos por Santos Dummont entre 1907 e 1909. Também conhecido como
21   - <emphasis>Libellule</emphasis>, as Demoiselles foram os melhores,
22   - menores e mais baratos aviões da sua época. Como sua intenção era popularizar a
23   - aviação com fabricação em larga escala, o inventor disponibilizou os planos em revistas técnicas para qualquer pessoa
24   - que se interessasse.
  21 + <emphasis>Libellule</emphasis>, as Demoiselles foram os melhores, menores e mais baratos aviões da sua época. Como
  22 + sua intenção era popularizar a aviação com fabricação em larga escala, o inventor disponibilizou os planos em revistas
  23 + técnicas para qualquer pessoa que se interessasse.
25 24 </para>
26 25 <para>
27   - O <emphasis>framework Demoiselle</emphasis>
28   - usa a mesma filosofia do <quote>Pai da Aviação</quote>,
29   - tendo sido disponibilizado como software livre em abril de 2009, sob a
30   - licença livre LGPL version 3. Mais informações no portal
  26 + O <emphasis>framework Demoiselle</emphasis> usa a mesma filosofia do <quote>Pai da Aviação</quote>, tendo sido
  27 + disponibilizado como software livre em abril de 2009, sob a licença livre LGPL version 3. Mais informações no portal
31 28 <ulink url="http://www.frameworkdemoiselle.gov.br">"www.frameworkdemoiselle.gov.br</ulink>
32 29 </para>
33 30 </section>
... ...
documentation/reference/pt-BR/master.xml
  Diff comments   View file @024b377
... ... @@ -14,7 +14,7 @@
14 14 </para>
15 15 <note>
16 16 <para>
17   - Esta documentação refere-se à release 2.2 do <emphasis>Framework Demoiselle</emphasis>
  17 + Esta documentação refere-se à release 2.3 do <emphasis>Framework Demoiselle</emphasis>
18 18 e pode diferir significativamente das versões anteriores.
19 19 </para>
20 20 </note>
... ...
documentation/reference/pt-BR/mensagem.xml
  Diff comments   View file @024b377
... ... @@ -8,8 +8,8 @@
8 8 <section>
9 9 <title>Mensagens em uma aplicação</title>
10 10 <para>
11   - Uma aplicação bem estruturada, seja na plataforma Web ou desktop, deve exibir mensagens informativas,
12   - de aviso ou de erro ao usuário após efetuar determinadas tarefas. Por exemplo, após gravar um registro
  11 + Uma aplicação bem estruturada, seja na plataforma Web ou Desktop, deve exibir mensagens informativas,
  12 + de aviso, ou de erro para o usuário após efetuar determinadas tarefas. Por exemplo, após gravar um registro
13 13 no banco de dados, é aconselhável que a aplicação exiba uma mensagem informativa. Se alguma exceção
14 14 ocorreu, é preciso exibir uma mensagem de erro. Ou seja, a severidade da mensagem deve ser escolhida de
15 15 acordo com o resultado da execução.
... ...
documentation/reference/pt-BR/paginacao.xml
  Diff comments   View file @024b377
... ... @@ -20,7 +20,7 @@
20 20 A apresentação de conjuntos de registros de médio a grande porte em formato de tabelas em aplicações Web geralmente requer um
21 21 <emphasis>mecanismo de paginação</emphasis>, o qual permite ao cliente ver apenas um pedaço do resultado final, podendo este
22 22 navegar para frente e para trás através dos registros. A menos que o conjunto de registros seja garantidamente pequeno, qualquer
23   - aplicação do tipo Web com funcionalidades de busca precisa ser dotada de paginação.
  23 + aplicação do tipo Web com funcionalidades de busca e/ou listagem de registros, precisa ser dotada de paginação.
24 24 </para>
25 25 <para>
26 26 O mecanismo de paginação para as aplicações fornecido pelo <emphasis>Demoiselle Framework</emphasis> consiste em um algoritmo
... ...
documentation/reference/pt-BR/parametro.xml
  Diff comments   View file @024b377
... ... @@ -43,7 +43,7 @@
43 43 nome diferente ao objeto, ele pode anotá-lo com <literal>@Name</literal> e no valor dessa anotação, colocar o
44 44 nome do parâmetro. Por default o objeto criado tem o escopo de request, mas é possível usar o escopo de sessão
45 45 ou de visão, bastando anotar o objeto com <literal>@SessionScoped</literal> ou <literal>@ViewScoped</literal>,
46   - respectivamente. Veja abaixo como ficaria essa passagem de parãmetros na versão 2.X do Demoiselle.
  46 + respectivamente. Veja abaixo como ficaria essa passagem de parâmetros na versão 2.X do Demoiselle.
47 47 </para>
48 48 <para>
49 49 Passagem do parâmetro
... ...
documentation/reference/pt-BR/parentsPom.xml
  Diff comments   View file @024b377
... ... @@ -32,19 +32,34 @@ Assim, a alteração no POM.XML da aplicação será a minima possível. Outra v
32 32 </section>
33 33  
34 34 <section>
35   - <title>Demoiselle-WEB-Parent</title>
  35 + <title>Demoiselle-SE-Parent</title>
36 36 <para>
37   - Especialização do POM mínimo, contendo configurações úteis para todas as aplicações JEE6/Web que utilizam o Demoiselle, mas sem a definição de
38   - qual camada de apresentação utilizará.
  37 + Especialização do POM mínimo, contendo configurações úteis para todas as aplicações <!-- SE -->Desktop que utilizam o framework, mas sem definição da
  38 + camada de apresentação que será utilizada.
  39 + </para>
  40 + </section>
  41 +
  42 + <section>
  43 + <title>Demoiselle-Servlet-Parent</title>
  44 + <para>
  45 + Especialização do POM mínimo, contendo profiles para Tomcat 6, Tomcat 7, GAE, Glassfish 3, JBoss 6 e JBoss 7, e outras configurações úteis para todas
  46 + as aplicações JEE6/Web que utilizam o Demoiselle, mas sem a definição de qual camada de apresentação utilizará. Entre as dependências referênciadas
  47 + por este POM está a extensão Demoiselle-Servlet.
39 48 </para>
40 49 </section>
41 50  
42 51 <section>
43 52 <title>Demoiselle-JSF-Parent</title>
44 53 <para>
45   - Especialização do POM demoiselle-web-parent, contendo configurações úteis e necessárias para todas as aplicações que utilizarão a tecnologia JSF2
46   - para camada de apresentação.
47   - Entre as dependências referênciadas por este POM está obviamente a extensão Demoiselle-JSF.
  54 + Especialização do POM demoiselle-servlet-parent, contendo configurações úteis e necessárias para todas as aplicações que utilizarão a tecnologia JSF2
  55 + para camada de apresentação. Entre as dependências referênciadas por este POM está obviamente a extensão Demoiselle-JSF.
  56 + </para>
  57 + </section>
  58 +
  59 + <section>
  60 + <title>Demoiselle-Archetype-Parent</title>
  61 + <para>
  62 + Contém configurações comuns a todos os projetos geradores de arquétipos.
48 63 </para>
49 64 </section>
50 65  
... ...
documentation/reference/pt-BR/properties.xml
  Diff comments   View file @024b377
... ... @@ -8,14 +8,14 @@
8 8 <para>
9 9 Em um projeto com o <emphasis>Demoiselle Framework</emphasis>, algumas propriedades e configurações
10 10 do <emphasis>Framework</emphasis> podem ser ajustadas no arquivo <literal>demoiselle.properties</literal>.
11   - Além disso, a partir da versão 2.3.0 também é nesse arquivo que devem ser definidas as estratégias de
12   - <emphasis>Transação</emphasis>, <emphasis>Autorização</emphasis> e <emphasis>Autenticação</emphasis>.
  11 + <!--Além disso, a partir da versão 2.3.0 também é nesse arquivo que devem ser definidas as estratégias de
  12 + <emphasis>Transação</emphasis>, <emphasis>Autorização</emphasis> e <emphasis>Autenticação</emphasis>.
13 13 </para>
14   - <para>
  14 + <para>-->
15 15 A seguir listamos as propriedades e configurações do <emphasis>Demoiselle Framework</emphasis> que o usuário pode modificar,
16   - acompanhados de alguns exemplos ilustrativos. Também mostraremos como escolher as estratégias para
  16 + acompanhados de alguns exemplos ilustrativos. <!-- Também mostraremos como escolher as estratégias para
17 17 <emphasis>Transação</emphasis>, <emphasis>Autorização</emphasis> e <emphasis>Autenticação</emphasis>, oferecidas pelo
18   - <emphasis>Demoiselle</emphasis>.
  18 + <emphasis>Demoiselle</emphasis>. -->
19 19 </para>
20 20  
21 21 <section>
... ... @@ -151,7 +151,7 @@
151 151 </para>
152 152 </section>
153 153  
154   - <section>
  154 + <!-- <section>
155 155 <title>Escolhendo Estratégias</title>
156 156 <para>
157 157 Para escolher as estratégias de <emphasis>Transação</emphasis>, <emphasis>Autorização</emphasis> e <emphasis>Autenticação</emphasis>
... ... @@ -184,5 +184,5 @@
184 184 As instruções para você construir e utilizar sua própria estratégia estãodescritas nos capítulos <link linkend="transacao">Transação</link>
185 185 e <link linkend="security">Segurança</link>.
186 186 </para>
187   - </section>
  187 + </section> -->
188 188 </chapter>
... ...
documentation/reference/pt-BR/security.xml
  Diff comments   View file @024b377
... ... @@ -20,7 +20,7 @@
20 20 <section>
21 21 <title>Configurando</title>
22 22 <para>
23   - Para um correto funcionamento do Demoiselle é necessário inserir od interceptadores de segurança no arquivo <filename>src/main/WEB-INF/beans.xml</filename>.
  23 + Para um correto funcionamento do Demoiselle é necessário inserir os interceptadores de segurança no arquivo <filename>src/main/WEB-INF/beans.xml</filename>.
24 24 </para>
25 25 <programlisting role="XML">
26 26 <![CDATA[
... ... @@ -179,10 +179,11 @@ public class Credential {
179 179 Após toda essa explicação, fica a dúvida: como implementar um esquema de segurança sem utilizar a extensão existente?
180 180 </para>
181 181 <para>
182   - O primeiro passo é criar classes para implementar as interfaces Authenticator e Authorizer. Essas classes devem ser
183   - anotadas com @Alternative para que o CDI saiba que se trata de uma estratégia:
  182 + O primeiro passo é criar classes para implementar as interfaces Authenticator e Authorizer. O <literal>Demoiselle</literal> detecta automaticamente
  183 + a implementação, e torna essa classe a implementação padrão dessas interfaces:<!-- Essas classes devem ser
  184 + anotadas com @Alternative para que o CDI saiba que se trata de uma estratégia: -->
184 185 </para>
185   - <programlisting role="JAVA"><![CDATA[@Alternative
  186 + <programlisting role="JAVA"><![CDATA[
186 187 public class MeuAuthenticator implements Authenticator {
187 188  
188 189 @Override
... ... @@ -204,7 +205,7 @@ public class MeuAuthenticator implements Authenticator {
204 205 }
205 206  
206 207 }]]></programlisting>
207   - <programlisting role="JAVA"><![CDATA[@Alternative
  208 + <programlisting role="JAVA"><![CDATA[
208 209 public class MeuAuthorizer implements Authorizer {
209 210  
210 211 @Override
... ... @@ -220,19 +221,30 @@ public class MeuAuthorizer implements Authorizer {
220 221 }
221 222  
222 223 }]]></programlisting>
223   - <para>
  224 + <!-- <para>
224 225 Feito isso deve-se definir no arquivo <filename>demoiselle.properties</filename>, as classes criadas:
225 226 </para>
226 227 <programlisting>
227 228 frameworkdemoiselle.security.authenticator.class=projeto.MeuAuthenticator
228 229 frameworkdemoiselle.security.authorizer.class=projeto.MeuAuthorizer
229   - </programlisting>
  230 + </programlisting> -->
230 231 <para>
231   - À partir desse momento, a aplicação já possui uma implementação de segurança definida.
  232 + Pronto! Sua aplicação já possui uma implementação de segurança definida. Caso sua ela não implemente essas interfaces, no momento em que
  233 + forem chamadas, o framework lançará uma exceção informando que a aplicação precisa implementá-las.
232 234 </para>
  235 + <para>
  236 + Se você tem mais de uma implementação de <literal>Authenticator</literal> e/ou <literal>Authorizer</literal> (o que pode acontecer, por exemplo, quando
  237 + se necessite de uma implementação na aplicação principal, e outra para os testes), deverá definir no arquivo <filename>demoiselle.properties</filename>
  238 + qual classe será a padrão:
  239 + <programlisting>
  240 + frameworkdemoiselle.security.authenticator.class=projeto.MeuAuthenticatorPadrao
  241 + frameworkdemoiselle.security.authorizer.class=projeto.MeuAuthorizerPadrao
  242 + </programlisting>
  243 + </para>
233 244 </section>
234   - <caution> <para>O Demoiselle também oferece o componente <ulink url="http://demoiselle.sourceforge.net/docs/demoiselle-guide-components/1.2.0/html/authorization-master.html">Authorization</ulink>
235   - que facilita o uso de segurança com JAAS. Obviamente, não é possível utilizá-los ao mesmo tempo. Há arquétipos Maven que já trazem esse componente como dependência, por isso sempre confira o arquivo
236   - POM.XML e se for o caso retire esse dependência.</para> </caution>
  245 + <caution> <para>O Demoiselle também oferece o componente
  246 + <ulink url="http://demoiselle.sourceforge.net/docs/demoiselle-guide-components/1.2.0/html/authorization-master.html">Authorization</ulink>
  247 + que facilita o uso de segurança com JAAS. Obviamente, não é possível utilizá-los ao mesmo tempo. Há arquétipos Maven que já trazem esse componente
  248 + como dependência, por isso sempre confira o arquivo POM.XML e se for o caso retire essa dependência.</para> </caution>
237 249  
238 250 </chapter>
239 251 \ No newline at end of file
... ...
documentation/reference/pt-BR/transacao.xml
  Diff comments   View file @024b377
... ... @@ -6,8 +6,8 @@
6 6 <title>Transação</title>
7 7  
8 8 <para>
9   - Esta funcionalidade utiliza os recursos do CDI para interceptar e delegar o tratamento adequado das transações
10   - para quem é de direito. Em outras palavras, não reinventamos a roda. Criamos algumas estratégias de delegação e
  9 + Esta funcionalidade utiliza os recursos do CDI para interceptar e delegar adequadamente o tratamento das transações.
  10 + Em outras palavras, não reinventamos a roda. Criamos algumas estratégias de delegação e
11 11 controle de transação com base no que está sendo mais utilizado no mercado, algumas mais simples de configurar,
12 12 outras mais completas para utilizar.
13 13 </para>
... ... @@ -74,7 +74,7 @@ public class Simples {
74 74 <title>E se acontecer uma Exception?</title>
75 75 <para>
76 76 Caso ocorra uma exceção na execução de um método transacional o mecanismo fará rollback na transação
77   - automaticamente. É possível mudar este comportamento utilizando exceções de aplicação.
  77 + automaticamente. É possível mudar este comportamento utilizando exceções de aplicação (para maiores detalhes ver <link linkend="excecao">Exceção</link>).
78 78 </para>
79 79 <programlisting role="JAVA"><![CDATA[@ApplicationException(rollback = false)
80 80 public class AbacaxiException {
... ... @@ -103,7 +103,12 @@ public class AbacaxiException {
103 103 </para>
104 104 <para>
105 105 Você pode optar também por não utilizar controle de transação. Neste caso, basta não utilizar a anotação <literal>@Transactional</literal>. Contudo,
106   - caso você a utilize e não defina qual estratégia deseja utilizar, o framework lançará uma exceção lhe avisando sobre isto!
  106 + caso você a utilize, você poderá escolher entre as estratégias JPA, JTA (ambas fornecidas pelo <literal>Framework</literal>) e uma estratégia que você
  107 + pode criar ou importar para seu projeto.
  108 + </para>
  109 + <para>
  110 + A forma de selecionar cada uma dessas estratégias é descrita abaixo. Caso tente utilizar o controle de transação e não selecione nenhuma estratégia,
  111 + o framework lançará uma exceção lhe avisando sobre isto!
107 112 </para>
108 113 </section>
109 114  
... ... @@ -118,11 +123,16 @@ public class AbacaxiException {
118 123 </para>
119 124 <para>
120 125 A transação JPA é simples de configurar e não exige nenhum recurso externo à sua aplicação.
121   - Basta definir no arquivo <filename>demoiselle.properties</filename> a seguinte configuração:
  126 + Para utilizá-la basta que seu projeto adicione no arquivo POM.XML dependência à extensão <literal>demoiselle-jpa</literal>, que o
  127 + Demoiselle fará a seleção por essa estratégia de forma automática.
  128 +<!-- Basta definir no arquivo <filename>demoiselle.properties</filename> a seguinte configuração: -->
122 129 </para>
  130 +
  131 + <!--
123 132 <programlisting>
124 133 frameworkdemoiselle.transaction.class=br.gov.frameworkdemoiselle.transaction.JPATransaction
125 134 </programlisting>
  135 + -->
126 136 <tip><para> Caso não esteja utilizando o arquétipo JSF-JPA fornecidos pelo Demoiselle, confira se a dependência para a
127 137 extensão está indicada corretamente no arquivo POM.XML.</para>
128 138 <programlisting role="XML"><![CDATA[<dependency>
... ... @@ -135,17 +145,24 @@ public class AbacaxiException {
135 145 <section>
136 146 <title>Estratégia JTA</title>
137 147 <para>
138   - Esta estratégia, também está disponível através de uma extensão: <literal>demoiselle-jta</literal> e é
  148 + Esta estratégia, também está disponível através de uma extensão (<literal>demoiselle-jta</literal>), e é
139 149 responsável por delegar o controle de transação para um container JEE. Com a <literal>JTATransaction</literal>
140 150 é possível incluir várias unidades de persistência de uma mesma aplicação no mesmo contexto transacional.
141 151 Isso mesmo, o famoso <emphasis>Two-Phase Commit (2PC)</emphasis>.
142 152 </para>
143 153 <para>
144 154 A estratégia JTA não serve apenas para persistência em banco de dados, serve também para integrar com
145   - tecnologias que façam acesso ao contexto JTA, como é o caso do EJB. Para ativar esta estratégia defina no
  155 + tecnologias que façam acesso ao contexto JTA, como é o caso do EJB. Para ativar esta estratégia basta
  156 + que seu projeto adicione no arquivo POM.XML a dependência à extensão <literal>demoiselle-jta</literal>, que o
  157 + Demoiselle fará a seleção por essa estratégia de forma automática, pois essa estratégia tem prioridade em relação
  158 + a estratégia JPA.
  159 + </para>
  160 + <!--
  161 + defina no
146 162 arquivo <filename>demoiselle.properties</filename> a seguinte configuração:
147 163 </para>
148 164 <programlisting>frameworkdemoiselle.transaction.class=br.gov.frameworkdemoiselle.transaction.JTATransaction</programlisting>
  165 + -->
149 166 <para>
150 167 Feito isto, o controle transacional será delegado para a transação acessível via JNDI com o nome
151 168 <literal>UserTransaction</literal>. A estratégia acessa o objeto da seguinte maneira:
... ... @@ -156,14 +173,15 @@ public class AbacaxiException {
156 173 É preciso também informar no arquivo <filename>persistence.xml</filename> o endereço da conexão
157 174 JTA gerenciada. Veja um exemplo utilizando o servidor de aplicações JBoss-AS6 e com o provider Hibernate (embutido no JBoss-AS) como implementação JPA:
158 175 </para>
159   - <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
160   -<persistence version="2.0"
  176 + <programlisting role="XML"><![CDATA[
  177 + <?xml version="1.0" encoding="UTF-8"?>
  178 + <persistence version="2.0"
161 179 xmlns="http://java.sun.com/xml/ns/persistence"
162 180 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
163 181 xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
164 182 http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
165 183  
166   - <persistence-unit name="bookmark-ds" transaction-type="JTA">
  184 + <persistence-unit name="bookmark-ds" transaction-type="JTA">
167 185 <jta-data-source>java:jboss/datasources/ExampleDS</jta-data-source>
168 186 <properties>
169 187 <property name="hibernate.show_sql" value="true" />
... ... @@ -172,12 +190,13 @@ public class AbacaxiException {
172 190 <property name="hibernate.transaction.jta.platform"
173 191 value="org.hibernate.service.jta.platform.internal.JBossAppServerJtaPlatform" />
174 192 </properties>
175   - </persistence-unit>
176   -</persistence>]]></programlisting>
  193 + </persistence-unit>
  194 + </persistence>]]></programlisting>
177 195  
178 196 <tip><para> Caso não esteja utilizando o arquétipo JSF-JPA fornecidos pelo Demoiselle, confira se a dependência para a
179 197 extensão está indicada corretamente, no arquivo POM.XML.</para>
180   - <programlisting role="XML"><![CDATA[<dependency>
  198 + <programlisting role="XML"><![CDATA[
  199 + <dependency>
181 200 <groupId>br.gov.frameworkdemoiselle</groupId>
182 201 <artifactId>demoiselle-jta</artifactId>
183 202 <scope>compile</scope>
... ... @@ -190,19 +209,19 @@ public class AbacaxiException {
190 209 <para>
191 210 Caso nenhuma das estratégias oferecidas sirva para você, crie a sua. Basta escrever uma
192 211 classe não-final que implemente a interface <literal>Transaction</literal> do pacote
193   - <literal>br.gov.frameworkdemoiselle.transaction</literal>. Anote a classe com
  212 + <literal>br.gov.frameworkdemoiselle.transaction</literal>. <!--Anote a classe com
194 213 <literal>@SessionScoped</literal> e <literal>@Alternative</literal> para que o CDI saiba
195   - que se trata de uma estratégia. É preciso que sua classe não possua construtores explícitos ou
  214 + que se trata de uma estratégia.-->É preciso que sua classe não possua construtores explícitos ou
196 215 que possua um construtor público sem parâmetros. É possível fazer injeções nesta classe.
197 216 </para>
  217 + <!-- import javax.enterprise.context.SessionScoped;
  218 + import javax.enterprise.inject.Alternative;
  219 + @Alternative
  220 + @SessionScoped -->
198 221 <programlisting role="JAVA"><![CDATA[package projeto;
199 222  
200   -import javax.enterprise.context.SessionScoped;
201   -import javax.enterprise.inject.Alternative;
202 223 import br.gov.frameworkdemoiselle.transaction.Transaction;
203 224  
204   -@Alternative
205   -@SessionScoped
206 225 public class MegaTransaction implements Transaction {
207 226  
208 227 public void begin() { }
... ... @@ -224,10 +243,34 @@ public class MegaTransaction implements Transaction {
224 243 }
225 244 ]]></programlisting>
226 245 <para>
  246 + Pronto, é só isso! Agora, os métodos anotados com <literal>@Transactional</literal> irão utilizar a estratégia criada em seu projeto de forma automática,
  247 + mesmo que as extensões <literal>demoiselle-jpa</literal> e <literal>demoiselle-jta</literal> sejam adicionadas ao projeto, pois o framework da prioridade
  248 + máxima à estratégia criada no projeto.
  249 + </para>
  250 +<!-- <para>
227 251 Basta agora definir no arquivo <filename>demoiselle.properties</filename> a sua estratégia:
228 252 </para>
229 253 <programlisting>
230 254 frameworkdemoiselle.transaction.class=projeto.MegaTransaction
  255 + </programlisting>-->
  256 + </section>
  257 +
  258 + <section>
  259 + <title>Escolhendo estratégias manualmente</title>
  260 + <para>
  261 + Existem alguns casos nos quais você vai ter que definir a estratégia manualmente. Um exemplo é quando seu projeto implementa mais do que uma estratégia
  262 + de transação. Outra situação pode acontecer em casos de teste, nos quais você queira utilizar estratégia diferente. Nesses casos você deve definir no
  263 + arquivo <filename>demoiselle.properties</filename> qual estratégia será utilizada. Veja alguns exemplos de definição de estratégias própria,
  264 + <literal>JTATransaction</literal> e <literal>JPATransaction</literal> (importante notar que apenas uma estratégia pode estar ativa por vez):
  265 + </para>
  266 + <programlisting>
  267 + frameworkdemoiselle.transaction.class=projeto.MyTransaction
  268 + </programlisting>
  269 + <programlisting>
  270 + frameworkdemoiselle.transaction.class=br.gov.frameworkdemoiselle.transaction.JTATransaction
  271 + </programlisting>
  272 + <programlisting>
  273 + frameworkdemoiselle.transaction.class=br.gov.frameworkdemoiselle.transaction.JPATransaction
231 274 </programlisting>
232 275 </section>
233 276  
... ...