Download as
Browse Code »

Commit 409070cf02315175261ac789e1c121bd185cc8dc

Authored by Dancovich
1 parent db1cd17c
Exists in master

Reorganizada documentação de JDBC

Showing 1 changed file with 231 additions and 53 deletions   Show diff stats
documentation/reference/pt-BR/persistencia.xml
  Diff comments   View file @409070c
... ... @@ -4,72 +4,250 @@
4 4 <chapter id="persistencia">
5 5  
6 6 <title>Persistência</title>
  7 +
  8 + <para>
  9 + Persist&ecirc;ncia &eacute; um dos aspectos mais importantes de sistemas corporativos - grande parte desses sistemas devem
  10 + em algum ponto persistir informa&ccedil;&otilde;es em um sistema gerenciador de banco de dados. A tecnologia Java conta
  11 + hoje com algumas formas de facilitar o acesso a SGBD's - algumas s&atilde;o especifica&ccedil;&otilde;es Java como o JDBC
  12 + e o JPA, outras s&atilde;o tecnologias desenvolvidas por terceiros como o Hibernate.
  13 + </para>
  14 +
  15 + <para>
  16 + O Framework Demoiselle facilita o acesso e a configura&ccedil;&atilde;o a algumas dessas tecnologias fornecendo produtores
  17 + padr&atilde;o para seus pontos de entrada e centralizando a configura&ccedil;&atilde;o. Tudo que o desenvolvedor deve fazer
  18 + &eacute; apenas injetar o recurso adequado em seu c&oacute;digo e o Framework Demoiselle se encarregar&aacute; de
  19 + produzi-lo e configur&aacute;-lo.
  20 + </para>
7 21  
8 22 <section>
  23 +
9 24 <title>JDBC</title>
  25 +
  26 + <para>
  27 + O Framework Demoiselle fornece um produtor padrão para conexões JDBC puras. Esse produtor possui suporte
  28 + ao acesso direto utilizando uma URL e ao acesso via <code>DataSource</code>, acessando a conexão através
  29 + de um nome <code>JNDI</code> configurado em um servidor de aplicação.
  30 + </para>
  31 +
10 32 <para>
11   - A persistência de dados usando JDBC, está disponível na extensão <literal>demoiselle-jdbc</literal>,
12   - que provê uma fábrica de <literal>Connection</literal>. Para utilizá-la basta incluir a dependência para extensão JDBC
13   - no arquivo pom.xml.
  33 + A persistência de dados usando JDBC está disponível na extensão <literal>demoiselle-jdbc</literal>. Para ter acesso
  34 + a essa extensão em um projeto Maven declare sua dependência no arquivo <literal>pom.xml</literal> de seu projeto.
14 35 </para>
15   - <programlisting role="XML"><![CDATA[<dependency>
  36 +
  37 + <tip>
  38 + <para>
  39 + Para acrescentar a dependência à extensão <literal>demoiselle-jdbc</literal>, adicione esse código
  40 + em seu arquivo <literal>pom.xml</literal>, na seção <literal>dependencies</literal>.
  41 + </para>
  42 +
  43 + <programlisting role="XML"><![CDATA[<dependency>
16 44 <groupId>br.gov.frameworkdemoiselle</groupId>
17 45 <artifactId>demoiselle-jdbc</artifactId>
18 46 <scope>compile</scope>
19   -</dependency>]]>
20   - </programlisting>
  47 +</dependency>]]></programlisting>
  48 + </tip>
  49 +
  50 + <section>
  51 + <title>Configuração</title>
21 52  
22   - <para>
23   - Para obter uma instância de uma conexão, basta injetá-la na classe:
24   - </para>
25   - <programlisting role="JAVA"><![CDATA[@Inject
26   -private Connection conn;]]></programlisting>
27   - <para>
28   - A conexão será criada pela fábrica do Demoiselle de acordo com as configurações no arquivo de propriedade (<emphasis>demoiselle.properties</emphasis>).
29   - </para>
30   - <para>
31   - Você pode configurar as propriedades da conexão:
32   - </para>
33   - <programlisting>frameworkdemoiselle.persistence.driver.class=MeuDriver
34   -frameworkdemoiselle.persistence.url=MinhaUrl
35   -frameworkdemoiselle.persistence.username=MeuUsername
36   -frameworkdemoiselle.persistence.password=MeuPassword</programlisting>
37   - <para>
38   - ou indicar o JNDI do datasource:
39   - </para>
40   - <programlisting>frameworkdemoiselle.persistence.jndi.name=MeuJndiName</programlisting>
  53 + <para>
  54 + A conexão será criada pela fábrica do Demoiselle de acordo com as configurações no arquivo de propriedade (<emphasis>demoiselle.properties</emphasis>).
  55 + Para configurar uma conexão diretamente através de uma URL utilize as propriedades abaixo:
  56 + </para>
  57 +
  58 + <informaltable width="100%">
  59 + <tgroup cols="2">
  60 + <colspec align="left"/>
  61 + <colspec align="left"/>
  62 +
  63 + <thead>
  64 + <row valign="top">
  65 + <entry><emphasis role="bold">Propriedade</emphasis></entry>
  66 + <entry><emphasis role="bold">Descrição</emphasis></entry>
  67 + </row>
  68 + </thead>
  69 +
  70 + <tbody>
  71 + <row valign="top">
  72 + <entry>frameworkdemoiselle.&#8203;persistence.&#8203;driver.&#8203;class</entry>
  73 + <entry>
  74 + <para>
  75 + Implementação da interface <code>java.sql.Driver</code> que dá acesso
  76 + ao SGBD utilizado pela aplicação.
  77 + </para>
  78 + </entry>
  79 + </row>
  80 +
  81 + <row valign="top">
  82 + <entry>frameworkdemoiselle.&#8203;persistence.&#8203;url</entry>
  83 + <entry>
  84 + <para>
  85 + URL de conexão no formato <code>jdbc:vendor:database-properties</code>.
  86 + </para>
  87 + </entry>
  88 + </row>
  89 +
  90 + <row valign="top">
  91 + <entry>frameworkdemoiselle.&#8203;persistence.&#8203;username</entry>
  92 + <entry>
  93 + <para>
  94 + Login de acesso ao SGBD.
  95 + </para>
  96 + </entry>
  97 + </row>
  98 +
  99 + <row valign="top">
  100 + <entry>frameworkdemoiselle.&#8203;persistence.&#8203;password</entry>
  101 + <entry>
  102 + <para>
  103 + Senha de acesso ao SGBD.
  104 + </para>
  105 + </entry>
  106 + </row>
  107 + </tbody>
  108 + </tgroup>
  109 + </informaltable>
  110 +
  111 + <para>
  112 + Também é possível configurar o acesso indicando um nome <code>JNDI</code> que esteja
  113 + configurado no servidor de aplicação.
  114 + </para>
  115 +
  116 + <informaltable width="100%">
  117 + <tgroup cols="2">
  118 + <colspec align="left"/>
  119 + <colspec align="left"/>
  120 +
  121 + <thead>
  122 + <row valign="top">
  123 + <entry><emphasis role="bold">Propriedade</emphasis></entry>
  124 + <entry><emphasis role="bold">Descrição</emphasis></entry>
  125 + </row>
  126 + </thead>
  127 +
  128 + <tbody>
  129 + <row valign="top">
  130 + <entry>frameworkdemoiselle.&#8203;persistence.&#8203;jndi.&#8203;name</entry>
  131 + <entry>
  132 + <para>
  133 + Nome <code>JNDI</code> criado no servidor de aplicação para dar acesso
  134 + à conexão ao banco de dados.
  135 + </para>
  136 + </entry>
  137 + </row>
  138 + </tbody>
  139 + </tgroup>
  140 + </informaltable>
  141 +
  142 + <para>
  143 + É possível configurar mais de uma conexão JDBC. Para isso acrescente nas propriedades nomes
  144 + separados para cada conexão como no exemplo abaixo:
  145 + </para>
  146 +
  147 + <example>
  148 + <title>Criando múltiplas conexões</title>
  149 +
  150 + <programlisting>frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn1</emphasis>.&#8203;driver.&#8203;class=MinhaClasse
  151 +frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn1</emphasis>.&#8203;url=MinhaURL
  152 +frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn1</emphasis>.&#8203;username=MeuLogin
  153 +frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn1</emphasis>.&#8203;password=MinhaSenha
41 154  
42   - <para>
43   - Caso você necessite usar conexões com datasources diferentes, você pode usar a anotoção
44   - <literal>@Name</literal> passando como valor o nome da conexão definida no arquivo
45   - <literal>demoiselle.properties</literal>
46   - </para>
47   -
48   - <para>
49   - No <literal>demoiselle.properties</literal> basta adicionar um nome qualquer para identificar a conexão:
50   - </para>
51   - <programlisting>frameworkdemoiselle.persistence.conn1.jndi.name=MeuJndiName1
52   -frameworkdemoiselle.persistence.conn2.jndi.name=MeuJndiName2</programlisting>
53   -
54   - <para>
55   - Injetar o <literal>Connection</literal> usando <literal>@Name</literal> com o nome da conexão escolhida:
56   - </para>
57   -
58   - <programlisting role="JAVA"><![CDATA[@Inject
59   -@Name("conn1")
60   -private Connection conn1;
  155 +frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn2</emphasis>.&#8203;driver.&#8203;class=MinhaClasse
  156 +frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn2</emphasis>.&#8203;url=MinhaURL
  157 +frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn2</emphasis>.&#8203;username=MeuLogin
  158 +frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn2</emphasis>.&#8203;password=MinhaSenha</programlisting>
  159 +
  160 + <programlisting>frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn1</emphasis>.&#8203;jndi.&#8203;name=MeuJndiName1
  161 +frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn2</emphasis>.&#8203;jndi.&#8203;name=MeuJndiName2</programlisting>
  162 + </example>
  163 +
  164 + <para>
  165 + Caso várias conexões sejam configuradas, é possível determinal a conexão padrão - aquela
  166 + que será utilizada quando o desenvolvedor não especificar qual deseja utilizar.
  167 + </para>
  168 +
  169 + <informaltable width="100%">
  170 + <tgroup cols="2">
  171 + <colspec align="left"/>
  172 + <colspec align="left"/>
  173 +
  174 + <thead>
  175 + <row valign="top">
  176 + <entry><emphasis role="bold">Propriedade</emphasis></entry>
  177 + <entry><emphasis role="bold">Descrição</emphasis></entry>
  178 + </row>
  179 + </thead>
  180 +
  181 + <tbody>
  182 + <row valign="top">
  183 + <entry>frameworkdemoiselle.&#8203;persistence.&#8203;default.&#8203;datasource.&#8203;name</entry>
  184 + <entry>
  185 + <para>
  186 + Caso múltiplas conexões sejam criadas, define a conexão padrão
  187 + quando uma <code>Connection</code> é injetada no código sem utilizar
  188 + a anotação <code>@Name</code>.
  189 + </para>
  190 + </entry>
  191 + </row>
  192 + </tbody>
  193 + </tgroup>
  194 + </informaltable>
  195 + </section>
  196 +
  197 + <section>
  198 + <title>Utilização</title>
  199 +
  200 + <para>
  201 + Para utilizar uma conexão JDBC em seu código, basta injetá-la. O Demoiselle se encarregará de produzir
  202 + o tipo adequado de conexão.
  203 + </para>
  204 +
  205 + <programlisting role="JAVA"><![CDATA[public class ClasseDAO {
  206 +
  207 + @Inject
  208 + private Connection conn1;
  209 +
  210 + public void metodoPersistir(){
  211 + conn1.prepareStatement("INSERT INTO TAB_1 VALUES (1,'JDBC')").execute();
  212 + }
  213 +
  214 +}]]></programlisting>
61 215  
62   -@Inject
63   -@Name("conn2")
64   -private Connection conn2;
65   -]]></programlisting>
  216 + <para>
  217 + Caso multiplas conexões tenham sido definidas, é possível utilizar a anotação <code>@Name</code> para injetar
  218 + uma conexão específica.
  219 + </para>
  220 +
  221 + <programlisting role="JAVA"><![CDATA[public class ClasseDAO {
  222 +
  223 + @Inject
  224 + @Name("conn1")
  225 + private Connection conn1;
  226 +
  227 + @Inject
  228 + @Name("conn2")
  229 + private Connection conn2;
  230 +
  231 + public void metodoPersistirEmConn1(){
  232 + conn1.prepareStatement("INSERT INTO TAB_1 VALUES (1,'JDBC')").execute();
  233 + }
  234 +
  235 + public void metodoPersistirEmConn2(){
  236 + conn2.prepareStatement("INSERT INTO TAB_2 VALUES (1,'JDBC')").execute();
  237 + }
  238 +
  239 +}]]></programlisting>
66 240  
  241 + <caution>
  242 + <para>
  243 + Caso a propriedade <code>frameworkdemoiselle.persistence.default.datasource.name</code> seja utilizada para
  244 + especificar uma conexão padrão, a anotação <code>@Name</code> só é necessária para utilizar conexões diferentes
  245 + da padrão. Caso essa propriedade não seja utilizada e existam múltiplas conexões configuradas, torna-se obrigatório
  246 + o uso da anotação <code>@Name</code> em todos os pontos de injeção.
  247 + </para>
  248 + </caution>
67 249  
68   - <para>
69   - Caso possua mais de uma configuração de datasource você pode definir uma configuração padrão
70   - para sua aplicação.
71   - </para>
72   - <programlisting>frameworkdemoiselle.persistence.default.datasource.name=conn1</programlisting>
  250 + </section>
73 251  
74 252 </section>
75 253  
... ...