Software Público Brasileiro

<?xml version='1.0' encoding="utf-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" []>
<chapter id="persistencia">

	<title>Persistência</title>
	
	<para>
		Persist&ecirc;ncia &eacute; um dos aspectos mais importantes de sistemas corporativos - grande parte desses sistemas devem
		em algum ponto persistir informa&ccedil;&otilde;es em um sistema gerenciador de banco de dados. A tecnologia Java conta
		hoje com algumas formas de facilitar o acesso a SGBD's - algumas s&atilde;o especifica&ccedil;&otilde;es Java como o JDBC
		e o JPA, outras s&atilde;o tecnologias desenvolvidas por terceiros como o Hibernate.
	</para>
	
	<para>
		O Framework Demoiselle facilita o acesso e a configura&ccedil;&atilde;o a algumas dessas tecnologias fornecendo produtores
		padr&atilde;o para seus pontos de entrada e centralizando a configura&ccedil;&atilde;o. Tudo que o desenvolvedor deve fazer
		&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>
		
		<title>JDBC</title>
		
		<para>
			O Framework Demoiselle fornece um produtor padrão para conexões JDBC puras. Esse produtor possui suporte
			ao acesso direto utilizando uma URL e ao acesso via <code>DataSource</code>, acessando a conexão através
			de um nome <code>JNDI</code> configurado em um servidor de aplicação.
		</para>
		
		<para>
			A persistência de dados usando JDBC está disponível na extensão <literal>demoiselle-jdbc</literal>. Para ter acesso
			a essa extensão em um projeto Maven declare sua dependência no arquivo <literal>pom.xml</literal> de seu projeto.
		</para>	
	 	
	 	<tip>
	 		<para>
	 			Para acrescentar a dependência à extensão <literal>demoiselle-jdbc</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-jdbc</artifactId>
	<scope>compile</scope>
</dependency>]]></programlisting>
		</tip>
		
		<section>
			<title>Configuração</title>
			
			<para>
				A conexão será criada pela fábrica do Demoiselle de acordo com as configurações no arquivo de propriedade (<emphasis>demoiselle.properties</emphasis>).
				Para configurar uma conexão diretamente através de uma URL utilize as propriedades abaixo:
			</para>
			
			<informaltable width="100%">
				<tgroup cols="2">
					<colspec align="left"/>
					<colspec align="left"/>
					
					<thead>
						<row valign="top">
							<entry><emphasis role="bold">Propriedade</emphasis></entry>
							<entry><emphasis role="bold">Descrição</emphasis></entry>
						</row>
					</thead>
					
					<tbody>
						<row valign="top">
							<entry>frameworkdemoiselle.&#8203;persistence.&#8203;driver.&#8203;class</entry>
							<entry>
								<para>
									Implementação da interface <code>java.sql.Driver</code> que dá acesso
									ao SGBD utilizado pela aplicação.
								</para>
							</entry>
						</row>
						
						<row valign="top">
							<entry>frameworkdemoiselle.&#8203;persistence.&#8203;url</entry>
							<entry>
								<para>
									URL de conexão no formato <code>jdbc:vendor:database-properties</code>.
								</para>
							</entry>
						</row>
						
						<row valign="top">
							<entry>frameworkdemoiselle.&#8203;persistence.&#8203;username</entry>
							<entry>
								<para>
									Login de acesso ao SGBD.
								</para>
							</entry>
						</row>
						
						<row valign="top">
							<entry>frameworkdemoiselle.&#8203;persistence.&#8203;password</entry>
							<entry>
								<para>
									Senha de acesso ao SGBD.
								</para>
							</entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>
			
			<para>
				Também é possível configurar o acesso indicando um nome <code>JNDI</code> que esteja
				configurado no servidor de aplicação. 
			</para>
			
			<informaltable width="100%">
				<tgroup cols="2">
					<colspec align="left"/>
					<colspec align="left"/>
					
					<thead>
						<row valign="top">
							<entry><emphasis role="bold">Propriedade</emphasis></entry>
							<entry><emphasis role="bold">Descrição</emphasis></entry>
						</row>
					</thead>
					
					<tbody>
						<row valign="top">
							<entry>frameworkdemoiselle.&#8203;persistence.&#8203;jndi.&#8203;name</entry>
							<entry>
								<para>
									Nome <code>JNDI</code> criado no servidor de aplicação para dar acesso
									à conexão ao banco de dados. 
								</para>
							</entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>
			
			<para>
				É possível configurar mais de uma conexão JDBC. Para isso acrescente nas propriedades nomes
				separados para cada conexão como no exemplo abaixo:
			</para>
			
			<example>
				<title>Criando múltiplas conexões</title>
				
				<programlisting>frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn1</emphasis>.&#8203;driver.&#8203;class=MinhaClasse
frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn1</emphasis>.&#8203;url=MinhaURL
frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn1</emphasis>.&#8203;username=MeuLogin
frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn1</emphasis>.&#8203;password=MinhaSenha

frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn2</emphasis>.&#8203;driver.&#8203;class=MinhaClasse
frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn2</emphasis>.&#8203;url=MinhaURL
frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn2</emphasis>.&#8203;username=MeuLogin
frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn2</emphasis>.&#8203;password=MinhaSenha</programlisting>
			
				<programlisting>frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn1</emphasis>.&#8203;jndi.&#8203;name=MeuJndiName1
frameworkdemoiselle.&#8203;persistence.&#8203;<emphasis role="bold">conn2</emphasis>.&#8203;jndi.&#8203;name=MeuJndiName2</programlisting>
			</example>
			
			<para>
				Caso várias conexões sejam configuradas, é possível determinal a conexão padrão - aquela
				que será utilizada quando o desenvolvedor não especificar qual deseja utilizar.
			</para>
			
			<informaltable width="100%">
				<tgroup cols="2">
					<colspec align="left"/>
					<colspec align="left"/>
					
					<thead>
						<row valign="top">
							<entry><emphasis role="bold">Propriedade</emphasis></entry>
							<entry><emphasis role="bold">Descrição</emphasis></entry>
						</row>
					</thead>
					
					<tbody>
						<row valign="top">
							<entry>frameworkdemoiselle.&#8203;persistence.&#8203;default.&#8203;datasource.&#8203;name</entry>
							<entry>
								<para>
									Caso múltiplas conexões sejam criadas, define a conexão padrão
									quando uma <code>Connection</code> é injetada no código sem utilizar
									a anotação <code>@Name</code>. 
								</para>
							</entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>
		</section>

		<section>
			<title>Utilização</title>
			
			<para>
				Para utilizar uma conexão JDBC em seu código, basta injetá-la. O Demoiselle se encarregará de produzir
				o tipo adequado de conexão.
			</para>
			
			<programlisting role="JAVA"><![CDATA[public class ClasseDAO {
 	
 	@Inject
 	private Connection conn1;
 	
 	public void metodoPersistir(){
 		conn1.prepareStatement("INSERT INTO TAB_1 VALUES (1,'JDBC')").execute();
 	}
 	
}]]></programlisting>

			<para>
				Caso multiplas conexões tenham sido definidas, é possível utilizar a anotação <code>@Name</code> para injetar
				uma conexão específica.
			</para>
			
			<programlisting role="JAVA"><![CDATA[public class ClasseDAO {
 	
 	@Inject
 	@Name("conn1")
 	private Connection conn1;
 	
 	@Inject
 	@Name("conn2")
 	private Connection conn2;
 	
 	public void metodoPersistirEmConn1(){
 		conn1.prepareStatement("INSERT INTO TAB_1 VALUES (1,'JDBC')").execute();
 	}
 	
 	public void metodoPersistirEmConn2(){
 		conn2.prepareStatement("INSERT INTO TAB_2 VALUES (1,'JDBC')").execute();
 	}
 	
}]]></programlisting>

			<caution>
				<para>
					Caso a propriedade <code>frameworkdemoiselle.persistence.default.datasource.name</code> seja utilizada para
					especificar uma conexão padrão, a anotação <code>@Name</code> só é necessária para utilizar conexões diferentes
					da padrão. Caso essa propriedade não seja utilizada e existam múltiplas conexões configuradas, torna-se obrigatório
					o uso da anotação <code>@Name</code> em todos os pontos de injeção. 
				</para>
			</caution>

		</section>

	</section>

</chapter>