[hibernate-commits] Hibernate SVN: r14080 - in core/trunk/documentation/manual/pt-BR/src/main: docbook and 2 other directories.

Author: steve.ebersole(a)jboss.com Date: 2007-10-09 15:32:35 -0400 (Tue, 09 Oct 2007) New Revision: 14080 Added: core/trunk/documentation/manual/pt-BR/src/main/docbook/Hibernate_Reference.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/architecture.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/association_mapping.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/basic_mapping.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/batch.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/best_practices.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/collection_mapping.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/component_mapping.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/configuration.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/events.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_mappings.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_parentchild.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_weblog.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/filters.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/inheritance_mapping.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/performance.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/persistent_classes.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/preface.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_criteria.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_hql.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_sql.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/session_api.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/toolset_guide.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/transactions.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/tutorial.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/tutorial1.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/content/xml.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/images/ core/trunk/documentation/manual/pt-BR/src/main/docbook/images/AuthorWork.png core/trunk/documentation/manual/pt-BR/src/main/docbook/images/AuthorWork.zargo core/trunk/documentation/manual/pt-BR/src/main/docbook/images/CustomerOrderProduct.png core/trunk/documentation/manual/pt-BR/src/main/docbook/images/CustomerOrderProduct.zargo core/trunk/documentation/manual/pt-BR/src/main/docbook/images/EmployerEmployee.png core/trunk/documentation/manual/pt-BR/src/main/docbook/images/EmployerEmployee.zargo core/trunk/documentation/manual/pt-BR/src/main/docbook/images/full_cream.png core/trunk/documentation/manual/pt-BR/src/main/docbook/images/full_cream.svg core/trunk/documentation/manual/pt-BR/src/main/docbook/images/hibernate_logo_a.png core/trunk/documentation/manual/pt-BR/src/main/docbook/images/lite.png core/trunk/documentation/manual/pt-BR/src/main/docbook/images/lite.svg core/trunk/documentation/manual/pt-BR/src/main/docbook/images/overview.png core/trunk/documentation/manual/pt-BR/src/main/docbook/images/overview.svg core/trunk/documentation/manual/pt-BR/src/main/docbook/legal_notice.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/legal_notice2.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/translators.xml Removed: core/trunk/documentation/manual/pt-BR/src/main/docbook/master.xml core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/ core/trunk/documentation/manual/pt-BR/src/main/resources/ Log: new docbook layout (prep for translations migration to PO) Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/Hibernate_Reference.xml (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/Hibernate_Reference.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/Hibernate_Reference.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/Hibernate_Reference.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,73 @@ +<?xml version='1.0' encoding="iso-8859-1"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + <!ENTITY versionNumber "3.3.0.alpha1"> + <!ENTITY copyrightYear "2004"> + <!ENTITY copyrightHolder "Red Hat Middleware, LLC."> +]> + +<book> + + <bookinfo> + <title>HIBERNATE - Relational Persistence for Idiomatic Java</title> + <subtitle>Documenta��o da Refer�ncia do Hibernate</subtitle> + <releaseinfo>&versionNumber;</releaseinfo> + <productnumber>&versionNumber;</productnumber> + <issuenum>1</issuenum> + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="images/hibernate_logo_a.png" align="center" /> + </imageobject> + <imageobject role="html"> + <imagedata fileref="images/hibernate_logo_a.png" depth="3cm" /> + </imageobject> + </mediaobject> + <copyright> + <year>&copyrightYear;</year> + <holder>&copyrightHolder;</holder> + </copyright> + <xi:include href="translators.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="legal_notice2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </bookinfo> + + <toc/> + + <xi:include href="content/preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/tutorial.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/persistent_classes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/basic_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/collection_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/association_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/component_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/inheritance_mapping.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/session_api.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/transactions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/events.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/batch.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/query_hql.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/query_criteria.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/query_sql.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/filters.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/xml.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/performance.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/toolset_guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/example_parentchild.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/example_weblog.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="content/example_mappings.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/best_practices.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</book> + Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/architecture.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/architecture.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/architecture.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/architecture.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,374 @@ +<!-- + ~ Copyright (c) 2007, Red Hat Middleware, LLC. All rights reserved. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, v. 2.1. This program is distributed in the + ~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied + ~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + ~ Lesser General Public License for more details. You should have received a + ~ copy of the GNU Lesser General Public License, v.2.1 along with this + ~ distribution; if not, write to the Free Software Foundation, Inc., + ~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + ~ + ~ Red Hat Author(s): Steve Ebersole + --> +<chapter id="architecture"> + + <title>Arquitetura</title> + + <sect1 id="architecture-overview" revision="1"> + <title>Vis&#x00E3;o Geral</title> + + <para> + Uma vis&#x00E3;o bem ampla da arquitetura do Hibernate: + </para> + + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="../images/overview.svg" format="SVG" align="center"/> + </imageobject> + <imageobject role="html"> + <imagedata fileref="../images/overview.png" format="PNG" align="center"/> + </imageobject> + </mediaobject> + + <para> + Esse diagrama mostra o Hibernate usando o banco de dados e a configuração + de dados para prover persistência de serviços (e persistência de objetos) + para o aplicativo. + </para> + + <para> + Nós gostaríamos de mostrar uma visão mais detalhada da arquitetura em execução. + Infelizmente, o Hibernate é muito flexível e suporta v&#x00E1;rias aproximações. + Nós iremos mostrar os dois extremos. Na arquitetura mais simples o aplicativo + fornece suas próprias conexões JDBC e gerencia suas transações. Esta abordagem + usa o mínimo de subconjuntos das APIs do Hibernate: + </para> + + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="../images/lite.svg" format="SVG" align="center"/> + </imageobject> + <imageobject role="html"> + <imagedata fileref="../images/lite.png" format="PNG" align="center"/> + </imageobject> + </mediaobject> + + <para> + A arquitetura "completa" abstrai a aplicação de ter de lidar diretamente + com JDBC/JTA e APIs e deixa o Hibernate tomar conta dos detalhes. + </para> + + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="../images/full_cream.svg" format="SVG" align="center"/> + </imageobject> + <imageobject role="html"> + <imagedata fileref="../images/full_cream.png" format="PNG" align="center"/> + </imageobject> + </mediaobject> + + <para> + Algumas definições dos objetos do diagrama: + + <variablelist spacing="compact"> + <varlistentry> + <term>SessionFactory (<literal>org.hibernate.SessionFactory</literal>)</term> + <listitem> + <para> + Um cache threadsafe (imutáveis) composto de identidades compiladas para um + único banco de dados. Uma fabrica para <literal>Session</literal> e um cliente + de <literal>ConnectionProvider</literal>. Pode conter um cachê opcional de + dados (segundo nível) reutilizáveis entre transações, no nível de processo- ou cluster. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Session (<literal>org.hibernate.Session</literal>)</term> + <listitem> + <para> + Objeto single-threaded, de vida curta, representando uma conversação entre + o aplicativo e o armazenamento persistente. Cria uma camada sobre uma conexão JDBC. + É uma fabrica de <literal>Transaction</literal>. Possui um cachê obrigatório + (primeiro nível) de objetos persistentes, usado para navegação no gráficos + de objetos e pesquisa de objetos pelo identificador. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Objetos persistentes e coleções</term> + <listitem> + <para> + Objetos, de vida curta, single threaded contendo estado persistente e função + de negócios. Esses podem ser JavaBeans/POJOs, onde única coisa especial sobre + eles é que são associados a (exatamente uma) <literal>Session</literal>. + Quando a <literal>Session</literal> é fechada, eles são separados e liberados + para serem usados dentro de qualquer camada da aplicacao (Ex. diretamente como + data transfer objects de e para a camada de apresentação) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Objetos e coleções desatachados e transientes</term> + <listitem> + <para> + Instâncias de classes persistentes que ainda não estão associadas a uma + <literal>Session</literal>. Eles podem ter sido instanciados pela aplicação + e não persistido (ainda) ou eles foram instanciados por uma <literal>Session</literal> + que foi encerrada. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Transaction (<literal>org.hibernate.Transaction</literal>)</term> + <listitem> + <para> + (Opcional) Objeto de vida curta, single threaded, usado pela aplicação para + especificar unidades atômicas de trabalho. Abstrai o aplicativo de lidar + diretamente com transações JDBC, JTA ou CORBA. Uma <literal>Session</literal> pode, + em alguns casos, iniciar várias <literal>Transaction</literal>s. Entretanto, + a demarcação da transação, mesmo utilizando API ou Transaction subjacentes, + nunca é opcional! + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ConnectionProvider (<literal>org.hibernate.connection.ConnectionProvider</literal>)</term> + <listitem> + <para> + (Opcional) Uma fábrica de (e combinações de) conexões JDBC. Abstrai a aplicação + de lidar diretamente com <literal>Datasource</literal> ou <literal>DriverManager</literal>. + Não exposto para a aplicação, mas pode ser implementado ou estendido pelo programador. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>TransactionFactory (<literal>org.hibernate.TransactionFactory</literal>)</term> + <listitem> + <para> + (Opcional) Uma fábrica para instâncias de <literal>Transaction</literal>. Não exposta + a aplicação, mas pode ser extendida/implementada pelo programador. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Extension Interfaces</emphasis></term> + <listitem> + <para> + O Hibernate oferece várias opções de interfaces estendidas que você pode implementar + para customizar sua camada persistente. Veja a documentação da API para maiores detalhes. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + Dada uma arquitetura simples, o aplicativo passa pelas APIs + <literal>Transaction</literal>/<literal>TransactionFactory</literal> e/ou + <literal>ConnectionProvider</literal> para se comunicar diretamente com a transação JTA ou JDBC. + </para> + </sect1> + + <sect1 id="architecture-states" revision="1"> + <title>Estados de instância</title> + <para> + Uma instância de classes persistentes pode estar em um dos três diferentes estados, + que são definidos respeitando um <emphasis>contexto persistente</emphasis>. + O objeto <literal>Session</literal> do Hibernate é o contexto persistente: + </para> + + <variablelist spacing="compact"> + <varlistentry> + <term>transiente</term> + <listitem> + <para> + A instância não é, e nunca foi associada com nenhum + contexto persistente. Não possui uma identidade persistente + (valor de chave primária). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>persistente</term> + <listitem> + <para> + A instância está atualmente associada a um contexto persistente. + Possui uma identidade persistente (valor de chave primária) e, + talvez, correspondente a um registro no banco de dados. Para um + contexto persistente em particular, o Hibernate + <emphasis>guarantees</emphasis> que a identidade persistente + é equivalente a identidade Java (na localização em memória do + objeto). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>desatachado</term> + <listitem> + <para> + A instância foi associada com um contexto persistente, + porém este contexto foi fechado, ou a instância + foi serializada por outro processo. Possui uma identidade + persistente, e, talvez, correspondenta a um registro no + banco de dados. Para instâncias desatachadas, o Hibernate + não garante o relacionamento entre identidade persistente + e identidade Java. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1 id="architecture-jmx" revision="1"> + <title>Integração JMX</title> + + <para> + JMX é padrão J2EE para manipulação de componentes Java. O Hibernate pode ser manipulado + por um serviço JMX padrão. Nós fornecemos uma implementação do MBean na distribuição, + <literal>org.hibernate.jmx.HibernateService</literal>. + </para> + + <para> + Para um exemplo de como instalar o Hibernate como um serviço JMX em um servidor de + aplicativo JBoss, por favor, consulte o manual do usuário do JBoss. No JBoss As, você + poderá ver os benefícios de de se fazer o deploy usando JMX: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>Session Management:</emphasis> O ciclo de vida de uma <literal>Session</literal> do + Hibernate pode ser automaticamente conectada a um escopo de transação JTA. Isso significa + que você não precisará mais abrir e fechar manualmente uma <literal>Session</literal>, isso + se torna trabalho para um interceptor EJB do JBoss . Você também não precisa se preocupar, + nunca mais, com demarcação de transação em seu código (a não ser que você prefira escrever + uma camada persistente portável, para isso, use a API opcional do Hibernate + <literal>Transaction</literal>). Você deve chamar <literal>HibernateContext</literal> + para acessar uma <literal>Session</literal>. + </para> + </listitem> + <listitem> + <para> + <emphasis>HAR deployment:</emphasis>: Normalmente você faz o deploy de um serviço JMX do + Hibernate usando um serviço descritor de deploy do JBoss (em um EAR e/ou arquivo SAR), + que suporta todas as configurações usuais de uma <literal>SessionFactory</literal> do + Hibernate. Entretanto, você ainda precisa nomear todos os seus arquivos de mapeamento + no descritor de deploração. Se você decidir usar o deploy opcional HAR, o JBoss irá + automaticamente detectar todos os seus arquivos de mapeamento no seu arquivo HAR. + </para> + </listitem> + </itemizedlist> + + <para> + Consulte o manual do usuário do JBoss AS, para obter maiores informações sobre essas opções. + </para> + + <para> + Another feature available as a JMX service are runtime Hibernate statistics. See + <xref linkend="configuration-optional-statistics"/>. + Outra opção disponível como um serviço JMX são as estatísticas de execução do Hibernate. + Veja a <xref linkend="configuration-optional-statistics"/>. + </para> + </sect1> + + <sect1 id="architecture-jca" revision="1"> + <title>Suporte JCA</title> + <para> + Hibernate may also be configured as a JCA connector. Please see the website for more + details. Please note that Hibernate JCA support is still considered experimental. + O Hibernate pode também ser configurado como um conector JCA. Por favor, visite o + website para maiores detalhes. Entretanto, note que o suporte JCA do Hibernate + ainda é considerado experimental. + </para> + </sect1> + + <sect1 id="architecture-current-session" revision="2"> + <title>Sessões contextuais</title> + <para> + Muitas aplicações que usam o Hibernate necessita de algum tipo de sessão "contextual", + onde uma sessão dada é na verdade um escopo de um contexto. Entretanto, através de aplicações + a definição sobre um contexto é geralmente diferente; e contextos diferentes definem escopos + diferentes. Aplicações usando versões anteriores ao Hibernate 3.0 tendem a utilizar tanto + sessões contextuais baseadas em <literal>ThreadLocal</literal>, classes utilitárias como + <literal>HibernateUtil</literal>, ou utilizar frameworks de terceiros(como Spring ou Pico) + que provê sessões contextuais baseadas em proxy. + + </para> + <para> + A partir da versão 3.0.1, o Hibernate adicionou o método <literal>SessionFactory.getCurrentSession()</literal>. + Inicialmente, este assume o uso de transações <literal>JTA</literal>, onde a transação + <literal>JTA</literal> define tanto o escopo quanto o contexto de uma sessão atual. + O time do Hibernate mantém este recurso, desenvolvendo as diversas implementações do + <literal>JTA TransactionManager</literal>, a maioria (se não todos) aplicativos deveria + utilizar o gerenciador de transações <literal>JTA</literal> sendo ou não instalados dentro + de um container <literal>J2EE</literal>. Baseado neste recurso, você deveria sempre utilizar sessões + contextuais baseadas em <literal>JTA</literal>. + </para> + <para> + Entretanto, na versão 3.1, o processo por trás do método <literal>SessionFactory.getCurrentSession()</literal> + é agora plugavel. Com isso, uma nova interface (<literal>org.hibernate.context.CurrentSessionContext</literal>) + e um novo parâmetro de configuração (<literal>hibernate.current_session_context_class</literal>) + foram adicionados para possibilitar a compatibilidade do contexto e do escopo na definição de sessões correntes. + </para> + <para> + De uma olhada em Javadocs sobre a interface <literal>org.hibernate.context.CurrentSessionContext</literal> + para uma discussão detalhada. Ela define um método único, <literal>currentSession()</literal>, + com o qual a implementação é responsável por rastrear a sessão contextual corrente. + Por fora do "encapsulamento", o Hibernate possui duas implementações dessa interface. + </para> + + <itemizedlist> + <listitem> + <para> + <literal>org.hibernate.context.JTASessionContext</literal> - As sessões correntes + são rastreadas e recebem um escopo por uma transação <literal>JTA</literal>. + O processamento aqui é exatamente igual ao antigo processo JTA. Consulte em + Javadocs para maiores detalhes. + </para> + </listitem> + <listitem> + <para> + <literal>org.hibernate.context.ThreadLocalSessionContext</literal> - As sessões + correntes são rastreadas por uma thread de execução. Novamente, consulte em + Javadocs para maiores detalhes. + </para> + </listitem> + <listitem> + <para> + <literal>org.hibernate.context.ManagedSessionContext</literal> - current + sessions are tracked by thread of execution. However, you are responsible to + bind and unbind a <literal>Session</literal> instance with static methods + on this class, it does never open, flush, or close a <literal>Session</literal>. + </para> + </listitem> + </itemizedlist> + + <para> + As duas primeiras implementações usam o modelo de programação "uma sessão – uma transação + do banco de dados", também conhecida e usado como <emphasis>sessão por requisição</emphasis>. + O começo e o fim de uma sessão Hibernate é definida pela duração da transação do banco de dados. + Se você usa demarcação programática de transação (por exemplo. em J2SE puro ou com JTA + /UserTransaction/BMT), você é recomendado a usar a API Hibernate <literal>Transaction</literal> + para esconder a base do sistema de transação do seu código. Se você executa em um container EJB + que suporta CMT, os limites das transações são definidas declarativamente e você não necessita + de qualquer transação ou operação de demarcação de sessão no seu código. Consulte o <xref linkend="transactions"/> + para mais informações exemplos de código. + </para> + + <para> + O parâmetro de configuração <literal>hibernate.current_session_context_class</literal> + define que a implementação <literal>org.hibernate.context.CurrentSessionContext</literal> + deve ser usada. Note que para compatibilidade anterior, se este parâmetro de configuração + não é determinado mas um <literal>org.hibernate.transaction.TransactionManagerLookup</literal> + é configurado, Hibernate usará o <literal>org.hibernate.context.JTASessionContext</literal>. + Tipicamente, o valor deste parâmetro nomearia apenas a classe de implementação para usar; + para as duas implementações out-of-the-box, entretanto, há três pequenos nomes correspondentes, + "jta", "thread", and "managed". + </para> + + </sect1> + +</chapter> Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/association_mapping.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/association_mapping.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/association_mapping.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/association_mapping.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,635 @@ +<chapter id="associations"> + + <title>Mapeamento de Associações</title> + + <sect1 id="assoc-intro" revision="1"> + <title>Introdução</title> + + <para> + Mapeamentos de associações são freqüentemente a coisa mais difícil de se + acertar. Nesta seção nós passaremos pêlos casos canônicos um pôr um, + começando com mapeamentos unidirecionais e considerando os casos + bidirecionais. Nos vamos usar <literal>Person</literal> e + <literal>Address</literal> em todos os exemplos. + </para> + + <para> + Nós classificaremos as associações pelo seu mapeamento ou a falta do + mesmo, sua intervenção na tabela associativa, e pela sua multiplicidade. + </para> + + <para> + O uso de chaves estrangeiras não obrigatórias não é considerada uma boa + prática na modelagem de dados tradicional, assim todos nossos exemplos + usam chaves estrangeiras obrigatórias. Esta não é uma exigência do + Hibernate, e todas as mapeamentos funcionarão se você remover as + constraints de obrigatoriedade. + </para> + + </sect1> + + <sect1 id="assoc-unidirectional" revision="1"> + <title>Associações Unidirecionais</title> + + <sect2 id="assoc-unidirectional-m21"> + <title>muitos para um</title> + + <para> + Uma <emphasis>associação unidirecional muitos-para-um</emphasis> é o + tipo mais comum de associação unidirecional. + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <many-to-one name="address" + column="addressId" + not-null="true"/> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key, addressId bigint not null ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </sect2> + + <sect2 id="assoc-unidirectional-121"> + <title>um para um</title> + + <para> + Uma <emphasis>associação unidirecional um-para-um em uma chave estrangeira + </emphasis> é quase idêntica. A única diferença é a constraint unique + na coluna. + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <many-to-one name="address" + column="addressId" + unique="true" + not-null="true"/> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key, addressId bigint not null unique ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + <para> + Uma <emphasis>associação unidirecional um-para-um na chave primaria</emphasis> + geralmente usa um gerador de id special. ( Note que nós invertemos a + direção da associação nesse exemplo). + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> +</class> + +<class name="Address"> + <id name="id" column="personId"> + <generator class="foreign"> + <param name="property">person</param> + </generator> + </id> + <one-to-one name="person" constrained="true"/> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table Address ( personId bigint not null primary key ) + ]]></programlisting> + + </sect2> + + <sect2 id="assoc-unidirectional-12m"> + <title>um para muitos</title> + + <para> + Uma <emphasis>associação unidirecional um-para-muitos em uma chave + estrangeira</emphasis> é um caso muito incomum, e realmente não é recomendada. + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <set name="addresses"> + <key column="personId" + not-null="true"/> + <one-to-many class="Address"/> + </set> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table Address ( addressId bigint not null primary key, personId bigint not null ) + ]]></programlisting> + + <para> + Nós achamos que é melhor usar uma tabela associativa para este tipo de + associação. + </para> + + </sect2> + + </sect1> + + <sect1 id="assoc-unidirectional-join" revision="1"> + <title>Associações Unidirecionais com tabelas associativas</title> + + <sect2 id="assoc-unidirectional-join-12m"> + <title>um para muitos</title> + + <para> + Uma <emphasis>associação um-para-muitos unidirecional usando uma tabela + associativa</emphasis> e o mais comum. Note que se especificarmos + <literal>unique="true"</literal>, estaremos modificando a cardinalidade + de muitos-para-muitos para um-para-muitos. + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <set name="addresses" table="PersonAddress"> + <key column="personId"/> + <many-to-many column="addressId" + unique="true" + class="Address"/> + </set> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table PersonAddress ( personId not null, addressId bigint not null primary key ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </sect2> + + <sect2 id="assoc-unidirectional-join-m21"> + <title>muitos para um</title> + + <para> + Uma <emphasis>associação unidirecional muitos-para-um em uma tabela + associativa</emphasis> é bastante comum quando a associação for opcional. + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <join table="PersonAddress" + optional="true"> + <key column="personId" unique="true"/> + <many-to-one name="address" + column="addressId" + not-null="true"/> + </join> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table PersonAddress ( personId bigint not null primary key, addressId bigint not null ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </sect2> + + <sect2 id="assoc-unidirectional-join-121"> + <title>um para um</title> + + <para> + Uma <emphasis>associação unidirecional um-para-um em uma tabela + associativa</emphasis> é extremamente incomum, mas possível. + + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <join table="PersonAddress" + optional="true"> + <key column="personId" + unique="true"/> + <many-to-one name="address" + column="addressId" + not-null="true" + unique="true"/> + </join> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table PersonAddress ( personId bigint not null primary key, addressId bigint not null unique ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </sect2> + + <sect2 id="assoc-unidirectional-join-m2m"> + <title>muitos para muitos</title> + + <para> + Finalmente, nós temos a <emphasis>associação unidirecional muitos-para- + muitos</emphasis>. + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <set name="addresses" table="PersonAddress"> + <key column="personId"/> + <many-to-many column="addressId" + class="Address"/> + </set> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table PersonAddress ( personId bigint not null, addressId bigint not null, primary key (personId, addressId) ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </sect2> + + </sect1> + + <sect1 id="assoc-bidirectional" revision="1"> + <title>Associações Bidirecionais</title> + + <sect2 id="assoc-bidirectional-m21" revision="2"> + <title>um para muitos / muitos para um</title> + + <para> + Uma <emphasis>associação bidirecional muitos-para-um</emphasis> é o + tipo mais comum de associação. (Esse é o relacionamento padrão + pai / filho. ) + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <many-to-one name="address" + column="addressId" + not-null="true"/> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> + <set name="people" inverse="true"> + <key column="addressId"/> + <one-to-many class="Person"/> + </set> +</class>]]></programlisting> + + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key, addressId bigint not null ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + <para> + Se você usar uma <literal>List</literal> ( ou outra coleção indexada ), você + precisa especificar a coluna <literal>chave</literal> estrangeira como not null, + e deixar o Hibernate administrar a associação do lado da coleção para que + seja mantido o índice de cada elemento da coleção (fazendo com que o outro + lado seja virtualmente inverso setando <literal>update="false"</literal> + e <literal>insert="false"</literal>): + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id"/> + ... + <many-to-one name="address" + column="addressId" + not-null="true" + insert="false" + update="false"/> +</class> + +<class name="Address"> + <id name="id"/> + ... + <list name="people"> + <key column="addressId" not-null="true"/> + <list-index column="peopleIdx"/> + <one-to-many class="Person"/> + </list> +</class>]]></programlisting> + + <para> + É importante que você defina <literal>not-null="true"</literal> no elemento + <literal>&lt;key&gt;</literal> no mapeamento na coleção se a coluna de chave + estrangeira for <literal>NOT NULL</literal>. Não declare como + <literal>not-null="true"</literal> apenas um elemento aninhado + <literal>&lt;column&gt;</literal>, mas sim o elemento + <literal>&lt;key&gt;</literal>. + </para> + + </sect2> + + <sect2 id="assoc-bidirectional-121"> + <title>um para um</title> + + <para> + Uma <emphasis>associação bidirecional um para um em uma chave estrangeira</emphasis> + é bastante comum. + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <many-to-one name="address" + column="addressId" + unique="true" + not-null="true"/> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> + <one-to-one name="person" + property-ref="address"/> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key, addressId bigint not null unique ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + <para> + Uma <emphasis>associação bidirecional um para um em uma chave primária</emphasis> + usa um gerador de id especial. + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <one-to-one name="address"/> +</class> + +<class name="Address"> + <id name="id" column="personId"> + <generator class="foreign"> + <param name="property">person</param> + </generator> + </id> + <one-to-one name="person" + constrained="true"/> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table Address ( personId bigint not null primary key ) + ]]></programlisting> + + </sect2> + + </sect1> + + <sect1 id="assoc-bidirectional-join" revision="1"> + <title>Associações Bidirecionais com tabelas associativas</title> + + <sect2 id="assoc-bidirectional-join-12m"> + <title>um para muitos / muitos para um</title> + + <para> + Uma <emphasis>associação bidirecional um para muitos em uma tabela + associativa</emphasis>. Veja que <literal>inverse="true"</literal> pode ser + colocado em qualquer ponta associação, na coleção, ou no join. + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <set name="addresses" + table="PersonAddress"> + <key column="personId"/> + <many-to-many column="addressId" + unique="true" + class="Address"/> + </set> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> + <join table="PersonAddress" + inverse="true" + optional="true"> + <key column="addressId"/> + <many-to-one name="person" + column="personId" + not-null="true"/> + </join> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table PersonAddress ( personId bigint not null, addressId bigint not null primary key ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </sect2> + + <sect2 id="assoc-bidirectional-join-121"> + <title>one to one</title> + + <para> + Uma <emphasis>associação bidirecional um-para-um em uma tabela de + associação</emphasis> é algo bastante incomum, mas possivel. + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <join table="PersonAddress" + optional="true"> + <key column="personId" + unique="true"/> + <many-to-one name="address" + column="addressId" + not-null="true" + unique="true"/> + </join> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> + <join table="PersonAddress" + optional="true" + inverse="true"> + <key column="addressId" + unique="true"/> + <many-to-one name="person" + column="personId" + not-null="true" + unique="true"/> + </join> +</class>]]></programlisting> + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table PersonAddress ( personId bigint not null primary key, addressId bigint not null unique ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </sect2> + + <sect2 id="assoc-bidirectional-join-m2m" revision="1"> + <title>muitos para muitos</title> + + <para> + Finally, we have a <emphasis>bidirectional many-to-many association</emphasis>. + Finalmente, nós temos uma associação bidirecional de muitos para muitos. + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id" column="personId"> + <generator class="native"/> + </id> + <set name="addresses" table="PersonAddress"> + <key column="personId"/> + <many-to-many column="addressId" + class="Address"/> + </set> +</class> + +<class name="Address"> + <id name="id" column="addressId"> + <generator class="native"/> + </id> + <set name="people" inverse="true" table="PersonAddress"> + <key column="addressId"/> + <many-to-many column="personId" + class="Person"/> + </set> +</class>]]></programlisting> + + <programlisting><![CDATA[ +create table Person ( personId bigint not null primary key ) +create table PersonAddress ( personId bigint not null, addressId bigint not null, primary key (personId, addressId) ) +create table Address ( addressId bigint not null primary key ) + ]]></programlisting> + + </sect2> + + </sect1> + + <sect1 id="assoc-complex"> + <title>Mapeamento de associações mais complexas</title> + + <para> + More complex association joins are <emphasis>extremely</emphasis> rare. + Hibernate makes it possible to handle more complex situations using + SQL fragments embedded in the mapping document. For example, if a table + with historical account information data defines + <literal>accountNumber</literal>, <literal>effectiveEndDate</literal> + and <literal>effectiveStartDate</literal>columns, mapped as follows: +Joins de associações mais complexas são extremamente raros. O Hibernate torna possível tratar mapeamentos mais complexos usando fragmentos de SQL embutidos no documento de mapeamento. Por exemplo, se uma tabela com informações de dados históricos de uma conta define a coluna accountNumber, effectiveEndDate e effectiveStartDate, mapeadas assim como segue: + </para> + + <programlisting><![CDATA[<properties name="currentAccountKey"> + <property name="accountNumber" type="string" not-null="true"/> + <property name="currentAccount" type="boolean"> + <formula>case when effectiveEndDate is null then 1 else 0 end</formula> + </property> +</properties> +<property name="effectiveEndDate" type="date"/> +<property name="effectiveStateDate" type="date" not-null="true"/>]]></programlisting> + + <para> + Then we can map an association to the <emphasis>current</emphasis> instance + (the one with null <literal>effectiveEndDate</literal>) using: +Então nós podemos mapear uma associação para a instância corrente (aquela com a effectiveEndDate igual a null) usando: + </para> + + <programlisting><![CDATA[<many-to-one name="currentAccountInfo" + property-ref="currentAccountKey" + class="AccountInfo"> + <column name="accountNumber"/> + <formula>'1'</formula> +</many-to-one>]]></programlisting> + + <para> + In a more complex example, imagine that the association between + <literal>Employee</literal> and <literal>Organization</literal> is maintained + in an <literal>Employment</literal> table full of historical employment data. + Then an association to the employee's <emphasis>most recent</emphasis> employer + (the one with the most recent <literal>startDate</literal>) might be mapped this way: +Em um exemplo mais complexo, imagine que a associação entre Employee e Organization é mantida em uma tabela Employment cheia de dados históricos do trabalho. Então a associação do funcionário mais recentemente empregado (aquele com a mais recente startDate) deve ser mapeado desta maneira: + </para> + + <programlisting><![CDATA[<join> + <key column="employeeId"/> + <subselect> + select employeeId, orgId + from Employments + group by orgId + having startDate = max(startDate) + </subselect> + <many-to-one name="mostRecentEmployer" + class="Organization" + column="orgId"/> +</join>]]></programlisting> + + <para> + You can get quite creative with this functionality, but it is usually more practical + to handle these kinds of cases using HQL or a criteria query. +Você pode ser criativo com esta funcionalidade, mas geralmente é mais prático tratar estes tipos de casos, usando uma pesquisa HQL ou uma pesquisa por criteria. + </para> + + </sect1> + + +</chapter> + Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/basic_mapping.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/basic_mapping.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/basic_mapping.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/basic_mapping.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,3491 @@ +<chapter id="mapping"> + <title>Mapeamento O/R Bassico</title> + + <sect1 id="mapping-declaration" revision="1"> + <title>Declaração de mapeamento</title> + + <para> + Object/relational mappings are usually defined in an XML document. The mapping + document is designed to be readable and hand-editable. The mapping language is + Java-centric, meaning that mappings are constructed around persistent class + declarations, not table declarations. + </para> + + <para> + Note that, even though many Hibernate users choose to write the XML by hand, + a number of tools exist to generate the mapping document, including XDoclet, + Middlegen and AndroMDA. + </para> + + <para> + Lets kick off with an example mapping: + </para> + + <programlisting id="mapping-declaration-ex1" revision="1"><![CDATA[<?xml version="1.0"?> +<!DOCTYPE hibernate-mapping PUBLIC + "-//Hibernate/Hibernate Mapping DTD 3.0//EN" + "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"> + +<hibernate-mapping package="eg"> + + <class name="Cat" + table="cats" + discriminator-value="C"> + + <id name="id"> + <generator class="native"/> + </id> + + <discriminator column="subclass" + type="character"/> + + <property name="weight"/> + + <property name="birthdate" + type="date" + not-null="true" + update="false"/> + + <property name="color" + type="eg.types.ColorUserType" + not-null="true" + update="false"/> + + <property name="sex" + not-null="true" + update="false"/> + + <property name="litterId" + column="litterId" + update="false"/> + + <many-to-one name="mother" + column="mother_id" + update="false"/> + + <set name="kittens" + inverse="true" + order-by="litter_id"> + <key column="mother_id"/> + <one-to-many class="Cat"/> + </set> + + <subclass name="DomesticCat" + discriminator-value="D"> + + <property name="name" + type="string"/> + + </subclass> + + </class> + + <class name="Dog"> + <!-- mapping for Dog could go here --> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Discutir agora o conteúdo deste documento de mapeamento. Iremos apenas descrever + os elementos do documento e atributos que são utilizados pelo Hibernate em tempo + de execução. O documento de mapeamento também contém alguns atributos adicionais + e opcionais além de elementos que afetam os esquemas de banco de dados exportados + pela ferramenta de exportação de esquemas. (Por exemplo, o atributo + <literal>not-null</literal>). + </para> + + + + <sect2 id="mapping-declaration-doctype" revision="3"> + <title>Doctype</title> + + <para> + Todos os mapeamentos de XML devem declarar o doctype exibido. O DTD atual pode + ser encontrado na URL abaixo, no diretório <literal>hibernate-x.x.x/src/org/ + hibernate </literal> ou no <literal>hibernate3.jar</literal>. O Hibernate sempre + irá procurar pelo DTD inicialmente no seu classpath. Se você tentar localizar + o DTD usando uma conexão de internet, compare a declaração do seu DTD com o + conteúdo do seu classpath + </para> + + <sect3 id="mapping-declaration-entity-resolution"> + <title>EntityResolver</title> + <para> + As mentioned previously, Hibernate will first attempt to resolve DTDs in its classpath. The + manner in which it does this is by registering a custom <literal>org.xml.sax.EntityResolver</literal> + implementation with the SAXReader it uses to read in the xml files. This custom + <literal>EntityResolver</literal> recognizes two different systemId namespaces. + </para> + <itemizedlist> + <listitem> + <para> + a <literal>hibernate namespace</literal> is recognized whenever the + resolver encounteres a systemId starting with + <literal>http://hibernate.sourceforge.net/</literal>; the resolver + attempts to resolve these entities via the classlaoder which loaded + the Hibernate classes. + </para> + </listitem> + <listitem> + <para> + a <literal>user namespace</literal> is recognized whenever the + resolver encounteres a systemId using a <literal>classpath://</literal> + URL protocol; the resolver will attempt to resolve these entities + via (1) the current thread context classloader and (2) the + classloader which loaded the Hibernate classes. + </para> + </listitem> + </itemizedlist> + <para> + An example of utilizing user namespacing: + </para> + <programlisting><![CDATA[<?xml version="1.0"?> +<!DOCTYPE hibernate-mapping PUBLIC + "-//Hibernate/Hibernate Mapping DTD 3.0//EN" + "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd" [ + <!ENTITY types SYSTEM "classpath://your/domain/types.xml"> +]> + +<hibernate-mapping package="your.domain"> + <class name="MyEntity"> + <id name="id" type="my-custom-id-type"> + ... + </id> + <class> + &types; +</hibernate-mapping>]]></programlisting> + <para> + Where <literal>types.xml</literal> is a resource in the <literal>your.domain</literal> + package and contains a custom <xref linkend="mapping-types-custom">typedef</xref>. + </para> + </sect3> + </sect2> + + <sect2 id="mapping-declaration-mapping" revision="3"> + <title>hibernate-mapping</title> + + <para> + Este elemento tem diversos atributos opcionais. Os atributos + <literal>schema</literal> e <literal>catalog</literal> especificam que tabelas + referenciadas neste mapeamento pertencem ao esquema e/ou ao catalogo nomeado. + Se especificados, os nomes das tabelas irão ser qualificados no schema ou catalog dado. + Se não, os nomes das tabelas não serão qualificados. O atributo <literal>default-cascade + </literal> especifica qual estilo de cascata será assumido pelas propriedades e + coleções que não especificarm um atributo <literal>cascade</literal>. O atributo + <literal>auto-import</literal> nos deixa utilizar nomes de classes não qualificados + na linguagem de consulta, por default. + </para> + + <programlistingco> + <areaspec> + <area id="hm1" coords="2 55"/> + <area id="hm2" coords="3 55"/> + <area id="hm3" coords="4 55"/> + <area id="hm4" coords="5 55"/> + <area id="hm5" coords="6 55"/> + <area id="hm6" coords="7 55"/> + <area id="hm7" coords="8 55"/> + </areaspec> + <programlisting><![CDATA[<hibernate-mapping + schema="schemaName" + catalog="catalogName" + default-cascade="cascade_style" + default-access="field|property|ClassName" + default-lazy="true|false" + auto-import="true|false" + package="package.name" + />]]></programlisting> + <calloutlist> + <callout arearefs="hm1"> + <para> + <literal>schema</literal> (opcional): O nome do esquema do banco de dados. + </para> + </callout> + <callout arearefs="hm2"> + <para> + <literal>catalog</literal> (opcional): O nome do catálogo do banco de dados. + </para> + </callout> + <callout arearefs="hm3"> + <para> + <literal>default-cascade</literal> (opcional – default é <literal>nenhum + </literal>): Um estilo cascata default. + </para> + </callout> + <callout arearefs="hm4"> + <para> + <literal>default-access</literal> (opcional – default é <literal>property</literal>): + A estratégia que o Hibernate deve utilizar para acessar todas as propridades. Pode + ser uma implementação própria de <literal>PropertyAccessor</literal>. + </para> + </callout> + <callout arearefs="hm5"> + <para> + <literal>default-lazy</literal> (opcional - default é <literal>true</literal>): + O valor default para atributos <literal>lazy</literal> da classe e dos + mapeamentos de coleções. + </para> + </callout> + <callout arearefs="hm6"> + <para> + <literal>auto-import</literal> ((opcional - default é <literal>true</literal>): + Especifica se nós podemos usar nomes de classess não qualificados + (das classes deste mapeamento) na linguagem de consulta. + </para> + </callout> + <callout arearefs="hm7"> + <para> + <literal>package</literal> (opcional): Especifica um prefixo da package para + assumir para nomes de classes não qualificadas no documento de mapeamento. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Se voce tem duas classes persistentes com o mesmo nome (não qualificadas), você deve + setar <literal>auto-import="false"</literal>. O Hibernate irá gerar uma exceção se + você tentar setar duas classes para o mesmo nome "importado". + </para> + + <para> + Observe que o elemento <literal>hibernate-mapping</literal> permite a você + aninhar diversos mapeamentos de <literal>&lt;class&gt;</literal> persistentes, + como mostrado abaixo. Entretanto, é uma boa prática (e esperado por algumas + ferramentas)o mapeamento de apenas uma classe persistente simples (ou uma + hierarquia de classes simples) em um arquivo de mapeamento e nomea-la após + a superclasse persistente, por exemplo: <literal>Cat.hbm.xml</literal>, + <literal>Dog.hbm.xml</literal>, ou se estiver usando herança, + <literal>Animal.hbm.xml</literal>. + </para> + + </sect2> + + <sect2 id="mapping-declaration-class" revision="3"> + <title>class</title> + + <para> + Você pode declarar uma classe persistente utilizando o elemento + <literal>class</literal>: + </para> + + <programlistingco> + <areaspec> + <area id="class1" coords="2 55"/> + <area id="class2" coords="3 55" /> + <area id="class3" coords="4 55"/> + <area id="class4" coords="5 55" /> + <area id="class5" coords="6 55"/> + <area id="class6" coords="7 55" /> + <area id="class7" coords="8 55"/> + <area id="class8" coords="9 55" /> + <area id="class9" coords="10 55" /> + <area id="class10" coords="11 55"/> + <area id="class11" coords="12 55"/> + <area id="class12" coords="13 55"/> + <area id="class13" coords="14 55"/> + <area id="class14" coords="15 55"/> + <area id="class15" coords="16 55"/> + <area id="class16" coords="17 55"/> + <area id="class17" coords="18 55"/> + <area id="class18" coords="19 55"/> + <area id="class19" coords="20 55"/> + <area id="class20" coords="21 55"/> + <area id="class21" coords="22 55"/> + </areaspec> + <programlisting><![CDATA[<class + name="ClassName" + table="tableName" + discriminator-value="discriminator_value" + mutable="true|false" + schema="owner" + catalog="catalog" + proxy="ProxyInterface" + dynamic-update="true|false" + dynamic-insert="true|false" + select-before-update="true|false" + polymorphism="implicit|explicit" + where="arbitrary sql where condition" + persister="PersisterClass" + batch-size="N" + optimistic-lock="none|version|dirty|all" + lazy="true|false" + entity-name="EntityName" + check="arbitrary sql check condition" + rowid="rowid" + subselect="SQL expression" + abstract="true|false" + node="element-name" +/>]]></programlisting> + <calloutlist> + <callout arearefs="class1"> + <para> + <literal>name</literal> (opcional): O nome da classe Java inteiramente qualificado + da classe persistente (ou interface); Se o atributo é ausente, assume-se que o + mapeamento é para intidades não-POJO. + </para> + </callout> + <callout arearefs="class2"> + <para> + <literal>table</literal> (opcional – default para nomes de classes não + qualificadas) O nome da sua tabela do banco de dados. + </para> + </callout> + <callout arearefs="class3"> + <para> + <literal>discriminator-value</literal> (opcional – default para o nome da classe): + Um valor que distingue subclasses individuais, usadas para o comportamento polimorfico. + Valores aceitos incluem <literal>null</literal> e <literal>not null</literal> + </para> + </callout> + <callout arearefs="class4"> + <para> + <literal>mutable</literal> (opcional - valor default <literal>true</literal>): + Especifica que instancias da classe são (ou não) mutáveis + </para> + </callout> + <callout arearefs="class5"> + <para> + <literal>schema</literal> (opcional): Sobrepõe o nome do esquema especificado + pelo elemento root <literal>&lt;hibernate-mapping&gt;</literal>. + </para> + </callout> + <callout arearefs="class6"> + <para> + <literal>catalog</literal> (opcional): Sobrepõe o nome do catálogo especificado + pelo elemento root <literal>&lt;hibernate-mapping&gt;</literal>. + </para> + </callout> + <callout arearefs="class7"> + <para> + <literal>proxy</literal> (opcional): Especifica um interface para ser + utilizada pelos proxies de inicialização tardia. Você pode especificar o + nome da própria classe. + </para> + </callout> + <callout arearefs="class8"> + <para> + <literal>dynamic-update</literal> (opcional, valor default <literal>false</literal>): + Especifica que o SQL de <literal>UPDATE</literal> deve ser gerado em tempo de + execução e conter apenas aquelas colunas cujos valores foram alterados. + </para> + </callout> + <callout arearefs="class9"> + <para> + <literal>dynamic-insert</literal> (opcional, valor default <literal>false</literal>): + Especifica que o SQL de <literal>INSERT</literal> deve ser gerado em tempo de + execução e conter apenas aquelas colunas cujos valores não estão nulos. + </para> + </callout> + <callout arearefs="class10"> + <para> + <literal>select-before-update</literal> (opcional, valor default <literal>false</literal>): + Especifica que o Hibernate <emphasis>never</emphasis> deve executar um SQL de + <literal>UPDATE</literal> a não ser que com certeza um objeto está atualmente modificado. + Em certos casos (atualmente, apenas quando um objeto transiente foi associado com uma nova + sessão utilizando <literal>update()</literal>), isto significa que o Hibernate ira executar + uma instrução SQL de <literal>SELECT</literal> adicional para determinar se um + <literal>UPDATE</literal> é necessário nesse momento. + </para> + </callout> + <callout arearefs="class11"> + <para> + <literal>polymorphism</literal> (opcional, default para <literal>implicit</literal>): + Determina se deve ser utilizado a query polimorfica implicita ou explicitamente. + </para> + </callout> + <callout arearefs="class12"> + <para> + <literal>where</literal> (opicional) especifica um comando SQL <literal>WHERE</literal> + arbitrário para ser usado quando da recuperação de objetos desta classe. + </para> + </callout> + <callout arearefs="class13"> + <para> + <literal>persister</literal> (opcional): Espeicifca uma <literal>ClassPersister</literal> + customizada. + </para> + </callout> + <callout arearefs="class14"> + <para> + <literal>batch-size</literal> (opcional, valor default <literal>1</literal>) especifica um + "tamanho de lote" para a recuperação de instancias desta classe pelo identificador. + </para> + </callout> + <callout arearefs="class15"> + <para> + <literal>optimistic-lock</literal> (octional, valor default <literal>version</literal>): + Determina a estratégia de bloqueio. + </para> + </callout> + <callout arearefs="class16"> + <para> + <literal>lazy</literal> (opcional): A recuperação tardia pode ser completamente + desabilitada, setando <literal>lazy="false"</literal>. + </para> + </callout> + <callout arearefs="class17"> + <para> + <literal>entity-name</literal> (opcional, default para o nome da classe): O + Hibernate3 permite uma classe ser mapeada multiplas vezes, (potencialmente,para + diferentes tabelas), e permite mapeamentos de entidades que são representadas + por Maps ou XML no nível Java. Nestes casos, você deve especificar um nome + arbitrário explicitamente para a entidade. Veja <xref linkend="persistent-classes-dynamicmodels"/> + e <xref linkend="xml"/> para maiores informações. + </para> + </callout> + <callout arearefs="class18"> + <para> + <literal>check</literal> (opcional): Uma expressão SQL utilizada para gerar uma + constraint de <emphasis>verificação</emphasis> de múltiplas linhas para a geração + automática do esquema. + </para> + </callout> + <callout arearefs="class19"> + <para> + <literal>rowid</literal> (opcional): O Hibernate poder usar as assim chamadas + ROWIDs em bancos de dados que a suportam. Por exemplo, no Oracle, o Hibernate + pode utilizar a coluna extra rowid para atualizações mais rápidas se você + configurar esta opção para <literal>rowid</literal>. Um ROWID é uma implementação + que representa de maneira detalhada a localização física de uma determinada + tupla armazenado. + </para> + </callout> + <callout arearefs="class20"> + <para> + <literal>subselect</literal> (optional): Maps an immutable and read-only entity + to a database subselect. Useful if you want to have a view instead of a base table, + but don't. See below for more information. + <literal>subselect</literal> (opcional): Mapeia uma entidade imutavel e somente + de leitura para um subconjunto do banco de dados. Útil se você quiser ter uma + view em vez de uma tabela. Veja abaixo para mais informações. + </para> + </callout> + <callout arearefs="class21"> + <para> + <literal>abstract</literal> (opcional): Utilizada para marcar superclasses + abstratas em hierarquias <literal>&lt;union-subclass&gt;</literal>. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + É perfeitamente aceitável para uma classe persitente nomeada ser uma interface. Você deverá + então declarar as classes implementadas desta interface utilizando o elemento + <literal>&lt;subclass&gt;</literal>. Você pode persistir qualquer classe de aninhada + <emphasis>estatica</emphasis>. Você deverá especificar o nome da classe usando a forma + padrão, por exemplo: <literal>eg.Foo$Bar</literal>. + </para> + + <para> + Classes imutáveis, <literal>mutable="false"</literal>, não podem ser modificadas ou excluídas + pela aplicação. Isso permite ao Hibernate fazer alguns aperfeiçoamentos de performance. + </para> + + <para> + O atributo opcional <literal>proxy</literal> habilita a inicialização tardia das + instâncias persistentes da classe. O Hibernate irá retornar CGLIB proxies como implementado + na interface nomeada. O objeto persistente atual será carregado quando um método do proxy + for invocado. Veja "Inicializando coleções e proxies" abaixo. + </para> + + <para>Polimorfismo <emphasis>implícito</emphasis> significa que instâncias de uma classe + serão retornada por uma query que dá nome a qualquer superclasse ou interface implementada, + ou a classe e as instancias de qualquer subclasse da classe será retornada por umq query + que nomeia a classe por si. Polimorfismo <emphasis>explícito</emphasis> significa que + instancias da classe serão retornadas apenas por queries que explicitamente nomeiam a + classe e que queries que nomeiam as classes irão retornar apenas instancias de subclasses + mapeadas dentro da declaração <literal>&lt;class&gt;</literal> como uma + <literal>&lt;subclass&gt;</literal> ou <literal>&lt;joined-subclass&gt;</literal>. + Para a maioria dos casos, o valor default <literal>polymorphism="implicit"</literal>, + é apropriado. Polimorfismo explicito é útil quando duas classes distintas estão mapeadas + para a mesma tabela (isso permite um classe "peso leve" que contem um subconjunto + de colunas da tabela). + </para> + + <para> + O atributo <literal>persister</literal> deixa você customizar a estratégia de persistência + utilizada para a classe. Você pode, por exemplo, especificar sua prórpia subclasse do + <literal>org.hibernate.persister.EntityPersister</literal> ou você pode criar + uma implementação completamente nova da interface + <literal>org.hibernate.persister.ClassPersister</literal> que implementa a persistência + através de, por exemplo, chamadas a stored procedeures, serialização de arquivos flat ou + LDAP. Veja <literal>org.hibernate.test.CustomPersister</literal> para um exemplo + simples (de "persistencia" para uma <literal>Hashtable</literal>). + </para> + + <para> + Observe que as configurações <literal>dynamic-update</literal> e + <literal>dynamic-insert</literal> não sao herdadas pelas subclasses e assim podem tambem + ser especificadas em elementos <literal>&lt;subclass&gt;</literal> or + <literal>&lt;joined-subclass&gt;</literal>. Estas configurações podem incrementar a + performance em alguns casos, mas pode realmente diminuir a performance em outras. + Use-as de forma bastante criteriosa. + </para> + + <para> + O uso de <literal>select-before-update</literal> geralmente irá diminuir a performance. Ela é + muito útil para prevenir que uma trigger de atualização no banco de dados seja ativada + desnecessariamente, se você reconectar um nó de uma instancia desconectada em uma + <literal>Session</literal>. + </para> + + <para> + Se você ativar <literal>dynamic-update</literal>, você terá de escolher + a estratégia de bloqueio otimista: + </para> + <itemizedlist> + <listitem> + <para> + <literal>version</literal> verifica a versão e a hora das colunas + </para> + </listitem> + <listitem> + <para> + <literal>all</literal> cverifica todas as colunas + </para> + </listitem> + <listitem> + <para> + <literal>dirty</literal> verifica as colunas modificadas, permitindo + alguns updates concorrentes + </para> + </listitem> + <listitem> + <para> + <literal>none</literal> não utiliza o bloqueio otimista + </para> + </listitem> + </itemizedlist> + <para> + Nós <emphasis>recomendamos</emphasis> com muita enfase que você utilize a + versão e a hora das colunas para o bloqueio otimista com o Hibernate. + Esta é a melhor estratégia com respeito a performance e é a única estratégia + que trata corretamente as modificações efetuadas em instancias desconectadas + (por exemplo, quando <literal>Session.merge()</literal> é utilizado). + + </para> + + <para> + Não ha diferença entre uma view e uma tabela para o mapeamento do Hibernate, e como + esperado isto é transparente no nível do banco de dados (observe que alguns bancos de + dados não suportam views apropriadamente, especialmente com updates). Algumas vezes, + você quer utilizar uma view, ma snão pode cria-la no banco de dados (por exemplo, + com um esquema legado). Neste caso, você pode mapear uma entidade imutável e de + somente leitura, para uma dada expressão SQL, que representa um subselect: + </para> + + <programlisting><![CDATA[<class name="Summary"> + <subselect> + select item.name, max(bid.amount), count(*) + from item + join bid on bid.item_id = item.id + group by item.name + </subselect> + <synchronize table="item"/> + <synchronize table="bid"/> + <id name="name"/> + ... +</class>]]></programlisting> + + <para> + Declare as tabelas para sincronizar com esta entidade, garantindo que o auto-flush + ocorra corretamente, e que as queries para esta entidade derivada não retornem dados + desatualizados. O <literal>&lt;subselect&gt;</literal> está disponível tanto como um + atributo como um elemento mapeado nested. + </para> + + </sect2> + + <sect2 id="mapping-declaration-id" revision="4"> + <title>id</title> + + <para> + Classes mapeadas <emphasis>precisam</emphasis> declarar a coluna de chave primaria da + tabela do banco de dados. Muitas classes irão tambem ter uma propriedade ao estilo + Java-Beans declarando o identificador unico de uma instancia. O elemento + <literal>&lt;id&gt;</literal> define o mapeamento desta propriedade para a chave primária. + </para> + + <programlistingco> + <areaspec> + <area id="id1" coords="2 70"/> + <area id="id2" coords="3 70" /> + <area id="id3" coords="4 70"/> + <area id="id4" coords="5 70" /> + <area id="id5" coords="6 70" /> + </areaspec> + <programlisting><![CDATA[<id + name="propertyName" + type="typename" + column="column_name" + unsaved-value="null|any|none|undefined|id_value" + access="field|property|ClassName"> + node=&quot;element-name|@attribute-name|element/(a)attribute|.&quot; + + <generator class="generatorClass"/> +</id>]]></programlisting> + <calloutlist> + <callout arearefs="id1"> + <para> + <literal>name</literal> (opcional): O nome do identificador. + </para> + </callout> + <callout arearefs="id2"> + <para> + <literal>type</literal> (opcional): Um nome que indica o tipo no Hibernate. + </para> + </callout> + <callout arearefs="id3"> + <para> + <literal>column</literal> (opcional – default para o a propridade name): O + nome coluna chave primaria. + </para> + </callout> + <callout arearefs="id4"> + <para> + <literal>unsaved-value</literal> (opcional - default para um valor "sensível"): + Uma propriedade de identificação que indica que a instancia foi novamente + instanciada (unsaved), diferenciando de instancias desconectadas que foram + salvas ou carregadas em uma sessão anterior. + </para> + </callout> + <callout arearefs="id5"> + <para> + <literal>access</literal> (opcional - valor default <literal>property</literal>): A + estratégia que o Hiberante deve utilizar para acessar o valor da propriedade + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Se o atributo <literal>name</literal> não for declarado, assume-se que a classe não tem + a propriedade de identificação. + </para> + + <para> + O atributo <literal>unsaved-value</literal> não é mais necessário no Hibernate 3. + </para> + + <para> + Há declaração alternativa <literal>&lt;composite-id&gt;</literal> permite o acesso a + dados legados com chaves compostas. Nós desencorajamos fortemente o seu uso por + qualquer pessoa. + </para> + + <sect3 id="mapping-declaration-id-generator" revision="2"> + <title>Generator</title> + + <para> + O elemento filho opcional <literal>&lt;generator&gt;</literal> nomeia uma classe Java + usada para gerar identificadores unicos para instancias de uma classe persistente. + Se algum parâmetro é requerido para configurar ou inicializar a instancia geradora, + eles são passados utilizando o elemento <literal>&lt;param&gt;</literal>. + </para> + + <programlisting><![CDATA[<id name="id" type="long" column="cat_id"> + <generator class="org.hibernate.id.TableHiLoGenerator"> + <param name="table">uid_table</param> + <param name="column">next_hi_value_column</param> + </generator> +</id>]]></programlisting> + + <para> + Todos os generators implementam a interface <literal>org.hibernate.id.IdentifierGenerator</literal>. + Esta é uma interface bem simples; algumas aplicações podem prover sua própria implementação + esepecializada. Entretanto, o Hibernate disponibiliza um conjunto de implementações internamente. + Há nomes de atalhos para estes generators próprios: + <variablelist> + <varlistentry> + <term><literal>increment</literal></term> + <listitem> + <para> + gera identificadores dos tipos <literal>long</literal>, <literal>short</literal> ou + <literal>int</literal> que são unicos apenas quando nenhum outro processo está + inserindo dados na mesma tabela. <emphasis>Não utilize em ambientes + de cluster.</emphasis> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>identity</literal></term> + <listitem> + <para> + suporta colunas de identidade em DB2, MySQL, MS SQL Server, Sybase e + HypersonicSQL. O identificador retornado é do tipo <literal>long</literal>, + <literal>short</literal> ou <literal>int</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>sequence</literal></term> + <listitem> + <para> + utiliza uma sequence em DB2, PostgreSQL, Oracle, SAP DB, McKoi ou um + generator no Interbase. O identificador de retorno é do tipo <literal> + long</literal>, <literal>short</literal> ou <literal>int</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>hilo</literal></term> + <listitem> + <para id="mapping-declaration-id-hilodescription" revision="1"> + utiliza um algoritmo hi/lo para gerar de forma eficiente identificadores do tipo + <literal>long</literal>, <literal>short</literal> ou <literal>int</literal>, + a partir de uma tabela e coluna fornecida (por default + <literal>hibernate_unique_key</literal> e <literal>next_hi</literal>) + como fonte para os valores hi. O algoritmo hi/lo gera identificadores que são + únicos apenas para um banco de dados particular. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>seqhilo</literal></term> + <listitem> + <para> + utiliza um algoritmo hi/lo para gerar de forma eficinete identificadores do tipo + <literal>long</literal>, <literal>short</literal> ou <literal>int</literal>, + a partir de uma sequence de banco de dados fornecida. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>uuid</literal></term> + <listitem> + <para> + utiliza um algortimo UUID de 128-bits para gerar identificadores do + tipo string, unicos em uma rede(o endereço IP é utilizado). O UUID é + codificado como um string de digitos hexadecimais de tamanho 32. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>guid</literal></term> + <listitem> + <para> + utiliza um string GUID gerado pelo banco de dados no MS SQL Server + e MySQL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>native</literal></term> + <listitem> + <para> + seleciona entre <literal>identity</literal>, <literal>sequence</literal> + ou <literal>hilo</literal> dependendo das capacidades do banco de dados + utilizado. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>assigned</literal></term> + <listitem> + <para> + deixa a aplicação definir um identificador para o objeto antes que o + <literal>save()</literal> seja chamado. Esta é a estratégia default + se nenhum elemento <literal>&lt;generator&gt;</literal> é especificado. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>select</literal></term> + <listitem> + <para> + retorna a chave primaria recuperada por uma trigger do banco de + dados, selecionado uma linha pela chave única e recuperando o valor + da chave primária. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>foreign</literal></term> + <listitem> + <para> + utiliza o identificador de um outro objeto associado. Normalmente utilizado + em conjunto com uma associaçõa de chave primária do tipo + <literal>&lt;one-to-one&gt;</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>sequence-identity</literal></term> + <listitem> + <para> + a specialized sequence generation strategy which utilizes a + database sequence for the actual value generation, but combines + this with JDBC3 getGeneratedKeys to actually return the generated + identifier value as part of the insert statement execution. This + strategy is only known to be supported on Oracle 10g drivers + targetted for JDK 1.4. Note comments on these insert statements + are disabled due to a bug in the Oracle drivers. + </para> + </listitem> + </varlistentry> + </variablelist> + + </para> + </sect3> + + <sect3 id="mapping-declaration-id-hilo" revision="1"> + <title>Algoritmo Hi/lo</title> + <para> + Os geradores <literal>hilo</literal> e <literal>seqhilo</literal> fornecem duas + implementações alternativas do algoritmo hi/lo, uma solução preferencial para a geração + de identificadores. A primeira implementação requer uma tabela especial do banco de + dados para manter o proximo valor "hi" disponível. A segunda utiliza uma seqüência + do estilo Oracle (quando suportado). + </para> + + <programlisting><![CDATA[<id name="id" type="long" column="cat_id"> + <generator class="hilo"> + <param name="table">hi_value</param> + <param name="column">next_value</param> + <param name="max_lo">100</param> + </generator> +</id>]]></programlisting> + + <programlisting><![CDATA[<id name="id" type="long" column="cat_id"> + <generator class="seqhilo"> + <param name="sequence">hi_value</param> + <param name="max_lo">100</param> + </generator> +</id>]]></programlisting> + + <para> + Infelizemente, voce não pode utilizar <literal>hilo</literal> quando estiver + fornecendo sia propria <literal>Connection</literal> para o Hibernate. Quando o + Hibernate está usando um datasource do servidor de aplicações para obter conexões + suportadas com JTA, você precisa configurar adequadamente o + <literal>hibernate.transaction.manager_lookup_class</literal>. + </para> + </sect3> + + <sect3 id="mapping-declaration-id-uuid"> + <title>UUID algorithm</title> + <para> + O UUID contem: o endereço IP, hora de inicio da JVM (com precisão de um quarto + de segundo), a hora do sistema e um valor contador (unico dentro da JVM). + Não é possivel obter o endereço MAC ou um endereço de memória do código Java, + assim este é o melhor que pode ser feito sem utilizar JNI. + </para> + </sect3> + + <sect3 id="mapping-declaration-id-sequences"> + <title>Colunas de identidade e sequencias</title> + <para> + Para bancos de dados que suportam colunas de identidade (DB2, MySQL, Sybase, + MS SQL), você pode utilizar uma geração de chave <literal>identity</literal>. + Para bancos de dados que suportam sequencias (DB2, Oracle, PostgreSQL, Interbase, + McKoi, SAP DB) voce pode utilizar a geração de chaves no estilo + <literal>sequence</literal>. As duas estratégias requerem duas consultas SQL + para inserir um novo objeto. + </para> + + <programlisting><![CDATA[<id name="id" type="long" column="person_id"> + <generator class="sequence"> + <param name="sequence">person_id_sequence</param> + </generator> +</id>]]></programlisting> + + <programlisting><![CDATA[<id name="id" type="long" column="person_id" unsaved-value="0"> + <generator class="identity"/> +</id>]]></programlisting> + + <para> + Para desenvolvimento multi-plataforma, a estratégia <literal>native</literal> + irá escolher entre as estratégias i <literal>identity</literal>, + <literal>sequence</literal> e <literal>hilo</literal>, dependendo das + capacidades do banco de dados utilizado. + </para> + </sect3> + + <sect3 id="mapping-declaration-id-assigned"> + <title>Identificadores especificados</title> + <para> + Se você quer que a aplicação especifique os identificadores + (em vez do Hibernate gerá-los) você deve utilizar o gerador + <literal>assigned</literal>. Este gerador especial irá utilizar o valor + do identificador especificado para a propriedade de identificação do objeto. + Este gerador é usado quando a chave primaria é a chave natural em vez de uma + surrogate key. Este é o comportamento padrão se você não especificar + um elemento <literal>&lt;generator&gt;</literal>. + </para> + + <para> + Escolher o gerador <literal>assigned</literal> faz com que o Hibernate + utilize <literal>unsaved-value="undefined"</literal>, forçando o Hibernate + ir até o banco de dados para determinar se uma instância está transiente ou + desasociada, a menos que haja uma versão ou uma propriedade timestamp, + ou você pode definir <literal>Interceptor.isUnsaved()</literal>. + </para> + </sect3> + + <sect3 id="mapping-declaration-id-select"> + <title>Chaves primárias geradas por triggers</title> + <para> + Apenas para sistemas legados (o Hibernate nao gera DDL com triggers). + </para> + + <programlisting><![CDATA[<id name="id" type="long" column="person_id"> + <generator class="select"> + <param name="key">socialSecurityNumber</param> + </generator> +</id>]]></programlisting> + + <para> + No exemplo acima, há uma única propriedade com valor nomeada + <literal>socialSecurityNumber</literal> definida pela classe, + uma chave natural, e uma surrogate key nomeada + <literal>person_id</literal> cujo valor é gerado pro uma trigger. + </para> + + </sect3> + + </sect2> + + <sect2 id="mapping-declaration-compositeid" revision="3"> + <title>composite-id</title> + + <programlisting><![CDATA[<composite-id + name="propertyName" + class="ClassName" + mapped="true|false" + access="field|property|ClassName"> + node="element-name|." + + <key-property name="propertyName" type="typename" column="column_name"/> + <key-many-to-one name="propertyName class="ClassName" column="column_name"/> + ...... +</composite-id>]]></programlisting> + + <para> + Para tabelas com uma chave composta, você pode mapear múltiplas propriedades + da classe como propriedades de identificação. O elemento + <literal>&lt;composite-id&gt;</literal> aceita o mapeamento da propriedade + <literal>&lt;key-property&gt;</literal> e mapeamentos + <literal>&lt;key-many-to-one&gt;</literal>como elements filhos. + </para> + + <programlisting><![CDATA[<composite-id> + <key-property name="medicareNumber"/> + <key-property name="dependent"/> +</composite-id>]]></programlisting> + + <para> + Sua classe persistente <emphasis>precisa</emphasis> sobre escrever + <literal>equals()</literal> e <literal>hashCode()</literal> para implementar + identificadores compostos igualmente. E precisa também implementar + <literal>Serializable</literal>. + </para> + + <para> + Infelizmente, esta solução para um identificador composto significa que um objeto + persistente é seu próprio identificador. Não há outro "handle" que o próprio objeto. + Você mesmo precisa instanciar uma instância de outra classe persistente e preencher + suas propriedades de identificação antes que você possa dar um <literal>load()</literal> + para o estado persistente associado com uma chave composta. Nos chamamos esta + solução de identificador composto <emphasis>embedded</emphasis> e não aconselhamos + para aplicações sérias. + </para> + + <para> + Uma segunda solução é o que podemos chamar de identificador composto + <emphasis>mapped</emphasis> quando a propriedades de identificação nomeadas dentro do + elemento <literal>&lt;composite-id&gt;</literal> estão duplicadas tando na classe + persistente como em uma classe de identificação separada. + </para> + + <programlisting><![CDATA[<composite-id class="MedicareId" mapped="true"> + <key-property name="medicareNumber"/> + <key-property name="dependent"/> +</composite-id>]]></programlisting> + + <para> + No exemplo, ambas as classes de identificação compostas, <literal>MedicareId</literal>, + e a própria classe entidade tem propriedades nomeadas <literal>medicareNumber</literal> + e <literal>dependent</literal>. A classe identificadora precisa sobrepor + <literal>equals()</literal> e <literal>hashCode()</literal> e implementar + <literal>Serializable</literal>. A desvantagem desta solução é obvia – + duplicação de código. + </para> + + <para> + Os seguintes atributos ão utilizados para especificar o mapeamento de + um identificador composto: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>mapped</literal> mapped (opcional, valor default <literal>false + </literal>): indica que um identificar composto mapeado é usado, e que as + propriedades de mapeamento contidas refere-se tanto a classe entidade e + a classe de identificação composta. + </para> + </listitem> + <listitem> + <para> + <literal>class</literal> (opcional, mas requerida para um identificar composto + mapeado): A classe usada como um identificador composto. + </para> + </listitem> + </itemizedlist> + + <para> + Nós iremos descrever uma terceira e as vezes mais conveniente solução, onde o + identificador composto é implementado como uma classe componente na + <xref linkend="components-compositeid"/>. Os atributos descritos abaixo aplicam-se + apenas para esta solução: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>name</literal> (opcional, requerida para esta solução): Uma + propriedade do tipo componente que armazena o identificador composto + (veja capítulo 9) + </para> + </listitem> + <listitem> + <para> + <literal>access</literal> (opcional - valor default <literal>property</literal>): + A estartégia Hibernate que deve ser utilizada para acessar o valor da propriedade. + </para> + </listitem> + <listitem> + <para> + <literal>class</literal> (opcional - valor default para o tipo de propriedade + determiando por reflexão) : A classe componente utilizada como um identificador + composto (veja a próxima sessão). + </para> + </listitem> + </itemizedlist> + + <para> + Esta terceira solução, um <emphasis>componente de identificação</emphasis>, é o que nós + recomendamos para a maioria das aplicações. + </para> + + </sect2> + + <sect2 id="mapping-declaration-discriminator" revision="3"> + <title>discriminator</title> + + <para> + O elemento <literal>&lt;discriminator&gt;</literal> é necessário para persistência + polimórfica utilizando a estratégia de mapeamento table-per-class-hierarchy e declara + uma coluna discriminadora da tabela. A coluna discriminadora contem valores de marcação + que dizem a camada de persistência qual subclasse instanciar para uma linha particular. + Um restrito conjunto de tipos que podem ser utilizados: <literal>string</literal>, + <literal>character</literal>, <literal>integer</literal>, <literal>byte</literal>, + <literal>short</literal>, <literal>boolean</literal>, + <literal>yes_no</literal>, <literal>true_false</literal>. + </para> + + <programlistingco> + <areaspec> + <area id="discriminator1" coords="2 60"/> + <area id="discriminator2" coords="3 60" /> + <area id="discriminator3" coords="4 60" /> + <area id="discriminator4" coords="5 60" /> + <area id="discriminator5" coords="6 60" /> + </areaspec> + <programlisting><![CDATA[<discriminator + column="discriminator_column" + type="discriminator_type" + force="true|false" + insert="true|false" + formula="arbitrary sql expression" +/>]]></programlisting> + <calloutlist> + <callout arearefs="discriminator1"> + <para> + <literal>column</literal> (opcional - valor default <literal>class</literal>) + o nome da coluna discriminadora + </para> + </callout> + <callout arearefs="discriminator2"> + <para> + <literal>type</literal> (opcional - valor default <literal>string</literal>) + o nome que indica o tipo Hibernate + </para> + </callout> + <callout arearefs="discriminator3"> + <para> + <literal>force</literal> (opcional - valor default <literal>false</literal>) + "força" o Hibernate a especificar valores discriminadores permitidos mesmo + quando recuperando todas as instancias da classe root. + </para> + </callout> + <callout arearefs="discriminator4"> + <para> + <literal>insert</literal> (opcional - valor default para <literal>true</literal>) + sete isto para <literal>false</literal> se sua coluna discriminadora é também + parte do identificador composto mapeado. (Diz ao Hibernate para não incluir a + coluna em comandos SQL <literal>INSERT</literal>s). + </para> + </callout> + <callout arearefs="discriminator5"> + <para> + <literal>formula</literal> (opcional) uma expressão SQL arbitraria que é e + xecutada quando um tipo tem que ser avaliado. Permite discriminação baseada + em conteúdo. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Valores atuais de uma coluna discriminada são especificados pelo atributo + <literal>discriminator-value</literal> da <literal>&lt;class&gt;</literal> + e elementos da <literal>&lt;subclass&gt;</literal>. + </para> + + <para> + O atributo <literal>force</literal> é util (apenas) em tabelas contendo linhas com + valores discriminadores "extras" que não estão mapeados para uma classe persistente. + Este não é geralmente o caso. + </para> + + <para> + Usando o atributo <literal>formula</literal> voce pode declarar uma expressão SQL + arbitrária que sera utilizada para avaliar o tipo de uma linha : + </para> + + <programlisting><![CDATA[<discriminator + formula="case when CLASS_TYPE in ('a', 'b', 'c') then 0 else 1 end" + type="integer"/>]]></programlisting> + + </sect2> + + <sect2 id="mapping-declaration-version" revision="4"> + <title>version (optional)</title> + + <para> + O elemento <literal>&lt;version&gt;</literal> é opcional e indica que a tabela + possui dados versionados. Isto é particularmente útil se você planeja utilizar + <emphasis>transações longas</emphasis> (veja abaixo): + </para> + + <programlistingco> + <areaspec> + <area id="version1" coords="2 70"/> + <area id="version2" coords="3 70"/> + <area id="version3" coords="4 70"/> + <area id="version4" coords="5 70"/> + <area id="version5" coords="6 70"/> + <area id="version6" coords="7 70"/> + <area id="version7" coords="8 70"/> + </areaspec> + <programlisting><![CDATA[<version + column="version_column" + name="propertyName" + type="typename" + access="field|property|ClassName" + unsaved-value="null|negative|undefined" + generated="never|always" + insert="true|false" + node=&quot;element-name|@attribute-name|element/(a)attribute|.&quot; +/>]]></programlisting> + <calloutlist> + <callout arearefs="version1"> + <para> + <literal>column</literal> (opcional - default a a propriedade name): O nome da + coluna mantendo o numero da versão + </para> + </callout> + <callout arearefs="version2"> + <para> + <literal>name</literal>: O nome da propriedade da classe persistente. + </para> + </callout> + <callout arearefs="version3"> + <para> + <literal>type</literal> (opcional - valor default para <literal>integer</literal>): + O tipo do numero da versão + </para> + </callout> + <callout arearefs="version4"> + <para> + <literal>access</literal> (opcional - valor default <literal>property</literal>): + A estratégia Hibernate que deve ser usada para acessar o valor da propriedade. + </para> + </callout> + <callout arearefs="version5"> + <para> + <literal>unsaved-value</literal> (opcional – valor default para <literal>undefined + </literal>): Um valor para a propriedade versão que indica que uma instancia é + uma nova instanciada (unsaved), distinguindo de instancias desconectadas que foram + salvas ou carregadas em sessões anteriores. ((<literal>undefined</literal> especifica + que o valor da propriedade de identificação deve ser utilizado). + </para> + </callout> + <callout arearefs="version6"> + <para> + <literal>generated</literal> (optional - defaults to <literal>never</literal>): + Specifies that this version property value is actually generated by the database. + See the discussion of <xref linkend="mapping-generated">generated properties</xref>. + <literal>generated</literal> (opcional - valor default <literal>never</literal>): + Especifica que valor para a propriedade versão é na verdade gerado pelo banco de + dados. Veja a discussão da Seção + <xref linkend="mapping-generated">generated properties</xref>. + </para> + </callout> + <callout arearefs="version7"> + <para> + <literal>insert</literal> (opcional - valor default para <literal>true</literal>): + Especifica se a coluna de versão deve ser incluída no comando SQL de insert. + Pode ser configurado como <literal>false</literal> se a coluna do banco de dados + está definida com um valor default de <literal>0</literal>. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Números de versão podem ser dos tipos Hibernate <literal>long</literal>, + <literal>integer</literal>, <literal>short</literal>, <literal>timestamp</literal> ou + <literal>calendar</literal>. + </para> + + <para> + A versão de uma propriedade timestamp nunca deve ser nula para uma instancia + desconectada, assim o Hibernate irá identificar qualquer instância com uma versão + nula ou timestamp como transiente, não importando qual estratégia para foi + especificada para <literal>unsaved-value</literal>. <emphasis>Declarando uma versão + nula ou a propriedade timestamp é um caminho fácil para tratar problemas com + reconexões transitivas no Hibernate, especialmente úteis para pessoas utilizando + identificadores assinaldados ou chaves compostas!</emphasis> + </para> + </sect2> + + <sect2 id="mapping-declaration-timestamp" revision="4" > + <title>timestamp (optional)</title> + + <para> + O elemento opcional <literal>&lt;timestamp&gt;</literal> indica que uma tabela contém + dados timestamped. Isso tem por objetivo dar uma alternativa para versionamento. Timestamps + são por natureza uma implementação menos segura do locking otimista. Entretanto, algumas + vezes a aplicação pode usar timestamps em outros caminhos. + </para> + + <programlistingco> + <areaspec> + <area id="timestamp1" coords="2 70"/> + <area id="timestamp2" coords="3 70" /> + <area id="timestamp3" coords="4 70" /> + <area id="timestamp4" coords="5 70" /> + <area id="timestamp5" coords="6 70" /> + <area id="timestamp6" coords="7 70" /> + </areaspec> + <programlisting><![CDATA[<timestamp + column="timestamp_column" + name="propertyName" + access="field|property|ClassName" + unsaved-value="null|undefined" + source="vm|db" + generated="never|always" + node=&quot;element-name|@attribute-name|element/(a)attribute|.&quot; +/>]]></programlisting> + <calloutlist> + <callout arearefs="timestamp1"> + <para> + <literal>column</literal> (opcional - valor default para a propriedade name): + O nome da coluna que mantem o timestamp. + </para> + </callout> + <callout arearefs="timestamp2"> + <para> + <literal>name</literal>: O nome da propriedade no estilo JavaBeans do + tipo <literal>Date</literal> ou <literal>Timestamp</literal> da classe + persistente Java. + </para> + </callout> + <callout arearefs="timestamp3"> + <para> + <literal>access</literal> (opcional - valor default para <literal>property</literal>): + A estretagia Hibernate que deve ser utilizada para acessar o valor da propriedade. + </para> + </callout> + <callout arearefs="timestamp4"> + <para> + <literal>unsaved-value</literal> (opcional - valor default <literal>null</literal>): + Uma propriedade para a versão de que indica que uma instância é uma nova instanciada + (unsaved), distinguindo-a de instancias desconectadas que foram salvas ou carregadas + em sessões previas. (<literal>undefined</literal> especifica que um valor de + propriedade de identificação deve ser utilizado) + </para> + </callout> + <callout arearefs="timestamp5"> + <para> + <literal>source</literal> (opcional - valor default para <literal>vm</literal>): + De onde o Hibernate deve recuperar o valor timestamp? Do banco de dados ou da JVM + corrente? Timestamps baseados em banco de dados levam a um overhead porque o + Hibernate precisa acessar o banco de dados para determinar o "próximo valor", mas é + mais seguro para uso em ambientes de "cluster". Observe também, que nem todos + <literal>Dialect</literal>s suportam a recuperação do timestamp corrente do banco + de dados, enquando outros podem não ser seguros para utilização em bloqueios + pela falta de precisão (Oracle 8 por exemplo) + </para> + </callout> + <callout arearefs="timestamp6"> + <para> + <literal>generated</literal> (opcional - valor default <literal>never</literal>): + Especifica que o valor da propriedade timestamp é gerado pelo banco de dados. + Veja a discussão <xref linkend="mapping-generated">generated properties</xref>. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Observe que <literal>&lt;timestamp&gt;</literal> é equivalente a + <literal>&lt;version type="timestamp"&gt;</literal>. E + <literal>&lt;timestamp source="db"&gt;</literal> é equivalente a + <literal>&lt;version type="dbtimestamp"&gt;</literal>. + </para> + </sect2> + + + <sect2 id="mapping-declaration-property" revision="4"> + <title>property</title> + + <para> + O elemento <literal>&lt;property&gt;</literal> declara uma propriedade + persistente de uma classe, no estilo JavaBean. + </para> + + <programlistingco> + <areaspec> + <area id="property1" coords="2 70"/> + <area id="property2" coords="3 70"/> + <area id="property3" coords="4 70"/> + <areaset id="property4-5" coords=""> + <area id="property4" coords='5 70'/> + <area id="property5" coords='6 70'/> + </areaset> + <area id="property6" coords="7 70"/> + <area id="property7" coords="8 70"/> + <area id="property8" coords="9 70"/> + <area id="property9" coords="10 70"/> + <area id="property10" coords="11 70"/> + <area id="property11" coords="12 70"/> + <area id="property12" coords="13 70"/> + </areaspec> + <programlisting><![CDATA[<property + name="propertyName" + column="column_name" + type="typename" + update="true|false" + insert="true|false" + formula="arbitrary SQL expression" + access="field|property|ClassName" + lazy="true|false" + unique="true|false" + not-null="true|false" + optimistic-lock="true|false" + generated="never|insert|always" + node=&quot;element-name|@attribute-name|element/(a)attribute|.&quot; + index="index_name" + unique_key="unique_key_id" + length="L" + precision="P" + scale="S" +/>]]></programlisting> + <calloutlist> + <callout arearefs="property1"> + <para> + <literal>name</literal>: o nome da propriedade, iniciando com letra minúscula. + </para> + </callout> + <callout arearefs="property2"> + <para> + <literal>column</literal> (opcional - default para a propriedade name): o nome + da coluna mapeada do banco de dados, Isto pode também ser especificado pelo(s) + elemento(s) <literal>&lt;column&gt;</literal> aninhados. + + </para> + </callout> + <callout arearefs="property3"> + <para> + <literal>type</literal> (opcional): um nome que indica o tipo Hibernate. + </para> + </callout> + <callout arearefs="property4-5"> + <para> + <literal>update, insert</literal> (opcional - valor default <literal>true</literal>): + especifica que as colunas mapeadas devem ser incluidas nas instruções SQL de + <literal>UPDATE</literal> e/ou <literal>INSERT</literal> . Setar ambas para to + <literal>false</literal> permite uma propridade "derivada" pura cujo valor é + inicializado de outra propriedade que mapeie a mesma coluna(s) ou por uma trigger + ou outra aplicação. + </para> + </callout> + <callout arearefs="property6"> + <para> + <literal>formula</literal> (opcional): uma expressão SQL que definie o valor para + uma propriedade <emphasis>calculada</emphasis>. Propriedades calculadas nao tem + uma coluna de mapeamento para elas. + </para> + </callout> + <callout arearefs="property7"> + <para> + <literal>access</literal> (opcional – valor default <literal>property</literal>): + A estratégia que o Hibernate deve utilizar para acessar o valor da propriedade + </para> + </callout> + <callout arearefs="property8"> + <para> + <literal>lazy</literal> (opcional - valor default para <literal>false</literal>): + Especifica que esta propriedade deve ser trazida de forma "lazy" quando a + instancia da variável é acessada pela primeira vez (requer instrumentação + bytecode em tempo de criação). + </para> + </callout> + <callout arearefs="property9"> + <para> + <literal>unique</literal> (opcional): Habilita a geração de DDL de uma + unica constraint para as colunas. Assim, permite que isto seja o + alvo de uma <literal>property-ref</literal>. + </para> + </callout> + <callout arearefs="property10"> + <para> + <literal>not-null</literal> (opcional): Habilita a geração de DDL de uma + constraint de nulidade para as colunas. + </para> + </callout> + <callout arearefs="property11"> + <para> + <literal>optimistic-lock</literal> (opcional - valor default <literal>true</literal>): + Especifica se mudanças para esta propriedade requerem ou não bloqueio otimista. + Em outras palavras, determina se um incremento de versão deve ocorrer quando + esta propriedade está suja. + </para> + </callout> + <callout arearefs="property12"> + <para> + <literal>generated</literal> (opcional - valor default <literal>never</literal>): + Especifica que o valor da propriedade é na verdade gerado pelo banco de dados. + Veja a discussão da seção + <xref linkend="mapping-generated">generated properties</xref>. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + <emphasis>typename</emphasis> pode ser: + </para> + + <orderedlist spacing="compact"> + <listitem> + <para> + The name of a Hibernate basic type (eg. <literal>integer, string, character, + date, timestamp, float, binary, serializable, object, blob</literal>). + O nome do tipo basico do Hibernate (ex., <literal>integer, string, character, + date, timestamp, float, binary, serializable, object, blob</literal>). + </para> + </listitem> + <listitem> + <para> + O nome da classe Java com um tipo básico default (ex. <literal>int, float, + char, java.lang.String, java.util.Date, java.lang.Integer, java.sql.Clob</literal>). + </para> + </listitem> + <listitem> + <para> + O nome da classe Java serializable + </para> + </listitem> + <listitem> + <para> + O nome da classe de um tipo customizado (ex. <literal>com.illflow.type.MyCustomType</literal>). + </para> + </listitem> + </orderedlist> + + <para> + Se você não especificar um tipo, o Hibernate ira utilizar reflexão sobre a + propriedade nomeada para ter uma idéia do tipo Hibernate correto. O Hibernate ira + tentar interpretar o nome da classe retornada, usando as regras 2, 3 e 4 nesta ordem. + Entretanto, isto não é sempre suficiente Em certos casos, você ainda irá necessitar + do atributo <literal>type</literal>. (Por exemplo, para distinguir entre + <literal>Hibernate.DATE</literal> ou <literal>Hibernate.TIMESTAMP</literal>, + ou para espcificar uma tipo ciustomizado.) + </para> + + <para> + O atributo <literal>access</literal> permite voce controlar como o Hibernate irá + acessar a propriedade em tempo de execução. Por default, o Hibernate irá chamar os + métodos get/set da propriedades. Se voce especificar <literal>access="field"</literal>, + o Hibernate ira bipassar os metodos get/set, acessnado o campo diretamente, + usando reflexão. Voc epode especificar sua própria estratégia para acesso da + propriedade criando uma classe que implemente a interface + <literal>org.hibernate.property.PropertyAccessor</literal>. + </para> + + <para> + Um recurso especialmente poderoso é o de propriedades derivadas. Estas propriedades + são por definição read-only, e o valor da propriedade é calculado em tempo de execução. + Você declara este calculo como uma expressão SQL, que traduz para clausula + <literal>SELECT</literal> de uma subquery daquery SQL que carrega a instancia: + </para> + + <programlisting><![CDATA[ +<property name="totalPrice" + formula="( SELECT SUM (li.quantity*p.price) FROM LineItem li, Product p + WHERE li.productId = p.productId + AND li.customerId = customerId + AND li.orderNumber = orderNumber )"/>]]></programlisting> + + <para> + Observe que você pode referenciar as entidades da própria tabela, + através da não declaração de um alias para uma coluna particular ( + <literal>customerId</literal> no exemplo dado). Observe tambem que voce pode usar o + mapeamento de elemento aninhado <literal>&lt;formula&gt;</literal>, se você não + gostar de usar o atributo. + </para> + + </sect2> + + <sect2 id="mapping-declaration-manytoone" revision="5"> + <title>many-to-one</title> + + <para> + Uma associação ordinária para outra classe persistente é declarada usando o + elemento <literal>many-to-one</literal>. O modelo relacional é uma + associação many-to-one: a uma chave estrangeira de uma tabela referenciando + a chave primaria da tabela destino. + </para> + + <programlistingco> + <areaspec> + <area id="manytoone1" coords="2 70"/> + <area id="manytoone2" coords="3 70"/> + <area id="manytoone3" coords="4 70"/> + <area id="manytoone4" coords="5 70"/> + <area id="manytoone5" coords="6 70"/> + <areaset id="manytoone6-7" coords=""> + <area id="manytoone6" coords='7 70'/> + <area id="manytoone7" coords='8 70'/> + </areaset> + <area id="manytoone8" coords="9 70"/> + <area id="manytoone9" coords="10 70"/> + <area id="manytoone10" coords="11 70"/> + <area id="manytoone11" coords="12 70"/> + <area id="manytoone12" coords="13 70"/> + <area id="manytoone13" coords="14 70"/> + <area id="manytoone14" coords="15 70"/> + <area id="manytoone15" coords="16 70"/> + <area id="manytoone16" coords="17 70"/> + </areaspec> + <programlisting><![CDATA[<many-to-one + name="propertyName" + column="column_name" + class="ClassName" + cascade="cascade_style" + fetch="join|select" + update="true|false" + insert="true|false" + property-ref="propertyNameFromAssociatedClass" + access="field|property|ClassName" + unique="true|false" + not-null="true|false" + optimistic-lock="true|false" + lazy="proxy|no-proxy|false" + not-found="ignore|exception" + entity-name="EntityName" + formula="arbitrary SQL expression" + node=&quot;element-name|@attribute-name|element/(a)attribute|.&quot; + embed-xml="true|false" + index="index_name" + unique_key="unique_key_id" + foreign-key="foreign_key_name" +/>]]></programlisting> + <calloutlist> + <callout arearefs="manytoone1"> + <para> + <literal>name</literal>: O nome da propriedade. + </para> + </callout> + <callout arearefs="manytoone2"> + <para> + <literal>column</literal> (opcional): O nome da coluna foreign key. Isto + pode também ser especificado através de elementos aninhados + <literal>&lt;column&gt;</literal>. + </para> + </callout> + <callout arearefs="manytoone3"> + <para> + <literal>class</literal> (opcional – default para o tipo de propriedade + determinado pela reflexão). O nome da classe associada. + </para> + </callout> + <callout arearefs="manytoone4"> + <para> + <literal>cascade</literal> (opcional): Especifica quais operações dever + ser em cascata do objeto pai para o objeto associado. + </para> + </callout> + <callout arearefs="manytoone5"> + <para> + <literal>fetch</literal> (opcional - default para <literal>select</literal>): + Escolhe entre recuperação outer-join ou recuperação seqüencial. + </para> + </callout> + <callout arearefs="manytoone6-7"> + <para> + <literal>update, insert</literal> (opcional - valor default <literal>true</literal>): + especifica que as colunas mapeadas dever ser incluidas em instruções SQL de + <literal>UPDATE</literal> e/ou <literal>INSERT</literal>. Setando ambas para + <literal>false</literal> você permite uma associação "derivada" pura cujos valores + são inicializados de algumas outras propriedades que mapeiam a mesma coluna ou + por uma trigger ou outra aplicação. + </para> + </callout> + <callout arearefs="manytoone8"> + <para> + <literal>property-ref</literal>: (opcional) O nome da propriedade da classe associada + que faz a junção desta foreign key. Se não especificada, a chave primaria da + classe associada será utilizada. + </para> + </callout> + <callout arearefs="manytoone9"> + <para> + <literal>access</literal> (opcional - valor default <literal>property</literal>): A + estrategia que o Hibernate deve utilizar para acessar o valor da propriedade. + </para> + </callout> + <callout arearefs="manytoone10"> + <para> + <literal>unique</literal> (opcional): Habilita a geração DDL de uma constraint + unique para a coluna foreign-key. Alem disso, permite ser o alvo de uma + <literal>property-ref</literal>. Isso torna a associação multipla + efetivamente um para um. + </para> + </callout> + <callout arearefs="manytoone11"> + <para> + <literal>not-null</literal> (opcional): Habilita a geração DDL de uma constraint de + nulidade para as foreign keys. + </para> + </callout> + <callout arearefs="manytoone12"> + <para> + <literal>optimistic-lock</literal> (opcional - valor default <literal>true</literal>): + Especifica se mudanças desta propriedade requerem ou não travamento otimista. + Em outras palavras, determina se um incremento de versão deve ocorrer quando + esta propriedade está suja. + </para> + </callout> + <callout arearefs="manytoone13"> + <para> + <literal>lazy</literal>(opcional – valor default <literal>proxy</literal>): + Por default, associações de ponto unico são envoltas em um proxie. + <literal>lazy="no-proxy"</literal> especifica que a propriedade deve ser + trazida de forma tardia quando a instancia da variável é acessada pela + primeira vez (requer instrumentação bytecode em tempo de criação) + <literal>lazy="false"</literal> especifica que a associação será + sempre recuperada fortemente. + </para> + </callout> + <callout arearefs="manytoone14"> + <para> + <literal>not-found</literal> (opcional - valor default <literal>exception</literal>): + Especifica como as foreign keys que referenciam linhas ausentes serão tratadas: + <literal>ignore</literal> irá tratar a linha ausente como ama associaççao de null + </para> + </callout> + <callout arearefs="manytoone15"> + <para> + <literal>entity-name</literal> (opcional): O nome da entidade da classe associada. + </para> + </callout> + </calloutlist> + <callout arearefs="manytoone16"> + <para> + <literal>formula</literal> (optional): Uma expressão SQL que define um valor + para um foreign key <emphasis>computed</emphasis>. + </para> + </callout> + </programlistingco> + + <para> + Setar o valor do atributo <literal>cascade</literal> para qualquer valor + significativo diferente de <literal>none</literal> irá propagar certas operações + ao objeto associado. Os valores significativos são os nomes das operações básicas + do Hibernate, <literal>persist, merge, delete, save-update, evict, replicate, lock, + refresh</literal>, assim como os valores especiais <literal>delete-orphan</literal> + e <literal>all</literal> e combinações de nomes de operações separadas por vírgula, + como por exemplo, <literal>cascade="persist,merge,evict"</literal> ou + <literal>cascade="all,delete-orphan"</literal>. Veja a seção + <xref linkend="objectstate-transitive"/> para uma explicação completa. Note que + associações valoradas simples (associações muitos-pra-um, e um-pra-um) não suportam + orphan delete. + </para> + + <para> + Uma típica declaração <literal>muitos-pra-um</literal> se parece com esta: + </para> + + <programlisting><![CDATA[<many-to-one name="product" class="Product" column="PRODUCT_ID"/>]]></programlisting> + + <para> + O atributo <literal>property-ref</literal> deve apenas ser usado para mapear dados + legados onde uma chave estrangeira se referencia a uma chave exclusiva da tabela + associada que não seja à chave primária. Este é um modelo relacional desagradável. + Por exemplo, suponha que a classe <literal>Product</literal> tenha um número + seqüencial exclusivo, que não é a chave primária. (O atributo <literal>unique</literal> + controla a geração de DDL do Hibernate com a ferramenta SchemaExport.) + </para> + + <programlisting><![CDATA[<property name="serialNumber" unique="true" type="string" column="SERIAL_NUMBER"/>]]></programlisting> + + <para> + Então o mapeamento para <literal>OrderItem</literal> poderia usar: + </para> + + <programlisting><![CDATA[<many-to-one name="product" property-ref="serialNumber" column="PRODUCT_SERIAL_NUMBER"/>]]></programlisting> + + <para> + Porém, isto obviamente não é indicado, nunca. + </para> + + <para> + Se a chave exclusiva referenciada engloba múltiplas propriedades da entidade associada, + você deve mapear as propriedades referenciadas dentro de um elemento chamado + <literal>&lt;properties&gt;</literal> + + </para> + + <para> + Se a chave exclusiva referenciada é a propriedade de um componente, você pode especificar + um caminho para a propriedade. + </para> + + <programlisting><![CDATA[<many-to-one name="owner" property-ref="identity.ssn" column="OWNER_SSN"/>]]></programlisting> + + </sect2> + + <sect2 id="mapping-declaration-onetoone" revision="3"> + <title>one-to-one (um-pra-um)</title> + + <para> + Uma associação um-pra-um para outra classe persistente é declarada usando + um elemento <literal>one-to-one </literal>. + </para> + + <programlistingco> + <areaspec> + <area id="onetoone1" coords="2 70"/> + <area id="onetoone2" coords="3 70"/> + <area id="onetoone3" coords="4 70"/> + <area id="onetoone4" coords="5 70"/> + <area id="onetoone5" coords="6 70"/> + <area id="onetoone6" coords="7 70"/> + <area id="onetoone7" coords="8 70"/> + <area id="onetoone8" coords="9 70"/> + <area id="onetoone9" coords="10 70"/> + <area id="onetoone10" coords="11 70"/> + </areaspec> + <programlisting><![CDATA[<one-to-one + name="propertyName" + class="ClassName" + cascade="cascade_style" + constrained="true|false" + fetch="join|select" + property-ref="propertyNameFromAssociatedClass" + access="field|property|ClassName" + formula="any SQL expression" + lazy="proxy|no-proxy|false" + entity-name="EntityName" + node=&quot;element-name|@attribute-name|element/(a)attribute|.&quot; + embed-xml="true|false" + foreign-key="foreign_key_name" +/>]]></programlisting> + <calloutlist> + <callout arearefs="onetoone1"> + <para> + <literal>name</literal>: O nome da propriedade. + </para> + </callout> + <callout arearefs="onetoone2"> + <para> + <literal>class</literal> (opcional – default para o tipo da propriedade + definido via reflection): O nome da classe associada. + </para> + </callout> + <callout arearefs="onetoone3"> + <para> + <literal>cascade</literal> (opcional): Especifica qual operação deve + ser cascateada do objeto pai para o objeto associado. + </para> + </callout> + <callout arearefs="onetoone4"> + <para> + <literal>constrained</literal> (opcional): Especifica que uma chave estrangeira + constraint na chave primária da tabela mapeada referencia a tabela da classe + associada, Esta opção afeta a ordem em queh <literal>save()</literal> e + <literal>delete()</literal> são cascateadas, e determina se a associação + pode ser substituída (isto também é usado pela ferramenta schema export). + </para> + </callout> + <callout arearefs="onetoone5"> + <para> + <literal>fetch</literal> ((opcional – valor default <literal>select</literal>): + Escolhe entre outer-join fetching ou sequential select fetching. + </para> + </callout> + <callout arearefs="onetoone6"> + <para> + <literal>property-ref</literal>(opcional): O nome da propriedade da classe associada + que é ligada a chave primária desta classe. Se não for especificada, a chave primária + da classe associada é utilizada. + </para> + </callout> + <callout arearefs="onetoone7"> + <para> + <literal>access</literal> (opcional - valor default padrão <literal>property</literal>): + A estratégia que o Hibernate pode usar para acessar o valor da propriedade. + </para> + </callout> + <callout arearefs="onetoone8"> + <para> + <literal>formula</literal> (opcional): Quase todas associações um-pra-um mapeiam + para a chave primária da entidade dona. No caso raro, que não é o caso, você + pode especificar uma outra coluna, colunas ou expressões para juntar utilizando + uma formula SQL. (Veja <literal>org.hibernate.test.onetooneformula</literal> + para exemplo). + </para> + </callout> + <callout arearefs="onetoone9"> + <para> + <literal>lazy</literal> (opcional – valor default <literal>proxy</literal>): + Por default, associações single point são proxied. <literal>lazy="no-proxy"</literal> + especifica que a propriedade deve ser fetched lazily quando o atributo é acessado + pela primeira vez (requer build-time bytecode instrumentation). + <literal>lazy="false"</literal> especifica que a associação vai sempre ser + avidamente fetched. <emphasis>Note que se <literal>constrained="false"</literal>, + proxing é impossível e o Hibernate vai ávido fetch a associação!</emphasis> + </para> + </callout> + <callout arearefs="onetoone10"> + <para> + <literal>entity-name</literal> (opcional): O nome da entidade da classe associada. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Existem duas variedades de associações um-pra-um: + </para> + <itemizedlist> + <listitem><para> + associações de chave primária + </para></listitem> + <listitem><para> + associações de chave estrangeira exclusiva + </para></listitem> + </itemizedlist> + + <para> + Associações de chave primária não necessitam de uma coluna extra de tabela; se duas + linhas são relacionadas pela associação então as duas linhas da tabela dividem a mesmo + valor da chave primária. Assim, se você quer que dois objetos sejam relacionados por + uma associação de chave primária, você deve ter certeza que eles são assinados com o + mesmo valor identificador! + </para> + + <para> + Para uma associação de chave primária, adicione os seguintes mapeamentos em + <literal>Employee</literal> e <literal>Person</literal>, respectivamente. + </para> + + <programlisting><![CDATA[<one-to-one name="person" class="Person"/>]]></programlisting> + <programlisting><![CDATA[<one-to-one name="employee" class="Employee" constrained="true"/>]]></programlisting> + + <para> + Agora nós devemos assegurar que as chaves primárias de linhas relacionadas nas + tabelas PERSON e EMPLOYEE são iguais. Nós usamos uma estratégia especial de geração + de identificador do Hibernate chamada <literal>foreign</literal>: + </para> + + <programlisting><![CDATA[<class name="person" table="PERSON"> + <id name="id" column="PERSON_ID"> + <generator class="foreign"> + <param name="property">employee</param> + </generator> + </id> + ... + <one-to-one name="employee" + class="Employee" + constrained="true"/> +</class>]]></programlisting> + + <para> + Uma nova instância de <literal>Person</literal> salva recentemente é então assinada + com o mesmo valor da chave primária da instância de <literal>employee</literal> referenciada + com a propriedade <literal>employee</literal> daquela <literal>Person</literal>. + </para> + + <para> + Alternativamente, uma chave estrangeira com uma unique constraint, de + <literal>Employee</literal> para <literal>Person</literal>, pode ser expressa como: + </para> + + <programlisting><![CDATA[<many-to-one name="person" class="Person" column="PERSON_ID" unique="true"/>]]></programlisting> + + <para> + E esta associação pode ser feita de forma bi-direcional adicionando o seguinte + no mapeamento de <literal>Person</literal>: + </para> + + <programlisting><![CDATA[<one-to-one name="employee" class="Employee" property-ref="person"/>]]></programlisting> + + </sect2> + + <sect2 id="mapping-declaration-naturalid"> + <title>natural-id</title> + + <programlisting><![CDATA[<natural-id mutable="true|false"/> + <property ... /> + <many-to-one ... /> + ...... +</natural-id>]]></programlisting> + + <para> + Embora nós recomendemos o uso de surrogate keys como chaves primárias, você deve + ainda identificar chaves naturais para todas as entidades. Uma chave natural é + uma propriedade ou combinação de propriedades que é exclusiva e não nula. Se não + pude ser modificada, melhor ainda. Mapeie as propriedades da chave natural dentro do + elemento <literal>&lt;natural-id&gt;</literal>. O Hibernate irá gerar a chave + exclusiva necessária e as constraints de nullability , e seu mapeamento será + apropriadamente auto documentado. + </para> + + <para> + Nós recomendamos com enfase que você implemente <literal>equals()</literal> e + <literal>hashCode()</literal> para comparar as propriedades da chave natural da + entidade. + </para> + + <para> + Este mapeamento não tem o objetivo de uso com entidades com natural chaves primárias. + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>mutable</literal> mutable (opcional, valor default<literal>false</literal>): + Por default, propriedades naturais identificadoras são consideradas imutáveis (constante). + </para> + </listitem> + </itemizedlist> + + </sect2> + + <sect2 id="mapping-declaration-component" revision="2"> + <title>componente, componente dinâmico</title> + + <para> + O elemento<literal>&lt;component&gt;</literal> mapeia propriedades de um + objeto filho para colunas da tabela de uma classe pai. Componentes podem, + um após o outro, declarar suas próprias propriedades, componentes ou coleções. + Veja "Components" abaixo. + </para> + + <programlistingco> + <areaspec> + <area id="component1" coords="2 45"/> + <area id="component2" coords="3 45"/> + <area id="component3" coords="4 45"/> + <area id="component4" coords="5 45"/> + <area id="component5" coords="6 45"/> + <area id="component6" coords="7 45"/> + <area id="component7" coords="8 45"/> + <area id="component8" coords="9 45"/> + </areaspec> + <programlisting><![CDATA[<component + name="propertyName" + class="className" + insert="true|false" + update="true|false" + access="field|property|ClassName" + lazy="true|false" + optimistic-lock="true|false" + unique="true|false" + node="element-name|." +> + + <property ...../> + <many-to-one .... /> + ........ +</component>]]></programlisting> + <calloutlist> + <callout arearefs="component1"> + <para> + <literal>name</literal>: O nome da propriedade. + </para> + </callout> + <callout arearefs="component2"> + <para> + <literal>class</literal> (opcional – valor default para o tipo de + propriedade determinada por reflection): O nome da classe (filha) do + componente. + </para> + </callout> + <callout arearefs="component3"> + <para> + <literal>insert</literal>: As colunas mapeadas aparecem nos + SQL de <literal>INSERT</literal>s? + </para> + </callout> + <callout arearefs="component4"> + <para> + <literal>update</literal>: As colunas mapeadas aparecem nos + SQL de <literal>UPDATE</literal>s? + </para> + </callout> + <callout arearefs="component5"> + <para> + <literal>access</literal> (opcional – valor default <literal>property</literal>): + A estratégia que o Hibernate pode usar para acessar o valor da propriedade. + </para> + </callout> + <callout arearefs="component6"> + <para> + <literal>lazy</literal> (opcional - valor default <literal>false</literal>): + Especifica que este componente deve ser fetched lazily quando o atributo for + acessado pela primeira vez (requer build-time bytecode instrumentation). + </para> + </callout> + <callout arearefs="component7"> + <para> + <literal>optimistic-lock</literal> (opcional – valor default <literal>true</literal>): + Especifica que atualizações para este componente requerem ou não aquisição + de um lock otimista. Em outras palavras, determina se uma versão de incremento deve + ocorrer quando esta propriedade estiver modificada. + </para> + </callout> + <callout arearefs="component8"> + <para> + <literal>unique</literal> (opcional – valor default <literal>false</literal>): + Especifica que existe uma unique constraint em todas as colunas mapeadas do + componente. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + A tag filha <literal>&lt;property&gt;</literal> acrescenta a propriedade + de mapeamento da classe filha para colunas de uma tabela. + </para> + + <para> + O elemento <literal>&lt;component&gt;</literal> permite um sub-elemento + <literal>&lt;parent&gt;</literal> mapeie uma propriedade da classe do componente + como uma referencia de volta para a entidade que o contém. + </para> + + <para> + O elemento <literal>&lt;dynamic-component&gt;</literal> permite que um + <literal>Map</literal> possa ser mapeado como um componente onde os nomes das + propriedades referem-se para as chaves no mapa, veja + <xref linkend="components-dynamic"/>. + </para> + + </sect2> + + <sect2 id="mapping-declaration-properties" revision="2"> + <title>propriedades</title> + + <para> + O elemento <literal>&lt;properties&gt;</literal> permite a definição de um grupo + com nome, lógico de propriedades de uma classe. O uso mais importante do construtor + é que este permite uma combinação de propriedades para ser o objetivo de uma + <literal>property-ref</literal>. É também um modo conveninente para definir uma + unique constraint de múltiplas colunas. + </para> + + <programlistingco> + <areaspec> + <area id="properties1" coords="2 45"/> + <area id="properties2" coords="3 45"/> + <area id="properties3" coords="4 45"/> + <area id="properties4" coords="5 45"/> + <area id="properties5" coords="6 45"/> + </areaspec> + <programlisting><![CDATA[<properties + name="logicalName" + insert="true|false" + update="true|false" + optimistic-lock="true|false" + unique="true|false" +> + + <property ...../> + <many-to-one .... /> + ........ +</properties>]]></programlisting> + <calloutlist> + <callout arearefs="properties1"> + <para> + <literal>name</literal>:: O nome lógico do agrupamento – + <emphasis>não </emphasis> é o nome atual de propriedade. + </para> + </callout> + <callout arearefs="properties2"> + <para> + <literal>insert</literal>: As colunas mapeadas aparecem nos + SQL de <literal>INSERT</literal>s? + </para> + </callout> + <callout arearefs="properties3"> + <para> + <literal>update</literal>: As colunas mapeadas aparecem nos + SQL de <literal>UPDATE</literal>s? + </para> + </callout> + <callout arearefs="properties4"> + <para> + <literal>optimistic-lock</literal> (opcional – valor default <literal>true</literal>): + Especifica que atualizações para estes componentes requerem ou não aquisição de um + lock otimista. Em outras palavras, determina se uma versão de incremento deve ocorrer + quando estas propriedades estiverem modificadas. + </para> + </callout> + <callout arearefs="properties5"> + <para> + <literal>unique</literal> (opcional – valor defautl <literal>false</literal>): + Especifica que uma unique constraint existe em todas as colunas mapeadas do componente. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Por exemplo, se nós temos o seguinte mapeamento de <literal>&lt;properties&gt;</literal>: + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="personNumber"/> + ... + <properties name="name" + unique="true" update="false"> + <property name="firstName"/> + <property name="initial"/> + <property name="lastName"/> + </properties> +</class>]]></programlisting> + + <para> + Então nós podemos ter uma associação de dados herdados que referem a esta chave + exclusiva da tabela <literal>Person</literal>, ao invés de se referirem a chave + primária: + </para> + + <programlisting><![CDATA[<many-to-one name="person" + class="Person" property-ref="name"> + <column name="firstName"/> + <column name="initial"/> + <column name="lastName"/> +</many-to-one>]]></programlisting> + + <para> + Nós não recomendamos o uso deste tipo de coisa fora do contexto de mapeamento de + dados herdados. + </para> + + </sect2> + + <sect2 id="mapping-declaration-subclass" revision="4"> + <title>subclass (subclasse)</title> + + <para> + Finalmente, a persistência polimórfica requer a declaração de cada subclasse + da classe de persistência raiz. Para a estratégia de mapeamento + table-per-class-hierarchy, a declaração <literal>&lt;subclass&gt;</literal> + deve ser usada. + </para> + + <programlistingco> + <areaspec> + <area id="subclass1" coords="2 55"/> + <area id="subclass2" coords="3 55"/> + <area id="subclass3" coords="4 55"/> + <area id="subclass4" coords="5 55"/> + </areaspec> + <programlisting><![CDATA[<subclass + name="ClassName" + discriminator-value="discriminator_value" + proxy="ProxyInterface" + lazy="true|false" + dynamic-update="true|false" + dynamic-insert="true|false" + entity-name="EntityName" + node="element-name" + extends="SuperclassName"> + + <property .... /> + ..... +</subclass>]]></programlisting> + <calloutlist> + <callout arearefs="subclass1"> + <para> + <literal>name</literal>: O nome de classe completamente qualificada da subclasse. + </para> + </callout> + <callout arearefs="subclass2"> + <para> + <literal>discriminator-value</literal> (opcional – valor default o nome da classe): + Um valor que distingue subclasses individuais. + </para> + </callout> + <callout arearefs="subclass3"> + <para> + <literal>proxy</literal> (opcional): Especifica a classe ou interface que + usará os proxies de inicialização atrasada. + </para> + </callout> + <callout arearefs="subclass4"> + <para> + <literal>lazy</literal> (opcional, valor default <literal>true</literal>): + Configurar <literal>lazy="false"</literal> desabilitará o uso de + inicialização atrasada. + </para> + </callout> + </calloutlist> + </programlistingco> + <para> + Cada subclasse deve declarar suas próprias propriedades persistentes e subclasses. + As propriedades <literal>&lt;version&gt;</literal> e <literal>&lt;id&gt;</literal> + são configuradas para serem herdades da classe raiz. Cada subclasse numa hierarquia + deve definir um único <literal>discriminator-value</literal>. Se nenhum for + especificado, o nome da classe Java completamente qualificada será usada. + </para> + + <para> + Para informações sobre mapeamento de heranças, veja o <xref linkend="inheritance"/>. + </para> + + </sect2> + + <sect2 id="mapping-declaration-joinedsubclass" revision="3"> + <title>joined-subclass</title> + + <para> + Alternativamente, cada subclasse pode ser mapeada para sua própria tabela + (Estratégia de mapeamento table-per-subclass). O estado herdado é devolvido + por associação com a tabela da superclasse. Nós usamos o elemento + <literal>&lt;joined-subclass&gt;</literal>. + </para> + + <programlistingco> + <areaspec> + <area id="joinedsubclass1" coords="2 45"/> + <area id="joinedsubclass2" coords="3 45"/> + <area id="joinedsubclass3" coords="4 45"/> + <area id="joinedsubclass4" coords="5 45"/> + </areaspec> + <programlisting><![CDATA[<joined-subclass + name="ClassName" + table="tablename" + proxy="ProxyInterface" + lazy="true|false" + dynamic-update="true|false" + dynamic-insert="true|false" + schema="schema" + catalog="catalog" + extends="SuperclassName" + persister="ClassName" + subselect="SQL expression" + entity-name="EntityName" + node="element-name"> + + <key .... > + + <property .... /> + ..... +</joined-subclass>]]></programlisting> + <calloutlist> + <callout arearefs="joinedsubclass1"> + <para> + <literal>name</literal>: O nome da classe completamente qualificada da + subclasse. + </para> + </callout> + <callout arearefs="joinedsubclass2"> + <para> + <literal>table</literal>: O nome da tabela da subclasse. + </para> + </callout> + <callout arearefs="joinedsubclass3"> + <para> + <literal>proxy</literal> (opcional): Especifica a classe ou interface + para usar os proxies de recuperação atrasada. + </para> + </callout> + <callout arearefs="joinedsubclass4"> + <para> + <literal>lazy</literal> (opcional, valor default <literal>true</literal>): + Fixanr <literal>lazy="false"</literal> desabilita o uso recuperação + atrasada. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + A coluna discriminator requerida para esta estratégia de mapeamento. Porém, + cada subclasse deve declarar uma coluna de tabela com o identificador do objeto + usando o elemento <literal>&lt;key&gt;</literal>. O mapeamento no início do + capítulo poderia ser re-escrito assim: + </para> + + <programlisting><![CDATA[<?xml version="1.0"?> +<!DOCTYPE hibernate-mapping PUBLIC + "-//Hibernate/Hibernate Mapping DTD//EN" + "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"> + +<hibernate-mapping package="eg"> + + <class name="Cat" table="CATS"> + <id name="id" column="uid" type="long"> + <generator class="hilo"/> + </id> + <property name="birthdate" type="date"/> + <property name="color" not-null="true"/> + <property name="sex" not-null="true"/> + <property name="weight"/> + <many-to-one name="mate"/> + <set name="kittens"> + <key column="MOTHER"/> + <one-to-many class="Cat"/> + </set> + <joined-subclass name="DomesticCat" table="DOMESTIC_CATS"> + <key column="CAT"/> + <property name="name" type="string"/> + </joined-subclass> + </class> + + <class name="eg.Dog"> + <!-- mapping for Dog could go here --> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Para informações de mapeamentos de herança, veja <xref linkend="inheritance"/>. + </para> + + </sect2> + + <sect2 id="mapping-declaration-unionsubclass" revision="2"> + <title>union-subclass</title> + + <para> + Uma terceira opção é mapear para tabelas apenas as classes concretas de uma + hierarquia de heranças, (a estratégia table-per-concrete-class) onde cada tabela + define todos os estados persistentes da classe, incluindo estados herdados. + No Hibernate, não é absolutamente necessário mapear explicitamente como hierarquia + de heranças. Você pode simplesmente mapear cada classe com uma declaração + <literal>&lt;class&gt;</literal> separada. Porém, se você deseja usar associações + polimórficas (por exemplo: uma associação para a superclasse de sua hierarquia), + você precisa usar o mapeamento <literal>&lt;union-subclass&gt;</literal>. + + </para> + + <programlistingco> + <areaspec> + <area id="unionsubclass1" coords="2 45"/> + <area id="unionsubclass2" coords="3 45"/> + <area id="unionsubclass3" coords="4 45"/> + <area id="unionsubclass4" coords="5 45"/> + </areaspec> + <programlisting><![CDATA[<union-subclass + name="ClassName" + table="tablename" + proxy="ProxyInterface" + lazy="true|false" + dynamic-update="true|false" + dynamic-insert="true|false" + schema="schema" + catalog="catalog" + extends="SuperclassName" + abstract="true|false" + persister="ClassName" + subselect="SQL expression" + entity-name="EntityName" + node="element-name"> + + <property .... /> + ..... +</union-subclass>]]></programlisting> + <calloutlist> + <callout arearefs="unionsubclass1"> + <para> + <literal>name</literal>: O nome da subclasse completamente qualificada. + </para> + </callout> + <callout arearefs="unionsubclass2"> + <para> + <literal>table</literal>: O nome da tabela da subclasse. + </para> + </callout> + <callout arearefs="unionsubclass3"> + <para> + <literal>proxy</literal> (optional): Specifies a class or interface to use + for lazy initializing proxies. + + <literal>proxy</literal> (opcional): Especifica a classe ou interface para usar + os proxies de recuperação atrasada. + </para> + </callout> + <callout arearefs="unionsubclass4"> + <para> + <literal>lazy</literal> (optional, defaults to <literal>true</literal>): Setting + <literal>lazy="false"</literal> disables the use of lazy fetching. + <literal>lazy</literal> (opcional, valor default p<literal>true</literal>): + Fixando <literal>lazy="false"</literal> desabilita o uso da recuperação atrasada. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + A coluna discriminatõria não é requerida para esta estratégia de mapeamento. + + </para> + + <para> + Para informações sobre mapeamentos de herança, veja <xref linkend="inheritance"/>. + </para> + + </sect2> + + <sect2 id="mapping-declaration-join" revision="3"> + <title>join</title> + + <para> + Usando o elemento <literal>&lt;join&gt;</literal>>, é possível mapear + propriedades de uma classe para várias tabelas. + </para> + + <programlistingco> + <areaspec> + <area id="join1" coords="2 50"/> + <area id="join2" coords="3 50"/> + <area id="join3" coords="4 50"/> + <area id="join4" coords="5 50"/> + <area id="join5" coords="6 50"/> + <area id="join6" coords="7 50"/> + </areaspec> + <programlisting><![CDATA[<join + table="tablename" + schema="owner" + catalog="catalog" + fetch="join|select" + inverse="true|false" + optional="true|false"> + + <key ... /> + + <property ... /> + ... +</join>]]></programlisting> + + <calloutlist> + <callout arearefs="join1"> + <para> + <literal>table</literal>: O nome da tabela associada. + </para> + </callout> + <callout arearefs="join2"> + <para> + <literal>schema</literal> (opcional): Sobrepõe o nome do esquema + especificado pelo elemento raiz <literal>&lt;hibernate-mapping&gt;</literal>. + </para> + </callout> + <callout arearefs="join3"> + <para> + <literal>catalog</literal> (opcional): Sobrepõe o nome do catálogo + especificado pelo elemento raiz<literal>&lt;hibernate-mapping&gt;</literal>. + </para> + </callout> + <callout arearefs="join4"> + <para> + <literal>fetch</literal>(opcional – valor default <literal>join</literal>): Se setado + para <literal>join</literal>, o padrão, o Hibernate irá usar um inner join para + restaurar um <literal>join</literal> definido por uma classe ou suas subclasses e + uma outer join para um <literal>join</literal> definido por uma subclasse. + Se setado para <literal>select</literal>, então o Hibernate irá usar uma seleção + seqüencial para um <literal>&lt;join&gt;</literal> definida numa subclasse, que irá + ser emitido apenas se uma linha se concentrar para representar uma instância + da subclasse. Inner joins irá ainda ser usado para restaurar um + <literal>&lt;join&gt;</literal> definido pela classe e suas superclasses. + </para> + </callout> + <callout arearefs="join5"> + <para> + <literal>inverse</literal> (opcional – valor default <literal>false</literal>): + Se habilitado, o Hibernate não irá tentar inserir ou atualizar as propriedades + definidas por este join. + </para> + </callout> + <callout arearefs="join6"> + <para> + <literal>optional</literal> (opcional – valor default <literal>false</literal>): + Se habilitado, o Hibernate irá inserir uma linha apenas se as propriedades definidas + por esta junção não forem nulas e irá sempre usar uma outer join para + recuperar as propriedades. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Por exemplo, a informação de endereço para uma pessoa pode ser mapeada para uma + tabela separada (enquanto preservando o valor da semântica de tipos para + todas as propriedades): + </para> + + <programlisting><![CDATA[<class name="Person" + table="PERSON"> + + <id name="id" column="PERSON_ID">...</id> + + <join table="ADDRESS"> + <key column="ADDRESS_ID"/> + <property name="address"/> + <property name="zip"/> + <property name="country"/> + </join> + ...]]></programlisting> + + <para> + Esta característica é útil apenas para modelos de dados legados, nós recomendamos + menos tabelas do que classes e um modelo de domínio bem granulado. Porém, é + útil para ficar trocando entre estratégias de mapeamento de herança + numa hierarquia simples, como explicado mais a frente. + </para> + + </sect2> + + <sect2 id="mapping-declaration-key"> + <title>key</title> + + <para> + Nós vimos que o elemento <literal>&lt;key&gt;</literal> surgiu algumas vezes + até agora. Ele aparece em qualquer lugar que o elemento pai define uma junção + para a nova tabela, e define a chave estrangeira para a tabela associada, que + referencia a chave primária da tabela original. + </para> + + <programlistingco> + <areaspec> + <area id="key1" coords="2 50"/> + <area id="key2" coords="3 50"/> + <area id="key3" coords="4 50"/> + <area id="key4" coords="5 50"/> + <area id="key5" coords="6 50"/> + <area id="key6" coords="7 50"/> + </areaspec> + <programlisting><![CDATA[<key + column="columnname" + on-delete="noaction|cascade" + property-ref="propertyName" + not-null="true|false" + update="true|false" + unique="true|false" +/>]]></programlisting> + + <calloutlist> + <callout arearefs="key1"> + <para>. + <literal>column</literal> (opcional): O nome da coluna da chave estrangeira. + Isto também pode ser especificado por aninhamento de elemento(s) + <literal>&lt;column&gt;</literal>. + </para> + </callout> + <callout arearefs="key2"> + <para> + <literal>on-delete</literal> (opcional, valor default <literal>noaction</literal>): + Especifica se a constraint da chave estrangeira no banco de dados esta + habilitada para cascade delete . + </para> + </callout> + <callout arearefs="key3"> + <para> + <literal>property-ref</literal> (opcional): Especifica que a chave estrangeira + se refere a colunas que não são chave primária da tabela original. + (Util para base de dados legadas.) + </para> + </callout> + <callout arearefs="key4"> + <para> + <literal>not-null</literal> (opcional): Especifica que a coluna da chave + estrangeira não aceita valores nulos (isto é implícito em qualquer momento + que a chave estrangeira também fizer parte da chave primária). + </para> + </callout> + <callout arearefs="key5"> + <para> + <literal>update</literal> (optional): Specifies that the foreign key should never + be updated (this is implied whenever the foreign key is also part of the primary + key). + <literal>update</literal> (opcional): Especifica que a chave estrangeira nunca + deve ser atualizada (isto é implícito em qualquer momento que a chave estrangeira + também fizer parte da chave primária). + </para> + </callout> + <callout arearefs="key6"> + <para> + <literal>unique</literal> (opcional): Especifica que a chave estrangeira deve ter + uma constraint unique (sto é implícito em qualquer momento que a chave estrangeira + também fizer parte da chave primária). + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Nós recomendamos que para sistemas que a performance de delete seja importante, todas as + chaves deve ser definida <literal>on-delete="cascade"</literal>, e o Hibernate irá usar + uma constraint a nível de banco de dados <literal>ON CASCADE DELETE</literal>, ao invés + de muitas instruções <literal>DELETE</literal>. Esteja ciente que esta característica é + um atalho da estratégia usual de optimistic locking do Hibernate para dados versionados. + </para> + + <para> + Os atributos <literal>not-null</literal> e <literal>update</literal> são úteis quando + estamos mapeamos uma associação unidirecional um para muitos. Se você mapear uma + asociação unidirecional um para muitos para uma chave estrangeira non-nullable, você + <emphasis>deve</emphasis> declarar a coluna chave usando + <literal>&lt;key not-null="true"&gt;</literal>. + </para> + + </sect2> + + <sect2 id="mapping-column" revision="4"> + <title>elementos column e formula</title> + <para> + Qualquer elemento de mapeamente que aceita um atributo <literal>column</literal> irá + aceitar alternativamente um subelemento <literal>&lt;column&gt;</literal>. Da mesma forma, + <literal>formula</literal> é uma alternativa para o atributo <literal>formula</literal>. + </para> + + <programlisting><![CDATA[<column + name="column_name" + length="N" + precision="N" + scale="N" + not-null="true|false" + unique="true|false" + unique-key="multicolumn_unique_key_name" + index="index_name" + sql-type="sql_type_name" + check="SQL expression" + default="SQL expression"/>]]></programlisting> + + <programlisting><![CDATA[<formula>SQL expression</formula>]]></programlisting> + + <para> + O atributo <literal>column</literal> e <literal>formula</literal> podem até ser combinados + dentro da mesma propriedade ou associação mapeando para expressar, + por exemplo, associações exóticas. + </para> + + <programlisting><![CDATA[<many-to-one name="homeAddress" class="Address" + insert="false" update="false"> + <column name="person_id" not-null="true" length="10"/> + <formula>'MAILING'</formula> +</many-to-one>]]></programlisting> + + </sect2> + + <sect2 id="mapping-declaration-import"> + <title>import</title> + + <para> + Suponha que a sua aplicação tem duas classes persistentes com o mesmo nome, e você não quer + especificar o nome qualificado (do pacote) nas queries do Hibernate. As Classes devem + ser "importadas" explicitamente, de preferência contando com <literal>auto-import="true"</literal>. + Você pode até importar classes e interfaces que não estão explicitamente mapeadas. + </para> + + <programlisting><![CDATA[<import class="java.lang.Object" rename="Universe"/>]]></programlisting> + + <programlistingco> + <areaspec> + <area id="import1" coords="2 40"/> + <area id="import2" coords="3 40"/> + </areaspec> + <programlisting><![CDATA[<import + class="ClassName" + rename="ShortName" +/>]]></programlisting> + <calloutlist> + <callout arearefs="import1"> + <para> + <literal>class</literal>: O nome qualificado (do pacote) de qualquer classe Java. + </para> + </callout> + <callout arearefs="import2"> + <para> + <literal>rename</literal> (opcional – valor default, o nome da classe não + qualificada): Um nome que pode ser usado numa linguagem de consulta. + </para> + </callout> + </calloutlist> + </programlistingco> + + </sect2> + + <sect2 id="mapping-types-anymapping" revision="2"> + <title>any</title> + + <para> + Existe mais um tipo de propriedade de mapeamento. O elemento de mapeamento + <literal>&lt;any&gt;</literal> define uma associação polimórfica para classes de múltiplas tabelas. + Este tipo de mapeamento sempre requer mais de uma coluna. A primeira coluna possui o tipo da entidade + associada. A outra coluna que ficou possui o identificador. É impossível especificar uma restrição + de chave estrangeira para este tipo de associação, assim isto claramente não é visto + como um caminho usual para associações (polimórficas) de mapeamento. Você deve usar este mapeamento + apenas em casos muito especiais (exemplo: audit logs, dados de sessão do usuário, etc). + + </para> + + <para> + O atributo <literal>meta-type</literal> permite a aplicação especificar um tipo adaptado + que mapeia valores de colunas de banco de dados para classes persistentes que tem propriedades + identificadoras do tipo especificado através do <literal>id-type</literal>. Você deve especificar + o mapeamento de valores do meta-type para nome de classes. + </para> + + <programlisting><![CDATA[<any name="being" id-type="long" meta-type="string"> + <meta-value value="TBL_ANIMAL" class="Animal"/> + <meta-value value="TBL_HUMAN" class="Human"/> + <meta-value value="TBL_ALIEN" class="Alien"/> + <column name="table_name"/> + <column name="id"/> +</any>]]></programlisting> + + <programlistingco> + <areaspec> + <area id="any1" coords="2 50"/> + <area id="any2" coords="3 50"/> + <area id="any3" coords="4 50"/> + <area id="any4" coords="5 50"/> + <area id="any5" coords="6 50"/> + <area id="any6" coords="7 50"/> + </areaspec> + <programlisting><![CDATA[<any + name="propertyName" + id-type="idtypename" + meta-type="metatypename" + cascade="cascade_style" + access="field|property|ClassName" + optimistic-lock="true|false" +> + <meta-value ... /> + <meta-value ... /> + ..... + <column .... /> + <column .... /> + ..... +</any>]]></programlisting> + <calloutlist> + <callout arearefs="any1"> + <para> + <literal>name</literal>: o nome da propriedade. + </para> + </callout> + <callout arearefs="any2"> + <para> + <literal>id-type</literal>: o tipo identificador. + </para> + </callout> + <callout arearefs="any3"> + <para> + <literal>meta-type</literal> (opcional – valor default <literal>string</literal>): + Qualquer tipo que é permitido para um mapeamento discriminador. + </para> + </callout> + <callout arearefs="any4"> + <para> + <literal>cascade</literal> (opcional – valor default <literal>none</literal>): + o estilo do cascade. + </para> + </callout> + <callout arearefs="any5"> + <para> + <literal>access</literal> (opcional – valor default <literal>property</literal>): + A estratégia que o hibernate deve usar para acessar o valor da propriedade. + </para> + </callout> + <callout arearefs="any6"> + <para> + <literal>optimistic-lock</literal> (opcional - valor default<literal>true</literal>): + Especifica que as atualizações para esta propriedade requerem ou não aquisição da + trava otimista. Em outras palavras, define se uma versão de incremento deve ocorrer + se esta propriedade está modificada. + </para> + </callout> + </calloutlist> + </programlistingco> + + </sect2> + + </sect1> + + <sect1 id="mapping-types"> + <title>Tipos do Hibernate</title> + + <sect2 id="mapping-types-entitiesvalues" revision="1"> + <title>Entidades e valores</title> + + <para> + Para entender o comportamento de vários objetos em nível de linguagem de Java a + respeito do serviço de persistência, nós precisamos classificá-los em dois grupos. + </para> + + <para> + Uma <emphasis>entidade </emphasis> existe independentemente de qualquer outro + objeto guardando referências para a entidade. Em contraste com o modelo usual de + Java que um objeto não referenciado é coletado pelo garbage collector. Entidades + devem ser explicitamente salvas ou deletada (exceto em operações de salvamento + ou deleção que possam ser executada em <emphasis>cascata</emphasis> de uma entidade + pai para seus filhos). Isto é diferente do modelo ODMG de persistência do objeto + por acessibilidade – e corresponde quase a como objetos de aplicações são + geralmente usados em grandes sistemas. Entidades suportam referências circulares + e comuns. Eles podem ser versionadas. + </para> + + <para> + Uma entidade em estado persistente consiste de referências para outras entidades + e instâncias de tipos de <emphasis>valor</emphasis>. Valores são primitivos, + coleções (não o que tem dentro de uma coleção), componentes e certos objetos + imutáveis. Entidades distintas, valores (em coleções e componentes particulares) + <emphasis>são </emphasis> persistidos e apagados por acessibilidade. Visto que + objetos value (e primitivos) são persistidos e apagados junto com as entidades + que os contém e não podem ser versionados independentemente. Valores têm + identidade não independente, assim eles não podem ser comuns para duas + entidades ou coleções. + + </para> + + <para> + Até agora, nós estivemos usando o termo "classe persistente" para referir + a entidades. Nós iremos continuar a fazer isto. Falando a rigor, porém, nem todas + as classes definidas pelo usuário com estados persistentes são entidades. Um + <emphasis>componente</emphasis> é uma classe de usuário definida com valores + semânticos. Uma propriedade de Java de tipo <literal>java.lang.String</literal> + também tem um valor semêntico. Dada esta definição, nós podemos dizer que + todos os tipos (classes) fornecida pelo JDK tem tipo de valor semântico em Java, + enquanto que tipos definidos pelo usuário pode ser mapeados com entidade ou valor + de tipo semântico. Esta decisão pertence ao desenvolvedor da aplicação. Uma boa + dica para uma classe entidade em um modelo de domínio são referências comuns + para uma instância simples daquela classe, enquanto a composição ou agregação + geralmente se traduz para um valor de tipo. + </para> + + <para> + Nós iremos rever ambos os conceitos durante toda a documentação. + + </para> + + <para> + O desafio pe mapear o sistema de tipo de Java (e a definição do desenvolvedor de + entidades e tipos de valor) para o sistema de tipo SQL/banco de dados. A ponte entre ambos + os sistemas é fornecido pelo Hibernate: para entidades que usam + <literal>&lt;class&gt;</literal>, <literal>&lt;subclass&gt;</literal> e assim por diante. + Para tipos de valores nós usamos <literal>&lt;property&gt;</literal>, + <literal>&lt;component&gt;</literal>, etc, geralmente com um atributo + <literal>type</literal>. O valor deste atributo é o nome de um <emphasis>tipo de + mapeamento</emphasis> do Hibernate. O Hibernate fornece muitos mapeamentos + (para tipos de valores do JDK padrão) ut of the box. Você pode escrever os seus + próprios tipos de mapeamentos e implementar sua estratégia de conversão adaptada, + como você verá adiante. + </para> + + <para> + Todos os tipos internos do hibernate exceto coleções suportam semânticas nulas. + + </para> + + </sect2> + + <sect2 id="mapping-types-basictypes" revision="3"> + <title>Valores de tipos básicos</title> + + <para> + O tipos internos de mapeamentos básicos podem ser a grosso modo categorizado como: + <variablelist> + <varlistentry> + <term><literal>integer, long, short, float, double, character, byte, + boolean, yes_no, true_false</literal></term> + <listitem> + <para> + Tipos de mapeamentos de classes primitivas ou wrapper Java especificos + (vendor-specific) para tipos de coluna SQL. Boolean, + <literal>boolean, yes_no</literal> são todas codificações alternativas + para um <literal>boolean</literal> ou <literal>java.lang.Boolean</literal> + do Java. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>string</literal></term> + <listitem> + <para> + Um tipo de mapeamento de <literal>java.lang.String</literal> para + <literal>VARCHAR</literal> (ou <literal>VARCHAR2</literal> no Oracle). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>date, time, timestamp</literal></term> + <listitem> + <para> + Tipos de mapeamento de <literal>java.util.Date</literal> e suas + subclasses para os tipos SQL <literal>DATE</literal>, + <literal>TIME</literal> e <literal>TIMESTAMP</literal> + (ou equivalente). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>calendar, calendar_date</literal></term> + <listitem> + <para> + Tipo de mapeamento de <literal>java.util.Calendar</literal> para + os tipos SQL <literal>TIMESTAMP</literal> e + <literal>DATE</literal> (ou equivalente). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>big_decimal, big_integer</literal></term> + <listitem> + <para> + Tipo de mapeamento de <literal>java.math.BigDecimal</literal> and + <literal>java.math.BigInteger</literal> para <literal>NUMERIC</literal> + (ou <literal>NUMBER</literal> no Oracle). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>locale, timezone, currency</literal></term> + <listitem> + <para> + Tipos de mapeamentos de <literal>java.util.Locale</literal>, + <literal>java.util.TimeZone</literal> e <literal>java.util.Currency</literal> + para <literal>VARCHAR</literal> (ou <literal>VARCHAR2</literal> no Oracle). + Instâncias de f <literal>Locale</literal> e <literal>Currency</literal> + são mapeados para seus códigos ISO. Instâncias de <literal>TimeZone</literal> + são mapeados para seu <literal>ID</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>class</literal></term> + <listitem> + <para> + um tipo de mapeamento de <literal>java.lang.Class</literal> para + <literal>VARCHAR</literal> (ou <literal>VARCHAR2</literal> no + Oracle). Uma <literal>Class</literal> é mapeada pelo + seu nome qualificado (completo). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>binary</literal></term> + <listitem> + <para> + Mapeia arrays de bytes para um tipo binário de SQL apropriado. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>text</literal></term> + <listitem> + <para> + Maps long Java strings to a SQL <literal>CLOB</literal> or + <literal>TEXT</literal> type. + Mapeia strings longas de Java para um tipo SQL + <literal>CLOB</literal> ou <literal>TEXT</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>serializable</literal></term> + <listitem> + <para> + Mapeia tipos Java serializáveis para um tipo binário SQL apropriado. + Você pode também indicar o tipo <literal>serializable</literal> do + Hibernate com o nome da classe ou interface Java serializável que + não é padrão para um tipo básico. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>clob, blob</literal></term> + <listitem> + <para> + Tipos de mapeamentos para as classes JDBC <literal>java.sql.Clob</literal> and + <literal>java.sql.Blob</literal>. Estes tipos podem ser inconveniente para + algumas aplicações, visto que o objeto blob ou clob pode não ser reusado + fora de uma transação. (Além disso, o suporte de driver é imcompleto e + inconsistente.) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>imm_date, imm_time, imm_timestamp, imm_calendar, imm_calendar_date, + imm_serializable, imm_binary</literal> + </term> + <listitem> + <para> + Mapeando tipos para o que geralmente são consideradas tipos mutáveis de + Java, onde o Hibernate faz determinadas otimizações apropriadas somente + para tipos imutáveis de Java, e a aplicação trata o objeto como imutável. + Por exemplo, você não deve chamar <literal>Date.setTime()</literal> para + uma instância mapeada como <literal>imm_timestamp</literal>. Para mudar + o valor da propriedade, e ter a mudança feita persistente, a aplicação + deve atribuir um novo objeto (nonidentical) à propriedade. + </para> + </listitem> + </varlistentry> + </variablelist> + + </para> + + <para> + Identificadores únicos das entidades e coleções podem ser de qualquer tipo + básico exceto <literal>binary</literal>, <literal>blob</literal> ou + <literal>clob</literal>. (Identificadores compostos também são permitidos, + veja abaixo.) + </para> + + <para> + Os tipos de valores básicos têm suas constantes <literal>Type</literal> + correspondentes definidas em <literal>org.hibernate.Hibernate</literal>. Por exemplo, + <literal>Hibernate.STRING</literal> representa o tipo <literal>string</literal>. + </para> + + </sect2> + + <sect2 id="mapping-types-custom" revision="2"> + <title>Tipos de valores personalizados</title> + + <para> + É relativamente fácil para desenvolvedores criar seus próprios tipos de valor. + Por exemplo, você pode querer persistir propriedades do tipo + <literal>java.lang.BigInteger</literal> para colunas <literal>VARCHAR</literal>. O + Hibernate não fornece um tipo correspondente para isso. Mas os tipos adaptados + não são limitados a mapeamento de uma propriedade (ou elemento de coleção) a uma + única coluna da tabela. Assim, por exemplo, você pôde ter uma propriedade Java + <literal>getName()</literal>/<literal>setName()</literal> do tipo + <literal>java.lang.String</literal> que é persistido para colunas + <literal>FIRST_NAME</literal>, <literal>INITIAL</literal>, <literal>SURNAME</literal>. + + </para> + + <para> + Para implementar um tipo personalizado, implemente <literal>org.hibernate.UserType</literal> + or <literal>org.hibernate.CompositeUserType</literal> e declare propriedades usando o nome + qualificado da classe do tipo. Veja <literal>org.hibernate.test.DoubleStringType</literal> + para ver o tipo das coisas que são possíveis. + </para> + + <programlisting><![CDATA[<property name="twoStrings" type="org.hibernate.test.DoubleStringType"> + <column name="first_string"/> + <column name="second_string"/> +</property>]]></programlisting> + + <para> + Observe o uso da tag <literal>&lt;column&gt;</literal> para mapear uma propriedade + para colunas múltiplas. + </para> + + <para> + As interfaces <literal>CompositeUserType</literal>, <literal>EnhancedUserType</literal>, + <literal>UserCollectionType</literal>, e <literal>UserVersionType</literal> + fornecem suporte para usos mais especializados. + </para> + + <para> + Você pode mesmo fornecer parâmetros a um <literal>UserType</literal> no arquivo de mapeamento. + Para isto, seu <literal>UserType</literal> deve implementar a interface + <literal>org.hibernate.usertype.ParameterizedType</literal>. Para fornecer parâmetros a seu + tipo personalizado, você pode usar o elemento <literal>&lt;type&gt;</literal> em seus + arquivos de mapeamento. + </para> + + <programlisting><![CDATA[<property name="priority"> + <type name="com.mycompany.usertypes.DefaultValueIntegerType"> + <param name="default">0</param> + </type> +</property>]]></programlisting> + + <para> + O <literal>UserType</literal> pode agora recuperar o valor para o parâmetro chamado + <literal>default</literal> da <literal>Propriedade</literal> do passado a ele. + </para> + + <para> + Se você usar freqüentemente um determinado <literal>UserType</literal>, pode ser útil definir + um nome mais curto para ele. Você pode fazer isto usando o elemento + <literal>&lt;typedef&gt;</literal>. Typedefs atribui um nome a um tipo personalizado, e pode também + conter uma lista de valores default de parâmetro se o tipo for parametrizado. + </para> + + <programlisting><![CDATA[<typedef class="com.mycompany.usertypes.DefaultValueIntegerType" name="default_zero"> + <param name="default">0</param> +</typedef>]]></programlisting> + + <programlisting><![CDATA[<property name="priority" type="default_zero"/>]]></programlisting> + + <para> + It is also possible to override the parameters supplied in a typedef on a case-by-case basis + by using type parameters on the property mapping. + </para> + + <para> + Even though Hibernate's rich range of built-in types and support for components means you + will very rarely <emphasis>need</emphasis> to use a custom type, it is nevertheless + considered good form to use custom types for (non-entity) classes that occur frequently + in your application. For example, a <literal>MonetaryAmount</literal> class is a good + candidate for a <literal>CompositeUserType</literal>, even though it could easily be mapped + as a component. One motivation for this is abstraction. With a custom type, your mapping + documents would be future-proofed against possible changes in your way of representing + monetary values. + </para> + + </sect2> + + </sect1> + + <sect1 id="mapping-entityname"> + <title>Mapping a class more than once</title> + <para> + It is possible to provide more than one mapping for a particular persistent class. In this + case you must specify an <emphasis>entity name</emphasis> do disambiguate between instances + of the two mapped entities. (By default, the entity name is the same as the class name.) + Hibernate lets you specify the entity name when working with persistent objects, when writing + queries, or when mapping associations to the named entity. + </para> + + <programlisting><![CDATA[<class name="Contract" table="Contracts" + entity-name="CurrentContract"> + ... + <set name="history" inverse="true" + order-by="effectiveEndDate desc"> + <key column="currentContractId"/> + <one-to-many entity-name="HistoricalContract"/> + </set> +</class> + +<class name="Contract" table="ContractHistory" + entity-name="HistoricalContract"> + ... + <many-to-one name="currentContract" + column="currentContractId" + entity-name="CurrentContract"/> +</class>]]></programlisting> + + <para> + Notice how associations are now specified using <literal>entity-name</literal> instead of + <literal>class</literal>. + </para> + + </sect1> + + <sect1 id="mapping-quotedidentifiers"> + <title>SQL quoted identifiers</title> + <para> + You may force Hibernate to quote an identifier in the generated SQL by enclosing the table or + column name in backticks in the mapping document. Hibernate will use the correct quotation + style for the SQL <literal>Dialect</literal> (usually double quotes, but brackets for SQL + Server and backticks for MySQL). + </para> + + <programlisting><![CDATA[<class name="LineItem" table="`Line Item`"> + <id name="id" column="`Item Id`"/><generator class="assigned"/></id> + <property name="itemNumber" column="`Item #`"/> + ... +</class>]]></programlisting> + + </sect1> + + + <sect1 id="mapping-alternatives"> + <title>Metadata alternatives</title> + + <para> + XML isn't for everyone, and so there are some alternative ways to define O/R mapping metadata in Hibernate. + </para> + + <sect2 id="mapping-xdoclet"> + <title>Using XDoclet markup</title> + + <para> + Many Hibernate users prefer to embed mapping information directly in sourcecode using + XDoclet <literal&gt;(a)hibernate.tags&lt;/literal&gt;. We will not cover this approach in this + document, since strictly it is considered part of XDoclet. However, we include the + following example of the <literal>Cat</literal> class with XDoclet mappings. + </para> + + <programlisting><![CDATA[package eg; +import java.util.Set; +import java.util.Date; + +/** + * @hibernate.class + * table="CATS" + */ +public class Cat { + private Long id; // identifier + private Date birthdate; + private Cat mother; + private Set kittens + private Color color; + private char sex; + private float weight; + + /* + * @hibernate.id + * generator-class="native" + * column="CAT_ID" + */ + public Long getId() { + return id; + } + private void setId(Long id) { + this.id=id; + } + + /** + * @hibernate.many-to-one + * column="PARENT_ID" + */ + public Cat getMother() { + return mother; + } + void setMother(Cat mother) { + this.mother = mother; + } + + /** + * @hibernate.property + * column="BIRTH_DATE" + */ + public Date getBirthdate() { + return birthdate; + } + void setBirthdate(Date date) { + birthdate = date; + } + /** + * @hibernate.property + * column="WEIGHT" + */ + public float getWeight() { + return weight; + } + void setWeight(float weight) { + this.weight = weight; + } + + /** + * @hibernate.property + * column="COLOR" + * not-null="true" + */ + public Color getColor() { + return color; + } + void setColor(Color color) { + this.color = color; + } + /** + * @hibernate.set + * inverse="true" + * order-by="BIRTH_DATE" + * @hibernate.collection-key + * column="PARENT_ID" + * @hibernate.collection-one-to-many + */ + public Set getKittens() { + return kittens; + } + void setKittens(Set kittens) { + this.kittens = kittens; + } + // addKitten not needed by Hibernate + public void addKitten(Cat kitten) { + kittens.add(kitten); + } + + /** + * @hibernate.property + * column="SEX" + * not-null="true" + * update="false" + */ + public char getSex() { + return sex; + } + void setSex(char sex) { + this.sex=sex; + } +}]]></programlisting> + + <para> + See the Hibernate web site for more examples of XDoclet and Hibernate. + </para> + + </sect2> + + <sect2 id="mapping-annotations" revision="2"> + <title>Using JDK 5.0 Annotations</title> + + <para> + JDK 5.0 introduced XDoclet-style annotations at the language level, type-safe and + checked at compile time. This mechnism is more powerful than XDoclet annotations and + better supported by tools and IDEs. IntelliJ IDEA, for example, supports auto-completion + and syntax highlighting of JDK 5.0 annotations. The new revision of the EJB specification + (JSR-220) uses JDK 5.0 annotations as the primary metadata mechanism for entity beans. + Hibernate3 implements the <literal>EntityManager</literal> of JSR-220 (the persistence API), + support for mapping metadata is available via the <emphasis>Hibernate Annotations</emphasis> + package, as a separate download. Both EJB3 (JSR-220) and Hibernate3 metadata is supported. + </para> + + <para> + This is an example of a POJO class annotated as an EJB entity bean: + </para> + + <programlisting><![CDATA[@Entity(access = AccessType.FIELD) +public class Customer implements Serializable { + + @Id; + Long id; + + String firstName; + String lastName; + Date birthday; + + @Transient + Integer age; + + @Embedded + private Address homeAddress; + + @OneToMany(cascade=CascadeType.ALL) + @JoinColumn(name="CUSTOMER_ID") + Set<Order> orders; + + // Getter/setter and business methods +}]]></programlisting> + + <para> + Note that support for JDK 5.0 Annotations (and JSR-220) is still work in progress and + not completed. Please refer to the Hibernate Annotations module for more details. + </para> + + </sect2> + </sect1> + + <sect1 id="mapping-generated" revision="1"> + <title>Generated Properties</title> + <para> + Generated properties are properties which have their values generated by the + database. Typically, Hibernate applications needed to <literal>refresh</literal> + objects which contain any properties for which the database was generating values. + Marking properties as generated, however, lets the application delegate this + responsibility to Hibernate. Essentially, whenever Hibernate issues an SQL INSERT + or UPDATE for an entity which has defined generated properties, it immediately + issues a select afterwards to retrieve the generated values. + </para> + <para> + Properties marked as generated must additionally be non-insertable and non-updateable. + Only <xref linkend="mapping-declaration-version">versions</xref>, + <xref linkend="mapping-declaration-timestamp">timestamps</xref>, and + <xref linkend="mapping-declaration-property">simple properties</xref> can be marked as + generated. + </para> + <para> + <literal>never</literal> (the default) - means that the given property value + is not generated within the database. + </para> + <para> + <literal>insert</literal> - states that the given property value is generated on + insert, but is not regenerated on subsequent updates. Things like created-date would + fall into this category. Note that even thought + <xref linkend="mapping-declaration-version">version</xref> and + <xref linkend="mapping-declaration-timestamp">timestamp</xref> properties can + be marked as generated, this option is not available there... + </para> + <para> + <literal>always</literal> - states that the property value is generated both + on insert and on update. + </para> + </sect1> + + <sect1 id="mapping-database-object"> + <title>Auxiliary Database Objects</title> + <para> + Allows CREATE and DROP of arbitrary database objects, in conjunction with + Hibernate's schema evolution tools, to provide the ability to fully define + a user schema within the Hibernate mapping files. Although designed specifically + for creating and dropping things like triggers or stored procedures, really any + SQL command that can be run via a <literal>java.sql.Statement.execute()</literal> + method is valid here (ALTERs, INSERTS, etc). There are essentially two modes for + defining auxiliary database objects... + </para> + <para> + The first mode is to explicitly list the CREATE and DROP commands out in the mapping + file: + </para> + <programlisting><![CDATA[<hibernate-mapping> + ... + <database-object> + <create>CREATE TRIGGER my_trigger ...</create> + <drop>DROP TRIGGER my_trigger</drop> + </database-object> +</hibernate-mapping>]]></programlisting> + <para> + The second mode is to supply a custom class which knows how to construct the + CREATE and DROP commands. This custom class must implement the + <literal>org.hibernate.mapping.AuxiliaryDatabaseObject</literal> interface. + </para> + <programlisting><![CDATA[<hibernate-mapping> + ... + <database-object> + <definition class="MyTriggerDefinition"/> + </database-object> +</hibernate-mapping>]]></programlisting> + <para> + Additionally, these database objects can be optionally scoped such that they only + apply when certain dialects are used. + </para> + <programlisting><![CDATA[<hibernate-mapping> + ... + <database-object> + <definition class="MyTriggerDefinition"/> + <dialect-scope name="org.hibernate.dialect.Oracle9Dialect"/> + <dialect-scope name="org.hibernate.dialect.OracleDialect"/> + </database-object> +</hibernate-mapping>]]></programlisting> + </sect1> +</chapter> + Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/batch.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/batch.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/batch.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/batch.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,357 @@ +<chapter id="batch"> + <title>Processamento de lotes</title> + + <para> + Uma alternativa para inserir 100.000 linhas no banco de dados usando o Hibernate + pode ser a seguinte: + </para> + +<programlisting><![CDATA[Session session = sessionFactory.openSession(); +Transaction tx = session.beginTransaction(); +for ( int i=0; i<100000; i++ ) { + Customer customer = new Customer(.....); + session.save(customer); +} +tx.commit(); +session.close();]]></programlisting> + + <para> + Isto irá falhar em algum lugar próximo a linha 50.000, lançando uma + <literal>OutOfMemoryException</literal>. Isso ocorre devido ao fato do Hibernate + fazer cache de todas as instâncias de <literal>Customer</literal> inseridas num + cachê em nível de sessão. + </para> + + <para> + Neste capítulo veremos como contornar esse problema. Entretanto, se você vai realizar + processamento de lotes, é muito importante que você habilite o uso de lotes JDBC, se + você pretende obter um desempenho razoável. Defina o tamanho do lote JDBC em um + valor razoável (algo entre 10-50): + </para> + +<programlisting><![CDATA[hibernate.jdbc.batch_size 20]]></programlisting> + + <para> + Você também pode querer rodar esse tipo de processamento de lotes com o cache + secundário completamente desabilitado: + </para> + +<programlisting><![CDATA[hibernate.cache.use_second_level_cache false]]></programlisting> + + <para> + Mas isto não é absolutamente necessário, desde que nós possamos ajustar o + <literal>CacheMode</literal> para desabilitar a interação com o cache secundário. + </para> + + <sect1 id="batch-inserts"> + <title>Inserção de lotes</title> + + <para> + Quando você estiver inserindo novos objetos persistentes, vocês deve executar + os métodos <literal>flush()</literal> e <literal>clear()</literal> regularmente + na sessão, para controlar o tamanho do cache primário. + </para> + +<programlisting><![CDATA[Session session = sessionFactory.openSession(); +Transaction tx = session.beginTransaction(); + +for ( int i=0; i<100000; i++ ) { + Customer customer = new Customer(.....); + session.save(customer); + if ( i % 20 == 0 ) { //20, same as the JDBC batch size + //flush a batch of inserts and release memory: + session.flush(); + session.clear(); + } +} + +tx.commit(); +session.close();]]></programlisting> + + </sect1> + + <sect1 id="batch-update" > + <title>Batch updates</title> + + <para> + Para recuperar e atualizar informações a mesma idéia é válida. Adicionalmente, + pode precisar usar o <literal>scroll()</literal> para usar recursos no lado + do servidor em queries que retornam muita informação. + </para> + +<programlisting><![CDATA[Session session = sessionFactory.openSession(); +Transaction tx = session.beginTransaction(); + +ScrollableResults customers = session.getNamedQuery("GetCustomers") + .setCacheMode(CacheMode.IGNORE) + .scroll(ScrollMode.FORWARD_ONLY); +int count=0; +while ( customers.next() ) { + Customer customer = (Customer) customers.get(0); + customer.updateStuff(...); + if ( ++count % 20 == 0 ) { + //flush a batch of updates and release memory: + session.flush(); + session.clear(); + } +} + +tx.commit(); +session.close();]]></programlisting> + + </sect1> + + <sect1 id="batch-statelesssession"> + <title>A interface StatelessSession</title> + <para> + Alternativamente, o Hibernate provê uma API orientada à comandos, usada para + transmitir um fluxo de dados de e para o banco de dados na forma de objetos soltos. + Uma <literal>StatelessSession</literal> não tem um contexto persistente associado e + não fornece muito das semânticas de alto nível para controle do ciclo de vida. + Em especial, uma StatelessSession não implemente o cache primário e nem interage + com o cache secundário ou query cache. Ele não implementa salvamento transacional + automatico ou checagem automática de mudanças. Operação realizadas usando uma + StatelessSession não fazem nenhum tipo de cascade com as instancias associadas. + As coleções são ignoradas por uma StatelessSession. Operações realizadas com um + StatelessSession ignoram a arquitetura de eventos e os interceptadores. + StatelessSession são vulneráveis aos efeitos do aliasing dos dados, devido a + falta do cache primário. Uma StatelessSession é uma abstração de baixo nível, + muito mais próxima do JDBC. + </para> + +<programlisting><![CDATA[StatelessSession session = sessionFactory.openStatelessSession(); +Transaction tx = session.beginTransaction(); + +ScrollableResults customers = session.getNamedQuery("GetCustomers") + .scroll(ScrollMode.FORWARD_ONLY); +while ( customers.next() ) { + Customer customer = (Customer) customers.get(0); + customer.updateStuff(...); + session.update(customer); +} + +tx.commit(); +session.close();]]></programlisting> + + <para> + Veja neste exempo, as instancias de <literal>Customer</literal> retornadas pela query + são imediatamente desvinculadas. Elas nunca serão assossiadas à um contexto persistente. + </para> + + <para> + As operações <literal>insert(), update()</literal> e <literal>delete()</literal> + definidos pela interface <literal>StatelessSession</literal> são considerados + operações diretas no banco de dados (row-level operations), isso resulta em uma + execução imediata de comandos SQL <literal>INSERT, UPDATE</literal> ou + <literal>DELETE</literal> respectivamente. Devido a isso, eles possuem uma + semântica bem diferente das operações <literal>save(), saveOrUpdate()</literal> + ou <literal>delete()</literal> definidas na interface <literal>Session</literal>. + </para> + + </sect1> + + <sect1 id="batch-direct" revision="3"> + <title>Operações no estilo DML</title> + + <para> + Como já discutido, mapeamento objeto/relacional automático e transparente é conseguido + com a gerência do estado do objeto. Com isto o estado daquele objeto fica disponível na + memória, manipulando(usando as expressões SQL <literal>Data Manipulation Language</literal> + (SQL-style DML): <literal>INSERT</literal>, <literal>UPDATE</literal>, <literal>DELETE</literal>) + os dados diretamente no banco de dados não irá afetar o estado registrado em memória. + Entretanto, o Hibernate provê métodos para executar queries SQL-style DML, que são + totalmente executas com HQL (Hibernate Query Language) + (<xref linkend="queryhql">HQL</xref>). + </para> + + <para> + A pseudo-sintaxe para expressões <literal>UPDATE</literal> e <literal>DELETE</literal> é: + <literal>( UPDATE | DELETE ) FROM? NomeEntidade (WHERE condições_where)?</literal>. + Algumas observações: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + Na clausula from, a palavra chave FROM é opcional; + </para> + </listitem> + <listitem> + <para> + Somente uma entidade pode ser chamada na clausula from; opcionalmente pode ter + um alias. Se o nome da entidade for possuir um alias, então qualquer propriedade + referenciada deve usar esse alias qualificado; se o nome da entidade não possuir + um alias, então nenhuma das propriedade precisa usar o acesso qualificado. + </para> + </listitem> + <listitem> + <para> + Na <xref linkend="queryhql-joins-forms">joins</xref> (ambas implícita ou explicita) + pode ser especificada em um bulk HQL query. Sub-queries podem ser usadas na clausula + where; as subqueries podem conter joins. + </para> + </listitem> + <listitem> + <para> + A clausula where também é opcional. + </para> + </listitem> + </itemizedlist> + + <para> + Como exemplo para executar um HQL <literal>UPDATE</literal>, use o + método <literal>Query.executeUpdate()</literal>(o método ganhou o nome + devido a sua familiaridade com o do JDBC + <literal>PreparedStatement.executeUpdate()</literal>): + </para> + +<programlisting><![CDATA[Session session = sessionFactory.openSession(); +Transaction tx = session.beginTransaction(); + +String hqlUpdate = "update Customer c set c.name = :newName where c.name = :oldName"; +// or String hqlUpdate = "update Customer set name = :newName where name = :oldName"; +int updatedEntities = s.createQuery( hqlUpdate ) + .setString( "newName", newName ) + .setString( "oldName", oldName ) + .executeUpdate(); +tx.commit(); +session.close();]]></programlisting> + + <para> + HQL <literal>UPDATE</literal> statements, by default do not effect the + <xref linkend="mapping-declaration-version">version</xref> + or the <xref linkend="mapping-declaration-timestamp">timestamp</xref> property values + for the affected entities; this is in keeping with the EJB3 specification. However, + you can force Hibernate to properly reset the <literal>version</literal> or + <literal>timestamp</literal> property values through the use of a <literal>versioned update</literal>. + This is achieved by adding the <literal>VERSIONED</literal> keyword after the <literal>UPDATE</literal> + keyword. + + </para> +<programlisting><![CDATA[Session session = sessionFactory.openSession(); +Transaction tx = session.beginTransaction(); +String hqlVersionedUpdate = "update versioned Customer set name = :newName where name = :oldName"; +int updatedEntities = s.createQuery( hqlUpdate ) + .setString( "newName", newName ) + .setString( "oldName", oldName ) + .executeUpdate(); +tx.commit(); +session.close();]]></programlisting> + + <para> + Note that custom version types (<literal>org.hibernate.usertype.UserVersionType</literal>) + are not allowed in conjunction with a <literal>update versioned</literal> statement. + </para> + + <para> + + Para executar um HQL <literal>DELETE</literal>, use o mesmo método + <literal>Query.executeUpdate()</literal>: + </para> + +<programlisting><![CDATA[Session session = sessionFactory.openSession(); +Transaction tx = session.beginTransaction(); + +String hqlDelete = "delete Customer c where c.name = :oldName"; +// or String hqlDelete = "delete Customer where name = :oldName"; +int deletedEntities = s.createQuery( hqlDelete ) + .setString( "oldName", oldName ) + .executeUpdate(); +tx.commit(); +session.close();]]></programlisting> + + <para> + O valor <literal>int</literal> retornado pelo método <literal>Query.executeUpdate()</literal> + indica o numero de entidade afetadas pela operação. Lembre-se que isso pode estar ou não + relacionado ao número de linhas alteradas no banco de dados. Uma operação bulk HQL pode resultar + em várias expressões SQL reais a serem executadas, por exemplo, no caso de joined-subclass. + O número retornado indica a quantidade real de entidades afetadas pela expressão. Voltando + ao exemplo da joined-subclass, a exclusão de uma das subclasses pode resultar numa + exclusão em outra tabelas, não apenas na tabela para qual a subclasses está mapeada, mas + também tabela "root" e possivelmente nas tabelas joined-subclass num nível hierárquico + imediatamente abaixo. + </para> + + <para> + + A pseudo-sintaxe para o comando <literal>INSERT</literal> é: + <literal>INSERT INTO EntityName properties_list select_statement</literal>. Alguns + pontos a observar: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + Apenas a forma INSERT INTO ... SELECT ... é suportada; INSERT INTO ... VALUES ... + não é suportada. + </para> + <para> + A lista de propriedade é análoga à <literal>especificação da coluna</literal> + do comando SQL <literal>INSERT</literal>. Para entidades envolvidas em mapeamentos, + apenas a propriedades definidas diretamente a nível da classe podem ser usandas na + properties_list. Propriedades da superclass não são permitidas; e as propriedades + da subclasse não faz sentido. Em outras palavras, os comandos + <literal>INSERT</literal> não são polimorficos. + </para> + </listitem> + <listitem> + <para> + O camando select pode ser qualquer query HQL válida, que tenha um retorno compatível + com o tipo com o esperado pela inclusão. Atualmente, isto é verificado durante a compilação + da query, isto é melhor do que permitir que a verificação chegue ao banco de dados. + Entretanto perceba que isso pode causar problemas entre os <literal>Tipo</literal> do Hibernate + que são <emphasis>equivalentes</emphasis> em oposição a <emphasis>equal</emphasis>. + Isso pode causar problemas nas combinações entre a propriedade definida como + <literal>org.hibernate.type.DateType</literal>e um propriedade definida como + <literal>org.hibernate.type.TimestampType</literal>, embora o banco de dados não possa + fazer uma distinção ou possa ser capaz de manusear a conversão. + </para> + </listitem> + <listitem> + <para> + Para a propriedade id, a expressão insert oferece duas opções. Você pode especificar + qualquer propriedade id explicitamente no properties_list (em alguns casos esse valor + é obtido diretamente da expressão select) ou pode omitir do properties_list (nesse caso, + um valor gerado é usado). Essa ultima opção só é válida quando são usados geradores de ids + que operam no banco de dados; a tentativa de usar essa opção com geradores do tipo + "em memória" vai causar um exceção durante a etapa de parser. Veja a finalidades desta + discussão, os seguintes geradores operam com o banco de dados + <literal>org.hibernate.id.SequenceGenerator</literal> (e suas subclasses) + e qualquer implementação de <literal>org.hibernate.id.PostInsertIdentifierGenerator</literal>. + Aqui, a exceção mais notável é o <literal>org.hibernate.id.TableHiLoGenerator</literal>, que + não pode ser usado porque ele não dispõe de mecanismos para recuperar o seu valor. + </para> + </listitem> + <listitem> + <para> + For properties mapped as either <literal>version</literal> or <literal>timestamp</literal>, + the insert statement gives you two options. You can either specify the property in the + properties_list (in which case its value is taken from the corresponding select expressions) + or omit it from the properties_list (in which case the <literal>seed value</literal> defined + by the <literal>org.hibernate.type.VersionType</literal> is used). + + Para propriedades mapeadas como <literal>version</literal> ou <literal>timestamp</literal>, + a expressão insert oferece a você duas opções. Você pode especificar a propriedade na + properties_list (nesse caso o seu valor é obtido a partir da expressão select correspondente) + ou ele pode ser omitido da properties_list (neste caso o usa o <literal>valor semente</literal> + definido pela classe <literal>org.hibernate.type.VersionType</literal>). + </para> + </listitem> + </itemizedlist> + + <para> + Exemplo da execução de um HQL <literal>INSERT</literal>: + </para> + +<programlisting><![CDATA[Session session = sessionFactory.openSession(); +Transaction tx = session.beginTransaction(); + +String hqlInsert = "insert into DelinquentAccount (id, name) select c.id, c.name from Customer c where ..."; +int createdEntities = s.createQuery( hqlInsert ) + .executeUpdate(); +tx.commit(); +session.close();]]></programlisting> + + </sect1> + +</chapter> Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/best_practices.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/best_practices.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/best_practices.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/best_practices.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,225 @@ +<chapter id="best-practices" revision="3"> + <title>Boas práticas</title> + + <variablelist spacing="compact"> + <varlistentry> + <term>Escreva classes compactas e mapeie-as usando <literal>&lt;component&gt;</literal>.</term> + <listitem> + <para> + Use uma classe <literal>Endereco</literal> para encapsular <literal>rua</literal>, + <literal>bairro</literal>, <literal>estado</literal>, <literal>CEP</literal>. Isto promove + a reutilização de código e simplifica o refactoring. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Declare propriedades identificadoras em classes persistentes.</term> + <listitem> + <para> + O Hibernate constrói propriedades identificadoras opcionais. Existem todos os tipos + de razões que explicam porquê você deveria utilizá-las. Nós recomendamos que os + identificadores sejam 'sintéticos' (gerados, sem significado para o negocio). + + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Identifique chaves naturais.</term> + <listitem> + <para> + Identifique chaves naturais para todas as entidades, e mapeie-as usando + <literal>&lt;natural-id&gt;</literal>. Implemente <literal>equals()</literal> e + <literal>hashCode()</literal> para comparar as propriedades que compõem a chave natural. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Coloque cada classe de mapeamento em seu próprio arquivo.</term> + <listitem> + <para> + Não use um único código de mapeamento monolítico. Mapeie <literal>com.eg.Foo</literal> + no arquivo <literal>com/eg/Foo.hbm.xml</literal>. Isto promove particularmente o bom + senso no time de desenvolvimento. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Carregue os mapeamentos como recursos.</term> + <listitem> + <para> + Faça o deploy dos mapeamentos junto com as classes que eles mapeiam. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Considere externalizar as strings de consultas.</term> + <listitem> + <para> + Esta é uma boa prática se suas consultas chamam funções SQL que não sejam ANSI. + Externalizar as strings de consultas para mapear arquivos irão tornar a aplicação + mais portável. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Use bind variables.</term> + <listitem> + <para> + Assim como em JDBC, sempre substitua valores não constantes por "?". Nunca use a manipulação + de strings para concatenar valores não constantes em uma consulta! Até melhor, considere + usar parâmetros nomeados nas consultas. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Não gerencie suas conexões JDBC.</term> + <listitem> + <para> + O Hibernate permite que a aplicação gerencie conexões JDBC. Esta abordagem deve ser considerada + um último recurso. Se você não pode usar os provedores de conexão embutidos, considere fazer + sua implementação a partir de <literal>org.hibernate.connection.ConnectionProvider</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Considere usar tipos customizados.</term> + <listitem> + <para> + Suponha que você tenha um tipo Java, de alguma biblioteca, que precisa ser persistido mas não + provê os acessórios necessários para mapeá-lo como um componente. Você deve implementar + <literal>org.hibernate.UserType</literal>. Esta abordagem livra o código da aplicação de + implementar transformações de/para o tipo Hibernate. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> Use código manual JDBC nos gargalos.</term> + <listitem> + <para> + Nas áreas de desempenho crítico do sistema, alguns tipos de operações podem se beneficiar do + uso direto do JDBC. Mas por favor, espere até você <emphasis>saber </emphasis> se é um gargalo. + E não suponha que o uso direto do JDBC é necessariamente mais rápido. Se você precisar usar + diretamente o JDBC, vale a pena abrir uma <literal>Session</literal> do Hibernate e usar uma + conexão JDBC. De modo que você possa ainda usar a mesma estratégia de transação e ocultar + o provedor a conexão + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Entenda o <literal>Session</literal> flushing.</term> + <listitem> + <para> + De tempos em tempos a sessão sincroniza seu estado persistente com o banco de dados. O desempenho + será afetado se este processo ocorrer frequentemente. Você pode algumas vezes minimizar o fluxo + desnecessário desabilitando o fluxo automático ou até mesmo mudando a ordem das consultas e outras + operações em uma transação particular. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Em uma arquitetura de três camadas, considere o uso de objetos separados.</term> + <listitem> + <para> + When using a servlet / session bean architecture, you could pass persistent objects loaded in + the session bean to and from the servlet / JSP layer. Use a new session to service each request. + Use <literal>Session.merge()</literal> or <literal>Session.saveOrUpdate()</literal> to + synchronize objects with the database. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>In a two tiered architecture, consider using long persistence contexts.</term> + <listitem> + <para> + Database Transactions have to be as short as possible for best scalability. However, it is often + necessary to implement long running <emphasis>application transactions</emphasis>, a single + unit-of-work from the point of view of a user. An application transaction might span several + client request/response cycles. It is common to use detached objects to implement application + transactions. An alternative, extremely appropriate in two tiered architecture, is to maintain + a single open persistence contact (session) for the whole life cycle of the application transaction + and simply disconnect from the JDBC connection at the end of each request and reconnect at the + beginning of the subsequent request. Never share a single session across more than one application + transaction, or you will be working with stale data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Don't treat exceptions as recoverable.</term> + <listitem> + <para> + This is more of a necessary practice than a "best" practice. When an exception occurs, roll back + the <literal>Transaction</literal> and close the <literal>Session</literal>. If you don't, Hibernate + can't guarantee that in-memory state accurately represents persistent state. As a special case of this, + do not use <literal>Session.load()</literal> to determine if an instance with the given identifier + exists on the database; use <literal>Session.get()</literal> or a query instead. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Prefer lazy fetching for associations.</term> + <listitem> + <para> + Use eager fetching sparingly. Use proxies and lazy collections for most associations to classes that + are not likely to be completely held in the second-level cache. For associations to cached classes, + where there is an a extremely high probability of a cache hit, explicitly disable eager fetching using + <literal>lazy="false"</literal>. When an join fetching is appropriate to a particular use + case, use a query with a <literal>left join fetch</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Use the <emphasis>open session in view</emphasis> pattern, or a disciplined + <emphasis>assembly phase</emphasis> to avoid problems with unfetched data. + </term> + <listitem> + <para> + Hibernate frees the developer from writing tedious <emphasis>Data Transfer Objects</emphasis> (DTO). + In a traditional EJB architecture, DTOs serve dual purposes: first, they work around the problem + that entity beans are not serializable; second, they implicitly define an assembly phase where + all data to be used by the view is fetched and marshalled into the DTOs before returning control + to the presentation tier. Hibernate eliminates the first purpose. However, you will still need + an assembly phase (think of your business methods as having a strict contract with the presentation + tier about what data is available in the detached objects) unless you are prepared to hold the + persistence context (the session) open across the view rendering process. This is not a limitation + of Hibernate! It is a fundamental requirement of safe transactional data access. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Consider abstracting your business logic from Hibernate.</term> + <listitem> + <para> + Hide (Hibernate) data-access code behind an interface. Combine the <emphasis>DAO</emphasis> and + <emphasis>Thread Local Session</emphasis> patterns. You can even have some classes persisted by + handcoded JDBC, associated to Hibernate via a <literal>UserType</literal>. (This advice is + intended for "sufficiently large" applications; it is not appropriate for an application with + five tables!) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Don't use exotic association mappings.</term> + <listitem> + <para> + Good usecases for a real many-to-many associations are rare. Most of the time you need + additional information stored in the "link table". In this case, it is much better to + use two one-to-many associations to an intermediate link class. In fact, we think that + most associations are one-to-many and many-to-one, you should be careful when using any + other association style and ask yourself if it is really neccessary. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Prefer bidirectional associations.</term> + <listitem> + <para> + Unidirectional associations are more difficult to query. In a large application, almost + all associations must be navigable in both directions in queries. + </para> + </listitem> + </varlistentry> + </variablelist> + +</chapter> + Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/collection_mapping.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/collection_mapping.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/collection_mapping.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/collection_mapping.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,1238 @@ +<chapter id="collections"> + <title>Mapeamento de Coleções</title> + + <sect1 id="collections-persistent" revision="3"> + <title>Persistent collections</title> + + <para> + Hibernate requires that persistent collection-valued fields be declared + as an interface type, for example: + </para> + + <programlisting><![CDATA[public class Product { + private String serialNumber; + private Set parts = new HashSet(); + + public Set getParts() { return parts; } + void setParts(Set parts) { this.parts = parts; } + public String getSerialNumber() { return serialNumber; } + void setSerialNumber(String sn) { serialNumber = sn; } +}]]></programlisting> + + <para> + The actual interface might be <literal>java.util.Set</literal>, + <literal>java.util.Collection</literal>, <literal>java.util.List</literal>, + <literal>java.util.Map</literal>, <literal>java.util.SortedSet</literal>, + <literal>java.util.SortedMap</literal> or ... anything you like! (Where + "anything you like" means you will have to write an implementation of + <literal>org.hibernate.usertype.UserCollectionType</literal>.) + </para> + + <para> + Notice how we initialized the instance variable with an instance of + <literal>HashSet</literal>. This is the best way to initialize collection + valued properties of newly instantiated (non-persistent) instances. When + you make the instance persistent - by calling <literal>persist()</literal>, + for example - Hibernate will actually replace the <literal>HashSet</literal> + with an instance of Hibernate's own implementation of <literal>Set</literal>. + Watch out for errors like this: + </para> + + <programlisting><![CDATA[Cat cat = new DomesticCat(); +Cat kitten = new DomesticCat(); +.... +Set kittens = new HashSet(); +kittens.add(kitten); +cat.setKittens(kittens); +session.persist(cat); +kittens = cat.getKittens(); // Okay, kittens collection is a Set +(HashSet) cat.getKittens(); // Error!]]></programlisting> + + <para> + The persistent collections injected by Hibernate behave like + <literal>HashMap</literal>, <literal>HashSet</literal>, + <literal>TreeMap</literal>, <literal>TreeSet</literal> or + <literal>ArrayList</literal>, depending upon the interface type. + </para> + + <para> + Collections instances have the usual behavior of value types. They are + automatically persisted when referenced by a persistent object and + automatically deleted when unreferenced. If a collection is passed from one + persistent object to another, its elements might be moved from one table to + another. Two entities may not share a reference to the same collection + instance. Due to the underlying relational model, collection-valued properties + do not support null value semantics; Hibernate does not distinguish between + a null collection reference and an empty collection. + </para> + + <para> + You shouldn't have to worry much about any of this. Use persistent collections + the same way you use ordinary Java collections. Just make sure you understand + the semantics of bidirectional associations (discussed later). + </para> + + </sect1> + + <sect1 id="collections-mapping" revision="4"> + <title>Collection mappings</title> + + <para> + The Hibernate mapping element used for mapping a collection depends upon + the type of the interface. For example, a <literal>&lt;set&gt;</literal> + element is used for mapping properties of type <literal>Set</literal>. + </para> + + <programlisting><![CDATA[<class name="Product"> + <id name="serialNumber" column="productSerialNumber"/> + <set name="parts"> + <key column="productSerialNumber" not-null="true"/> + <one-to-many class="Part"/> + </set> +</class>]]></programlisting> + + <para> + Apart from <literal>&lt;set&gt;</literal>, there is also + <literal>&lt;list&gt;</literal>, <literal>&lt;map&gt;</literal>, + <literal>&lt;bag&gt;</literal>, <literal>&lt;array&gt;</literal> and + <literal>&lt;primitive-array&gt;</literal> mapping elements. The + <literal>&lt;map&gt;</literal> element is representative: + </para> + + <programlistingco> + <areaspec> + <area id="mappingcollection1" coords="2 65"/> + <area id="mappingcollection2" coords="3 65"/> + <area id="mappingcollection3" coords="4 65"/> + <area id="mappingcollection4" coords="5 65"/> + <area id="mappingcollection5" coords="6 65"/> + <area id="mappingcollection6" coords="7 65"/> + <area id="mappingcollection7" coords="8 65"/> + <area id="mappingcollection8" coords="9 65"/> + <area id="mappingcollection9" coords="10 65"/> + <area id="mappingcollection10" coords="11 65"/> + <area id="mappingcollection11" coords="12 65"/> + <area id="mappingcollection12" coords="13 65"/> + <area id="mappingcollection13" coords="14 65"/> + <area id="mappingcollection14" coords="15 65"/> + </areaspec> + <programlisting><![CDATA[<map + name="propertyName" + table="table_name" + schema="schema_name" + lazy="true|extra|false" + inverse="true|false" + cascade="all|none|save-update|delete|all-delete-orphan|delete-orphan" + sort="unsorted|natural|comparatorClass" + order-by="column_name asc|desc" + where="arbitrary sql where condition" + fetch="join|select|subselect" + batch-size="N" + access="field|property|ClassName" + optimistic-lock="true|false" + mutable="true|false" + node="element-name|." + embed-xml="true|false" +> + + <key .... /> + <map-key .... /> + <element .... /> +</map>]]></programlisting> + <calloutlist> + <callout arearefs="mappingcollection1"> + <para> + <literal>name</literal> the collection property name + </para> + </callout> + <callout arearefs="mappingcollection2"> + <para> + <literal>table</literal> (optional - defaults to property name) the + name of the collection table (not used for one-to-many associations) + </para> + </callout> + <callout arearefs="mappingcollection3"> + <para> + <literal>schema</literal> (optional) the name of a table schema to + override the schema declared on the root element + </para> + </callout> + <callout arearefs="mappingcollection4"> + <para> + <literal>lazy</literal> (optional - defaults to <literal>true</literal>) + may be used to disable lazy fetching and specify that the association is + always eagerly fetched, or to enable "extra-lazy" fetching where most + operations do not initialize the collection (suitable for very large + collections) + </para> + </callout> + <callout arearefs="mappingcollection5"> + <para> + <literal>inverse</literal> (optional - defaults to <literal>false</literal>) + mark this collection as the "inverse" end of a bidirectional association + </para> + </callout> + <callout arearefs="mappingcollection6"> + <para> + <literal>cascade</literal> (optional - defaults to <literal>none</literal>) + enable operations to cascade to child entities + </para> + </callout> + <callout arearefs="mappingcollection7"> + <para> + <literal>sort</literal> (optional) specify a sorted collection with + <literal>natural</literal> sort order, or a given comparator class + </para> + </callout> + <callout arearefs="mappingcollection8"> + <para> + <literal>order-by</literal> (optional, JDK1.4 only) specify a table column (or columns) + that define the iteration order of the <literal>Map</literal>, <literal>Set</literal> + or bag, together with an optional <literal>asc</literal> or <literal>desc</literal> + </para> + </callout> + <callout arearefs="mappingcollection9"> + <para> + <literal>where</literal> (optional) specify an arbitrary SQL <literal>WHERE</literal> + condition to be used when retrieving or removing the collection (useful if the + collection should contain only a subset of the available data) + </para> + </callout> + <callout arearefs="mappingcollection10"> + <para> + <literal>fetch</literal> (optional, defaults to <literal>select</literal>) Choose + between outer-join fetching, fetching by sequential select, and fetching by sequential + subselect. + </para> + </callout> + <callout arearefs="mappingcollection11"> + <para> + <literal>batch-size</literal> (optional, defaults to <literal>1</literal>) specify a + "batch size" for lazily fetching instances of this collection. + </para> + </callout> + <callout arearefs="mappingcollection12"> + <para> + <literal>access</literal> (optional - defaults to <literal>property</literal>): The + strategy Hibernate should use for accessing the collection property value. + </para> + </callout> + <callout arearefs="mappingcollection13"> + <para> + <literal>optimistic-lock</literal> (optional - defaults to <literal>true</literal>): + Species that changes to the state of the collection results in increment of the + owning entity's version. (For one to many associations, it is often reasonable to + disable this setting.) + </para> + </callout> + <callout arearefs="mappingcollection14"> + <para> + <literal>mutable</literal> (optional - defaults to <literal>true</literal>): + A value of <literal>false</literal> specifies that the elements of the + collection never change (a minor performance optimization in some cases). + </para> + </callout> + </calloutlist> + </programlistingco> + + <sect2 id="collections-foreignkeys" > + <title>Collection foreign keys</title> + + <para> + Collection instances are distinguished in the database by the foreign key of + the entity that owns the collection. This foreign key is referred to as the + <emphasis>collection key column</emphasis> (or columns) of the collection + table. The collection key column is mapped by the <literal>&lt;key&gt;</literal> + element. + </para> + + <para> + There may be a nullability constraint on the foreign key column. For most + collections, this is implied. For unidirectional one to many associations, + the foreign key column is nullable by default, so you might need to specify + <literal>not-null="true"</literal>. + </para> + + <programlisting><![CDATA[<key column="productSerialNumber" not-null="true"/>]]></programlisting> + + <para> + The foreign key constraint may use <literal>ON DELETE CASCADE</literal>. + </para> + + <programlisting><![CDATA[<key column="productSerialNumber" on-delete="cascade"/>]]></programlisting> + + <para> + See the previous chapter for a full definition of the <literal>&lt;key&gt;</literal> + element. + </para> + + </sect2> + + <sect2 id="collections-elements" > + <title>Collection elements</title> + + <para> + Collections may contain almost any other Hibernate type, including all basic types, + custom types, components, and of course, references to other entities. This is an + important distinction: an object in a collection might be handled with "value" + semantics (its life cycle fully depends on the collection owner) or it might be a + reference to another entity, with its own life cycle. In the latter case, only the + "link" between the two objects is considered to be state held by the collection. + </para> + + <para> + The contained type is referred to as the <emphasis>collection element type</emphasis>. + Collection elements are mapped by <literal>&lt;element&gt;</literal> or + <literal>&lt;composite-element&gt;</literal>, or in the case of entity references, + with <literal>&lt;one-to-many&gt;</literal> or <literal>&lt;many-to-many&gt;</literal>. + The first two map elements with value semantics, the next two are used to map entity + associations. + </para> + + </sect2> + + <sect2 id="collections-indexed"> + <title>Indexed collections</title> + + <para> + All collection mappings, except those with set and bag semantics, need an + <emphasis>index column</emphasis> in the collection table - a column that maps to an + array index, or <literal>List</literal> index, or <literal>Map</literal> key. The + index of a <literal>Map</literal> may be of any basic type, mapped with + <literal>&lt;map-key&gt;</literal>, it may be an entity reference mapped with + <literal>&lt;map-key-many-to-many&gt;</literal>, or it may be a composite type, + mapped with <literal>&lt;composite-map-key&gt;</literal>. The index of an array or + list is always of type <literal>integer</literal> and is mapped using the + <literal>&lt;list-index&gt;</literal> element. The mapped column contains + sequential integers (numbered from zero, by default). + </para> + + <programlistingco> + <areaspec> + <area id="index1" coords="2 45"/> + <area id="index2" coords="3 45"/> + </areaspec> + <programlisting><![CDATA[<list-index + column="column_name" + base="0|1|..."/>]]></programlisting> + <calloutlist> + <callout arearefs="index1"> + <para> + <literal>column_name</literal> (required): The name of the column holding the + collection index values. + </para> + </callout> + <callout arearefs="index1"> + <para> + <literal>base</literal> (optional, defaults to <literal>0</literal>): The value + of the index column that corresponds to the first element of the list or array. + </para> + </callout> + </calloutlist> + </programlistingco> + + <programlistingco> + <areaspec> + <area id="mapkey1" coords="2 45"/> + <area id="mapkey2" coords="3 45"/> + <area id="mapkey3" coords="4 45"/> + </areaspec> + <programlisting><![CDATA[<map-key + column="column_name" + formula="any SQL expression" + type="type_name" + node="@attribute-name" + length="N"/>]]></programlisting> + <calloutlist> + <callout arearefs="mapkey1"> + <para> + <literal>column</literal> (optional): The name of the column holding the + collection index values. + </para> + </callout> + <callout arearefs="mapkey2"> + <para> + <literal>formula</literal> (optional): A SQL formula used to evaluate the + key of the map. + </para> + </callout> + <callout arearefs="mapkey3"> + <para> + <literal>type</literal> (reguired): The type of the map keys. + </para> + </callout> + </calloutlist> + </programlistingco> + + <programlistingco> + <areaspec> + <area id="indexmanytomany1" coords="2 45"/> + <area id="indexmanytomany2" coords="3 45"/> + <area id="indexmanytomany3" coords="3 45"/> + </areaspec> + <programlisting><![CDATA[<map-key-many-to-many + column="column_name" + formula="any SQL expression" + class="ClassName" +/>]]></programlisting> + <calloutlist> + <callout arearefs="indexmanytomany1"> + <para> + <literal>column</literal> (optional): The name of the foreign key + column for the collection index values. + </para> + </callout> + <callout arearefs="indexmanytomany2"> + <para> + <literal>formula</literal> (optional): A SQL formula used to evaluate the + foreign key of the map key. + </para> + </callout> + <callout arearefs="indexmanytomany3"> + <para> + <literal>class</literal> (required): The entity class used as the map key. + </para> + </callout> + </calloutlist> + </programlistingco> + + + <para> + If your table doesn't have an index column, and you still wish to use <literal>List</literal> + as the property type, you should map the property as a Hibernate <emphasis>&lt;bag&gt;</emphasis>. + A bag does not retain its order when it is retrieved from the database, but it may be + optionally sorted or ordered. + </para> + + </sect2> + + <para> + There are quite a range of mappings that can be generated for collections, covering + many common relational models. We suggest you experiment with the schema generation tool + to get a feeling for how various mapping declarations translate to database tables. + </para> + + <sect2 id="collections-ofvalues" revision="2"> + <title>Collections of values and many-to-many associations</title> + + <para> + Any collection of values or many-to-many association requires a dedicated + <emphasis>collection table</emphasis> with a foreign key column or columns, + <emphasis>collection element column</emphasis> or columns and possibly + an index column or columns. + </para> + + <para> + For a collection of values, we use the <literal>&lt;element&gt;</literal> tag. + </para> + + <programlistingco> + <areaspec> + <area id="element1b" coords="2 50"/> + <area id="element2b" coords="3 50"/> + <area id="element3b" coords="4 50"/> + </areaspec> + <programlisting><![CDATA[<element + column="column_name" + formula="any SQL expression" + type="typename" + length="L" + precision="P" + scale="S" + not-null="true|false" + unique="true|false" + node="element-name" +/>]]></programlisting> + <calloutlist> + <callout arearefs="element1b"> + <para> + <literal>column</literal> (optional): The name of the column holding the + collection element values. + </para> + </callout> + <callout arearefs="element2b"> + <para> + <literal>formula</literal> (optional): An SQL formula used to evaluate the + element. + </para> + </callout> + <callout arearefs="element3b"> + <para> + <literal>type</literal> (required): The type of the collection element. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + A <emphasis>many-to-many association</emphasis> is specified using the + <literal>&lt;many-to-many&gt;</literal> element. + </para> + + <programlistingco> + <areaspec> + <area id="manytomany1" coords="2 60"/> + <area id="manytomany2" coords="3 60"/> + <area id="manytomany3" coords="4 60"/> + <area id="manytomany4" coords="5 60"/> + <area id="manytomany5" coords="6 60"/> + <area id="manytomany6" coords="7 60"/> + <area id="manytomany7" coords="8 60"/> + <area id="manytomany8" coords="9 60"/> + </areaspec> + <programlisting><![CDATA[<many-to-many + column="column_name" + formula="any SQL expression" + class="ClassName" + fetch="select|join" + unique="true|false" + not-found="ignore|exception" + entity-name="EntityName" + property-ref="propertyNameFromAssociatedClass" + node="element-name" + embed-xml="true|false" + />]]></programlisting> + <calloutlist> + <callout arearefs="manytomany1"> + <para> + <literal>column</literal> (optional): The name of the element foreign key column. + </para> + </callout> + <callout arearefs="manytomany2"> + <para> + <literal>formula</literal> (optional): An SQL formula used to evaluate the element + foreign key value. + </para> + </callout> + <callout arearefs="manytomany3"> + <para> + <literal>class</literal> (required): The name of the associated class. + </para> + </callout> + <callout arearefs="manytomany4"> + <para> + <literal>fetch</literal> (optional - defaults to <literal>join</literal>): + enables outer-join or sequential select fetching for this association. This + is a special case; for full eager fetching (in a single <literal>SELECT</literal>) + of an entity and its many-to-many relationships to other entities, you would + enable <literal>join</literal> fetching not only of the collection itself, + but also with this attribute on the <literal>&lt;many-to-many&gt;</literal> + nested element. + </para> + </callout> + <callout arearefs="manytomany5"> + <para> + <literal>unique</literal> (optional): Enable the DDL generation of a unique + constraint for the foreign-key column. This makes the association multiplicity + effectively one to many. + </para> + </callout> + <callout arearefs="manytomany6"> + <para> + <literal>not-found</literal> (optional - defaults to <literal>exception</literal>): + Specifies how foreign keys that reference missing rows will be handled: + <literal>ignore</literal> will treat a missing row as a null association. + </para> + </callout> + <callout arearefs="manytomany7"> + <para> + <literal>entity-name</literal> (optional): The entity name of the associated class, + as an alternative to <literal>class</literal>. + </para> + </callout> + <callout arearefs="manytomany8"> + <para> + <literal>property-ref</literal>: (optional) The name of a property of the associated + class that is joined to this foreign key. If not specified, the primary key of + the associated class is used. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Some examples, first, a set of strings: + </para> + + <programlisting><![CDATA[<set name="names" table="person_names"> + <key column="person_id"/> + <element column="person_name" type="string"/> +</set>]]></programlisting> + + <para> + A bag containing integers (with an iteration order determined by the + <literal>order-by</literal> attribute): + </para> + + <programlisting><![CDATA[<bag name="sizes" + table="item_sizes" + order-by="size asc"> + <key column="item_id"/> + <element column="size" type="integer"/> +</bag>]]></programlisting> + + <para> + An array of entities - in this case, a many to many association: + </para> + + <programlisting><![CDATA[<array name="addresses" + table="PersonAddress" + cascade="persist"> + <key column="personId"/> + <list-index column="sortOrder"/> + <many-to-many column="addressId" class="Address"/> +</array>]]></programlisting> + + <para> + A map from string indices to dates: + </para> + + <programlisting><![CDATA[<map name="holidays" + table="holidays" + schema="dbo" + order-by="hol_name asc"> + <key column="id"/> + <map-key column="hol_name" type="string"/> + <element column="hol_date" type="date"/> +</map>]]></programlisting> + + <para> + A list of components (discussed in the next chapter): + </para> + + <programlisting><![CDATA[<list name="carComponents" + table="CarComponents"> + <key column="carId"/> + <list-index column="sortOrder"/> + <composite-element class="CarComponent"> + <property name="price"/> + <property name="type"/> + <property name="serialNumber" column="serialNum"/> + </composite-element> +</list>]]></programlisting> + + </sect2> + + <sect2 id="collections-onetomany"> + <title>One-to-many associations</title> + + <para> + A <emphasis>one to many association</emphasis> links the tables of two classes + via a foreign key, with no intervening collection table. This mapping loses + certain semantics of normal Java collections: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + An instance of the contained entity class may not belong to more than + one instance of the collection + </para> + </listitem> + <listitem> + <para> + An instance of the contained entity class may not appear at more than + one value of the collection index + </para> + </listitem> + </itemizedlist> + + <para> + An association from <literal>Product</literal> to <literal>Part</literal> requires + existence of a foreign key column and possibly an index column to the <literal>Part</literal> + table. A <literal>&lt;one-to-many&gt;</literal> tag indicates that this is a one to many + association. + </para> + + <programlistingco> + <areaspec> + <area id="onetomany1" coords="2 60"/> + <area id="onetomany2" coords="3 60"/> + <area id="onetomany3" coords="4 60"/> + </areaspec> + <programlisting><![CDATA[<one-to-many + class="ClassName" + not-found="ignore|exception" + entity-name="EntityName" + node="element-name" + embed-xml="true|false" + />]]></programlisting> + <calloutlist> + <callout arearefs="onetomany1"> + <para> + <literal>class</literal> (required): The name of the associated class. + </para> + </callout> + <callout arearefs="onetomany2"> + <para> + <literal>not-found</literal> (optional - defaults to <literal>exception</literal>): + Specifies how cached identifiers that reference missing rows will be handled: + <literal>ignore</literal> will treat a missing row as a null association. + </para> + </callout> + <callout arearefs="onetomany3"> + <para> + <literal>entity-name</literal> (optional): The entity name of the associated class, + as an alternative to <literal>class</literal>. + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Notice that the <literal>&lt;one-to-many&gt;</literal> element does not need to + declare any columns. Nor is it necessary to specify the <literal>table</literal> + name anywhere. + </para> + + <para> + <emphasis>Very important note:</emphasis> If the foreign key column of a + <literal>&lt;one-to-many&gt;</literal> association is declared <literal>NOT NULL</literal>, + you must declare the <literal>&lt;key&gt;</literal> mapping + <literal>not-null="true"</literal> or <emphasis>use a bidirectional association</emphasis> + with the collection mapping marked <literal>inverse="true"</literal>. See the discussion + of bidirectional associations later in this chapter. + </para> + + <para> + This example shows a map of <literal>Part</literal> entities by name (where + <literal>partName</literal> is a persistent property of <literal>Part</literal>). + Notice the use of a formula-based index. + </para> + + <programlisting><![CDATA[<map name="parts" + cascade="all"> + <key column="productId" not-null="true"/> + <map-key formula="partName"/> + <one-to-many class="Part"/> +</map>]]></programlisting> + </sect2> + + </sect1> + + <sect1 id="collections-advancedmappings"> + <title>Advanced collection mappings</title> + + <sect2 id="collections-sorted" revision="2"> + <title>Sorted collections</title> + + <para> + Hibernate supports collections implementing <literal>java.util.SortedMap</literal> and + <literal>java.util.SortedSet</literal>. You must specify a comparator in the mapping file: + </para> + + <programlisting><![CDATA[<set name="aliases" + table="person_aliases" + sort="natural"> + <key column="person"/> + <element column="name" type="string"/> +</set> + +<map name="holidays" sort="my.custom.HolidayComparator"> + <key column="year_id"/> + <map-key column="hol_name" type="string"/> + <element column="hol_date" type="date"/> +</map>]]></programlisting> + + <para> + Allowed values of the <literal>sort</literal> attribute are <literal>unsorted</literal>, + <literal>natural</literal> and the name of a class implementing + <literal>java.util.Comparator</literal>. + </para> + + <para> + Sorted collections actually behave like <literal>java.util.TreeSet</literal> or + <literal>java.util.TreeMap</literal>. + </para> + + <para> + If you want the database itself to order the collection elements use the + <literal>order-by</literal> attribute of <literal>set</literal>, <literal>bag</literal> + or <literal>map</literal> mappings. This solution is only available under + JDK 1.4 or higher (it is implemented using <literal>LinkedHashSet</literal> or + <literal>LinkedHashMap</literal>). This performs the ordering in the SQL query, + not in memory. + </para> + + <programlisting><![CDATA[<set name="aliases" table="person_aliases" order-by="lower(name) asc"> + <key column="person"/> + <element column="name" type="string"/> +</set> + +<map name="holidays" order-by="hol_date, hol_name"> + <key column="year_id"/> + <map-key column="hol_name" type="string"/> + <element column="hol_date type="date"/> +</map>]]></programlisting> + + <para> + Note that the value of the <literal>order-by</literal> attribute is an SQL ordering, not + a HQL ordering! + </para> + + <para> + Associations may even be sorted by some arbitrary criteria at runtime using a collection + <literal>filter()</literal>. + </para> + + <programlisting><![CDATA[sortedUsers = s.createFilter( group.getUsers(), "order by this.name" ).list();]]></programlisting> + + </sect2> + + <sect2 id="collections-bidirectional" revision="1"> + <title>Bidirectional associations</title> + + <para> + A <emphasis>bidirectional association</emphasis> allows navigation from both + "ends" of the association. Two kinds of bidirectional association are + supported: + + <variablelist> + <varlistentry> + <term>one-to-many</term> + <listitem> + <para> + set or bag valued at one end, single-valued at the other + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>many-to-many</term> + <listitem> + <para> + set or bag valued at both ends + </para> + </listitem> + </varlistentry> + </variablelist> + + </para> + + <para> + You may specify a bidirectional many-to-many association simply by mapping two + many-to-many associations to the same database table and declaring one end as + <emphasis>inverse</emphasis> (which one is your choice, but it can not be an + indexed collection). + </para> + + <para> + Here's an example of a bidirectional many-to-many association; each category can + have many items and each item can be in many categories: + </para> + + <programlisting><![CDATA[<class name="Category"> + <id name="id" column="CATEGORY_ID"/> + ... + <bag name="items" table="CATEGORY_ITEM"> + <key column="CATEGORY_ID"/> + <many-to-many class="Item" column="ITEM_ID"/> + </bag> +</class> + +<class name="Item"> + <id name="id" column="ITEM_ID"/> + ... + + <!-- inverse end --> + <bag name="categories" table="CATEGORY_ITEM" inverse="true"> + <key column="ITEM_ID"/> + <many-to-many class="Category" column="CATEGORY_ID"/> + </bag> +</class>]]></programlisting> + + <para> + As mudanças feitas somente de um lado da associação <emphasis>não</emphasis> são + persistidas. Isto significa que o Hibernate tem duas representações na memória + para cada associação bidirecional, uma associação de A para B e uma outra + associação de B para A. Isto é mais fácil de compreender se você pensa + sobre o modelo do objetos do Java e como nós criamos um relacionamento muitos + para muitos em Java: + </para> + + <programlisting><![CDATA[ +category.getItems().add(item); // The category now "knows" about the relationship +item.getCategories().add(category); // The item now "knows" about the relationship + +session.persist(item); // The relationship won't be saved! +session.persist(category); // The relationship will be saved]]></programlisting> + + <para> + A outra ponta é usada salvar a representação em memória à base de dados. + </para> + + <para> + Você pode definir uma associação bidirecional um para muitos através de uma associação + um-para-muitos indicando as mesmas colunas da tabela que à associação muitos-para-um e + declarando a propriedade <literal>inverse="true"</literal> + + </para> + + <programlisting><![CDATA[<class name="Parent"> + <id name="id" column="parent_id"/> + .... + <set name="children" inverse="true"> + <key column="parent_id"/> + <one-to-many class="Child"/> + </set> +</class> + +<class name="Child"> + <id name="id" column="child_id"/> + .... + <many-to-one name="parent" + class="Parent" + column="parent_id" + not-null="true"/> +</class>]]></programlisting> + + <para> + Mapear apenas uma das pontas da associação com <literal>inverse="true"</literal> + não afeta as operações em cascata, isso é um conceito ortogonal. + </para> + + </sect2> + + <sect2 id="collections-indexedbidirectional"> + <title>Associações bidirecionais com coleções indexadas</title> + <para> + Uma associação bidirecional onde uma dos lados e representa pôr uma + <literal>&lt;list&gt;</literal> ou <literal>&lt;map&gt;</literal> requer uma consideração + especial. Se houver uma propriedade da classe filha que faça o mapeamento da coluna do + índice, sem problema, pode-se continuar usando <literal>inverse="true"</literal> no + mapeamento da coleção. + </para> + + <programlisting><![CDATA[<class name="Parent"> + <id name="id" column="parent_id"/> + .... + <map name="children" inverse="true"> + <key column="parent_id"/> + <map-key column="name" + type="string"/> + <one-to-many class="Child"/> + </map> +</class> + +<class name="Child"> + <id name="id" column="child_id"/> + .... + <property name="name" + not-null="true"/> + <many-to-one name="parent" + class="Parent" + column="parent_id" + not-null="true"/> +</class>]]></programlisting> + + <para> + Mas, se não houver nenhuma propriedade na classe filha, não podemos ver essa associação + como verdadeiramente bidirecional (há uma informação disponível em um lado da associação + que não está disponível no extremo oposto). Nesse caso, nos não podemos mapear a coleção + usando <literal>inverse="true"</literal>. Nos devemos usar o seguinte mapeamento: + </para> + + <programlisting><![CDATA[<class name="Parent"> + <id name="id" column="parent_id"/> + .... + <map name="children"> + <key column="parent_id" + not-null="true"/> + <map-key column="name" + type="string"/> + <one-to-many class="Child"/> + </map> +</class> + +<class name="Child"> + <id name="id" column="child_id"/> + .... + <many-to-one name="parent" + class="Parent" + column="parent_id" + insert="false" + update="false" + not-null="true"/> +</class>]]></programlisting> + + <para> + Veja que neste mapeamento, que um dos lado da associação, a coleção, é responsável pela + atualização da chave estrangeira. TODO: Isso realmente resulta em updates desnecessários ?. + </para> + + </sect2> + + <sect2 id="collections-ternary"> + <title>Associações Ternárias</title> + + <para> + Há três meios possíveis de se mapear uma associação ternária. Uma é usar um + <literal>Map</literal> com uma associação como seu índice: + </para> + + <programlisting><![CDATA[<map name="contracts"> + <key column="employer_id" not-null="true"/> + <map-key-many-to-many column="employee_id" class="Employee"/> + <one-to-many class="Contract"/> +</map>]]></programlisting> + + <programlisting><![CDATA[<map name="connections"> + <key column="incoming_node_id"/> + <map-key-many-to-many column="outgoing_node_id" class="Node"/> + <many-to-many column="connection_id" class="Connection"/> +</map>]]></programlisting> + + <para> + A segunda maneira é simplesmente remodelar a associação das classes da entidade. + Esta é a maneira que nós usamos de uma maneira geral. + </para> + + <para> + Uma alternativa final é usar os elementos compostos, que nós + discutiremos mais tarde. + </para> + + </sect2> + + <sect2 id="collections-idbag" revision="1"> + <title><literal>Usando o &lt;idbag&gt;</literal></title> + + <para> + Se você concorda com nossa visão que chaves compostas são uma coisa ruim e que + as entidades devem ter identificadores sintéticos (surrogate keys), então você + deve estar achando um pouco estranho que as associações muitos para muitos + usando coleções de valores que nós mostramos estejam mapeadas com chaves + compostas! Bem, este ponto é bastante discutível; um simples tabela de associação + não parece se beneficiar muito de uma surrogate key (entretanto uma coleção de + valores compostos <emphasis>sim</emphasis>). Opcionalmente, o Hibernate prove + uma maneira de mapear uma associação muitos para muitos com uma coleção + de valores para uma tabela com uma surrogate key. + </para> + + <para> + O elemento <literal>&lt;idbag&gt;</literal> permite mapear um <literal>List</literal> + (ou uma <literal>Collection</literal> com uma semântica de bag. + </para> + +<programlisting><![CDATA[<idbag name="lovers" table="LOVERS"> + <collection-id column="ID" type="long"> + <generator class="sequence"/> + </collection-id> + <key column="PERSON1"/> + <many-to-many column="PERSON2" class="Person" fetch="join"/> +</idbag>]]></programlisting> + + <para> + Como você pode ver, um <literal>&lt;idbag&gt;</literal> possui um gerador de id + sintético, igual uma classe de entidade! Uma surrogate key diferente é associada + para cada elemento de coleção. Porém, o Hibernate não prove nenhum mecanismo + para descobrir qual a surrogate key de uma linha em particular. + </para> + + <para> + Note que o desempenho de atualização de um <literal>&lt;idbag&gt;</literal> é + <emphasis>much</emphasis> melhor que um <literal>&lt;bag&gt;</literal> normal! + O Hibernate pode localizar uma linha individual eficazmente e atualizar ou + deletar individualmente, como um list, map ou set. + </para> + + <para> + Na implementação atual, a estratégia de geração de identificador <literal>native</literal> + não é suportada para identificadores de coleção usando o <literal>&lt;idbag&gt;</literal>. + </para> + + </sect2> + + </sect1> + + <!--undocumenting this stuff --> + + <!--sect1 id="collections-heterogeneous"> + <title>Heterogeneous Associations</title> + + <para> + The <literal>&lt;many-to-any&gt;</literal> and <literal>&lt;index-many-to-any&gt;</literal> + elements provide for true heterogeneous associations. These mapping elements work in the + same way as the <literal>&lt;any&gt;</literal> element - and should also be used + rarely, if ever. + </para> + + </sect1--> + + <sect1 id="collections-example" revision="1"> + <title>Exemplos de coleções</title> + + <para> + As seções anteriores são uma grande confusão. Assim sendo vejamos uma exemplo. + Essa classe: + </para> + + <programlisting><![CDATA[package eg; +import java.util.Set; + +public class Parent { + private long id; + private Set children; + + public long getId() { return id; } + private void setId(long id) { this.id=id; } + + private Set getChildren() { return children; } + private void setChildren(Set children) { this.children=children; } + + .... + .... +}]]></programlisting> + + <para> + tem uma coleção de instancias de <literal>Child</literal>. Se + cada Child tiver no máximo um parent, o mapeamento natural é + uma associação um para muitos: + </para> + + <programlisting><![CDATA[<hibernate-mapping> + + <class name="Parent"> + <id name="id"> + <generator class="sequence"/> + </id> + <set name="children"> + <key column="parent_id"/> + <one-to-many class="Child"/> + </set> + </class> + + <class name="Child"> + <id name="id"> + <generator class="sequence"/> + </id> + <property name="name"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Esse mapeamento gera a seguinte definição de tabelas + </para> + + <programlisting><![CDATA[create table parent ( id bigint not null primary key ) +create table child ( id bigint not null primary key, name varchar(255), parent_id bigint ) +alter table child add constraint childfk0 (parent_id) references parent]]></programlisting> + + <para> + Se o parent for <emphasis>obrigatório</emphasis>, use uma associação bidirecional + um para muitos: + </para> + + <programlisting><![CDATA[<hibernate-mapping> + + <class name="Parent"> + <id name="id"> + <generator class="sequence"/> + </id> + <set name="children" inverse="true"> + <key column="parent_id"/> + <one-to-many class="Child"/> + </set> + </class> + + <class name="Child"> + <id name="id"> + <generator class="sequence"/> + </id> + <property name="name"/> + <many-to-one name="parent" class="Parent" column="parent_id" not-null="true"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Repare na constraint <literal>NOT NULL</literal>: + </para> + + <programlisting><![CDATA[create table parent ( id bigint not null primary key ) +create table child ( id bigint not null + primary key, + name varchar(255), + parent_id bigint not null ) +alter table child add constraint childfk0 (parent_id) references parent]]></programlisting> + + <para> + Uma outra alternativa, no caso de você insistir que esta associação devea ser + unidirecional, você pode declarar a constraint como <literal>NOT NULL</literal> + na tag <literal>&lt;key&gt;</literal> do mapeamento: + </para> + + <programlisting><![CDATA[<hibernate-mapping> + + <class name="Parent"> + <id name="id"> + <generator class="sequence"/> + </id> + <set name="children"> + <key column="parent_id" not-null="true"/> + <one-to-many class="Child"/> + </set> + </class> + + <class name="Child"> + <id name="id"> + <generator class="sequence"/> + </id> + <property name="name"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Por outro lado, se uma child puder ter os múltiplos parents, a associação + apropriada é muitos-para-muitos: + </para> + + <programlisting><![CDATA[<hibernate-mapping> + + <class name="Parent"> + <id name="id"> + <generator class="sequence"/> + </id> + <set name="children" table="childset"> + <key column="parent_id"/> + <many-to-many class="Child" column="child_id"/> + </set> + </class> + + <class name="Child"> + <id name="id"> + <generator class="sequence"/> + </id> + <property name="name"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Definições das tabelas: + </para> + + <programlisting><![CDATA[create table parent ( id bigint not null primary key ) +create table child ( id bigint not null primary key, name varchar(255) ) +create table childset ( parent_id bigint not null, + child_id bigint not null, + primary key ( parent_id, child_id ) ) +alter table childset add constraint childsetfk0 (parent_id) references parent +alter table childset add constraint childsetfk1 (child_id) references child]]></programlisting> + + <para> + For more examples and a complete walk-through a parent/child relationship mapping, + see <xref linkend="example-parentchild"/>. + Para mais exemplos e um exemplo completo de mapeamento de relacionamento + de mestre/detalhe, veja <xref linkend="example-parentchild"/>. + </para> + + <para> + Até mesmo o mapeamento de associações mais exóticas são possíveis, nós catalogaremos + todas as possibilidades no próximo capítulo. + </para> + + </sect1> + +</chapter> Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/component_mapping.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/component_mapping.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/component_mapping.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/component_mapping.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,413 @@ +<chapter id="components"> + <title>Mapeamento de Componentes</title> + + <para> + A noção de <emphasis>componente</emphasis> é reusada em vários contextos diferentes, + para propósitos diferentes, pelo Hibernate. + + + </para> + + <sect1 id="components-dependentobjects" revision="2" > + <title>Objetos dependentes</title> + + <para> + Um componente é um objeto contido que é persistido como um tipo de valor, não uma + referência de entidade. O termo "componente" refere-se à noção de composição da + orientação a objetos (não a componentes no nível de arquitetura). Por exemplo, você + pode modelar uma pessoa desta maneira: + </para> + + <programlisting><![CDATA[public class Person { + private java.util.Date birthday; + private Name name; + private String key; + public String getKey() { + return key; + } + private void setKey(String key) { + this.key=key; + } + public java.util.Date getBirthday() { + return birthday; + } + public void setBirthday(java.util.Date birthday) { + this.birthday = birthday; + } + public Name getName() { + return name; + } + public void setName(Name name) { + this.name = name; + } + ...... + ...... +}]]></programlisting> + +<programlisting><![CDATA[public class Name { + char initial; + String first; + String last; + public String getFirst() { + return first; + } + void setFirst(String first) { + this.first = first; + } + public String getLast() { + return last; + } + void setLast(String last) { + this.last = last; + } + public char getInitial() { + return initial; + } + void setInitial(char initial) { + this.initial = initial; + } +}]]></programlisting> + + <para> + Agora <literal>Name</literal> pode ser persistido como um componente + de <literal>Person</literal>. Note que <literal>Name</literal> define métodos + getter e setter para suas propriedades persistentes, mas não necessita declarar + nenhuma interface ou propriedades identificadoras. + </para> + + <para> + Nosso mapeamento do Hibernate seria semelhante a isso + </para> + + <programlisting><![CDATA[<class name="eg.Person" table="person"> + <id name="Key" column="pid" type="string"> + <generator class="uuid"/> + </id> + <property name="birthday" type="date"/> + <component name="Name" class="eg.Name"> <!-- class attribute optional --> + <property name="initial"/> + <property name="first"/> + <property name="last"/> + </component> +</class>]]></programlisting> + + <para> + A tabela pessoa teria as seguintes colunas <literal>pid</literal>, + <literal>birthday</literal>, + <literal>initial</literal>, + <literal>first</literal> and + <literal>last</literal>. + </para> + + <para> + Assim como todos tipos por valor, componentes não suportam referencias cruzadas. Em + outras palavras, duas pessoas poderiam possuir o mesmo nome, mas os dois objetos + pessoa poderiam conter dois objetos nome independentes, apenas com "o mesmo" por valor. + A semântica dos valores null de um componente são <emphasis>ad hoc</emphasis>. No + recarregameno do conteúdo do objeto, O Hibernate assumira que se todas as colunas + do componente são null, então todo o componente é null. Isto seria o certo para + a maioria dos propósitos. + </para> + + <para> + As propriedades de um componente podem ser de qualquer tipo do Hibernate(collections, + associações muitos-para-um, outros componentes, etc). Componentes agrupados + <emphasis>não </emphasis> devem ser consideros um uso exótico. O Hibernate tem + a intenção de suportar um modelo de objetos muito bem granulado. + </para> + + <para> + O elemento <literal>&lt;component&gt;</literal> permite um subelemento + <literal>&lt;parent&gt;</literal> que mapeia uma propriedade da classe componente + como uma referência de volta para a entidade que a contém. + </para> + + <programlisting><![CDATA[<class name="eg.Person" table="person"> + <id name="Key" column="pid" type="string"> + <generator class="uuid"/> + </id> + <property name="birthday" type="date"/> + <component name="Name" class="eg.Name" unique="true"> + <parent name="namedPerson"/> <!-- reference back to the Person --> + <property name="initial"/> + <property name="first"/> + <property name="last"/> + </component> +</class>]]></programlisting> + + </sect1> + + <sect1 id="components-incollections" revision="1"> + <title>Collections de objetos dependentes</title> + + <para> + Collections de componentes são suportadadas(ex. uma array de + tipo <literal>Name</literal>). Declare a sua collection de + componentes substituindo a tag<literal>&lt;element&gt;</literal> + pela tag <literal>&lt;composite-element&gt;</literal>. + </para> + + <programlisting><![CDATA[<set name="someNames" table="some_names" lazy="true"> + <key column="id"/> + <composite-element class="eg.Name"> <!-- class attribute required --> + <property name="initial"/> + <property name="first"/> + <property name="last"/> + </composite-element> +</set>]]></programlisting> + + <para> + Nota: se você definir um <literal>Set</literal> de elementos compostos, + é muito importante implementar <literal>equals()</literal> e + <literal>hashCode()</literal> corretamente. + </para> + + <para> + Elementos compostos podem conter componentes mas não collections. Se o + seu elemento composto contiver componentes , use a tag + <literal>&lt;nested-composite-element&gt;</literal> . Este é um caso + bastante exótico – uma collections de componentes que por si própria + possui componentes. Neste momento você deve estar se perguntando se + uma associação de um-para-muitos seria mais apropriada. Tente remodelar + o elemento composto como uma entidade – mas note que mesmo pensando + que o modelo Java é o mesmo, o modelo relacional e a semântica de + persistência ainda são diferentes. + </para> + + <para> + Por favor, note que um mapeamento de elemento composto não suporta propriedades + capazes de serem null se você estiver usando um <literal>&lt;set&gt;</literal>. + O Hibernate tem que usar cada valor das colunas para identificar um registro + quando estiver deletando objetos (não existe coluna chave primária separada na + tabela de elemento composto), que não é possível com valores null. + Você tem que usar um dos dois, ou apenas propriedades não null em um elemento + composto ou escolher uma <literal>&lt;list&gt;</literal>, + <literal>&lt;map&gt;</literal>, <literal>&lt;bag&gt;</literal> ou + <literal>&lt;idbag&gt;</literal>. + </para> + + <para> + Um caso especial de elemento composto é um elemento composto com um elemento + <literal>&lt;many-to-one&gt;</literal> aninhado. Um mapeamento como este + permite você a mapear colunas extras de uma tabela de associação de + muitos-para-muitos para a classe de elemento composto. A seguinte + associação de muitos-para-muitos de <literal>Order</literal> para um + <literal>Item</literal> onde <literal>purchaseDate</literal>, + <literal>price</literal> e <literal>quantity</literal> são propriedades + da associação: + </para> + + <programlisting><![CDATA[<class name="eg.Order" .... > + .... + <set name="purchasedItems" table="purchase_items" lazy="true"> + <key column="order_id"> + <composite-element class="eg.Purchase"> + <property name="purchaseDate"/> + <property name="price"/> + <property name="quantity"/> + <many-to-one name="item" class="eg.Item"/> <!-- class attribute is optional --> + </composite-element> + </set> +</class>]]></programlisting> + + <para> + Claro, que não pode ter uma referência para purchase no outro lado, para a + navegação da associação bidirecional. Lembre-se que componentes são tipos por + valor e não permitem referências compartilhadas. Uma classe <literal>Purchase</literal> + simples pode estar no set de uma classe <literal>Order</literal>, mas ela não + pode ser referenciada por <literal>Item</literal> no mesmo momento. + </para> + + <para>Até mesmo associações ternárias (ou quaternária, etc) são possíveis:</para> + + + <programlisting><![CDATA[<class name="eg.Order" .... > + .... + <set name="purchasedItems" table="purchase_items" lazy="true"> + <key column="order_id"> + <composite-element class="eg.OrderLine"> + <many-to-one name="purchaseDetails class="eg.Purchase"/> + <many-to-one name="item" class="eg.Item"/> + </composite-element> + </set> +</class>]]></programlisting> + + <para> + Elementos compostos podem aparecer em pesquisas usando a mesma + sintaxe assim como associações para outras entidades. + </para> + + </sect1> + + <sect1 id="components-asmapindex"> + <title>Componentes como índices de Map</title> + + <para> + O elemento <literal>&lt;composite-map-key&gt;</literal> permite você mapear + uma classe componente como uma chave de um <literal>Map</literal>. Tenha + certeza que você sobrescreveu <literal>hashCode()</literal> e + <literal>equals()</literal> corretamente na classe componente. + </para> + </sect1> + + <sect1 id="components-compositeid" revision="1"> + <title>. Componentes como identificadores compostos</title> + + <para> + Você pode usar um componente como um identificador de uma classe entidade. + Sua classe componente deve satisfazer certos requisitos: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + Ele deve implementar <literal>java.io.Serializable</literal>. + </para> + </listitem> + <listitem> + <para> + Ele deve re-implementar <literal>equals()</literal> e + <literal>hashCode()</literal>, consistentemente com a noção + de igualdade de chave composta do banco de dados. + </para> + </listitem> + </itemizedlist> + + <para> + <emphasis>Nota: no Hibernate 3, o segundo requisito não é um requisito absolutamente + necessário. Mas atenda ele de qualquer forma.</emphasis> + </para> + + <para> + Você não pode usar um <literal>IdentifierGenerator</literal> para gerar chaves compostas. + Ao invés disso o aplicativo deve gerenciar seus próprios identificadores. + </para> + + <para> + Use a tag <literal>&lt;composite-id&gt;</literal> (com elementos + <literal>&lt;key-property&gt;</literal> aninhados) no lugar da declaração + <literal>&lt;id&gt;</literal> de costume. Por exemplo, a classe + <literal>OrderLine</literal> possui uma chave primária que depende da + chave primária (composta) de <literal>Order</literal>. + </para> + + <programlisting><![CDATA[<class name="OrderLine"> + + <composite-id name="id" class="OrderLineId"> + <key-property name="lineId"/> + <key-property name="orderId"/> + <key-property name="customerId"/> + </composite-id> + + <property name="name"/> + + <many-to-one name="order" class="Order" + insert="false" update="false"> + <column name="orderId"/> + <column name="customerId"/> + </many-to-one> + .... + +</class>]]></programlisting> + + <para> + Agora, qualquer chave estrangeira referenciando a tabela <literal>OrderLine</literal> + também serão compostas. Você deve declarar isto em seus mapeamentos para outras + classes. Uma associação para <literal>OrderLine</literal> seria mapeada dessa forma: + </para> + + <programlisting><![CDATA[<many-to-one name="orderLine" class="OrderLine"> +<!-- the "class" attribute is optional, as usual --> + <column name="lineId"/> + <column name="orderId"/> + <column name="customerId"/> +</many-to-one>]]></programlisting> + + <para> + (Note que a tag <literal>&lt;column&gt;</literal> é uma alternativa para o + atributo <literal>column</literal> por toda a parte.) + + + </para> + + <para> + Uma associação <literal>many-to-many</literal> para <literal>many-to-many</literal> + também usa a chave estrangeira composta: + </para> + + <programlisting><![CDATA[<set name="undeliveredOrderLines"> + <key column name="warehouseId"/> + <many-to-many class="OrderLine"> + <column name="lineId"/> + <column name="orderId"/> + <column name="customerId"/> + </many-to-many> +</set>]]></programlisting> + + <para> + A collection de <literal>OrderLine</literal>s em <literal>Order</literal> usaria: + </para> + + <programlisting><![CDATA[<set name="orderLines" inverse="true"> + <key> + <column name="orderId"/> + <column name="customerId"/> + </key> + <one-to-many class="OrderLine"/> +</set>]]></programlisting> + + <para> + (O elemento <literal>&lt;one-to-many&gt;</literal>, como de costume, não declara colunas.) + + + </para> + + <para> + Se <literal>OrderLine</literal> possui uma collection, ela também tem uma + chave estrangeira composta. + </para> + + <programlisting><![CDATA[<class name="OrderLine"> + .... + .... + <list name="deliveryAttempts"> + <key> <!-- a collection inherits the composite key type --> + <column name="lineId"/> + <column name="orderId"/> + <column name="customerId"/> + </key> + <list-index column="attemptId" base="1"/> + <composite-element class="DeliveryAttempt"> + ... + </composite-element> + </set> +</class>]]></programlisting> + + </sect1> + + <sect1 id="components-dynamic" revision="1"> + <title>Componentes Dinâmicos</title> + + <para> + Você pode até mesmo mapear uma propriedade do tipo <literal>Map</literal>: + </para> + + <programlisting><![CDATA[<dynamic-component name="userAttributes"> + <property name="foo" column="FOO" type="string"/> + <property name="bar" column="BAR" type="integer"/> + <many-to-one name="baz" class="Baz" column="BAZ_ID"/> +</dynamic-component>]]></programlisting> + + <para> + A semântica de um mapeamento <literal>&lt;dynamic-component&gt;</literal> é idêntica + à <literal>&lt;component&gt;</literal>. A vantagem deste tipo de mapeamento é a + habilidade de determinar as propriedades atuais do bean no momento de deploy, + apenas editando o documento de mapeamento. A Manipulação em tempo de execução do + documento de mapeamento também é possível, usando o parser DOM. Até melhor, + você pode acessar (e mudar) o metamodelo configuration-time do Hibernate + através do objeto <literal>Configuration</literal>. + </para> + + </sect1> + +</chapter> Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/configuration.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/configuration.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/configuration.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/configuration.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,1789 @@ +<chapter id="session-configuration" revision="1"> + + <title>Configuração</title> + + <para> + Devido ao fato de o Hibernate ser projetado para operar em vários ambientes diferentes, + há um grande número de parâmetros de configuração. Felizmente, a maioria tem valores default + lógicos e o Hibernate é distribuído com um arquivo <literal>hibernate.properties</literal> + de exemplo no <literal>etc/</literal> que mostra várias opções. Apenas coloque o arquivo + de exemplo no seu classpath e personalize-o. + </para> + + <sect1 id="configuration-programmatic" revision="1"> + <title>1.11 Configuração programática</title> + + <para> + Uma instância de <literal>org.hibernate.cfg.Configuration</literal> + representa um conjunto inteiro de mapeamentos de tipos Java da aplicação para + um banco de dados SQL. O <literal>Configuration</literal> é usado para construir + uma <literal>SessionFactory</literal> (imutável). Os mapeamentos são compilados + a partir de arquivos de mapeamento XML. + + </para> + + <para> + Você pode obter uma instância <literal>Configuration</literal> intanciando- + o diretamente e especificando documentos de mapeamento XML. Se o arquivo + de mapeamento estão no classpath, use use <literal>addResource()</literal>: + </para> + + <programlisting><![CDATA[Configuration cfg = new Configuration() + .addResource("Item.hbm.xml") + .addResource("Bid.hbm.xml");]]></programlisting> + + <para> + Uma alternativa (às vezes melhor) é especificar a classe mapeada, + e permitir que o Hibernate encontre o documento de mapeamento para você: + </para> + + <programlisting><![CDATA[Configuration cfg = new Configuration() + .addClass(org.hibernate.auction.Item.class) + .addClass(org.hibernate.auction.Bid.class);]]></programlisting> + + <para> + Então o Hibernate procurará pelos arquivos de mapeamento chamados + <literal>/org/hibernate/auction/Item.hbm.xml</literal> e + <literal>/org/hibernate/auction/Bid.hbm.xml</literal> no classpath. + Esta abordagem elimina qualquer nome de arquivo de difícil compreensão. + </para> + + <para> + Uma <literal>Configuration</literal> também permite você especificar + propriedades de configuração: + </para> + + <programlisting><![CDATA[Configuration cfg = new Configuration() + .addClass(org.hibernate.auction.Item.class) + .addClass(org.hibernate.auction.Bid.class) + .setProperty("hibernate.dialect", "org.hibernate.dialect.MySQLInnoDBDialect") + .setProperty("hibernate.connection.datasource", "java:comp/env/jdbc/test") + .setProperty("hibernate.order_updates", "true");]]></programlisting> + + <para> + Este não é o único caminho para passar as propriedades de configuração + para o Hibernate. As várias opções incluem: + </para> + + <orderedlist spacing="compact"> + <listitem> + <para> + Passar uma instância de <literal>java.util.Properties</literal> + para <literal>Configuration.setProperties()</literal>. + </para> + </listitem> + <listitem> + <para> + Colocar <literal>hibernate.properties</literal> no diretório + raiz do classpath. + </para> + </listitem> + <listitem> + <para> + Determinar as propriedades do <literal>System</literal> + usando <literal>java -Dproperty=value</literal>. + </para> + </listitem> + <listitem> + <para> + Include <literal>&lt;property&gt;</literal> elements in + <literal>hibernate.cfg.xml</literal> (discussed later). + Incluir elementos <literal>&lt;property&gt;</literal> no + <literal>hibernate.cfg.xml</literal> (discutido mais tarde). + </para> + </listitem> + </orderedlist> + + <para> + <literal>hibernate.properties</literal> é o caminho mais facil + se você quer começar mais rápido. + </para> + + <para> + O <literal>Configuration</literal> é entendido como um objeto startup-time, + é descartado uma vez que a <literal>SessionFactory</literal> é criada. + </para> + + </sect1> + + <sect1 id="configuration-sessionfactory"> + <title>Obtendo uma SessionFactory</title> + + <para> + Quando todos os mapeamentos têm sido analisados pelo <literal>Configuration</literal>, + a aplicação deve obter uma factory para as instâncias da <literal>Session</literal>. + O objetivo desta factory é ser compartilhado por todas as threads da aplicação: + </para> + + <programlisting><![CDATA[SessionFactory sessions = cfg.buildSessionFactory();]]></programlisting> + + <para> + Hibernate permite sua aplicação instanciar mais do que uma + <literal>SessionFactory</literal>. Isto é útil se você está usando mais + do que um banco de dados. + </para> + + </sect1> + + <sect1 id="configuration-hibernatejdbc" revision="1"> + <title>Conexões JDBC</title> + + <para> + Normalmente, você quer mandar criar a <literal>SessionFactory</literal> criar um + pool de conexões JDBC para você. Se você seguir essa abordagem, a abertura de uma + <literal>Session</literal> é tão simples quanto: + + </para> + + <programlisting><![CDATA[Session session = sessions.openSession(); // open a new Session]]></programlisting> + + <para> + Assim que você fizer algo que requer o acesso ao banco de dados, uma + conexão JDBC será obtida do pool. + </para> + + <para> + Para esse trabalho, nós necessitamos passar algumas propriedades da conexão JDBC + para o Hibernate. Todos os nomes de propriedades Hibernate e semânticas são definidas + <literal>org.hibernate.cfg.Environment</literal>. Nós iremos descrever agora + o mais importantes configurações de conexão JDBC. + </para> + + <para> + O Hibernate obterá conexões( e pool) usando <literal>java.sql.DriverManager</literal> + se você determinar as seguintes propriedades: + </para> + + <table frame="topbot"> + <title>Propriedades JDBC Hibernate</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="1*"/> + <thead> + <row> + <entry>Nome da Propriedade</entry> + <entry>Propósito</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>hibernate.connection.driver_class</literal> + </entry> + <entry> + <emphasis>Classe driver jdbc</emphasis> + </entry> + </row> + <row> + <entry> + <literal>hibernate.connection.url</literal> + </entry> + <entry> + <emphasis>URL jdbc</emphasis> + </entry> + </row> + <row> + <entry> + <literal>hibernate.connection.username</literal> + </entry> + <entry> + <emphasis>Usuário do banco de dados</emphasis> + </entry> + </row> + <row> + <entry> + <literal>hibernate.connection.password</literal> + </entry> + <entry> + <emphasis>Senha do usuário do banco de dados</emphasis> + </entry> + </row> + <row> + <entry> + <literal>hibernate.connection.pool_size</literal> + </entry> + <entry> + <emphasis>Número máximo de connecxões no pool</emphasis> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + O algoritmo de pool de conexões do próprio Hibernate entretanto é completamente + rudimentar. A intenção dele e ajudar a iniciar e <emphasis>não para usar em um + sistema de produção</emphasis> ou até para testar desempenho. Você deveria usar + uma ferramente de pool de terceiros para conseguir melhor desempenho e estabilidade. + Apenas especifique a propriedade <literal>hibernate.connection.pool_size</literal> + com a definição do pool de conexões. Isto irá desligar o pool interno do Hibernate. + Por exemplo, você pode gostar de usar C3P0. + </para> + + <para> + O C3P0 é um pool conexão JDBC de código aberto distribuído junto com + Hibernate no diretório <literal>lib</literal>. O Hibernate usará o + <literal>C3P0ConnectionProvider</literal> para o pool de conexão se + você configurar a propriedade <literal>hibernate.c3p0.*</literal>. Se você + gostar de usar Proxool consulte ao pacote <literal>hibernate.properties</literal> + e o web site do Hibernate para mais informações. + </para> + + <para> + Aqui é um exemplo de arquivo <literal>hibernate.properties</literal> para C3P0: + </para> + + <programlisting id="c3p0-configuration" revision="1"><![CDATA[hibernate.connection.driver_class = org.postgresql.Driver +hibernate.connection.url = jdbc:postgresql://localhost/mydatabase +hibernate.connection.username = myuser +hibernate.connection.password = secret +hibernate.c3p0.min_size=5 +hibernate.c3p0.max_size=20 +hibernate.c3p0.timeout=1800 +hibernate.c3p0.max_statements=50 +hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect]]></programlisting> + + <para> + Para usar dentro de um servidor de aplicação, você deve configurar + o Hibernate para obter conexões de um application server + <literal>Datasource</literal> registrado no JNDI. Você necessitará + determinar pelo menos uma das seguintes propriedades: + </para> + + <table frame="topbot"> + <title>Propriedades do Datasource do Hibernate</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="1*"/> + <thead> + <row> + <entry>Nome da Propriedade</entry> + <entry>Propósito</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>hibernate.connection.datasource</literal> + </entry> + <entry> + <emphasis>Nome datasource JNDI</emphasis> + </entry> + </row> + <row> + <entry> + <literal>hibernate.jndi.url</literal> + </entry> + <entry> + <emphasis>URL do fornecedor JNDI</emphasis> (opcional) + </entry> + </row> + <row> + <entry> + <literal>hibernate.jndi.class</literal> + </entry> + <entry> + <emphasis>Classe do JNDI <literal>InitialContextFactory</literal></emphasis> (opcional) + </entry> + </row> + <row> + <entry> + <literal>hibernate.connection.username</literal> + </entry> + <entry> + <emphasis>Usuário do banco de dados</emphasis> (opcional) + </entry> + </row> + <row> + <entry> + <literal>hibernate.connection.password</literal> + </entry> + <entry> + <emphasis>Senha do usuário do banco de dados</emphasis> (opcional) + </entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + Eis um exemplo de arquivo <literal>hibernate.properties</literal> para + um servidor de aplicação fornecedor de datasources JNDI: + </para> + + <programlisting><![CDATA[hibernate.connection.datasource = java:/comp/env/jdbc/test +hibernate.transaction.factory_class = \ + org.hibernate.transaction.JTATransactionFactory +hibernate.transaction.manager_lookup_class = \ + org.hibernate.transaction.JBossTransactionManagerLookup +hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect]]></programlisting> + + <para> + Conexões JDBC obtidas de um datasource JNDI irão automaticamente irão participar + das transações gerenciadas pelo container no servidor de aplicação. + </para> + + <para> + Arbitrariamente as propriedades de conexão podem ser acrescentandas ao + "<literal>hibernate.connnection</literal>" ao nome da propriedade. Por exemplo, + você deve especificar o <literal>charSet</literal> usando <literal>hibernate.connection.charSet</literal>.t. + </para> + + <para> + Você pode definir sua própria estratégia de plugin para obter conexões JDBC implementando + a interface <literal>org.hibernate.connection.ConnectionProvider</literal>. Você pode + escolher uma implementação customizada setando <literal>hibernate.connection.provider_class</literal>. + </para> + + </sect1> + + <sect1 id="configuration-optional" revision="1"> + <title>Propriedades opcionais de configuração</title> + + <para> + Há um grande número de outras propriedades que controlam o comportamento do Hibernate + em tempo de execução. Todos são opcionais e tem valores default lógicos. + </para> + + <para> + <emphasis>Aviso: algumas destas propriedades são somente a "nível de sistema".</emphasis> + Propriedades nível de sistema podem ser determinados somente via <literal>java -Dproperty=value</literal> + ou <literal>hibernate.properties</literal>. Elas <emphasis>não</emphasis>podem ser + configuradas por outras técnicas descritas abaixo. + </para> + + <table frame="topbot" id="configuration-optional-properties" revision="8"> + <title>Hibernate Configuration Properties</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="1*"/> + <thead> + <row> + <entry>Nome da Propriedade</entry> + <entry>Propósito</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>hibernate.dialect</literal> + </entry> + <entry> + O nome da classe de um <literal>Dialeto</literal> + que permite o Hibernate gerar SQL otimizado para um banco de + dados relacional em particular. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>full.classname.of.Dialect</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.show_sql</literal> + </entry> + <entry> + Escreve todas as instruções SQL no console. Esta é uma alternativa + a configurar a categoria de log <literal>org.hibernate.SQL</literal> + para <literal>debug</literal>. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.format_sql</literal> + </entry> + <entry> + Imprime o SQL formatado no log e console. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.default_schema</literal> + </entry> + <entry> + Qualifica no sql gerado, os nome das tabelas sem qualificar + com schena/tablespace dado + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>SCHEMA_NAME</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.default_catalog</literal> + </entry> + <entry> + Qualifica no sql gerado, os nome das tabelas sem qualificar + com catálogo dado + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>CATALOG_NAME</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.session_factory_name</literal> + </entry> + <entry> + O <literal>SessionFactory</literal> irá automaticamente + se ligar a este nome no JNDI depois de ter sido criado. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>jndi/composite/name</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.max_fetch_depth</literal> + </entry> + <entry> + Estabelece a "profundidade" máxima para árvore outer join fetch + para associações finais únicas(one-to-one,many-to-one). + Um <literal>0</literal> desativa por default a busca outer join. + <para> + <emphasis role="strong">eg.</emphasis> + Valores recomendados entre<literal>0</literal> e <literal>3</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.default_batch_fetch_size</literal> + </entry> + <entry> + Determina um tamanho default para busca de associações em lotes do Hibernate + <para> + <emphasis role="strong">eg.</emphasis> + Valores recomendados <literal>4</literal>, <literal>8</literal>, + <literal>16</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.default_entity_mode</literal> + </entry> + <entry> + Determina um modo default para representação de entidades + para todas as sessões abertas desta <literal>SessionFactory</literal> + <para> + <literal>dynamic-map</literal>, <literal>dom4j</literal>, + <literal>pojo</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.order_updates</literal> + </entry> + <entry> + Força o Hibernate a ordenar os updates SQL pelo valor da chave + primária dos itens a serem atualizados. Isto resultará em menos + deadlocks nas transações em sistemas altamente concorrente. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.generate_statistics</literal> + </entry> + <entry> + If enabled, Hibernate will collect statistics useful for + performance tuning. + Se habilitado, o Hibernate coletará estatísticas úties + para performance tuning dos bancos. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.use_identifer_rollback</literal> + </entry> + <entry> + Se habilitado, propriedades identificadoras geradas + serão zeradas para os valores default quando os + objetos forem apagados. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.use_sql_comments</literal> + </entry> + <entry> + Se ligado, o Hibernate irá gerar comentários dentro do SQL, + para facilitar o debugging, o valor default é <literal>false</literal>. + <para> + <emphasis role="strong">eg.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="topbot" id="configuration-jdbc-properties" revision="8"> + <title>JDBC Hibernate e Propriedades de Conexão</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="1*"/> + <thead> + <row> + <entry>Nome da Propriedade</entry> + <entry>Propósito</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>hibernate.jdbc.fetch_size</literal> + </entry> + <entry> + Um valor maior que zero determina o tamanho do fetch + do JDBC( chamadas <literal>Statement.setFetchSize()</literal>). + </entry> + </row> + <row> + <entry> + <literal>hibernate.jdbc.batch_size</literal> + </entry> + <entry> + Um valor maior que zero habilita uso de batch updates JDBC2 pelo Hibernate. + <para> + <emphasis role="strong">Ex.</emphasis> + valores recomentados entre <literal>5</literal> e <literal>30</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.jdbc.batch_versioned_data</literal> + </entry> + <entry> + Sete esta propriedade como <literal>true</literal> se seu driver JDBC retorna + o número correto de linhas no <literal>executeBatch()</literal> ( É usualmente + seguro tornar esta opção ligada). O Hibernate então irá usar betched DML + para automaticamente versionar dados. <literal>false</literal> por default. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.jdbc.factory_class</literal> + </entry> + <entry> + Escolher um <literal>Batcher</literal> customizado. Muitas + aplicações não irão necessitar desta propriedade de configuração + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>classname.of.BatcherFactory</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.jdbc.use_scrollable_resultset</literal> + </entry> + <entry> + Habilita o uso de JDBC2 scrollable resultsets pelo Hibernate. + Essa propriedade somente é necessaria quando se usa Conexeções + JDBC providas pelo usuário, caso contrário o Hibernate os os + metadados da conexão. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.jdbc.use_streams_for_binary</literal> + </entry> + <entry> + Use streams para escrever/ler tipos <literal>binary</literal> + ou <literal>serializable</literal> para/a o JDBC( propriedade a nível de sistema). + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.jdbc.use_get_generated_keys</literal> + </entry> + <entry> + Possibilita o uso <literal>PreparedStatement.getGeneratedKeys()</literal> + do JDBC3 para recuperar chaves geradas nativamente depois da inserçãp. + Requer driver JDBC3+ e JRE1.4+, determine para false se seu driver tem + problemas com gerador de indentificadores Hibernate. Por default, tente + determinar o driver capaz de usar metadados da conexão. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true|false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.connection.provider_class</literal> + </entry> + <entry> + O nome da classe de um <literal>ConnectionProvider</literal> personalizado + o qual proverá conexões JDBC para o Hibernate. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>classname.of.ConnectionProvider</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.connection.isolation</literal> + </entry> + <entry> + Determina o nível de isolamento de uma transação JDBC. + Verifique <literal>java.sql.Connection</literal> para valores + siginificativos mas note que a maior parte dos bancos de dados + não suportam todos os níveis de isolamento. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>1, 2, 4, 8</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.connection.autocommit</literal> + </entry> + <entry> + Habilita autocommit para conexões no pool JDBC( não recomendado). + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.connection.release_mode</literal> + </entry> + <entry> + Especifica quando o Hibernate deve liberar conexões JDBC. Por default, + uma conexão JDBC é retida até a sessão está explicitamente fechada + ou desconectada. Para um datasource JTA do servidor de aplicação, você deve + usar <literal>after_statement</literal> para forçar s liberação da conexões + depois de todas as chamadas JDBC. Para uma conexão não-JTA, freqüentemente + faz sentido liberar a conexão ao fim de cada transação, usando + <literal>after_transaction</literal>. <literal>auto</literal> escolheremos + <literal>after_statement</literal> para as estratégias de transaçãoes JTA e CMT + e <literal>after_transaction</literal> para as estratégias de transação JDBC + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>auto</literal> (default) | <literal>on_close</literal> | + <literal>after_transaction</literal> | <literal>after_statement</literal> + </para> + <para> + Note that this setting only affects <literal>Session</literal>s returned from + <literal>SessionFactory.openSession</literal>. For <literal>Session</literal>s + obtained through <literal>SessionFactory.getCurrentSession</literal>, the + <literal>CurrentSessionContext</literal> implementation configured for use + controls the connection release mode for those <literal>Session</literal>s. + See <xref linkend="architecture-current-session"/> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.connection.<emphasis>&lt;propertyName&gt;</emphasis></literal> + </entry> + <entry> + Passa a propriedade JDBC <literal>propertyName</literal> + para <literal>DriverManager.getConnection()</literal>. + </entry> + </row> + <row> + <entry> + <literal>hibernate.jndi.<emphasis>&lt;propertyName&gt;</emphasis></literal> + </entry> + <entry> + Passar a propriedade <literal>propertyName</literal> para + o <literal>InitialContextFactory</literal> JNDI. + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="topbot" id="configuration-cache-properties" revision="7"> + <title>Propriedades de Cachê do Hibernate</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="1*"/> + <thead> + <row> + <entry>Nome da Propriedade</entry> + <entry>Propósito</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>hibernate.cache.provider_class</literal> + </entry> + <entry> + O nome da classe de um <literal>CacheProvider</literal> customizado. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>classname.of.CacheProvider</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.cache.use_minimal_puts</literal> + </entry> + <entry> + Otimizar operação de cachê de segundo nível para minimizar escritas, + ao custo de leituras mais frequantes. Esta configuração é mais útil + para cachês clusterizados e, no Hibernate3, é habilitado por default + para implementações de cachê clusterizar. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true|false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.cache.use_query_cache</literal> + </entry> + <entry> + Habilita a cache de consultas, Mesmo assim, consultas individuais ainda tem que ser + habilitadas para o cache. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true|false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.cache.use_second_level_cache</literal> + </entry> + <entry> + May be used to completely disable the second level cache, which is enabled + by default for classes which specify a <literal>&lt;cache&gt;</literal> + mapping. + Pode ser usada para desabilitar completamente ocache de segundo nível, + o qual está habilitado por default para classes que especificam + um mapeamento <literal>&lt;cache&gt;</literal>. + + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true|false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.cache.query_cache_factory</literal> + </entry> + <entry> + O nome de uma classe que implementa a interface + <literal>QueryCache</literal> personalizada, por + default, um <literal>StandardQueryCache</literal> + criado automaticamente. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>classname.of.QueryCache</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.cache.region_prefix</literal> + </entry> + <entry> + Um prefixo para usar nos nomes da área especial + do cachê de segundo nível. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>prefix</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.cache.use_structured_entries</literal> + </entry> + <entry> + Forces Hibernate to store data in the second-level cache + in a more human-friendly format. + Força o Hibernate armazenar dados no cachê se segundo + nível em um formato mais legivel. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true|false</literal> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="topbot" id="configuration-transaction-properties" revision="9"> + <title>Propriedades de Transação do Hibernate</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="1*"/> + <thead> + <row> + <entry>Nome da Propriedade</entry> + <entry>Propósito</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>hibernate.transaction.factory_class</literal> + </entry> + <entry> + O nome da clase de um a <literal>TransactionFactory</literal> + para usar com API <literal>Transaction</literal> + ( por default JDBCTransactionFactory). + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>classname.of.TransactionFactory</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>jta.UserTransaction</literal> + </entry> + <entry> + Um nome JNDI usado pelo <literal>JTATransactionFactory</literal> + para obter uma <literal>UserTransaction</literal> JTA a partir + do servidor de aplicação. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>jndi/composite/name</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.transaction.manager_lookup_class</literal> + </entry> + <entry> + O nome da classe de um <literal>TransactionManagerLookup</literal> + – requerido quando caching a nível JVM esta habilitado ou quando + estivermos usando um generator hilo em um ambiente JTA. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>classname.of.TransactionManagerLookup</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.transaction.flush_before_completion</literal> + </entry> + <entry> + Se habilitado, a sessão será automaticamente limpa antes da fase de + conclusão da transação. É preferivel a gerência interna e + automática do contexto da sessão, veja + <xref linkend="architecture-current-session"/> + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.transaction.auto_close_session</literal> + </entry> + <entry> + Se habilitado, a sessão será automaticamente fechada após a fase de + conclusão da transação. É preferivel a gerência interna e + automática do contexto da sessão, veja + <xref linkend="architecture-current-session"/> + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="topbot" id="configuration-misc-properties" revision="10"> + <title>Propriedades Variadas</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"/> + <colspec colname="c2" colwidth="1*"/> + <thead> + <row> + <entry>Nome da Propriedade</entry> + <entry>Propósito</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>hibernate.current_session_context_class</literal> + </entry> + <entry> + Forneçe uma estratégia (personalizada) para extensão + da <literal>Session</literal> "corrente". Veja + <xref linkend="architecture-current-session"/> para + mais informação sobre estratégias internas. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>jta</literal> | <literal>thread</literal> | + <literal>managed</literal> | <literal>custom.Class</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.query.factory_class</literal> + </entry> + <entry> + Escolha a implementação de análise HQL. + <para> + <emphasis role="strong">eg.</emphasis> + <literal>org.hibernate.hql.ast.ASTQueryTranslatorFactory</literal> or + <literal>org.hibernate.hql.classic.ClassicQueryTranslatorFactory</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.query.substitutions</literal> + </entry> + <entry> + Mapeamento a partir de símbolos em consultas HQL para + símbolos SQL( símbolos devem ser funções ou nome literais + , por exemplo). + <para> + <emphasis role="strong">eg.</emphasis> + <literal>hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.hbm2ddl.auto</literal> + </entry> + <entry> + Automaticamente valida ou exporta schema DDL para o banco de + dados quando o <literal>SessionFactory</literal> é criads. + Com <literal>create-drop</literal>, o schema do banco de dados + será excluido quando a <literal>create-drop</literal> for + fechada esplicitamente. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>validate</literal> | <literal>update</literal> | + <literal>create</literal> | <literal>create-drop</literal> + </para> + </entry> + </row> + <row> + <entry> + <literal>hibernate.cglib.use_reflection_optimizer</literal> + </entry> + <entry> + Habilita o uso de CGLIB em vez de reflexão em tempo de execução + ( propriedade a nível de sistema). Reflexão pode algumas vezes ser ú + til quando controlar erros, note que o Hibernate sempre irá requerer a CGLIB + mesmo se você desligar o otimizador. Você não pode determinar esta + propriedade no hibernate.cfg.xml. + <para> + <emphasis role="strong">Ex.</emphasis> + <literal>true</literal> | <literal>false</literal> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <sect2 id="configuration-optional-dialects" revision="1"> + <title>Dialetos SQL</title> + + <para> + Você deve sempre determinar a propriedade <literal>hibernate.dialect</literal> + para a subclasse de <literal>org.hibernate.dialect.Dialect</literal> correta de seu + banco de dados. Se você especificar um dialeto, Hibernate usará defaults lógicos + para qualquer um das outras propriedades listadas abaixo, reduzindo o esforço de + especificá-los manualmente. + </para> + + <table frame="topbot" id="sql-dialects" revision="2"> + <title>Hibernate SQL Dialects (<literal>hibernate.dialect</literal>)</title> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="2.5*"/> + <thead> + <row> + <entry>RDBMS</entry> + <entry>Dialect</entry> + </row> + </thead> + <tbody> + <row> + <entry>DB2</entry> <entry><literal>org.hibernate.dialect.DB2Dialect</literal></entry> + </row> + <row> + <entry>DB2 AS/400</entry> <entry><literal>org.hibernate.dialect.DB2400Dialect</literal></entry> + </row> + <row> + <entry>DB2 OS390</entry> <entry><literal>org.hibernate.dialect.DB2390Dialect</literal></entry> + </row> + <row> + <entry>PostgreSQL</entry> <entry><literal>org.hibernate.dialect.PostgreSQLDialect</literal></entry> + </row> + <row> + <entry>MySQL</entry> <entry><literal>org.hibernate.dialect.MySQLDialect</literal></entry> + </row> + <row> + <entry>MySQL with InnoDB</entry> <entry><literal>org.hibernate.dialect.MySQLInnoDBDialect</literal></entry> + </row> + <row> + <entry>MySQL with MyISAM</entry> <entry><literal>org.hibernate.dialect.MySQLMyISAMDialect</literal></entry> + </row> + <row> + <entry>Oracle (any version)</entry> <entry><literal>org.hibernate.dialect.OracleDialect</literal></entry> + </row> + <row> + <entry>Oracle 9i/10g</entry> <entry><literal>org.hibernate.dialect.Oracle9Dialect</literal></entry> + </row> + <row> + <entry>Sybase</entry> <entry><literal>org.hibernate.dialect.SybaseDialect</literal></entry> + </row> + <row> + <entry>Sybase Anywhere</entry> <entry><literal>org.hibernate.dialect.SybaseAnywhereDialect</literal></entry> + </row> + <row> + <entry>Microsoft SQL Server</entry> <entry><literal>org.hibernate.dialect.SQLServerDialect</literal></entry> + </row> + <row> + <entry>SAP DB</entry> <entry><literal>org.hibernate.dialect.SAPDBDialect</literal></entry> + </row> + <row> + <entry>Informix</entry> <entry><literal>org.hibernate.dialect.InformixDialect</literal></entry> + </row> + <row> + <entry>HypersonicSQL</entry> <entry><literal>org.hibernate.dialect.HSQLDialect</literal></entry> + </row> + <row> + <entry>Ingres</entry> <entry><literal>org.hibernate.dialect.IngresDialect</literal></entry> + </row> + <row> + <entry>Progress</entry> <entry><literal>org.hibernate.dialect.ProgressDialect</literal></entry> + </row> + <row> + <entry>Mckoi SQL</entry> <entry><literal>org.hibernate.dialect.MckoiDialect</literal></entry> + </row> + <row> + <entry>Interbase</entry> <entry><literal>org.hibernate.dialect.InterbaseDialect</literal></entry> + </row> + <row> + <entry>Pointbase</entry> <entry><literal>org.hibernate.dialect.PointbaseDialect</literal></entry> + </row> + <row> + <entry>FrontBase</entry> <entry><literal>org.hibernate.dialect.FrontbaseDialect</literal></entry> + </row> + <row> + <entry>Firebird</entry> <entry><literal>org.hibernate.dialect.FirebirdDialect</literal></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2 id="configuration-optional-outerjoin" revision="4"> + <title>Recuperação por união externa (Outer Join Fetching)</title> + + <para> + Se seu banco de dados suporta Recuperação por união externa (Outer Join Fetching) no estilo ANSI, + Oracle ou Sybase, A recuperação por união externa (Outer Join Fetching) frequentemente aumentará + o desempenho limitando o número de chamadas (round trips) ao banco de dados( ao custo de + possivelmente mais trabalho desempenhado pelo próprio banco de dados). A recuperação por + união externa (Outer Join Fetching)permite um gráfico completo de objetos conectados + por muitos-para-um, um-para-muitos, muitos-para-muitos e associações um-para-um para ser + recuperadas em um simples instrução SQL SELECT . + + </para> + + <para> + A recuperação por união externa (Outer Join Fetching) pode ser desabilitado + <emphasis>globalmente</emphasis> setando a propriedade + <literal>hibernate.max_fetch_depth</literal> para <literal>0</literal>. + Uma valor 1 ou maior habilita o outer join fetching para associações um-para-um + e muitos-para-umos cujos quais tem sido mapeado com <literal>fetch="join"</literal>. + </para> + + <para> + Veja <xref linkend="performance-fetching"/> para mais informações. + </para> + + </sect2> + + <sect2 id="configuration-optional-binarystreams" revision="1"> + <title>Fluxos Binários (Binary Streams)</title> + + <para> + O Oracle limita o tamanho de arrays de <literal>byte</literal> que pode ser + passado para/de o driver JDBC. Se você desejar usar grandes instâncias de + tipos <literal>binary</literal> ou <literal>serializable</literal>, você + deve habilitar <literal>hibernate.jdbc.use_streams_for_binary</literal>. + <emphasis>Essa é uma configuração que só pode ser feita a nível de sistema.</emphasis> + </para> + + </sect2> + + <sect2 id="configuration-optional-cacheprovider" revision="2"> + <title>Cachê de segundo nível e query</title> + + <para> + As propriedades prefixadas pelo <literal>hibernate.cache</literal> + permite você usar um sistema de cachê de segundo nível + em um processo executado em clustercom Hibernate. + Veja <xref linkend="performance-cache"/> para mais detalhes. + </para> + + </sect2> + + <sect2 id="configuration-optional-querysubstitution"> + <title>Substituições na Linguagem de Consulta</title> + + <para> + Você pode definir novos símbolos de consulta Hibernate usando + <literal>hibernate.query.substitutions</literal>. + Por exemplo: + </para> + + <programlisting>hibernate.query.substitutions true=1, false=0</programlisting> + + <para> + Faria com que os símbolos <literal>true</literal> e <literal>false</literal> + passasem a ser traduzidos para literais inteiro no SQL gerado. + </para> + + <programlisting>hibernate.query.substitutions toLowercase=LOWER</programlisting> + + <para> + permitirá você renomear a função <literal>LOWER</literal> no SQL. + </para> + + </sect2> + + <sect2 id="configuration-optional-statistics" revision="2"> + <title>Estatísticas do Hibernate</title> + + <para> + If you enable <literal>hibernate.generate_statistics</literal>, Hibernate will + expose a number of metrics that are useful when tuning a running system via + <literal>SessionFactory.getStatistics()</literal>. Hibernate can even be configured + to expose these statistics via JMX. Read the Javadoc of the interfaces in + <literal>org.hibernate.stats</literal> for more information. + + Se você habilitar <literal>hibernate.generate_statistics</literal>, o Hibernate + exibirá um número de métricas bastante útil ao ajustar um sistema via + <literal>SessionFactory.getStatistics()</literal>. O Hibernate pode até ser + configurado para exibir essas estatísticas via JMX. Leia o Javadoc da interface + <literal>org.hibernate.stats</literal> para mais informações. + </para> + + </sect2> + </sect1> + + <sect1 id="configuration-logging"> + <title>Logging</title> + + <para> + Hibernate registra vários eventos usando Apache commons-logging. + </para> + + <para> + O serviço commons-logging direcionará a saída para o Apache Log4j + ( se você incluir <literal>log4j.jar</literal>r no seu classpath) ou + JDK1.4 logging( se estiver em uso JDK1.4 ou maior). Você pode fazer o + download do Log4j a partir de <literal>http://jakarta.apache.org</literal>. + Para usar Log4j você necessitará colocar um arquivo + <literal>log4j.properties</literal> no seu classpath, um exemplo de arquivo + de propriedades é distribuído com o Hibernate no diretório + <literal>src/</literal>. + + </para> + + <para> + We strongly recommend that you familiarize yourself with Hibernate's log + messages. A lot of work has been put into making the Hibernate log as + detailed as possible, without making it unreadable. It is an essential + troubleshooting device. The most interesting log categories are the + following: + + Nós recomendamos enfaticamente que você se familiarize-se com mensagens de + log do Hibernate. Uma parte do trabalho tem sido posto em fazer o log + Hibernate tão detalhado quanto possível, sem fazê-lo ilegível. + É um essencial dispositivos de controle de erros. As categorias de log + mais interessantes são as seguintes: + </para> + + <table frame="topbot" id="log-categories" revision="2"> + <title>Categorias de Log do Hibernate</title> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="2.5*"/> + <thead> + <row> + <entry>Categoria</entry> + <entry>Função</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>org.hibernate.SQL</literal></entry> + <entry>Registra todas as instruções SQL DML a medida que elas são executadas</entry> + </row> + <row> + <entry><literal>org.hibernate.type</literal></entry> + <entry>Registra todos os parâmetros JDBC</entry> + </row> + <row> + <entry><literal>org.hibernate.tool.hbm2ddl</literal></entry> + <entry>Registra todas as instruções SQL DDL a medida que elas são executadas</entry> + </row> + <row> + <entry><literal>org.hibernate.pretty</literal></entry> + <entry> + Log the state of all entities (max 20 entities) associated + with the session at flush time + Registra o estado de todas as entidades (máximo 20 entidades) + associadas a session no momento da limpeza (flush). + </entry> + </row> + <row> + <entry><literal>org.hibernate.cache</literal></entry> + <entry>Registra todas as atividades de cachê de segundo nível</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction</literal></entry> + <entry>Registra atividades relacionada a transação</entry> + </row> + <row> + <entry><literal>org.hibernate.jdbc</literal></entry> + <entry>Registra todas as requisições de recursos JDBC</entry> + </row> + <row> + <entry><literal>org.hibernate.hql.ast.AST</literal></entry> + <entry> + Registra instruções SQL e HQL durante a análise da consultas + </entry> + </row> + <row> + <entry><literal>org.hibernate.secure</literal></entry> + <entry>Registra todas as requisições de autorização JAAS</entry> + </row> + <row> + <entry><literal>org.hibernate</literal></entry> + <entry> + Registra tudo ( uma parte das informações, mas muito + útil para controle de erros ) + </entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + Quando desenvolver aplicações com Hibernate, você deve quase sempre trabalhar com + debug <literal>debug</literal> para a categoria <literal>org.hibernate.SQL</literal>, + ou, alternativamente, a com a propriedade <literal>hibernate.show_sql</literal> habilitada. + </para> + + + </sect1> + + <sect1 id="configuration-namingstrategy"> + <title>Implementado uma <literal>NamingStrategy</literal></title> + + <para> + A interface <literal>org.hibernate.cfg.NamingStrategy</literal> permite você + especificar um "padrão de nomeação" para objetos do banco de dados e elementos schema. + </para> + + <para> + Você deve criar regras para a geração automaticamente de identificadores + do banco de dados a partir de identificadores Java ou para processar + colunas "computadas" e nomes de tabelas dado o arquivo de mapeamento + para nomes "físicos" de tabelas e colunas. Esta característica ajuda a + reduzir a verbosidade do documento de mapeamento, eliminando interferências + repetitivas( <literal>TBL_</literal>prefixos, por exemplo). A estratégia + default usada pelo Hibernate é completamente mínima. + </para> + + <para> + Você pode especificar uma estratégia diferente ao chamar + <literal>Configuration.setNamingStrategy()</literal> antes de adicionar + os mapeamentos: + </para> + + <programlisting><![CDATA[SessionFactory sf = new Configuration() + .setNamingStrategy(ImprovedNamingStrategy.INSTANCE) + .addFile("Item.hbm.xml") + .addFile("Bid.hbm.xml") + .buildSessionFactory();]]></programlisting> + + <para> + <literal>org.hibernate.cfg.ImprovedNamingStrategy</literal> é uma estratégia + interna que pode ser um ponto de começo útil para algumas aplicações. + </para> + + </sect1> + + <sect1 id="configuration-xmlconfig" revision="2"> + <title>Arquivo de configuração XML</title> + + <para> + Uma maneira alternativa de configuração é especificar uma configuração completa + em um arquivo chamado <literal>hibernate.cfg.xml</literal>. Este arquivo pode + ser usado como um substituto para o arquivo <literal>hibernate.properties</literal> + ou, se ambos estão presentes, sobrescrever propriedades. + </para> + + <para> + The XML configuration file is by default expected to be in the root o + your <literal>CLASSPATH</literal>. Here is an example: + O arquivo XML de configuração é por default esperado para estar na + raiz do seu <literal>CLASSPATH</literal>. Veja um exemplo: + </para> + + <programlisting><![CDATA[<?xml version='1.0' encoding='utf-8'?> +<!DOCTYPE hibernate-configuration PUBLIC + "-//Hibernate/Hibernate Configuration DTD//EN" + "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd"> + +<hibernate-configuration> + + <!-- a SessionFactory instance listed as /jndi/name --> + <session-factory + name="java:hibernate/SessionFactory"> + + <!-- properties --> + <property name="connection.datasource">java:/comp/env/jdbc/MyDB</property> + <property name="dialect">org.hibernate.dialect.MySQLDialect</property> + <property name="show_sql">false</property> + <property name="transaction.factory_class"> + org.hibernate.transaction.JTATransactionFactory + </property> + <property name="jta.UserTransaction">java:comp/UserTransaction</property> + + <!-- mapping files --> + <mapping resource="org/hibernate/auction/Item.hbm.xml"/> + <mapping resource="org/hibernate/auction/Bid.hbm.xml"/> + + <!-- cache settings --> + <class-cache class="org.hibernate.auction.Item" usage="read-write"/> + <class-cache class="org.hibernate.auction.Bid" usage="read-only"/> + <collection-cache collection="org.hibernate.auction.Item.bids" usage="read-write"/> + + </session-factory> + +</hibernate-configuration>]]></programlisting> + + <para> + Como você pode ver, a vantagem deste enfoque é a externalização dos nomes dos + arquivos de mapeamento para configuração. O <literal>hibernate.cfg.xml</literal> + também é mais conveniente caso você tenha que ajustar o cache do Hibernate. + Note que a escolha é sua em usar <literal>hibernate.properties</literal> ou + <literal>hibernate.cfg.xml</literal>, ambos são equivalente, à exceção dos benefícios + acima mencionados de usar a sintaxe de XML. + </para> + + <para> + Com a configuração do XML, iniciar o Hibernate é então tão simples como + </para> + + <programlisting><![CDATA[SessionFactory sf = new Configuration().configure().buildSessionFactory();]]></programlisting> + + <para> + You can pick a different XML configuration file using + </para> + + <programlisting><![CDATA[SessionFactory sf = new Configuration() + .configure("catdb.cfg.xml") + .buildSessionFactory();]]></programlisting> + + </sect1> + + <sect1 id="configuration-j2ee" revision="1"> + <title>Integração com servidores de aplicação J2EE</title> + + <para> + O Hibernate tem os seguintes pontos da integração para o infraestrutura de J2EE: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>DataSources gerenciados pelo container</emphasis>: O Hibernate pode + usar conexões JDBC gerenciadas pelo Container e fornecidas pela JNDI. Geralmente, + um <literal>TransactionManager</literal> compatível com JTA e um + <literal>ResourceManager</literal> cuidam do gerenciamento da transação ( CMT ), + especialmente em transações distribuídas manipuladas através de vários DataSources. + Naturalmente, você também pode demarcar os limites das transações programaticamente (BMT) + ou você poderia querer usar a API opcional do Hibernate <literal>Transaction</literal> + para esta manter seu código portável. + </para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para> + <emphasis>Ligação (binding) automática a JNDI</emphasis>: O Hibernate pode + associar sua <literal>SessionFactory</literal> a JNDI depois de iniciado. + </para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para> + <emphasis>Ligação (binding) Session na JTA:</emphasis> + A <literal>Session</literal> do Hibernate pode automaticamente ser ligada + ao escopo da transações JTA. Simplesmente localizando a <literal>SessionFactory</literal> + da JNDI e obtendo a<literal>Session</literal> corrente. Deixe o Hibernate cuidar + da limpeza e encerramento da <literal>Session</literal> quando as transações JTA + terminarem. A Demarcação de transação pode ser declarativa (CMT) ou + programática(BMT/Transação do usuário). + </para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para> + <emphasis>JMX deployment:</emphasis> Se você usa um JMX servidor de + aplicações capaz (ex. Jboss AS), você pode fazer a instação do Hibernate + como um Mbean controlado. Isto evita ter que iniciar uma linha de + código para construir sua <literal>SessionFactory</literal> de uma + <literal>Configuration</literal>. O container iniciará seu + <literal>HibernateService</literal>, e idealmente também cuidará + das dependências de serviços (DataSources, têm que estar disponíveis + antes do Hibernate iniciar, etc.). + </para> + </listitem> + </itemizedlist> + + <para> + Dependendo em seu ambiente, você poderia ter que ajustar a opção de configuração + <literal>hibernate.connection.aggressive_release</literal> para verdadeiro ( true ), + se seu servidor de aplicações lançar exeções "retenção de conecção". + </para> + + <sect2 id="configuration-optional-transactionstrategy" revision="3"> + <title>Configuração de estratégia de transação</title> + + <para> + A API Hibernate <literal>Session</literal> é independente de qualquer sistema de + demarcação de transação em sua arquitetura. Se você deixar o Hibernate usar + a JDBC diretamente, através de um pool de conexões, você pode inicializar e + encerrar suas transações chamando a API JDBC. Se você rodar em um servidor de + aplicações J2EE, você poderá usar transações controladas por beans e chamar + a API JTA e <literal>UserTransaction</literal> quando necessário. + + </para> + + <para> + Para manter seu código portável entre estes dois ( e outros ) ambientes, recomendamos + a API Hibernate <literal>Transaction</literal>, que envolve e esconde o sistema subjacente. + Você tem que especificar um classe construtora para <literal>Transaction</literal> instanciar + ajustando a propriedade de configuração do <literal>hibernate.transaction.factory_class</literal>. + + </para> + + <para> + Existem três escolhas (internas) padrões: + </para> + + <variablelist spacing="compact"> + <varlistentry> + <term><literal>org.hibernate.transaction.JDBCTransactionFactory</literal></term> + <listitem> + <para>delegada as transações (JDBC)a bases de dados (Padrão)</para> + + </listitem> + </varlistentry> + <varlistentry> + <term><literal>org.hibernate.transaction.JTATransactionFactory</literal></term> + <listitem> + <para> + delegada a transação a um container gerenciador se a transação + existente estiver de acordo neste contexto (ex: método bean sessão EJB), + se não uma nova transação é iniciada e uma transação controlado por + um bean é usada. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>org.hibernate.transaction.CMTTransactionFactory</literal></term> + <listitem> + <para>delega para um container gerenciador de transações JTA</para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Você também pode definir suas próprias estratégias de transação ( para um serviço de + transação CORBA por exemplo). + </para> + + <para> + Algumas características no Hibernate (ex., o cache de segundo nível, sessões contextuais + com JTA, etc.) requerem acesso a JTA <literal>TransactionManager</literal> em um ambiente + controlado. Em um servidor de aplicação você tem que especificar como o Hibernate pode + obter uma referência para a <literal>TransactionManager</literal>, pois o J2EE não + padronize um mecanismo simples : + </para> + + <table frame="topbot" id="jtamanagerlookup" revision="1"> + <title>Gerenciadores de transações JTA</title> + <tgroup cols="2"> + <colspec colwidth="2.5*"/> + <colspec colwidth="1*"/> + <thead> + <row> + <entry>Transaction Factory</entry> + <entry align="center">Application Server</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>org.hibernate.transaction.JBossTransactionManagerLookup</literal></entry> + <entry align="center">JBoss</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.WeblogicTransactionManagerLookup</literal></entry> + <entry align="center">Weblogic</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.WebSphereTransactionManagerLookup</literal></entry> + <entry align="center">WebSphere</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.WebSphereExtendedJTATransactionLookup</literal></entry> + <entry align="center">WebSphere 6</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.OrionTransactionManagerLookup</literal></entry> + <entry align="center">Orion</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.ResinTransactionManagerLookup</literal></entry> + <entry align="center">Resin</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.JOTMTransactionManagerLookup</literal></entry> + <entry align="center">JOTM</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.JOnASTransactionManagerLookup</literal></entry> + <entry align="center">JOnAS</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.JRun4TransactionManagerLookup</literal></entry> + <entry align="center">JRun4</entry> + </row> + <row> + <entry><literal>org.hibernate.transaction.BESTransactionManagerLookup</literal></entry> + <entry align="center">Borland ES</entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2 id="configuration-optional-jndi" revision="3"> + <title><literal>SessionFactory</literal> ligada a JNDI</title> + + <para> + Uma <literal>SessionFactory</literal> de Hibernate ligada a JNDI pode simplificar + a localização da fabrica e a criação de novas <literal>Session</literal>s. + Observe que isto não relacionado a um <literal>Datasource</literal> ligado + a JNDI, simplemente ambos usam o mesmo registro! + </para> + + <para> + If you wish to have the <literal>SessionFactory</literal> bound to a JNDI namespace, specify + a name (eg. <literal>java:hibernate/SessionFactory</literal>) using the property + <literal>hibernate.session_factory_name</literal>. If this property is omitted, the + <literal>SessionFactory</literal> will not be bound to JNDI. (This is especially useful in + environments with a read-only JNDI default implementation, e.g. Tomcat.) + </para> + + <para> + When binding the <literal>SessionFactory</literal> to JNDI, Hibernate will use the values of + <literal>hibernate.jndi.url</literal>, <literal>hibernate.jndi.class</literal> to instantiate + an initial context. If they are not specified, the default <literal>InitialContext</literal> + will be used. + </para> + + <para> + Hibernate will automatically place the <literal>SessionFactory</literal> in JNDI after + you call <literal>cfg.buildSessionFactory()</literal>. This means you will at least have + this call in some startup code (or utility class) in your application, unless you use + JMX deployment with the <literal>HibernateService</literal> (discussed later). + </para> + + <para> + If you use a JNDI <literal>SessionFactory</literal>, an EJB or any other class may + obtain the <literal>SessionFactory</literal> using a JNDI lookup. + </para> + + <para> + We recommend that you bind the <literal>SessionFactory</literal> to JNDI in + a managend environment and use a <literal>static</literal> singleton otherwise. + To shield your application code from these details, we also recommend to hide the + actual lookup code for a <literal>SessionFactory</literal> in a helper class, + such as <literal>HibernateUtil.getSessionFactory()</literal>. Note that such a + class is also a convenient way to startup Hibernate&mdash;see chapter 1. + </para> + + </sect2> + + <sect2 id="configuration-j2ee-currentsession" revision="4"> + <title>Current Session context management with JTA</title> + + <para> + The easiest way to handle <literal>Session</literal>s and transactions is + Hibernates automatic "current" <literal>Session</literal> management. + See the discussion of <xref linkend="architecture-current-session">current sessions</xref>. + Using the <literal>"jta"</literal> session context, if there is no Hibernate + <literal>Session</literal> associated with the current JTA transaction, one will + be started and associated with that JTA transaction the first time you call + <literal>sessionFactory.getCurrentSession()</literal>. The <literal>Session</literal>s + retrieved via <literal>getCurrentSession()</literal> in <literal>"jta"</literal> context + will be set to automatically flush before the transaction completes, close + after the transaction completes, and aggressively release JDBC connections + after each statement. This allows the <literal>Session</literal>s to + be managed by the life cycle of the JTA transaction to which it is associated, + keeping user code clean of such management concerns. Your code can either use + JTA programmatically through <literal>UserTransaction</literal>, or (recommended + for portable code) use the Hibernate <literal>Transaction</literal> API to set + transaction boundaries. If you run in an EJB container, declarative transaction + demarcation with CMT is preferred. + </para> + + </sect2> + + <sect2 id="configuration-j2ee-jmx" revision="1"> + <title>JMX deployment</title> + + <para> + The line <literal>cfg.buildSessionFactory()</literal> still has to be executed + somewhere to get a <literal>SessionFactory</literal> into JNDI. You can do this + either in a <literal>static</literal> initializer block (like the one in + <literal>HibernateUtil</literal>) or you deploy Hibernate as a <emphasis>managed + service</emphasis>. + </para> + + <para> + Hibernate is distributed with <literal>org.hibernate.jmx.HibernateService</literal> + for deployment on an application server with JMX capabilities, such as JBoss AS. + The actual deployment and configuration is vendor specific. Here is an example + <literal>jboss-service.xml</literal> for JBoss 4.0.x: + </para> + + <programlisting><![CDATA[<?xml version="1.0"?> +<server> + +<mbean code="org.hibernate.jmx.HibernateService" + name="jboss.jca:service=HibernateFactory,name=HibernateFactory"> + + <!-- Required services --> + <depends>jboss.jca:service=RARDeployer</depends> + <depends>jboss.jca:service=LocalTxCM,name=HsqlDS</depends> + + <!-- Bind the Hibernate service to JNDI --> + <attribute name="JndiName">java:/hibernate/SessionFactory</attribute> + + <!-- Datasource settings --> + <attribute name="Datasource">java:HsqlDS</attribute> + <attribute name="Dialect">org.hibernate.dialect.HSQLDialect</attribute> + + <!-- Transaction integration --> + <attribute name="TransactionStrategy"> + org.hibernate.transaction.JTATransactionFactory</attribute> + <attribute name="TransactionManagerLookupStrategy"> + org.hibernate.transaction.JBossTransactionManagerLookup</attribute> + <attribute name="FlushBeforeCompletionEnabled">true</attribute> + <attribute name="AutoCloseSessionEnabled">true</attribute> + + <!-- Fetching options --> + <attribute name="MaximumFetchDepth">5</attribute> + + <!-- Second-level caching --> + <attribute name="SecondLevelCacheEnabled">true</attribute> + <attribute name="CacheProviderClass">org.hibernate.cache.EhCacheProvider</attribute> + <attribute name="QueryCacheEnabled">true</attribute> + + <!-- Logging --> + <attribute name="ShowSqlEnabled">true</attribute> + + <!-- Mapping files --> + <attribute name="MapResources">auction/Item.hbm.xml,auction/Category.hbm.xml</attribute> + +</mbean> + +</server>]]></programlisting> + + <para> + This file is deployed in a directory called <literal>META-INF</literal> and packaged + in a JAR file with the extension <literal>.sar</literal> (service archive). You also need + to package Hibernate, its required third-party libraries, your compiled persistent classes, + as well as your mapping files in the same archive. Your enterprise beans (usually session + beans) may be kept in their own JAR file, but you may include this EJB JAR file in the + main service archive to get a single (hot-)deployable unit. Consult the JBoss AS + documentation for more information about JMX service and EJB deployment. + </para> + + </sect2> + + </sect1> + +</chapter> + Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/events.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/events.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/events.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/events.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,271 @@ +<chapter id="events"> + <title>Interceptadores e Eventos</title> + + <para> + É muito útil quando a aplicação precisa executar alguma "coisa" no momento em + que o Hibernate executa uma de suas ações. Isso permite a implementação de + certas funções genéricas, assim como permite estender as funcionalidades do + Hibernate + </para> + + <sect1 id="objectstate-interceptors" revision="3"> + <title>Interceptadores</title> + + <para> + A interface <literal>Interceptor</literal> permite fornecer informações da session para o + aplicativo, permitindo ao aplicativo inspecionar e/ou manipular as propriedades de um + objeto persistente antes de ser salvo, atualizado, excluído ou salvo. Um dos possíveis usos é + gerar informações de auditoria. Por exemplo, o seguinte <literal>Interceptor</literal> seta + automaticamente o atributo <literal>createTimestamp</literal> quando um + <literal>Auditable</literal> é criada e atualiza o atributo <literal>lastUpdateTimestamp</literal> + quando um <literal>Auditable</literal> é atualizado. + </para> + + <para> + Você pode implementar <literal>Auditable</literal> diretamente ou pode estender + <literal>EmptyInterceptor</literal>, sendo que a segunda é considerada a melhor opção. + </para> + + <programlisting><![CDATA[package org.hibernate.test; + +import java.io.Serializable; +import java.util.Date; +import java.util.Iterator; + +import org.hibernate.EmptyInterceptor; +import org.hibernate.Transaction; +import org.hibernate.type.Type; + +public class AuditInterceptor extends EmptyInterceptor { + + private int updates; + private int creates; + private int loads; + + public void onDelete(Object entity, + Serializable id, + Object[] state, + String[] propertyNames, + Type[] types) { + // do nothing + } + + public boolean onFlushDirty(Object entity, + Serializable id, + Object[] currentState, + Object[] previousState, + String[] propertyNames, + Type[] types) { + + if ( entity instanceof Auditable ) { + updates++; + for ( int i=0; i < propertyNames.length; i++ ) { + if ( "lastUpdateTimestamp".equals( propertyNames[i] ) ) { + currentState[i] = new Date(); + return true; + } + } + } + return false; + } + + public boolean onLoad(Object entity, + Serializable id, + Object[] state, + String[] propertyNames, + Type[] types) { + if ( entity instanceof Auditable ) { + loads++; + } + return false; + } + + public boolean onSave(Object entity, + Serializable id, + Object[] state, + String[] propertyNames, + Type[] types) { + + if ( entity instanceof Auditable ) { + creates++; + for ( int i=0; i<propertyNames.length; i++ ) { + if ( "createTimestamp".equals( propertyNames[i] ) ) { + state[i] = new Date(); + return true; + } + } + } + return false; + } + + public void afterTransactionCompletion(Transaction tx) { + if ( tx.wasCommitted() ) { + System.out.println("Creations: " + creates + ", Updates: " + updates, "Loads: " + loads); + } + updates=0; + creates=0; + loads=0; + } + +}]]></programlisting> + + <para> + Os interceptadores podem ser aplicados em dois diferentes escopos: + No escopo da <literal>Session</literal> e no escopo + <literal>SessionFactory</literal>. + </para> + + <para> + Um interceptador no escopo da <literal>Session</literal> é definido quando + uma sessão é aberta usando o método sobrecarregado da SessionFactory.openSession() + que aceita um <literal>Interceptor</literal> como parâmetro. + </para> + + <programlisting><![CDATA[Session session = sf.openSession( new AuditInterceptor() );]]></programlisting> + + <para> + Um interceptador no escopo da <literal>SessionFactory</literal> é definido no objeto + <literal>Configuration</literal> antes da <literal>SessionFactory</literal> ser instanciada. + Nesse caso, o interceptador fornecido será aplicado para todas as sessões abertas por aquela + <literal>SessionFactory</literal>; Isso apenas não ocorrerá caso seja especificado um + interceptador no momento em que a sessão for aberta. Um interceptador no escopo de + <literal>SessionFactory</literal> deve ser thread safe, tomando-se o cuidado de não + armazenar atributos de estado específicos da sessão, pois, provavelmente, múltiplas + sessões irão utilizar esse interceptador simultaneamente. + </para> + + <programlisting><![CDATA[new Configuration().setInterceptor( new AuditInterceptor() );]]></programlisting> + + </sect1> + + <sect1 id="objectstate-events" revision="4"> + <title>Sistema de Eventos</title> + + <para> + Se você precisa executar uma ação em determinados eventos da camada de persistência, + você também pode usar a arquitetura de <emphasis>event</emphasis> do Hibernate3. + Um evento do sistema pode ser utilizado como complemento ou em + substituição a um interceptador. + </para> + + <para> + Essencialmente todos os métodos da interface <literal>Session</literal> possuem um evento + correlacionado. Se você tiver um <literal>LoadEvent</literal>, um <literal>LoadEvent</literal>, + etc (consulte o DTD do XML de configuração ou o pacote <literal>org.hibernate.event</literal> + para a lista completa dos tipos de eventos). Quando uma requisição é feita em um desses métodos, + a <literal>Session</literal> do hibernate gera um evento apropriado e o envia para o listener + de evento correspondente àquele tipo de evento. Esses listeners implementam a mesma lógica + que aqueles métodos, trazendo os mesmos resultados. Entretanto, você é livre para implementar + uma customização de um desses listeners (isto é, o <literal>LoadEvent</literal> é processado + pela implementação registrada da interface <literal>LoadEventListener</literal>), então sua + implementação vai ficar responsável por processar qualquer requisição <literal>load()</literal> + feita pela <literal>Session</literal>. + </para> + + <para> + Para todos os efeitos esses listeners deve ser considerados singletons; ou seja, eles são + compartilhados entre as requisições, e assim sendo, não devem salvar nenhum estado das + variáveis instanciadas. + </para> + + <para> + Um listener personalizado deve implementar a interface referente ao evento a ser + processado e/ou deve estender a classes base equivalente (ou mesmo os listeners padrões + usados pelo Hibernate, eles não são declarados como finais com esse objetivo). O listener + personalizado pode ser registrado programaticamente no objeto <literal>Configuration</literal>, + ou declarativamente no XML de configuração do Hibernate (o registro do listener no propertie + de configuração não é suportado). Aqui temos um exemplo de como carregar um listener + personalizado: + </para> + + <programlisting><![CDATA[public class MyLoadListener implements LoadEventListener { + // this is the single method defined by the LoadEventListener interface + public void onLoad(LoadEvent event, LoadEventListener.LoadType loadType) + throws HibernateException { + if ( !MySecurity.isAuthorized( event.getEntityClassName(), event.getEntityId() ) ) { + throw MySecurityException("Unauthorized access"); + } + } +}]]></programlisting> + + <para> + Você também precisa adicionar uma entrada no XML de configuração do Hibernate para + registrar declarativamente qual listener deve se utilizado em conjunto com o listener + padrão: + </para> + +<programlisting><![CDATA[<hibernate-configuration> + <session-factory> + ... + <event type="load"> + <listener class="com.eg.MyLoadListener"/> + <listener class="org.hibernate.event.def.DefaultLoadEventListener"/> + </event> + </session-factory> +</hibernate-configuration>]]></programlisting> + + <para> + Ou, você pode registrar o listener programaticamente: + </para> + + <programlisting><![CDATA[Configuration cfg = new Configuration(); +LoadEventListener[] stack = { new MyLoadListener(), new DefaultLoadEventListener() }; +cfg.EventListeners().setLoadEventListeners(stack);]]></programlisting> + + <para> + Listeners registrados declarativamente não compartilham da mesma instancia. Se o mesmo + nome da classe é utilizado em vários elementos e <literal>&lt;listener/&gt;</literal>, + cada um vai resultar em uma instancia separada dessa classe. Se você tem a necessidade + de compartilhar uma instancia de um listener entre diversos tipos de listeners você + deve registrar o listener programaticamente. + + </para> + + <para> + Mas porque implementar uma interface e definir o tipo específico durante a configuração? + Bem, um listener pode implementar vários listeners de evento. Com o tipo sendo definido + durante o registro, fica fácil ligar ou desligar listeners personalizados durante + a configuração. + </para> + + </sect1> + + <sect1 id="objectstate-decl-security" revision="2"> + <title>Hibernate declarative security</title> + <para> + Usually, declarative security in Hibernate applications is managed in a session facade + layer. Now, Hibernate3 allows certain actions to be permissioned via JACC, and authorized + via JAAS. This is optional functionality built on top of the event architecture. + </para> + + <para> + First, you must configure the appropriate event listeners, to enable the use of JAAS + authorization. + </para> + + <programlisting><![CDATA[<listener type="pre-delete" class="org.hibernate.secure.JACCPreDeleteEventListener"/> +<listener type="pre-update" class="org.hibernate.secure.JACCPreUpdateEventListener"/> +<listener type="pre-insert" class="org.hibernate.secure.JACCPreInsertEventListener"/> +<listener type="pre-load" class="org.hibernate.secure.JACCPreLoadEventListener"/>]]></programlisting> + + <para> + Note that <literal>&lt;listener type="..." class="..."/&gt;</literal> is just a shorthand + for <literal>&lt;event type="..."&gt;&lt;listener class="..."/&gt;&lt;/event&gt;</literal> + when there is exactly one listener for a particular event type. + </para> + + <para> + Next, still in <literal>hibernate.cfg.xml</literal>, bind the permissions to roles: + </para> + + <programlisting><![CDATA[<grant role="admin" entity-name="User" actions="insert,update,read"/> +<grant role="su" entity-name="User" actions="*"/>]]></programlisting> + + <para> + The role names are the roles understood by your JACC provider. + </para> + + </sect1> + +</chapter> + Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_mappings.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/example_mappings.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_mappings.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_mappings.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,678 @@ +<!-- + ~ Copyright (c) 2007, Red Hat Middleware, LLC. All rights reserved. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, v. 2.1. This program is distributed in the + ~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied + ~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + ~ Lesser General Public License for more details. You should have received a + ~ copy of the GNU Lesser General Public License, v.2.1 along with this + ~ distribution; if not, write to the Free Software Foundation, Inc., + ~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + ~ + ~ Red Hat Author(s): Steve Ebersole + --> +<chapter id="example-mappings"> + <title>Exemplo: Vários Mapeamentos</title> + + <para> + Este capitulo mostra algums mapeamentos de associações mais complexos. + </para> + + <sect1 id="example-mappings-emp"> + <title>Employer/Employee</title> + + <para> + O modelo de seguinte relacionamento entre <literal>Employer</literal> e + <literal>Employee</literal> utiliza uma entidade de classe atual (<literal>Employment</literal>) + para representar a associação. Isto é feito porque pode-ser ter mais do que um período de + trabalho para as duas partes envolvidas. Outros Componentes são usados para modelar + valores monetários e os nomes do empregado. + </para> + + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="../images/EmployerEmployee.png" format="PNG" align="center"/> + </imageobject> + <imageobject role="html"> + <imagedata fileref="../images/EmployerEmployee.png" format="PNG" align="center"/> + </imageobject> + </mediaobject> + + <para> + Abaixo o código de um possível mapeamento: + </para> + + <programlisting><![CDATA[<hibernate-mapping> + + <class name="Employer" table="employers"> + <id name="id"> + <generator class="sequence"> + <param name="sequence">employer_id_seq</param> + </generator> + </id> + <property name="name"/> + </class> + + <class name="Employment" table="employment_periods"> + + <id name="id"> + <generator class="sequence"> + <param name="sequence">employment_id_seq</param> + </generator> + </id> + <property name="startDate" column="start_date"/> + <property name="endDate" column="end_date"/> + + <component name="hourlyRate" class="MonetaryAmount"> + <property name="amount"> + <column name="hourly_rate" sql-type="NUMERIC(12, 2)"/> + </property> + <property name="currency" length="12"/> + </component> + + <many-to-one name="employer" column="employer_id" not-null="true"/> + <many-to-one name="employee" column="employee_id" not-null="true"/> + + </class> + + <class name="Employee" table="employees"> + <id name="id"> + <generator class="sequence"> + <param name="sequence">employee_id_seq</param> + </generator> + </id> + <property name="taxfileNumber"/> + <component name="name" class="Name"> + <property name="firstName"/> + <property name="initial"/> + <property name="lastName"/> + </component> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + E abaixo o esquema da tabela gerado pelo <literal>SchemaExport</literal>. + </para> + + <programlisting><![CDATA[create table employers ( + id BIGINT not null, + name VARCHAR(255), + primary key (id) +) + +create table employment_periods ( + id BIGINT not null, + hourly_rate NUMERIC(12, 2), + currency VARCHAR(12), + employee_id BIGINT not null, + employer_id BIGINT not null, + end_date TIMESTAMP, + start_date TIMESTAMP, + primary key (id) +) + +create table employees ( + id BIGINT not null, + firstName VARCHAR(255), + initial CHAR(1), + lastName VARCHAR(255), + taxfileNumber VARCHAR(255), + primary key (id) +) + +alter table employment_periods + add constraint employment_periodsFK0 foreign key (employer_id) references employers +alter table employment_periods + add constraint employment_periodsFK1 foreign key (employee_id) references employees +create sequence employee_id_seq +create sequence employment_id_seq +create sequence employer_id_seq]]></programlisting> + + </sect1> + + <sect1 id="example-mappings-authorwork"> + <title>Author/Work</title> + + <para> + Considere o seguinte modelo de relacionamento entre <literal>Work</literal>, + <literal>Author</literal> e <literal>Person</literal>. Nós representamos o relacionamento + entre <literal>Work</literal> e <literal>Author</literal> como uma associação + muitos-para-muitos. Nós escolhemos representar o relacionamento entre <literal>Author</literal> + e <literal>Person</literal> como uma associação um-para-um. Outra possibilidade seria ter + <literal>Author</literal> extendendo <literal>Person</literal>. + </para> + + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="../images/AuthorWork.png" format="PNG" align="center"/> + </imageobject> + <imageobject role="html"> + <imagedata fileref="../images/AuthorWork.png" format="PNG" align="center"/> + </imageobject> + </mediaobject> + + <para> + O mapeamento do código seguinte representa corretamente estes relacionamentos: + </para> + + <programlisting><![CDATA[<hibernate-mapping> + + <class name="Work" table="works" discriminator-value="W"> + + <id name="id" column="id"> + <generator class="native"/> + </id> + <discriminator column="type" type="character"/> + + <property name="title"/> + <set name="authors" table="author_work"> + <key column name="work_id"/> + <many-to-many class="Author" column name="author_id"/> + </set> + + <subclass name="Book" discriminator-value="B"> + <property name="text"/> + </subclass> + + <subclass name="Song" discriminator-value="S"> + <property name="tempo"/> + <property name="genre"/> + </subclass> + + </class> + + <class name="Author" table="authors"> + + <id name="id" column="id"> + <!-- The Author must have the same identifier as the Person --> + <generator class="assigned"/> + </id> + + <property name="alias"/> + <one-to-one name="person" constrained="true"/> + + <set name="works" table="author_work" inverse="true"> + <key column="author_id"/> + <many-to-many class="Work" column="work_id"/> + </set> + + </class> + + <class name="Person" table="persons"> + <id name="id" column="id"> + <generator class="native"/> + </id> + <property name="name"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + There are four tables in this mapping. <literal>works</literal>, + <literal>authors</literal> and <literal>persons</literal> hold work, author + and person data respectively. <literal>author_work</literal> is an association + table linking authors to works. Heres the table schema, as generated by + <literal>SchemaExport</literal>. + Existem quatro tabelas neste mapeamento. <literal>works</literal>, + <literal>authors</literal> e <literal>persons</literal> recebem os dados de work, + author e person, respectivamente. <literal>author_work</literal> é uma tabela de + associação que liga authors à works. Abaixo o esquema das tabelas, gerados pelo + <literal>SchemaExport</literal>. + </para> + + <programlisting><![CDATA[create table works ( + id BIGINT not null generated by default as identity, + tempo FLOAT, + genre VARCHAR(255), + text INTEGER, + title VARCHAR(255), + type CHAR(1) not null, + primary key (id) +) + +create table author_work ( + author_id BIGINT not null, + work_id BIGINT not null, + primary key (work_id, author_id) +) + +create table authors ( + id BIGINT not null generated by default as identity, + alias VARCHAR(255), + primary key (id) +) + +create table persons ( + id BIGINT not null generated by default as identity, + name VARCHAR(255), + primary key (id) +) + +alter table authors + add constraint authorsFK0 foreign key (id) references persons +alter table author_work + add constraint author_workFK0 foreign key (author_id) references authors +alter table author_work + add constraint author_workFK1 foreign key (work_id) references works]]></programlisting> + + </sect1> + + <sect1 id="example-mappings-customerorderproduct"> + <title>Customer/Order/Product</title> + + <para> + Agora considere um modelo de relacionamento entre <literal>Customer</literal>, + <literal>Order</literal> e <literal>LineItem</literal> e <literal>Product</literal>. + Existe uma associação um-para-muitos entre <literal>Customer</literal> e + <literal>Order</literal>, mas como devemos representar <literal>Order</literal> / + <literal>LineItem</literal> / <literal>Product</literal>? Eu escolhi mapear LineItem + como uma classe de associação representando a associação muitos-para-muitos entre + <literal>Order</literal> and <literal>Product</literal>. No Hibernate, isto é conhecido + como um elemento composto. + </para> + + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="../images/CustomerOrderProduct.png" format="PNG" align="center"/> + </imageobject> + <imageobject role="html"> + <imagedata fileref="../images/CustomerOrderProduct.png" format="PNG" align="center"/> + </imageobject> + </mediaobject> + + <para> + O código do mapeamento: + </para> + + <programlisting><![CDATA[<hibernate-mapping> + + <class name="Customer" table="customers"> + <id name="id"> + <generator class="native"/> + </id> + <property name="name"/> + <set name="orders" inverse="true"> + <key column="customer_id"/> + <one-to-many class="Order"/> + </set> + </class> + + <class name="Order" table="orders"> + <id name="id"> + <generator class="native"/> + </id> + <property name="date"/> + <many-to-one name="customer" column="customer_id"/> + <list name="lineItems" table="line_items"> + <key column="order_id"/> + <list-index column="line_number"/> + <composite-element class="LineItem"> + <property name="quantity"/> + <many-to-one name="product" column="product_id"/> + </composite-element> + </list> + </class> + + <class name="Product" table="products"> + <id name="id"> + <generator class="native"/> + </id> + <property name="serialNumber"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + <literal>customers</literal>, <literal>orders</literal>, <literal>line_items</literal> e + <literal>products</literal> recebem os dados de customer, order, line_item e product, + respectivamente. <literal>line_items</literal> também atua como uma tabela de associação + ligando orders com products. + </para> + + <programlisting><![CDATA[create table customers ( + id BIGINT not null generated by default as identity, + name VARCHAR(255), + primary key (id) +) + +create table orders ( + id BIGINT not null generated by default as identity, + customer_id BIGINT, + date TIMESTAMP, + primary key (id) +) + +create table line_items ( + line_number INTEGER not null, + order_id BIGINT not null, + product_id BIGINT, + quantity INTEGER, + primary key (order_id, line_number) +) + +create table products ( + id BIGINT not null generated by default as identity, + serialNumber VARCHAR(255), + primary key (id) +) + +alter table orders + add constraint ordersFK0 foreign key (customer_id) references customers +alter table line_items + add constraint line_itemsFK0 foreign key (product_id) references products +alter table line_items + add constraint line_itemsFK1 foreign key (order_id) references orders]]></programlisting> + + </sect1> + + <sect1 id="misc"> + <title>Exemplos variados de mapeamento</title> + + <para> + Todos estes exemplos são retirados do conjunto de testes do Hibernate. + Lá, você encontrará vários outros exemplos úteis de mapeamentos. + Verifique o diretorio <literal>test</literal> da distribuição do Hibernate. + </para> + + <para>TODO: put words around this stuff</para> + + <sect2 id="example-mappings-typed-onetone"> + <title>Associação um-para-um "Tipadas"</title> +<programlisting><![CDATA[<class name="Person"> + <id name="name"/> + <one-to-one name="address" + cascade="all"> + <formula>name</formula> + <formula>'HOME'</formula> + </one-to-one> + <one-to-one name="mailingAddress" + cascade="all"> + <formula>name</formula> + <formula>'MAILING'</formula> + </one-to-one> +</class> + +<class name="Address" batch-size="2" + check="addressType in ('MAILING', 'HOME', 'BUSINESS')"> + <composite-id> + <key-many-to-one name="person" + column="personName"/> + <key-property name="type" + column="addressType"/> + </composite-id> + <property name="street" type="text"/> + <property name="state"/> + <property name="zip"/> +</class>]]></programlisting> + </sect2> + + <sect2 id="example-mappings-composite-key"> + <title>Exemplo de chave composta</title> +<programlisting><![CDATA[<class name="Customer"> + + <id name="customerId" + length="10"> + <generator class="assigned"/> + </id> + + <property name="name" not-null="true" length="100"/> + <property name="address" not-null="true" length="200"/> + + <list name="orders" + inverse="true" + cascade="save-update"> + <key column="customerId"/> + <index column="orderNumber"/> + <one-to-many class="Order"/> + </list> + +</class> + +<class name="Order" table="CustomerOrder" lazy="true"> + <synchronize table="LineItem"/> + <synchronize table="Product"/> + + <composite-id name="id" + class="Order$Id"> + <key-property name="customerId" length="10"/> + <key-property name="orderNumber"/> + </composite-id> + + <property name="orderDate" + type="calendar_date" + not-null="true"/> + + <property name="total"> + <formula> + ( select sum(li.quantity*p.price) + from LineItem li, Product p + where li.productId = p.productId + and li.customerId = customerId + and li.orderNumber = orderNumber ) + </formula> + </property> + + <many-to-one name="customer" + column="customerId" + insert="false" + update="false" + not-null="true"/> + + <bag name="lineItems" + fetch="join" + inverse="true" + cascade="save-update"> + <key> + <column name="customerId"/> + <column name="orderNumber"/> + </key> + <one-to-many class="LineItem"/> + </bag> + +</class> + +<class name="LineItem"> + + <composite-id name="id" + class="LineItem$Id"> + <key-property name="customerId" length="10"/> + <key-property name="orderNumber"/> + <key-property name="productId" length="10"/> + </composite-id> + + <property name="quantity"/> + + <many-to-one name="order" + insert="false" + update="false" + not-null="true"> + <column name="customerId"/> + <column name="orderNumber"/> + </many-to-one> + + <many-to-one name="product" + insert="false" + update="false" + not-null="true" + column="productId"/> + +</class> + +<class name="Product"> + <synchronize table="LineItem"/> + + <id name="productId" + length="10"> + <generator class="assigned"/> + </id> + + <property name="description" + not-null="true" + length="200"/> + <property name="price" length="3"/> + <property name="numberAvailable"/> + + <property name="numberOrdered"> + <formula> + ( select sum(li.quantity) + from LineItem li + where li.productId = productId ) + </formula> + </property> + +</class>]]></programlisting> + </sect2> + + <sect2 id="example-mappings-composite-key-manytomany"> + <title>Mmuitos-para-muitos com atributo de chave composta compartilhada</title> +<programlisting><![CDATA[<class name="User" table="`User`"> + <composite-id> + <key-property name="name"/> + <key-property name="org"/> + </composite-id> + <set name="groups" table="UserGroup"> + <key> + <column name="userName"/> + <column name="org"/> + </key> + <many-to-many class="Group"> + <column name="groupName"/> + <formula>org</formula> + </many-to-many> + </set> +</class> + +<class name="Group" table="`Group`"> + <composite-id> + <key-property name="name"/> + <key-property name="org"/> + </composite-id> + <property name="description"/> + <set name="users" table="UserGroup" inverse="true"> + <key> + <column name="groupName"/> + <column name="org"/> + </key> + <many-to-many class="User"> + <column name="userName"/> + <formula>org</formula> + </many-to-many> + </set> +</class> +]]></programlisting> + </sect2> + + <sect2 id="example-mappings-content-discrimination"> + <title>Conteúdo baseado em descriminação</title> +<programlisting><![CDATA[<class name="Person" + discriminator-value="P"> + + <id name="id" + column="person_id" + unsaved-value="0"> + <generator class="native"/> + </id> + + + <discriminator + type="character"> + <formula> + case + when title is not null then 'E' + when salesperson is not null then 'C' + else 'P' + end + </formula> + </discriminator> + + <property name="name" + not-null="true" + length="80"/> + + <property name="sex" + not-null="true" + update="false"/> + + <component name="address"> + <property name="address"/> + <property name="zip"/> + <property name="country"/> + </component> + + <subclass name="Employee" + discriminator-value="E"> + <property name="title" + length="20"/> + <property name="salary"/> + <many-to-one name="manager"/> + </subclass> + + <subclass name="Customer" + discriminator-value="C"> + <property name="comments"/> + <many-to-one name="salesperson"/> + </subclass> + +</class>]]></programlisting> + </sect2> + + <sect2 id="example-mappings-association-alternatekeys" revision="2"> + <title>Associações em chaves alternativas</title> +<programlisting><![CDATA[<class name="Person"> + + <id name="id"> + <generator class="hilo"/> + </id> + + <property name="name" length="100"/> + + <one-to-one name="address" + property-ref="person" + cascade="all" + fetch="join"/> + + <set name="accounts" + inverse="true"> + <key column="userId" + property-ref="userId"/> + <one-to-many class="Account"/> + </set> + + <property name="userId" length="8"/> + +</class> + +<class name="Address"> + + <id name="id"> + <generator class="hilo"/> + </id> + + <property name="address" length="300"/> + <property name="zip" length="5"/> + <property name="country" length="25"/> + <many-to-one name="person" unique="true" not-null="true"/> + +</class> + +<class name="Account"> + <id name="accountId" length="32"> + <generator class="uuid"/> + </id> + + <many-to-one name="user" + column="userId" + property-ref="userId"/> + + <property name="type" not-null="true"/> + +</class>]]></programlisting> + </sect2> + + </sect1> + +</chapter> + Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_parentchild.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/example_parentchild.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_parentchild.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_parentchild.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,361 @@ +<chapter id="example-parentchild"> + <title>Example: Parent/Child</title> + + <para> + One of the very first things that new users try to do with Hibernate is to model a parent / child type + relationship. There are two different approaches to this. For various reasons the most convenient + approach, especially for new users, is to model both <literal>Parent</literal> and <literal>Child</literal> + as entity classes with a <literal>&lt;one-to-many&gt;</literal> association from <literal>Parent</literal> + to <literal>Child</literal>. (The alternative approach is to declare the <literal>Child</literal> as a + <literal>&lt;composite-element&gt;</literal>.) Now, it turns out that default semantics of a one to many + association (in Hibernate) are much less close to the usual semantics of a parent / child relationship than + those of a composite element mapping. We will explain how to use a <emphasis>bidirectional one to many + association with cascades</emphasis> to model a parent / child relationship efficiently and elegantly. + It's not at all difficult! + </para> + + <sect1 id="example-parentchild-collections"> + <title>A note about collections</title> + + <para> + Hibernate collections are considered to be a logical part of their owning entity; never of the + contained entities. This is a crucial distinction! It has the following consequences: + </para> + + <itemizedlist> + <listitem> + <para> + When we remove / add an object from / to a collection, the version number of the collection owner + is incremented. + </para> + </listitem> + <listitem> + <para> + If an object that was removed from a collection is an instance of a value type (eg, a composite + element), that object will cease to be persistent and its state will be completely removed from + the database. Likewise, adding a value type instance to the collection will cause its state to be + immediately persistent. + </para> + </listitem> + <listitem> + <para> + On the other hand, if an entity is removed from a collection (a one-to-many or many-to-many + association), it will not be deleted, by default. This behaviour is completely consistent - a + change to the internal state of another entity should not cause the associated entity to vanish! + Likewise, adding an entity to a collection does not cause that entity to become persistent, by + default. + </para> + </listitem> + </itemizedlist> + + <para> + Instead, the default behaviour is that adding an entity to a collection merely creates a link between + the two entities, while removing it removes the link. This is very appropriate for all sorts of cases. + Where it is not appropriate at all is the case of a parent / child relationship, where the life of the + child is bound to the life cycle of the parent. + </para> + + </sect1> + + <sect1 id="example-parentchild-bidir"> + <title>Bidirectional one-to-many</title> + + <para> + Suppose we start with a simple <literal>&lt;one-to-many&gt;</literal> association from + <literal>Parent</literal> to <literal>Child</literal>. + </para> + + <programlisting><![CDATA[<set name="children"> + <key column="parent_id"/> + <one-to-many class="Child"/> +</set>]]></programlisting> + + <para> + If we were to execute the following code + </para> + + <programlisting><![CDATA[Parent p = .....; +Child c = new Child(); +p.getChildren().add(c); +session.save(c); +session.flush();]]></programlisting> + + <para> + Hibernate would issue two SQL statements: + </para> + + <itemizedlist> + <listitem> + <para>an <literal>INSERT</literal> to create the record for <literal>c</literal></para> + </listitem> + <listitem> + <para> + an <literal>UPDATE</literal> to create the link from <literal>p</literal> to + <literal>c</literal> + </para> + </listitem> + </itemizedlist> + + <para> + This is not only inefficient, but also violates any <literal>NOT NULL</literal> constraint on the + <literal>parent_id</literal> column. We can fix the nullability constraint violation by specifying + <literal>not-null="true"</literal> in the collection mapping: + </para> + + <programlisting><![CDATA[<set name="children"> + <key column="parent_id" not-null="true"/> + <one-to-many class="Child"/> +</set>]]></programlisting> + + <para> + However, this is not the recommended solution. + </para> + <para> + The underlying cause of this behaviour is that the link (the foreign key <literal>parent_id</literal>) + from <literal>p</literal> to <literal>c</literal> is not considered part of the state of the + <literal>Child</literal> object and is therefore not created in the <literal>INSERT</literal>. So the + solution is to make the link part of the <literal>Child</literal> mapping. + </para> + + <programlisting><![CDATA[<many-to-one name="parent" column="parent_id" not-null="true"/>]]></programlisting> + + <para> + (We also need to add the <literal>parent</literal> property to the <literal>Child</literal> class.) + </para> + + <para> + Now that the <literal>Child</literal> entity is managing the state of the link, we tell the collection + not to update the link. We use the <literal>inverse</literal> attribute. + </para> + + <programlisting><![CDATA[<set name="children" inverse="true"> + <key column="parent_id"/> + <one-to-many class="Child"/> +</set>]]></programlisting> + + <para> + The following code would be used to add a new <literal>Child</literal> + </para> + + <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid); +Child c = new Child(); +c.setParent(p); +p.getChildren().add(c); +session.save(c); +session.flush();]]></programlisting> + + <para> + And now, only one SQL <literal>INSERT</literal> would be issued! + </para> + + <para> + To tighten things up a bit, we could create an <literal>addChild()</literal> method of + <literal>Parent</literal>. + </para> + + <programlisting><![CDATA[public void addChild(Child c) { + c.setParent(this); + children.add(c); +}]]></programlisting> + + <para> + Now, the code to add a <literal>Child</literal> looks like + </para> + + <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid); +Child c = new Child(); +p.addChild(c); +session.save(c); +session.flush();]]></programlisting> + + </sect1> + + <sect1 id="example-parentchild-cascades"> + <title>Cascading life cycle</title> + + <para> + The explicit call to <literal>save()</literal> is still annoying. We will address this by + using cascades. + </para> + + <programlisting><![CDATA[<set name="children" inverse="true" cascade="all"> + <key column="parent_id"/> + <one-to-many class="Child"/> +</set>]]></programlisting> + + <para> + This simplifies the code above to + </para> + + <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid); +Child c = new Child(); +p.addChild(c); +session.flush();]]></programlisting> + + <para> + Similarly, we don't need to iterate over the children when saving or deleting a <literal>Parent</literal>. + The following removes <literal>p</literal> and all its children from the database. + </para> + + <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid); +session.delete(p); +session.flush();]]></programlisting> + + <para> + However, this code + </para> + + <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid); +Child c = (Child) p.getChildren().iterator().next(); +p.getChildren().remove(c); +c.setParent(null); +session.flush();]]></programlisting> + + <para> + will not remove <literal>c</literal> from the database; it will ony remove the link to <literal>p</literal> + (and cause a <literal>NOT NULL</literal> constraint violation, in this case). You need to explicitly + <literal>delete()</literal> the <literal>Child</literal>. + </para> + + <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid); +Child c = (Child) p.getChildren().iterator().next(); +p.getChildren().remove(c); +session.delete(c); +session.flush();]]></programlisting> + + <para> + Now, in our case, a <literal>Child</literal> can't really exist without its parent. So if we remove + a <literal>Child</literal> from the collection, we really do want it to be deleted. For this, we must + use <literal>cascade="all-delete-orphan"</literal>. + </para> + + <programlisting><![CDATA[<set name="children" inverse="true" cascade="all-delete-orphan"> + <key column="parent_id"/> + <one-to-many class="Child"/> +</set>]]></programlisting> + + <para> + Note: even though the collection mapping specifies <literal>inverse="true"</literal>, cascades are + still processed by iterating the collection elements. So if you require that an object be saved, + deleted or updated by cascade, you must add it to the collection. It is not enough to simply call + <literal>setParent()</literal>. + </para> + + </sect1> + + <sect1 id="example-parentchild-update"> + <title>Cascades and <literal>unsaved-value</literal></title> + + <para> + Suppose we loaded up a <literal>Parent</literal> in one <literal>Session</literal>, made some changes + in a UI action and wish to persist these changes in a new session by calling <literal>update()</literal>. + The <literal>Parent</literal> will contain a collection of childen and, since cascading update is enabled, + Hibernate needs to know which children are newly instantiated and which represent existing rows in the + database. Lets assume that both <literal>Parent</literal> and <literal>Child</literal> have genenerated + identifier properties of type <literal>Long</literal>. Hibernate will use the identifier and + version/timestamp property value to determine which of the children are new. (See + <xref linkend="objectstate-saveorupdate"/>.) <emphasis>In Hibernate3, it is no longer necessary to specify + an <literal>unsaved-value</literal> explicitly.</emphasis> + </para> + + <para> + The following code will update <literal>parent</literal> and <literal>child</literal> and insert + <literal>newChild</literal>. + </para> + + <programlisting><![CDATA[//parent and child were both loaded in a previous session +parent.addChild(child); +Child newChild = new Child(); +parent.addChild(newChild); +session.update(parent); +session.flush();]]></programlisting> + + <para> + Well, that's all very well for the case of a generated identifier, but what about assigned identifiers + and composite identifiers? This is more difficult, since Hibernate can't use the identifier property to + distinguish between a newly instantiated object (with an identifier assigned by the user) and an + object loaded in a previous session. In this case, Hibernate will either use the timestamp or version + property, or will actually query the second-level cache or, worst case, the database, to see if the + row exists. + </para> + + <!-- undocumenting + <para> + There is one further possibility. The <literal>Interceptor</literal> method named + <literal>isUnsaved()</literal> lets the application implement its own strategy for distinguishing + newly instantiated objects. For example, you could define a base class for your persistent classes. + </para> + + <programlisting><![CDATA[public class Persistent { + private boolean _saved = false; + public void onSave() { + _saved=true; + } + public void onLoad() { + _saved=true; + } + ...... + public boolean isSaved() { + return _saved; + } +}]]></programlisting> + + <para> + (The <literal>saved</literal> property is non-persistent.) + Now implement <literal>isUnsaved()</literal>, along with <literal>onLoad()</literal> + and <literal>onSave()</literal> as follows. + </para> + + <programlisting><![CDATA[public Boolean isUnsaved(Object entity) { + if (entity instanceof Persistent) { + return new Boolean( !( (Persistent) entity ).isSaved() ); + } + else { + return null; + } +} + +public boolean onLoad(Object entity, + Serializable id, + Object[] state, + String[] propertyNames, + Type[] types) { + + if (entity instanceof Persistent) ( (Persistent) entity ).onLoad(); + return false; +} + +public boolean onSave(Object entity, + Serializable id, + Object[] state, + String[] propertyNames, + Type[] types) { + + if (entity instanceof Persistent) ( (Persistent) entity ).onSave(); + return false; +}]]></programlisting> + + <para> + Don't worry; in Hibernate3 you don't need to write any of this kind of code if you don't want to. + </para> + --> + </sect1> + + <sect1 id="example-parentchild-conclusion"> + <title>Conclusion</title> + + <para> + There is quite a bit to digest here and it might look confusing first time around. However, in practice, + it all works out very nicely. Most Hibernate applications use the parent / child pattern in many places. + </para> + + <para> + We mentioned an alternative in the first paragraph. None of the above issues exist in the case of + <literal>&lt;composite-element&gt;</literal> mappings, which have exactly the semantics of a parent / child + relationship. Unfortunately, there are two big limitations to composite element classes: composite elements + may not own collections, and they should not be the child of any entity other than the unique parent. + </para> + + </sect1> + +</chapter> \ No newline at end of file Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_weblog.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/example_weblog.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_weblog.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_weblog.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,430 @@ +<chapter id="example-weblog"> + <title>Example: Weblog Application</title> + + <sect1 id="example-weblog-classes"> + <title>Persistent Classes</title> + + <para> + The persistent classes represent a weblog, and an item posted + in a weblog. They are to be modelled as a standard parent/child + relationship, but we will use an ordered bag, instead of a set. + </para> + + <programlisting><![CDATA[package eg; + +import java.util.List; + +public class Blog { + private Long _id; + private String _name; + private List _items; + + public Long getId() { + return _id; + } + public List getItems() { + return _items; + } + public String getName() { + return _name; + } + public void setId(Long long1) { + _id = long1; + } + public void setItems(List list) { + _items = list; + } + public void setName(String string) { + _name = string; + } +}]]></programlisting> + + <programlisting><![CDATA[package eg; + +import java.text.DateFormat; +import java.util.Calendar; + +public class BlogItem { + private Long _id; + private Calendar _datetime; + private String _text; + private String _title; + private Blog _blog; + + public Blog getBlog() { + return _blog; + } + public Calendar getDatetime() { + return _datetime; + } + public Long getId() { + return _id; + } + public String getText() { + return _text; + } + public String getTitle() { + return _title; + } + public void setBlog(Blog blog) { + _blog = blog; + } + public void setDatetime(Calendar calendar) { + _datetime = calendar; + } + public void setId(Long long1) { + _id = long1; + } + public void setText(String string) { + _text = string; + } + public void setTitle(String string) { + _title = string; + } +}]]></programlisting> + + </sect1> + + <sect1 id="example-weblog-mappings"> + <title>Hibernate Mappings</title> + + <para> + The XML mappings should now be quite straightforward. + </para> + + <programlisting><![CDATA[<?xml version="1.0"?> +<!DOCTYPE hibernate-mapping PUBLIC + "-//Hibernate/Hibernate Mapping DTD 3.0//EN" + "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"> + +<hibernate-mapping package="eg"> + + <class + name="Blog" + table="BLOGS"> + + <id + name="id" + column="BLOG_ID"> + + <generator class="native"/> + + </id> + + <property + name="name" + column="NAME" + not-null="true" + unique="true"/> + + <bag + name="items" + inverse="true" + order-by="DATE_TIME" + cascade="all"> + + <key column="BLOG_ID"/> + <one-to-many class="BlogItem"/> + + </bag> + + </class> + +</hibernate-mapping>]]></programlisting> + + <programlisting><![CDATA[<?xml version="1.0"?> +<!DOCTYPE hibernate-mapping PUBLIC + "-//Hibernate/Hibernate Mapping DTD 3.0//EN" + "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"> + +<hibernate-mapping package="eg"> + + <class + name="BlogItem" + table="BLOG_ITEMS" + dynamic-update="true"> + + <id + name="id" + column="BLOG_ITEM_ID"> + + <generator class="native"/> + + </id> + + <property + name="title" + column="TITLE" + not-null="true"/> + + <property + name="text" + column="TEXT" + not-null="true"/> + + <property + name="datetime" + column="DATE_TIME" + not-null="true"/> + + <many-to-one + name="blog" + column="BLOG_ID" + not-null="true"/> + + </class> + +</hibernate-mapping>]]></programlisting> + + </sect1> + + <sect1 id="example-weblog-code"> + <title>Hibernate Code</title> + + <para> + The following class demonstrates some of the kinds of things + we can do with these classes, using Hibernate. + </para> + + <programlisting><![CDATA[package eg; + +import java.util.ArrayList; +import java.util.Calendar; +import java.util.Iterator; +import java.util.List; + +import org.hibernate.HibernateException; +import org.hibernate.Query; +import org.hibernate.Session; +import org.hibernate.SessionFactory; +import org.hibernate.Transaction; +import org.hibernate.cfg.Configuration; +import org.hibernate.tool.hbm2ddl.SchemaExport; + +public class BlogMain { + + private SessionFactory _sessions; + + public void configure() throws HibernateException { + _sessions = new Configuration() + .addClass(Blog.class) + .addClass(BlogItem.class) + .buildSessionFactory(); + } + + public void exportTables() throws HibernateException { + Configuration cfg = new Configuration() + .addClass(Blog.class) + .addClass(BlogItem.class); + new SchemaExport(cfg).create(true, true); + } + + public Blog createBlog(String name) throws HibernateException { + + Blog blog = new Blog(); + blog.setName(name); + blog.setItems( new ArrayList() ); + + Session session = _sessions.openSession(); + Transaction tx = null; + try { + tx = session.beginTransaction(); + session.persist(blog); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + return blog; + } + + public BlogItem createBlogItem(Blog blog, String title, String text) + throws HibernateException { + + BlogItem item = new BlogItem(); + item.setTitle(title); + item.setText(text); + item.setBlog(blog); + item.setDatetime( Calendar.getInstance() ); + blog.getItems().add(item); + + Session session = _sessions.openSession(); + Transaction tx = null; + try { + tx = session.beginTransaction(); + session.update(blog); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + return item; + } + + public BlogItem createBlogItem(Long blogid, String title, String text) + throws HibernateException { + + BlogItem item = new BlogItem(); + item.setTitle(title); + item.setText(text); + item.setDatetime( Calendar.getInstance() ); + + Session session = _sessions.openSession(); + Transaction tx = null; + try { + tx = session.beginTransaction(); + Blog blog = (Blog) session.load(Blog.class, blogid); + item.setBlog(blog); + blog.getItems().add(item); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + return item; + } + + public void updateBlogItem(BlogItem item, String text) + throws HibernateException { + + item.setText(text); + + Session session = _sessions.openSession(); + Transaction tx = null; + try { + tx = session.beginTransaction(); + session.update(item); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + } + + public void updateBlogItem(Long itemid, String text) + throws HibernateException { + + Session session = _sessions.openSession(); + Transaction tx = null; + try { + tx = session.beginTransaction(); + BlogItem item = (BlogItem) session.load(BlogItem.class, itemid); + item.setText(text); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + } + + public List listAllBlogNamesAndItemCounts(int max) + throws HibernateException { + + Session session = _sessions.openSession(); + Transaction tx = null; + List result = null; + try { + tx = session.beginTransaction(); + Query q = session.createQuery( + "select blog.id, blog.name, count(blogItem) " + + "from Blog as blog " + + "left outer join blog.items as blogItem " + + "group by blog.name, blog.id " + + "order by max(blogItem.datetime)" + ); + q.setMaxResults(max); + result = q.list(); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + return result; + } + + public Blog getBlogAndAllItems(Long blogid) + throws HibernateException { + + Session session = _sessions.openSession(); + Transaction tx = null; + Blog blog = null; + try { + tx = session.beginTransaction(); + Query q = session.createQuery( + "from Blog as blog " + + "left outer join fetch blog.items " + + "where blog.id = :blogid" + ); + q.setParameter("blogid", blogid); + blog = (Blog) q.uniqueResult(); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + return blog; + } + + public List listBlogsAndRecentItems() throws HibernateException { + + Session session = _sessions.openSession(); + Transaction tx = null; + List result = null; + try { + tx = session.beginTransaction(); + Query q = session.createQuery( + "from Blog as blog " + + "inner join blog.items as blogItem " + + "where blogItem.datetime > :minDate" + ); + + Calendar cal = Calendar.getInstance(); + cal.roll(Calendar.MONTH, false); + q.setCalendar("minDate", cal); + + result = q.list(); + tx.commit(); + } + catch (HibernateException he) { + if (tx!=null) tx.rollback(); + throw he; + } + finally { + session.close(); + } + return result; + } +}]]></programlisting> + + </sect1> + +</chapter> + Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/filters.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/filters.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/filters.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/filters.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,128 @@ +<chapter id="filters"> + <title>Filtrando dados</title> + + <para> + O Hibernate3 provê um novo método inovador para manusear dados com regras de "visibilidade". + Um <emphasis>Filtro do Hibernate</emphasis> é um filtro global, nomeado e parametrizado que pode + se habilitado ou não dentro de um Session do Hibernate. + </para> + + <sect1 id="objectstate-filters"> + <title>Filtros do Hibernate</title> + + <para> + O Hibernate tem a habilidade de pré definir os critérios do filtro e anexar esses filtros no + nível da classe e no nível da coleção. Um critério do filtro é a habilidade de definir uma + cláusula restritiva muito semelhante ao atributo "where" disponível para a classe e várias + coleções. A não ser que essas condições de filtros podem ser parametrizadas. A aplicação + pode, então, fazer uma decisão em tempo de execução se os filtros definidos devem estar + habilitados e quais valores seus parâmetros devem ter. Os filtros podem ser usados como + Views de bancos de dados, mas com parametros internos à aplicação. + </para> + + <para> + Para usar esses filtros, eles primeiramente devem ser definidos e anexados aos elementos do + mapeamento apropriados. Para definir um filtro, use o elemento <literal>&lt;filter-def/&gt;</literal> + dentro do elemento <literal>&lt;hibernate-mapping/&gt;</literal>: + </para> + + <programlisting><![CDATA[<filter-def name="myFilter"> + <filter-param name="myFilterParam" type="string"/> +</filter-def>]]></programlisting> + + <para> + Então esse filtro pode ser anexo à uma classe: + </para> + + <programlisting><![CDATA[<class name="myClass" ...> + ... + <filter name="myFilter" condition=":myFilterParam = MY_FILTERED_COLUMN"/> +</class>]]></programlisting> + + <para> + ou em uma coleção: + </para> + + <programlisting><![CDATA[<set ...> + <filter name="myFilter" condition=":myFilterParam = MY_FILTERED_COLUMN"/> +</set>]]></programlisting> + + <para> + ou mesmo para ambos (ou muitos de cada) ao mesmo tempo. + </para> + + <para> + Os métodos na <literal>Session</literal> são: <literal>enableFilter(String filterName)</literal>, + <literal>getEnabledFilter(String filterName)</literal>, e <literal>disableFilter(String filterName)</literal>. + Por padrão, os filtros não são habilitados dentro de qualquer session; Eles devem ser explicitamente + habilitados usando o método <literal>Session.enabledFilter()</literal>, que retorna uma instância da + interface <literal>Filter</literal>. Usando o filtro simples definido acima, o código se pareceria + com o seguinte: + </para> + + <programlisting><![CDATA[session.enableFilter("myFilter").setParameter("myFilterParam", "some-value");]]></programlisting> + + <para> + Veja que os métodos da interface org.hibernate.Filter permite o encadeamento de funções, comum à maioria das funções do Hibernate. + </para> + + <para> + Um exemplo completo, usando dados temporais com um padrão efetivo de registro de datas: + </para> + + <programlisting><![CDATA[<filter-def name="effectiveDate"> + <filter-param name="asOfDate" type="date"/> +</filter-def> + +<class name="Employee" ...> +... + <many-to-one name="department" column="dept_id" class="Department"/> + <property name="effectiveStartDate" type="date" column="eff_start_dt"/> + <property name="effectiveEndDate" type="date" column="eff_end_dt"/> +... + <!-- + Note that this assumes non-terminal records have an eff_end_dt set to + a max db date for simplicity-sake + --> + <filter name="effectiveDate" + condition=":asOfDate BETWEEN eff_start_dt and eff_end_dt"/> +</class> + +<class name="Department" ...> +... + <set name="employees" lazy="true"> + <key column="dept_id"/> + <one-to-many class="Employee"/> + <filter name="effectiveDate" + condition=":asOfDate BETWEEN eff_start_dt and eff_end_dt"/> + </set> +</class>]]></programlisting> + + <para> + Para garantir que você sempre tenha registro efetivos, simplesmente habilite o filtro + na session antes de recuperar os dados dos empregados: + </para> + +<programlisting><![CDATA[Session session = ...; +session.enabledFilter("effectiveDate").setParameter("asOfDate", new Date()); +List results = session.createQuery("from Employee as e where e.salary > :targetSalary") + .setLong("targetSalary", new Long(1000000)) + .list(); +]]></programlisting> + + <para> + No HQL acima, mesmo que mencionamos apenas uma restrição de salário nos resultados, por causa + do filtro habilitado, a consulta retornará apenas os funcionários ativos cujo salário é maior + que um milhão de dólares. + </para> + + <para> + Nota: se você planeja usar filtros com outer join (por HQL ou por load fetching) seja cuidadoso + na direção da expressão de condição. É mais seguro configura-lo com para um left outer join; + geralmente, coloque o parâmetro primeiro seguido pelo nome da coluna após o operador. + </para> + + </sect1> + +</chapter> + Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/inheritance_mapping.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/inheritance_mapping.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/inheritance_mapping.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/inheritance_mapping.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,501 @@ +<chapter id="inheritance"> + <title>Mapeamento de Herança</title> + + <sect1 id="inheritance-strategies" revision="3"> + <title> As três estratégias</title> + + <para> + O Hibernate suporta as três estratégias básicas de mapeamento de herança: + </para> + + <itemizedlist> + <listitem> + <para> + tabela por hierarquia de classes + </para> + </listitem> + <listitem> + <para> + tabela por subclasse + </para> + </listitem> + <listitem> + <para> + tabela por classe concreta + </para> + </listitem> + </itemizedlist> + + <para> + Adicionalmente, o Hibernate suporta uma quarta, um tipo levemente + diferente de polimorfismo: + </para> + + <itemizedlist> + <listitem> + <para> + polimorfismo implícito + </para> + </listitem> + </itemizedlist> + + <para> + É possível usar diferentes estratégias de mapeamento para diferentes + ramificações da mesma hierarquia de herança, e então fazer uso do + polimorfismo implícito para alcançar polimorfismo através da + hierarquia completa. De qualquer forma, O Hibernate não suporta a + mistura de mapeamentos <literal>&lt;subclass&gt;</literal>, + and <literal>&lt;joined-subclass&gt;</literal> e + <literal>&lt;union-subclass&gt;</literal> dentro do mesmo elemento + raiz <literal>&lt;class&gt;</literal>. É possível usar junto às estratégias + tabela por hierarquia e a tabela por subclasse, abaixo do mesmo elemento + <literal>&lt;class&gt;</literal>, combinando os elementos + <literal>&lt;subclass&gt;</literal> e <literal>&lt;join&gt;</literal> + (veja abaixo). + + </para> + + <para> + É possível definir mapeamentos <literal>subclass</literal>, <literal>union-subclass</literal>, + e <literal>joined-subclass</literal> em documentos de mapeamento separados, diretamente abaixo de + <literal>hibernate-mapping</literal>. Isso permite a você estender uma hierarquia de classes + apenas adicionando um novo arquivo de mapeamento. Você deve especificar um atributo + <literal>extends</literal> no mapeamento da subclasse, nomeando uma superclasse previamente + mapeada. Nota: Anteriormente esta característica fazia o ordenamento dos documentos de + mapeamento importantes. Desde o Hibernate3, o ordenamento dos arquivos de mapeamento não + importa quando usamos a palavra chave extends. O ordenamento dentro de um arquivo de mapeamento + simples ainda necessita ser definido como superclasse antes de subclasse. + </para> + + <programlisting><![CDATA[ + <hibernate-mapping> + <subclass name="DomesticCat" extends="Cat" discriminator-value="D"> + <property name="name" type="string"/> + </subclass> + </hibernate-mapping>]]></programlisting> + + + <sect2 id="inheritance-tableperclass" > + <title>Tabela por hierarquia de classes</title> + + <para> + Suponha que tenhamos uma interface <literal>Payment</literal>, com sua + implementação <literal>CreditCardPayment</literal>, <literal>CashPayment</literal>, + <literal>ChequePayment</literal>. O mapeamento da tabela por hierarquia + seria parecido com: + </para> + + <programlisting><![CDATA[<class name="Payment" table="PAYMENT"> + <id name="id" type="long" column="PAYMENT_ID"> + <generator class="native"/> + </id> + <discriminator column="PAYMENT_TYPE" type="string"/> + <property name="amount" column="AMOUNT"/> + ... + <subclass name="CreditCardPayment" discriminator-value="CREDIT"> + <property name="creditCardType" column="CCTYPE"/> + ... + </subclass> + <subclass name="CashPayment" discriminator-value="CASH"> + ... + </subclass> + <subclass name="ChequePayment" discriminator-value="CHEQUE"> + ... + </subclass> +</class>]]></programlisting> + + <para> + Exactly one table is required. There is one big limitation of this mapping + strategy: columns declared by the subclasses, such as <literal>CCTYPE</literal>, + may not have <literal>NOT NULL</literal> constraints. + </para> + + </sect2> + + <sect2 id="inheritance-tablepersubclass"> + <title>Tabela por subclasse</title> + + <para> + Um mapeamento de tabela por subclasse seria parecido com: + </para> + + <programlisting><![CDATA[<class name="Payment" table="PAYMENT"> + <id name="id" type="long" column="PAYMENT_ID"> + <generator class="native"/> + </id> + <property name="amount" column="AMOUNT"/> + ... + <joined-subclass name="CreditCardPayment" table="CREDIT_PAYMENT"> + <key column="PAYMENT_ID"/> + <property name="creditCardType" column="CCTYPE"/> + ... + </joined-subclass> + <joined-subclass name="CashPayment" table="CASH_PAYMENT"> + <key column="PAYMENT_ID"/> + ... + </joined-subclass> + <joined-subclass name="ChequePayment" table="CHEQUE_PAYMENT"> + <key column="PAYMENT_ID"/> + ... + </joined-subclass> +</class>]]></programlisting> + + <para> + Quatro tabelas são necessárias. As três tabelas subclasses possuem + associação de chave primária para a tabela de superclasse + (então o modelo relacional é atualmente uma associação de + um-para-um). + </para> + + </sect2> + + <sect2 id="inheritance-tablepersubclass-discriminator" revision="2"> + <title>Tabela por subclasse, usando um discriminador</title> + + <para> + Note que a implementação de tabela por subclasse do Hibernate não + necessita de coluna de discriminador. Outro mapeador objeto/relacional + usa uma implementação diferente de tabela por subclasse, que necessita + uma coluna com o tipo discriminador na tabela da superclasse. A + abordagem escolhida pelo Hibernate é muito mais difícil de implementar, + porém de forma argumentável mais correto de um ponto de vista relacional. + Se você deseja utilizar uma coluna discriminadora com a estratégia + tabela por subclasse, você pode combinar o uso de + <literal>&lt;subclass&gt;</literal> e <literal>&lt;join&gt;</literal>, + dessa maneira: + </para> + + <programlisting><![CDATA[<class name="Payment" table="PAYMENT"> + <id name="id" type="long" column="PAYMENT_ID"> + <generator class="native"/> + </id> + <discriminator column="PAYMENT_TYPE" type="string"/> + <property name="amount" column="AMOUNT"/> + ... + <subclass name="CreditCardPayment" discriminator-value="CREDIT"> + <join table="CREDIT_PAYMENT"> + <key column="PAYMENT_ID"/> + <property name="creditCardType" column="CCTYPE"/> + ... + </join> + </subclass> + <subclass name="CashPayment" discriminator-value="CASH"> + <join table="CASH_PAYMENT"> + <key column="PAYMENT_ID"/> + ... + </join> + </subclass> + <subclass name="ChequePayment" discriminator-value="CHEQUE"> + <join table="CHEQUE_PAYMENT" fetch="select"> + <key column="PAYMENT_ID"/> + ... + </join> + </subclass> +</class>]]></programlisting> + + <para> + The optional <literal>fetch="select"</literal> declaration tells Hibernate + not to fetch the <literal>ChequePayment</literal> subclass data using an + outer join when querying the superclass. +A declaração opcional fetch=”select” diz ao Hibernate para não buscar os dados da subclasse ChequePayment, quando usar um outer join pesquisando pela superclasse. + </para> + + </sect2> + + <sect2 id="inheritance-mixing-tableperclass-tablepersubclass"> + <title>. Misturando tabela por hierarquia de classes com tabela por subclasse</title> + + <para> + Você pode até mesmo misturar a estratégia de tabela por hierarquia e + tabela por subclasse usando esta abordagem: + </para> + + <programlisting><![CDATA[<class name="Payment" table="PAYMENT"> + <id name="id" type="long" column="PAYMENT_ID"> + <generator class="native"/> + </id> + <discriminator column="PAYMENT_TYPE" type="string"/> + <property name="amount" column="AMOUNT"/> + ... + <subclass name="CreditCardPayment" discriminator-value="CREDIT"> + <join table="CREDIT_PAYMENT"> + <property name="creditCardType" column="CCTYPE"/> + ... + </join> + </subclass> + <subclass name="CashPayment" discriminator-value="CASH"> + ... + </subclass> + <subclass name="ChequePayment" discriminator-value="CHEQUE"> + ... + </subclass> +</class>]]></programlisting> + + <para> + Para qualquer uma dessas estratégias de mapeamento, uma associação + polimórfica para a classe raiz <literal>Payment</literal> deve ser + mapeada usando <literal>&lt;many-to-one&gt;</literal>. + </para> + + <programlisting><![CDATA[<many-to-one name="payment" column="PAYMENT_ID" class="Payment"/>]]></programlisting> + + </sect2> + + <sect2 id="inheritance-tableperconcrete" revision="2"> + <title>Tabela por classe concreta</title> + + <para> + Existem duas formas que poderíamos usar a respeito da estratégia de + mapeamento de tabela por classe concreta. A primeira é usar + <literal>&lt;union-subclass&gt;</literal>.. + </para> + + <programlisting><![CDATA[<class name="Payment"> + <id name="id" type="long" column="PAYMENT_ID"> + <generator class="sequence"/> + </id> + <property name="amount" column="AMOUNT"/> + ... + <union-subclass name="CreditCardPayment" table="CREDIT_PAYMENT"> + <property name="creditCardType" column="CCTYPE"/> + ... + </union-subclass> + <union-subclass name="CashPayment" table="CASH_PAYMENT"> + ... + </union-subclass> + <union-subclass name="ChequePayment" table="CHEQUE_PAYMENT"> + ... + </union-subclass> +</class>]]></programlisting> + + <para> + Três tabelas estão envolvidas para as subclasses. Cada tabela define + colunas para todas as propriedades da classe, incluindo propriedades herdadas. + </para> + + <para> + A limitação dessa abordagem é que se uma propriedade é mapeada na + superclasse, o nome da coluna deve ser o mesmo em todas as tabelas das + subclasses. (Nós devemos melhorar isto em um futuro release do Hibernate). + A estratégia do gerador de identidade não é permitida em união de + subclasses(union-subclass) herdadas, na verdade a fonte de chave + primária deve ser compartilhada através de todas subclasses unidas da + hierarquia. + + </para> + + <para> + Se sua superclasse é abstrata, mapeie ela com <literal>abstract="true"</literal>. + Claro, que se ela não for abstrata, uma tabela (padrão para <literal>PAYMENT</literal> + no exemplo acima) adicional é necessária para segurar as instâncias da superclasse. + </para> + + </sect2> + + <sect2 id="inheritance-tableperconcreate-polymorphism"> + <title>Tabela por classe concreta, usando polimorfismo implícito</title> + + <para> + Uma abordagem alternativa é fazer uso de polimorfismo implícito: + </para> + + <programlisting><![CDATA[<class name="CreditCardPayment" table="CREDIT_PAYMENT"> + <id name="id" type="long" column="CREDIT_PAYMENT_ID"> + <generator class="native"/> + </id> + <property name="amount" column="CREDIT_AMOUNT"/> + ... +</class> + +<class name="CashPayment" table="CASH_PAYMENT"> + <id name="id" type="long" column="CASH_PAYMENT_ID"> + <generator class="native"/> + </id> + <property name="amount" column="CASH_AMOUNT"/> + ... +</class> + +<class name="ChequePayment" table="CHEQUE_PAYMENT"> + <id name="id" type="long" column="CHEQUE_PAYMENT_ID"> + <generator class="native"/> + </id> + <property name="amount" column="CHEQUE_AMOUNT"/> + ... +</class>]]></programlisting> + + <para> + Veja que em nenhum lugar mencionamos a interface <literal>Payment</literal> + explicitamente. Também preste atenção que propriedades de <literal>Payment</literal> + são mapeadas em cada uma das subclasses. Se você quer evitar duplicação, + considere usar entidades de XML (ex. (e.g. <literal>[ &lt;!ENTITY allproperties + SYSTEM "allproperties.xml"&gt; ]</literal> na declaração do <literal>DOCTYPE</literal> + e <literal>&amp;allproperties;</literal> no mapeamento). + </para> + + <para> + A desvantagem dessa abordagem é que o Hibernate não gera <literal>UNION</literal>s + SQL quando executa pesquisas polimórficas. + </para> + + <para> + Para essa estratégia, uma associação polimórfica para <literal>Payment</literal> + geralmente é mapeada usando <literal>&lt;any&gt;</literal>. + </para> + + <programlisting><![CDATA[<any name="payment" meta-type="string" id-type="long"> + <meta-value value="CREDIT" class="CreditCardPayment"/> + <meta-value value="CASH" class="CashPayment"/> + <meta-value value="CHEQUE" class="ChequePayment"/> + <column name="PAYMENT_CLASS"/> + <column name="PAYMENT_ID"/> +</any>]]></programlisting> + + </sect2> + + <sect2 id="inheritace-mixingpolymorphism"> + <title>Misturando polimorfismo implícito com outros mapeamentos de herança</title> + + <para> + Ainda existe uma coisa para ser observada com respeito a este mapeamento. + Desde que as subclasses sejam mapeadas em seu próprio elemento + <literal>&lt;class&gt;</literal> (e desde que <literal>Payment</literal> seja + apenas uma interface), cada uma das subclasses pode ser facilmente parte de uma + outra hierarquia de herança! (E você ainda pode usar pesquisas polimórficas + em cima da interface <literal>Payment</literal>.) + + </para> + + <programlisting><![CDATA[<class name="CreditCardPayment" table="CREDIT_PAYMENT"> + <id name="id" type="long" column="CREDIT_PAYMENT_ID"> + <generator class="native"/> + </id> + <discriminator column="CREDIT_CARD" type="string"/> + <property name="amount" column="CREDIT_AMOUNT"/> + ... + <subclass name="MasterCardPayment" discriminator-value="MDC"/> + <subclass name="VisaPayment" discriminator-value="VISA"/> +</class> + +<class name="NonelectronicTransaction" table="NONELECTRONIC_TXN"> + <id name="id" type="long" column="TXN_ID"> + <generator class="native"/> + </id> + ... + <joined-subclass name="CashPayment" table="CASH_PAYMENT"> + <key column="PAYMENT_ID"/> + <property name="amount" column="CASH_AMOUNT"/> + ... + </joined-subclass> + <joined-subclass name="ChequePayment" table="CHEQUE_PAYMENT"> + <key column="PAYMENT_ID"/> + <property name="amount" column="CHEQUE_AMOUNT"/> + ... + </joined-subclass> +</class>]]></programlisting> + + <para> + Mais uma vez, nós não mencionamos <literal>Payment</literal> explicitamente. + Se nós executarmos uma pesquisa em cima da interface <literal>Payment</literal> – + por exemplo, <literal>from Payment</literal> – o Hibernate retorna + automaticamente instâncias de <literal>CreditCardPayment</literal> (e suas + subclasses, desde que elas também implementem <literal>Payment</literal>), + <literal>CashPayment</literal> e <literal>ChequePayment</literal> mas + não as instâncias de <literal>NonelectronicTransaction</literal>. + </para> + + </sect2> + + </sect1> + + <sect1 id="inheritance-limitations"> + <title>Limitações</title> + + <para> + Existem certas limitações para a abordagem do "polimorfismo implícito" + comparada com a estratégia de mapeamento da tabela por classe concreta. + Existe uma limitação um tanto menos restritiva para mapeamentos + <literal>&lt;union-subclass&gt;</literal>. + + </para> + + <para> + A tabela seguinte demonstra as limitações do mapeamento de tabela + por classe concreta e do polimorfismo implícito no Hibernate. + </para> + + <table frame="topbot"> + <title>Features of inheritance mappings</title> + <tgroup cols='8' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="1*"/> + <colspec colname='c3' colwidth="1*"/> + <colspec colname='c4' colwidth="1*"/> + <colspec colname='c5' colwidth="1*"/> + <colspec colname='c6' colwidth="1*"/> + <colspec colname='c7' colwidth="1*"/> + <colspec colname='c8' colwidth="1*"/> + <thead> + <row> + <entry>Estratégia de Herança</entry> + <entry>muitos-para-um Polimórfico</entry> + <entry>um-para-um Polimórfico</entry> + <entry>um-para-muitos Polimórfico</entry> + <entry>muitos-para-muitos Polimórfico</entry> + <entry><literal>load()/get()</literal> Polimórfico </entry> + <entry>Pesquisas Polimórficas</entry> + <entry>Joins polimórficos</entry> + <entry>Outer join fetching</entry> + </row> + </thead> + <tbody> + <row> + <entry>table per class-hierarchy</entry> + <entry><literal>&lt;many-to-one&gt;</literal></entry> + <entry><literal>&lt;one-to-one&gt;</literal></entry> + <entry><literal>&lt;one-to-many&gt;</literal></entry> + <entry><literal>&lt;many-to-many&gt;</literal></entry> + <entry><literal>s.get(Payment.class, id)</literal></entry> + <entry><literal>from Payment p</literal></entry> + <entry><literal>from Order o join o.payment p</literal></entry> + <entry><emphasis>supported</emphasis></entry> + </row> + <row> + <entry>table per subclass</entry> + <entry><literal>&lt;many-to-one&gt;</literal></entry> + <entry><literal>&lt;one-to-one&gt;</literal></entry> + <entry><literal>&lt;one-to-many&gt;</literal></entry> + <entry><literal>&lt;many-to-many&gt;</literal></entry> + <entry><literal>s.get(Payment.class, id)</literal></entry> + <entry><literal>from Payment p</literal></entry> + <entry><literal>from Order o join o.payment p</literal></entry> + <entry><emphasis>supported</emphasis></entry> + </row> + <row> + <entry>table per concrete-class (union-subclass)</entry> + <entry><literal>&lt;many-to-one&gt;</literal></entry> + <entry><literal>&lt;one-to-one&gt;</literal></entry> + <entry><literal>&lt;one-to-many&gt;</literal> (for <literal>inverse="true"</literal> only)</entry> + <entry><literal>&lt;many-to-many&gt;</literal></entry> + <entry><literal>s.get(Payment.class, id)</literal></entry> + <entry><literal>from Payment p</literal></entry> + <entry><literal>from Order o join o.payment p</literal></entry> + <entry><emphasis>supported</emphasis></entry> + </row> + <row> + <entry>table per concrete class (implicit polymorphism)</entry> + <entry><literal>&lt;any&gt;</literal></entry> + <entry><emphasis>not supported</emphasis></entry> + <entry><emphasis>not supported</emphasis></entry> + <entry><literal>&lt;many-to-any&gt;</literal></entry> + <entry><literal>s.createCriteria(Payment.class).add( Restrictions.idEq(id) ).uniqueResult()</literal></entry> + <entry><literal>from Payment p</literal></entry> + <entry><emphasis>not supported</emphasis></entry> + <entry><emphasis>not supported</emphasis></entry> + </row> + </tbody> + </tgroup> + </table> + + </sect1> + +</chapter> Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/performance.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/performance.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/performance.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/performance.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,1384 @@ +<chapter id="performance"> + <title>Aumentando a performance</title> + + <sect1 id="performance-fetching" revision="2"> + <title>Estratégias de Fetching</title> + + <para> + Uma <emphasis>estratégia de fetching</emphasis> é a estratégia que o Hibernate + irá usar para buscar objetos associados se a aplicação precisar navegar pela associação. + Estratégias de Fetch podem ser declaradas nos metadados de mapeamento O/R, ou sobrescritos + por uma query HQL ou query com <literal>Criteria</literal>. + </para> + + <para> + Hibernate3 define as seguintes estratégias de fetching: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>Join fetching</emphasis> - o Hibernate busca o objeto + ou coleção associada no mesmo <literal>SELECT</literal>, usando um + <literal>OUTER JOIN</literal>. + </para> + </listitem> + <listitem> + <para> + <emphasis>Select fetching</emphasis> - um segundo <literal>SELECT</literal> é + usado para buscar a entidade ou coleção associada. A menos que você desabilite + lazy fetching especificando <literal>lazy="false"</literal>, esse segundo SELECT + será executado apenas quando você acessar a associação. + </para> + </listitem> + <listitem> + <para> + <emphasis>Subselect fetching</emphasis> - um segundo <literal>SELECT</literal> será + usado para buscar as coleções associadas de todas as entidades buscadas na query ou + fetch anterior. A menos que você desabilite lazy fetching especificando + <literal>lazy="false"</literal>, esse segundo SELECT será executado apenas quando + você acessar a associação. + </para> + </listitem> + <listitem> + <para> + <emphasis>Batch fetching</emphasis> - uma opção de otimização para o Select + Fetching – O Hibernate busca um lote de instâncias ou entidades usando um único + <literal>SELECT</literal>, especificando uma lista de chaves primárias ou chaves + estrangeiras. + </para> + </listitem> + </itemizedlist> + + <para> + O Hibernate distingue também entre: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>Immediate fetching</emphasis> - uma associação, coleção ou atributo é buscado + como ela é carregada (Qual SQL é usado). Não se confuda com eles! Nós usamos fetch para melhorar a performance. Nós podemos usar lazy para definir um contrato para qual dado é sempre disponível em qualquer instância desanexada de uma classe qualquer. + imediatamente, quando o pai é carregado. + </para> + </listitem> + <listitem> + <para> + <emphasis>Lazy collection fetching</emphasis> - a coleção é buscada quando a + aplicação invoca uma operação sobre aquela coleção (Esse é o padrão para coleções) + </para> + </listitem> + <listitem> + <para> + <emphasis>"Extra-lazy" collection fetching</emphasis> - elementos individuais de uma + coleção são acessados do banco de dados quando preciso. O Hibernate tenta não buscar + a coleção inteira dentro da memória ao menos que seja absolutamente preciso. + (indicado para coleções muito grandes) + </para> + </listitem> + <listitem> + <para> + <emphasis>Proxy fetching</emphasis> - uma associação de um valor é carregada quando um método + diferente do getter do identificador é invocado sobre o objeto associado. + </para> + </listitem> + <listitem> + <para> + <emphasis>"No-proxy" fetching</emphasis> - uma associação de um valor é carregada quando + a variável da instância é carregada. Comparada com a proxy fetching, esse método é menos + preguiçoso (lazy)(a associação é carregada somente quando o identificador é acessada) + mas é mais transparente, já que não há proxies visíveis para a aplicação. + Esse método requer instrumentação de bytecodes em build-time e é raramente necessário. + </para> + </listitem> + <listitem> + <para> + <emphasis>Lazy attribute fetching</emphasis> - um atributo ou associação de um valor é + carregada quanto a varíavel da instância é acessada. Esse método requer instrumentação + de bytecodes em build-time e é raramente necessário. + </para> + </listitem> + </itemizedlist> + + <para> + Nós temos aqui duas noções ortogonais: <emphasis>quando</emphasis> a associação é carregada e + <emphasis>como </emphasis> ela é carregada (Qual SQL é usado). Não se confuda com eles! Nós + usamos <literal>fetch</literal> para melhorar a performance. Nós podemos usar lazy para + definir um contrato para qual dado é sempre disponível em qualquer instância desconectada + de uma classe qualquer. + </para> + + <sect2 id="performance-fetching-lazy"> + <title>Inicializando coleções e proxies</title> + + <para> + Por padrão, o Hibernate3 usa busca preguiçosa para coleções e busca preguiçosa + com proxy para associações de um valor. Esses padrões fazem sentido para quase + todas as associações em quase todas a aplicações. + </para> + + <para> + <emphasis>Veja:</emphasis> se voce setar + <literal>hibernate.default_batch_fetch_size</literal>, O Hibernate irá usar otimização + de carregamento em lote para o carregamento preguiçoso(Essa otimização pode ser também + habilitada em um nível mais fino). + </para> + + <para> + Porém, a busca preguiçosa tem um problema que você precisar saber. Acesso a associações + preguiçosas fora do contexto de uma sessão aberta do Hibernate irá resultar numa exceção. + Por exemplo: + </para> + + <programlisting><![CDATA[s = sessions.openSession(); +Transaction tx = s.beginTransaction(); + +User u = (User) s.createQuery("from User u where u.name=:userName") + .setString("userName", userName).uniqueResult(); +Map permissions = u.getPermissions(); + +tx.commit(); +s.close(); + +Integer accessLevel = (Integer) permissions.get("accounts"); // Error!]]></programlisting> + + <para> + Como a coleção de permissões não foi inicializada quando a <literal>Session</literal> + foi fechada, a coleção não poderá carregar o seu estado. O Hibernate não suporta + inicialização preguiçosa para objetos desconectados. Para consertar isso, é necessário + mover o código que carrega a coleção para antes da transação ser comitada. + </para> + + <para> + Alternativamente, nós podemos usar uma coleção ou associação não preguiçosa, + especificando <literal>lazy="false"</literal> para o mapeamento da associação. + Porém, é pretendido que a inicialização preguiçosa seja usada por quase todas as + coleções e associações. Se você definir muitas associações não preguiçosas em seu + modelo de objetos, o Hibernate irá precisar carregar o banco de dados inteiro na memória + em cada transação! + </para> + + <para> + Por outro lado, nós geralmente escolhemos join fetching (que é não preguiçosa por natureza) + ao invés de select fetching em uma transação particular. Nós iremos ver como customizar + a estratégoa de busca. No Hibernate3, os mecanismos para escolher a estratégia de fetching + são identicos para as associações simples e para coleções. + </para> + + </sect2> + + <sect2 id="performance-fetching-custom" revision="4"> + <title>Personalizando as estratégias de busca</title> + + <para> + O select fetching (o padrão) é extremamente vunerável para N+1 problemas em select, + então nós iremos querer habilitar o join fetching no documento de mapeamento: + </para> + + <programlisting><![CDATA[<set name="permissions" + fetch="join"> + <key column="userId"/> + <one-to-many class="Permission"/> +</set]]></programlisting> + + <programlisting><![CDATA[<many-to-one name="mother" class="Cat" fetch="join"/>]]></programlisting> + + <para> + A estratégia de <literal>fetch</literal> definida no documento de mapeamento afeta: + </para> + + <itemizedlist> + <listitem> + <para> + recupera via <literal>get()</literal> ou <literal>load()</literal> + </para> + </listitem> + <listitem> + <para> + Recuperações que acontecem implicitamente quando navegamos por uma associação + </para> + </listitem> + <listitem> + <para> + <literal>Criteria</literal> queries + </para> + </listitem> + <listitem> + <para> + buscas por HQL se buscar por <literal>subselect</literal> for usado + </para> + </listitem> + </itemizedlist> + + <para> + Independentemente da estratégia de busca que você usar, o grafo não preguiçoso definido + será garantidamente carregado na memória. Note que isso irá resultar em diversos selects + imediatos sendo usados em um HQL em particular. + </para> + + <para> + Usualmente não usamos documentos de mapeamento para customizar as buscas. Ao invés disso, + nós deixamos o comportamento padrão e sobrescrevemos isso em uma transação em particular, + usando <literal>left join fetch</literal> no HQL. Isso diz ao Hibernate para buscar a associação + inteira no primeiro select, usando um outer join. Na API de busca <literal>Criteria</literal>, + você irá usar <literal>setFetchMode(FetchMode.JOIN)</literal>. + </para> + + <para> + Se você quiser mudar a estratégia de busca usada pelo <literal>get()</literal> + ou <literal>load()</literal>, simplesmente use uma query <literal>Criteria</literal>, + por exemplo: + </para> + + <programlisting><![CDATA[User user = (User) session.createCriteria(User.class) + .setFetchMode("permissions", FetchMode.JOIN) + .add( Restrictions.idEq(userId) ) + .uniqueResult();]]></programlisting> + + <para> + (Isto é o equivalente do Hibernate para o que algumas soluções ORM chamam de "plano de busca") + </para> + + <para> + Um meio totalmente diferente de evitar problemas com selects N+1 é usar um cache de segundo nível. + </para> + + </sect2> + + <sect2 id="performance-fetching-proxies" revision="2"> + <title>Proxies de associação single-ended</title> + + <para> + A recuperação preguiçosa para coleções é implementada usando uma implementação + própria do Hibernate para coleções persistentes. Porém, um mecanismo diferente é + necessário para comportamento preguiçoso para associações de um lado só. A entidade + alvo da associação precisa usar um proxy. O Hibernate implementa proxies para inicialização + preguiçosa em objetos persistentes usando manipulação de bytecode + (via a excelente biblioteca CGLIB). + </para> + + <para> + Por padrão, o Hibernate3 gera proxies (na inicialização) para todas as classes + persistentes que usem eles para habilitar recuperaçãopreguiçosa de associações + <literal>many-to-one</literal> e <literal>one-to-one</literal>. + </para> + + <para> + O arquivo de mapeamento deve declaram uma interface para usar como interface de proxy + para aquela classe, com o atributo <literal>proxy</literal>. Por padrão, o Hibernate usa + uma subclasse dessa classe. <emphasis>Note que a classe a ser usada via proxy precisa + implementar o construtor padrão com pelo menos visibilidade de package. Nós recomendamos + esse construtor para todas as classes persistentes!</emphasis> + </para> + + <para> + Existe alguns truques que você deve saber quando extender esse comportamento para classes + polimórficas, dessa maneira: + </para> + + <programlisting><![CDATA[<class name="Cat" proxy="Cat"> + ...... + <subclass name="DomesticCat"> + ..... + </subclass> +</class>]]></programlisting> + + <para> + Primeiramente, instâncias de <literal>Cat</literal> nunca seráo convertidas + para <literal>DomesticCat</literal>, mesmo que a instância em questão seja uma + estância de <literal>DomesticCat</literal>: + </para> + + <programlisting><![CDATA[Cat cat = (Cat) session.load(Cat.class, id); // instantiate a proxy (does not hit the db) +if ( cat.isDomesticCat() ) { // hit the db to initialize the proxy + DomesticCat dc = (DomesticCat) cat; // Error! + .... +}]]></programlisting> + + <para> + É possível quebrar o proxy <literal>==</literal>. + </para> + + <programlisting><![CDATA[Cat cat = (Cat) session.load(Cat.class, id); // instantiate a Cat proxy +DomesticCat dc = + (DomesticCat) session.load(DomesticCat.class, id); // acquire new DomesticCat proxy! +System.out.println(cat==dc); // false]]></programlisting> + + <para> + Porém a situação não é tão ruim como parece. Mesmo quando temos duas referências para + objetos proxies diferentes, a instância deles será o mesmo objeto + </para> + + <programlisting><![CDATA[cat.setWeight(11.0); // hit the db to initialize the proxy +System.out.println( dc.getWeight() ); // 11.0]]></programlisting> + + <para> + Terceiro, Você não pode usar um proxy CGLIB em uma classe <literal>final</literal> + ou com qualquer método <literal>final</literal>. + </para> + + <para> + Finalmente, se o seu objeto persistente adquirir qualquer recursto durante a instanciação + (em inicializadores ou construtor padrão), então esses recursos serão adquiridos pelo proxy + também. A classe de proxy é uma subclasse da classe persistente. + </para> + + <para> + Esses problemas são todos devido a limitação fundamental do modelo de herança simples do Java. + Se você quiser evitar esse problemas em suas classes persistentes você deve imeplementar uma + interface que declare seus métodos de negócio. Você deve especificar essas interfaces no arquivo + de mapeamento. Ex: + </para> + + <programlisting><![CDATA[<class name="CatImpl" proxy="Cat"> + ...... + <subclass name="DomesticCatImpl" proxy="DomesticCat"> + ..... + </subclass> +</class>]]></programlisting> + + <para> + onde <literal>CatImpl</literal> implementa a interface <literal>Cat</literal> e + <literal>DomesticCatImpl</literal> implementa a interface <literal>DomesticCat</literal>. + Então proxies para instâncias de <literal>Cat</literal> e <literal>DomesticCat</literal> + serão retornadas por <literal>load()</literal> ou <literal>iterate()</literal>. + (Note que <literal>list()</literal> geralmente não retorna proxies). + </para> + + <programlisting><![CDATA[Cat cat = (Cat) session.load(CatImpl.class, catid); +Iterator iter = session.createQuery("from CatImpl as cat where cat.name='fritz'").iterate(); +Cat fritz = (Cat) iter.next();]]></programlisting> + + <para> + Relacionamentos são também carregados preguiçosamente. Isso significa que você precisa declarar + qualquer propriedade como sendo do tipo <literal>Cat</literal>, e não <literal>CatImpl</literal>. + </para> + + <para> + Algumas operações <emphasis>não</emphasis> requerem inicialização por proxy: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>equals()</literal>, se a classe persistente não sobrescrever + <literal>equals()</literal> + </para> + </listitem> + <listitem> + <para> + <literal>hashCode()</literal>, se a classe persistente não sobrescrever + <literal>hashCode()</literal> + </para> + </listitem> + <listitem> + <para> + O método getter do identificador + </para> + </listitem> + </itemizedlist> + + <para> + O Hibernate irá detectar classes persistentes que sobrescrevem + <literal>equals()</literal> ou <literal>hashCode()</literal>. + </para> + + <para> + Escolhendo <literal>lazy="no-proxy"</literal> ao invés do padrão + <literal>lazy="proxy"</literal>, podemos evitar problemas associados com typecasting. + Porém, iremos precisar de instrumentação de bytecode em tempo de compilação e todas + as operações irão resultar em iniciazações de proxy imediatas. + </para> + + </sect2> + + <sect2 id="performance-fetching-initialization" revision="1"> + <title>Inicializando coleções e proxies</title> + + <para> + Será lançada uma <literal>LazyInitializationException</literal> se uma coleção não inicializada + ou proxy é acessado fora do escopo da <literal>Session</literal>, isto é, quando a entidade que + contém a coleção ou tem a referência ao proxy estiver no estado destachado. + </para> + + <para> + Algumas vezes precisamos garantir qie o proxy ou coleção é inicializado antes de se fechar a + <literal>Session</literal>. Claro que sempre podemos forçar a inicialização chamando + <literal>cat.getSex()</literal> ou <literal>cat.getKittens().size()</literal>, por exemplo. + Mas isto parece confuso para quem lê o código e não é conveniente para códigos genéricos. + </para> + + <para> + Os métodos estáticos <literal>Hibernate.initialize()</literal> e <literal>Hibernate.isInitialized()</literal> + possibilitam a aplicação uma maneira conveniente de trabalhar com coleções inicializadas preguiçosamente e + proxies. <literal>Hibernate.initialize(cat)</literal> irá forçar a inicialização de um proxy, + <literal>cat</literal>, contanto que a <literal>Session</literal> esteja ainda aberta. + <literal>Hibernate.initialize( cat.getKittens() )</literal> tem um efeito similar para a coleção de + kittens. + </para> + + <para> + Outra opção é manter a <literal>Session</literal> aberta até que todas as coleções e + proxies necessários sejam carregados. Em algumas arquiteturas de aplicações, particularmente + onde o código que acessa os dados usando Hibernate e o código que usa os dados estão em diferentes + camadas da aplicação ou diferentes processos físicos, será um problema garantir que a + <literal>Session</literal> esteja aberta quando uma coleção for inicializada. Existem dois + caminhos básicos para lidar com esse problema: + </para> + + <itemizedlist> + <listitem> + <para> + Em aplicações web, um filtro servlet pode ser usado para fechar a + <literal>Session</literal> somente no final da requisição do usuário, já que a + renderização da visão estará completa (o pattern <emphasis>Open Session In View</emphasis>). + Claro, que isto cria a necessidade de um correto manuseio de exceções na infraestrutura + de sua aplicação. É vitalmente importante que a <literal>Session</literal> esteja fechada + e a transação terminada antes de retornar para o usuário, mesmo que uma exceção ocorra + durante a renderização da view. Veja o Wiki do Hibernate para exemplos do pattern + "Open Session In View" + </para> + </listitem> + <listitem> + <para> + Em uma aplicação com uma camada de negócios separada, a lógica de negócios deve + "preparar" todas as coleções que serão usadas pela camada web antes de retornar. + Isto sgnifica que a camada de negócios deve carregar todos os dados e retorná-los + já inicializados para a camada de apresentação. Usualmente a aplicação chama + <literal>Hibernate.initialize()</literal> para cada coleção que será usada pela + camada web (essa chamada de método deve ocorrer antes da sessão ser fechada ou + retornar a coleção usando uma consulta Hibernate com uma cláusula <literal>FETCH</literal> + ou um <literal>FetchMode.JOIN</literal> na <literal>Criteria</literal>. Fica muito + mais fácil se você adotar o pattern <emphasis>Command</emphasis> ao invés do + <emphasis>Session Facade</emphasis>. + </para> + </listitem> + <listitem> + <para> + Você também pode anexar um objeto prevaimente carregado em uma nova + <literal>Session</literal> <literal>merge()</literal> or <literal>lock()</literal> + antes de acessar coleções não inicializadas (ou outros proxies). O Hibernate não faz + e certamente <literal>não deve</literal> isso automaticamente pois isso introduziria + semantica em transações ad hoc. + </para> + </listitem> + </itemizedlist> + + <para> + As vezes você não quer inicializar uma coleção muito grande, mas precisa de algumas + informações (como o tamanho) ou alguns de seus dados. + </para> + + <para> + Você pode usar um filtro de coleção para saber seu tamanho sem a inicializar: + </para> + + <programlisting><![CDATA[( (Integer) s.createFilter( collection, "select count(*)" ).list().get(0) ).intValue()]]></programlisting> + + <para> + O método <literal>createFilter()</literal> é usado também para retornar algus dados de uma + coleção eficientemente sem precisar inicializar a coleção inteira: + </para> + + <programlisting><![CDATA[s.createFilter( lazyCollection, "").setFirstResult(0).setMaxResults(10).list();]]></programlisting> + + </sect2> + + <sect2 id="performance-fetching-batch"> + <title>Usando busca em lote</title> + + <para> + O Hibernate pode fazer uso eficiente de busca em lote, isto é, o Hibernate pode carregar diversos + proxies não inicializados se um proxy é acessado (ou coleções. A busca em lote é uma otimização da + estratégia de select fetching). Existe duas maneiras em que você pode usar busca em lote: no nível + da classe ou no nível da coleção. + </para> + + <para> + A recuperação em lote para classes/entidades é mais fácil de entender. Imagine que você tem a seguinte + situação em tempo de execução: Você tem 25 instâncias de <literal>Cat</literal> carregadas em uma + <literal>Session</literal>, cada <literal>Cat</literal> tem uma referência ao seu <literal>owner</literal>, + que é da classe <literal>Person</literal>. A classe <literal>Person</literal> é mapeada com um proxy, + <literal>lazy="true"</literal>. Se você iterar sobre todos os Cat's e chamar <literal>getOwner()</literal> + em cada, o Hibernate irá por padrão executar 25 comandos <literal>SELECT()</literal>, para buscar os + proxies de owners. Você pode melhorar esse comportamento especificando um <literal>batch-size</literal> + no mapeamento da classe <literal>Person</literal>: + </para> + + <programlisting><![CDATA[<class name="Person" batch-size="10">...</class>]]></programlisting> + + <para> + O Hibernate irá executar agora apenas três consultas, buscando por vez, 10, 10 e 5 Person. + </para> + + <para> + Você também pode habilitar busca em lote de uma coleção. Por exemplo, se cada <literal>Person</literal> + tem uma coleção preguiçosa de <literal>Cat</literal>s, e 10 pessoas estão já carregados em uma + <literal>Sesssion</literal>, serão gerados 10 <literal>SELECT</literal>s ao se iterar todas as + pessoas, um para cada chamada de <literal>getCats()</literal>.. Se você habilitar busca em lote + para a coleção de <literal>cats</literal> no mapeamento da classe <literal>Person</literal>, + o Hibernate pode fazer uma pré carga das coleções: + </para> + + <programlisting><![CDATA[<class name="Person"> + <set name="cats" batch-size="3"> + ... + </set> +</class>]]></programlisting> + + <para> + Com um <literal>batch-size</literal> de 3, o Hibernate irá carregar 3, 3, 3, 1 coleções em 4 + <literal>SELECT</literal>s. Novamente, o valor do atributo depende do número esperado de coleções + não inicialiadas em determinada <literal>Session</literal>. + </para> + + <para> + A busca em lote de coleções é particularmente útil quando você tem uma árvore encadeada de + items, ex. o típico padrão bill-of-materials (Se bem que um <emphasis>conjunto encadeado</emphasis> + ou <emphasis>caminho materializado </emphasis> pode ser uma opção melhor para árvores com mais + leitura) + </para> + + </sect2> + + <sect2 id="performance-fetching-subselect"> + <title>Usando subselect fetching</title> + + <para> + Se uma coleção ou proxy simples precisa ser recuperado, o Hibernate carrega todos eles + rodando novamente a query original em um subselect. Isso funciona da mesma maneira que busca + em lote, sem carregar tanto. + </para> + + <!-- TODO: Write more about this --> + + </sect2> + + <sect2 id="performance-fetching-lazyproperties"> + <title>Usando busca preguiçosa de propriedade</title> + + <para> + O Hibernate3 suporta a carga posterior de propriedades individuais. Essa técnica de otimização + também conhecida como <emphasis>fetch groups</emphasis>. Veja que isso é mais uma funcionalidade + de marketing já que na prática, é mais importante otimização nas leituras dos registros do + que na leitura das colunas. Porém, carregar apenas algumas propriedades de uma classe pode + ser útil em casos extremos, onde tabelas legadas podem ter centenas de colunas e o modelo + de dados não pode ser melhorado. + </para> + + <para> + Para habilitar a carga posterior de propriedade, é preciso setar o atributo + <literal>lazy</literal> no seu mapeamento de propriedade: + </para> + + <programlisting><![CDATA[<class name="Document"> + <id name="id"> + <generator class="native"/> + </id> + <property name="name" not-null="true" length="50"/> + <property name="summary" not-null="true" length="200" lazy="true"/> + <property name="text" not-null="true" length="2000" lazy="true"/> +</class>]]></programlisting> + + <para> + A carga posterior de propriedades requer instrumentação de bytecode! Se suas classes + persistentes não forem melhoradas, o Hibernate irá ignorar silenciosamente essa + configuração e usará busca imediatamente. + </para> + + <para> + Para instrumentação de bytecode, use a seguinte tarefa do Ant: + </para> + + <programlisting><![CDATA[<target name="instrument" depends="compile"> + <taskdef name="instrument" classname="org.hibernate.tool.instrument.InstrumentTask"> + <classpath path="${jar.path}"/> + <classpath path="${classes.dir}"/> + <classpath refid="lib.class.path"/> + </taskdef> + + <instrument verbose="true"> + <fileset dir="${testclasses.dir}/org/hibernate/auction/model"> + <include name="*.class"/> + </fileset> + </instrument> +</target>]]></programlisting> + + <para> + A different (better?) way to avoid unnecessary column reads, at least for + read-only transactions is to use the projection features of HQL or Criteria + queries. This avoids the need for buildtime bytecode processing and is + certainly a prefered solution. + </para> + + <para> + You may force the usual eager fetching of properties using <literal>fetch all + properties</literal> in HQL. + </para> + + </sect2> + + </sect1> + + <sect1 id="performance-cache" revision="1"> + <title>The Second Level Cache</title> + + <para> + A Hibernate <literal>Session</literal> is a transaction-level cache of persistent data. It is + possible to configure a cluster or JVM-level (<literal>SessionFactory</literal>-level) cache on + a class-by-class and collection-by-collection basis. You may even plug in a clustered cache. Be + careful. Caches are never aware of changes made to the persistent store by another application + (though they may be configured to regularly expire cached data). + </para> + + <para revision="1"> + You have the option to tell Hibernate which caching implementation to use by + specifying the name of a class that implements <literal>org.hibernate.cache.CacheProvider</literal> + using the property <literal>hibernate.cache.provider_class</literal>. Hibernate + comes bundled with a number of built-in integrations with open-source cache providers + (listed below); additionally, you could implement your own and plug it in as + outlined above. Note that versions prior to 3.2 defaulted to use EhCache as the + default cache provider; that is no longer the case as of 3.2. + </para> + + <table frame="topbot" id="cacheproviders" revision="1"> + <title>Cache Providers</title> + <tgroup cols='5' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="3*"/> + <colspec colname='c3' colwidth="1*"/> + <colspec colname='c4' colwidth="1*"/> + <colspec colname='c5' colwidth="1*"/> + <thead> + <row> + <entry>Cache</entry> + <entry>Provider class</entry> + <entry>Type</entry> + <entry>Cluster Safe</entry> + <entry>Query Cache Supported</entry> + </row> + </thead> + <tbody> + <row> + <entry>Hashtable (not intended for production use)</entry> + <entry><literal>org.hibernate.cache.HashtableCacheProvider</literal></entry> + <entry>memory</entry> + <entry></entry> + <entry>yes</entry> + </row> + <row> + <entry>EHCache</entry> + <entry><literal>org.hibernate.cache.EhCacheProvider</literal></entry> + <entry>memory, disk</entry> + <entry></entry> + <entry>yes</entry> + </row> + <row> + <entry>OSCache</entry> + <entry><literal>org.hibernate.cache.OSCacheProvider</literal></entry> + <entry>memory, disk</entry> + <entry></entry> + <entry>yes</entry> + </row> + <row> + <entry>SwarmCache</entry> + <entry><literal>org.hibernate.cache.SwarmCacheProvider</literal></entry> + <entry>clustered (ip multicast)</entry> + <entry>yes (clustered invalidation)</entry> + <entry></entry> + </row> + <row> + <entry>JBoss TreeCache</entry> + <entry><literal>org.hibernate.cache.TreeCacheProvider</literal></entry> + <entry>clustered (ip multicast), transactional</entry> + <entry>yes (replication)</entry> + <entry>yes (clock sync req.)</entry> + </row> + </tbody> + </tgroup> + </table> + + <sect2 id="performance-cache-mapping" revision="2"> + <title>Cache mappings</title> + + <para> + The <literal>&lt;cache&gt;</literal> element of a class or collection mapping has the + following form: + </para> + + <programlistingco> + <areaspec> + <area id="cache1" coords="2 70"/> + <area id="cache2" coords="3 70"/> + <area id="cache3" coords="4 70"/> + </areaspec> + <programlisting><![CDATA[<cache + usage="transactional|read-write|nonstrict-read-write|read-only" + region="RegionName" + include="all|non-lazy" +/>]]></programlisting> + <calloutlist> + <callout arearefs="cache1"> + <para> + <literal>usage</literal> (required) specifies the caching strategy: + <literal>transactional</literal>, + <literal>read-write</literal>, + <literal>nonstrict-read-write</literal> or + <literal>read-only</literal> + </para> + </callout> + <callout arearefs="cache2"> + <para> + <literal>region</literal> (optional, defaults to the class or + collection role name) specifies the name of the second level cache + region + </para> + </callout> + <callout arearefs="cache3"> + <para> + <literal>include</literal> (optional, defaults to <literal>all</literal>) + <literal>non-lazy</literal> specifies that properties of the entity mapped + with <literal>lazy="true"</literal> may not be cached when attribute-level + lazy fetching is enabled + </para> + </callout> + </calloutlist> + </programlistingco> + + <para> + Alternatively (preferrably?), you may specify <literal>&lt;class-cache&gt;</literal> and + <literal>&lt;collection-cache&gt;</literal> elements in <literal>hibernate.cfg.xml</literal>. + </para> + + <para> + The <literal>usage</literal> attribute specifies a <emphasis>cache concurrency strategy</emphasis>. + </para> + + </sect2> + + <sect2 id="performance-cache-readonly"> + <title>Strategy: read only</title> + + <para> + If your application needs to read but never modify instances of a persistent class, a + <literal>read-only</literal> cache may be used. This is the simplest and best performing + strategy. It's even perfectly safe for use in a cluster. + </para> + + <programlisting><![CDATA[<class name="eg.Immutable" mutable="false"> + <cache usage="read-only"/> + .... +</class>]]></programlisting> + + </sect2> + + + <sect2 id="performance-cache-readwrite"> + <title>Strategy: read/write</title> + + <para> + If the application needs to update data, a <literal>read-write</literal> cache might be appropriate. + This cache strategy should never be used if serializable transaction isolation level is required. + If the cache is used in a JTA environment, you must specify the property + <literal>hibernate.transaction.manager_lookup_class</literal>, naming a strategy for obtaining the + JTA <literal>TransactionManager</literal>. In other environments, you should ensure that the transaction + is completed when <literal>Session.close()</literal> or <literal>Session.disconnect()</literal> is called. + If you wish to use this strategy in a cluster, you should ensure that the underlying cache implementation + supports locking. The built-in cache providers do <emphasis>not</emphasis>. + </para> + + <programlisting><![CDATA[<class name="eg.Cat" .... > + <cache usage="read-write"/> + .... + <set name="kittens" ... > + <cache usage="read-write"/> + .... + </set> +</class>]]></programlisting> + + </sect2> + + <sect2 id="performance-cache-nonstrict"> + <title>Strategy: nonstrict read/write</title> + + <para> + If the application only occasionally needs to update data (ie. if it is extremely unlikely that two + transactions would try to update the same item simultaneously) and strict transaction isolation is + not required, a <literal>nonstrict-read-write</literal> cache might be appropriate. If the cache is + used in a JTA environment, you must specify <literal>hibernate.transaction.manager_lookup_class</literal>. + In other environments, you should ensure that the transaction is completed when + <literal>Session.close()</literal> or <literal>Session.disconnect()</literal> is called. + </para> + + </sect2> + + <sect2 id="performance-cache-transactional"> + <title>Strategy: transactional</title> + + <para> + The <literal>transactional</literal> cache strategy provides support for fully transactional cache + providers such as JBoss TreeCache. Such a cache may only be used in a JTA environment and you must + specify <literal>hibernate.transaction.manager_lookup_class</literal>. + </para> + + </sect2> + + <para> + None of the cache providers support all of the cache concurrency strategies. The following table shows + which providers are compatible with which concurrency strategies. + </para> + + <table frame="topbot"> + <title>Cache Concurrency Strategy Support</title> + <tgroup cols='5' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="1*"/> + <colspec colname='c3' colwidth="1*"/> + <colspec colname='c4' colwidth="1*"/> + <colspec colname='c5' colwidth="1*"/> + <thead> + <row> + <entry>Cache</entry> + <entry>read-only</entry> + <entry>nonstrict-read-write</entry> + <entry>read-write</entry> + <entry>transactional</entry> + </row> + </thead> + <tbody> + <row> + <entry>Hashtable (not intended for production use)</entry> + <entry>yes</entry> + <entry>yes</entry> + <entry>yes</entry> + <entry></entry> + </row> + <row> + <entry>EHCache</entry> + <entry>yes</entry> + <entry>yes</entry> + <entry>yes</entry> + <entry></entry> + </row> + <row> + <entry>OSCache</entry> + <entry>yes</entry> + <entry>yes</entry> + <entry>yes</entry> + <entry></entry> + </row> + <row> + <entry>SwarmCache</entry> + <entry>yes</entry> + <entry>yes</entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry>JBoss TreeCache</entry> + <entry>yes</entry> + <entry></entry> + <entry></entry> + <entry>yes</entry> + </row> + </tbody> + </tgroup> + </table> + + </sect1> + + <sect1 id="performance-sessioncache" revision="2"> + <title>Managing the caches</title> + + <para> + Whenever you pass an object to <literal>save()</literal>, <literal>update()</literal> + or <literal>saveOrUpdate()</literal> and whenever you retrieve an object using + <literal>load()</literal>, <literal>get()</literal>, <literal>list()</literal>, + <literal>iterate()</literal> or <literal>scroll()</literal>, that object is added + to the internal cache of the <literal>Session</literal>. + </para> + <para> + When <literal>flush()</literal> is subsequently called, the state of that object will + be synchronized with the database. If you do not want this synchronization to occur or + if you are processing a huge number of objects and need to manage memory efficiently, + the <literal>evict()</literal> method may be used to remove the object and its collections + from the first-level cache. + </para> + + <programlisting><![CDATA[ScrollableResult cats = sess.createQuery("from Cat as cat").scroll(); //a huge result set +while ( cats.next() ) { + Cat cat = (Cat) cats.get(0); + doSomethingWithACat(cat); + sess.evict(cat); +}]]></programlisting> + + <para> + The <literal>Session</literal> also provides a <literal>contains()</literal> method to determine + if an instance belongs to the session cache. + </para> + + <para> + To completely evict all objects from the session cache, call <literal>Session.clear()</literal> + </para> + + <para> + For the second-level cache, there are methods defined on <literal>SessionFactory</literal> for + evicting the cached state of an instance, entire class, collection instance or entire collection + role. + </para> + + <programlisting><![CDATA[sessionFactory.evict(Cat.class, catId); //evict a particular Cat +sessionFactory.evict(Cat.class); //evict all Cats +sessionFactory.evictCollection("Cat.kittens", catId); //evict a particular collection of kittens +sessionFactory.evictCollection("Cat.kittens"); //evict all kitten collections]]></programlisting> + + <para> + The <literal>CacheMode</literal> controls how a particular session interacts with the second-level + cache. + </para> + + <itemizedlist> + <listitem> + <para> + <literal>CacheMode.NORMAL</literal> - read items from and write items to the second-level cache + </para> + </listitem> + <listitem> + <para> + <literal>CacheMode.GET</literal> - read items from the second-level cache, but don't write to + the second-level cache except when updating data + </para> + </listitem> + <listitem> + <para> + <literal>CacheMode.PUT</literal> - write items to the second-level cache, but don't read from + the second-level cache + </para> + </listitem> + <listitem> + <para> + <literal>CacheMode.REFRESH</literal> - write items to the second-level cache, but don't read from + the second-level cache, bypass the effect of <literal>hibernate.cache.use_minimal_puts</literal>, forcing + a refresh of the second-level cache for all items read from the database + </para> + </listitem> + </itemizedlist> + + <para> + To browse the contents of a second-level or query cache region, use the <literal>Statistics</literal> + API: + </para> + + <programlisting><![CDATA[Map cacheEntries = sessionFactory.getStatistics() + .getSecondLevelCacheStatistics(regionName) + .getEntries();]]></programlisting> + + <para> + You'll need to enable statistics, and, optionally, force Hibernate to keep the cache entries in a + more human-understandable format: + </para> + + <programlisting><![CDATA[hibernate.generate_statistics true +hibernate.cache.use_structured_entries true]]></programlisting> + + </sect1> + + <sect1 id="performance-querycache" revision="1"> + <title>The Query Cache</title> + + <para> + Query result sets may also be cached. This is only useful for queries that are run + frequently with the same parameters. To use the query cache you must first enable it: + </para> + + <programlisting><![CDATA[hibernate.cache.use_query_cache true]]></programlisting> + + <para> + This setting causes the creation of two new cache regions - one holding cached query + result sets (<literal>org.hibernate.cache.StandardQueryCache</literal>), the other + holding timestamps of the most recent updates to queryable tables + (<literal>org.hibernate.cache.UpdateTimestampsCache</literal>). Note that the query + cache does not cache the state of the actual entities in the result set; it caches + only identifier values and results of value type. So the query cache should always be + used in conjunction with the second-level cache. + </para> + + <para> + Most queries do not benefit from caching, so by default queries are not cached. To + enable caching, call <literal>Query.setCacheable(true)</literal>. This call allows + the query to look for existing cache results or add its results to the cache when + it is executed. + </para> + + <para> + If you require fine-grained control over query cache expiration policies, you may + specify a named cache region for a particular query by calling + <literal>Query.setCacheRegion()</literal>. + </para> + + <programlisting><![CDATA[List blogs = sess.createQuery("from Blog blog where blog.blogger = :blogger") + .setEntity("blogger", blogger) + .setMaxResults(15) + .setCacheable(true) + .setCacheRegion("frontpages") + .list();]]></programlisting> + + <para> + If the query should force a refresh of its query cache region, you should call + <literal>Query.setCacheMode(CacheMode.REFRESH)</literal>. This is particularly useful + in cases where underlying data may have been updated via a separate process (i.e., + not modified through Hibernate) and allows the application to selectively refresh + particular query result sets. This is a more efficient alternative to eviction of + a query cache region via <literal>SessionFactory.evictQueries()</literal>. + </para> + + </sect1> + + <sect1 id="performance-collections"> + <title>Understanding Collection performance</title> + + <para> + We've already spent quite some time talking about collections. + In this section we will highlight a couple more issues about + how collections behave at runtime. + </para> + + <sect2 id="performance-collections-taxonomy"> + <title>Taxonomy</title> + + <para>Hibernate defines three basic kinds of collections:</para> + + <itemizedlist> + <listitem> + <para>collections of values</para> + </listitem> + <listitem> + <para>one to many associations</para> + </listitem> + <listitem> + <para>many to many associations</para> + </listitem> + </itemizedlist> + + <para> + This classification distinguishes the various table and foreign key + relationships but does not tell us quite everything we need to know + about the relational model. To fully understand the relational structure + and performance characteristics, we must also consider the structure of + the primary key that is used by Hibernate to update or delete collection + rows. This suggests the following classification: + </para> + + <itemizedlist> + <listitem> + <para>indexed collections</para> + </listitem> + <listitem> + <para>sets</para> + </listitem> + <listitem> + <para>bags</para> + </listitem> + </itemizedlist> + + <para> + All indexed collections (maps, lists, arrays) have a primary key consisting + of the <literal>&lt;key&gt;</literal> and <literal>&lt;index&gt;</literal> + columns. In this case collection updates are usually extremely efficient - + the primary key may be efficiently indexed and a particular row may be efficiently + located when Hibernate tries to update or delete it. + </para> + + <para> + Sets have a primary key consisting of <literal>&lt;key&gt;</literal> and element + columns. This may be less efficient for some types of collection element, particularly + composite elements or large text or binary fields; the database may not be able to index + a complex primary key as efficently. On the other hand, for one to many or many to many + associations, particularly in the case of synthetic identifiers, it is likely to be just + as efficient. (Side-note: if you want <literal>SchemaExport</literal> to actually create + the primary key of a <literal>&lt;set&gt;</literal> for you, you must declare all columns + as <literal>not-null="true"</literal>.) + </para> + + <para> + <literal>&lt;idbag&gt;</literal> mappings define a surrogate key, so they are + always very efficient to update. In fact, they are the best case. + </para> + + <para> + Bags are the worst case. Since a bag permits duplicate element values and has no + index column, no primary key may be defined. Hibernate has no way of distinguishing + between duplicate rows. Hibernate resolves this problem by completely removing + (in a single <literal>DELETE</literal>) and recreating the collection whenever it + changes. This might be very inefficient. + </para> + + <para> + Note that for a one-to-many association, the "primary key" may not be the physical + primary key of the database table - but even in this case, the above classification + is still useful. (It still reflects how Hibernate "locates" individual rows of the + collection.) + </para> + + </sect2> + + <sect2 id="performance-collections-mostefficientupdate"> + <title>Lists, maps, idbags and sets are the most efficient collections to update</title> + + <para> + From the discussion above, it should be clear that indexed collections + and (usually) sets allow the most efficient operation in terms of adding, + removing and updating elements. + </para> + + <para> + There is, arguably, one more advantage that indexed collections have over sets for + many to many associations or collections of values. Because of the structure of a + <literal>Set</literal>, Hibernate doesn't ever <literal>UPDATE</literal> a row when + an element is "changed". Changes to a <literal>Set</literal> always work via + <literal>INSERT</literal> and <literal>DELETE</literal> (of individual rows). Once + again, this consideration does not apply to one to many associations. + </para> + + <para> + After observing that arrays cannot be lazy, we would conclude that lists, maps and + idbags are the most performant (non-inverse) collection types, with sets not far + behind. Sets are expected to be the most common kind of collection in Hibernate + applications. This is because the "set" semantics are most natural in the relational + model. + </para> + + <para> + However, in well-designed Hibernate domain models, we usually see that most collections + are in fact one-to-many associations with <literal>inverse="true"</literal>. For these + associations, the update is handled by the many-to-one end of the association, and so + considerations of collection update performance simply do not apply. + </para> + + </sect2> + + <sect2 id="performance-collections-mostefficentinverse"> + <title>Bags and lists are the most efficient inverse collections</title> + + <para> + Just before you ditch bags forever, there is a particular case in which bags (and also lists) + are much more performant than sets. For a collection with <literal>inverse="true"</literal> + (the standard bidirectional one-to-many relationship idiom, for example) we can add elements + to a bag or list without needing to initialize (fetch) the bag elements! This is because + <literal>Collection.add()</literal> or <literal>Collection.addAll()</literal> must always + return true for a bag or <literal>List</literal> (unlike a <literal>Set</literal>). This can + make the following common code much faster. + </para> + + <programlisting><![CDATA[Parent p = (Parent) sess.load(Parent.class, id); +Child c = new Child(); +c.setParent(p); +p.getChildren().add(c); //no need to fetch the collection! +sess.flush();]]></programlisting> + + </sect2> + + <sect2 id="performance-collections-oneshotdelete"> + <title>One shot delete</title> + + <para> + Occasionally, deleting collection elements one by one can be extremely inefficient. Hibernate + isn't completely stupid, so it knows not to do that in the case of an newly-empty collection + (if you called <literal>list.clear()</literal>, for example). In this case, Hibernate will + issue a single <literal>DELETE</literal> and we are done! + </para> + + <para> + Suppose we add a single element to a collection of size twenty and then remove two elements. + Hibernate will issue one <literal>INSERT</literal> statement and two <literal>DELETE</literal> + statements (unless the collection is a bag). This is certainly desirable. + </para> + + <para> + However, suppose that we remove eighteen elements, leaving two and then add thee new elements. + There are two possible ways to proceed + </para> + + <itemizedlist> + <listitem> + <para>delete eighteen rows one by one and then insert three rows</para> + </listitem> + <listitem> + <para>remove the whole collection (in one SQL <literal>DELETE</literal>) and insert + all five current elements (one by one)</para> + </listitem> + </itemizedlist> + + <para> + Hibernate isn't smart enough to know that the second option is probably quicker in this case. + (And it would probably be undesirable for Hibernate to be that smart; such behaviour might + confuse database triggers, etc.) + </para> + + <para> + Fortunately, you can force this behaviour (ie. the second strategy) at any time by discarding + (ie. dereferencing) the original collection and returning a newly instantiated collection with + all the current elements. This can be very useful and powerful from time to time. + </para> + + <para> + Of course, one-shot-delete does not apply to collections mapped <literal>inverse="true"</literal>. + </para> + + </sect2> + + </sect1> + + <sect1 id="performance-monitoring" revision="1"> + <title>Monitoring performance</title> + + <para> + Optimization is not much use without monitoring and access to performance numbers. + Hibernate provides a full range of figures about its internal operations. + Statistics in Hibernate are available per <literal>SessionFactory</literal>. + </para> + + <sect2 id="performance-monitoring-sf" revision="2"> + <title>Monitoring a SessionFactory</title> + + <para> + You can access <literal>SessionFactory</literal> metrics in two ways. + Your first option is to call <literal>sessionFactory.getStatistics()</literal> and + read or display the <literal>Statistics</literal> yourself. + </para> + + <para> + Hibernate can also use JMX to publish metrics if you enable the + <literal>StatisticsService</literal> MBean. You may enable a single MBean for all your + <literal>SessionFactory</literal> or one per factory. See the following code for + minimalistic configuration examples: + </para> + + <programlisting><![CDATA[// MBean service registration for a specific SessionFactory +Hashtable tb = new Hashtable(); +tb.put("type", "statistics"); +tb.put("sessionFactory", "myFinancialApp"); +ObjectName on = new ObjectName("hibernate", tb); // MBean object name + +StatisticsService stats = new StatisticsService(); // MBean implementation +stats.setSessionFactory(sessionFactory); // Bind the stats to a SessionFactory +server.registerMBean(stats, on); // Register the Mbean on the server]]></programlisting> + + +<programlisting><![CDATA[// MBean service registration for all SessionFactory's +Hashtable tb = new Hashtable(); +tb.put("type", "statistics"); +tb.put("sessionFactory", "all"); +ObjectName on = new ObjectName("hibernate", tb); // MBean object name + +StatisticsService stats = new StatisticsService(); // MBean implementation +server.registerMBean(stats, on); // Register the MBean on the server]]></programlisting> + + <para> + TODO: This doesn't make sense: In the first case, we retrieve and use the MBean directly. In the second one, we must give + the JNDI name in which the session factory is held before using it. Use + <literal>hibernateStatsBean.setSessionFactoryJNDIName("my/JNDI/Name")</literal> + </para> + <para> + You can (de)activate the monitoring for a <literal>SessionFactory</literal> + </para> + <itemizedlist> + <listitem> + <para> + at configuration time, set <literal>hibernate.generate_statistics</literal> to <literal>false</literal> + </para> + </listitem> + </itemizedlist> + <itemizedlist> + <listitem> + <para> + at runtime: <literal>sf.getStatistics().setStatisticsEnabled(true)</literal> + or <literal>hibernateStatsBean.setStatisticsEnabled(true)</literal> + </para> + </listitem> + </itemizedlist> + + <para> + Statistics can be reset programatically using the <literal>clear()</literal> method. + A summary can be sent to a logger (info level) using the <literal>logSummary()</literal> + method. + </para> + + </sect2> + + <sect2 id="performance-monitoring-metrics" revision="1"> + <title>Metrics</title> + + <para> + Hibernate provides a number of metrics, from very basic to the specialized information + only relevant in certain scenarios. All available counters are described in the + <literal>Statistics</literal> interface API, in three categories: + </para> + <itemizedlist> + <listitem> + <para> + Metrics related to the general <literal>Session</literal> usage, such as + number of open sessions, retrieved JDBC connections, etc. + </para> + </listitem> + <listitem> + <para> + Metrics related to he entities, collections, queries, and caches as a + whole (aka global metrics), + </para> + </listitem> + <listitem> + <para> + Detailed metrics related to a particular entity, collection, query or + cache region. + </para> + </listitem> + </itemizedlist> + + <para> + For exampl,e you can check the cache hit, miss, and put ratio of entities, collections + and queries, and the average time a query needs. Beware that the number of milliseconds + is subject to approximation in Java. Hibernate is tied to the JVM precision, on some + platforms this might even only be accurate to 10 seconds. + </para> + + <para> + Simple getters are used to access the global metrics (i.e. not tied to a particular entity, + collection, cache region, etc.). You can access the metrics of a particular entity, collection + or cache region through its name, and through its HQL or SQL representation for queries. Please + refer to the <literal>Statistics</literal>, <literal>EntityStatistics</literal>, + <literal>CollectionStatistics</literal>, <literal>SecondLevelCacheStatistics</literal>, + and <literal>QueryStatistics</literal> API Javadoc for more information. The following + code shows a simple example: + </para> + + <programlisting><![CDATA[Statistics stats = HibernateUtil.sessionFactory.getStatistics(); + +double queryCacheHitCount = stats.getQueryCacheHitCount(); +double queryCacheMissCount = stats.getQueryCacheMissCount(); +double queryCacheHitRatio = + queryCacheHitCount / (queryCacheHitCount + queryCacheMissCount); + +log.info("Query Hit ratio:" + queryCacheHitRatio); + +EntityStatistics entityStats = + stats.getEntityStatistics( Cat.class.getName() ); +long changes = + entityStats.getInsertCount() + + entityStats.getUpdateCount() + + entityStats.getDeleteCount(); +log.info(Cat.class.getName() + " changed " + changes + "times" );]]></programlisting> + + <para> + To work on all entities, collections, queries and region caches, you can retrieve + the list of names of entities, collections, queries and region caches with the + following methods: <literal>getQueries()</literal>, <literal>getEntityNames()</literal>, + <literal>getCollectionRoleNames()</literal>, and + <literal>getSecondLevelCacheRegionNames()</literal>. + </para> + + </sect2> + + </sect1> + +</chapter> \ No newline at end of file Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/persistent_classes.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/persistent_classes.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/persistent_classes.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/persistent_classes.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,531 @@ +<chapter id="persistent-classes" revision="2"> + <title>Persistent Classes</title> + + <para> + Persistent classes are classes in an application that implement the entities + of the business problem (e.g. Customer and Order in an E-commerce application). + Not all instances of a persistent class are considered to be in the persistent + state - an instance may instead be transient or detached. + </para> + + <para> + Hibernate works best if these classes follow some simple rules, also known + as the Plain Old Java Object (POJO) programming model. However, none of these + rules are hard requirements. Indeed, Hibernate3 assumes very little about + the nature of your persistent objects. You may express a domain model in other + ways: using trees of <literal>Map</literal> instances, for example. + </para> + + <sect1 id="persistent-classes-pojo"> + <title>A simple POJO example</title> + + <para> + Most Java applications require a persistent class representing felines. + </para> + + <programlisting><![CDATA[package eg; +import java.util.Set; +import java.util.Date; + +public class Cat { + private Long id; // identifier + + private Date birthdate; + private Color color; + private char sex; + private float weight; + private int litterId; + + private Cat mother; + private Set kittens = new HashSet(); + + private void setId(Long id) { + this.id=id; + } + public Long getId() { + return id; + } + + void setBirthdate(Date date) { + birthdate = date; + } + public Date getBirthdate() { + return birthdate; + } + + void setWeight(float weight) { + this.weight = weight; + } + public float getWeight() { + return weight; + } + + public Color getColor() { + return color; + } + void setColor(Color color) { + this.color = color; + } + + void setSex(char sex) { + this.sex=sex; + } + public char getSex() { + return sex; + } + + void setLitterId(int id) { + this.litterId = id; + } + public int getLitterId() { + return litterId; + } + + void setMother(Cat mother) { + this.mother = mother; + } + public Cat getMother() { + return mother; + } + void setKittens(Set kittens) { + this.kittens = kittens; + } + public Set getKittens() { + return kittens; + } + + // addKitten not needed by Hibernate + public void addKitten(Cat kitten) { + kitten.setMother(this); + kitten.setLitterId( kittens.size() ); + kittens.add(kitten); + } +}]]></programlisting> + + <para> + There are four main rules to follow here: + </para> + + + <sect2 id="persistent-classes-pojo-constructor" revision="1"> + <title>Implement a no-argument constructor</title> + + <para> + <literal>Cat</literal> has a no-argument constructor. All persistent classes must + have a default constructor (which may be non-public) so that Hibernate can instantiate + them using <literal>Constructor.newInstance()</literal>. We strongly recommend having a + default constructor with at least <emphasis>package</emphasis> visibility for runtime proxy + generation in Hibernate. + </para> + </sect2> + + <sect2 id="persistent-classes-pojo-identifier" revision="2"> + <title>Provide an identifier property (optional)</title> + + <para> + <literal>Cat</literal> has a property called <literal>id</literal>. This property + maps to the primary key column of a database table. The property might have been called + anything, and its type might have been any primitive type, any primitive "wrapper" + type, <literal>java.lang.String</literal> or <literal>java.util.Date</literal>. (If + your legacy database table has composite keys, you can even use a user-defined class + with properties of these types - see the section on composite identifiers later.) + </para> + + <para> + The identifier property is strictly optional. You can leave them off and let Hibernate + keep track of object identifiers internally. We do not recommend this, however. + </para> + + <para> + In fact, some functionality is available only to classes which declare an + identifier property: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + Transitive reattachment for detached objects (cascade update or cascade + merge) - see <xref linkend="objectstate-transitive"/> + </para> + </listitem> + <listitem> + <para> + <literal>Session.saveOrUpdate()</literal> + </para> + </listitem> + <listitem> + <para> + <literal>Session.merge()</literal> + </para> + </listitem> + </itemizedlist> + + <para> + We recommend you declare consistently-named identifier properties on persistent + classes. We further recommend that you use a nullable (ie. non-primitive) type. + </para> + </sect2> + + <sect2 id="persistent-classes-pojo-final"> + <title>Prefer non-final classes (optional)</title> + <para> + A central feature of Hibernate, <emphasis>proxies</emphasis>, depends upon the + persistent class being either non-final, or the implementation of an interface + that declares all public methods. + </para> + <para> + You can persist <literal>final</literal> classes that do not implement an interface + with Hibernate, but you won't be able to use proxies for lazy association fetching - + which will limit your options for performance tuning. + </para> + <para> + You should also avoid declaring <literal>public final</literal> methods on the + non-final classes. If you want to use a class with a <literal>public final</literal> + method, you must explicitly disable proying by setting <literal>lazy="false"</literal>. + </para> + </sect2> + + <sect2 id="persistent-classes-pojo-accessors" revision="2"> + <title>Declare accessors and mutators for persistent fields (optional)</title> + + <para> + <literal>Cat</literal> declares accessor methods for all its persistent fields. + Many other ORM tools directly persist instance variables. We believe it is + better to provide an indirection between the relational schema and internal + data structures of the class. By default, Hibernate persists JavaBeans style + properties, and recognizes method names of the form <literal>getFoo</literal>, + <literal>isFoo</literal> and <literal>setFoo</literal>. You may switch to direct + field access for particular properties, if needed. + </para> + + <para> + Properties need <emphasis>not</emphasis> be declared public - Hibernate can + persist a property with a default, <literal>protected</literal> or + <literal>private</literal> get / set pair. + </para> + + </sect2> + + </sect1> + + <sect1 id="persistent-classes-inheritance"> + <title>Implementing inheritance</title> + + <para> + A subclass must also observe the first and second rules. It inherits its + identifier property from the superclass, <literal>Cat</literal>. + </para> + + <programlisting><![CDATA[package eg; + +public class DomesticCat extends Cat { + private String name; + + public String getName() { + return name; + } + protected void setName(String name) { + this.name=name; + } +}]]></programlisting> + </sect1> + + <sect1 id="persistent-classes-equalshashcode" revision="1"> + <title>Implementing <literal>equals()</literal> and <literal>hashCode()</literal></title> + + <para> + You have to override the <literal>equals()</literal> and <literal>hashCode()</literal> + methods if you + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + intend to put instances of persistent classes in a <literal>Set</literal> + (the recommended way to represent many-valued associations) + <emphasis>and</emphasis> + </para> + </listitem> + <listitem> + <para> + intend to use reattachment of detached instances + </para> + </listitem> + </itemizedlist> + + <para> + Hibernate guarantees equivalence of persistent identity (database row) and Java identity + only inside a particular session scope. So as soon as we mix instances retrieved in + different sessions, we must implement <literal>equals()</literal> and + <literal>hashCode()</literal> if we wish to have meaningful semantics for + <literal>Set</literal>s. + </para> + + <para> + The most obvious way is to implement <literal>equals()</literal>/<literal>hashCode()</literal> + by comparing the identifier value of both objects. If the value is the same, both must + be the same database row, they are therefore equal (if both are added to a <literal>Set</literal>, + we will only have one element in the <literal>Set</literal>). Unfortunately, we can't use that + approach with generated identifiers! Hibernate will only assign identifier values to objects + that are persistent, a newly created instance will not have any identifier value! Furthermore, + if an instance is unsaved and currently in a <literal>Set</literal>, saving it will assign + an identifier value to the object. If <literal>equals()</literal> and <literal>hashCode()</literal> + are based on the identifier value, the hash code would change, breaking the contract of the + <literal>Set</literal>. See the Hibernate website for a full discussion of this problem. Note + that this is not a Hibernate issue, but normal Java semantics of object identity and equality. + </para> + + <para> + We recommend implementing <literal>equals()</literal> and <literal>hashCode()</literal> + using <emphasis>Business key equality</emphasis>. Business key equality means that the + <literal>equals()</literal> method compares only the properties that form the business + key, a key that would identify our instance in the real world (a + <emphasis>natural</emphasis> candidate key): + </para> + + <programlisting><![CDATA[public class Cat { + + ... + public boolean equals(Object other) { + if (this == other) return true; + if ( !(other instanceof Cat) ) return false; + + final Cat cat = (Cat) other; + + if ( !cat.getLitterId().equals( getLitterId() ) ) return false; + if ( !cat.getMother().equals( getMother() ) ) return false; + + return true; + } + + public int hashCode() { + int result; + result = getMother().hashCode(); + result = 29 * result + getLitterId(); + return result; + } + +}]]></programlisting> + + <para> + Note that a business key does not have to be as solid as a database + primary key candidate (see <xref linkend="transactions-basics-identity"/>). + Immutable or unique properties are usually good + candidates for a business key. + </para> + + </sect1> + + <sect1 id="persistent-classes-dynamicmodels"> + <title>Dynamic models</title> + + <para> + <emphasis>Note that the following features are currently considered + experimental and may change in the near future.</emphasis> + </para> + + <para> + Persistent entities don't necessarily have to be represented as POJO classes + or as JavaBean objects at runtime. Hibernate also supports dynamic models + (using <literal>Map</literal>s of <literal>Map</literal>s at runtime) and the + representation of entities as DOM4J trees. With this approach, you don't + write persistent classes, only mapping files. + </para> + + <para> + By default, Hibernate works in normal POJO mode. You may set a default entity + representation mode for a particular <literal>SessionFactory</literal> using the + <literal>default_entity_mode</literal> configuration option (see + <xref linkend="configuration-optional-properties"/>. + </para> + + <para> + The following examples demonstrates the representation using <literal>Map</literal>s. + First, in the mapping file, an <literal>entity-name</literal> has to be declared + instead of (or in addition to) a class name: + </para> + + <programlisting><![CDATA[<hibernate-mapping> + + <class entity-name="Customer"> + + <id name="id" + type="long" + column="ID"> + <generator class="sequence"/> + </id> + + <property name="name" + column="NAME" + type="string"/> + + <property name="address" + column="ADDRESS" + type="string"/> + + <many-to-one name="organization" + column="ORGANIZATION_ID" + class="Organization"/> + + <bag name="orders" + inverse="true" + lazy="false" + cascade="all"> + <key column="CUSTOMER_ID"/> + <one-to-many class="Order"/> + </bag> + + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + + Note that even though associations are declared using target class names, + the target type of an associations may also be a dynamic entity instead + of a POJO. + </para> + + <para> + After setting the default entity mode to <literal>dynamic-map</literal> + for the <literal>SessionFactory</literal>, we can at runtime work with + <literal>Map</literal>s of <literal>Map</literal>s: + </para> + + <programlisting><![CDATA[Session s = openSession(); +Transaction tx = s.beginTransaction(); +Session s = openSession(); + +// Create a customer +Map david = new HashMap(); +david.put("name", "David"); + +// Create an organization +Map foobar = new HashMap(); +foobar.put("name", "Foobar Inc."); + +// Link both +david.put("organization", foobar); + +// Save both +s.save("Customer", david); +s.save("Organization", foobar); + +tx.commit(); +s.close();]]></programlisting> + + <para> + The advantages of a dynamic mapping are quick turnaround time for prototyping + without the need for entity class implementation. However, you lose compile-time + type checking and will very likely deal with many exceptions at runtime. Thanks + to the Hibernate mapping, the database schema can easily be normalized and sound, + allowing to add a proper domain model implementation on top later on. + </para> + + <para> + Entity representation modes can also be set on a per <literal>Session</literal> + basis: + </para> + + <programlisting><![CDATA[Session dynamicSession = pojoSession.getSession(EntityMode.MAP); + +// Create a customer +Map david = new HashMap(); +david.put("name", "David"); +dynamicSession.save("Customer", david); +... +dynamicSession.flush(); +dynamicSession.close() +... +// Continue on pojoSession +]]></programlisting> + + + <para> + Please note that the call to <literal>getSession()</literal> using an + <literal>EntityMode</literal> is on the <literal>Session</literal> API, not the + <literal>SessionFactory</literal>. That way, the new <literal>Session</literal> + shares the underlying JDBC connection, transaction, and other context + information. This means you don't have tocall <literal>flush()</literal> + and <literal>close()</literal> on the secondary <literal>Session</literal>, and + also leave the transaction and connection handling to the primary unit of work. + </para> + + <para> + More information about the XML representation capabilities can be found + in <xref linkend="xml"/>. + </para> + + </sect1> + + <sect1 id="persistent-classes-tuplizers" revision="0"> + <title>Tuplizers</title> + + <para> + <literal>org.hibernate.tuple.Tuplizer</literal>, and its sub-interfaces, are responsible + for managing a particular representation of a piece of data, given that representation's + <literal>org.hibernate.EntityMode</literal>. If a given piece of data is thought of as + a data structure, then a tuplizer is the thing which knows how to create such a data structure + and how to extract values from and inject values into such a data structure. For example, + for the POJO entity mode, the correpsonding tuplizer knows how create the POJO through its + constructor and how to access the POJO properties using the defined property accessors. + There are two high-level types of Tuplizers, represented by the + <literal>org.hibernate.tuple.EntityTuplizer</literal> and <literal>org.hibernate.tuple.ComponentTuplizer</literal> + interfaces. <literal>EntityTuplizer</literal>s are responsible for managing the above mentioned + contracts in regards to entities, while <literal>ComponentTuplizer</literal>s do the same for + components. + </para> + + <para> + Users may also plug in their own tuplizers. Perhaps you require that a <literal>java.util.Map</literal> + implementation other than <literal>java.util.HashMap</literal> be used while in the + dynamic-map entity-mode; or perhaps you need to define a different proxy generation strategy + than the one used by default. Both would be achieved by defining a custom tuplizer + implementation. Tuplizers definitions are attached to the entity or component mapping they + are meant to manage. Going back to the example of our customer entity: + </para> + + <programlisting><![CDATA[<hibernate-mapping> + <class entity-name="Customer"> + <!-- + Override the dynamic-map entity-mode + tuplizer for the customer entity + --> + <tuplizer entity-mode="dynamic-map" + class="CustomMapTuplizerImpl"/> + + <id name="id" type="long" column="ID"> + <generator class="sequence"/> + </id> + + <!-- other properties --> + ... + </class> +</hibernate-mapping> + + +public class CustomMapTuplizerImpl + extends org.hibernate.tuple.DynamicMapEntityTuplizer { + // override the buildInstantiator() method to plug in our custom map... + protected final Instantiator buildInstantiator( + org.hibernate.mapping.PersistentClass mappingInfo) { + return new CustomMapInstantiator( mappingInfo ); + } + + private static final class CustomMapInstantiator + extends org.hibernate.tuple.DynamicMapInstantitor { + // override the generateMap() method to return our custom map... + protected final Map generateMap() { + return new CustomMap(); + } + } +}]]></programlisting> + + + </sect1> + + <para> + TODO: Document user-extension framework in the property and proxy packages + </para> + +</chapter> + Added: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/preface.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/preface.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/preface.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,120 @@ +<?xml version='1.0' encoding="iso-8859-1"?> +<!-- + ~ Copyright (c) 2007, Red Hat Middleware, LLC. All rights reserved. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, v. 2.1. This program is distributed in the + ~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied + ~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + ~ Lesser General Public License for more details. You should have received a + ~ copy of the GNU Lesser General Public License, v.2.1 along with this + ~ distribution; if not, write to the Free Software Foundation, Inc., + ~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + ~ + ~ Red Hat Author(s): Steve Ebersole + --> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<preface id="preface" revision="2"> + <title>Pref�cio</title> + + <para> + Trabalhando com software orientado a objetos e banco de dados relacional, podemos + ter alguns inc�modos hoje em dia em ambientes empresariais. Hibernate � uma ferramenta + que mapeia o objeto/relacional para o ambiente Java. O termo de mapeamento de + objeto/relacional (ou ORM � Object/Relational Mapping) se refere a t�cnica de mapear + uma representa��o de dados de um modelo de objeto para dados de modelo + relacional com o esquema baseado em SQL + </para> + + <para> + O Hibernate n�o somente cuida do mapeamento de classes em Java + para tabelas de banco de dados (e de tipos de dados em Java para tipos de dados em SQL), como tamb�m + fornece facilidade de consultas e recupera��o de dados, podendo tamb�m reduzir significantemente o + tempo de desenvolvimento gasto com a manipula��o manual de dados no SQL e JDBC. + </para> + + <para> + O objetivo do Hibernate � de aliviar o desenvolvedor de 95 por cento das tarefas de programa��o + relacionadas aos dados comuns de persist�ncia. O Hibernate talvez n�o seja a melhor solu��o para + aplica��es de dados-data-centric que somente usa stored-procedures para implementar a l�gica + de neg�cio no banco de dados, isto � muito utilizado com o dom�nio de modelos orientado a objetos e + l�gicas de neg�cio em camadas do meio (middle-tier) baseadas em Java. Por�m, o Hibernate + poder� certamente ajuda-lo a remover ou encapsular o c�digo SQL de um vendedor espec�fico, + ajudando tamb�m com a tarefa comum da tradu��o do resultado ajustado de uma representa��o + para um gr�fico de objetos. + </para> + + <para> + Se voc� for novo no Hibernate e no mapeamento Objeto/Relacional, ou at� mesmo em Java, + por favor, siga os seguintes passos. + </para> + + <orderedlist> + <listitem> + <para> + Leia <xref linkend="tutorial"/> para um tutorial com instru��es passo-a-passo. + O c�digo fonte para do tutorial est� inclu�do na distribui��o no diret�rio + <literal>doc/reference/tutorial/</literal>. + </para> + </listitem> + <listitem> + <para> + Leia o <xref linkend="architecture"/> para entender o ambiente onde o Hibernate pode ser utilizado. + </para> + </listitem> + <listitem> + <para> + D� uma olhada no diret�rio de exemplo <literal>eg/</literal> da distribui��o + do Hibernate, ele cont�m uma simples aplica��o standalone. + Copie seu driver JDBC para o diret�rio <literal>lib/</literal> e edite o arquivo + <literal>etc/hibernate.properties</literal>, especificando corretamente os valores + para seu banco de dados. Usando o prompt de commando no diretorio de distribuicao, + digite <literal>ant eg</literal> (usando Ant), ou no Windows, digite + <literal>build eg</literal>. + </para> + </listitem> + <listitem> + <para> + Use esta documenta��o de referencia como sua fonte primaria de informa��o. + Considere ler tamb�m o livro <emphasis>Java Persistence with Hibernate</emphasis> + (http://www.manning.com/bauer2) caso voc� precise de mais ajuda com o + desenvolvimento de aplica��es ou caso prefira um tutorial passo-a-passo. + Tamb�m visite o site http://caveatemptor.hibernate.org e fa�a o download + da aplica��o de exemplo do Java Persistence with Hibernate. + </para> + </listitem> + <listitem> + <para> + FAQs (perguntas feitas com mais freq��ncia) est�o respondidas no site do Hibernate + </para> + </listitem> + <listitem> + <para> + Demonstra��es, exemplos e tutorials est�o dispon�veis no site do Hibernate. + </para> + </listitem> + <listitem> + <para> + A �rea da comunidade no site do Hibernate � uma boa fonte de recursos + para padr�es de projeto e v�rias solu��es de integra��o (Tomcat, JBoss AS, Struts, EJB, etc.). + </para> + </listitem> + </orderedlist> + + <para> + Caso voc� tenha d�vidas, use o f�rum dos usu�rios encontrado no site do Hibernate. + N�s tamb�m fornecemos um sistema para controle de bug�s (JIRA) para relat�rios de erros + e requisi��es de features. Se voc� est� interessado no desenvolvimento do Hibernate, + junte-se a lista de e-mail dos desenvolvedores. + </para> + + <para> + Suporte comercial de desenvolvimento, suporte de produ��o e treinamento para o Hibernate + est� dispon�vel atrav�s do JBoss Inc. (veja http://www.hibernate.org/SupportTraining). + O Hibernate � um Projeto Profissional de C�digo Aberto e um componente cr�tico da su�te + de produtos JBoss Enterprise Middleware System (JEMS). + </para> + +</preface> Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_criteria.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/query_criteria.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_criteria.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_criteria.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,436 @@ +<chapter id="querycriteria"> + <title>Consultas por critérios</title> + + <para> + O Hibernate provê uma intuitiva e extensível API de critério de query. + </para> + + <sect1 id="querycriteria-creating"> + <title>Criando uma instancia <literal>Criteria</literal></title> + + <para> + A interface <literal>org.hibernate.Criteria</literal> representa a query + ao invés de uma classe persistente particular. A sessão é uma fábrica para + intancias de <literal>Criteria</literal> . + </para> + + <programlisting><![CDATA[Criteria crit = sess.createCriteria(Cat.class); +crit.setMaxResults(50); +List cats = crit.list();]]></programlisting> + + </sect1> + + <sect1 id="querycriteria-narrowing"> + <title>Limitando o result set</title> + + <para> + Um critério individual de query é uma instancia da interface + <literal>org.hibernate.criterion.Criterion</literal>. A classe + <literal>org.hibernate.criterion.Restrictions</literal> define + os métodos da fábrica para obter certos tipos pré fabricados + de <literal>Criterion</literal>. + </para> + + <programlisting><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Restrictions.like("name", "Fritz%") ) + .add( Restrictions.between("weight", minWeight, maxWeight) ) + .list();]]></programlisting> + + <para> + Restrições podem ser logicamente agrupadas. + </para> + + <programlisting><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Restrictions.like("name", "Fritz%") ) + .add( Restrictions.or( + Restrictions.eq( "age", new Integer(0) ), + Restrictions.isNull("age") + ) ) + .list();]]></programlisting> + + <programlisting><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Restrictions.in( "name", new String[] { "Fritz", "Izi", "Pk" } ) ) + .add( Restrictions.disjunction() + .add( Restrictions.isNull("age") ) + .add( Restrictions.eq("age", new Integer(0) ) ) + .add( Restrictions.eq("age", new Integer(1) ) ) + .add( Restrictions.eq("age", new Integer(2) ) ) + ) ) + .list();]]></programlisting> + + <para> + Existe um grande número de critérios pré fabricados (subclasses de + <literal>Restrictions</literal>), mas um é especialmente útil pois + permite especificar o SQL diretamente. + </para> + + <programlisting><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Restrictions.sqlRestriction("lower({alias}.name) like lower(?)", "Fritz%", Hibernate.STRING) ) + .list();]]></programlisting> + + <para> + O parametro <literal>{alias}</literal> será substituido pelo alias da entidade procurada. + </para> + + <para> + Uma maneira alternativa de obter um critério é pegá-lo de uma instancia de + <literal>Property</literal>. Você pode criar uma <literal>Property</literal> + chamando <literal>Property.forName()</literal>. + </para> + + <programlisting><![CDATA[ +Property age = Property.forName("age"); +List cats = sess.createCriteria(Cat.class) + .add( Restrictions.disjunction() + .add( age.isNull() ) + .add( age.eq( new Integer(0) ) ) + .add( age.eq( new Integer(1) ) ) + .add( age.eq( new Integer(2) ) ) + ) ) + .add( Property.forName("name").in( new String[] { "Fritz", "Izi", "Pk" } ) ) + .list();]]></programlisting> + + </sect1> + + <sect1 id="querycriteria-ordering"> + <title>Ordering the results</title> + + <para> + You may order the results using <literal>org.hibernate.criterion.Order</literal>. + </para> + + <programlisting><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Restrictions.like("name", "F%") + .addOrder( Order.asc("name") ) + .addOrder( Order.desc("age") ) + .setMaxResults(50) + .list();]]></programlisting> + + <programlisting><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Property.forName("name").like("F%") ) + .addOrder( Property.forName("name").asc() ) + .addOrder( Property.forName("age").desc() ) + .setMaxResults(50) + .list();]]></programlisting> + + </sect1> + + <sect1 id="querycriteria-associations" revision="2"> + <title>Associations</title> + + <para> + You may easily specify constraints upon related entities by navigating + associations using <literal>createCriteria()</literal>. + </para> + + <programlisting><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Restrictions.like("name", "F%") ) + .createCriteria("kittens") + .add( Restrictions.like("name", "F%") ) + .list();]]></programlisting> + + <para> + note that the second <literal>createCriteria()</literal> returns a new + instance of <literal>Criteria</literal>, which refers to the elements of + the <literal>kittens</literal> collection. + </para> + + <para> + The following, alternate form is useful in certain circumstances. + </para> + + <programlisting><![CDATA[List cats = sess.createCriteria(Cat.class) + .createAlias("kittens", "kt") + .createAlias("mate", "mt") + .add( Restrictions.eqProperty("kt.name", "mt.name") ) + .list();]]></programlisting> + + <para> + (<literal>createAlias()</literal> does not create a new instance of + <literal>Criteria</literal>.) + </para> + + <para> + Note that the kittens collections held by the <literal>Cat</literal> instances + returned by the previous two queries are <emphasis>not</emphasis> pre-filtered + by the criteria! If you wish to retrieve just the kittens that match the + criteria, you must use a <literal>ResultTransformer</literal>. + </para> + + <programlisting><![CDATA[List cats = sess.createCriteria(Cat.class) + .createCriteria("kittens", "kt") + .add( Restrictions.eq("name", "F%") ) + .setResultTransformer(Criteria.ALIAS_TO_ENTITY_MAP) + .list(); +Iterator iter = cats.iterator(); +while ( iter.hasNext() ) { + Map map = (Map) iter.next(); + Cat cat = (Cat) map.get(Criteria.ROOT_ALIAS); + Cat kitten = (Cat) map.get("kt"); +}]]></programlisting> + + </sect1> + + <sect1 id="querycriteria-dynamicfetching" revision="1"> + <title>Dynamic association fetching</title> + + <para> + You may specify association fetching semantics at runtime using + <literal>setFetchMode()</literal>. + </para> + + <programlisting><![CDATA[List cats = sess.createCriteria(Cat.class) + .add( Restrictions.like("name", "Fritz%") ) + .setFetchMode("mate", FetchMode.EAGER) + .setFetchMode("kittens", FetchMode.EAGER) + .list();]]></programlisting> + + <para> + This query will fetch both <literal>mate</literal> and <literal>kittens</literal> + by outer join. See <xref linkend="performance-fetching"/> for more information. + </para> + + </sect1> + + <sect1 id="querycriteria-examples"> + <title>Example queries</title> + + <para> + The class <literal>org.hibernate.criterion.Example</literal> allows + you to construct a query criterion from a given instance. + </para> + + <programlisting><![CDATA[Cat cat = new Cat(); +cat.setSex('F'); +cat.setColor(Color.BLACK); +List results = session.createCriteria(Cat.class) + .add( Example.create(cat) ) + .list();]]></programlisting> + + <para> + Version properties, identifiers and associations are ignored. By default, + null valued properties are excluded. + </para> + + <para> + You can adjust how the <literal>Example</literal> is applied. + </para> + + <programlisting><![CDATA[Example example = Example.create(cat) + .excludeZeroes() //exclude zero valued properties + .excludeProperty("color") //exclude the property named "color" + .ignoreCase() //perform case insensitive string comparisons + .enableLike(); //use like for string comparisons +List results = session.createCriteria(Cat.class) + .add(example) + .list();]]></programlisting> + + <para> + You can even use examples to place criteria upon associated objects. + </para> + + <programlisting><![CDATA[List results = session.createCriteria(Cat.class) + .add( Example.create(cat) ) + .createCriteria("mate") + .add( Example.create( cat.getMate() ) ) + .list();]]></programlisting> + + </sect1> + + <sect1 id="querycriteria-projection"> + <title>Projections, aggregation and grouping</title> + <para> + The class <literal>org.hibernate.criterion.Projections</literal> is a + factory for <literal>Projection</literal> instances. We apply a + projection to a query by calling <literal>setProjection()</literal>. + </para> + + <programlisting><![CDATA[List results = session.createCriteria(Cat.class) + .setProjection( Projections.rowCount() ) + .add( Restrictions.eq("color", Color.BLACK) ) + .list();]]></programlisting> + + <programlisting><![CDATA[List results = session.createCriteria(Cat.class) + .setProjection( Projections.projectionList() + .add( Projections.rowCount() ) + .add( Projections.avg("weight") ) + .add( Projections.max("weight") ) + .add( Projections.groupProperty("color") ) + ) + .list();]]></programlisting> + + <para> + There is no explicit "group by" necessary in a criteria query. Certain + projection types are defined to be <emphasis>grouping projections</emphasis>, + which also appear in the SQL <literal>group by</literal> clause. + </para> + + <para> + An alias may optionally be assigned to a projection, so that the projected value + may be referred to in restrictions or orderings. Here are two different ways to + do this: + </para> + + <programlisting><![CDATA[List results = session.createCriteria(Cat.class) + .setProjection( Projections.alias( Projections.groupProperty("color"), "colr" ) ) + .addOrder( Order.asc("colr") ) + .list();]]></programlisting> + + <programlisting><![CDATA[List results = session.createCriteria(Cat.class) + .setProjection( Projections.groupProperty("color").as("colr") ) + .addOrder( Order.asc("colr") ) + .list();]]></programlisting> + + <para> + The <literal>alias()</literal> and <literal>as()</literal> methods simply wrap a + projection instance in another, aliased, instance of <literal>Projection</literal>. + As a shortcut, you can assign an alias when you add the projection to a + projection list: + </para> + + <programlisting><![CDATA[List results = session.createCriteria(Cat.class) + .setProjection( Projections.projectionList() + .add( Projections.rowCount(), "catCountByColor" ) + .add( Projections.avg("weight"), "avgWeight" ) + .add( Projections.max("weight"), "maxWeight" ) + .add( Projections.groupProperty("color"), "color" ) + ) + .addOrder( Order.desc("catCountByColor") ) + .addOrder( Order.desc("avgWeight") ) + .list();]]></programlisting> + + <programlisting><![CDATA[List results = session.createCriteria(Domestic.class, "cat") + .createAlias("kittens", "kit") + .setProjection( Projections.projectionList() + .add( Projections.property("cat.name"), "catName" ) + .add( Projections.property("kit.name"), "kitName" ) + ) + .addOrder( Order.asc("catName") ) + .addOrder( Order.asc("kitName") ) + .list();]]></programlisting> + + <para> + You can also use <literal>Property.forName()</literal> to express projections: + </para> + + <programlisting><![CDATA[List results = session.createCriteria(Cat.class) + .setProjection( Property.forName("name") ) + .add( Property.forName("color").eq(Color.BLACK) ) + .list();]]></programlisting> + + <programlisting><![CDATA[List results = session.createCriteria(Cat.class) + .setProjection( Projections.projectionList() + .add( Projections.rowCount().as("catCountByColor") ) + .add( Property.forName("weight").avg().as("avgWeight") ) + .add( Property.forName("weight").max().as("maxWeight") ) + .add( Property.forName("color").group().as("color" ) + ) + .addOrder( Order.desc("catCountByColor") ) + .addOrder( Order.desc("avgWeight") ) + .list();]]></programlisting> + + </sect1> + + <sect1 id="querycriteria-detachedqueries"> + <title>Detached queries and subqueries</title> + <para> + The <literal>DetachedCriteria</literal> class lets you create a query outside the scope + of a session, and then later execute it using some arbitrary <literal>Session</literal>. + </para> + + <programlisting><![CDATA[DetachedCriteria query = DetachedCriteria.forClass(Cat.class) + .add( Property.forName("sex").eq('F') ); + +Session session = ....; +Transaction txn = session.beginTransaction(); +List results = query.getExecutableCriteria(session).setMaxResults(100).list(); +txn.commit(); +session.close();]]></programlisting> + + <para> + A <literal>DetachedCriteria</literal> may also be used to express a subquery. Criterion + instances involving subqueries may be obtained via <literal>Subqueries</literal> or + <literal>Property</literal>. + </para> + + <programlisting><![CDATA[DetachedCriteria avgWeight = DetachedCriteria.forClass(Cat.class) + .setProjection( Property.forName("weight").avg() ); +session.createCriteria(Cat.class) + .add( Property.forName("weight").gt(avgWeight) ) + .list();]]></programlisting> + + <programlisting><![CDATA[DetachedCriteria weights = DetachedCriteria.forClass(Cat.class) + .setProjection( Property.forName("weight") ); +session.createCriteria(Cat.class) + .add( Subqueries.geAll("weight", weights) ) + .list();]]></programlisting> + + <para> + Even correlated subqueries are possible: + </para> + + <programlisting><![CDATA[DetachedCriteria avgWeightForSex = DetachedCriteria.forClass(Cat.class, "cat2") + .setProjection( Property.forName("weight").avg() ) + .add( Property.forName("cat2.sex").eqProperty("cat.sex") ); +session.createCriteria(Cat.class, "cat") + .add( Property.forName("weight").gt(avgWeightForSex) ) + .list();]]></programlisting> + + </sect1> + + <!--TODO: ResultSetTransformer + aliasing. AliasToBeanTransformer allow returning arbitrary + user objects - similar to setResultClass in JDO2. General use of ResultTransformer + could also be explained. --> + + <sect1 id="query-criteria-naturalid"> + <title>Queries by natural identifier</title> + + <para> + For most queries, including criteria queries, the query cache is not very efficient, + because query cache invalidation occurs too frequently. However, there is one special + kind of query where we can optimize the cache invalidation algorithm: lookups by a + constant natural key. In some applications, this kind of query occurs frequently. + The criteria API provides special provision for this use case. + </para> + + <para> + First, you should map the natural key of your entity using + <literal>&lt;natural-id&gt;</literal>, and enable use of the second-level cache. + </para> + + <programlisting><![CDATA[<class name="User"> + <cache usage="read-write"/> + <id name="id"> + <generator class="increment"/> + </id> + <natural-id> + <property name="name"/> + <property name="org"/> + </natural-id> + <property name="password"/> +</class>]]></programlisting> + + <para> + Note that this functionality is not intended for use with entities with + <emphasis>mutable</emphasis> natural keys. + </para> + + <para> + Next, enable the Hibernate query cache. + </para> + + <para> + Now, <literal>Restrictions.naturalId()</literal> allows us to make use of + the more efficient cache algorithm. + </para> + + <programlisting><![CDATA[session.createCriteria(User.class) + .add( Restrictions.naturalId() + .set("name", "gavin") + .set("org", "hb") + ).setCacheable(true) + .uniqueResult();]]></programlisting> + + </sect1> + +</chapter> Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_hql.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/query_hql.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_hql.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_hql.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,1162 @@ +858 + +<chapter id="queryhql"> + <title>HQL: A linguagem de Queries do Hibernate</title> + + <para> + O Hibernate vem com uma poderosa linguagem que é (intencionalmente) muito parecida + com o SQL. Mas não seja enganado pela sintaxe; a HQL é totalmente orientada à objetos, + requer conhecimentos de herança, polimorfismo e associações. + </para> + + <sect1 id="queryhql-casesensitivity"> + <title>Case Sensitíve</title> + + <para> + As Queries não são case-sensitive, exceto pelo nomes das classes e propriedades Java. + <literal>sELEct</literal> e o mesmo que + <literal>SELECT</literal> mas + <literal>org.hibernate.eg.FOO</literal> não é + <literal>org.hibernate.eg.Foo</literal> e + <literal>foo.barSet</literal> não é + <literal>foo.BARSET</literal>. + + </para> + + <para> + Esse manual usa as palavras chave HQL em letras minúsculas. Alguns usuários acham que + com letras maiúsculas as queries ficam mais legíveis, mas nós achamos essa convenção feia + dentro do código Java. + </para> + + </sect1> + + <sect1 id="queryhql-from"> + <title>A clausula from</title> + + <para> + A mais simples query possível do Hibernate é a assim: + </para> + + <programlisting><![CDATA[from eg.Cat]]></programlisting> + + <para> + Ela irá retornar todas as instancias da classe <literal>eg.Cat</literal>. + Necessariamente não precisamos qualificar o nome da classe, pois é realizado + <literal>auto-import</literal> por padrão. Por isso na maior parte do tempos + nós simplesmente escrevemos: + </para> + + <programlisting><![CDATA[from Cat]]></programlisting> + + <para> + Na maior parte do tempo, você precisará atribuir um <emphasis>alias</emphasis>, + desde que você queira se referia ao <literal>Cat</literal> em outras partes da + query. + </para> + + <programlisting><![CDATA[from Cat as cat]]></programlisting> + + <para> + Essa query atribui um alias a <literal>cat</literal> para as instancias de + <literal>Cat</literal>, então nós podemos usar esse alias depois na query. + A palavra chave as é opcional; poderíamos escrever assim: + </para> + + <programlisting><![CDATA[from Cat cat]]></programlisting> + + <para> + Múltiplas classes pode ser envolvidas, resultando em um produto cartesiano ou "cross" join. + </para> + + <programlisting><![CDATA[from Formula, Parameter]]></programlisting> + <programlisting><![CDATA[from Formula as form, Parameter as param]]></programlisting> + + <para> + É considerada uma boa prática os nomes dos aliases começarem com letra minúscula, + aderente com os padrões Java para variáveis locais (ex: <literal>domesticCat</literal>). + </para> + + </sect1> + + <sect1 id="queryhql-joins" revision="2"> + <title>Associações e joins</title> + + <para> + Nós também podemos querer atribuir aliases em uma entidade associada, ou mesmo + em elementos de uma coleção de valores, usando um <literal>join</literal>. + </para> + + <programlisting><![CDATA[from Cat as cat + inner join cat.mate as mate + left outer join cat.kittens as kitten]]></programlisting> + + <programlisting><![CDATA[from Cat as cat left join cat.mate.kittens as kittens]]></programlisting> + + <programlisting><![CDATA[from Formula form full join form.parameter param]]></programlisting> + + <para> + Os tipos de joins suportados foram inspirados no SQL ANSI: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>inner join</literal> + </para> + </listitem> + <listitem> + <para> + <literal>left outer join</literal> + </para> + </listitem> + <listitem> + <para> + <literal>right outer join</literal> + </para> + </listitem> + <listitem> + <para> + <literal>full join</literal> (geralmente não é útil) + </para> + </listitem> + </itemizedlist> + + <para> + The <literal>inner join</literal>, <literal>left outer join</literal> and + <literal>right outer join</literal> constructs may be abbreviated. + As construções <literal>inner join</literal>, <literal>left outer join</literal> e + <literal>right outer join</literal> podem ser abreviadas. + </para> + + <programlisting><![CDATA[from Cat as cat + join cat.mate as mate + left join cat.kittens as kitten]]></programlisting> + + <para> + Você pode fornecer condições extras de join usando a palavra + chave do HQL <literal>with</literal>. + </para> + + <programlisting><![CDATA[from Cat as cat + left join cat.kittens as kitten + <literal>with</literal> kitten.bodyWeight > 10.0]]></programlisting> + + <para> + Adicionalmente, um "fetch" join permite que associações ou coleções de valores + sejam inicializadas junto com o objeto pai, usando apenas um select. Isso é + muito útil no caso das coleções. Isso efetivamente sobre escreve as declarações + outer join e lazy do arquivo mapeamento para associações e coleções. + Veja a seção <xref linkend="performance-fetching"/> para mais informações. + </para> + + <programlisting><![CDATA[from Cat as cat + inner join <literal>fetch</literal>cat.mate + left join <literal>fetch</literal>cat.kittens]]></programlisting> + + <para> + Usualmente, um <literal>fetch</literal>join não precisa atribuir um alias, pois o objeto associado não + deve ser usado na clausula <literal>where</literal> (ou em qualquer outra clausula). + Também, os objetos associados não são retornados diretamente nos resultados da query. + Ao invés disso, eles devem ser acessados usando o objeto pai. A única razão que nós + podemos necessitar de um alias é quando fazemos um fech join recursivamente em uma + coleção adicional: + </para> + + <programlisting><![CDATA[from Cat as cat + inner join <literal>fetch</literal>cat.mate + left join <literal>fetch</literal>cat.kittens child + left join <literal>fetch</literal>child.kittens]]></programlisting> + + <para> + Observe que a construção <literal>fetch</literal> não deve ser usada em queries invocadas usando + <literal>iterate()</literal> (embora possa ser usado com <literal>scroll()</literal>). O + <literal>fetch</literal> também não deve ser usado junto com o <literal>setMaxResults()</literal> ou + <literal>setFirstResult()</literal> pois essas operações são baseadas nas linhas retornadas, que + normalmente contem duplicidade devido ao fetching das coleções, então o número de linhas pode não + ser o que você espera. + + O <literal>fetch</literal> não deve ser usado junto com uma condição <literal>with</literal> em + uma condição <literal>with</literal> ad hoc. É possível que seja criado um produto cartesiano pelo + join fetching em mais do que uma coleção em uma query, então tome cuidado nesses casos. Um join + fetching em varias coleções pode trazer resultados inesperados para mapeamentos do tipo bag, tome + cuidado na hora de formular queries como essas. Finalmente, observe o seguinte, o + <literal>full join fetch</literal> e <literal>right join fetch</literal> não são significativos. + </para> + + <para> + + Se está usando o nível de propriedade lazy (<literal>com</literal> instrumentação de bytecode), é possível + forçar o Hibernate a <literal>buscar</literal> as propriedades lazy imediatamente (na primeira query), + usando <literal>fetch all properties </literal>. + </para> + + <programlisting><![CDATA[from Document <literal>fetch</literal>all properties order by name]]></programlisting> + <programlisting><![CDATA[from Document doc <literal>fetch</literal>all properties where lower(doc.name) like '%cats%']]></programlisting> + + </sect1> + + <sect1 id="queryhql-joins-forms"> + <title>Formas e sintaxe de joins</title> + + <para> + O HQL suporta duas formas de associação para união: <literal>implícita</literal> e <literal>explicita</literal>. + </para> + + <para> + As queries apresentadas na seção anterior usam a forma <literal>explicita</literal>, onde a + palavra chave "join" é explicitamente usada na clausula "from". Essa é a forma recomendada. + </para> + + <para> + A forma <literal>implícita</literal> não usa a palavra chave "join". Entretanto, as associações + são diferenciadas usando pontuação ("." - dotnation). Uniões implícitas podem aparecer em + qualquer das clausulas HQL. A união <literal>implícita</literal> resulta em declarações + SQL que contem inner joins. + </para> + + <programlisting><![CDATA[from Cat as cat where cat.mate.name like '%s%']]></programlisting> + </sect1> + + <sect1 id="queryhql-select"> + <title>Clausula select</title> + + <para> + A clausula <literal>select</literal> seleciona quais obetos e propriedades retornam + no resultado da query. Considere: + </para> + + <programlisting><![CDATA[select mate +from Cat as cat + inner join cat.mate as mate]]></programlisting> + + <para> + A query selecionará <literal>mate</literal>s (companheiros), de outros <literal>Cat</literal>s. + Atualmente, podemos expressar a query de forma mais compacta como: + </para> + + <programlisting><![CDATA[select cat.mate from Cat cat]]></programlisting> + + <para> + Queries podem retornar propriedades de qualquer tipo de valor, incluindo propriedades de tipo de componente: + + </para> + + <programlisting><![CDATA[select cat.name from DomesticCat cat +where cat.name like 'fri%']]></programlisting> + + <programlisting><![CDATA[select cust.name.firstName from Customer as cust]]></programlisting> + + <para> + Queries podem retornar múltiplos objetos e/ou propriedades como um array do + tipo Object[], + </para> + + <programlisting><![CDATA[select mother, offspr, mate.name +from DomesticCat as mother + inner join mother.mate as mate + left outer join mother.kittens as offspr]]></programlisting> + + <para> + ou como um <literal>List</literal>, + </para> + + <programlisting><![CDATA[select new list(mother, offspr, mate.name) +from DomesticCat as mother + inner join mother.mate as mate + left outer join mother.kittens as offspr]]></programlisting> + + <para> + ou como um objeto Java typesafe, + </para> + + <programlisting><![CDATA[select new Family(mother, mate, offspr) +from DomesticCat as mother + join mother.mate as mate + left join mother.kittens as offspr]]></programlisting> + + <para> + assumindo que a classe <literal>Family</literal> tenha um construtor apropriado. + </para> + + <para> + Pode-se designar referencias a expressões selecionadas, <literal>as</literal>: + </para> + + <programlisting><![CDATA[select max(bodyWeight) as max, min(bodyWeight) as min, count(*) as n +from Cat cat]]></programlisting> + + <para> + Isto é bem mais útil quando usado junto <literal>com</literal> <literal>select new map</literal>: + </para> + + <programlisting><![CDATA[select new map( max(bodyWeight) as max, min(bodyWeight) as min, count(*) as n ) +from Cat cat]]></programlisting> + + <para> + Esta query retorna um <literal>Map</literal> de referencias para valores selecionados. + </para> + + </sect1> + + <sect1 id="queryhql-aggregation"> + <title>Funções de agregação</title> + + <para> + As queries HQL podem retornar o resultado de funções agregadas nas propriedades. + </para> + + <programlisting><![CDATA[select avg(cat.weight), sum(cat.weight), max(cat.weight), count(cat) +from Cat cat]]></programlisting> + +<!-- NO LONGER SUPPORTED + <para> + Collections may also appear inside aggregate functions in the <literal>select</literal> + clause. + </para> + + <programlisting><![CDATA[select cat, count( elements(cat.kittens) ) +from Cat cat group by cat]]></programlisting> +--> + + <para> + As funções agregadas suportadas são: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>avg(...), sum(...), min(...), max(...)</literal> + </para> + </listitem> + <listitem> + <para> + <literal>count(*)</literal> + </para> + </listitem> + <listitem> + <para> + <literal>count(...), count(distinct ...), count(all...)</literal> + </para> + </listitem> + </itemizedlist> + + <para> + Pode-se usar operadores aritiméticos, concatenação e funções SQL + reconhecidas na clausula select: + </para> + + <programlisting><![CDATA[select cat.weight + sum(kitten.weight) +from Cat cat + join cat.kittens kitten +group by cat.id, cat.weight]]></programlisting> + + <programlisting><![CDATA[select firstName||' '||initial||' '||upper(lastName) from Person]]></programlisting> + + <para> + As palavras <literal>distinct</literal> e <literal>all</literal> podem ser usadas e têm + a mesma semântica como no SQL. + </para> + + <programlisting><![CDATA[select distinct cat.name from Cat cat + +select count(distinct cat.name), count(cat) from Cat cat]]></programlisting> + + </sect1> + + <sect1 id="queryhql-polymorphism"> + <title>Queries polimórficas</title> + + <para> + A query: + </para> + + <programlisting><![CDATA[from Cat as cat]]></programlisting> + + <para> + retorna instancias não só de <literal>Cat</literal>, mas também de subclasses como + <literal>DomesticCat</literal>. As queries do Hibernate podem nomear qualquer classe Java + ou interface na clausula <literal>from</literal>. A query retornará instancias de toda classe + persistente que extenda a determinada classe ou implemente a determinada interface. A query + , a seguir, pode retornar todo objeto persistente: + </para> + + <programlisting><![CDATA[from java.lang.Object o]]></programlisting> + + <para> + A interface <literal>Named</literal> pode ser implementada por várias classes persistentes: + </para> + + <programlisting><![CDATA[from Named n, Named m where n.name = m.name]]></programlisting> + + <para> + Note que as duas últimas queries requerem mais de um SQL SELECT . Isto significa que a clausula + <literal>order by</literal> não ordena corretamente todo o resultado. (Isso também significa que + você não pode chamar essas queries usando <literal>Query.scroll()</literal>.) + </para> + + </sect1> + + <sect1 id="queryhql-where"> + <title>A clausula where</title> + + <para> + A clausula <literal>where</literal> permite estreitar a lista de instancias retornada. + Se não houver referencia alguma, pode-se referir a propriedades pelo nome: + </para> + + <programlisting><![CDATA[from Cat where name='Fritz']]></programlisting> + + <para> + Se houver uma referência, use o nome da propriedade qualificada: + </para> + + <programlisting><![CDATA[from Cat as cat where cat.name='Fritz']]></programlisting> + + <para> + retorna instancias de <literal>Cat</literal> com nome ‘Fritz’. + </para> + + <programlisting><![CDATA[select foo +from Foo foo, Bar bar +where foo.startDate = bar.date]]></programlisting> + + <para> + retornará todas as instancias de <literal>Foo</literal>, para cada + um que tiver uma instancia de <literal>bar</literal> com a propriedade + <literal>date</literal> igual a propriedade + <literal>startDate</literal> de + <literal>Foo</literal>. Expressões de filtro compostas fazem da + clausula <literal>where</literal>, extremamente poderosa. Consideremos: + </para> + + <programlisting><![CDATA[from Cat cat where cat.mate.name is not null]]></programlisting> + + <para> + Esta query traduzida para uma query SQL <literal>com</literal> uma tabela (inner) join. Se fosse + escrever algo como: + </para> + + <programlisting><![CDATA[from Foo foo +where foo.bar.baz.customer.address.city is not null]]></programlisting> + + <para> + Poderia-se terminar <literal>com</literal> uma query que necessitasse de join de quatro tabelas, + no SQL. + </para> + + <para> + O operador <literal>=</literal> pode ser uasdo para comparar não apenas propriedades, + mas também instancias: + </para> + + <programlisting><![CDATA[from Cat cat, Cat rival where cat.mate = rival.mate]]></programlisting> + + <programlisting><![CDATA[select cat, mate +from Cat cat, Cat mate +where cat.mate = mate]]></programlisting> + + <para> + A propriedade especial (lowercase) <literal>id</literal> pode ser usada para referenciar + o identificador único de um objeto. (Pode-se usar também o nome de sua propriedade) + </para> + + <programlisting><![CDATA[from Cat as cat where cat.id = 123 + +from Cat as cat where cat.mate.id = 69]]></programlisting> + + <para> + A Segunda query é eficiente. Nenhuma união de tabelas é necessária! + </para> + + <para> + As propriedades de identificadores compostas também podem ser usadas. Suponha que + <literal>Person</literal> tenha um identificador composto que consiste de + <literal>country</literal> e <literal>medicareNumber</literal>. + </para> + + <programlisting><![CDATA[from bank.Person person +where person.id.country = 'AU' + and person.id.medicareNumber = 123456]]></programlisting> + + <programlisting><![CDATA[from bank.Account account +where account.owner.id.country = 'AU' + and account.owner.id.medicareNumber = 123456]]></programlisting> + + <para> + Mais uma vez, a Segunda query não precisa de nenhum join de tabela. + </para> + + <para> + Assim mesmo, a propriedade especial <literal>class</literal> acessa o valor discriminador da + instancia, no caso de persistência polimórfica. O nome de uma classe Java inclusa em uma + clausula "where", será traduzida para seu valor descriminante. + </para> + + <programlisting><![CDATA[from Cat cat where cat.class = DomesticCat]]></programlisting> + + <para> + Pode-se também especificar as propriedades dos components ou tipos de usuário composto + (e de componentes de componentes). Nunca tente usar uma expressão de filtro que termine na propriedade + de um tipo de componente (ao contrário de uma propriedade de um componente). Por exemplo, + se store.owner é uma entidade <literal>com</literal> um componente <literal>address</literal>. + </para> + + <programlisting><![CDATA[store.owner.address.city // okay +store.owner.address // error!]]></programlisting> + + <para> + Um tipo "any" tem as propriedades <literal>id</literal> e <literal>class</literal> especiais, + nôs permitindo expressar um join da seguinte forma (onde <literal>AuditLog.item</literal> é + uma propriedade mapeada <literal>com</literal> <literal>&lt;any&gt;</literal>) + </para> + + <programlisting><![CDATA[from AuditLog log, Payment payment +where log.item.class = 'Payment' and log.item.id = payment.id]]></programlisting> + + <para> + Veja que <literal>log.item.class</literal> e <literal>payment.class</literal> podem + referir-se a valores de colunas de banco de dados completamente diferentes, na query acima. + </para> + + </sect1> + + <sect1 id="queryhql-expressions"> + <title>Expressões</title> + + <para> + As expressões permitidas na cláusula <literal>where</literal> inclui a maioria + das coisas que você poderia escrever no SQL: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + operadores matemáticos <literal>+, -, *, /</literal> + </para> + </listitem> + <listitem> + <para> + operadores de comparação binários <literal>=, &gt;=, &lt;=, &lt;&gt;, !=, like</literal> + </para> + </listitem> + <listitem> + <para> + operadores lógicos <literal>and, or, not</literal> + </para> + </listitem> + <listitem> + <para> + parenteses <literal>( )</literal>, indicating grouping + </para> + </listitem> + <listitem> + <para> + <literal>in</literal>, + <literal>not in</literal>, + <literal>between</literal>, + <literal>is null</literal>, + <literal>is not null</literal>, + <literal>is empty</literal>, + <literal>is not empty</literal>, + <literal>member of</literal> and + <literal>not member of</literal> + </para> + </listitem> + <listitem> + <para> + case "simples" , <literal>case ... when ... then ... else ... end</literal>, and + "searched" case, <literal>case when ... then ... else ... end</literal> + </para> + </listitem> + <listitem> + <para> + concatenação de string <literal>...||...</literal> ou <literal>concat(...,...)</literal> + </para> + </listitem> + <listitem> + <para> + <literal>current_date()</literal>, <literal>current_time()</literal>, + <literal>current_timestamp()</literal> + </para> + </listitem> + <listitem> + <para> + <literal>second(...)</literal>, <literal>minute(...)</literal>, + <literal>hour(...)</literal>, <literal>day(...)</literal>, + <literal>month(...)</literal>, <literal>year(...)</literal>, + </para> + </listitem> + <listitem> + <para> + qualquer funcao ou operador definida pela EJB-QL 3.0: <literal>substring(), trim(), + lower(), upper(), length(), locate(), abs(), sqrt(), bit_length(), mod()</literal> + </para> + </listitem> + <listitem> + <para> + <literal>coalesce()</literal> and <literal>nullif()</literal> + </para> + </listitem> + <listitem> + <para> + <literal>str()</literal> para converter valores numericos ou temporais para string + </para> + </listitem> + <listitem> + <para> + <literal>cast(... as ...)</literal>, onde o segundo argumento é o nome do tipo + hibernate, e<literal>extract(... from ...)</literal> se ANSI + <literal>cast()</literal> e <literal>extract()</literal> é suportado pele + banco de dados usado + </para> + </listitem> + <listitem> + <para> + A função HQL <literal>index()</literal> , que se aplicam a referencias de + coleçôes associadas e indexadas + </para> + </listitem> + <listitem> + <para> + As funções hql que retornam expressões de coleções de valores: + <literal>size(), minelement(), maxelement(), minindex(), maxindex()</literal>, + <literal>junto</literal> com o elemento especial, <literal>elements()</literal>, + e funções de <literal>índice</literal> que podem ser quantificadas usando + <literal>some, all, exists, any, in</literal>. + </para> + </listitem> + <listitem> + <para> + Qualquer funçâo escalar pelo bando de dados como <literal>sign()</literal>, + <literal>trunc()</literal>, <literal>rtrim()</literal>, <literal>sin()</literal> + </para> + </listitem> + <listitem> + <para> + Parametros posicionais ao estilo JDBC <literal>?</literal> + </para> + </listitem> + <listitem> + <para> + Parametros nomeados <literal>:name</literal>, <literal>:start_date</literal>, <literal>:x1</literal> + </para> + </listitem> + <listitem> + <para> + Literais SQL <literal>'foo'</literal>, <literal>69</literal>, <literal>6.66E+2</literal>, + <literal>'1970-01-01 10:00:01.0'</literal> + </para> + </listitem> + <listitem> + <para> + Constantes Java <literal>public static final</literal> <literal>ex: Color.TABBY</literal> + </para> + </listitem> + </itemizedlist> + + <para> + <literal>in</literal> e <literal>between</literal> podem ser usadas da seguinte maneira: + </para> + + <programlisting><![CDATA[from DomesticCat cat where cat.name between 'A' and 'B']]></programlisting> + + <programlisting><![CDATA[from DomesticCat cat where cat.name in ( 'Foo', 'Bar', 'Baz' )]]></programlisting> + + <para> + e as formas negativas podem ser escritas + </para> + + <programlisting><![CDATA[from DomesticCat cat where cat.name not between 'A' and 'B']]></programlisting> + + <programlisting><![CDATA[from DomesticCat cat where cat.name not in ( 'Foo', 'Bar', 'Baz' )]]></programlisting> + + <para> + Likewise, <literal>is null</literal> and <literal>is not null</literal> may be used to test + for null values. + Assim mesmo, , <literal>is null</literal> e <literal>is not null</literal> podem ser usados + para testar valores nulos. + </para> + + <para> + Booleanos podem ser facilmente usados em expressões, declarando as substituições da HQL query, + na configuração do Hibernate + </para> + + <programlisting><![CDATA[<property name="hibernate.query.substitutions">true 1, false 0</property>]]></programlisting> + + <para> + Isso irá substituir as palavras chave <literal>true</literal> e <literal>false</literal> + <literal>pelos</literal> literais <literal>1</literal> e <literal>0</literal> na tradução do HQL para SQL. + </para> + + <programlisting><![CDATA[from Cat cat where cat.alive = true]]></programlisting> + + <para> + Pode-se testar o tamanho de uma coleção <literal>com</literal> a propriedade especial <literal>size</literal>, + ou a função especial <literal>size()</literal>. + </para> + + <programlisting><![CDATA[from Cat cat where cat.kittens.size > 0]]></programlisting> + + <programlisting><![CDATA[from Cat cat where size(cat.kittens) > 0]]></programlisting> + + <para> + Para coleções indexadas, você pode se referir aos índices máximo e mínimo, usando + as funções <literal>minindex</literal> e <literal>maxindex</literal>. Similarmente, + pode-se referir aos elementos máximo e mínimo de uma coleção de tipos básicos usando + as funções <literal>minelement</literal> e <literal>maxelement</literal>. + </para> + + <programlisting><![CDATA[from Calendar cal where maxelement(cal.holidays) > current_date]]></programlisting> + + <programlisting><![CDATA[from Order order where maxindex(order.items) > 100]]></programlisting> + + <programlisting><![CDATA[from Order order where minelement(order.items) > 10000]]></programlisting> + + <para> + As funções SQL <literal>any, some, all, exists, in</literal> são suportadas quando passado o + elemento ou o conjunto de índices de uma coleção (<literal>elements</literal> e + <literal>indices</literal> de funções), ou o resultado de uma subquery (veja abaixo). + </para> + + <programlisting><![CDATA[select mother from Cat as mother, Cat as kit +where kit in elements(foo.kittens)]]></programlisting> + + <programlisting><![CDATA[select p from NameList list, Person p +where p.name = some elements(list.names)]]></programlisting> + + <programlisting><![CDATA[from Cat cat where exists elements(cat.kittens)]]></programlisting> + + <programlisting><![CDATA[from Player p where 3 > all elements(p.scores)]]></programlisting> + + <programlisting><![CDATA[from Show show where 'fizard' in indices(show.acts)]]></programlisting> + + <para> + Note que essas construções - <literal>size</literal>, <literal>elements</literal>, + <literal>indices</literal>, <literal>minindex</literal>, <literal>maxindex</literal>, + <literal>minelement</literal>, <literal>maxelement</literal>– + só podem ser usados na clausula where do Hibernate3. + </para> + + <para> + Elementos de coleções com índice (arrays, lists, maps), podem ser referenciadas + pelo índice (apenas na clausula where): + </para> + + <programlisting><![CDATA[from Order order where order.items[0].id = 1234]]></programlisting> + + <programlisting><![CDATA[select person from Person person, Calendar calendar +where calendar.holidays['national day'] = person.birthDay + and person.nationality.calendar = calendar]]></programlisting> + + <programlisting><![CDATA[select item from Item item, Order order +where order.items[ order.deliveredItemIndices[0] ] = item and order.id = 11]]></programlisting> + + <programlisting><![CDATA[select item from Item item, Order order +where order.items[ maxindex(order.items) ] = item and order.id = 11]]></programlisting> + + <para> + A expressão entre colchetes <literal>[]</literal>, pode ser até uma expressão aritimética. + </para> + + <programlisting><![CDATA[select item from Item item, Order order +where order.items[ size(order.items) - 1 ] = item]]></programlisting> + + <para> + O HQL também provê a função interna <literal>index()</literal>, para elementos de + associação um-pra-muitos ou coleção de valores. + </para> + + <programlisting><![CDATA[select item, index(item) from Order order + join order.items item +where index(item) < 5]]></programlisting> + + <para> + Funções escalares SQL, suportadas pelo banco de dados subjacente. + </para> + + <programlisting><![CDATA[from DomesticCat cat where upper(cat.name) like 'FRI%']]></programlisting> + + <para> + Se ainda ainda não está totalmente convencido, pense o quão maior e menos legível poderia + ser a query a seguir, em SQL: + </para> + + <programlisting><![CDATA[select cust +from Product prod, + Store store + inner join store.customers cust +where prod.name = 'widget' + and store.location.name in ( 'Melbourne', 'Sydney' ) + and prod = all elements(cust.currentOrder.lineItems)]]></programlisting> + + <para> + <emphasis>Hint:</emphasis> something like + </para> + + <programlisting><![CDATA[SELECT cust.name, cust.address, cust.phone, cust.id, cust.current_order +FROM customers cust, + stores store, + locations loc, + store_customers sc, + product prod +WHERE prod.name = 'widget' + AND store.loc_id = loc.id + AND loc.name IN ( 'Melbourne', 'Sydney' ) + AND sc.store_id = store.id + AND sc.cust_id = cust.id + AND prod.id = ALL( + SELECT item.prod_id + FROM line_items item, orders o + WHERE item.order_id = o.id + AND cust.current_order = o.id + )]]></programlisting> + + </sect1> + + <sect1 id="queryhql-ordering"> + <title>A clausula order by</title> + + <para> + A lista retornada pela query pode ser ordenada por qualquer propriedade da classe ou componente retornado: + </para> + + <programlisting><![CDATA[from DomesticCat cat +order by cat.name asc, cat.weight desc, cat.birthdate]]></programlisting> + + <para> + As opções <literal>asc</literal> ou <literal>desc</literal> indicam ordem crescente ou decrescente, + respectivamente. + </para> + </sect1> + + <sect1 id="queryhql-grouping"> + <title>A clausula group by</title> + + <para> + Uma query que retorne valores agregados, podem ser agrupados por qualquer propriedade de uma classe + ou componente retornado: + </para> + + <programlisting><![CDATA[select cat.color, sum(cat.weight), count(cat) +from Cat cat +group by cat.color]]></programlisting> + + <programlisting><![CDATA[select foo.id, avg(name), max(name) +from Foo foo join foo.names name +group by foo.id]]></programlisting> + + <para> + Uma clausula <literal>having</literal> também é permitida. + </para> + + <programlisting><![CDATA[select cat.color, sum(cat.weight), count(cat) +from Cat cat +group by cat.color +having cat.color in (eg.Color.TABBY, eg.Color.BLACK)]]></programlisting> + + <para> + Funções SQL e funções agregadas são permitidas nas clausulas + <literal>having</literal> e <literal>order by</literal>, se suportadas pelo banco + de dados subjacente (ex: não no MySQL). + </para> + + <programlisting><![CDATA[select cat +from Cat cat + join cat.kittens kitten +group by cat +having avg(kitten.weight) > 100 +order by count(kitten) asc, sum(kitten.weight) desc]]></programlisting> + + <para> + Note que, nem a clausula <literal>group by</literal> ou + <literal>order by</literal>, podem conter expressões aritiméticas. + </para> + + </sect1> + + <sect1 id="queryhql-subqueries" revision="2"> + <title>Subqueries</title> + + <para> + Para bancos de dados que suportem subselects, o Hibernate suporta subqueries dentro de queries. + Uma subquery precisa estar entre parênteses (normalmente uma chamada de função agregada SQL). + Mesmo subqueries co-relacionadas (subqueries que fazem referência à alias de outras queries), + são aceitas. + </para> + + <programlisting><![CDATA[from Cat as fatcat +where fatcat.weight > ( + select avg(cat.weight) from DomesticCat cat +)]]></programlisting> + + <programlisting><![CDATA[from DomesticCat as cat +where cat.name = some ( + select name.nickName from Name as name +)]]></programlisting> + + <programlisting><![CDATA[from Cat as cat +where not exists ( + from Cat as mate where mate.mate = cat +)]]></programlisting> + + <programlisting><![CDATA[from DomesticCat as cat +where cat.name not in ( + select name.nickName from Name as name +)]]></programlisting> + + <programlisting><![CDATA[select cat.id, (select max(kit.weight) from cat.kitten kit) +from Cat as cat]]></programlisting> + + <para> + Note que HQL subqueries podem aparecer apenas dentro de clausulas select ou where. + </para> + + <para> + Para subqueries <literal>com</literal> mais de uma expressão na lista do select, pode-se usar um construtor + de tuplas: + </para> + + <programlisting><![CDATA[from Cat as cat +where not ( cat.name, cat.color ) in ( + select cat.name, cat.color from DomesticCat cat +)]]></programlisting> + + <para> + Veja que em alguns bancos de dados (mas não o Oracle ou HSQL), pode-se usar construtores + de tuplas em outros contextos. Por exemplo quando buscando componentes ou tipos de usuário composto. + </para> + + <programlisting><![CDATA[from Person where name = ('Gavin', 'A', 'King')]]></programlisting> + + <para> + Qual é equivalente ao mais verbalizado: + </para> + + <programlisting><![CDATA[from Person where name.first = 'Gavin' and name.initial = 'A' and name.last = 'King')]]></programlisting> + + <para> + Há duas razões boas que você pode não querer fazer este tipo de coisa: primeira, não + é completamente portável entre plataformas de banco de dados; segunda, a query agora é + dependente da ordem de propriedades no documento de mapeamento. + </para> + + </sect1> + + <sect1 id="queryhql-examples"> + <title>Exemplos de HQL</title> + + <para> + As queries do Hibernate, podem ser muito poderosas e complexas. De fato, o poder da linguagem de + querie é um dos pontos principais na distribuição do Hibernate. Aqui temos algumas queries de exemplo, + muito similares a queries que usei em um projeto recente. Note que a maioria das queries que você + irá escrever, são mais simples que estas. + </para> + + <para> + A query a seguir retorna o id de order, numero de itens e o valor total do order para todos os + orders não pagos para um freguês particular e valor total mínimo dado, ordenando os resultados por + valor total. Ao determinar os preços, é usado o catalogo corrente. A query SQL resultante, + usando tabelas <literal>ORDER</literal>, <literal>ORDER_LINE</literal>, <literal>PRODUCT</literal>, + <literal>CATALOG</literal> e <literal>PRICE</literal>, tem quatro inner joins e um + (não correlacionado) subselect. + </para> + + <programlisting><![CDATA[select order.id, sum(price.amount), count(item) +from Order as order + join order.lineItems as item + join item.product as product, + Catalog as catalog + join catalog.prices as price +where order.paid = false + and order.customer = :customer + and price.product = product + and catalog.effectiveDate < sysdate + and catalog.effectiveDate >= all ( + select cat.effectiveDate + from Catalog as cat + where cat.effectiveDate < sysdate + ) +group by order +having sum(price.amount) > :minAmount +order by sum(price.amount) desc]]></programlisting> + + <para> + Que monstro! Atualmente, na vida real, eu não sou muito afeiçoado a subqueries, então + minha query seria mais parecida com isto: + </para> + + <programlisting><![CDATA[select order.id, sum(price.amount), count(item) +from Order as order + join order.lineItems as item + join item.product as product, + Catalog as catalog + join catalog.prices as price +where order.paid = false + and order.customer = :customer + and price.product = product + and catalog = :currentCatalog +group by order +having sum(price.amount) > :minAmount +order by sum(price.amount) desc]]></programlisting> + + <para> + A próxima query conta o número de pagamentos em cada status, tirando todos os pagamentos com + status <literal>AWAITING_APPROVAL</literal>, onde a mais recente mudança de status foi feita + pelo usuário corrente. Traduz-se para uma query SQL <literal>com</literal> dois inner joins e + um subselect correlacionado, nas tabelas <literal>PAYMENT</literal>, + <literal>PAYMENT_STATUS</literal> e <literal>PAYMENT_STATUS_CHANGE</literal> . + </para> + + <programlisting><![CDATA[select count(payment), status.name +from Payment as payment + join payment.currentStatus as status + join payment.statusChanges as statusChange +where payment.status.name <> PaymentStatus.AWAITING_APPROVAL + or ( + statusChange.timeStamp = ( + select max(change.timeStamp) + from PaymentStatusChange change + where change.payment = payment + ) + and statusChange.user <> :currentUser + ) +group by status.name, status.sortOrder +order by status.sortOrder]]></programlisting> + + <para> + Se eu tivesse mapeado a Collection <literal>statusChanges</literal> como um List, ao invés de um + Set, a query teria sido muito mais simples de escrever. + </para> + + <programlisting><![CDATA[select count(payment), status.name +from Payment as payment + join payment.currentStatus as status +where payment.status.name <> PaymentStatus.AWAITING_APPROVAL + or payment.statusChanges[ maxIndex(payment.statusChanges) ].user <> :currentUser +group by status.name, status.sortOrder +order by status.sortOrder]]></programlisting> + + <para> + A próxima query usa a função <literal>isNull()</literal> do MS SQL Server, para retornar + todas as contas e pagamentos não pagos para a organização, para cada usuário corrente + pertencente. Traduz-se para uma query SQL <literal>com</literal> três inner joins, + um outer join e um subselect nas tabelas <literal>ACCOUNT</literal>, <literal>PAYMENT</literal>, + <literal>PAYMENT_STATUS</literal>,<literal>ACCOUNT_TYPE</literal>, + <literal>ORGANIZATION</literal> e <literal>ORG_USER</literal> . + </para> + + <programlisting><![CDATA[select account, payment +from Account as account + left outer join account.payments as payment +where :currentUser in elements(account.holder.users) + and PaymentStatus.UNPAID = isNull(payment.currentStatus.name, PaymentStatus.UNPAID) +order by account.type.sortOrder, account.accountNumber, payment.dueDate]]></programlisting> + + <para> + Para alguns bancos de dados, precisaremos eleminar o subselect (correlacionado). + </para> + + <programlisting><![CDATA[select account, payment +from Account as account + join account.holder.users as user + left outer join account.payments as payment +where :currentUser = user + and PaymentStatus.UNPAID = isNull(payment.currentStatus.name, PaymentStatus.UNPAID) +order by account.type.sortOrder, account.accountNumber, payment.dueDate]]></programlisting> + + </sect1> + + <sect1 id="queryhql-bulk" revision="2"> + <title>update e delete em lote</title> + + <para> + Agora o HQL suporta declarações, <literal>update</literal>, + <literal>delete</literal> e <literal>insert ... select ...</literal> + Veja <xref linkend="batch-direct"/>, para mais detalhes. + </para> + </sect1> + + <sect1 id="queryhql-tipstricks"> + <title>Dicas e Truques</title> + + <para> + Pode-se contar o número de resultados da query, sem realmente retorna-los. + </para> + + <programlisting><![CDATA[( (Integer) session.createQuery("select count(*) from ....").iterate().next() ).intValue()]]></programlisting> + + <para> + Para ordenar um resultado pelo tamanho de uma Collection, use a query a seguir. + </para> + + <programlisting><![CDATA[select usr.id, usr.name +from User as usr + left join usr.messages as msg +group by usr.id, usr.name +order by count(msg)]]></programlisting> + + <para> + Se seu banco de dados suporta subselects, pode-se colocar uma condição sobre + tamanho de seleção na cláusula where da sua query: + </para> + + <programlisting><![CDATA[from User usr where size(usr.messages) >= 1]]></programlisting> + + <para> + Se seu banco de dados não suporta subselects, use a query a seguir: + </para> + + <programlisting><![CDATA[select usr.id, usr.name +from User usr.name + join usr.messages msg +group by usr.id, usr.name +having count(msg) >= 1]]></programlisting> + + <para> + Com essa solução não se pode retornar um <literal>User</literal> <literal>com</literal> sem + nenhuma menssagem, por causa do "inner join", a forma a seguir também é útil. + </para> + + <programlisting><![CDATA[select usr.id, usr.name +from User as usr + left join usr.messages as msg +group by usr.id, usr.name +having count(msg) = 0]]></programlisting> + + <para> + As propriedades de um JavaBean podem ser limitadas à parâmetros nomeados da query: + </para> + + <programlisting><![CDATA[Query q = s.createQuery("from foo Foo as foo where foo.name=:name and foo.size=:size"); +q.setProperties(fooBean); // fooBean has getName() and getSize() +List foos = q.list();]]></programlisting> + + <para> + As Collections são paginaveis, usando a interface <literal>Query</literal> <literal>com</literal> um filtro: + </para> + + <programlisting><![CDATA[Query q = s.createFilter( collection, "" ); // the trivial filter +q.setMaxResults(PAGE_SIZE); +q.setFirstResult(PAGE_SIZE * pageNumber); +List page = q.list();]]></programlisting> + + <para> + Os elementos da Collection podem ser ordenados ou agrupados + usando um filtro de query: + </para> + + <programlisting><![CDATA[Collection orderedCollection = s.filter( collection, "order by this.amount" ); +Collection counts = s.filter( collection, "select this.type, count(this) group by this.type" );]]></programlisting> + + <para> + Pode-se achar o tamanho de uma Collection sem inicializa-la: + </para> + + <programlisting><![CDATA[( (Integer) session.createQuery("select count(*) from ....").iterate().next() ).intValue();]]></programlisting> + + </sect1> + +</chapter> + Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_sql.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/query_sql.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_sql.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_sql.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,783 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<chapter id="querysql" revision="2"> + <title>Native SQL</title> + + <para>You may also express queries in the native SQL dialect of your + database. This is useful if you want to utilize database specific features + such as query hints or the <literal>CONNECT</literal> keyword in Oracle. It + also provides a clean migration path from a direct SQL/JDBC based + application to Hibernate.</para> + + <para>Hibernate3 allows you to specify handwritten SQL (including stored + procedures) for all create, update, delete, and load operations.</para> + + <sect1 id="querysql-creating" revision="4"> + <title>Using a <literal>SQLQuery</literal></title> + + <para>Execution of native SQL queries is controlled via the + <literal>SQLQuery</literal> interface, which is obtained by calling + <literal>Session.createSQLQuery()</literal>. The following describes how + to use this API for querying.</para> + + <sect2> + <title>Scalar queries</title> + + <para>The most basic SQL query is to get a list of scalars + (values).</para> + + <programlisting><![CDATA[sess.createSQLQuery("SELECT * FROM CATS").list(); +sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE FROM CATS").list(); +]]></programlisting> + + <para>These will both return a List of Object arrays (Object[]) with + scalar values for each column in the CATS table. Hibernate will use + ResultSetMetadata to deduce the actual order and types of the returned + scalar values.</para> + + <para>To avoid the overhead of using + <literal>ResultSetMetadata</literal> or simply to be more explicit in + what is returned one can use <literal>addScalar()</literal>.</para> + + <programlisting><![CDATA[sess.createSQLQuery("SELECT * FROM CATS") + .addScalar("ID", Hibernate.LONG) + .addScalar("NAME", Hibernate.STRING) + .addScalar("BIRTHDATE", Hibernate.DATE) +]]></programlisting> + + <para>This query specified:</para> + + <itemizedlist> + <listitem> + <para>the SQL query string</para> + </listitem> + + <listitem> + <para>the columns and types to return</para> + </listitem> + </itemizedlist> + + <para>This will still return Object arrays, but now it will not use + <literal>ResultSetMetdata</literal> but will instead explicitly get the + ID, NAME and BIRTHDATE column as respectively a Long, String and a Short + from the underlying resultset. This also means that only these three + columns will be returned, even though the query is using + <literal>*</literal> and could return more than the three listed + columns.</para> + + <para>It is possible to leave out the type information for all or some + of the scalars.</para> + + <programlisting><![CDATA[sess.createSQLQuery("SELECT * FROM CATS") + .addScalar("ID", Hibernate.LONG) + .addScalar("NAME") + .addScalar("BIRTHDATE") +]]></programlisting> + + <para>This is essentially the same query as before, but now + <literal>ResultSetMetaData</literal> is used to decide the type of NAME + and BIRTHDATE where as the type of ID is explicitly specified.</para> + + <para>How the java.sql.Types returned from ResultSetMetaData is mapped + to Hibernate types is controlled by the Dialect. If a specific type is + not mapped or does not result in the expected type it is possible to + customize it via calls to <literal>registerHibernateType</literal> in + the Dialect.</para> + </sect2> + + <sect2> + <title>Entity queries</title> + + <para>The above queries were all about returning scalar values, + basically returning the "raw" values from the resultset. The following + shows how to get entity objects from a native sql query via + <literal>addEntity()</literal>.</para> + + <programlisting><![CDATA[sess.createSQLQuery("SELECT * FROM CATS").addEntity(Cat.class); +sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE FROM CATS").addEntity(Cat.class); +]]></programlisting> + + <para>This query specified:</para> + + <itemizedlist> + <listitem> + <para>the SQL query string</para> + </listitem> + + <listitem> + <para>the entity returned by the query</para> + </listitem> + </itemizedlist> + + <para>Assuming that Cat is mapped as a class with the columns ID, NAME + and BIRTHDATE the above queries will both return a List where each + element is a Cat entity.</para> + + <para>If the entity is mapped with a <literal>many-to-one</literal> to + another entity it is required to also return this when performing the + native query, otherwise a database specific "column not found" error + will occur. The additional columns will automatically be returned when + using the * notation, but we prefer to be explicit as in the following + example for a <literal>many-to-one</literal> to a + <literal>Dog</literal>:</para> + + <programlisting><![CDATA[sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE, DOG_ID FROM CATS").addEntity(Cat.class); +]]></programlisting> + + <para>This will allow cat.getDog() to function properly.</para> + </sect2> + + <sect2> + <title>Handling associations and collections</title> + + <para>It is possible to eagerly join in the <literal>Dog</literal> to + avoid the possible extra roundtrip for initializing the proxy. This is + done via the <literal>addJoin()</literal> method, which allows you to + join in an association or collection.</para> + + <programlisting><![CDATA[sess.createSQLQuery("SELECT c.ID, NAME, BIRTHDATE, DOG_ID, D_ID, D_NAME FROM CATS c, DOGS d WHERE c.DOG_ID = d.D_ID") + .addEntity("cat", Cat.class) + .addJoin("cat.dog"); +]]></programlisting> + + <para>In this example the returned <literal>Cat</literal>'s will have + their <literal>dog</literal> property fully initialized without any + extra roundtrip to the database. Notice that we added a alias name + ("cat") to be able to specify the target property path of the join. It + is possible to do the same eager joining for collections, e.g. if the + <literal>Cat</literal> had a one-to-many to <literal>Dog</literal> + instead.</para> + + <programlisting><![CDATA[sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE, D_ID, D_NAME, CAT_ID FROM CATS c, DOGS d WHERE c.ID = d.CAT_ID") + .addEntity("cat", Cat.class) + .addJoin("cat.dogs"); +]]></programlisting> + + <p>At this stage we are reaching the limits of what is possible with + native queries without starting to enhance the sql queries to make them + usable in Hibernate; the problems starts to arise when returning + multiple entities of the same type or when the default alias/column + names are not enough.</p> + </sect2> + + <sect2> + <title>Returning multiple entities</title> + + <para>Until now the result set column names are assumed to be the same + as the column names specified in the mapping document. This can be + problematic for SQL queries which join multiple tables, since the same + column names may appear in more than one table.</para> + + <para>Column alias injection is needed in the following query (which + most likely will fail):</para> + + <programlisting><![CDATA[sess.createSQLQuery("SELECT c.*, m.* FROM CATS c, CATS m WHERE c.MOTHER_ID = c.ID") + .addEntity("cat", Cat.class) + .addEntity("mother", Cat.class) +]]></programlisting> + + <para>The intention for this query is to return two Cat instances per + row, a cat and its mother. This will fail since there is a conflict of + names since they are mapped to the same column names and on some + databases the returned column aliases will most likely be on the form + "c.ID", "c.NAME", etc. which are not equal to the columns specificed in + the mappings ("ID" and "NAME").</para> + + <para>The following form is not vulnerable to column name + duplication:</para> + + <programlisting><![CDATA[sess.createSQLQuery("SELECT {cat.*}, {mother.*} FROM CATS c, CATS m WHERE c.MOTHER_ID = c.ID") + .addEntity("cat", Cat.class) + .addEntity("mother", Cat.class) +]]></programlisting> + + <para>This query specified:</para> + + <itemizedlist> + <listitem> + <para>the SQL query string, with placeholders for Hibernate to + inject column aliases</para> + </listitem> + + <listitem> + <para>the entities returned by the query</para> + </listitem> + </itemizedlist> + + <para>The {cat.*} and {mother.*} notation used above is a shorthand for + "all properties". Alternatively, you may list the columns explicity, but + even in this case we let Hibernate inject the SQL column aliases for + each property. The placeholder for a column alias is just the property + name qualified by the table alias. In the following example, we retrieve + Cats and their mothers from a different table (cat_log) to the one + declared in the mapping metadata. Notice that we may even use the + property aliases in the where clause if we like.</para> + + <programlisting><![CDATA[String sql = "SELECT ID as {c.id}, NAME as {c.name}, " + + "BIRTHDATE as {c.birthDate}, MOTHER_ID as {c.mother}, {mother.*} " + + "FROM CAT_LOG c, CAT_LOG m WHERE {c.mother} = c.ID"; + +List loggedCats = sess.createSQLQuery(sql) + .addEntity("cat", Cat.class) + .addEntity("mother", Cat.class).list() +]]></programlisting> + + <sect3 id="querysql-aliasreferences" revision="2"> + <title>Alias and property references</title> + + <para>For most cases the above alias injection is needed, but for + queries relating to more complex mappings like composite properties, + inheritance discriminators, collections etc. there are some specific + aliases to use to allow Hibernate to inject the proper aliases.</para> + + <para>The following table shows the different possibilities of using + the alias injection. Note: the alias names in the result are examples, + each alias will have a unique and probably different name when + used.</para> + + <table frame="topbot" id="aliasinjection-summary"> + <title>Alias injection names</title> + + <tgroup cols="3"> + <colspec colwidth="1*" /> + + <colspec colwidth="1*" /> + + <colspec colwidth="2.5*" /> + + <thead> + <row> + <entry>Description</entry> + + <entry>Syntax</entry> + + <entry>Example</entry> + </row> + </thead> + + <tbody> + <row> + <entry>A simple property</entry> + + <entry><literal>{[aliasname].[propertyname]</literal></entry> + + <entry><literal>A_NAME as {item.name}</literal></entry> + </row> + + <row> + <entry>A composite property</entry> + + <entry><literal>{[aliasname].[componentname].[propertyname]}</literal></entry> + + <entry><literal>CURRENCY as {item.amount.currency}, VALUE as + {item.amount.value}</literal></entry> + </row> + + <row> + <entry>Discriminator of an entity</entry> + + <entry><literal>{[aliasname].class}</literal></entry> + + <entry><literal>DISC as {item.class}</literal></entry> + </row> + + <row> + <entry>All properties of an entity</entry> + + <entry><literal>{[aliasname].*}</literal></entry> + + <entry><literal>{item.*}</literal></entry> + </row> + + <row> + <entry>A collection key</entry> + + <entry><literal>{[aliasname].key}</literal></entry> + + <entry><literal>ORGID as {coll.key}</literal></entry> + </row> + + <row> + <entry>The id of an collection</entry> + + <entry><literal>{[aliasname].id}</literal></entry> + + <entry><literal>EMPID as {coll.id}</literal></entry> + </row> + + <row> + <entry>The element of an collection</entry> + + <entry><literal>{[aliasname].element}</literal></entry> + + <entry><literal>XID as {coll.element}</literal></entry> + </row> + + <row> + <entry>roperty of the element in the collection</entry> + + <entry><literal>{[aliasname].element.[propertyname]}</literal></entry> + + <entry><literal>NAME as {coll.element.name}</literal></entry> + </row> + + <row> + <entry>All properties of the element in the collection</entry> + + <entry><literal>{[aliasname].element.*}</literal></entry> + + <entry><literal>{coll.element.*}</literal></entry> + </row> + + <row> + <entry>All properties of the the collection</entry> + + <entry><literal>{[aliasname].*}</literal></entry> + + <entry><literal>{coll.*}</literal></entry> + </row> + </tbody> + </tgroup> + </table> + </sect3> + </sect2> + + <sect2> + <title>Returning non-managed entities</title> + + <para>It is possible to apply a ResultTransformer to native sql queries. Allowing it to e.g. return non-managed entities.</para> + + <programlisting><![CDATA[sess.createSQLQuery("SELECT NAME, BIRTHDATE FROM CATS") + .setResultTransformer(Transformers.aliasToBean(CatDTO.class))]]></programlisting> + + <para>This query specified:</para> + + <itemizedlist> + <listitem> + <para>the SQL query string</para> + </listitem> + + <listitem> + <para>a result transformer</para> + </listitem> + </itemizedlist> + + <para> + The above query will return a list of <literal>CatDTO</literal> which has been instantiated and injected the values of NAME and BIRTHNAME into its corresponding + properties or fields. + </para> + </sect2> + + <sect2> + <title>Handling inheritance</title> + + <para>Native sql queries which query for entities that is mapped as part + of an inheritance must include all properties for the baseclass and all + it subclasses.</para> + </sect2> + + <sect2> + <title>Parameters</title> + + <para>Native sql queries support positional as well as named + parameters:</para> + + <programlisting><![CDATA[Query query = sess.createSQLQuery("SELECT * FROM CATS WHERE NAME like ?").addEntity(Cat.class); +List pusList = query.setString(0, "Pus%").list(); + +query = sess.createSQLQuery("SELECT * FROM CATS WHERE NAME like :name").addEntity(Cat.class); +List pusList = query.setString("name", "Pus%").list(); ]]></programlisting> + </sect2> + + + + </sect1> + + <sect1 id="querysql-namedqueries" revision="3"> + <title>Named SQL queries</title> + + <para>Named SQL queries may be defined in the mapping document and called + in exactly the same way as a named HQL query. In this case, we do + <emphasis>not</emphasis> need to call + <literal>addEntity()</literal>.</para> + + <programlisting><![CDATA[<sql-query name="persons"> + <return alias="person" class="eg.Person"/> + SELECT person.NAME AS {person.name}, + person.AGE AS {person.age}, + person.SEX AS {person.sex} + FROM PERSON person + WHERE person.NAME LIKE :namePattern +</sql-query>]]></programlisting> + + <programlisting><![CDATA[List people = sess.getNamedQuery("persons") + .setString("namePattern", namePattern) + .setMaxResults(50) + .list();]]></programlisting> + + <para>The <literal>&lt;return-join&gt;</literal> and + <literal>&lt;load-collection&gt;</literal> elements are used to join + associations and define queries which initialize collections, + respectively.</para> + + <programlisting><![CDATA[<sql-query name="personsWith"> + <return alias="person" class="eg.Person"/> + <return-join alias="address" property="person.mailingAddress"/> + SELECT person.NAME AS {person.name}, + person.AGE AS {person.age}, + person.SEX AS {person.sex}, + address.STREET AS {address.street}, + address.CITY AS {address.city}, + address.STATE AS {address.state}, + address.ZIP AS {address.zip} + FROM PERSON person + JOIN ADDRESS address + ON person.ID = address.PERSON_ID AND address.TYPE='MAILING' + WHERE person.NAME LIKE :namePattern +</sql-query>]]></programlisting> + + <para>A named SQL query may return a scalar value. You must declare the + column alias and Hibernate type using the + <literal>&lt;return-scalar&gt;</literal> element:</para> + + <programlisting><![CDATA[<sql-query name="mySqlQuery"> + <return-scalar column="name" type="string"/> + <return-scalar column="age" type="long"/> + SELECT p.NAME AS name, + p.AGE AS age, + FROM PERSON p WHERE p.NAME LIKE 'Hiber%' +</sql-query>]]></programlisting> + + <para>You can externalize the resultset mapping informations in a + <literal>&lt;resultset&gt;</literal> element to either reuse them accross + several named queries or through the + <literal>setResultSetMapping()</literal> API.</para> + + <programlisting><![CDATA[<resultset name="personAddress"> + <return alias="person" class="eg.Person"/> + <return-join alias="address" property="person.mailingAddress"/> +</resultset> + +<sql-query name="personsWith" resultset-ref="personAddress"> + SELECT person.NAME AS {person.name}, + person.AGE AS {person.age}, + person.SEX AS {person.sex}, + address.STREET AS {address.street}, + address.CITY AS {address.city}, + address.STATE AS {address.state}, + address.ZIP AS {address.zip} + FROM PERSON person + JOIN ADDRESS address + ON person.ID = address.PERSON_ID AND address.TYPE='MAILING' + WHERE person.NAME LIKE :namePattern +</sql-query>]]></programlisting> + + <para>You can alternatively use the resultset mapping information in your + hbm files directly in java code.</para> + + <programlisting><![CDATA[List cats = sess.createSQLQuery( + "select {cat.*}, {kitten.*} from cats cat, cats kitten where kitten.mother = cat.id" + ) + .setResultSetMapping("catAndKitten") + .list();]]></programlisting> + + <sect2 id="propertyresults"> + <title>Using return-property to explicitly specify column/alias + names</title> + + <para>With <literal>&lt;return-property&gt;</literal> you can explicitly + tell Hibernate what column aliases to use, instead of using the + <literal>{}</literal>-syntax to let Hibernate inject its own + aliases.</para> + + <programlisting><![CDATA[<sql-query name="mySqlQuery"> + <return alias="person" class="eg.Person"> + <return-property name="name" column="myName"/> + <return-property name="age" column="myAge"/> + <return-property name="sex" column="mySex"/> + </return> + SELECT person.NAME AS myName, + person.AGE AS myAge, + person.SEX AS mySex, + FROM PERSON person WHERE person.NAME LIKE :name +</sql-query> +]]></programlisting> + + <para><literal>&lt;return-property&gt;</literal> also works with + multiple columns. This solves a limitation with the + <literal>{}</literal>-syntax which can not allow fine grained control of + multi-column properties.</para> + + <programlisting><![CDATA[<sql-query name="organizationCurrentEmployments"> + <return alias="emp" class="Employment"> + <return-property name="salary"> + <return-column name="VALUE"/> + <return-column name="CURRENCY"/> + </return-property> + <return-property name="endDate" column="myEndDate"/> + </return> + SELECT EMPLOYEE AS {emp.employee}, EMPLOYER AS {emp.employer}, + STARTDATE AS {emp.startDate}, ENDDATE AS {emp.endDate}, + REGIONCODE as {emp.regionCode}, EID AS {emp.id}, VALUE, CURRENCY + FROM EMPLOYMENT + WHERE EMPLOYER = :id AND ENDDATE IS NULL + ORDER BY STARTDATE ASC +</sql-query>]]></programlisting> + + <para>Notice that in this example we used + <literal>&lt;return-property&gt;</literal> in combination with the + <literal>{}</literal>-syntax for injection. Allowing users to choose how + they want to refer column and properties.</para> + + <para>If your mapping has a discriminator you must use + <literal>&lt;return-discriminator&gt;</literal> to specify the + discriminator column.</para> + </sect2> + + <sect2 id="sp_query" revision="1"> + <title>Using stored procedures for querying</title> + + <para>Hibernate 3 introduces support for queries via stored procedures + and functions. Most of the following documentation is equivalent for + both. The stored procedure/function must return a resultset as the first + out-parameter to be able to work with Hibernate. An example of such a + stored function in Oracle 9 and higher is as follows:</para> + + <programlisting><![CDATA[CREATE OR REPLACE FUNCTION selectAllEmployments + RETURN SYS_REFCURSOR +AS + st_cursor SYS_REFCURSOR; +BEGIN + OPEN st_cursor FOR + SELECT EMPLOYEE, EMPLOYER, + STARTDATE, ENDDATE, + REGIONCODE, EID, VALUE, CURRENCY + FROM EMPLOYMENT; + RETURN st_cursor; + END;]]></programlisting> + + <para>To use this query in Hibernate you need to map it via a named + query.</para> + + <programlisting><![CDATA[<sql-query name="selectAllEmployees_SP" callable="true"> + <return alias="emp" class="Employment"> + <return-property name="employee" column="EMPLOYEE"/> + <return-property name="employer" column="EMPLOYER"/> + <return-property name="startDate" column="STARTDATE"/> + <return-property name="endDate" column="ENDDATE"/> + <return-property name="regionCode" column="REGIONCODE"/> + <return-property name="id" column="EID"/> + <return-property name="salary"> + <return-column name="VALUE"/> + <return-column name="CURRENCY"/> + </return-property> + </return> + { ? = call selectAllEmployments() } +</sql-query>]]></programlisting> + + <para>Notice stored procedures currently only return scalars and + entities. <literal>&lt;return-join&gt;</literal> and + <literal>&lt;load-collection&gt;</literal> are not supported.</para> + + <sect3 id="querysql-limits-storedprocedures" revision="1"> + <title>Rules/limitations for using stored procedures</title> + + <para>To use stored procedures with Hibernate the procedures/functions + have to follow some rules. If they do not follow those rules they are + not usable with Hibernate. If you still want to use these procedures + you have to execute them via <literal>session.connection()</literal>. + The rules are different for each database, since database vendors have + different stored procedure semantics/syntax.</para> + + <para>Stored procedure queries can't be paged with + <literal>setFirstResult()/setMaxResults()</literal>.</para> + + <para>Recommended call form is standard SQL92: <literal>{ ? = call + functionName(&lt;parameters&gt;) }</literal> or <literal>{ ? = call + procedureName(&lt;parameters&gt;}</literal>. Native call syntax is not + supported.</para> + + <para>For Oracle the following rules apply:</para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + A fun��p deve retornar um result set. O primeiro par�metro da procedure + dever ser uma <literal>SA�DA</literal> que retorne um result set. Isto � feito + usando o tipo a <literal>SYS_REFCURSOR</literal> no Oracle 9 ou 10. No Oracle � + necess�rio definir o tipo <literal>REF CURSOR</literal>, veja a documenta��o do Oracle. + </para> + </listitem> + </itemizedlist> + + <para>For Sybase or MS SQL server the following rules apply:</para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + A procedure deve retornar um result set. Veja que este servidor pode retornar + m�ltiplos result sets e update counts. O Hibernate ira iterar os resultados e + pegar o primeiro resultado que � o valor de retorno do result set. + O resto ser� descartado. + </para> + </listitem> + + <listitem> + <para> + Se voc� habilitar <literal>SET NOCOUNT ON</literal> na sua procedure, ela + provavelmente ser� mais eficiente. Mas, isto n�o � obrigat�rio</para> + </listitem> + </itemizedlist> + </sect3> + </sect2> + </sect1> + + <sect1 id="querysql-cud"> + <title>SQL customizado para create, update e delete</title> + + <para>Hibernate3 can use custom SQL statements for create, update, and + delete operations. The class and collection persisters in Hibernate + already contain a set of configuration time generated strings (insertsql, + deletesql, updatesql etc.). The mapping tags + <literal>&lt;sql-insert&gt;</literal>, + <literal>&lt;sql-delete&gt;</literal>, and + <literal>&lt;sql-update&gt;</literal> override these strings: + + Hibernate3 pode usar SQL customizado para opera��es de create, update e delete. + A persist�ncia de classe e collection no hibernate j� contem alguma strings + de configura��es (insertsql, deletesql, updatesql etc.). + O mapaemento das tags + <literal>&lt;sql-insert&gt;</literal>, + <literal>&lt;sql-delete&gt;</literal>, e + <literal>&lt;sql-update&gt;</literal> + sobreecreve essas strings: + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id"> + <generator class="increment"/> + </id> + <property name="name" not-null="true"/> + <sql-insert>INSERT INTO PERSON (NAME, ID) VALUES ( UPPER(?), ? )</sql-insert> + <sql-update>UPDATE PERSON SET NAME=UPPER(?) WHERE ID=?</sql-update> + <sql-delete>DELETE FROM PERSON WHERE ID=?</sql-delete> +</class>]]></programlisting> + + <para> + O SQL � executado diretamente no seu banco de dados, ent�o voc� pode usar qualquer + linguagem que quiser. Isto com certeza reduzira a portabilidade do seu mapeamento se + voc� utilizar um SQL para um banco de dados especifico. + </para> + + <para> + Stored Procedures s�o suportadas se o atributo the + <literal>callable</literal> estiver ativado: + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id"> + <generator class="increment"/> + </id> + <property name="name" not-null="true"/> + <sql-insert callable="true">{call createPerson (?, ?)}</sql-insert> + <sql-delete callable="true">{? = call deletePerson (?)}</sql-delete> + <sql-update callable="true">{? = call updatePerson (?, ?)}</sql-update> +</class>]]></programlisting> + + <para> + A ordem de posi��es dos par�metros s�o vitais, pois eles devem estar na mesma seq��ncia + esperada pelo Hibernate. + </para> + + <para>Voc� pode ver a ordem esperada ativando o debug logging no n�vel + <literal>org.hibernate.persister.entity</literal>. Com este n�vel ativado, o Hibernate + ir� imprimir o SQL est�tico que foi usado para create, update, delete, etc. + Entidades. (Para ver a seq��ncia esperada, lembre-se de n�o incluir seu SQL + customizado no arquivo de mapeamento, pois ele ir� sobreecreve o SQL + est�tico gerado pelo Hibernate). + </para> + + <para>As stored procedures s�o na maioria dos casos (leia: melhor n�o fazer) requeridas para + retornar o numero de linhas inseridas/atualizadas/deletadas. O hibernate tem algumas + verifica��es em tempo de execu��o para o sucesso da declara��o. Hibernate sempre registra + o primeiro par�metro da declara��o como uma sa�da num�rica para opera��es CRUD. + </para> + + <programlisting><![CDATA[CREATE OR REPLACE FUNCTION updatePerson (uid IN NUMBER, uname IN VARCHAR2) + RETURN NUMBER IS +BEGIN + + update PERSON + set + NAME = uname, + where + ID = uid; + + return SQL%ROWCOUNT; + +END updatePerson;]]> +</programlisting> + + </sect1> + + <sect1 id="querysql-load"> + <title>SQL customizado para carga</title> + + <para> + Voc� pode declarar sua pr�pria query SQL (ou HQL) para iniciar entidades: + </para> + + <programlisting><![CDATA[<sql-query name="person"> + <return alias="pers" class="Person" lock-mode="upgrade"/> + SELECT NAME AS {pers.name}, ID AS {pers.id} + FROM PERSON + WHERE ID=? + FOR UPDATE +</sql-query>]]></programlisting> + + <para> + Este � apenas uma declara��o de query com nome, como discutido anteriormente. + Voc� pode referenciar esta query com nome em um mapeamento de classe: + </para> + + <programlisting><![CDATA[<class name="Person"> + <id name="id"> + <generator class="increment"/> + </id> + <property name="name" not-null="true"/> + <loader query-ref="person"/> +</class>]]></programlisting> + + <para>Isto tamb�m funciona com stored procedures. + </para> + + <para>Voc� pode temb�m definir uma query para iniciar collection: + </para> + + <programlisting><![CDATA[<set name="employments" inverse="true"> + <key/> + <one-to-many class="Employment"/> + <loader query-ref="employments"/> +</set>]]></programlisting> + + <programlisting><![CDATA[<sql-query name="employments"> + <load-collection alias="emp" role="Person.employments"/> + SELECT {emp.*} + FROM EMPLOYMENT emp + WHERE EMPLOYER = :id + ORDER BY STARTDATE ASC, EMPLOYEE ASC +</sql-query>]]></programlisting> + + <para>You could even define an entity loader that loads a collection by + join fetching:</para> + + <programlisting><![CDATA[<sql-query name="person"> + <return alias="pers" class="Person"/> + <return-join alias="emp" property="pers.employments"/> + SELECT NAME AS {pers.*}, {emp.*} + FROM PERSON pers + LEFT OUTER JOIN EMPLOYMENT emp + ON pers.ID = emp.PERSON_ID + WHERE ID=? +</sql-query>]]></programlisting> + </sect1> +</chapter> \ No newline at end of file Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/session_api.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/session_api.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/session_api.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/session_api.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,1245 @@ +<chapter id="objectstate"> + <title>Trabalhando com objetos</title> + + <para> + O Hibernate é uma solução completa de mapeamento objeto/relacional que não apenas + poupa o desenvolvedor dos detalhes de baixo nível do sistema de gerenciamento do + banco de dados, mas também oferece um <emphasis>gerenciamento de estado </emphasis> + para objetos. Isto é, ao contrário do gerenciamento de <literal>instruções </literal> + SQL em camadas de persistência JDBC/SQL comuns, uma visão natural da persistência + orientada a objetos em aplicações Java. + </para> + + <para> + Em outras palavras, desenvolvedores de aplicações Hibernate podem sempre pensar em + relação ao <emphasis>estado</emphasis> de seus objetos, e não necessariamente em + relação a execução de instruções SQL. Este parte é responsabilidade do Hibernate e + é relevante aos desenvolvedores de aplicações apenas quando estão ajustando + a performance do sistema. + </para> + + <sect1 id="objectstate-overview"> + <title>Estado dos objetos no Hibernate</title> + + <para> + O Hibernate define e suporta os seguintes estados de um objetos: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>Transient</emphasis> - um objeto é transiente se ele foi instanciando + usando apenas o operador <literal>new</literal>, e não foi associado com uma + <literal>Session</literal> do Hibernate. Ele não terá uma representação + persistente no banco de dados e nenhum identificador será atribuído para ele. + Instâncias transientes serão destruídas pelo coletor de lixo se a aplicação + não manter sua referência. Use uma <literal>Session</literal> do Hibernate + para tornar o objeto persistente ( e deixe o Hibernate gerenciar as + instruções SQL que serão necessárias para executar esta transição). + </para> + </listitem> + <listitem> + <para> + <emphasis>Persistent</emphasis> -– uma instância persistente possui uma + representação no banco de dados e um identificador. Ele pode ter sido salvo + ou carregado, assim, ele está por definição no escopo de uma + <literal>Session</literal>. O Hibernate irá detectar qualquer mudança feita a + um objeto persistente e sincronizar o seu estado com o banco de dados quando + completar a unidade de trabalho. Desenvolvedores não executam instruções manuais + de <literal>UPDATE</literal>, ou instruções de <literal>DELETE</literal> + quando o objeto deve ser passado para transiente. + </para> + </listitem> + <listitem> + <para> + <emphasis>Detached</emphasis> – uma instância desaclopada é um objeto que + foi persistido, mas sua <literal>Session</literal> foi fechada. A referência + ao objeto continua válida, é claro, e a instância destacada desaclopada pode + ser acoplada a uma nova <literal>Session</literal> no futuro, fazendo-o + ( e todas as modificações sofridas) persistente novamente. Essa característica + possibilita um modelo de programação para unidades de trabalho que rodam + durante muito tempo que requer um pensamento por tempo do usuário. Podemos + chamar-las de <emphasis>transações da aplicação</emphasis>, i.e. uma unidade + de trabalho do ponto de vista do usuário. + </para> + </listitem> + </itemizedlist> + + <para> + Agora iremos discutir os estados e suas transições ( e os métodos do Hibernate que + disparam uma transição) em mais detalhes. + </para> + + </sect1> + + <sect1 id="objectstate-makingpersistent" revision="1"> + <title>Tornando os objetos persistentes</title> + + <para> + Instâncias recentemente instanciadas de uma classe persistente são + consideradas <emphasis>transientes </emphasis> pelo Hibernate. + Podemos tornar uma instância transiente em <emphasis>persistente</emphasis> + associando-a a uma sessão: + </para> + + <programlisting><![CDATA[DomesticCat fritz = new DomesticCat(); +fritz.setColor(Color.GINGER); +fritz.setSex('M'); +fritz.setName("Fritz"); +Long generatedId = (Long) sess.save(fritz);]]></programlisting> + + <para> + Se <literal>Cat</literal> possui um identificador gerado, o identificador + é gerado e atribuído a <literal>cat</literal> quando <literal>save()</literal> + for chamada. Se <literal>Cat</literal> possuir um identificador + <literal>Associado</literal>, ou uma chave composta, o identificador deve ser + atribuído à instância de <literal>cat</literal> antes que <literal>save()</literal> + seja chamado. Pode-se usar também <literal>persist()</literal> ao invés de + <literal>save()</literal>, com a semântica definada no novo esboço do EJB3. + </para> + + <para> + Alternativamente, pode-se atribuir o identificador usando uma versão + sobrecarregada de <literal>save()</literal>. + </para> + +<programlisting><![CDATA[DomesticCat pk = new DomesticCat(); +pk.setColor(Color.TABBY); +pk.setSex('F'); +pk.setName("PK"); +pk.setKittens( new HashSet() ); +pk.addKitten(fritz); +sess.save( pk, new Long(1234) );]]></programlisting> + + <para> + Se o objeto persistido possuir objetos associados (e.g. a coleção + <literal>kittens</literal> no exemplo anterior), esses objetos podem ser + tornar persistente em qualquer ordem que se queira ao menos que se tenha uma + restrição <literal>NOT NULL</literal> em uma coluna de chave estrangeira. + Nunca há risco de violação de restrições de chave estrangeira. Assim, + pode-se violar uma restrição <literal>NOT NULL</literal> se + <literal>save()</literal> for usada nos objetos em uma ordem errada. + </para> + + <para> + Geralmente você não deve se importar com esses detalhes, muito provavelmente se + usará a característica de <emphasis>persistência transitiva </emphasis> do Hibernate + para salvar os objetos associados automaticamente. Então, enquanto uma restrição + <literal>NOT NULL</literal> não ocorrer – Hibernate tomará conta de tudo. + Persistência transitiva será discutida futuramente nesse capítulo. + </para> + + </sect1> + + <sect1 id="objectstate-loading"> + <title>Carregando o objetos</title> + + <para> + O método <literal>load()</literal> de uma <literal> Session</literal> nos + fornece um meio para recuperar uma instância persistente se o identificador + for conhecido. <literal>load()</literal> recebe uma classe do objeto e carregará + o estado em uma instância mais recente dessa classe, no estado persistente. + </para> + + <programlisting><![CDATA[Cat fritz = (Cat) sess.load(Cat.class, generatedId);]]></programlisting> + +<programlisting><![CDATA[// you need to wrap primitive identifiers +long id = 1234; +DomesticCat pk = (DomesticCat) sess.load( DomesticCat.class, new Long(id) );]]></programlisting> + + <para> + Alternatively, you can load state into a given instance: +Alternativamente, pode-se carregar um estado em uma instância dada: + </para> + +<programlisting><![CDATA[Cat cat = new DomesticCat(); +// load pk's state into cat +sess.load( cat, new Long(pkId) ); +Set kittens = cat.getKittens();]]></programlisting> + + <para> + Repare que <literal>load()</literal> irá lançar uma exceção irrecuperável + se não houver na tabela no banco de dados um registro que combine. + Se a classe for mapeada com um proxy, <literal>load()</literal> + simplesmente retorna um proxy não inicializado e realmente não chamará + o banco de dados até que um método do proxy seja invocado. + Esse comportamento é muito útil se deseja-se criar uma associação + com um objeto sem que realmente o carregue do bando de dados. + Isto também permite que sejam carregadas múltiplas instâncias como um + grupo se <literal>batch-size</literal> estiver para o mapeamento da + classe. + </para> + + <para> + Se você não tiver certeza da existencia do registro no banco, você deve + usar o metodo <literal>get()</literal>, que consulta o banco + imediantamente e retorna um null se não existir o registro. + </para> + + <programlisting><![CDATA[Cat cat = (Cat) sess.get(Cat.class, id); +if (cat==null) { + cat = new Cat(); + sess.save(cat, id); +} +return cat;]]></programlisting> + + <para> + Também pode-se carregar um objeto usando <literal>SELECT ... FOR UPDATE</literal>, + usando um <literal>LockMode</literal>. Veja a documentação da API para maiores + informações. + </para> + + <programlisting><![CDATA[Cat cat = (Cat) sess.get(Cat.class, id, LockMode.UPGRADE);]]></programlisting> + + <para> + Note that any associated instances or contained collections are + <emphasis>not</emphasis> selected <literal>FOR UPDATE</literal>, unless you decide + to specify <literal>lock</literal> or <literal>all</literal> as a + cascade style for the association. + </para> + + <para> + O recarregamento de um objeto e todas as suas coleções é possível a qualquer momento, + usando o método <literal>refresh()</literal>. Util quando as triggers do banco de + dados são usados para inicializar algumas propriedades do objeto. + </para> + + <programlisting><![CDATA[sess.save(cat); +sess.flush(); //force the SQL INSERT +sess.refresh(cat); //re-read the state (after the trigger executes)]]></programlisting> + + <para> + Uma importante questão geralmente aparece neste ponto: O quanto Hibernate carrega + do banco de dados e quantos SQL <literal>SELECT</literal> ele irá usar? Isto + depende da estratégia de <emphasis>recuperação</emphasis>usada e explicada na + <xref linkend="performance-fetching"/>. + </para> + + </sect1> + + <sect1 id="objectstate-querying" revision="1"> + <title>Consultando</title> + + <para> + Se o identificador do objeto que se está buscando não for conhecido, + uma consulta será necessária. O Hibernate suporta uma linguagem de consulta + (HQL) orientada a objetos fácil mas poderosa. Para criação via programação + de consultas, o Hibernate suporta características sofisticadas de consulta + por Critério e Exemplo (QBCe QBE). Pode-se também expressar a consulta + por meio de SQL nativa do banco de dados, com suporte opcional do Hibernate + para conversão do conjunto de reultados em objetos. + </para> + + <sect2 id="objectstate-querying-executing" revision="1"> + <title>Executando consultas</title> + + <para> + Consultas HQL e SQL nativa são representadas por uma instância de <literal>org.hibernate.Query</literal>. + Esta interface oferece métodos para associação de parâmetros, tratamento de conjunto de resultados, + e para a execução de consultas reais. Você pode obter uma <literal>Query</literal> usando a + <literal>Session</literal> atual: + </para> + + <programlisting><![CDATA[List cats = session.createQuery( + "from Cat as cat where cat.birthdate < ?") + .setDate(0, date) + .list(); + +List mothers = session.createQuery( + "select mother from Cat as cat join cat.mother as mother where cat.name = ?") + .setString(0, name) + .list(); + +List kittens = session.createQuery( + "from Cat as cat where cat.mother = ?") + .setEntity(0, pk) + .list(); + +Cat mother = (Cat) session.createQuery( + "select cat.mother from Cat as cat where cat = ?") + .setEntity(0, izi) + .uniqueResult();]] + +Query mothersWithKittens = (Cat) session.createQuery( + "select mother from Cat as mother left join fetch mother.kittens"); +Set uniqueMothers = new HashSet(mothersWithKittens.list());]]></programlisting> + + <para> + Geralmente uma consulta é executada ao invocar <literal>list()</literal>, + o resultado da consulta será carregado completamente em uma coleção na memória. + Instâncias de entidades recuperadas por uma consulta estão no estado persistente. + O <literal>uniqueResult()</literal> oferece um atalho se você souber de + previamente que a consulta retornará apenas um único objeto. Repare que consultas + que fazem uso de buscas de coleções de forma ansiosa (eager) geralmente retornam + duplicatas dos objetos raiz ( mas com suas coleções inicializadas ). Pode-se + filtrar estas duplicatas através de um simples <literal>Set</literal>. + </para> + + <sect3 id="objectstate-querying-executing-iterate"> + <title>Interagindo com resultados</title> + + <para> + Ocasionalmente, deves-se ser capaz de atingir performances melhores com + a execução de consultas usando o método <literal>iterate()</literal>. + Geralmente isso será o caso esperado apenas se as instâncias dos entidades + reais retornadas pela consulta já estiverem na sessão ou no caché de segundo + nível. Caso elas ainda não tenham sido armazenadas, <literal>iterate()</literal> + será mais devagar do que <literal>list()</literal> e pode ser necessário vários + acessos ao banco de dados para um simples consulta, geralmente <emphasis>1</emphasis> + para a seleção inicial que retorna apenas identificadores, e <emphasis>n</emphasis> + consultas adicionais para inicializar as instâncias reais. + </para> + + <programlisting><![CDATA[// fetch ids +Iterator iter = sess.createQuery("from eg.Qux q order by q.likeliness").iterate(); +while ( iter.hasNext() ) { + Qux qux = (Qux) iter.next(); // fetch the object + // something we couldnt express in the query + if ( qux.calculateComplicatedAlgorithm() ) { + // delete the current instance + iter.remove(); + // dont need to process the rest + break; + } +}]]></programlisting> + </sect3> + + <sect3 id="objectstate-querying-executing-tuples"> + <title>Consultas que retornam tuplas</title> + + <para> + Algumas vezes as consultas do Hibernate retornam tuplas de objetos, nesse caso + cada tupla é retornada como um array: + </para> + + <programlisting><![CDATA[Iterator kittensAndMothers = sess.createQuery( + "select kitten, mother from Cat kitten join kitten.mother mother") + .list() + .iterator(); + +while ( kittensAndMothers.hasNext() ) { + Object[] tuple = (Object[]) kittensAndMothers.next(); + Cat kitten = (Cat) tuple[0]; + Cat mother = (Cat) tuple[1]; + .... +}]]></programlisting> + + </sect3> + + <sect3 id="objectstate-querying-executing-scalar" revision="1"> + <title>Resultados escalares</title> + + <para> + Consultas devem especificar uma propriedade da classe na clausula + <literal>select</literal>. Elas também podem chamar funções SQL de agregaçãos. + Propriedades ou agregações são considerados resultados agregados + ( e não entidades no estado persistente). + </para> + + <programlisting><![CDATA[Iterator results = sess.createQuery( + "select cat.color, min(cat.birthdate), count(cat) from Cat cat " + + "group by cat.color") + .list() + .iterator(); + +while ( results.hasNext() ) { + Object[] row = (Object[]) results.next(); + Color type = (Color) row[0]; + Date oldest = (Date) row[1]; + Integer count = (Integer) row[2]; + ..... +}]]></programlisting> + + </sect3> + + <sect3 id="objectstate-querying-executing-parameters"> + <title>Bind parameters</title> + + <para> + Methods on <literal>Query</literal> are provided for binding values to + named parameters or JDBC-style <literal>?</literal> parameters. + <emphasis>Contrary to JDBC, Hibernate numbers parameters from zero.</emphasis> + Named parameters are identifiers of the form <literal>:name</literal> in + the query string. The advantages of named parameters are: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + named parameters are insensitive to the order they occur in the + query string + </para> + </listitem> + <listitem> + <para> + they may occur multiple times in the same query + </para> + </listitem> + <listitem> + <para> + they are self-documenting + </para> + </listitem> + </itemizedlist> + + <programlisting><![CDATA[//named parameter (preferred) +Query q = sess.createQuery("from DomesticCat cat where cat.name = :name"); +q.setString("name", "Fritz"); +Iterator cats = q.iterate();]]></programlisting> + + <programlisting><![CDATA[//positional parameter +Query q = sess.createQuery("from DomesticCat cat where cat.name = ?"); +q.setString(0, "Izi"); +Iterator cats = q.iterate();]]></programlisting> + + <programlisting><![CDATA[//named parameter list +List names = new ArrayList(); +names.add("Izi"); +names.add("Fritz"); +Query q = sess.createQuery("from DomesticCat cat where cat.name in (:namesList)"); +q.setParameterList("namesList", names); +List cats = q.list();]]></programlisting> + + </sect3> + + <sect3 id="objectstate-querying-executing-pagination"> + <title>Pagination</title> + + <para> + If you need to specify bounds upon your result set (the maximum number of rows + you want to retrieve and / or the first row you want to retrieve) you should + use methods of the <literal>Query</literal> interface: + </para> + + <programlisting><![CDATA[Query q = sess.createQuery("from DomesticCat cat"); +q.setFirstResult(20); +q.setMaxResults(10); +List cats = q.list();]]></programlisting> + + <para> + Hibernate knows how to translate this limit query into the native + SQL of your DBMS. + </para> + + </sect3> + + <sect3 id="objectstate-querying-executing-scrolling"> + <title>Scrollable iteration</title> + + <para> + If your JDBC driver supports scrollable <literal>ResultSet</literal>s, the + <literal>Query</literal> interface may be used to obtain a + <literal>ScrollableResults</literal> object, which allows flexible + navigation of the query results. + </para> + + <programlisting><![CDATA[Query q = sess.createQuery("select cat.name, cat from DomesticCat cat " + + "order by cat.name"); +ScrollableResults cats = q.scroll(); +if ( cats.first() ) { + + // find the first name on each page of an alphabetical list of cats by name + firstNamesOfPages = new ArrayList(); + do { + String name = cats.getString(0); + firstNamesOfPages.add(name); + } + while ( cats.scroll(PAGE_SIZE) ); + + // Now get the first page of cats + pageOfCats = new ArrayList(); + cats.beforeFirst(); + int i=0; + while( ( PAGE_SIZE > i++ ) && cats.next() ) pageOfCats.add( cats.get(1) ); + +} +cats.close()]]></programlisting> + + <para> + Note that an open database connection (and cursor) is required for this + functionality, use <literal>setMaxResult()</literal>/<literal>setFirstResult()</literal> + if you need offline pagination functionality. + </para> + + </sect3> + + <sect3 id="objectstate-querying-executing-named" revision="1"> + <title>Externalizing named queries</title> + + <para> + You may also define named queries in the mapping document. (Remember to use a + <literal>CDATA</literal> section if your query contains characters that could + be interpreted as markup.) + </para> + + <programlisting><![CDATA[<query name="ByNameAndMaximumWeight"><![CDATA[ + from eg.DomesticCat as cat + where cat.name = ? + and cat.weight > ? +] ]></query>]]></programlisting> + + <para> + Parameter binding and executing is done programatically: + </para> + + <programlisting><![CDATA[Query q = sess.getNamedQuery("ByNameAndMaximumWeight"); +q.setString(0, name); +q.setInt(1, minWeight); +List cats = q.list();]]></programlisting> + + <para> + Note that the actual program code is independent of the query language that + is used, you may also define native SQL queries in metadata, or migrate + existing queries to Hibernate by placing them in mapping files. + </para> + + <para> + Also note that a query declaration inside a <literal>&lt;hibernate-mapping&gt;</literal> + element requires a global unique name for the query, while a query declaration inside a + <literal>&lt;class&gt;</literal> element is made unique automatically by prepending the + fully qualified name of the class, for example + <literal>eg.Cat.ByNameAndMaximumWeight</literal>. + </para> + + </sect3> + + </sect2> + + <sect2 id="objectstate-filtering" revision="1"> + <title>Filtering collections</title> + <para> + A collection <emphasis>filter</emphasis> is a special type of query that may be applied to + a persistent collection or array. The query string may refer to <literal>this</literal>, + meaning the current collection element. + </para> + + <programlisting><![CDATA[Collection blackKittens = session.createFilter( + pk.getKittens(), + "where this.color = ?") + .setParameter( Color.BLACK, Hibernate.custom(ColorUserType.class) ) + .list() +);]]></programlisting> + + <para> + The returned collection is considered a bag, and it's a copy of the given + collection. The original collection is not modified (this is contrary to + the implication of the name "filter", but consistent with expected behavior). + </para> + + <para> + Observe that filters do not require a <literal>from</literal> clause (though they may have + one if required). Filters are not limited to returning the collection elements themselves. + </para> + + <programlisting><![CDATA[Collection blackKittenMates = session.createFilter( + pk.getKittens(), + "select this.mate where this.color = eg.Color.BLACK.intValue") + .list();]]></programlisting> + + <para> + Even an empty filter query is useful, e.g. to load a subset of elements in a + huge collection: + </para> + + <programlisting><![CDATA[Collection tenKittens = session.createFilter( + mother.getKittens(), "") + .setFirstResult(0).setMaxResults(10) + .list();]]></programlisting> + + </sect2> + + <sect2 id="objecstate-querying-criteria" revision="1"> + <title>Criteria queries</title> + + <para> + HQL is extremely powerful but some developers prefer to build queries dynamically, + using an object-oriented API, rather than building query strings. Hibernate provides + an intuitive <literal>Criteria</literal> query API for these cases: + </para> + + <programlisting><![CDATA[Criteria crit = session.createCriteria(Cat.class); +crit.add( Restrictions.eq( "color", eg.Color.BLACK ) ); +crit.setMaxResults(10); +List cats = crit.list();]]></programlisting> + + <para> + The <literal>Criteria</literal> and the associated <literal>Example</literal> + API are discussed in more detail in <xref linkend="querycriteria"/>. + </para> + + </sect2> + + <sect2 id="objectstate-querying-nativesql" revision="2"> + <title>Queries in native SQL</title> + + <para> + You may express a query in SQL, using <literal>createSQLQuery()</literal> and + let Hibernate take care of the mapping from result sets to objects. Note + that you may at any time call <literal>session.connection()</literal> and + use the JDBC <literal>Connection</literal> directly. If you chose to use the + Hibernate API, you must enclose SQL aliases in braces: + </para> + + <programlisting><![CDATA[List cats = session.createSQLQuery("SELECT {cat.*} FROM CAT {cat} WHERE ROWNUM<10") + .addEntity("cat", Cat.class) +.list();]]></programlisting> + + <programlisting><![CDATA[List cats = session.createSQLQuery( + "SELECT {cat}.ID AS {cat.id}, {cat}.SEX AS {cat.sex}, " + + "{cat}.MATE AS {cat.mate}, {cat}.SUBCLASS AS {cat.class}, ... " + + "FROM CAT {cat} WHERE ROWNUM<10") + .addEntity("cat", Cat.class) +.list()]]></programlisting> + + <para> + SQL queries may contain named and positional parameters, just like Hibernate queries. + More information about native SQL queries in Hibernate can be found in + <xref linkend="querysql"/>. + </para> + + </sect2> + + </sect1> + + <sect1 id="objectstate-modifying" revision="1"> + <title>Modifying persistent objects</title> + + <para> + <emphasis>Transactional persistent instances</emphasis> (ie. objects loaded, saved, created or + queried by the <literal>Session</literal>) may be manipulated by the application + and any changes to persistent state will be persisted when the <literal>Session</literal> + is <emphasis>flushed</emphasis> (discussed later in this chapter). There is no need + to call a particular method (like <literal>update()</literal>, which has a different + purpose) to make your modifications persistent. So the most straightforward way to update + the state of an object is to <literal>load()</literal> it, + and then manipulate it directly, while the <literal>Session</literal> is open: + </para> + + <programlisting><![CDATA[DomesticCat cat = (DomesticCat) sess.load( Cat.class, new Long(69) ); +cat.setName("PK"); +sess.flush(); // changes to cat are automatically detected and persisted]]></programlisting> + + <para> + Sometimes this programming model is inefficient since it would require both an SQL + <literal>SELECT</literal> (to load an object) and an SQL <literal>UPDATE</literal> + (to persist its updated state) in the same session. Therefore Hibernate offers an + alternate approach, using detached instances. + </para> + + <para> + <emphasis>Note that Hibernate does not offer its own API for direct execution of + <literal>UPDATE</literal> or <literal>DELETE</literal> statements. Hibernate is a + <emphasis>state management</emphasis> service, you don't have to think in + <emphasis>statements</emphasis> to use it. JDBC is a perfect API for executing + SQL statements, you can get a JDBC <literal>Connection</literal> at any time + by calling <literal>session.connection()</literal>. Furthermore, the notion + of mass operations conflicts with object/relational mapping for online + transaction processing-oriented applications. Future versions of Hibernate + may however provide special mass operation functions. See <xref linkend="batch"/> + for some possible batch operation tricks.</emphasis> + </para> + + </sect1> + + <sect1 id="objectstate-detached" revision="2"> + <title>Modifying detached objects</title> + + <para> + Many applications need to retrieve an object in one transaction, send it to the + UI layer for manipulation, then save the changes in a new transaction. + Applications that use this kind of approach in a high-concurrency environment + usually use versioned data to ensure isolation for the "long" unit of work. + </para> + + <para> + Hibernate supports this model by providing for reattachment of detached instances + using the <literal>Session.update()</literal> or <literal>Session.merge()</literal> + methods: + </para> + + <programlisting><![CDATA[// in the first session +Cat cat = (Cat) firstSession.load(Cat.class, catId); +Cat potentialMate = new Cat(); +firstSession.save(potentialMate); + +// in a higher layer of the application +cat.setMate(potentialMate); + +// later, in a new session +secondSession.update(cat); // update cat +secondSession.update(mate); // update mate]]></programlisting> + + <para> + If the <literal>Cat</literal> with identifier <literal>catId</literal> had already + been loaded by <literal>secondSession</literal> when the application tried to + reattach it, an exception would have been thrown. + </para> + + <para> + Use <literal>update()</literal> if you are sure that the session does + not contain an already persistent instance with the same identifier, and + <literal>merge()</literal> if you want to merge your modifications at any time + without consideration of the state of the session. In other words, <literal>update()</literal> + is usually the first method you would call in a fresh session, ensuring that + reattachment of your detached instances is the first operation that is executed. + </para> + + <para> + The application should individually <literal>update()</literal> detached instances + reachable from the given detached instance if and <emphasis>only</emphasis> if it wants + their state also updated. This can be automated of course, using <emphasis>transitive + persistence</emphasis>, see <xref linkend="objectstate-transitive"/>. + </para> + + <para> + The <literal>lock()</literal> method also allows an application to reassociate + an object with a new session. However, the detached instance has to be unmodified! + </para> + + <programlisting><![CDATA[//just reassociate: +sess.lock(fritz, LockMode.NONE); +//do a version check, then reassociate: +sess.lock(izi, LockMode.READ); +//do a version check, using SELECT ... FOR UPDATE, then reassociate: +sess.lock(pk, LockMode.UPGRADE);]]></programlisting> + + <para> + Note that <literal>lock()</literal> can be used with various + <literal>LockMode</literal>s, see the API documentation and the + chapter on transaction handling for more information. Reattachment is not + the only usecase for <literal>lock()</literal>. + </para> + + <para> + Other models for long units of work are discussed in <xref linkend="transactions-optimistic"/>. + </para> + + </sect1> + + <sect1 id="objectstate-saveorupdate"> + <title>Automatic state detection</title> + + <para> + Hibernate users have requested a general purpose method that either saves a + transient instance by generating a new identifier or updates/reattaches + the detached instances associated with its current identifier. + The <literal>saveOrUpdate()</literal> method implements this functionality. + </para> + + <programlisting><![CDATA[// in the first session +Cat cat = (Cat) firstSession.load(Cat.class, catID); + +// in a higher tier of the application +Cat mate = new Cat(); +cat.setMate(mate); + +// later, in a new session +secondSession.saveOrUpdate(cat); // update existing state (cat has a non-null id) +secondSession.saveOrUpdate(mate); // save the new instance (mate has a null id)]]></programlisting> + + <para> + The usage and semantics of <literal>saveOrUpdate()</literal> seems to be confusing + for new users. Firstly, so long as you are not trying to use instances from one session + in another new session, you should not need to use <literal>update()</literal>, + <literal>saveOrUpdate()</literal>, or <literal>merge()</literal>. Some whole + applications will never use either of these methods. + </para> + + <para> + Usually <literal>update()</literal> or <literal>saveOrUpdate()</literal> are used in + the following scenario: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + the application loads an object in the first session + </para> + </listitem> + <listitem> + <para> + the object is passed up to the UI tier + </para> + </listitem> + <listitem> + <para> + some modifications are made to the object + </para> + </listitem> + <listitem> + <para> + the object is passed back down to the business logic tier + </para> + </listitem> + <listitem> + <para> + the application persists these modifications by calling + <literal>update()</literal> in a second session + </para> + </listitem> + </itemizedlist> + + <para> + <literal>saveOrUpdate()</literal> does the following: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + if the object is already persistent in this session, do nothing + </para> + </listitem> + <listitem> + <para> + if another object associated with the session has the same identifier, + throw an exception + </para> + </listitem> + <listitem> + <para> + if the object has no identifier property, <literal>save()</literal> it + </para> + </listitem> + <listitem> + <para> + if the object's identifier has the value assigned to a newly instantiated + object, <literal>save()</literal> it + </para> + </listitem> + <listitem> + <para> + if the object is versioned (by a <literal>&lt;version&gt;</literal> or + <literal>&lt;timestamp&gt;</literal>), and the version property value + is the same value assigned to a newly instantiated object, + <literal>save()</literal> it + </para> + </listitem> + <listitem> + <para> + otherwise <literal>update()</literal> the object + </para> + </listitem> + </itemizedlist> + + <para> + and <literal>merge()</literal> is very different: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + if there is a persistent instance with the same identifier currently + associated with the session, copy the state of the given object onto + the persistent instance + </para> + </listitem> + <listitem> + <para> + if there is no persistent instance currently associated with the session, + try to load it from the database, or create a new persistent instance + </para> + </listitem> + <listitem> + <para> + the persistent instance is returned + </para> + </listitem> + <listitem> + <para> + the given instance does not become associated with the session, it + remains detached + </para> + </listitem> + </itemizedlist> + + </sect1> + + <sect1 id="objectstate-deleting" revision="1"> + <title>Deleting persistent objects</title> + + <para> + <literal>Session.delete()</literal> will remove an object's state from the database. + Of course, your application might still hold a reference to a deleted object. + It's best to think of <literal>delete()</literal> as making a persistent instance + transient. + </para> + + <programlisting><![CDATA[sess.delete(cat);]]></programlisting> + + <para> + You may delete objects in any order you like, without risk of foreign key + constraint violations. It is still possible to violate a <literal>NOT + NULL</literal> constraint on a foreign key column by deleting objects in + the wrong order, e.g. if you delete the parent, but forget to delete the + children. + </para> + + </sect1> + + <sect1 id="objectstate-replicating" revision="1"> + <title>Replicating object between two different datastores</title> + + <para> + It is occasionally useful to be able to take a graph of persistent instances + and make them persistent in a different datastore, without regenerating identifier + values. + </para> + + <programlisting><![CDATA[//retrieve a cat from one database +Session session1 = factory1.openSession(); +Transaction tx1 = session1.beginTransaction(); +Cat cat = session1.get(Cat.class, catId); +tx1.commit(); +session1.close(); + +//reconcile with a second database +Session session2 = factory2.openSession(); +Transaction tx2 = session2.beginTransaction(); +session2.replicate(cat, ReplicationMode.LATEST_VERSION); +tx2.commit(); +session2.close();]]></programlisting> + + <para> + The <literal>ReplicationMode</literal> determines how <literal>replicate()</literal> + will deal with conflicts with existing rows in the database. + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>ReplicationMode.IGNORE</literal> - ignore the object when there is + an existing database row with the same identifier + </para> + </listitem> + <listitem> + <para> + <literal>ReplicationMode.OVERWRITE</literal> - overwrite any existing database + row with the same identifier + </para> + </listitem> + <listitem> + <para> + <literal>ReplicationMode.EXCEPTION</literal> - throw an exception if there is + an existing database row with the same identifier + </para> + </listitem> + <listitem> + <para> + <literal>ReplicationMode.LATEST_VERSION</literal> - overwrite the row if its + version number is earlier than the version number of the object, or ignore + the object otherwise + </para> + </listitem> + </itemizedlist> + + <para> + Usecases for this feature include reconciling data entered into different database + instances, upgrading system configuration information during product upgrades, + rolling back changes made during non-ACID transactions and more. + </para> + + </sect1> + + <sect1 id="objectstate-flushing"> + <title>Flushing the Session</title> + + <para> + From time to time the <literal>Session</literal> will execute the SQL statements + needed to synchronize the JDBC connection's state with the state of objects held in + memory. This process, <emphasis>flush</emphasis>, occurs by default at the following + points + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + before some query executions + </para> + </listitem> + <listitem> + <para> + from <literal>org.hibernate.Transaction.commit()</literal> + </para> + </listitem> + <listitem> + <para> + from <literal>Session.flush()</literal> + </para> + </listitem> + </itemizedlist> + + <para> + The SQL statements are issued in the following order + </para> + + <orderedlist spacing="compact"> + <listitem> + <para> + all entity insertions, in the same order the corresponding objects + were saved using <literal>Session.save()</literal> + </para> + </listitem> + <listitem> + <para> + all entity updates + </para> + </listitem> + <listitem> + <para> + all collection deletions + </para> + </listitem> + <listitem> + <para> + all collection element deletions, updates and insertions + </para> + </listitem> + <listitem> + <para> + all collection insertions + </para> + </listitem> + <listitem> + <para> + all entity deletions, in the same order the corresponding objects + were deleted using <literal>Session.delete()</literal> + </para> + </listitem> + </orderedlist> + + <para> + (An exception is that objects using <literal>native</literal> ID generation are + inserted when they are saved.) + </para> + + <para> + Except when you explicity <literal>flush()</literal>, there are absolutely no + guarantees about <emphasis>when</emphasis> the <literal>Session</literal> executes + the JDBC calls, only the <emphasis>order</emphasis> in which they are executed. + However, Hibernate does guarantee that the <literal>Query.list(..)</literal> + will never return stale data; nor will they return the wrong data. + </para> + + <para> + It is possible to change the default behavior so that flush occurs less frequently. + The <literal>FlushMode</literal> class defines three different modes: only flush + at commit time (and only when the Hibernate <literal>Transaction</literal> API + is used), flush automatically using the explained routine, or never flush unless + <literal>flush()</literal> is called explicitly. The last mode is useful for long running + units of work, where a <literal>Session</literal> is kept open and disconnected for + a long time (see <xref linkend="transactions-optimistic-longsession"/>). + </para> + + <programlisting><![CDATA[sess = sf.openSession(); +Transaction tx = sess.beginTransaction(); +sess.setFlushMode(FlushMode.COMMIT); // allow queries to return stale state + +Cat izi = (Cat) sess.load(Cat.class, id); +izi.setName(iznizi); + +// might return stale data +sess.find("from Cat as cat left outer join cat.kittens kitten"); + +// change to izi is not flushed! +... +tx.commit(); // flush occurs +sess.close();]]></programlisting> + + <para> + During flush, an exception might occur (e.g. if a DML operation violates a constraint). + Since handling exceptions involves some understanding of Hibernate's transactional + behavior, we discuss it in <xref linkend="transactions"/>. + </para> + + </sect1> + + <sect1 id="objectstate-transitive" revision="1"> + <title>Transitive persistence</title> + + <para> + It is quite cumbersome to save, delete, or reattach individual objects, + especially if you deal with a graph of associated objects. A common case is + a parent/child relationship. Consider the following example: + </para> + + <para> + If the children in a parent/child relationship would be value typed (e.g. a collection + of addresses or strings), their life cycle would depend on the parent and no + further action would be required for convenient "cascading" of state changes. + When the parent is saved, the value-typed child objects are saved as + well, when the parent is deleted, the children will be deleted, etc. This + even works for operations such as the removal of a child from the collection; + Hibernate will detect this and, since value-typed objects can't have shared + references, delete the child from the database. + </para> + + <para> + Now consider the same scenario with parent and child objects being entities, + not value-types (e.g. categories and items, or parent and child cats). Entities + have their own life cycle, support shared references (so removing an entity from + the collection does not mean it can be deleted), and there is by default no + cascading of state from one entity to any other associated entities. Hibernate + does not implement <emphasis>persistence by reachability</emphasis> by default. + </para> + + <para> + For each basic operation of the Hibernate session - including <literal>persist(), merge(), + saveOrUpdate(), delete(), lock(), refresh(), evict(), replicate()</literal> - there is a + corresponding cascade style. Respectively, the cascade styles are named <literal>create, + merge, save-update, delete, lock, refresh, evict, replicate</literal>. If you want an + operation to be cascaded along an association, you must indicate that in the mapping + document. For example: + </para> + + <programlisting><![CDATA[<one-to-one name="person" cascade="persist"/>]]></programlisting> + + <para> + Cascade styles my be combined: + </para> + + <programlisting><![CDATA[<one-to-one name="person" cascade="persist,delete,lock"/>]]></programlisting> + + <para> + You may even use <literal>cascade="all"</literal> to specify that <emphasis>all</emphasis> + operations should be cascaded along the association. The default <literal>cascade="none"</literal> + specifies that no operations are to be cascaded. + </para> + + <para> + A special cascade style, <literal>delete-orphan</literal>, applies only to one-to-many + associations, and indicates that the <literal>delete()</literal> operation should + be applied to any child object that is removed from the association. + </para> + + + <para> + Recommendations: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + It doesn't usually make sense to enable cascade on a <literal>&lt;many-to-one&gt;</literal> + or <literal>&lt;many-to-many&gt;</literal> association. Cascade is often useful for + <literal>&lt;one-to-one&gt;</literal> and <literal>&lt;one-to-many&gt;</literal> + associations. + </para> + </listitem> + <listitem> + <para> + If the child object's lifespan is bounded by the lifespan of the parent + object, make it a <emphasis>life cycle object</emphasis> by specifying + <literal>cascade="all,delete-orphan"</literal>. + </para> + </listitem> + <listitem> + <para> + Otherwise, you might not need cascade at all. But if you think that you will often be + working with the parent and children together in the same transaction, and you want to save + yourself some typing, consider using <literal>cascade="persist,merge,save-update"</literal>. + </para> + </listitem> + </itemizedlist> + + <para> + Mapping an association (either a single valued association, or a collection) with + <literal>cascade="all"</literal> marks the association as a + <emphasis>parent/child</emphasis> style relationship where save/update/delete of the + parent results in save/update/delete of the child or children. + </para> + <para> + Futhermore, a mere reference to a child from a persistent parent will result in + save/update of the child. This metaphor is incomplete, however. A child which becomes + unreferenced by its parent is <emphasis>not</emphasis> automatically deleted, except + in the case of a <literal>&lt;one-to-many&gt;</literal> association mapped with + <literal>cascade="delete-orphan"</literal>. The precise semantics of cascading + operations for a parent/child relationship are as follows: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + If a parent is passed to <literal>persist()</literal>, all children are passed to + <literal>persist()</literal> + </para> + </listitem> + <listitem> + <para> + If a parent is passed to <literal>merge()</literal>, all children are passed to + <literal>merge()</literal> + </para> + </listitem> + <listitem> + <para> + If a parent is passed to <literal>save()</literal>, <literal>update()</literal> or + <literal>saveOrUpdate()</literal>, all children are passed to <literal>saveOrUpdate()</literal> + </para> + </listitem> + <listitem> + <para> + If a transient or detached child becomes referenced by a persistent parent, + it is passed to <literal>saveOrUpdate()</literal> + </para> + </listitem> + <listitem> + <para> + If a parent is deleted, all children are passed to <literal>delete()</literal> + </para> + </listitem> + <listitem> + <para> + If a child is dereferenced by a persistent parent, <emphasis>nothing + special happens</emphasis> - the application should explicitly delete + the child if necessary - unless <literal>cascade="delete-orphan"</literal>, + in which case the "orphaned" child is deleted. + </para> + </listitem> + </itemizedlist> + + <para> + Finally, note that cascading of operations can be applied to an object graph at + <emphasis>call time</emphasis> or at <emphasis>flush time</emphasis>. All operations, + if enabled, are cascaded to associated entities reachable when the operation is + executed. However, <literal>save-upate</literal> and <literal>delete-orphan</literal> + are transitive for all associated entities reachable during flush of the + <literal>Session</literal>. + </para> + + </sect1> + + <sect1 id="objectstate-metadata"> + <title>Usando metadados</title> + + <para> + O Hibernate requer um modelo muito rico a nível de metadados de todas as entidades e tipos de + valores. De tempos em tempos, este modelo é muito útil à própria aplicação. Por exemplo, a + aplicação pode usar o metadados do Hibernate que executa um algoritmo "inteligente" que + compreende quais objetos podem ser copiados (por exemplo, tipos de valores mutáveis) ou + não (por exemplo, tipos de valores imutáveis e, possivelmente, entidades associadas). + </para> + <para> + O Hibernate expõe o metadados via interfaces <literal>ClassMetadata</literal> + e <literal>CollectionMetadata</literal> e pela hierarquia <literal>Type</literal>. + Instâncias das interfaces de metadados podem ser obtidas a partir do + <literal>SessionFactory</literal>. + </para> + + <programlisting><![CDATA[Cat fritz = ......; +ClassMetadata catMeta = sessionfactory.getClassMetadata(Cat.class); + +Object[] propertyValues = catMeta.getPropertyValues(fritz); +String[] propertyNames = catMeta.getPropertyNames(); +Type[] propertyTypes = catMeta.getPropertyTypes(); + +// get a Map of all properties which are not collections or associations +Map namedValues = new HashMap(); +for ( int i=0; i<propertyNames.length; i++ ) { + if ( !propertyTypes[i].isEntityType() && !propertyTypes[i].isCollectionType() ) { + namedValues.put( propertyNames[i], propertyValues[i] ); + } +}]]></programlisting> + + </sect1> + +</chapter> + Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/toolset_guide.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/toolset_guide.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/toolset_guide.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/toolset_guide.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,604 @@ +<chapter id="toolsetguide" revision="2"> + <title>Toolset Guide</title> + + <para> + Roundtrip engineering with Hibernate is possible using a set of Eclipse plugins, + commandline tools, as well as Ant tasks. + </para> + + <para> + The <emphasis>Hibernate Tools</emphasis> currently include plugins for the Eclipse + IDE as well as Ant tasks for reverse engineering of existing databases: + </para> + + <itemizedlist> + <listitem><para> + <emphasis>Mapping Editor:</emphasis> An editor for Hibernate XML mapping files, + supporting auto-completion and syntax highlighting. It also supports semantic + auto-completion for class names and property/field names, making it much more versatile than a normal XML editor. + </para></listitem> + <listitem><para> + <emphasis>Console:</emphasis> The console is a new view in Eclipse. In addition to + a tree overview of your console configurations, you also get an interactive view + of your persistent classes and their relationships. The console allows you to + execute HQL queries against your database and browse the result directly in + Eclipse. + </para></listitem> + <listitem><para> + <emphasis>Development Wizards:</emphasis> Several wizards are provided with the + Hibernate Eclipse tools; you can use a wizard to quickly generate Hibernate configuration + (cfg.xml) files, or you may even completely reverse engineer an existing database schema + into POJO source files and Hibernate mapping files. The reverse engineering wizard + supports customizable templates. + </para></listitem> + <listitem><para> + <emphasis>Ant Tasks:</emphasis> + </para></listitem> + + </itemizedlist> + + <para> + Please refer to the <emphasis>Hibernate Tools</emphasis> package and it's documentation + for more information. + </para> + + <para> + However, the Hibernate main package comes bundled with an integrated tool (it can even + be used from "inside" Hibernate on-the-fly): <emphasis>SchemaExport</emphasis> aka + <literal>hbm2ddl</literal>. + </para> + + <sect1 id="toolsetguide-s1" revision="2"> + <title>Automatic schema generation</title> + + <para> + DDL may be generated from your mapping files by a Hibernate utility. The generated + schema includes referential integrity constraints (primary and foreign keys) for + entity and collection tables. Tables and sequences are also created for mapped + identifier generators. + </para> + + <para> + You <emphasis>must</emphasis> specify a SQL <literal>Dialect</literal> via the + <literal>hibernate.dialect</literal> property when using this tool, as DDL + is highly vendor specific. + </para> + + <para> + First, customize your mapping files to improve the generated schema. + </para> + + <sect2 id="toolsetguide-s1-2" revision="3"> + <title>Customizing the schema</title> + + <para> + Many Hibernate mapping elements define optional attributes named <literal>length</literal>, + <literal>precision</literal> and <literal>scale</literal>. You may set the length, precision + and scale of a column with this attribute. + + </para> + + <programlisting><![CDATA[<property name="zip" length="5"/>]]></programlisting> + <programlisting><![CDATA[<property name="balance" precision="12" scale="2"/>]]></programlisting> + + <para> + Some tags also accept a <literal>not-null</literal> attribute (for generating a + <literal>NOT NULL</literal> constraint on table columns) and a <literal>unique</literal> + attribute (for generating <literal>UNIQUE</literal> constraint on table columns). + </para> + + <programlisting><![CDATA[<many-to-one name="bar" column="barId" not-null="true"/>]]></programlisting> + + <programlisting><![CDATA[<element column="serialNumber" type="long" not-null="true" unique="true"/>]]></programlisting> + + <para> + A <literal>unique-key</literal> attribute may be used to group columns in + a single unique key constraint. Currently, the specified value of the + <literal>unique-key</literal> attribute is <emphasis>not</emphasis> used + to name the constraint in the generated DDL, only to group the columns in + the mapping file. + </para> + + <programlisting><![CDATA[<many-to-one name="org" column="orgId" unique-key="OrgEmployeeId"/> +<property name="employeeId" unique-key="OrgEmployee"/>]]></programlisting> + + <para> + An <literal>index</literal> attribute specifies the name of an index that + will be created using the mapped column or columns. Multiple columns may be + grouped into the same index, simply by specifying the same index name. + </para> + + <programlisting><![CDATA[<property name="lastName" index="CustName"/> +<property name="firstName" index="CustName"/>]]></programlisting> + + <para> + A <literal>foreign-key</literal> attribute may be used to override the name + of any generated foreign key constraint. + </para> + + <programlisting><![CDATA[<many-to-one name="bar" column="barId" foreign-key="FKFooBar"/>]]></programlisting> + + <para> + Many mapping elements also accept a child <literal>&lt;column&gt;</literal> element. + This is particularly useful for mapping multi-column types: + </para> + + <programlisting><![CDATA[<property name="name" type="my.customtypes.Name"/> + <column name="last" not-null="true" index="bar_idx" length="30"/> + <column name="first" not-null="true" index="bar_idx" length="20"/> + <column name="initial"/> +</property>]]></programlisting> + + <para> + The <literal>default</literal> attribute lets you specify a default value for + a column (you should assign the same value to the mapped property before + saving a new instance of the mapped class). + </para> + + <programlisting><![CDATA[<property name="credits" type="integer" insert="false"> + <column name="credits" default="10"/> +</property>]]></programlisting> + + <programlisting><![CDATA[<version name="version" type="integer" insert="false"> + <column name="version" default="0"/> +</property>]]></programlisting> + + <para> + The <literal>sql-type</literal> attribute allows the user to override the default + mapping of a Hibernate type to SQL datatype. + </para> + + <programlisting><![CDATA[<property name="balance" type="float"> + <column name="balance" sql-type="decimal(13,3)"/> +</property>]]></programlisting> + + <para> + The <literal>check</literal> attribute allows you to specify a check constraint. + </para> + + <programlisting><![CDATA[<property name="foo" type="integer"> + <column name="foo" check="foo > 10"/> +</property>]]></programlisting> + + <programlisting><![CDATA[<class name="Foo" table="foos" check="bar < 100.0"> + ... + <property name="bar" type="float"/> +</class>]]></programlisting> + + + <table frame="topbot" id="schemattributes-summary" revision="2"> + <title>Summary</title> + <tgroup cols="3"> + <colspec colwidth="1*"/> + <colspec colwidth="1*"/> + <colspec colwidth="2.5*"/> + <thead> + <row> + <entry>Attribute</entry> + <entry>Values</entry> + <entry>Interpretation</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>length</literal></entry> + <entry>number</entry> + <entry>column length</entry> + </row> + <row> + <entry><literal>precision</literal></entry> + <entry>number</entry> + <entry>column decimal precision</entry> + </row> + <row> + <entry><literal>scale</literal></entry> + <entry>number</entry> + <entry>column decimal scale</entry> + </row> + <row> + <entry><literal>not-null</literal></entry> + <entry><literal>true|false</literal></entry> + <entry>specfies that the column should be non-nullable</entry> + </row> + <row> + <entry><literal>unique</literal></entry> + <entry><literal>true|false</literal></entry> + <entry>specifies that the column should have a unique constraint</entry> + </row> + <row> + <entry><literal>index</literal></entry> + <entry><literal>index_name</literal></entry> + <entry>specifies the name of a (multi-column) index</entry> + </row> + <row> + <entry><literal>unique-key</literal></entry> + <entry><literal>unique_key_name</literal></entry> + <entry>specifies the name of a multi-column unique constraint</entry> + </row> + <row> + <entry><literal>foreign-key</literal></entry> + <entry><literal>foreign_key_name</literal></entry> + <entry> + specifies the name of the foreign key constraint generated + for an association, for a <literal>&lt;one-to-one&gt;</literal>, + <literal>&lt;many-to-one&gt;</literal>, <literal>&lt;key&gt;</literal>, + or <literal>&lt;many-to-many&gt;</literal> mapping element. Note that + <literal>inverse="true"</literal> sides will not be considered + by <literal>SchemaExport</literal>. + </entry> + </row> + <row> + <entry><literal>sql-type</literal></entry> + <entry><literal>SQL column type</literal></entry> + <entry> + overrides the default column type (attribute of + <literal>&lt;column&gt;</literal> element only) + </entry> + </row> + <row> + <entry><literal>default</literal></entry> + <entry>SQL expression</entry> + <entry> + specify a default value for the column + </entry> + </row> + <row> + <entry><literal>check</literal></entry> + <entry>SQL expression</entry> + <entry> + create an SQL check constraint on either column or table + </entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + The <literal>&lt;comment&gt;</literal> element allows you to specify comments + for the generated schema. + </para> + + <programlisting><![CDATA[<class name="Customer" table="CurCust"> + <comment>Current customers only</comment> + ... +</class>]]></programlisting> + + <programlisting><![CDATA[<property name="balance"> + <column name="bal"> + <comment>Balance in USD</comment> + </column> +</property>]]></programlisting> + + <para> + This results in a <literal>comment on table</literal> or + <literal>comment on column</literal> statement in the generated + DDL (where supported). + </para> + + </sect2> + + <sect2 id="toolsetguide-s1-3" revision="2"> + <title>Running the tool</title> + + <para> + The <literal>SchemaExport</literal> tool writes a DDL script to standard out and/or + executes the DDL statements. + </para> + + <para> + <literal>java -cp </literal><emphasis>hibernate_classpaths</emphasis> + <literal>org.hibernate.tool.hbm2ddl.SchemaExport</literal> <emphasis>options mapping_files</emphasis> + </para> + + <table frame="topbot"> + <title><literal>SchemaExport</literal> Command Line Options</title> + <tgroup cols="2"> + <colspec colwidth="1.5*"/> + <colspec colwidth="2*"/> + <thead> + <row> + <entry>Option</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>--quiet</literal></entry> + <entry>don't output the script to stdout</entry> + </row> + <row> + <entry><literal>--drop</literal></entry> + <entry>only drop the tables</entry> + </row> + <row> + <entry><literal>--create</literal></entry> + <entry>only create the tables</entry> + </row> + <row> + <entry><literal>--text</literal></entry> + <entry>don't export to the database</entry> + </row> + <row> + <entry><literal>--output=my_schema.ddl</literal></entry> + <entry>output the ddl script to a file</entry> + </row> + <row> + <entry><literal>--naming=eg.MyNamingStrategy</literal></entry> + <entry>select a <literal>NamingStrategy</literal></entry> + </row> + <row> + <entry><literal>--config=hibernate.cfg.xml</literal></entry> + <entry>read Hibernate configuration from an XML file</entry> + </row> + <row> + <entry><literal>--properties=hibernate.properties</literal></entry> + <entry>read database properties from a file</entry> + </row> + <row> + <entry><literal>--format</literal></entry> + <entry>format the generated SQL nicely in the script</entry> + </row> + <row> + <entry><literal>--delimiter=;</literal></entry> + <entry>set an end of line delimiter for the script</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + You may even embed <literal>SchemaExport</literal> in your application: + </para> + + <programlisting><![CDATA[Configuration cfg = ....; +new SchemaExport(cfg).create(false, true);]]></programlisting> + + </sect2> + + <sect2 id="toolsetguide-s1-4"> + <title>Properties</title> + + <para> + Database properties may be specified + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para>as system properties with <literal>-D</literal><emphasis>&lt;property&gt;</emphasis></para> + </listitem> + <listitem> + <para>in <literal>hibernate.properties</literal></para> + </listitem> + <listitem> + <para>in a named properties file with <literal>--properties</literal></para> + </listitem> + </itemizedlist> + + <para> + The needed properties are: + </para> + + <table frame="topbot"> + <title>SchemaExport Connection Properties</title> + <tgroup cols="2"> + <colspec colwidth="1.5*"/> + <colspec colwidth="2*"/> + <thead> + <row> + <entry>Property Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>hibernate.connection.driver_class</literal></entry> + <entry>jdbc driver class</entry> + </row> + <row> + <entry><literal>hibernate.connection.url</literal></entry> + <entry>jdbc url</entry> + </row> + <row> + <entry><literal>hibernate.connection.username</literal></entry> + <entry>database user</entry> + </row> + <row> + <entry><literal>hibernate.connection.password</literal></entry> + <entry>user password</entry> + </row> + <row> + <entry><literal>hibernate.dialect</literal></entry> + <entry>dialect</entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2 id="toolsetguide-s1-5"> + <title>Using Ant</title> + + <para> + You can call <literal>SchemaExport</literal> from your Ant build script: + </para> + + <programlisting><![CDATA[<target name="schemaexport"> + <taskdef name="schemaexport" + classname="org.hibernate.tool.hbm2ddl.SchemaExportTask" + classpathref="class.path"/> + + <schemaexport + properties="hibernate.properties" + quiet="no" + text="no" + drop="no" + delimiter=";" + output="schema-export.sql"> + <fileset dir="src"> + <include name="**/*.hbm.xml"/> + </fileset> + </schemaexport> +</target>]]></programlisting> + + </sect2> + + <sect2 id="toolsetguide-s1-6" revision="2"> + <title>Incremental schema updates</title> + + <para> + The <literal>SchemaUpdate</literal> tool will update an existing schema with "incremental" changes. + Note that <literal>SchemaUpdate</literal> depends heavily upon the JDBC metadata API, so it will + not work with all JDBC drivers. + </para> + + <para> + <literal>java -cp </literal><emphasis>hibernate_classpaths</emphasis> + <literal>org.hibernate.tool.hbm2ddl.SchemaUpdate</literal> <emphasis>options mapping_files</emphasis> + </para> + + <table frame="topbot"> + <title><literal>SchemaUpdate</literal> Command Line Options</title> + <tgroup cols="2"> + <colspec colwidth="1.5*"/> + <colspec colwidth="2*"/> + <thead> + <row> + <entry>Option</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>--quiet</literal></entry> + <entry>don't output the script to stdout</entry> + </row> + <row> + <entry><literal>--text</literal></entry> + <entry>don't export the script to the database</entry> + </row> + <row> + <entry><literal>--naming=eg.MyNamingStrategy</literal></entry> + <entry>select a <literal>NamingStrategy</literal></entry> + </row> + <row> + <entry><literal>--properties=hibernate.properties</literal></entry> + <entry>read database properties from a file</entry> + </row> + <row> + <entry><literal>--config=hibernate.cfg.xml</literal></entry> + <entry>specify a <literal>.cfg.xml</literal> file</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + You may embed <literal>SchemaUpdate</literal> in your application: + </para> + + <programlisting><![CDATA[Configuration cfg = ....; +new SchemaUpdate(cfg).execute(false);]]></programlisting> + + </sect2> + + <sect2 id="toolsetguide-s1-7"> + <title>Using Ant for incremental schema updates</title> + + <para> + You can call <literal>SchemaUpdate</literal> from the Ant script: + </para> + + <programlisting><![CDATA[<target name="schemaupdate"> + <taskdef name="schemaupdate" + classname="org.hibernate.tool.hbm2ddl.SchemaUpdateTask" + classpathref="class.path"/> + + <schemaupdate + properties="hibernate.properties" + quiet="no"> + <fileset dir="src"> + <include name="**/*.hbm.xml"/> + </fileset> + </schemaupdate> +</target>]]></programlisting> + + </sect2> + + <sect2 id="toolsetguide-s1-8" revision="1"> + <title>Schema validation</title> + + <para> + The <literal>SchemaValidator</literal> tool will validate that the existing database schema "matches" + your mapping documents. Note that <literal>SchemaValidator</literal> depends heavily upon the JDBC + metadata API, so it will not work with all JDBC drivers. This tool is extremely useful for testing. + </para> + + <para> + <literal>java -cp </literal><emphasis>hibernate_classpaths</emphasis> + <literal>org.hibernate.tool.hbm2ddl.SchemaValidator</literal> <emphasis>options mapping_files</emphasis> + </para> + + <table frame="topbot"> + <title><literal>SchemaValidator</literal> Command Line Options</title> + <tgroup cols="2"> + <colspec colwidth="1.5*"/> + <colspec colwidth="2*"/> + <thead> + <row> + <entry>Option</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>--naming=eg.MyNamingStrategy</literal></entry> + <entry>select a <literal>NamingStrategy</literal></entry> + </row> + <row> + <entry><literal>--properties=hibernate.properties</literal></entry> + <entry>read database properties from a file</entry> + </row> + <row> + <entry><literal>--config=hibernate.cfg.xml</literal></entry> + <entry>specify a <literal>.cfg.xml</literal> file</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + You may embed <literal>SchemaValidator</literal> in your application: + </para> + + <programlisting><![CDATA[Configuration cfg = ....; +new SchemaValidator(cfg).validate();]]></programlisting> + + </sect2> + + <sect2 id="toolsetguide-s1-9"> + <title>Using Ant for schema validation</title> + + <para> + You can call <literal>SchemaValidator</literal> from the Ant script: + </para> + + <programlisting><![CDATA[<target name="schemavalidate"> + <taskdef name="schemavalidator" + classname="org.hibernate.tool.hbm2ddl.SchemaValidatorTask" + classpathref="class.path"/> + + <schemavalidator + properties="hibernate.properties"> + <fileset dir="src"> + <include name="**/*.hbm.xml"/> + </fileset> + </schemavalidator> +</target>]]></programlisting> + + </sect2> + + </sect1> + +</chapter> + Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/transactions.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/transactions.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/transactions.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/transactions.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,1147 @@ +<chapter id="transactions" revision="2"> + <title>Transações e Concorrência</title> + + <para> + O ponto o mais importante sobre o Hibernate e o controle de concorrência é que é muito + fácil de ser compreendido. O Hibernate usa diretamente conexões de JDBC e recursos de + JTA sem adicionar nenhum comportamento de bloqueio a mais. Nós altamente recomendamos + que você gaste algum tempo com o JDBC, o ANSI e a especificação de isolamento de transação + de seu sistema de gerência da base de dados. + </para> + + <para> + O Hibernate não bloqueia objetos na memória. Sua aplicação pode esperar o comportamento + tal qual definido pelo nível de isolamento de suas transações de banco de dados. + Note que graças ao <literal>Session</literal>, que também é um cache de escopo de + transação, o Hibernate fornece leituras repetíveis para procurar por identificadores + e consultas de entidade (não pesquisas de relatórios que retornam valores escalares). + </para> + + <para> + Além do versionamento para o controle automático de concorrência otimista, o Hibernate + oferece também uma API (menor) para bloqueio pessimista de linhas usando a sintaxe + <literal>SELECT FOR UPDATE</literal>. O controle de concorrência otimista e esta + API são discutidos mais tarde neste capítulo. + </para> + + <para> + Nós começamos a discussão do controle de concorrência no Hibernate com a granularidade + do <literal>Configuration</literal>, <literal>SessionFactory</literal>, e + <literal>Session</literal>, além de transações de base de dados e conversações longas. + </para> + + <sect1 id="transactions-basics" revision="1"> + <title>Session e escopos de transações</title> + + <para> + Um <literal>SessionFactory</literal> é objeto threadsafe compartilhado por + todas as threads da aplicação que consome muitos recursos na sua criação. + É criado uma unica vez no inicio da execução da aplicação a partir da + instância de uma <literal>Configuration</literal>. + </para> + + <para> + Uma <literal>Session</literal> é um objeto de baixo custo de criação, não é threadsafe, + deve ser usado uma vez, para uma única requisição, uma conversação, uma única unidade + do trabalho e então deve ser descartado. Um <literal>Session</literal> não obterá um + JDBC <literal>Connection</literal> (ou um <literal>Datasource</literal>) a menos que + necessite, conseqüentemente não consome nenhum recurso até ser usado. + </para> + + <para> + Para completar, você também tem que pensar sobre as transações de base de dados. + Uma transação tem que ser tão curta quanto possível, para reduzir a disputa pelo + bloqueio na base de dados. Transações longas impedirão que sua aplicação escale a + carga altamente concorrente. Por isso, em um projeto raramente é para manter + uma transação de base de dados aberta durante o tempo que o usuário pensa, + até que a unidade do trabalho esteja completa. + </para> + + <para> + Qual é o escopo de uma unidade de trabalho? Pode uma únicoa <literal>Session</literal> + do Hibernate gerenciar diversas transações ou é esta um o relacionamento um-para-um dos + escopos? Quando deve você abrir e fechar uma <literal>Session</literal> e como você + demarca os limites da transação? + </para> + + <sect2 id="transactions-basics-uow" revision="1"> + <title>Unidade de trabalho</title> + + <para> + Primeiro, não use o antipattern <emphasis>sessão-por-operação</emphasis>, + isto é, não abra e não feche uma <literal>Session</literal> para cada simples chamada + ao banco de de dados em uma única thread! Naturalmente, o mesmo é verdadeiro para + transações. As chamadas a banco de dados em uma aplicação são feitas usando uma + seqüência planejada, elas são agrupadas em unidades de trabalho atômicas. + (Veja que isso também significa que um auto-commit depois de cada sentença SQL é + inútil em uma aplicação, esta modalidade é ideal para o trabalho ad hoc do console + do SQL. O Hibernate impede, ou espera que o servidor de aplicação impessa isso, + o uso da modalidade de auto-commit.) As transações nunca são opcionais, toda a + comunicação com um banco de dados tem que ocorrer dentro de uma transação, não + importa se você vai ler ou escrever dados. Como explicado, o comportamento auto-commit + para leitura de dados deve ser evitado, como muitas transações pequenas são + improváveis de executar melhor do que uma unidade claramente definida do trabalho. A + última opção também muito mais manutenível e extensível. + </para> + + <para> + O pattern mais comum em uma aplicação multi-usuário cliente/servidor é + <emphasis>sessão-por-requisição</emphasis>. Neste modelo, uma requisição do cliente é + enviada ao servidor (onde a camada de persistência do Hibernate roda), uma + <literal>Session</literal> nova do Hibernate é aberta, e todas as operações da base de + dados são executadas nesta unidade do trabalho. Logo que o trabalho for completado + (e a resposta para o cliente for preparada), a sessão é descarregad e fechada. + Você usaria também uma única transação de base de dados para servir às requisições + dos clientes, começando e commitando-o quando você abre e fecha a <literal>Session</literal>. + O relacionamento entre os dois é um-para-um e este modelo é um ajuste perfeito para muitas + aplicações. + </para> + + <para> + O desafio encontra-se na implementação. O Hibernate fornece gerência integrada da "sessão atual" + para simplificar este pattern. Tudo que você tem que fazer é iniciar uma transação quando uma + requisição tem que ser processada e termina a transação antes que a resposta seja enviada ao + cliente. Você pode fazer onde quiser, soluções comuns são <literal>ServletFilter</literal>, + interceptador AOP com um pointcut (ponto de corte) nos métodos de serviço ou em um + container de proxy/interceptação. Um container de EJB é uma maneira padronizada para + implementar aspectos cross-cutting tais como a demarcação da transação em EJB session beans, + declarativamente com CMT. Se você se decidir usar demarcação programática de transação, + de preferencia a API <literal>Transaction</literal> do Hibernate mostrada mais adiante neste + capítulo, para fácilidade no uso e portabilidade de código. + </para> + + <para> + Seu código de aplicação pode acessar a "sessão atual" para processar a requisição + fazendo uma chamada simples a <literal>sessionFactory.getCurrentSession()</literal> em + qualquer lugar e com a frequencia necessária. Você sempre conseguirá uma + <literal>Session</literal> limitada a transação atual. Isto tem que ser configurado + para recurso local ou os ambientes JTA. Veja <xref linkend="architecture-current-session"/>. + </para> + + <para> + Às vezes é conveniente estender o escopo de uma <literal>Session</literal> e de + uma transação do banco de dados até que a "visão esteja renderizada". É especialmente + útil em aplicações servlet que utilizam uma fase de rendenderização separada depois + que a requisição ter sido processada. Estendendo a transação até que renderização da + visão esteja completa é fácil de fazer se você implementar seu próprio interceptador. + Entretanto, não se pode fazer facilmente se você confiar em EJBs com transações + gerenciadas por contêiner, porque uma transação será terminada quando um método de + EJB retornar, antes da renderização de toda visão puder começar. + Veja o website e o fórum do Hibernate para dicas e exemplos em torno deste + pattern <emphasis>Open Session in View</emphasis>. + + </para> + + </sect2> + + <sect2 id="transactions-basics-apptx" revision="1"> + <title>Longas conversações</title> + + <para> + O pattern sessão-por-requisição não é o único conceito útil que você pode usar ao projetar + unidades de trabalho. Muitos processos de negócio requerem uma totalidade de séries de + interações com o usuário intercaladas com acessos a uma base de dados. Em aplicações web + e corporativas não é aceitável para uma transação atrapalhe uma interação do usuário. + Considere o seguinte exemplo: + </para> + + <itemizedlist> + <listitem> + <para> + A primeira tela de um diálogo abre os dados carregado pelo usuário em através de + <literal>Session</literal> e transação particulares. O usuário está livre + modificar os objetos. + </para> + </listitem> + <listitem> + <para> + O usuário clica em "Salvar" após 5 minutos e espera suas modificações serem persistidas; + espera também que ele era a única pessoa que edita esta informação e que nenhuma + modificação conflitante possa ocorrer. + </para> + </listitem> + </itemizedlist> + + <para> + Nós chamamos esta unidade de trabalho, do ponto da visão do usuário, executando uma + longa <emphasis>conversação</emphasis> (ou <emphasis>transação da aplicação</emphasis>). + Há muitas maneiras de você pode implementar em sua aplicação. + + </para> + + <para> + Uma primeira implementação simples pode manter a<literal>Session</literal> e a transação + aberta durante o tempo de interação do usuário, com bloqueios na base de dados para impedir + a modificação concorrente e para garantir o isolamento e a atomicidade. Esse é naturalmente + um anti-pattern, desde que a disputa do bloqueio não permitiria o escalonameneto da + aplicação com o número de usuários concorrentes. + </para> + + <para> + Claramente, nós temos que usar diversas transações para implementar a conversação. + Neste caso, Manter o isolamento dos processos de negócio torna-se responsabilidade + parcial da camada da aplicação. Uma única conversação geralmente usa diversas transações. + Ela será atômica se somente uma destas transações (a última) armazenar os + dados atualizados, todas as outras simplesmente leram os dados (por exemplo em um + diálogo do estilo wizard que mede diversos ciclos de requisição/resposta). Isto é mais + fácil de implementar do que pode parecer, especialmente se você usar as + características do Hibernate: + </para> + + <itemizedlist> + <listitem> + <para> + <emphasis>Versionamento automático</emphasis> - O Hibernate pode fazer o + controle automático de concorrência otimista para você, ele pode + automaticamente detectar se uma modificação concorrente + ocorreu durante o tempo de interação do usuário. Geralmente nós verificamos + somente no fim da conversação. + </para> + </listitem> + <listitem> + <para> + <emphasis>Detached Objects</emphasis>- se você se decidir usar o já discutido + pattern <emphasis>session-per-request</emphasis>, todas as instâncias carregadas + estarão no estado destacado durante o tempo em que o usuário estiver pensando. + O Hibernate permite que você reatache os objetos e persita as modificações, + esse pattern é chamado + <emphasis>session-per-request-with-detached-objects</emphasis>. + É usado versionamento automatico para isolar as modificações concorrentes. + </para> + </listitem> + <listitem> + <para> + <emphasis>Extended (or Long) Session</emphasis> A <literal>Session</literal> + do Hibernate pode ser desligada da conexão básica do JDBC depois que a + transação foi commitada e ser reconectado quando uma nova requisição do + cliente ocorrer. Este pattern é conhecido como + <emphasis>session-per-conversation</emphasis> e faz o reatamento uniforme + desnecessário. Versionamento automático é usado para isolar modificações + concorrentes e a <emphasis>session-per-conversation</emphasis> usualmente + não é permitido para ser nivelado automaticamente, e sim explicitamente. + </para> + </listitem> + </itemizedlist> + + <para> + Ambos <emphasis>session-per-request-with-detached-objects</emphasis> e + <emphasis>session-per-conversation</emphasis> possuem vantagens e desvantagens, + nos discutiremos mais tarde neste capítulo no contexto do controle de + concorrência otimista. + </para> + + </sect2> + + <sect2 id="transactions-basics-identity"> + <title>Considerando a identidade do objeto</title> + + <para> + Uma aplicação pode acessar concorrentemente o mesmo estado persistente em duas + <literal>Session</literal>s diferentes. Entretanto, uma instância de uma classe + persistente nunca é compartilhada entre duas instâncias <literal>Session</literal>. + Por tanto, há duas noções diferentes da identidade: + </para> + + <variablelist spacing="compact"> + <varlistentry> + <term>Identidade da base de dados</term> + <listitem> + <para> + <literal>foo.getId().equals( bar.getId() )</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Identidade da JVM</term> + <listitem> + <para> + <literal>foo==bar</literal> + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Então para os objetos acoplados a um <literal>Session</literal> em <literal>particular </literal> + (isto é no escopo de um <literal>Session</literal>), as duas noções são equivalentes e a + identidade da JVM para a identidade da base de dados é garantida pelo Hibernate. Entretanto, + quando a aplicação pode acessar concorrentemente o "mesmo" objeto do negócio (identidade + persistente) em duas sessões diferentes, as duas instâncias serão realmente "diferentes" + (identidade de JVM). Os conflitos são resolvidos usando (versionamento automático) no + flush/commit, usando abordagem otimista. + + </para> + + <para> + Este caminho deixa o Hibernate e o banco dedados se preocuparem com a concorrência; também + fornece uma escalabilidade melhor, garantindo que a identidade em unidades de trabalho + único-encadeadas não necessite de bloqueio dispendioso ou de outros meios de sincronização. + A aplicação nunca necessita sincronizar qualquer objeto de negócio tão longo que transpasse + uma única thread por <literal>Session</literal>. Dentro de uma <literal>Session</literal> a + aplicação pode usar com segurança o <literal>==</literal> para comparar objetos. + </para> + + <para> + Com tudo, uma aplicação que usa <literal>==</literal> fora de uma <literal>Session</literal>, + pode ver resultados inesperados. Isto pode ocorrer mesmo em alguns lugares inesperados, por + exemplo, se você colocar duas instâncias desacopladas em um mesmo <literal>Set</literal>. + Ambos podem ter a mesma identidade na base de dados (isto é eles representam a mesma linha + em uma tabela), mas a identidade da JVM pela definição não garantida para instâncias em estado + desacoplado. O desenvolvedor tem que sobrescrever os métodos <literal>equals()</literal> e + <literal>hashCode()</literal> em classes persistentes e implementar sua própria noção da + igualdade do objeto. Advertência: nunca use o identificador da base de dados para implementar + a igualdade, use atributos de negócio, uma combinação única, geralmente imutável. O + identificador da base de dados mudará se um objeto transiente passar para o estado persistente. + Se a instância transiente (geralmente junto com instâncias desacopladas) for inserida em um + <literal>Set</literal>, mudar o hashcode quebra o contrato do <literal>Set</literal>. + Atributos para chaves de negócio não têm que ser tão estável quanto às chaves primárias + da base de dados, você somente tem que garantir a estabilidade durante o tempo que + os objetos estiverem no mesmo Set. Veja o website do Hibernate para uma discussão mais + completa sobre o assunto. Note também que esta não é uma caracteristica do Hibernate, + mas simplesmente como a identidade e a igualdade do objeto de Java têm que ser implementadas. + </para> + + </sect2> + + <sect2 id="transactions-basics-issues"> + <title>Edições comuns</title> + + <para> + Nunca use o anti-patterns <emphasis>session-per-user-session</emphasis> ou + <emphasis>session-per-application</emphasis> (naturalmente, há umas exceções raras a + essa regra). Note que algumas das seguintes edições podem também aparecer com patterns + recomendados, certifique-se que tenha compreendido as implicações antes de fazer + uma decisão de projeto: + </para> + + <itemizedlist> + <listitem> + <para> + Uma <literal>Session</literal> não é threadsafe. As coisas que são supostas para trabalhar + concorrentemente, como requisições HTTP, session beans, ou Swing, causarão condições de + disputa se uma instância <literal>Session</literal> for compartilhada. Se você mantiver + sua <literal>Session</literal> do Hibernate em seu <literal>HttpSession</literal> + (discutido mais tarde), você deve considerar sincronizar o acesso a sua sessão do HTTP. + Caso contrário, um usuário que clica em reload várias muito rapidamente pode usar o + mesmo <literal>Session</literal> em duas threads executando concorrentemente. + </para> + </listitem> + <listitem> + <para> + Uma exceção lançada pelo Hibernate significa que você tem que dar rollback na sua + transação no banco de dados e fechar a <literal>Session</literal> imediatamente + (discutido mais tarde em maiores detalhes). Se sua <literal>Session</literal> é + limitado pela aplicação, você tem que parar a aplicação. Dando rollback na + transação no banco de dados não põe seus objetos do negócio em um estado anterior + que estavam no início da transação. Isto significa que o estado da base de dados + e os objetos de negócio perdem a sincronização. Geralmente não é um problema + porque as exceções não são recuperáveis e você tem que iniciar após o + rollback de qualquer maneira. + </para> + </listitem> + <listitem> + <para> + O <literal>Session</literal> guarda em cache cada objeto que está no estado persistente + (guardado e checado para estado "sujo" pelo Hibernate). Isto significa que ele cresce + infinitamente até que você obtenha uma OutOfMemoryException, se você o mantiver aberto + por muito tempo ou simplesmente carregar dados demais. Uma solução é chamar + <literal>clear()</literal> e <literal>evict()</literal> para controlar o cache + da <literal>Session</literal>, mas você deve considerar uma Store Procedure + se precisar de operações que envolvam grande volume de dados. Algumas soluções são + mostradas no <xref linkend="batch"/>. Manter uma <literal>Session</literal> aberta + durante uma sessão do usuário significa também uma probabilidade elevada de se acabar + com dados velhos. + </para> + </listitem> + </itemizedlist> + + </sect2> + + </sect1> + + <sect1 id="transactions-demarcation"> + <title>Demarcação de transações de bancos de dados</title> + + <para> + Os limites de uma transação de banco de dados (ou sistema) são sempre necessários. Nenhuma + comunicação com o banco de dados pode ocorrer fora de uma transação de banco de dados (isto + parece confundir muitos desenvolvedores que estão usados modo auto-commit). Sempre use os + limites desobstruídos da transação, até mesmo para operações somente leitura. Dependendo + de seu nível de isolamento e capacidade da base de dados isto pode não ser requerido, + mas não há nenhum aspecto negativo se você demarca sempre transações explicitamente. + Certamente, uma única transação será melhor executada do que muitas transações pequenas, + até mesmo para dados de leitura. + </para> + + <para> + Uma aplicação do Hibernate pode funcionar em ambientes não gerenciados (isto é aplicações standalone, Web + simples ou Swing) e ambientes gerenciados J2EE. Em um ambiente não gerenciado, o Hibernate é geralmente + responsável pelo seu próprio pool de conexões. O desenvolvedor tem que manualmente ajustar limites das + transaçãos, ou seja, começar, commitar, ou dar rollback nas transações ele mesmo. Um ambiente gerenciado + fornece transações gerenciadas por contêiner (CMT - container-managed transactions), com um conjunto + da transações definido declarativamente em descritores de deployment de EJB session beans, por exemplo. + A demarcação programática é então já não é necessário. + </para> + + <para> + Entretanto, é freqüentemente desejável manter sua camada de persistência portável entre ambientes + de recurso locais não gerenciados e sistemas que podem confiar em JTA, mas usar BMT em vez de CMT. + Em ambos os casos você usaria demarcação de transação programática. O Hibernate oferece uma API + chamada Transaction que traduz dentro do sistema de transação nativa de seu ambiente de deployment. + Esta API é realmente opcional, mas nós encorajamos fortemente seu uso a menos que você estiver + em um CMT session bean. + </para> + + <para> + Geralmente, finalizar um <literal>Session</literal>envolve quatro fases distintas: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + flush da sessão + </para> + </listitem> + <listitem> + <para> + commitar a transação + </para> + </listitem> + <listitem> + <para> + fechar a sessão + </para> + </listitem> + <listitem> + <para> + tratar as exceções + </para> + </listitem> + </itemizedlist> + + <para> + A limpeza da sessão já foi bem discutida, agora nós daremos uma olhada na demarcação da + transação e na manipulação de exceção em ambientes controlados e não controlados. + </para> + + + <sect2 id="transactions-demarcation-nonmanaged" revision="2"> + <title>Ambiente não gerenciado</title> + + <para> + Se uma camada de persistência do Hibernate roda em um ambiente não gerenciado, as conexões + do banco de dados são geralmente tratadas pelos pools de conexões simples + (isto é, não baseados em DataSource) dos quais o Hibernate obtém as conexões assim + que necessita. A maneira de se manipular uma sessão/transação é mais ou menos assim: + </para> + + <programlisting><![CDATA[// Non-managed environment idiom +Session sess = factory.openSession(); +Transaction tx = null; +try { + tx = sess.beginTransaction(); + + // do some work + ... + + tx.commit(); +} +catch (RuntimeException e) { + if (tx != null) tx.rollback(); + throw e; // or display error message +} +finally { + sess.close(); +}]]></programlisting> + + <para> + Você não pode chamar <literal>flush()</literal> do <literal>Session()</literal> + explicitamente - a chamada ao <literal>commit()</literal> dispara automaticamente + a sincronização para a sessão (dependendo do <xref linkend="objectstate-flushing"> + FlushMode</xref>). Uma chamada ao <literal>close()</literal> marca o fim de uma sessão. + A principal implicação do <literal>close()</literal> é que a conexão JDBC será abandonada + pela sessão. Este código Java é portável e funciona em ambientes não gerenciado e de JTA. + </para> + + <para> + Uma solução muito mais flexível é gerência integrada de contexto da "sessão atual" + do Hibernate, como descrito anteriormente: + </para> + + <programlisting><![CDATA[// Non-managed environment idiom with getCurrentSession() +try { + factory.getCurrentSession().beginTransaction(); + + // do some work + ... + + factory.getCurrentSession().getTransaction().commit(); +} +catch (RuntimeException e) { + factory.getCurrentSession().getTransaction().rollback(); + throw e; // or display error message +}]]></programlisting> + + <para> + Você muito provavelmente nunca verá estes fragmentos de código em uma aplicação + regular; as exceções fatais (do sistema) devem sempre ser pegas no "alto". + Ou seja, o código que executa chamadas do Hibernate (na camada de persistência) + e o código que trata <literal>RuntimeException</literal> (e geralmente pode + somente limpar acima e na saída) estão em camadas diferentes. O gerenciamento do + contexto atual feito pelo Hibernate pode significativamente simplificar este + projeto, como tudo que você necessita é do acesso a um <literal>SessionFactory</literal>. + A manipulação de exceção é discutida mais tarde neste capítulo. + </para> + + <para> + Note que você deve selecionar <literal>org.hibernate.transaction.JDBCTransactionFactory</literal> + (que é o padrão) e para o segundo exemplo <literal>"thread"</literal> como seu + <literal>hibernate.current_session_context_class</literal>. + </para> + + </sect2> + + <sect2 id="transactions-demarcation-jta" revision="3"> + <title>Usando JTA</title> + + <para> + Se sua camada de persistência funcionar em um servidor de aplicação (por exemplo, + dentro dos EJB session beans), cada conexão do datasource obtida pelo Hibernate + automaticamente fará parte da transação global de JTA. Você pode também instalar uma + implementação standalone de JTA e usá-la sem EJB. O Hibernate oferece duas estratégias + para a integração de JTA. + </para> + + <para> + Se você usar bean-managed transactions (BMT - transações gerenciadas por bean) o Hibernate dirá + ao servidor de aplicação para começar e para terminar uma transação de BMT se você usar a API + Transaction. Assim, o código de gerência de transação é idêntico ao ambiente não gerenciado. + </para> + + <programlisting><![CDATA[// BMT idiom +Session sess = factory.openSession(); +Transaction tx = null; +try { + tx = sess.beginTransaction(); + + // do some work + ... + + tx.commit(); +} +catch (RuntimeException e) { + if (tx != null) tx.rollback(); + throw e; // or display error message +} +finally { + sess.close(); +}]]></programlisting> + + <para> + Se você quiser usar um <literal>Session</literal> limitada por transação, isto é, + a funcionalidade do <literal>getCurrentSession()</literal> para a propagação fácil + do contexto, você terá que usar diretamente a API JTA <literal>UserTransaction</literal>: + </para> + + <programlisting><![CDATA[// BMT idiom with getCurrentSession() +try { + UserTransaction tx = (UserTransaction)new InitialContext() + .lookup("java:comp/UserTransaction"); + + tx.begin(); + + // Do some work on Session bound to transaction + factory.getCurrentSession().load(...); + factory.getCurrentSession().persist(...); + + tx.commit(); +} +catch (RuntimeException e) { + tx.rollback(); + throw e; // or display error message +}]]></programlisting> + + <para> + Com CMT, a demarcação da transação é feita em descritores de deployment do session beans, + não programaticamente, conseqüentemente, o código é reduzido a: + </para> + + <programlisting><![CDATA[// CMT idiom + Session sess = factory.getCurrentSession(); + + // do some work + ... +]]></programlisting> + + <para> + Em um CMT/EJB mesmo um rollback acontece automaticamente, desde que uma exeção <literal>RuntimeException</literal> + não tratável seja lançada por um método de um session bean que informa ao contêiner ajustar a + transação global ao rollback. <emphasis>Isto significa que você não necessita usar a API + <literal>Transaction</literal> do Hibernate em tudo com BMT ou CMT e você obtém a propagação + automática do Session "atual" limitada à transação.</emphasis> + </para> + + <para> + Veja que você deverá escolher <literal>org.hibernate.transaction.JTATransactionFactory</literal> + se você usar o JTA diretamente (BMT) e <literal>org.hibernate.transaction.CMTTransactionFactory</literal> + em um CMT session bean, quando você configura a fábrica de transação do Hibernate. Lembre-se também de + configurar o <literal>hibernate.transaction.manager_lookup_class</literal>. Além disso, certifique-se + que seu <literal>hibernate.current_session_context_class</literal> ou não é configurado (compatibilidade + com o legado) ou é definido para <literal>"jta"</literal>. + + </para> + + <para> + A operação <literal>getCurrentSession()</literal> tem um aspecto negativo em um ambiente JTA. + Há uma advertência para o uso do método liberado de conexão <literal>after_statement</literal>, + o qual é usado então por padrão. Devido a uma limitação simples da especificação JTA, não é + possível para o Hibernate automaticamente limpar quaisquer instâncias <literal>ScrollableResults</literal> + ou <literal>Iterator</literal> abertas retornadas pelo <literal>scroll()</literal> ou + <literal>iterate()</literal>. Você <emphasis>deve</emphasis> liberar o cursor subjacente da + base de dados chamando <literal>ScrollableResults.close()</literal> ou + <literal>Hibernate.close(Iterator)</literal> explicitamente de um bloco <literal>finally</literal>. + (Claro que a maioria de aplicações podem facilmente evitar o uso do <literal>scroll()</literal> ou + do <literal>iterate()</literal> em todo código provindo do JTA ou do CMT.) + + </para> + + </sect2> + + <sect2 id="transactions-demarcation-exceptions"> + <title>Tratamento de Exceção</title> + + <para> + Se a <literal>Session</literal> levantar uma exceção (incluindo qualquer + <literal>SQLException</literal>), você deve imediatamente dar um rollback + na transação do banco, chamando <literal>Session.close()</literal> e descartando + a instância da <literal>Session</literal>. Certos métodos da <literal>Session</literal> + <literal>não</literal> deixarão a sessão em um estado inconsistente. Nenhuma exceção + lançada pelo Hibernate pode ser recuperada. Certifique-se que a <literal>Session</literal> + será fechada chamando <literal>close()</literal> no bloco <literal>finally</literal>. + </para> + + <para> + A exceção <literal>HibernateException</literal>, a qual envolve a maioria dos erros + que podem ocorrer em uma camada de persistência do Hibernate, é uma exceção unchecked ( + não estava em umas versões mais antigas de Hibernate). Em nossa opinião, nós não devemos + forçar o desenvolvedor a tratar uma exceção irrecuperável em uma camada mais baixa. + Na maioria dos sistemas, as exceções unchecked e fatais são tratadas em um dos primeiros + frames da pilha da chamada do método (isto é, em umas camadas mais elevadas) e uma mensagem + de erro é apresentada ao usuário da aplicação (ou a alguma outra ação apropriada é feita). + Note que Hibernate pode também lançar outras exceções unchecked que não são um + <literal>HibernateException</literal>. Estas, também são, irrecuperáveis e uma ação + apropriada deve ser tomada. + </para> + + <para> + O Hibernate envolve <literal>SQLException</literal>s lançadas ao interagir com a base de dados + em um <literal>JDBCException</literal>. Na realidade, o Hibernate tentará converter a exceção em + em uma sub classe mais significativa da <literal>JDBCException</literal>. A + <literal>SQLException</literal> subjacente está sempre disponível através de + <literal>JDBCException.getCause()</literal>. + </para> + + <para> + O Hibernate converte a <literal>SQLException</literal> em uma sub classe + <literal>JDBCException</literal> apropriada usando <literal>SQLExceptionConverter</literal> + associado ao SessionFactory. Por padrão, o <literal>SQLExceptionConverter</literal> é definido + pelo dialeto configurado; entretanto, é também possível conectar em uma implementação customizada + (veja o javadoc para mais detalhes da classe <literal>SQLExceptionConverterFactory</literal>). + Os subtipos padrão de <literal>JDBCException</literal> são: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>JDBCConnectionException</literal> - indica um erro com a comunicação subjacente de JDBC. + </para> + </listitem> + <listitem> + <para> + <literal>SQLGrammarException</literal> - indica um problema da gramática ou da sintaxe com o SQL emitido. + </para> + </listitem> + <listitem> + <para> + <literal>ConstraintViolationException</literal> - indica algum forma de violação de confinamento de integridade. + </para> + </listitem> + <listitem> + <para> + <literal>LockAcquisitionException</literal> - indica um erro ao adquirir um nível de bloqueio necessário para realizar a operação de requisição. + </para> + </listitem> + <listitem> + <para> + <literal>GenericJDBCException</literal> - uma exceção genérica que não cai em algumas das outras categorias. + </para> + </listitem> + </itemizedlist> + + </sect2> + + <sect2 id="transactions-demarcation-timeout"> + <title>Timeout de Transação</title> + + <para> + Uma característica extremamente importante fornecida por um ambiente + gerenciado como EJB e que nunca é fornecido pelo código não gerenciado é o timeout + de transação. Timeouts de transação asseguram que nenhuma transação possa + reter indefinidamente recursos enquanto não retorna nenhuma resposta ao usuário. + Fora de um ambiente controlado (JTA), o Hibernate não pode fornecer inteiramente + esta funcionalidade. Entretanto, o Hibernate pode afinal controlar as operações + do acesso a dados, assegurando que o nível de deadlocks e queries do banco de + dados com imensos resultados definidos sejam limitados pelo timeout. Em um ambiente + gerenciado, o Hibernate pode delegar o timeout da transação ao JTA. Esta funcionalidade + é abstraída pelo objeto <literal>Transaction</literal> do Hibernate. + </para> + + <programlisting><![CDATA[ +Session sess = factory.openSession(); +try { + //set transaction timeout to 3 seconds + sess.getTransaction().setTimeout(3); + sess.getTransaction().begin(); + + // do some work + ... + + sess.getTransaction().commit() +} +catch (RuntimeException e) { + sess.getTransaction().rollback(); + throw e; // or display error message +} +finally { + sess.close(); +}]]></programlisting> + + <para> + Veja que <literal>setTimeout()</literal> não pode ser chamado em um CMT bean, + onde os timeouts das transações devem ser definidos declarativamente. + </para> + + </sect2> + + </sect1> + + <sect1 id="transactions-optimistic"> + <title>Controle de concorrência otimista</title> + + <para> + O único caminho que é consistente com a elevada concorrência e escalabilidade + é controle de concorrência otimista com versionamento. Checagem de versão usa + número de versão, ou timestamps, para detectar conflitos de atualizações (e para + impedir atualizações perdidas). O Hibernate fornece três caminhos possíveis para + escrever aplicações que usam concorrência otimista. Os casos de uso que nós mostramos + estão no contexto de conversações longas, mas a checagem de versão também tem o + benefício de impedir atualizações perdidas em únicas transações. + </para> + + <sect2 id="transactions-optimistic-manual"> + <title>Checagem de versão da aplicação</title> + + <para> + Em uma implementação sem muita ajuda do Hibernate, cada interação com o banco de dados + ocorre em uma nova <literal>Session</literal> e o desenvolvedor é responsável para + recarregar todas as instâncias persistentes da base de dados antes de manipulá-las. + Este caminho força a aplicação a realizar sua própria checagem de versão para assegurar + a conversação do isolamento da transação. Este caminho é menos eficiente em termos de + acesso ao banco de dados. É a caminho mais similar a EJBs entity. + </para> + + <programlisting><![CDATA[// foo is an instance loaded by a previous Session +session = factory.openSession(); +Transaction t = session.beginTransaction(); + +int oldVersion = foo.getVersion(); +session.load( foo, foo.getKey() ); // load the current state +if ( oldVersion != foo.getVersion() ) throw new StaleObjectStateException(); +foo.setProperty("bar"); + +t.commit(); +session.close();]]></programlisting> + + <para> + A propriedade <literal>version</literal> é mapeada usando <literal>&lt;version&gt;</literal>, + e o Hibernate vai incrementá-lo-á automaticamente durante o flush se a entidade + estiver alterada. + </para> + + <para> + Claro, se você se estiver operando em um ambiente de baixa concorrência de dados + e não requerer a checagem de versão, você pode usar este caminho e apenas saltar a + checagem de versão. Nesse caso, o <emphasis>ultimo commit realizdo </emphasis> é + a estratégia padrão para suas conversações longas. Mantenha em mente que isto pode + confundir os usuários da aplicação, assim como eles podem experimentar atualizações + perdidas sem mensagens de erro ou uma possibilidade ajustar mudanças de conflito. + + </para> + + <para> + Claro que, checagem manual da versão é somente praticável em circunstâncias triviais + e não para a maioria de aplicações. Freqüentemente, os grafos completos de objetos + modificados têm que ser verificados, não somente únicas instâncias. O Hibernate oferece + checagem de versão automática com uma <literal>Session</literal> estendida ou instâncias + desatachadas como o paradigma do projeto. + </para> + + </sect2> + + <sect2 id="transactions-optimistic-longsession"> + <title>Sessão estendida e versionamento automático</title> + + <para> + Uma única instância de <literal>Session</literal> e suas instâncias persistentes + são usadas para a conversação inteira, isto é conhecido como + <emphasis>session-per-conversation</emphasis>. O Hibernate verifica versões da instância + no momento dio flush, lançando uma exceção se a modificação concorrente for detectada. + Até o desenvolvedor pegar e tratar essa exceção (as opções comuns são a oportunidade + para que o usuário intercale as mudanças ou reinicie a conversação do negócio com + dados não antigos). + </para> + + <para> + The <literal>Session</literal> is disconnected from any underlying JDBC connection + when waiting for user interaction. This approach is the most efficient in terms + of database access. The application need not concern itself with version checking or + with reattaching detached instances, nor does it have to reload instances in every + database transaction. + A <literal>Session</literal> é desconectada de toda a conexão JDBC subjacente + enquanto espera a interação do usuário. Este caminho é a mais eficiente em termos + de acesso a bancos de dados. A aplicação não necessita concernir-se com a checagem + de versão ou com as instâncias destacadas reatadas, nem tem que recarregar instâncias + em cada transação. + </para> + + <programlisting><![CDATA[// foo is an instance loaded earlier by the old session +Transaction t = session.beginTransaction(); // Obtain a new JDBC connection, start transaction + +foo.setProperty("bar"); + +session.flush(); // Only for last transaction in conversation +t.commit(); // Also return JDBC connection +session.close(); // Only for last transaction in conversation]]></programlisting> + <para> + O objeto <literal>foo</literal> sabe que <literal>Session</literal> já foi carregada. Começando + uma nova transação em uma sessão velha obtém uma conexão nova e recomeça a sessão. Commitando + uma transação desconecta uma sessão da conexão JDBC e retorna a conexão ao pool. Após a reconexão, + forçar uma checagem de versão em dados que você não está atualizando, você pode chamar + <literal>Session.lock()</literal> com o <literal>LockMode.READ</literal> em todos os objetos + que possam ter sido atualizados por uma outra transação. Você não necessita bloquear nenhum + dado para atualizar. Geralmente você configuraria <literal>FlushMode.MANUAL</literal> em uma + <literal>Session</literal> estendida, de modo que somente o último ciclo da transação tenha + permissão de persistir todas as modificações feitas nesta conversação. Disso, somente esta última + transação incluiria a operação <literal>flush()</literal> e então chamar também <literal>close()</literal> + da sessão para terminar a conversação. + </para> + + <para> + Este pattern é problemático se a <literal>Session</literal> for demasiadamente grande para + ser armazenado durante o tempo que usuário pensar, por exemplo um <literal>HttpSession</literal> + estiver mantido tão pequeno quanto possível. Como o <literal>Session</literal> é também cache + de primeiro nível (imperativo) e contém todos os objetos carregados, nós podemos provavelmente + usar esta estratégia somente para alguns ciclos de requisição/resposta. Você deve usar a + <literal>Session</literal> somente para uma única conversação, porque ela logo também + estará com dados velhos. + </para> + + <para> + (Note que versões mais atuais de Hibernate requerem a desconexão e o reconexão explícitas de + uma <literal>Session</literal>. Estes métodos são desatualizados, como o início e término de + uma transação tem o mesmo efeito.) + </para> + + <para> + Note também que você deve manter a <literal>Session</literal> desconectada fechada + para a camada de persistência. Ou seja, use um EJB stateful session bean para + prender a <literal>Session</literal> em um ambiente do três camadas e não o + transferir à camada web (ou até serializá-lo para uma camada separada) + para armazená-lo no <literal>HttpSession</literal>. + + </para> + + <para> + O pattern sessão estendida, ou <emphasis>session-per-conversation</emphasis>, é mais + difícil de implementar com gerenciamento automático de sessão atual. Você precisa fornecer + sua própria implementação do <literal>CurrentSessionContext</literal> para isto + (veja o Hibernate Wiki para exemplos). + </para> + + </sect2> + + <sect2 id="transactions-optimistic-detached"> + <title>Objetos destacados e versionamento automático</title> + + <para> + Cada interação com o armazenamento persistente ocorre em uma <literal>Session</literal> nova. + Entretanto, as mesmas instâncias persistentes são reusadas para cada interação com o banco de dados. + A aplicação manipula o estado das instâncias desatachadas originalmente carregadas em um outro + <literal>Session</literal> e reata-os então usando <literal>Session.update()</literal>, + <literal>Session.saveOrUpdate()</literal> ou <literal>Session.merge()</literal>. + </para> + + <programlisting><![CDATA[// foo is an instance loaded by a previous Session +foo.setProperty("bar"); +session = factory.openSession(); +Transaction t = session.beginTransaction(); +session.saveOrUpdate(foo); // Use merge() if "foo" might have been loaded already +t.commit(); +session.close();]]></programlisting> + + <para> + Outra vez, o Hibernate verificará versões da instância durante o flush, + lançando uma exceção se ocorrer conflitos de atualizações. + </para> + + <para> + Você pode também chamar o <literal>lock()</literal> em vez de <literal>update()</literal> + e usar <literal>LockMode.READ</literal> (executando uma checagem de versão, ignorando + todos os caches) se você estiver certo de que o objeto não foi modificado. + </para> + + </sect2> + + <sect2 id="transactions-optimistic-customizing"> + <title>Versionamento automático customizado</title> + + <para> + Você pode desabilitar o incremento da versão automática de Hibernate para propriedades + e coleções particulares configurando o mapeamento do atributo <literal>optimistic-lock</literal> + para false. O Hibernate então não irá incrementa versões se a propriedade estiver + modificada. + </para> + + <para> + Os esquemas da base de dados legada são freqüentemente estáticos e não podem ser modificados. + Ou outras aplicações puderam também acessar a mesma base de dados e não sabem tratar a + versão dos números ou timestamps. Em ambos os casos, o versionamento não pode confiar em uma + coluna particular em uma tabela. Para forçar uma checagem de versão sem uma versão ou mapeamento + da propriedade do timestamp com uma comparação do estado de todos os campos em uma linha, + configure <literal>optimistic-lock="all"</literal> no mapeamento <literal>&lt;class&gt;</literal>. + Note que isto conceitualmente é somente feito em trabalhos se Hibernate puder comparar o estado + velho e novo, isto é, se você usa um único <literal>Session</literal> longo e não + session-per-request-with-detached-objects. + </para> + + <para> + Às vezes a modificação concorrente pode ser permitida tão longa quanto às mudanças que + tiveram sido feitas que não sobrepuseram. Se você configurar <literal>optimistic-lock="dirty"</literal> + ao mapear o <literal>&lt;class&gt;</literal>, o Hibernate comparará somente campos + modificados durante o flush. + </para> + + <para> + Em ambos os casos, com as colunas dedicadas da versão/timestamp ou com comparação do + campo cheio/modificados, o Hibernate usa uma única declaração UPDATE (com uma cláusula + WHERE apropriada ) por entidade para executar a checagem da versão e atualizar a informação. + Se você usa a persistência transitiva para cascatear o reatamento das entidades associadas, + o Hibernate pode executar atualizações desnecessárias. Isso não é geralmente um problema, + mas triggers <emphasis>on update</emphasis> em um banco de dados podem ser executados + mesmo quando nenhuma mudança foi feita nas instâncias destacadas. Você pode customizar + este comportamento configurando <literal>select-before-update="true"</literal> no + mapeamento <literal>&lt;class&gt;</literal>, forçando o Hibernate a dá um SELECT nas + instâncias para assegurar-se esse as mudanças ocorreram realmente, antes de atualizar + a linha. + </para> + + </sect2> + + </sect1> + + <sect1 id="transactions-locking"> + <title>Locking pessimista</title> + + <para> + Não se pretende que os usuários gastam muitas horas se preocupando com suas estratégias de + locking. Geralmente é o bastante para especificar um nível de isolamento para as conexões + JDBC e então deixar simplesmente o banco de dados fazer todo o trabalho. Entretanto, os + usuários avançados podem às vezes desejar obter locks pessimistas exclusivos, ou re-obter + locks no início de uma nova transação. + </para> + + <para> + O Hibernate usará sempre o mecanismo de lock da base de dados, nunca trava objetos + na memória! + </para> + + <para> + A classe <literal>LockMode</literal> define os diferentes níveis de lock que o Hibernate + pode adquirir. Um lock é obtido pelos seguintes mecanismos: + + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>LockMode.WRITE</literal> é adquirido automaticamente quando o Hibernate atualiza + ou insere uma linha. + </para> + </listitem> + <listitem> + <para> + <literal>LockMode.UPGRADE</literal> pode ser adquirido explicitamente pelo usuário + usando <literal>SELECT ... FOR UPDATE</literal> em um banco de dados que suporte + esse sintaxe. + </para> + </listitem> + <listitem> + <para> + <literal>LockMode.UPGRADE_NOWAIT</literal> pode ser adquirido explicitamente pelo usuário + usando <literal>SELECT ... FOR UPDATE NOWAIT</literal> no Oracle. + + </para> + </listitem> + <listitem> + <para> + <literal>LockMode.READ</literal> é adquirido automaticamente quando o Hibernate lê + dados em um nível Repeatable Read ou Serializable isolation. Pode ser readquirido + explicitamente pelo usuário. + </para> + </listitem> + <listitem> + <para> + <literal>LockMode.NONE</literal> representa a ausência do lock. Todos os objetos mudam para + esse estado de lock no final da <literal>Transaction</literal>. Objetos associados com a sessão + através do método <literal>update()</literal> ou <literal>saveOrUpdate()</literal> também são + inicializados com esse lock mode. + </para> + </listitem> + </itemizedlist> + + <para> + O lock obtido "explicitamente pelo usuário" se dá em uma das seguintes maneiras: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + Uma chamada a <literal>Session.load()</literal>, especificando + o <literal>LockMode</literal>. + </para> + </listitem> + <listitem> + <para> + Uma chamada a <literal>Session.lock()</literal>. + </para> + </listitem> + <listitem> + <para> + Uma chamada a <literal>Query.setLockMode()</literal>. + </para> + </listitem> + </itemizedlist> + + <para> + Se uma <literal>Session.load()</literal> é invocada com <literal>UPGRADE</literal> ou + <literal>UPGRADE_NOWAIT</literal>, e o objeto requisitado ainda não foi carregado + pela sessão, o objeto é carregado usando <literal>SELECT ... FOR UPDATE</literal>. + Se <literal>load()</literal> for chamado para um objeto que já foi carregado + com um lock menos restritivo que o novo lock solicitado, o Hibernate invoca o + método <literal>lock()</literal> para aquele objeto. + </para> + + <para> + O método <literal>Session.lock()</literal> executa uma verificação no número da versão + se o modo de lock especificado for <literal>READ</literal>, <literal>UPGRADE</literal> ou + <literal>UPGRADE_NOWAIT</literal>.. (No caso do <literal>UPGRADE</literal> ou + <literal>UPGRADE_NOWAIT</literal>, é usado <literal>SELECT ... FOR UPDATE</literal>.) + </para> + + <para> + Se o banco de dados não suportar o lock mode solicitado, o Hibernate vai usar um modo + alternativo apropriado (ao invés de lançar uma exceção). Isso garante que a aplicação + vai ser portável. + </para> + + </sect1> + + <sect1 id="transactions-connection-release"> + <title>Modos de liberar a Connection</title> + + <para> + O comportamento legado do Hibernate (2.x) em consideração ao gerenciamento da conexão + via JDBC fez com que a <literal>Session</literal> precisasse obter uma conexão + quando ela precisasse pela primeira vez e depois manter a conexão enquanto + a sessão não fosse fechada. O Hibernate 3.x introduz a idéia de modos de liberar a + sessão, para informar a sessão a forma como deve manusear a sua conexão JDBC. + Veja que essa discussão só é pertinente para conexões fornecidas com um + <literal>ConnectionProvider</literal> configurado; conexões fornecidas pelo usuário + estão fora do escopo dessa discussão. Os diferentes modos de liberação estão definidos + pelos valores da enumeração + <literal>org.hibernate.ConnectionReleaseMode</literal>: + + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>ON_CLOSE</literal> - essencialmente é o modo legado descrito acima. A sessão + do Hibernate obtêm a conexão quando precisar executar alguma operação JDBC pela + primeira vez e mantem enquanto a conexão não for fechada. + </para> + </listitem> + <listitem> + <para> + <literal>AFTER_TRANSACTION</literal> – informa que a conexão deve ser + liberada após a conclusão de uma <literal>org.hibernate.Transaction</literal>. + </para> + </listitem> + <listitem> + <para> + <literal>AFTER_STATEMENT</literal> (também conhecida com liberação agressiva) – informa + que a conexão deve ser liberada após a execução de cada statement. A liberação agressiva + não ocorre se o statement deixa pra trás algum recurso aberto associado com a sessão + obtida; atualmente, a única situação em que isso é possível é com o uso de + <literal>org.hibernate.ScrollableResults</literal>. + </para> + </listitem> + </itemizedlist> + + <para> + O parâmetro de configuração <literal>hibernate.connection.release_mode</literal> é usado + para especificar qual modo de liberação deve ser usado. Opções disponíveis: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>auto</literal> (padrão) – essa opção delega ao modo de liberação retornado pelo + método <literal>org.hibernate.transaction.TransactionFactory.getDefaultReleaseMode()</literal>. + Para JTATransactionFactory, ele retorna ConnectionReleaseMode.AFTER_STATEMENT; para + JDBCTransactionFactory, ele retorna ConnectionReleaseMode.AFTER_TRANSACTION. + Raramente é uma boa idéia alterar padrão, como frequencia ao se fazer isso temos falhas + que parecem bugs e/ou suposições inválidas no código do usuário. + </para> + </listitem> + <listitem> + <para> + <literal>on_close</literal> - indica o uso da ConnectionReleaseMode.ON_CLOSE. Essa opção + foi deixada para manter a compatibilidade, mas seu uso é fortemente desencorajado. + </para> + </listitem> + <listitem> + <para> + <literal>after_transaction</literal> – indica o uso da ConnectionReleaseMode.AFTER_TRANSACTION. + Essa opção nada deve ser usada com ambientes JTA. Também note que no caso da + ConnectionReleaseMode.AFTER_TRANSACTION, se a sessão foi colocada no modo auto-commit a + conexão vai ser liberada de forma similar ao modo AFTER_STATEMENT. + </para> + </listitem> + <listitem> + <para> + <literal>after_statement</literal> – indica o uso ConnectionReleaseMode.AFTER_STATEMENT. + Adicionalmente, o <literal>ConnectionProvider</literal> configurado é consultado para + verificar se suporta essa configuração ((<literal>supportsAggressiveRelease()</literal>). + Se não suportar, o modo de liberação é redefinido como ConnectionRelease-Mode.AFTER_TRANSACTION. + Essa configuração só é segura em ambientes onde podemos readquirir a mesma conexão JDBC + toda vez que o método <literal>ConnectionProvider.getConnection()</literal> for chamado ou + em um ambiente auto-commit onde não importa se nós recuperamos a mesma conexão. + </para> + </listitem> + </itemizedlist> + + </sect1> + +</chapter> + Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/tutorial.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/tutorial.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/tutorial.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/tutorial.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,1530 @@ +<chapter id="tutorial"> + <title>Introdu&#x00E7;&#x00E3;o ao Hibernate</title> + + <sect1 id="tutorial-intro" revision="1"> + <title>Prefácio</title> + + <para> + Este cap&#x00ED;tulo &#x00E9; um tutorial introdut&#x00F3;rio para novos usuários do Hibernate. N&#x00F3;s iniciaremos com uma simples linha de comando em uma aplica&#x00E7;&#x00E3;o usando uma base de dados em mem&#x00F3;ria tornando isto um passo de fácil de compreender. + </para> + + <para> + Este tutorial &#x00E9; voltado para novos usuários do Hibernate, mas requer um conhecimento de Java e SQL. Este tutorial &#x00E9; baseado no tutorial de Michael Gloegl, as bibliotecas Third Party foram nomeadas para JDK 1.4 e 5.0. Você pode precisar de outras bibliotecas para JDK 1.3. + </para> + + <para> + O código fonte para o tutorial está incluído no diretório da distribuição + <literal>doc/reference/tutorial/</literal>. + </para> + + </sect1> + + <sect1 id="tutorial-firstapp" revision="2"> + <title>Parte 1 – A primeira aplicação Hibernate</title> + + <para> + Primeiro, iremos criar uma simples aplica&#x00E7;&#x00E3;o Hibernate baseada em console. Usaremos uma base de dados Java (HSQL DB), ent&#x00E3;o n&#x00E3;o teremos que instalar nenhum servidor de base de dados. + </para> + + <para> + Vamos supor que precisemos de uma aplica&#x00E7;&#x00E3;o com um banco de dados pequeno que possa armazenar e atender os eventos que queremos, e as informa&#x00E7;&#x00E7;es sobre os hosts destes eventos. + </para> + + <para> + A primeira coisa que devemos fazer &#x00E9; configurar nosso diret&#x00F3;rio de desenvolvimento, + e colocar todas as bibliotecas Java que precisamos dentro dele. Fa&#x00E7;a o download da + distribui&#x00E7;&#x00E3;o do Hibernate no site do Hibernate. Descompacte o pacote e coloque todas + as bibliotecas necessárias encontradas no diret&#x00F3;rio <literal>/lib</literal>, dentro do + diret&#x00F3;rio <literal>/lib</literal> do seu novo projeto. Você deverá ter algo parecido + com isso: + </para> + + <programlisting><![CDATA[. ++lib + antlr.jar + cglib.jar + asm.jar + asm-attrs.jars + commons-collections.jar + commons-logging.jar + hibernate3.jar + jta.jar + dom4j.jar + log4j.jar ]]></programlisting> + + <para> + Esta &#x00E9; a configura&#x00E7;&#x00E3;o m&#x00ED;nima requerida das bibliotecas (observe que tamb&#x00E9;m foi copiado + o hibernate3.jar da pasta principal do Hibernate) para o Hibernate <emphasis>na hora do desenvolvimento</emphasis>. O Hibernate permite que você utilize mais ou menos bibliotecas. + Veja o arquivo <literal>README.txt</literal> no diret&#x00F3;rio <literal>lib/</literal> da distribui&#x00E7;&#x00E3;o + do Hibernate para maiores informa&#x00E7;&#x00E7;es sobre bibliotecas requeridas e opcionais. + (Atualmente, a biblioteca Log4j n&#x00E3;o &#x00E9; requerida, mas &#x00E9; preferida por muitos desenvolvedores.) + </para> + + <para> + Agora, iremos criar uma classe que representa o evento que queremos armazenar na base de dados.. + </para> + + <sect2 id="tutorial-firstapp-firstclass" revision="1"> + <title>A primeira Classe</title> + + <para> + Nossa primeira classe de persistência é uma simples classe JavaBean com algumas propriedades: + </para> + + <programlisting><![CDATA[package events; + +import java.util.Date; + +public class Event { + private Long id; + + private String title; + private Date date; + + public Event() {} + + public Long getId() { + return id; + } + + private void setId(Long id) { + this.id = id; + } + + public Date getDate() { + return date; + } + + public void setDate(Date date) { + this.date = date; + } + + public String getTitle() { + return title; + } + + public void setTitle(String title) { + this.title = title; + } +}]]></programlisting> + + <para> + Você pode ver que esta classe usa o padrão JavaBean para o nomeamento convencional da propriedade getter e dos métodos setter, como também a visibilidade private dos campos. Este é um padrão de projeto recomendado, mas não requerido. O Hibernate pode também acessar campos diretamente, o benefício para os métodos de acesso é a robustez para o Refactoring. O construtor sem argumento é requerido para instanciar um objeto desta classe com a reflexão. + </para> + + <para> + A propriedade <literal>id</literal> mantém um único valor de identificação para um evento + particular. Todas as classes persistentes da entidade (bem como aquelas classes dependentes + de menos importância) precisam de uma propriedade de identificação, caso nós queiramos usar o + conjunto completo de características do Hibernate. De fato, a maioria das aplicações + (esp. aplicações web) precisam destinguir os objetos pelo identificador, então você deverá + considerar esta, uma característica em lugar de uma limitação. Porém, nós normalmente não + manipulamos a identidade de um objeto, consequentemente o método setter deverá ser privado. + O Hibernate somente nomeará os identificadores quando um objeto for salvo. Você pode ver como + o Hibernate pode acessar métodos públicos, privados, e protegidos, como também campos + (públicos, privados, protegidos) diretamente. A escolha está até você, e você pode combinar + isso para adaptar seu projeto de aplicação + </para> + + <para> + O construtor sem argumentos é um requerimento para todas as classes persistentes; + O Hibernate tem que criar para você os objetos usando Java Reflection. O construtor + pode ser privado, porém, a visibilidade do pacote é requerida para a procuração da + geração em tempo de execução e recuperação eficiente dos dados sem a instrumentação + de bytecode + </para> + + <para> + Coloque este fonte Java no diretório chamado <literal>src</literal> na pasta de desenvolvimento, + e em seu pacote correto. O diretório deverá ser parecido como este: + </para> + + <programlisting><![CDATA[. ++lib + <Hibernate and third-party libraries> ++src + +events + Event.java]]></programlisting> + + <para> + No próximo passo, iremos falar sobre as classes de persistência do Hibernate.. + </para> + + </sect2> + + <sect2 id="tutorial-firstapp-mapping" revision="1"> + <title>O mapeamento do arquivo</title> + + <para> + O Hibernate precisa saber como carregar e armazenar objetos da classe de + persistência. Isto será onde o mapeamento do arquivo do Hibernate entrará em + jogo. O arquivo mapeado informa ao Hibernate, qual tabela no banco de dados + ele deverá acessar, e quais as colunas na tabela ele deverá usar. + </para> + + <para> + A estrutura básica de um arquivo de mapeamento é parecida com: + </para> + + <programlisting><![CDATA[<?xml version="1.0"?> +<!DOCTYPE hibernate-mapping PUBLIC + "-//Hibernate/Hibernate Mapping DTD 3.0//EN" + "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"> + +<hibernate-mapping> +[...] +</hibernate-mapping>]]></programlisting> + + <para> + Note que o Hibernate DTD é muito sofisticado. Você pode usar isso para auto-conclusão + no mapeamento XML dos elementos e atributos no seu editor ou IDE. Você também pode + abrir o arquivo DTD no seu editor – é a maneira mais fácil de ter uma visão geral + de todos os elementos e atributos e dos padrões, como também alguns comentários. + Note que o Hibernate não irá carregar o arquivo DTD da web, e sim do diretório + da aplicação (classpath). O arquivo DTD está incluído no <literal>hibernate3.jar</literal> como + também no diretório <literal>src/</literal> da distribuição do Hibernate. + </para> + + <para> + Nós omitiremos a declaração do DTD nos exemplos futuros para encurtar o código. Isto, é claro, não é opcional. + </para> + + <para> + Entre os dois tags <literal>hibernate-mapping</literal>, inclua um elemento <literal>class</literal>. + Todas as classes persistentes da entidade (novamente, poderá haver + mais tarde, dependências sobre as classes que não são classes-primárias + de entidades) necessitam do tal mapeamento, para uma tabela na base + de dados SQL + </para> + + <programlisting><![CDATA[<hibernate-mapping> + + <class name="events.Event" table="EVENTS"> + + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Mais adiante iremos dizer ao Hibernate como fazer para persistir e carregar objetos da classe + <literal>Event</literal> da tabela <literal>EVENTS</literal>, cada instancia representada por + uma coluna na tabela. Agora, continuaremos com o mapeamento de uma única propriedade identificadora + para as chaves primárias da tabela. Além disso, nós não iremos se importar com esta propriedade + identificadora, nós iremos configurar uma estratégia de geração de id’s para uma chave primária + de uma surrogate key: + </para> + + <programlisting><![CDATA[<hibernate-mapping> + + <class name="events.Event" table="EVENTS"> + <id name="id" column="EVENT_ID"> + <generator class="native"/> + </id> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + O elemento <literal>id</literal> é a declaração da propriedade identificadora, + o <literal>name="id"</literal> declara o nome da propriedade Java – + o Hibernate irá usar os métodos getter e setter para acessar a propriedade. + O atributo da coluna informa ao Hibernate qual coluna da tabela <literal>EVENTS</literal> nós + iremos usar como chave primária. O elemento <literal>generator</literal> especifica + a estratégia de geração do identificador, neste caso usaremos <literal>native</literal>, que + escolhe a melhor estratégia dependendo da base de dados (dialeto) configurada. + O Hibernate suporta a base de dados gerada, globalmente única, bem como a atribuição + aos identificadores da aplicação (ou toda estratégia escrita para uma extensão). + </para> + + <para> + Finalmente incluiremos as declarações para as propriedades persistentes da classe + no arquivo mapeado. Por default, nenhuma das propriedades da classe é considerada persistente: + </para> + + <programlisting><![CDATA[ +<hibernate-mapping> + + <class name="events.Event" table="EVENTS"> + <id name="id" column="EVENT_ID"> + <generator class="native"/> + </id> + <property name="date" type="timestamp" column="EVENT_DATE"/> + <property name="title"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Da mesma maneira que com o elemento <literal>id</literal>, o atributo <literal>name</literal> do elemento + <literal>property</literal> informa ao Hibernate qual método getter e setter deverá usar. + Assim, neste caso, o Hibernate irá procurar pelo <literal>getDate()/setDate()</literal>, + como também pelo <literal>getTitle()/setTitle()</literal>. + </para> + + <para> + Porque fazer o mapeamento da propriedade <literal>date</literal> incluído no + atributo <literal>column</literal>, e no title não fazer? + Sem o atributo <literal>column</literal> o Hibernate por padrão usa o nome + da propriedade como o nome da coluna. Isto trabalha muito + bem para o <literal>title</literal>. Entretanto o <literal>date</literal> é uma palavra-chave reservada + na maioria dos bancos de dados, assim nós melhoramos o mapeamentos + disto com um nome diferente. + </para> + + <para> + A próxima coisa interessante é que mapemanto do <literal>title</literal> + também falta o atributo <literal>type</literal>. O tipo que declaramos e o uso nos + arquivos mapeados, não são como você pôde esperar, atributos de dados Java. + Eles não são como os tipos de base de dados SQL. + Esses tipos podem ser chamados de <emphasis>Tipos de mapeamento Hibernate</emphasis>, que são conversores + que podem traduzir tipos de dados do Java para os tipos de dados SQL e vice-versa. + Novamente, o Hibernate irá tentar determinar a conversão correta e mapeará o <literal>type</literal> + próprio, caso o tipo do atributo não estiver presente no mapeamento. + Em alguns casos, esta detecção automática (que usa Reflection sobre as classes Java) + poderá não ter padrão que você espera ou necessita. + Este é o caso com a propriedade <literal>date</literal>. O Hibernate não pode saber se a propriedade + (que é do <literal>java.util.Date</literal>) pode mapear para uma coluna do tipo <literal>date</literal> + do SQL, <literal>timestamp</literal>, ou <literal>time</literal> . + Nós preservamos a informação cheia de datas e horas pelo mapeamento da propriedade com um conversor + <literal>timestamp</literal>. + </para> + + <para> + Este arquivo de mapeamento deve ser salvo como <literal>Event.hbm.xml</literal>, + corretamente no diretório próximo ao arquivo fonte da Classe Java <literal>Event</literal>. + O nomeamento dos arquivos de mapeamento podem ser arbitrários, porém o sufixo + <literal>hbm.xml</literal> é uma convenção da comunidade dos desenvolvedores do Hibernate. + Esta estrutura do diretório deve agora se parecer com isso: + </para> + + <programlisting><![CDATA[. ++lib + <Hibernate and third-party libraries> ++src + +events + Event.java + Event.hbm.xml]]></programlisting> + + <para> + Nós iremos continuar com a configuração principal do Hibernate. + </para> + + </sect2> + + <sect2 id="tutorial-firstapp-configuration" revision="2"> + <title>Configuração do Hibernate</title> + + <para> + Agora nós temos uma classe persistente e este arquivo de mapeamento no lugar. + Está na hora de configurar o Hibernate. Antes de fazermos isso, iremos precisar de uma base de dados. + O HSQL DB, um SQL DBMS feito em java, pode ser baixado através do site do HSQL DB(http://hsqldb.org/). + Atualmente, você só precisa baixar o <literal>hsqldb.jar</literal>. + Coloque este arquivo no diretório da pasta de desenvolvimento <literal>lib/</literal>. + </para> + + <para> + Crie um diretório chamado <literal>data</literal> no diretório root de desenvolvimento – + Isto será onde o HSQL DB irá armazenar arquivos de dados. Agora iremos iniciar o banco de dados + executando <literal>java -classpath ../lib/hsqldb.jar org.hsqldb.Server</literal> neste diretório de dados. + Você pode ver ele iniciando e conectando ao socket TCP/IP, isto será onde nossa aplicação irá se + conectar depois. Se você deseja iniciar uma nova base de dados durante este tutorial, + finalize o HSQL DB(pressionando o <literal>CTRL + C</literal> na janela), delete todos os + arquivos no diretório <literal>data/</literal>, e inicie o HSQL BD novamente. + </para> + + <para> + O Hibernate é uma camada na sua aplicação na qual se conecta com a base de dados, para isso + necessita de informação da conexão. As conexões são feitas através de um pool de conexão JDBC, + na qual teremos que configurar. A distribuição do Hibernate contém diversas ferramentas de pooling + da conexão JDBC de fonte aberta, mas iremos usar o pool de conexão interna para este tutorial. + Note que você tem que copiar a biblioteca necessária em seu classpath e use configurações + diferentes para pooling de conexão caso você deseje utilizar um software de pooling JDBC terceirizado + para qualidade de produção. + </para> + + <para> + Para as configurações do Hibernate, nós podemos usar um arquivo simples <literal>hibernate.properties</literal>, + um arquivo mais ligeiramente sofisticado <literal>hibernate.cfg.xml</literal> ou até mesmo uma + instalação programática completa. A maioria dos usuários preferem utilizar o arquivo de configuração XML + </para> + + <programlisting><![CDATA[<?xml version='1.0' encoding='utf-8'?> +<!DOCTYPE hibernate-configuration PUBLIC + "-//Hibernate/Hibernate Configuration DTD 3.0//EN" + "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd"> + +<hibernate-configuration> + + <session-factory> + + <!-- Database connection settings --> + <property name="connection.driver_class">org.hsqldb.jdbcDriver</property> + <property name="connection.url">jdbc:hsqldb:hsql://localhost</property> + <property name="connection.username">sa</property> + <property name="connection.password"></property> + + <!-- JDBC connection pool (use the built-in) --> + <property name="connection.pool_size">1</property> + + <!-- SQL dialect --> + <property name="dialect">org.hibernate.dialect.HSQLDialect</property> + + <!-- Enable Hibernate's automatic session context management --> + <property name="current_session_context_class">thread</property> + + <!-- Disable the second-level cache --> + <property name="cache.provider_class">org.hibernate.cache.NoCacheProvider</property> + + <!-- Echo all executed SQL to stdout --> + <property name="show_sql">true</property> + + <!-- Drop and re-create the database schema on startup --> + <property name="hbm2ddl.auto">create</property> + + <mapping resource="events/Event.hbm.xml"/> + + </session-factory> + +</hibernate-configuration>]]></programlisting> + + <para> + Note que esta configuração XML usa um diferente DTD. Nós configuraremos + as <literal>SessionFactory</literal> do Hibernate – uma factory global responsável + por uma base de dedados particular. Se você tiver diversas bases de dados, + use diversas configurações <literal>&lt;session-factory&gt;</literal>, geralmente + em diversos arquivos de configuração (para uma partida mais fácil). + </para> + + <para> + As primeiras quatro <literal>propriedades</literal> do elemento contém a configuração + necessária para a conexão ao JDBC. A propriedade <literal>propriedade</literal> dialect + do elemento especifica a variante particular do SQL que o Hibernate gera. + O gerenciamento automático de sessão do Hibernate para contextos de persistência + estará disponível em breve. A opção <literal>hbm2ddl.auto</literal> habilita a geração + automática de schemas da base de dados – diretamente na base de dados. + Isto também pode ser naturalmente desligado (removendo a opção de configuração) ou redirecionando + para um arquivo com ajuda do <literal>SchemaExport</literal> nas tarefas do Ant. + Finalmente, iremos adicionar os arquivos das classes de persistência mapeadas na configuração. + </para> + + <para> + Copie este arquivo no diretório fonte, assim isto irá terminar na raiz (root) do + classpath. O Hibernate automaticamente procura por um arquivo chamado + <literal>hibernate.cfg.xml</literal> na raiz do classpath, no startup. + </para> + + </sect2> + + <sect2 id="tutorial-firstapp-ant" revision="1"> + <title>Construindo com o Ant</title> + + <para> + Nos iremos, agora, construir o tutorial com Ant. Você ira precisar o Ant instalado – + se encontra disponível <ulink url="http://ant.apache.org/bindownload.cgi">na página de download do Ant</ulink>. + Como instalar o Ant, não será abordado aqui. Caso tenha alguma dúvida, por favor, + vá ao <ulink url="http://ant.apache.org/manual/index.html">Ant manual</ulink>. + Depois que tiver instalado o Ant, podemos começar a criar o arquivo de construção <literal>build.xml</literal>. + Este arquivo será chamado de <literal>build.xml</literal> e posto diretamente no diretório de desenvolvimento. + </para> + + <para> + Um arquivo básico de build, se parece com isto: + </para> + + <programlisting><![CDATA[<project name="hibernate-tutorial" default="compile"> + + <property name="sourcedir" value="${basedir}/src"/> + <property name="targetdir" value="${basedir}/bin"/> + <property name="librarydir" value="${basedir}/lib"/> + + <path id="libraries"> + <fileset dir="${librarydir}"> + <include name="*.jar"/> + </fileset> + </path> + + <target name="clean"> + <delete dir="${targetdir}"/> + <mkdir dir="${targetdir}"/> + </target> + + <target name="compile" depends="clean, copy-resources"> + <javac srcdir="${sourcedir}" + destdir="${targetdir}" + classpathref="libraries"/> + </target> + + <target name="copy-resources"> + <copy todir="${targetdir}"> + <fileset dir="${sourcedir}"> + <exclude name="**/*.java"/> + </fileset> + </copy> + </target> + +</project>]]></programlisting> + + <para> + Isto irá avisar ao Ant para adicionar todos os arquivos no diretório lib terminando com + <literal>.jar</literal>, para o classpath usado para compilação. Irá também copiar todos os + arquivos não-java para o diretório alvo (arquivos de configuração, mapeamento). Se você rodar + o ant agora, deverá ter esta saída. + </para> + + <programlisting><![CDATA[C:\hibernateTutorial\>ant +Buildfile: build.xml + +copy-resources: + [copy] Copying 2 files to C:\hibernateTutorial\bin + +compile: + [javac] Compiling 1 source file to C:\hibernateTutorial\bin + +BUILD SUCCESSFUL +Total time: 1 second ]]></programlisting> + + </sect2> + + <sect2 id="tutorial-firstapp-helpers" revision="3"> + <title>Startup and helpers</title> + + <para> + É hora de carregar e arquivar alguns objetos <literal>Event</literal>, mas primeiro + nós temos de completar o setup com algum código de infraestrutura. Este startup + inclui a construção de um objeto <literal>SessionFactory</literal> global e armazenar + isto em algum lugar de fácil acesso para o código da aplicação. + Uma <literal>SessionFactory</literal> pode abrir novas <literal>Session</literal>'s. + Uma <literal>Session</literal> representa uma unidade single-theaded do trabalho, a + <literal>SessionFactory</literal> é um objeto global thread-safe, instanciado uma vez. + </para> + + <para> + Nos iremos criar uma classe de ajuda <literal>HibernateUtil</literal>, que toma + conta do startup e faz acesso a uma <literal>SessionFactory</literal> conveniente. + Vamos dar uma olhada na implementação: + </para> + + <programlisting><![CDATA[package util; + +import org.hibernate.*; +import org.hibernate.cfg.*; + +public class HibernateUtil { + + private static final SessionFactory sessionFactory; + + static { + try { + // Create the SessionFactory from hibernate.cfg.xml + sessionFactory = new Configuration().configure().buildSessionFactory(); + } catch (Throwable ex) { + // Make sure you log the exception, as it might be swallowed + System.err.println("Initial SessionFactory creation failed." + ex); + throw new ExceptionInInitializerError(ex); + } + } + + public static SessionFactory getSessionFactory() { + return sessionFactory; + } + +}]]></programlisting> + + <para> + Esta classe não só produz a global <literal>SessionFactory</literal> no seu static initializer + (chamado uma vez pela JVM quando a classe é carregada), mas também esconde o fato + de que isto usa um static singleton. Ela pode muito bem, enxergar a + <literal>SessionFactory</literal> do JNDI em um application server. + </para> + + <para> + Se você der à <literal>SessionFactory</literal> um nome, no seu arquivo de configuração. + O Hibernate irá, de fato, tentar uni-lo ao JNDI depois que estiver construído. + Para evitar este completamente este código, você também poderia usar JMX deployment + e deixar o contêiner JMX capaz, instanciar e unir um <literal>HibernateService</literal> + no JNDI. Essas opções avançadas são discutidas no documento de referência do Hibernate. + </para> + + <para> + Coloque o <literal>HibernateUtil.java</literal> no diretório de arquivos + de desenvolvimento(source), em um pacote após o <literal>events</literal>: + </para> + + <programlisting><![CDATA[. ++lib + <Hibernate and third-party libraries> ++src + +events + Event.java + Event.hbm.xml + +util + HibernateUtil.java + hibernate.cfg.xml ++data +build.xml]]></programlisting> + + <para> + Novamente, isto deve compilar sem problemas. Finalmente, nós precisamos configurar + um sistema de logging – o Hibernate usa commons logging e deixa você escolher entre o + Log4j e o logging do JDK 1.4 . A maioria dos desenvolvedores preferem o Log4j: copie + <literal>log4j.properties</literal> da distribuição do Hibernate (está no diretório + <literal>etc/</literal>), para seu diretório <literal>src</literal>, + depois vá em hibernate.cfg.xml. Dê uma olhada no exemplo de configuração e mude as + configurações se você quizer ter uma saída mais detalhada. Por default, apenas as + mensagems de startup e shwwn do Hibernate é mostrada no stdout. + </para> + + <para> + O tutorial de infra-estrutura está completo - e nós já estamos preparados para algum + trabalho de verdade com o Hibernate. + </para> + + </sect2> + + <sect2 id="tutorial-firstapp-workingpersistence" revision="4"> + <title>Carregando e salvando objetos</title> + + <para> + Finalmente, nós podemos usar o Hibernate para carregar e armazenar objetos. + Nós escrevemos uma classe <literal>EventManager</literal> com um método main(): + </para> + + <programlisting><![CDATA[package events; +import org.hibernate.Session; + +import java.util.Date; + +import util.HibernateUtil; + +public class EventManager { + + public static void main(String[] args) { + EventManager mgr = new EventManager(); + + if (args[0].equals("store")) { + mgr.createAndStoreEvent("My Event", new Date()); + } + + HibernateUtil.getSessionFactory().close(); + } + + private void createAndStoreEvent(String title, Date theDate) { + + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + + session.beginTransaction(); + + Event theEvent = new Event(); + theEvent.setTitle(title); + theEvent.setDate(theDate); + + session.save(theEvent); + + session.getTransaction().commit(); + } + +}]]></programlisting> + + <para> + Nós criamos um novo objeto <literal>Event</literal>, e passamos para o Hibernate. + O Hibernate sabe como tomar conta do SQL e executa <literal>INSERT</literal>s + no banco de dados. Vamos dar uma olhada na <literal>Session</literal> e no + código <literal>Transaction</literal>-handling antes de executarmos. + </para> + + <para> + Um <literal>Session</literal> é uma unidade simples de trabalho. Por agora nós + iremos pegar coisas simples e assumir uma granularidade de um-pra-um entre uma + <literal>Session</literal> do Hibernate e uma transação de banco de dados. + Para proteger nosso código de um atual sistema subjacente de transação (nesse + caso puro JDBC, mas também poderia rodar com JTA), nos usamos a API + <literal>Transaction</literal>, que está disponível na <literal>Session</literal> do Hibernate. + </para> + + <para> + O que a <literal>sessionFactory.getCurrentSession()</literal> faz? Primeiro, você pode + chamar quantas vezes e de onde quiser, uma vez você recebe sua <literal>SessionFactory</literal> + (fácil graças ao <literal>HibernateUtil</literal>). O método <literal>getCurrentSession()</literal> + sempre retorna a unidade de trabalho "corrente". Lembra de que nós mudamos a opção + de configuração desse mecanismo para thread no <literal>hibernate.cfg.xml</literal>? Daqui em + diante, o escopo da unidade de trabalho corrente é a thread Java + corrente que executa nossa aplicação. Entretanto, esta não é toda a verdade. Uma + <literal>Session</literal> começa quando é primeiramente necessária, quando é feita a + primeira chamada à <literal>getCurrentSession()</literal>. É então limitado pelo Hibernate + para thread corrente. Quando a transação termina, tanto com commit quanto rollback, + o Hibernate também desune a <literal>Session</literal> da thread e fecha isso pra você. + Se você chamar <literal>getCurrentSession()</literal> novamente, você receberá uma nova + <literal>Session</literal> e pode começar uma nova unidade de trabalho. Esse modelo de + programação de limite de thread <emphasis>thread-bound</emphasis>, é o modo mais popular + de se usar o Hibernate. + </para> + + <para> + Dê uma olhada no <xref linkend="transactions"/> para mais informações a + respeito de manipulação de transação e demarcação. Nós também pulamos qualquer + manipulação de erro e rollback no exemplo anterior. + </para> + + <para> + Para executar esta primeira rotina, nos teremos que adicionar um ponto de chamada + para o arquivo de build do Ant: + </para> + + <programlisting><![CDATA[<target name="run" depends="compile"> + <java fork="true" classname="events.EventManager" classpathref="libraries"> + <classpath path="${targetdir}"/> + <arg value="${action}"/> + </java> +</target>]]></programlisting> + + <para> + O valor do argumento <literal>action</literal>, é setado na linha de comando quando chamando esse ponto: + </para> + + <programlisting><![CDATA[C:\hibernateTutorial\>ant run -Daction=store]]></programlisting> + + <para> + Você deverá ver, após a compilação, o startup do Hibernate e, dependendo da sua + configuração, muito log de saída. No final você verá a seguinte linha: + </para> + + <programlisting><![CDATA[[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?)]]></programlisting> + + <para> + Este é o <literal>INSERT</literal> executado pelo Hibernate, os pontos de interrogação + representam parêmetros de união do JDBC. Para ver os valores substituídos, ou para diminuir a + verbalidade do log, check seu l<literal>log4j.properties</literal>. + </para> + + <para> + Agora nós gostaríamos de listar os eventos arquivados, então nós adicionamos uma + opção para o método main: + </para> + + <programlisting><![CDATA[if (args[0].equals("store")) { + mgr.createAndStoreEvent("My Event", new Date()); +} +else if (args[0].equals("list")) { + List events = mgr.listEvents(); + for (int i = 0; i < events.size(); i++) { + Event theEvent = (Event) events.get(i); + System.out.println("Event: " + theEvent.getTitle() + + " Time: " + theEvent.getDate()); + } +}]]></programlisting> + + <para> + Nos também adicionamos um novo <literal>método listEvents()</literal>: + </para> + + <programlisting><![CDATA[private List listEvents() { + + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + + session.beginTransaction(); + + List result = session.createQuery("from Event").list(); + + session.getTransaction().commit(); + + return result; +}]]></programlisting> + + <para> + O que nós fazemos aqui, é usar uma query HQL (Hibernate Query Language), + para carregar todos os objetos <literal>Event</literal> exitentes no banco de dados. + O Hibernate irá gerar o SQL apropriado, enviar para o banco de dados e popular objetos + <literal>Event</literal> com os dados. Você pode criar queries mais complexas com + HQL, claro. + </para> + + <para> + Agora, para executar e testar tudo isso, siga os passos a seguir: + </para> + + <itemizedlist> + <listitem> + <para> + Execute <literal>ant run -Daction=store</literal> para armazenar algo no banco de dados + e, claro, gerar o esquema do banco de dados antes pelo hbm2ddl. + </para> + </listitem> + <listitem> + <para> + Agora desabilite hbm2ddl comentando a propriedade no seu arquivo <literal>hibernate.cfg.xml</literal>. + Normalmente só se deixa habilitado em teste unitários contínuos, mas outra carga de hbm2ddl + pode <emphasis>remover</emphasis> tudo que você já tenha arquivado. Sa configuração + <literal>create</literal>, atualmente são traduzidas para "apague todas as tabelas do esquema, + então recrie todas quando a SessionFactory estiver pronta". + </para> + </listitem> + </itemizedlist> + + <para> + Se você agora chamar o Ant com <literal>-Daction=list</literal>, você deverá ver os + eventos que você acabou de criar. Você pode também chamar a ação <literal>store</literal> + mais algumas vezes. + </para> + + <para> + Nota: A maioria dos novos usuários do Hibernate falha nesse ponto e nós regularmente, vemos + questões sobre mensagens de erro de <emphasis>tabela não encontrada </emphasis> . + Entretanto, se você seguir os passos marcados acima, você não terá esse problema, + com o hbm2ddl criando o esquema do banco de dados na primeira execução, e restarts + subsequentes da aplicação irão usar este esquema. Se você mudar o mapeamento e/ou + o esquema do banco de dados, terá de re-habilitar o hbm2ddl mais uma vez. + </para> + + </sect2> + + </sect1> + + <sect1 id="tutorial-associations"> + <title>Part 2 - Mapeando associações</title> + + <para> + Nós mapeamos uma classe de entidade de persistência para uma tabela. Agora vamos continuar + e adicionar algumas associações de classe. Primeiro nos iremos adicionar pessoas a nossa aplicação, + e armazenar os eventos de que elas participam. + </para> + + <sect2 id="tutorial-associations-mappinguser" revision="1"> + <title>Mapeando a classe Person</title> + + <para> + O primeiro código da classe <literal>Person</literal> é simples: + </para> + + <programlisting><![CDATA[package events; + +public class Person { + + private Long id; + private int age; + private String firstname; + private String lastname; + + public Person() {} + + // Accessor methods for all properties, private setter for 'id' + +}]]></programlisting> + + <para> + Crie um novo arquivo de mapeamento, chamado <literal>Person.hbm.xml</literal> (não + esqueça a referencia ao DTD no topo) + </para> + + <programlisting><![CDATA[<hibernate-mapping> + + <class name="events.Person" table="PERSON"> + <id name="id" column="PERSON_ID"> + <generator class="native"/> + </id> + <property name="age"/> + <property name="firstname"/> + <property name="lastname"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Finalmente, adicione o novo mapeamento a configuração do Hibernate: + </para> + + <programlisting><![CDATA[<mapping resource="events/Event.hbm.xml"/> +<mapping resource="events/Person.hbm.xml"/>]]></programlisting> + + <para> + Nos iremos agora criar uma associação entre estas duas entidades. Obviamente, + pessoas (Person) podem participar de eventos, e eventos possuem participantes. + As questões de design com que teremos de lidar são: direcionalidade, multiplicidade e + comportamento de coleção. + </para> + + </sect2> + + <sect2 id="tutorial-associations-unidirset" revision="3"> + <title>Uma associação Set-based unidirectional</title> + + <para> + Nos iremos adicionar uma coleção de eventos na classe <literal>Person</literal>. Desse jeito + poderemos navegar pelos eventos de uma pessoa em particular, sem executar uma query explicitamente – + apenas chamando <literal>aPerson.getEvents()</literal>. Nos usaremos uma coleção Java, um + <literal>Set</literal>, porquê a coleção não conterá elementos duplicados e a ordem não é + relevante para nós. + </para> + + <para> + Vamos escrever o código para isto nas classes Java e então mapear: + </para> + + <programlisting><![CDATA[public class Person { + + private Set events = new HashSet(); + + public Set getEvents() { + return events; + } + + public void setEvents(Set events) { + this.events = events; + } +}]]></programlisting> + + <para> + Antes de mapearmos esta associação, pense no outro lado. Claramente, poderíamos apenas fazer isto de + forma unidirecional. Ou poderíamos criar outra coleção no <literal>Event</literal>, se quisermos + ser capaz de navegar bidirecionalmente, i.e. um - <literal>anEvent.getParticipants()</literal>. + Isto não é necessário, de perspectiva funcional. Você poderia sempre executar uma query explicita + que retornasse os participantes de um evento em particular. Esta é uma escolha de design que cabe + a você, mas o que é claro nessa discussão é a multiplicidade da associação: "muitos" valores em ambos + os lados, nós chamamos isto uma associação <emphasis>muitos-para-muitos</emphasis>. Daqui pra frente, + nos usaremos o mapeamento muitos-para-muitos do Hibernate: + </para> + + <programlisting><![CDATA[<class name="events.Person" table="PERSON"> + <id name="id" column="PERSON_ID"> + <generator class="native"/> + </id> + <property name="age"/> + <property name="firstname"/> + <property name="lastname"/> + + <set name="events" table="PERSON_EVENT"> + <key column="PERSON_ID"/> + <many-to-many column="EVENT_ID" class="events.Event"/> + </set> + +</class>]]></programlisting> + + <para> + O Hibernate suporta todo tipo de mapeamento de coleção , sendo um <literal>&lt;set&gt;</literal> mais comum. + Para uma associação muitos-para-muitos (ou relacionamento de entidade <emphasis>n:m</emphasis> ), + uma tabela de associação é necessária. Cada linha nessa tabela representa um link entre uma pessoa e um + evento. O nome da tabela é configurado com o atributo <literal>table</literal> do elemento + <literal>set</literal>. O nome da coluna identificadora na associção, peloo lado da pessoa, + é definido com o elemento <literal>&lt;key&gt;</literal> , o nome da coluna pelo lado dos eventos, + e definido com o atributo <literal>column</literal> do <literal>&lt;many-to-many&gt;</literal>. + Você também precisa dizer para o Hibernate a classe dos objetos na sua coleção (a classe do outro + lado das coleções de referência). + </para> + + <para> + O esquema de mapeamento para o banco de dados está a seguir: + </para> + + <programlisting><![CDATA[ + _____________ __________________ + | | | | _____________ + | EVENTS | | PERSON_EVENT | | | + |_____________| |__________________| | PERSON | + | | | | |_____________| + | *EVENT_ID | <--> | *EVENT_ID | | | + | EVENT_DATE | | *PERSON_ID | <--> | *PERSON_ID | + | TITLE | |__________________| | AGE | + |_____________| | FIRSTNAME | + | LASTNAME | + |_____________| + ]]></programlisting> + + </sect2> + + <sect2 id="tutorial-associations-working" revision="1"> + <title>Trabalhando a associação</title> + + <para> + Vamos trazer juntos algumas pessoas e eventos em um novo método na classe <literal>EventManager</literal>:: + </para> + + <programlisting><![CDATA[private void addPersonToEvent(Long personId, Long eventId) { + + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + session.beginTransaction(); + + Person aPerson = (Person) session.load(Person.class, personId); + Event anEvent = (Event) session.load(Event.class, eventId); + + aPerson.getEvents().add(anEvent); + + session.getTransaction().commit(); +}]]></programlisting> + + <para> + Após carregar um <literal>Person</literal> e um <literal>Event</literal>, simplesmente + modifique a coleção usando os métodos normais de uma coleção. Como você pode ver, não há chamada explícita + para <literal>update()</literal> ou <literal>save()</literal>, o Hibernate detecta automaticamente + que a coleção foi modificada e necessita ser atualizada. Isso é chamado de <emphasis>checagem + suja automática</emphasis>, e você também pode usá-la modificando o nome ou a data de qualquer um dos + seus objetos. Assim que eles estiverem no estado <emphasis>persistent</emphasis>, ou seja, + limitado por uma <literal>Session</literal> do Hibernate em particular (i.e. eles foram carregados ou + salvos dentro de uma unidade de trabalho), o Hibernate monitora qualquer alteração e executa o SQL + em modo de escrita em segundo plano. O processo de sincronização do estado da memória com o banco de + dados, geralmente apenas no final de uma unidade de trabalho, é chamado de <emphasis>flushing</emphasis>. + No nosso código, a unidade de trabalho termina com o commit da transação do banco de dados – + como definido pela opção de configuração da <literal>thread</literal> da classe <literal>CurrentSessionContext</literal>. + </para> + + <para> + Você pode também querer carregar pessoas e eventos em diferentes unidades de trabalho. + Ou você modifica um objeto fora de uma <literal>Session</literal>, quando não se encontra no + estado persistent (se já esteve neste estado anteriormente, chamamos esse estado de + <emphasis>detached</emphasis>). Você pode até mesmo modificar uma coleção quando esta + se encontrar no estado detached. + </para> + + <programlisting><![CDATA[private void addPersonToEvent(Long personId, Long eventId) { + + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + session.beginTransaction(); + + Person aPerson = (Person) session + .createQuery("select p from Person p left join fetch p.events where p.id = :pid") + .setParameter("pid", personId) + .uniqueResult(); // Eager fetch the collection so we can use it detached + + Event anEvent = (Event) session.load(Event.class, eventId); + + session.getTransaction().commit(); + + // End of first unit of work + + aPerson.getEvents().add(anEvent); // aPerson (and its collection) is detached + + // Begin second unit of work + + Session session2 = HibernateUtil.getSessionFactory().getCurrentSession(); + session2.beginTransaction(); + + session2.update(aPerson); // Reattachment of aPerson + + session2.getTransaction().commit(); +}]]></programlisting> + + <para> + A chamada <literal>update</literal> cria um objeto persistent novamente, você poderia + dizer que ele liga o objeto a uma nova unidade de trabalho, assim qualquer modificação + que você faça neste objeto enquanto estiver no estado detached pode ser salvo no banco de dados. + Isso inclui qualquer modificação (adição/exclusão) que você faça em uma coleção da entidade deste objeto. + </para> + + <para> + Bom, isso não foi muito usado na nossa situação, porém, é um importante conceito que você + pode aplicar em seus aplicativos. Agora, complete este exercício adicionando uma nova ação + ao método main( ) da classe <literal>EventManager</literal> e chame-o pela linha de comando. + Se você precisar dos identificadores de uma pessoa ou evento – o método <literal>save()</literal> + retorna estes identificadores (você poderá modificar alguns dos métodos anteriores para retornar aquele + identificador): + </para> + + <programlisting><![CDATA[else if (args[0].equals("addpersontoevent")) { + Long eventId = mgr.createAndStoreEvent("My Event", new Date()); + Long personId = mgr.createAndStorePerson("Foo", "Bar"); + mgr.addPersonToEvent(personId, eventId); + System.out.println("Added person " + personId + " to event " + eventId);]]></programlisting> + + <para> + Este foi um exemplo de uma associação entre duas classes igualmente importantes, duas entidades. + Como mencionado anteriormente, há outras classes e tipos dentro de um modelo típico, + geralmente "menos importante". Alguns você já viu, como um <literal>int</literal> ou uma <literal>String</literal>. + Nós chamamos essas classes de <emphasis>value types</emphasis>, e suas instâncias <emphasis>depend</emphasis> + de uma entidade particular. As instâncias desses tipos não possuem sua própria identidade, nem são + compartilhados entre entidades (duas pessoas não referenciam o mesmo objeto <literal>firstname</literal> + mesmo se elas tiverem o mesmo objeto firstname). Naturalmente, os value types não são apenas encontrados + dentro da JDK (de fato, em um aplicativo Hibernate todas as classes JDK são consideradas como value types), + mas você pode também criar suas classes como, por exemplo, <literal>Address</literal> ou <literal>MonetaryAmount</literal>. + + </para> + + <para> + Você também pode criar uma coleção de value types. Isso é conceitualmente muito diferente + de uma coleção de referências para outras entidades, mas em Java parece ser quase a mesma coisa. + </para> + + </sect2> + + <sect2 id="tutorial-associations-valuecollections"> + <title>Coleção de valores</title> + + <para> + Nós adicionamos uma coleção de objetos de tipo de valores à entidade <literal>Person</literal>. + Nós querermos armazenar endereços de e-mail, para isso utilizamos o tipo <literal>String</literal>, + e a coleção novamente será um <literal>Set</literal>: + </para> + <programlisting><![CDATA[private Set emailAddresses = new HashSet(); + +public Set getEmailAddresses() { + return emailAddresses; +} + +public void setEmailAddresses(Set emailAddresses) { + this.emailAddresses = emailAddresses; +}]]></programlisting> + + <para> + O mapeamento deste <literal>Set</literal>: + </para> + + <programlisting><![CDATA[<set name="emailAddresses" table="PERSON_EMAIL_ADDR"> + <key column="PERSON_ID"/> + <element type="string" column="EMAIL_ADDR"/> +</set>]]></programlisting> + + <para> + A diferença comparada com o mapeamento anterior se encontra na parte <literal>element</literal>, + que indica ao Hibernate que a coleção não contém referências à outra entidade, mas uma coleção de + elementos do tipo <literal>String</literal> (a tag name em miniscula indica que se trata de um + mapeamento do Hibernate para conversão de tipos). Mais uma vez, o atributo <literal>table</literal> + do elemento <literal>set</literal> determina o nome da tabela para a coleção. O elemento + <literal>key</literal> define o nome da coluna de chave estrangeira na tabela de coleção. + O atributo <literal>column</literal> dentro do elemento <literal>element</literal> define o + nome da coluna onde os valores da <literal>String</literal> serão armazenados. + </para> + + <para> + Dê uma olhada no esquema atualizado: + </para> + + <programlisting><![CDATA[ + _____________ __________________ + | | | | _____________ + | EVENTS | | PERSON_EVENT | | | ___________________ + |_____________| |__________________| | PERSON | | | + | | | | |_____________| | PERSON_EMAIL_ADDR | + | *EVENT_ID | <--> | *EVENT_ID | | | |___________________| + | EVENT_DATE | | *PERSON_ID | <--> | *PERSON_ID | <--> | *PERSON_ID | + | TITLE | |__________________| | AGE | | *EMAIL_ADDR | + |_____________| | FIRSTNAME | |___________________| + | LASTNAME | + |_____________| + ]]></programlisting> + + <para> + Você pode observar que a chave primária da tabela da coleção é de na verdade uma chave composta, + usando ambas colunas. Isso também implica que cada pessoa não pode ter endereços de e-mail + duplicados, o que é exatamente a semântica que precisamos para um set em Java. + </para> + + <para> + Você pode agora tentar adicionar elementos a essa coleção, do mesmo modo que fizemos + anteriormente ligando pessoas e eventos. È o mesmo código em Java: + </para> + + <programlisting><![CDATA[private void addEmailToPerson(Long personId, String emailAddress) { + + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + session.beginTransaction(); + + Person aPerson = (Person) session.load(Person.class, personId); + + // The getEmailAddresses() might trigger a lazy load of the collection + aPerson.getEmailAddresses().add(emailAddress); + + session.getTransaction().commit(); +}]]></programlisting> + + <para> + This time we didnt' use a <emphasis>fetch</emphasis> query to initialize the collection. + Hence, the call to its getter method will trigger an additional select to initialize + it, so we can add an element to it. Monitor the SQL log and try to optimize this with + an eager fetch. + </para> + + </sect2> + + <sect2 id="tutorial-associations-bidirectional" revision="1"> + <title>Associações bidirecionais</title> + + <para> + Agora iremos mapear uma associação bidirecional – fazendo a associação entre pessoas e + eventos, de ambos os lados, em Java. Logicamente, o esquema do banco de dados não muda, + nós continuamos tendo multiplicidades muitos-para-muitos. Um banco de dados é mais flexível do que + uma linguagem de programação para redes, ele não precisa de nenhuma direção de navegação – os + dados podem ser acessados em qualquer caminho possível. + </para> + + <para> + Primeiramente, adicione uma coleção de participantes à classe <literal>Event</literal>: + </para> + + <programlisting><![CDATA[private Set participants = new HashSet(); + +public Set getParticipants() { + return participants; +} + +public void setParticipants(Set participants) { + this.participants = participants; +}]]></programlisting> + + <para> + Agora mapeie este lado da associação em <literal>Event.hbm.xml</literal>. + </para> + + <programlisting><![CDATA[<set name="participants" table="PERSON_EVENT" inverse="true"> + <key column="EVENT_ID"/> + <many-to-many column="PERSON_ID" class="events.Person"/> +</set>]]></programlisting> + + <para> + Como você pode ver, esses é uma mapeamento normal usando <literal>set</literal> em ambos documenentos + de mapeamento. Observe que o nome das colunas em <literal>key</literal> e <literal>many-to-many</literal> + estão trocados em ambos os documentos de mapeamento. A adição mais importante feita está no atributo + <literal>inverse="true"</literal> no elemento set do mapeamento da coleção da classe <literal>Event</literal>. + </para> + + <para> + Isso significa que o Hibernate deve pegar o outro lado – a classe <literal>Person</literal> – + quando necessitar encontrar informação sobre a relação entre as duas entidades. Isso será muito + mais facilmente compreendido quando você analisar como a relação bidirecional entre as entidades é criada. + </para> + + </sect2> + + <sect2 id="tutorial-associations-usingbidir"> + <title>Trabalhando com links bidirecionais</title> + + <para> + Primeiro tenha em mente que o Hibernate não afeta a semântica normal do Java. Como nós criamos + um link entre uma <literal>Person</literal> e um <literal>Event</literal> no exemplo unidirecional? + Nós adicionamos uma instância de <literal>Event</literal>, da coleção de referências de eventos, + a uma instância de <literal>Person</literal>. Então, obviamente, se nós queremos que este link funcione + bidirecionalmente, nós devemos fazer a mesma coisa para o outro lado – adicionando uma referência de + <literal>Person</literal> na coleção de um <literal>Event</literal>. Esse acerto de link de ambos + os lados é absolutamente necessário e você nunca deve esquecer de faze-lo. + </para> + + <para> + Muitos desenvolvedores programam de maneira defensiva e criam métodos + gerenciador de associações que ajusta corretamente ambos os lados: + </para> + + <programlisting><![CDATA[protected Set getEvents() { + return events; +} + +protected void setEvents(Set events) { + this.events = events; +} + +public void addToEvent(Event event) { + this.getEvents().add(event); + event.getParticipants().add(this); +} + +public void removeFromEvent(Event event) { + this.getEvents().remove(event); + event.getParticipants().remove(this); +}]]></programlisting> + + <para> + Observe que os métodos set e get da a coleção estão protegidos – isso permite que classes e + subclasses do mesmo pacote continuem acessando os métodos, mas previne que qualquer outra classe, + que não esteja no mesmo pacote, acesse a coleção diretamente. Você provavelmente deve fazer a mesma + coisa para a coleção do outro lado. + </para> + + <para> + E sobre o mapeamento do atributo <literal>inverse</literal>? Pra você, e para o Java, um link bidirecional + é simplesmente o fato de ajustar corretamente as referências de ambos os lados. O Hibernate, entretanto + não possui informação necessária para corretamente adaptar os estados <literal>INSERT</literal> e + <literal>UPDATE</literal> do SQL, e precisa de ajuda para manipular as propriedades das associações + bidirecionais. Fazer um lado da associação com o atributo <literal>inverse</literal> instrui o Hibernate + para basicamente ignora-lo, considerando-o uma <emphasis>cópia</emphasis> do outro lado. Isso é todo o + necessário para o Hibernate trabalhar com todas as possibilidades quando transformando um modelo de + navegação bidirecional em esquema de banco de dados do SQL. As regras que você possui para lembrar são + diretas: Todas associações bidirecionais necessitam que um lado possua o atributo inverse. Em uma + associação de um-para-muitos, o lado de "muitos" deve conter o atributo <literal>inverse</literal>, + já em uma associação de muitos-para-muitos você pode pegar qualquer lado, não há diferença. + </para> + + </sect2> + + <para> + Agora, vamos portar este exemplo para um pequeno aplicativo para internet. + + </para> + + </sect1> + + <sect1 id="tutorial-webapp"> + <title>EventManager um aplicativo para internet</title> + + <para> + Um aplicativo para internet do Hibernate usa uma <literal>Session</literal> e uma <literal>Transaction</literal> + quase do mesmo modo que um aplicativo standalone. Entretanto, alguns patterns comuns são úteis. + Nós agora criaremos um <literal>EventManagerServlet</literal>. Esse servlet lista todos os eventos + salvos no banco de dados, e cria um formulário HTML para entrada de novos eventos. + </para> + + <sect2 id="tutorial-webapp-servlet" revision="1"> + <title>Criando um servlet básico</title> + + <para> + Crie uma nova classe no seu diretório fonte, no pacote <literal>events</literal>: + </para> + + <programlisting><![CDATA[package events; + +// Imports + +public class EventManagerServlet extends HttpServlet { + + // Servlet code +}]]></programlisting> + + <para> + O servlet manuseia somente requisições <literal>GET</literal> do HTTP, + portanto o método que iremos implementar é <literal>doGet()</literal>: + </para> + + <programlisting><![CDATA[protected void doGet(HttpServletRequest request, + HttpServletResponse response) + throws ServletException, IOException { + + SimpleDateFormat dateFormatter = new SimpleDateFormat("dd.MM.yyyy"); + + try { + // Begin unit of work + HibernateUtil.getSessionFactory() + .getCurrentSession().beginTransaction(); + + // Process request and render page... + + // End unit of work + HibernateUtil.getSessionFactory() + .getCurrentSession().getTransaction().commit(); + + } catch (Exception ex) { + HibernateUtil.getSessionFactory() + .getCurrentSession().getTransaction().rollback(); + throw new ServletException(ex); + } + +}]]></programlisting> + + <para> + O pattern que estamos aplicando neste código é chamado <emphasis>session-per-request</emphasis>. + Quando uma requisição chega ao servlet, uma nova <literal>Session</literal> do Hibernate é + aberta através da primeira chamada para <literal>getCurrentSession()</literal> em + <literal>SessionFactory</literal>. Então uma transação do banco de dados é inicializada - + todo acesso a dados deve ocorrer dentro de uma transação, não importando se o dado é de leitura ou escrita. + (nós não devemos usar o modo auto-commit em aplicações). + + </para> + + <para> + Agora, as possibilidades de ações de uma requisição serão processadas e uma resposta HTML será renderizada. + Nós já iremos chegar nesta parte. + </para> + + <para> + Finalmente, a unidade de trabalho termina quando o processamento e a restituição são completados. + Se ocorrer algum erro durante o processamento ou a restituição, uma exceção será lançada e a + transação do banco de dados encerrada. Isso completa o pattern <literal>session-per-request</literal>. + Em vez de usar código de demarcação de transação em todo servlet você pode também criar um filtro servlet. + Dê uma olhada no site do Hibernate e do Wiki para maiores informações sobre esse pattern, + chamado <emphasis>Open Session in View</emphasis>. + </para> + + </sect2> + + <sect2 id="tutorial-webapp-processing" revision="1"> + <title>Processando e renderizando</title> + + <para> + Vamos implementar o processamento da requisição e a restituição da página HTML. + </para> + +<programlisting><![CDATA[// Write HTML header +PrintWriter out = response.getWriter(); +out.println("<html><head><title>Event Manager</title></head><body>"); + +// Handle actions +if ( "store".equals(request.getParameter("action")) ) { + + String eventTitle = request.getParameter("eventTitle"); + String eventDate = request.getParameter("eventDate"); + + if ( "".equals(eventTitle) || "".equals(eventDate) ) { + out.println("<b><i>Please enter event title and date.</i></b>"); + } else { + createAndStoreEvent(eventTitle, dateFormatter.parse(eventDate)); + out.println("<b><i>Added event.</i></b>"); + } +} + +// Print page +printEventForm(out); +listEvents(out, dateFormatter); + +// Write HTML footer +out.println("</body></html>"); +out.flush(); +out.close();]]></programlisting> + + <para> + O estilo de código acima, misturando linguagem HTML e Java não será funcional em um aplicativo + mais complexo&mdash;tenha em mente que neste manual nós estamos apenas ilustrando conceitos + básicos do Hibernate. O código imprime um cabeçalho HTML e um rodapé. Dentro desta página, + é mostrado um formulário em HTML, para entrada de novos eventos, e uma lista de todos + os eventos contidos no banco de dados. O primeiro método é trivial e apenas imprime + uma página HTML: + </para> + + <programlisting><![CDATA[private void printEventForm(PrintWriter out) { + out.println("<h2>Add new event:</h2>"); + out.println("<form>"); + out.println("Title: <input name='eventTitle' length='50'/><br/>"); + out.println("Date (e.g. 24.12.2009): <input name='eventDate' length='10'/><br/>"); + out.println("<input type='submit' name='action' value='store'/>"); + out.println("</form>"); +}]]></programlisting> + + <para> + O método <literal>listEvents()</literal> usa a <literal>Session</literal> do Hibernate + associada a thread atual para executar um query: + </para> + + <programlisting><![CDATA[private void listEvents(PrintWriter out, SimpleDateFormat dateFormatter) { + + List result = HibernateUtil.getSessionFactory() + .getCurrentSession().createCriteria(Event.class).list(); + if (result.size() > 0) { + out.println("<h2>Events in database:</h2>"); + out.println("<table border='1'>"); + out.println("<tr>"); + out.println("<th>Event title</th>"); + out.println("<th>Event date</th>"); + out.println("</tr>"); + for (Iterator it = result.iterator(); it.hasNext();) { + Event event = (Event) it.next(); + out.println("<tr>"); + out.println("<td>" + event.getTitle() + "</td>"); + out.println("<td>" + dateFormatter.format(event.getDate()) + "</td>"); + out.println("</tr>"); + } + out.println("</table>"); + } +}]]></programlisting> + + <para> + Finalmente, a action <literal>store</literal> é passada pra o método + <literal>createAndStoreEvent()</literal>, que também usa a + <literal>Session</literal> da thread atual: + </para> + + <programlisting><![CDATA[protected void createAndStoreEvent(String title, Date theDate) { + Event theEvent = new Event(); + theEvent.setTitle(title); + theEvent.setDate(theDate); + + HibernateUtil.getSessionFactory() + .getCurrentSession().save(theEvent); +}]]></programlisting> + + <para> + Pronto, o servlet está completo. Uma requisição para o servlet será processada + em uma <literal>Session</literal> e uma <literal>Transaction</literal> simples. + Como anteriormente, no aplicativo standalone, o Hibernate pode automaticamente + associar esses objetos a thread atual em execução. Isso possibilita a liberdade + de você modelar seu código e acessar o método <literal>SessionFactory</literal> + do jeito que achar melhor. Geralmente você irá usar um design mais sofisticado + e mover o código de acesso a dados para dentro de objetos de acesso a dados + (o patter DAO). Leia o Hibernate Wiki para maiores exemplos. + </para> + + </sect2> + + <sect2 id="tutorial-webapp-deploy"> + <title>Instalando e testando</title> + + <para> + Para fazer o deploy desta aplicação você tem que criar um arquivo para web, um WAR. + Adicione o alvo Ant abaixo em seu <literal>build.xml</literal>: + </para> + +<programlisting><![CDATA[<target name="war" depends="compile"> + <war destfile="hibernate-tutorial.war" webxml="web.xml"> + <lib dir="${librarydir}"> + <exclude name="jsdk*.jar"/> + </lib> + + <classes dir="${targetdir}"/> + </war> +</target>]]></programlisting> + + <para> + Esta target cria um arquivo chamado <literal>hibernate-tutorial.war</literal> + no diretório do seu projeto. Ele empacota todas as bibliotecas e o arquivo de + descrição <literal>web.xml</literal>, o qual é esperado no diretório base do seu projeto: + </para> + + <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<web-app version="2.4" + xmlns="http://java.sun.com/xml/ns/j2ee" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"> + + <servlet> + <servlet-name>Event Manager</servlet-name> + <servlet-class>events.EventManagerServlet</servlet-class> + </servlet> + + <servlet-mapping> + <servlet-name>Event Manager</servlet-name> + <url-pattern>/eventmanager</url-pattern> + </servlet-mapping> +</web-app>]]></programlisting> + + <para> + Antes de você compilar e fazer o deploy desta aplicação web, note que uma biblioteca + adicional é requerida: <literal>jsdk.jar</literal>. Esse é o Java servlet development kit, + se você não possui esta biblioteca, faça seu download na página da Sun e copie-a + para seu diretório de bibliotecas. Entretanto, será usado somente para a compilação e + excluído do pacote WAR. + </para> + + <para> + Para compilar e instalar execute <literal>ant war</literal> no seu diretório do projeto + e copie o arquivo <literal>hibernate-tutorial.war</literal> para o diretório + <literal>webapp</literal> do Tomcat. Se você não possui o Tomcat instalado faça + o download e siga as instruções de instalação. Você não precisa modificar + nenhuma configuração do Tomcat para rodar este aplicativo. + </para> + + <para> + Uma vez feito o deploy e com Tomcat rodando, acesse o aplicativo em + <literal>http://localhost:8080/hibernate-tutorial/eventmanager</literal>. + Veja o log do Tomcat para observar a inicialização do Hibernate quando a + primeira requisição chega ao servlet (o inicializador estático dentro de + <literal>HibernateUtil</literal> é chamado) e para ter uma depuração + detalhada se ocorrer alguma exceção. + </para> + + </sect2> + + </sect1> + + <sect1 id="tutorial-summary" revision="1"> + <title>Sumário</title> + + <para> + Este manual cobriu os princípios básicos para criação de uma aplicação simples do Hibernate + e uma pequena aplicação web. + </para> + + <para> + Se você já se sente seguro com o Hibernate, continue navegando na documentação de referência + por tópicos que você acha interessante – os tópicos mais questionados são: + processo de transação (<xref linkend="transactions"/>), uso da API (<xref linkend="objectstate"/>) + e características de consulta (<xref linkend="objectstate-querying"/>). + </para> + + <para> + Não esqueça de visitar o site do Hibernate para obter mais tutoriais especializados. + </para> + + </sect1> + +</chapter> Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/tutorial1.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/tutorial1.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/tutorial1.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/tutorial1.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,1544 @@ +<chapter id="tutorial"> + <title>Introdu&#x00E7;&#x00E3;o ao Hibernate</title> + + <sect1 id="tutorial-intro" revision="1"> + <title>Pref&#x00E1;cio</title> + + <para> + Este cap&#x00ED;tulo &#x00E9; um tutorial introdut&#x00F3;rio para novos usu&#x00E1;rios do Hibernate. N&#x00F3;s iniciaremos com uma simples linha de comando em uma aplica&#x00E7;&#x00E3;o usando uma base de dados em mem&#x00F3;ria tornando isto um passo de f&#x00E1;cil de compreender. + </para> + + <para> + Este tutorial &#x00E9; voltado para novos usu&#x00E1;rios do Hibernate, mas requer um conhecimento de Java e SQL. Este tutorial &#x00E9; baseado no tutorial de Michael Gloegl, as bibliotecas Third Party foram nomeadas para JDK 1.4 e 5.0. Você pode precisar de outras bibliotecas para JDK 1.3. + </para> + + <para> + O código fonte para o tutorial está incluído no diretório da distribuição + <literal>doc/reference/tutorial/</literal>. + </para> + + </sect1> + + <sect1 id="tutorial-firstapp" revision="2"> + <title>Parte 1 – A primeira aplicação Hibernate</title> + + <para> + Primeiro, iremos criar uma simples aplica&#x00E7;&#x00E3;o Hibernate baseada em console. Usaremos uma base de dados Java (HSQL DB), ent&#x00E3;o n&#x00E3;o teremos que instalar nenhum servidor de base de dados. + </para> + + <para> + Vamos supor que precisemos de uma aplica&#x00E7;&#x00E3;o com um banco de dados pequeno que possa armazenar e atender os eventos que queremos, e as informa&#x00E7;&#x00E7;es sobre os hosts destes eventos. + </para> + + <para> + A primeira coisa que devemos fazer &#x00E9; configurar nosso diret&#x00F3;rio de desenvolvimento, + e colocar todas as bibliotecas Java que precisamos dentro dele. Fa&#x00E7;a o download da + distribui&#x00E7;&#x00E3;o do Hibernate no site do Hibernate. Descompacte o pacote e coloque todas + as bibliotecas necess&#x00E1;rias encontradas no diret&#x00F3;rio <literal>/lib</literal>, dentro do + diret&#x00F3;rio <literal>/lib</literal> do seu novo projeto. Você dever&#x00E1; ter algo parecido + com isso: + </para> + + <programlisting><![CDATA[. ++lib + antlr.jar + cglib.jar + asm.jar + asm-attrs.jars + commons-collections.jar + commons-logging.jar + hibernate3.jar + jta.jar + dom4j.jar + log4j.jar ]]></programlisting> + + <para> + Esta &#x00E9; a configura&#x00E7;&#x00E3;o m&#x00ED;nima requerida das bibliotecas (observe que tamb&#x00E9;m foi copiado + o hibernate3.jar da pasta principal do Hibernate) para o Hibernate <emphasis>na hora do desenvolvimento</emphasis>. O Hibernate permite que você utilize mais ou menos bibliotecas. + Veja o arquivo <literal>README.txt</literal> no diret&#x00F3;rio <literal>lib/</literal> da distribui&#x00E7;&#x00E3;o + do Hibernate para maiores informa&#x00E7;&#x00E7;es sobre bibliotecas requeridas e opcionais. + (Atualmente, a biblioteca Log4j n&#x00E3;o &#x00E9; requerida, mas &#x00E9; preferida por muitos desenvolvedores.) + </para> + + <para> + Agora, iremos criar uma classe que representa o evento que queremos armazenar na base de dados.. + </para> + + <sect2 id="tutorial-firstapp-firstclass" revision="1"> + <title>A primeira Classe</title> + + <para> + Nossa primeira classe de persistência é uma simples classe JavaBean com algumas propriedades: + </para> + + <programlisting><![CDATA[package events; + +import java.util.Date; + +public class Event { + private Long id; + + private String title; + private Date date; + + public Event() {} + + public Long getId() { + return id; + } + + private void setId(Long id) { + this.id = id; + } + + public Date getDate() { + return date; + } + + public void setDate(Date date) { + this.date = date; + } + + public String getTitle() { + return title; + } + + public void setTitle(String title) { + this.title = title; + } +}]]></programlisting> + + <para> + Você pode ver que esta classe usa o padrão JavaBean para o nomeamento convencional da propriedade getter e dos métodos setter, como também a visibilidade private dos campos. Este é um padrão de projeto recomendado, mas não requerido. O Hibernate pode também acessar campos diretamente, o benefício para os métodos de acesso é a robustez para o Refactoring. O construtor sem argumento é requerido para instanciar um objeto desta classe com a reflexão. + </para> + + <para> + A propriedade <literal>id</literal> mantém um único valor de identificação para um evento + particular. Todas as classes persistentes da entidade (bem como aquelas classes dependentes + de menos importância) precisam de uma propriedade de identificação, caso nós queiramos usar o + conjunto completo de características do Hibernate. De fato, a maioria das aplicações + (esp. aplicações web) precisam destinguir os objetos pelo identificador, então você deverá + considerar esta, uma característica em lugar de uma limitação. Porém, nós normalmente não + manipulamos a identidade de um objeto, consequentemente o método setter deverá ser privado. + O Hibernate somente nomeará os identificadores quando um objeto for salvo. Você pode ver como + o Hibernate pode acessar métodos públicos, privados, e protegidos, como também campos + (públicos, privados, protegidos) diretamente. A escolha está até você, e você pode combinar + isso para adaptar seu projeto de aplicação + </para> + + <para> + O construtor sem argumentos é um requerimento para todas as classes persistentes; + O Hibernate tem que criar para você os objetos usando Java Reflection. O construtor + pode ser privado, porém, a visibilidade do pacote é requerida para a procuração da + geração em tempo de execução e recuperação eficiente dos dados sem a instrumentação + de bytecode + </para> + + <para> + Coloque este fonte Java no diretório chamado <literal>src</literal> na pasta de desenvolvimento, + e em seu pacote correto. O diretório deverá ser parecido como este: + </para> + + <programlisting><![CDATA[. ++lib + <Hibernate and third-party libraries> ++src + +events + Event.java]]></programlisting> + + <para> + No próximo passo, iremos falar sobre as classes de persistência do Hibernate.. + </para> + + </sect2> + + <sect2 id="tutorial-firstapp-mapping" revision="1"> + <title>O mapeamento do arquivo</title> + + <para> + O Hibernate precisa saber como carregar e armazenar objetos da classe de + persistência. Isto será onde o mapeamento do arquivo do Hibernate entrará em + jogo. O arquivo mapeado informa ao Hibernate, qual tabela no banco de dados + ele deverá acessar, e quais as colunas na tabela ele deverá usar. + </para> + + <para> + A estrutura básica de um arquivo de mapeamento é parecida com: + </para> + + <programlisting><![CDATA[<?xml version="1.0"?> +<!DOCTYPE hibernate-mapping PUBLIC + "-//Hibernate/Hibernate Mapping DTD 3.0//EN" + "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"> + +<hibernate-mapping> +[...] +</hibernate-mapping>]]></programlisting> + + <para> + Note que o Hibernate DTD é muito sofisticado. Você pode usar isso para auto-conclusão + no mapeamento XML dos elementos e atributos no seu editor ou IDE. Você também pode + abrir o arquivo DTD no seu editor – é a maneira mais fácil de ter uma visão geral + de todos os elementos e atributos e dos padrões, como também alguns comentários. + Note que o Hibernate não irá carregar o arquivo DTD da web, e sim do diretório + da aplicação (classpath). O arquivo DTD está incluído no <literal>hibernate3.jar</literal> como + também no diretório <literal>src/</literal> da distribuição do Hibernate. + </para> + + <para> + Nós omitiremos a declaração do DTD nos exemplos futuros para encurtar o código. Isto, é claro, não é opcional. + </para> + + <para> + Entre os dois tags <literal>hibernate-mapping</literal>, inclua um elemento <literal>class</literal>. + Todas as classes persistentes da entidade (novamente, poderá haver + mais tarde, dependências sobre as classes que não são classes-primárias + de entidades) necessitam do tal mapeamento, para uma tabela na base + de dados SQL + </para> + + <programlisting><![CDATA[<hibernate-mapping> + + <class name="events.Event" table="EVENTS"> + + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Mais adiante iremos dizer ao Hibernate como fazer para persistir e carregar objetos da classe + <literal>Event</literal> da tabela <literal>EVENTS</literal>, cada instancia representada por + uma coluna na tabela. Agora, continuaremos com o mapeamento de uma única propriedade identificadora + para as chaves primárias da tabela. Além disso, nós não iremos se importar com esta propriedade + identificadora, nós iremos configurar uma estratégia de geração de id’s para uma chave primária + de coluna surrogate: + </para> + + <programlisting><![CDATA[<hibernate-mapping> + + <class name="events.Event" table="EVENTS"> + <id name="id" column="EVENT_ID"> + <generator class="native"/> + </id> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + O elemento <literal>id</literal> é a declaração da propriedade identificadora, + o <literal>name="id"</literal> declara o nome da propriedade Java – + o Hibernate irá usar os métodos getter e setter para acessar a propriedade. + O atributo da coluna informa ao Hibernate qual coluna da tabela <literal>EVENTS</literal> nós + iremos usar como chave primária. O elemento <literal>generator</literal> especifica + a estratégia de geração do identificador, neste caso usaremos <literal>native</literal>, que + escolhe a melhor estratégia dependendo da base de dados (dialeto) configurada. + O Hibernate suporta a base de dados gerada, globalmente única, bem como a atribuição + aos identificadores da aplicação (ou toda estratégia escrita para uma extensão). + </para> + + <para> + Finalmente incluiremos as declarações para as propriedades persistentes da classe + no arquivo mapeado. Por default, nenhuma das propriedades da classe é considerada persistente: + </para> + + <programlisting><![CDATA[ +<hibernate-mapping> + + <class name="events.Event" table="EVENTS"> + <id name="id" column="EVENT_ID"> + <generator class="native"/> + </id> + <property name="date" type="timestamp" column="EVENT_DATE"/> + <property name="title"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Da mesma maneira que com o elemento <literal>id</literal>, o atributo <literal>name</literal> do elemento + <literal>property</literal> informa ao Hibernate qual método getter e setter deverá usar. + Assim, neste caso, o Hibernate irá procurar pelo <literal>getDate()/setDate()</literal>, + como também pelo <literal>getTitle()/setTitle()</literal>. + </para> + + <para> + Porque fazer o mapeamento da propriedade <literal>date</literal> incluído no + atributo <literal>column</literal>, e no title não fazer? + Sem o atributo <literal>column</literal> o Hibernate por padrão usa o nome + da propriedade como o nome da coluna. Isto trabalha muito + bem para o <literal>title</literal>. Entretanto o <literal>date</literal> é uma palavra-chave reservada + na maioria dos bancos de dados, assim nós melhoramos o mapeamentos + disto com um nome diferente. + </para> + + <para> + A próxima coisa interessante é que mapemanto do <literal>title</literal> + também falta o atributo <literal>type</literal>. O tipo que declaramos e o uso nos + arquivos mapeados, não são como você pôde esperar, atributos de dados Java. + Eles não são como os tipos de base de dados SQL. + Esses tipos podem ser chamados de <emphasis>Tipos de mapeamento Hibernate</emphasis>, que são conversores + que podem traduzir tipos de dados do Java para os tipos de dados SQL e vice-versa. + Novamente, o Hibernate irá tentar determinar a conversão correta e mapeará o <literal>type</literal> + próprio, caso o tipo do atributo não estiver presente no mapeamento. + Em alguns casos, esta detecção automática (que usa Reflection sobre as classes Java) + poderá não ter padrão que você espera ou necessita. + Este é o caso com a propriedade <literal>date</literal>. O Hibernate não pode saber se a propriedade + (que é do <literal>java.util.Date</literal>) pode mapear para uma coluna do tipo <literal>date</literal> + do SQL, <literal>timestamp</literal>, ou <literal>time</literal> . + Nós preservamos a informação cheia de datas e horas pelo mapeamento da propriedade com um conversor + <literal>timestamp</literal>. + </para> + + <para> + Este arquivo de mapeamento deve ser salvo como <literal>Event.hbm.xml</literal>, + corretamente no diretório próximo ao arquivo fonte da Classe Java <literal>Event</literal>. + O nomeamento dos arquivos de mapeamento podem ser arbitrários, porém o sufixo + <literal>hbm.xml</literal> é uma convenção da comunidade dos desenvolvedores do Hibernate. + Esta estrutura do diretório deve agora se parecer com isso: + </para> + + <programlisting><![CDATA[. ++lib + <Hibernate and third-party libraries> ++src + +events + Event.java + Event.hbm.xml]]></programlisting> + + <para> + Nós iremos continuar com a configuração principal do Hibernate. + </para> + + </sect2> + + <sect2 id="tutorial-firstapp-configuration" revision="2"> + <title>Configuração do Hibernate</title> + + <para> + Agora nós temos uma classe persistente e este arquivo de mapeamento no lugar. + Está na hora de configurar o Hibernate. Antes de fazermos isso, iremos precisar de uma base de dados. + O HSQL DB, um SQL DBMS feito em java, pode ser baixado através do site do HSQL DB(http://hsqldb.org/). + Atualmente, você só precisa baixar o <literal>hsqldb.jar</literal>. + Coloque este arquivo no diretório da pasta de desenvolvimento <literal>lib/</literal>. + </para> + + <para> + Crie um diretório chamado <literal>data</literal> no diretório root de desenvolvimento – + Isto será onde o HSQL DB irá armazenar arquivos de dados. Agora iremos iniciar o banco de dados + executando <literal>java -classpath ../lib/hsqldb.jar org.hsqldb.Server</literal> neste diretório de dados. + Você pode ver ele iniciando e conectando ao socket TCP/IP, isto será onde nossa aplicação irá se + conectar depois. Se você deseja iniciar uma nova base de dados durante este tutorial, + finalize o HSQL DB(pressionando o <literal>CTRL + C</literal> na janela), delete todos os + arquivos no diretório <literal>data/</literal>, e inicie o HSQL BD novamente. + </para> + + <para> + O Hibernate é uma camada na sua aplicação na qual se conecta com a base de dados, para isso + necessita de informação da conexão. As conexões são feitas através de um pool de conexão JDBC, + na qual teremos que configurar. A distribuição do Hibernate contém diversas ferramentas de pooling + da conexão JDBC de fonte aberta, mas iremos usar o pool de conexão interna para este tutorial. + Note que você tem que copiar a biblioteca necessária em seu classpath e use configurações + diferentes para pooling de conexão caso você deseje utilizar um software de pooling JDBC terceirizado + para qualidade de produção. + </para> + + <para> + Para as configurações do Hibernate, nós podemos usar um arquivo simples <literal>hibernate.properties</literal>, + um arquivo mais ligeiramente sofisticado <literal>hibernate.cfg.xml</literal> ou até mesmo uma + instalação programática completa. A maioria dos usuários preferem utilizar o arquivo de configuração XML + </para> + + <programlisting><![CDATA[<?xml version='1.0' encoding='utf-8'?> +<!DOCTYPE hibernate-configuration PUBLIC + "-//Hibernate/Hibernate Configuration DTD 3.0//EN" + "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd"> + +<hibernate-configuration> + + <session-factory> + + <!-- Database connection settings --> + <property name="connection.driver_class">org.hsqldb.jdbcDriver</property> + <property name="connection.url">jdbc:hsqldb:hsql://localhost</property> + <property name="connection.username">sa</property> + <property name="connection.password"></property> + + <!-- JDBC connection pool (use the built-in) --> + <property name="connection.pool_size">1</property> + + <!-- SQL dialect --> + <property name="dialect">org.hibernate.dialect.HSQLDialect</property> + + <!-- Enable Hibernate's automatic session context management --> + <property name="current_session_context_class">thread</property> + + <!-- Disable the second-level cache --> + <property name="cache.provider_class">org.hibernate.cache.NoCacheProvider</property> + + <!-- Echo all executed SQL to stdout --> + <property name="show_sql">true</property> + + <!-- Drop and re-create the database schema on startup --> + <property name="hbm2ddl.auto">create</property> + + <mapping resource="events/Event.hbm.xml"/> + + </session-factory> + +</hibernate-configuration>]]></programlisting> + + <para> + Note que esta configuração XML usa um diferente DTD. Nós configuraremos + as <literal>SessionFactory</literal> do Hibernate – uma factory global responsável + por uma base de dedados particular. Se você tiver diversas bases de dados, + use diversas configurações <literal>&lt;session-factory&gt;</literal>, geralmente + em diversos arquivos de configuração (para uma partida mais fácil). + </para> + + <para> + As primeiras quatro <literal>propriedades</literal> do elemento contém a configuração + necessária para a conexão ao JDBC. A propriedade <literal>propriedade</literal> dialect + do elemento especifica a variante particular do SQL que o Hibernate gera. + O gerenciamento automático de sessão do Hibernate para contextos de persistência + estará disponível em breve. A opção <literal>hbm2ddl.auto</literal> habilita a geração + automática de schemas da base de dados – diretamente na base de dados. + Isto também pode ser naturalmente desligado (removendo a opção de configuração) ou redirecionando + para um arquivo com ajuda do <literal>SchemaExport</literal> nas tarefas do Ant. + Finalmente, iremos adicionar os arquivos das classes de persistência mapeadas na configuração. + </para> + + <para> + Copie este arquivo no diretório fonte, assim isto irá terminar na raiz (root) do + classpath. O Hibernate automaticamente procura por um arquivo chamado + <literal>hibernate.cfg.xml</literal> na raiz do classpath, no startup. + </para> + + </sect2> + + <sect2 id="tutorial-firstapp-ant" revision="1"> + <title>Construindo com o Ant</title> + + <para> + Nos iremos, agora, construir o tutorial com Ant. Você ira precisar o Ant instalado – + se encontra disponível <ulink url="http://ant.apache.org/bindownload.cgi">na página de download do Ant</ulink>. + Como instalar o Ant, não será abordado aqui. Caso tenha alguma dúvida, por favor, + vá ao <ulink url="http://ant.apache.org/manual/index.html">Ant manual</ulink>. + Depois que tiver instalado o Ant, podemos começar a criar o arquivo de construção <literal>build.xml</literal>. + Este arquivo será chamado de <literal>build.xml</literal> e posto diretamente no diretório de desenvolvimento. + </para> + + <para> + Um arquivo básico de build, se parece com isto: + </para> + + <programlisting><![CDATA[<project name="hibernate-tutorial" default="compile"> + + <property name="sourcedir" value="${basedir}/src"/> + <property name="targetdir" value="${basedir}/bin"/> + <property name="librarydir" value="${basedir}/lib"/> + + <path id="libraries"> + <fileset dir="${librarydir}"> + <include name="*.jar"/> + </fileset> + </path> + + <target name="clean"> + <delete dir="${targetdir}"/> + <mkdir dir="${targetdir}"/> + </target> + + <target name="compile" depends="clean, copy-resources"> + <javac srcdir="${sourcedir}" + destdir="${targetdir}" + classpathref="libraries"/> + </target> + + <target name="copy-resources"> + <copy todir="${targetdir}"> + <fileset dir="${sourcedir}"> + <exclude name="**/*.java"/> + </fileset> + </copy> + </target> + +</project>]]></programlisting> + + <para> + Isto irá avisar ao Ant para adicionar todos os arquivos no diretório lib terminando com + <literal>.jar</literal>, para o classpath usado para compilação. Irá também copiar todos os + arquivos não-java para o diretório alvo (arquivos de configuração, mapeamento). Se você rodar + o ant agora, deverá ter esta saída. + </para> + + <programlisting><![CDATA[C:\hibernateTutorial\>ant +Buildfile: build.xml + +copy-resources: + [copy] Copying 2 files to C:\hibernateTutorial\bin + +compile: + [javac] Compiling 1 source file to C:\hibernateTutorial\bin + +BUILD SUCCESSFUL +Total time: 1 second ]]></programlisting> + + </sect2> + + <sect2 id="tutorial-firstapp-helpers" revision="3"> + <title>Startup and helpers</title> + + <para> + É hora de carregar e arquivar alguns objetos <literal>Event</literal>, mas primeiro + nós temos de completar o setup com algum código de infraestrutura. Este startup + inclui a construção de um objeto <literal>SessionFactory</literal> global e armazenar + isto em algum lugar de fácil acesso para o código da aplicação. + Uma <literal>SessionFactory</literal> pode abrir novas <literal>Session</literal>'s. + Uma <literal>Session</literal> representa uma unidade single-theaded do trabalho, a + <literal>SessionFactory</literal> é um objeto global thread-safe, instanciado uma vez. + </para> + + <para> + Nos iremos criar uma classe de ajuda <literal>HibernateUtil</literal>, que toma + conta do startup e faz acesso a uma <literal>SessionFactory</literal> conveniente. + Vamos dar uma olhada na implementação: + </para> + + <programlisting><![CDATA[package util; + +import org.hibernate.*; +import org.hibernate.cfg.*; + +public class HibernateUtil { + + private static final SessionFactory sessionFactory; + + static { + try { + // Create the SessionFactory from hibernate.cfg.xml + sessionFactory = new Configuration().configure().buildSessionFactory(); + } catch (Throwable ex) { + // Make sure you log the exception, as it might be swallowed + System.err.println("Initial SessionFactory creation failed." + ex); + throw new ExceptionInInitializerError(ex); + } + } + + public static SessionFactory getSessionFactory() { + return sessionFactory; + } + +}]]></programlisting> + + <para> + Esta classe não só produz a global <literal>SessionFactory</literal> no seu static initializer + (chamado uma vez pela JVM quando a classe é carregada), mas também esconde o fato + de que isto usa um static singleton. Ela pode muito bem, enxergar a + <literal>SessionFactory</literal> do JNDI em um application server. + </para> + + <para> + Se você der à <literal>SessionFactory</literal> um nome, no seu arquivo de configuração. + O Hibernate irá, de fato, tentar uni-lo ao JNDI depois que estiver construído. + Para evitar este completamente este código, você também poderia usar JMX deployment + e deixar o contêiner JMX capaz, instanciar e unir um <literal>HibernateService</literal> + no JNDI. Essas opções avançadas são discutidas no documento de referência do Hibernate. + </para> + + <para> + Coloque o Place <literal>HibernateUtil.java</literal> no diretório de arquivos + de desenvolvimento(source), em um pacote após o <literal>events</literal>: + </para> + + <programlisting><![CDATA[. ++lib + <Hibernate and third-party libraries> ++src + +events + Event.java + Event.hbm.xml + +util + HibernateUtil.java + hibernate.cfg.xml ++data +build.xml]]></programlisting> + + <para> + Novamente, isto deve compilar sem problemas. Finalmente, nós precisamos configurar + um sistema de logging – o Hibernate usa commons logging e deixa você escolher entre o + Log4j e o logging do JDK 1.4 . A maioria dos desenvolvedores preferem o Log4j: copie + <literal>log4j.properties</literal> da distribuição do Hibernate (está no diretório + <literal>etc/</literal>), para seu diretório <literal>src</literal>, + depois vá em hibernate.cfg.xml. Dê uma olhada no exemplo de configuração e mude as + configurações se você quizer ter uma saída mais detalhada. Por default, apenas as + mensagems de startup e shwwn do Hibernate é mostrada no stdout. + </para> + + <para> + O tutorial de infra-estrutura está completo - e nós já estamos preparados para algum + trabalho de verdade com o Hibernate. + </para> + + </sect2> + + <sect2 id="tutorial-firstapp-workingpersistence" revision="4"> + <title>Carregando e salvando objetos</title> + + <para> + Finalmente, nós podemos usar o Hibernate para carregar e armazenar objetos. + Nós escrevemos uma classe <literal>EventManager</literal> com um método main(): + </para> + + <programlisting><![CDATA[package events; +import org.hibernate.Session; + +import java.util.Date; + +import util.HibernateUtil; + +public class EventManager { + + public static void main(String[] args) { + EventManager mgr = new EventManager(); + + if (args[0].equals("store")) { + mgr.createAndStoreEvent("My Event", new Date()); + } + + HibernateUtil.getSessionFactory().close(); + } + + private void createAndStoreEvent(String title, Date theDate) { + + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + + session.beginTransaction(); + + Event theEvent = new Event(); + theEvent.setTitle(title); + theEvent.setDate(theDate); + + session.save(theEvent); + + session.getTransaction().commit(); + } + +}]]></programlisting> + + <para> + We create a new <literal>Event</literal> object, and hand it over to Hibernate. + Hibernate now takes care of the SQL and executes <literal>INSERT</literal>s + on the database. Let's have a look at the <literal>Session</literal> and + <literal>Transaction</literal>-handling code before we run this. + + Nós criamos um novo objeto <literal>Event</literal>, e passamos para o Hibernate. + O Hibernate sabe como tomar conta do SQL e executa <literal>INSERT</literal>s + no banco de dados. Vamos dar uma olhada na <literal>Session</literal> e no + código <literal>Transaction</literal>-handling antes de executarmos. + </para> + + <para> + Um <literal>Session</literal> é uma unidade simples de trabalho. Por agora nós + iremos pegar coisas simples e assumir uma granularidade de um-pra-um entre uma + <literal>Session</literal> do Hibernate e uma transação de banco de dados. + Para proteger nosso código de um atual sistema subjacente de transação (nesse + caso puro JDBC, mas também poderia rodar com JTA), nos usamos a API + <literal>Transaction</literal>, que está disponível na <literal>Session</literal> do Hibernate. + </para> + + <para> + O que a <literal>sessionFactory.getCurrentSession()</literal> faz? Primeiro, você pode + chamar quantas vezes e de onde quiser, uma vez você recebe sua <literal>SessionFactory</literal> + (fácil graças ao <literal>HibernateUtil</literal>). O método <literal>getCurrentSession()</literal> + sempre retorna a unidade de trabalho "corrente". Lembra de que nós mudamos a opção + de configuração desse mecanismo para thread no <literal>hibernate.cfg.xml</literal>? Daqui em + diante, o escopo da unidade de trabalho corrente é a thread Java + corrente que executa nossa aplicação. Entretanto, esta não é toda a verdade. Uma + <literal>Session</literal> começa quando é primeiramente necessária, quando é feita a + primeira chamada à <literal>getCurrentSession()</literal>. É então limitado pelo Hibernate + para thread corrente. Quando a transação termina, tanto com commit quanto rollback, + o Hibernate também desune a <literal>Session</literal> da thread e fecha isso pra você. + Se você chamar <literal>getCurrentSession()</literal> novamente, você receberá uma nova + <literal>Session</literal> e pode começar uma nova unidade de trabalho. Esse modelo de + programação de limite de thread <emphasis>thread-bound</emphasis>, é o modo mais popular + de se usar o Hibernate. + </para> + + <para> + Dê uma olhada no <xref linkend="transactions"/> para mais informações a + respeito de manipulação de transação e demarcação. Nós também pulamos qualquer + manipulação de erro e rollback no exemplo anterior. + </para> + + <para> + Para executar esta primeira rotina, nos teremos que adicionar um ponto de chamada + para o arquivo de build do Ant: + </para> + + <programlisting><![CDATA[<target name="run" depends="compile"> + <java fork="true" classname="events.EventManager" classpathref="libraries"> + <classpath path="${targetdir}"/> + <arg value="${action}"/> + </java> +</target>]]></programlisting> + + <para> + O valor do argumento <literal>action</literal>, é setado na linha de comando quando chamando esse ponto: + </para> + + <programlisting><![CDATA[C:\hibernateTutorial\>ant run -Daction=store]]></programlisting> + + <para> + Você deverá ver, após a compilação, o startup do Hibernate e, dependendo da sua + configuração, muito log de saída. No final você verá a seguinte linha: + </para> + + <programlisting><![CDATA[[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?)]]></programlisting> + + <para> + Este é o <literal>INSERT</literal> executado pelo Hibernate, os pontos de interrogação + representam parêmetros de união do JDBC. Para ver os valores substituídos, ou para diminuir a + verbalidade do log, check seu l<literal>log4j.properties</literal>. + </para> + + <para> + Agora nós gostaríamos de listar os eventos arquivados, então nós adicionamos uma + opção para o método main: + </para> + + <programlisting><![CDATA[if (args[0].equals("store")) { + mgr.createAndStoreEvent("My Event", new Date()); +} +else if (args[0].equals("list")) { + List events = mgr.listEvents(); + for (int i = 0; i < events.size(); i++) { + Event theEvent = (Event) events.get(i); + System.out.println("Event: " + theEvent.getTitle() + + " Time: " + theEvent.getDate()); + } +}]]></programlisting> + + <para> + Nos também adicionamos um novo <literal>método listEvents()</literal>: + </para> + + <programlisting><![CDATA[private List listEvents() { + + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + + session.beginTransaction(); + + List result = session.createQuery("from Event").list(); + + session.getTransaction().commit(); + + return result; +}]]></programlisting> + + <para> + O que nós fazemos aqui, é usar uma query HQL (Hibernate Query Language), + para carregar todos os objetos <literal>Event</literal> exitentes no banco de dados. + O Hibernate irá gerar o SQL apropriado, enviar para o banco de dados e popular objetos + <literal>Event</literal> com os dados. Você pode criar queries mais complexas com + HQL, claro. + </para> + + <para> + Agora, para executar e testar tudo isso, siga os passos a seguir: + </para> + + <itemizedlist> + <listitem> + <para> + Execute <literal>ant run -Daction=store</literal> para armazenar algo no banco de dados + e, claro, gerar o esquema do banco de dados antes pelo hbm2ddl. + </para> + </listitem> + <listitem> + <para> + Agora desabilite hbm2ddl comentando a propriedade no seu arquivo <literal>hibernate.cfg.xml</literal>. + Normalmente só se deixa habilitado em teste unitários contínuos, mas outra carga de hbm2ddl + pode <emphasis>remover</emphasis> tudo que você já tenha arquivado. Sa configuração + <literal>create</literal>, atualmente são traduzidas para "apague todas as tabelas do esquema, + então recrie todas quando a SessionFactory estiver pronta". + </para> + </listitem> + </itemizedlist> + + <para> + Se você agora chamar o Ant com <literal>-Daction=list</literal>, você deverá ver os + eventos que você acabou de criar. Você pode também chamar a ação <literal>store</literal> + mais algumas vezes. + </para> + + <para> + Nota: A maioria dos novos usuários do Hibernate falha nesse ponto e nós regularmente, vemos + questões sobre mensagens de erro de <emphasis>tabela não encontrada </emphasis> . + Entretanto, se você seguir os passos marcados acima, você não terá esse problema, + com o hbm2ddl criando o esquema do banco de dados na primeira execução, e restarts + subsequentes da aplicação irão usar este esquema. Se você mudar o mapeamento e/ou + o esquema do banco de dados, terá de re-habilitar o hbm2ddl mais uma vez. + </para> + + </sect2> + + </sect1> + + <sect1 id="tutorial-associations"> + <title>Part 2 - Mapeando associações</title> + + <para> + Nós mapeamos uma classe de entidade de persistência para uma tabela. Agora vamos continuar + e adicionar algumas associações de classe. Primeiro nos iremos adicionar pessoas a nossa aplicação, + e armazenar os eventos de que elas participam. + </para> + + <sect2 id="tutorial-associations-mappinguser" revision="1"> + <title>Mapeando a classe Person</title> + + <para> + O primeiro código da classe <literal>Person</literal> é simples: + </para> + + <programlisting><![CDATA[package events; + +public class Person { + + private Long id; + private int age; + private String firstname; + private String lastname; + + public Person() {} + + // Accessor methods for all properties, private setter for 'id' + +}]]></programlisting> + + <para> + Crie um novo arquivo de mapeamento, chamado <literal>Person.hbm.xml</literal> (não + esqueça a referencia ao DTD no topo) + </para> + + <programlisting><![CDATA[<hibernate-mapping> + + <class name="events.Person" table="PERSON"> + <id name="id" column="PERSON_ID"> + <generator class="native"/> + </id> + <property name="age"/> + <property name="firstname"/> + <property name="lastname"/> + </class> + +</hibernate-mapping>]]></programlisting> + + <para> + Finalmente, adicione o novo mapeamento a configuração do Hibernate: + </para> + + <programlisting><![CDATA[<mapping resource="events/Event.hbm.xml"/> +<mapping resource="events/Person.hbm.xml"/>]]></programlisting> + + <para> + Nos iremos agora criar uma associação entre estas duas entidades. Obviamente, + pessoas (Person) podem participar de eventos, e eventos possuem participantes. + As questões de design com que teremos de lidar são: direcionalidade, multiplicidade e + comportamento de coleção. + </para> + + </sect2> + + <sect2 id="tutorial-associations-unidirset" revision="3"> + <title>Uma associação Set-based unidirectional</title> + + <para> + Nos iremos adicionar uma coleção de eventos na classe <literal>Person</literal>. Desse jeito + poderemos navegar pelos eventos de uma pessoa em particular, sem executar uma query explicitamente – + apenas chamando <literal>aPerson.getEvents()</literal>. Nos usaremos uma coleção Java, um + <literal>Set</literal>, porquê a coleção não conterá elementos duplicados e a ordem não é + relevante para nós. + </para> + + <para> + Vamos escrever o código para isto nas classes Java e então mapear: + </para> + + <programlisting><![CDATA[public class Person { + + private Set events = new HashSet(); + + public Set getEvents() { + return events; + } + + public void setEvents(Set events) { + this.events = events; + } +}]]></programlisting> + + <para> + Antes de mapearmos esta associação, pense no outro lado. Claramente, poderíamos apenas fazer isto de + forma unidirecional. Ou poderíamos criar outra coleção no <literal>Event</literal>, se quisermos + ser capaz de navegar bidirecionalmente, i.e. um - <literal>anEvent.getParticipants()</literal>. + Isto não é necessário, de perspectiva funcional. Você poderia sempre executar uma query explicita + que retornasse os participantes de um evento em particular. Esta é uma escolha de design que cabe + a você, mas o que é claro nessa discussão é a multiplicidade da associação: "muitos" valores em ambos + os lados, nós chamamos isto uma associação <emphasis>muitos-para-muitos</emphasis>. Daqui pra frente, + nos usaremos o mapeamento muitos-para-muitos do Hibernate: + </para> + + <programlisting><![CDATA[<class name="events.Person" table="PERSON"> + <id name="id" column="PERSON_ID"> + <generator class="native"/> + </id> + <property name="age"/> + <property name="firstname"/> + <property name="lastname"/> + + <set name="events" table="PERSON_EVENT"> + <key column="PERSON_ID"/> + <many-to-many column="EVENT_ID" class="events.Event"/> + </set> + +</class>]]></programlisting> + + <para> + O Hibernate suporta todo tipo de mapeamento de coleção , sendo um <literal>&lt;set&gt;</literal> mais comum. + Para uma associação muitos-para-muitos (ou relacionamento de entidade <emphasis>n:m</emphasis> ), + uma tabela de associação é necessária. Cada linha nessa tabela representa um link entre uma pessoa e um + evento. O nome da tabela é configurado com o atributo <literal>table</literal> do elemento + <literal>set</literal>. O nome da coluna identificadora na associção, peloo lado da pessoa, + é definido com o elemento <literal>&lt;key&gt;</literal> , o nome da coluna pelo lado dos eventos, + e definido com o atributo <literal>column</literal> do <literal>&lt;many-to-many&gt;</literal>. + Você também precisa dizer para o Hibernate a classe dos objetos na sua coleção (a classe do outro + lado das coleções de referência). + </para> + + <para> + O esquema de mapeamento para o banco de dados está a seguir: + </para> + + <programlisting><![CDATA[ + _____________ __________________ + | | | | _____________ + | EVENTS | | PERSON_EVENT | | | + |_____________| |__________________| | PERSON | + | | | | |_____________| + | *EVENT_ID | <--> | *EVENT_ID | | | + | EVENT_DATE | | *PERSON_ID | <--> | *PERSON_ID | + | TITLE | |__________________| | AGE | + |_____________| | FIRSTNAME | + | LASTNAME | + |_____________| + ]]></programlisting> + + </sect2> + + <sect2 id="tutorial-associations-working" revision="1"> + <title>Trabalhando a associação</title> + + <para> + Vamos trazer juntos algumas pessoas e eventos em um novo método na classe <literal>EventManager</literal>:: + </para> + + <programlisting><![CDATA[private void addPersonToEvent(Long personId, Long eventId) { + + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + session.beginTransaction(); + + Person aPerson = (Person) session.load(Person.class, personId); + Event anEvent = (Event) session.load(Event.class, eventId); + + aPerson.getEvents().add(anEvent); + + session.getTransaction().commit(); +}]]></programlisting> + + <para> + Após carregar um <literal>Person</literal> e um <literal>Event</literal>, simplesmente + modifique a coleção usando os métodos normais de uma coleção. Como você pode ver, não há chamada explícita + para <literal>update()</literal> ou <literal>save()</literal>, o Hibernate detecta automaticamente + que a coleção foi modificada e necessita ser atualizada. Isso é chamado de <emphasis>checagem + suja automática</emphasis>, e você também pode usá-la modificando o nome ou a data de qualquer um dos + seus objetos. Assim que eles estiverem no estado <emphasis>persistent</emphasis>, ou seja, + limitado por uma <literal>Session</literal> do Hibernate em particular (i.e. eles foram carregados ou + salvos dentro de uma unidade de trabalho), o Hibernate monitora qualquer alteração e executa o SQL + em modo de escrita em segundo plano. O processo de sincronização do estado da memória com o banco de + dados, geralmente apenas no final de uma unidade de trabalho, é chamado de <emphasis>flushing</emphasis>. + No nosso código, a unidade de trabalho termina com o commit da transação do banco de dados – + como definido pela opção de configuração da <literal>thread</literal> da classe <literal>CurrentSessionContext</literal>. + </para> + + <para> + Você pode também querer carregar pessoas e eventos em diferentes unidades de trabalho. + Ou você modifica um objeto fora de uma <literal>Session</literal>, quando não se encontra no + estado persistent (se já esteve neste estado anteriormente, chamamos esse estado de + <emphasis>detached</emphasis>). Você pode até mesmo modificar uma coleção quando esta + se encontrar no estado detached. + </para> + + <programlisting><![CDATA[private void addPersonToEvent(Long personId, Long eventId) { + + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + session.beginTransaction(); + + Person aPerson = (Person) session + .createQuery("select p from Person p left join fetch p.events where p.id = :pid") + .setParameter("pid", personId) + .uniqueResult(); // Eager fetch the collection so we can use it detached + + Event anEvent = (Event) session.load(Event.class, eventId); + + session.getTransaction().commit(); + + // End of first unit of work + + aPerson.getEvents().add(anEvent); // aPerson (and its collection) is detached + + // Begin second unit of work + + Session session2 = HibernateUtil.getSessionFactory().getCurrentSession(); + session2.beginTransaction(); + + session2.update(aPerson); // Reattachment of aPerson + + session2.getTransaction().commit(); +}]]></programlisting> + + <para> + A chamada <literal>update</literal> cria um objeto persistent novamente, você poderia + dizer que ele liga o objeto a uma nova unidade de trabalho, assim qualquer modificação + que você faça neste objeto enquanto estiver no estado detached pode ser salvo no banco de dados. + Isso inclui qualquer modificação (adição/exclusão) que você faça em uma coleção da entidade deste objeto. + </para> + + <para> + Bom, isso não foi muito usado na nossa situação, porém, é um importante conceito que você + pode aplicar em seus aplicativos. Agora, complete este exercício adicionando uma nova ação + ao método main( ) da classe <literal>EventManager</literal> e chame-o pela linha de comando. + Se você precisar dos identificadores de uma pessoa ou evento – o método <literal>save()</literal> + retorna estes identificadores (você poderá modificar alguns dos métodos anteriores para retornar aquele + identificador): + </para> + + <programlisting><![CDATA[else if (args[0].equals("addpersontoevent")) { + Long eventId = mgr.createAndStoreEvent("My Event", new Date()); + Long personId = mgr.createAndStorePerson("Foo", "Bar"); + mgr.addPersonToEvent(personId, eventId); + System.out.println("Added person " + personId + " to event " + eventId);]]></programlisting> + + <para> + Este foi um exemplo de uma associação entre duas classes igualmente importantes, duas entidades. + Como mencionado anteriormente, há outras classes e tipos dentro de um modelo típico, + geralmente "menos importante". Alguns você já viu, como um <literal>int</literal> ou uma <literal>String</literal>. + Nós chamamos essas classes de <emphasis>value types</emphasis>, e suas instâncias <emphasis>depend</emphasis> + de uma entidade particular. As instâncias desses tipos não possuem sua própria identidade, nem são + compartilhados entre entidades (duas pessoas não referenciam o mesmo objeto <literal>firstname</literal> + mesmo se elas tiverem o mesmo objeto firstname). Naturalmente, os value types não são apenas encontrados + dentro da JDK (de fato, em um aplicativo Hibernate todas as classes JDK são consideradas como value types), + mas você pode também criar suas classes como, por exemplo, <literal>Address</literal> ou <literal>MonetaryAmount</literal>. + + </para> + + <para> + Você também pode criar uma coleção de value types. Isso é conceitualmente muito diferente + de uma coleção de referências para outras entidades, mas em Java parece ser quase a mesma coisa. + </para> + + </sect2> + + <sect2 id="tutorial-associations-valuecollections"> + <title>Coleção de valores</title> + + <para> + Nós adicionamos uma coleção de objetos de tipo de valores à entidade <literal>Person</literal. + Nós querermos armazenar endereços de e-mail, para isso utilizamos o tipo <literal>String</literal>, + e a coleção novamente será um <literal>Set</literal>: + </para> + <programlisting><![CDATA[private Set emailAddresses = new HashSet(); + +public Set getEmailAddresses() { + return emailAddresses; +} + +public void setEmailAddresses(Set emailAddresses) { + this.emailAddresses = emailAddresses; +}]]></programlisting> + + <para> + O mapeamento deste <literal>Set</literal>: + </para> + + <programlisting><![CDATA[<set name="emailAddresses" table="PERSON_EMAIL_ADDR"> + <key column="PERSON_ID"/> + <element type="string" column="EMAIL_ADDR"/> +</set>]]></programlisting> + + <para> + The difference compared with the earlier mapping is the <literal>element</literal> part, which tells Hibernate that the collection + does not contain references to another entity, but a collection of elements of type + <literal>String</literal> (the lowercase name tells you it's a Hibernate mapping type/converter). + Once again, the <literal>table</literal> attribute of the <literal>set</literal> element determines + the table name for the collection. The <literal>key</literal> element defines the foreign-key column + name in the collection table. The <literal>column</literal> attribute in the <literal>element</literal> + element defines the column name where the <literal>String</literal> values will actually be stored. + + A diferença comparada com o mapeamento anterior se encontra na parte <literal>element</literal>, + que indica ao Hibernate que a coleção não contém referências à outra entidade, mas uma coleção de + elementos do tipo <literal>String</literal> (a tag name em miniscula indica que se trata de um + mapeamento do Hibernate para conversão de tipos). Mais uma vez, o atributo <literal>table</literal> + do elemento <literal>set</literal> determina o nome da tabela para a coleção. O elemento + <literal>key</literal> define o nome da coluna de chave estrangeira na tabela de coleção. + O atributo <literal>column</literal> dentro do elemento <literal>element</literal> define o + nome da coluna onde os valores da <literal>String</literal> serão armazenados. + </para> + + <para> + Dê uma olhada no esquema atualizado: + </para> + + <programlisting><![CDATA[ + _____________ __________________ + | | | | _____________ + | EVENTS | | PERSON_EVENT | | | ___________________ + |_____________| |__________________| | PERSON | | | + | | | | |_____________| | PERSON_EMAIL_ADDR | + | *EVENT_ID | <--> | *EVENT_ID | | | |___________________| + | EVENT_DATE | | *PERSON_ID | <--> | *PERSON_ID | <--> | *PERSON_ID | + | TITLE | |__________________| | AGE | | *EMAIL_ADDR | + |_____________| | FIRSTNAME | |___________________| + | LASTNAME | + |_____________| + ]]></programlisting> + + <para> + Você pode observar que a chave primária da tabela da coleção é de na verdade uma chave composta, + usando ambas colunas. Isso também implica que cada pessoa não pode ter endereços de e-mail + duplicados, o que é exatamente a semântica que precisamos para um set em Java. + </para> + + <para> + Você pode agora tentar adicionar elementos a essa coleção, do mesmo modo que fizemos + anteriormente ligando pessoas e eventos. È o mesmo código em Java: + </para> + + <programlisting><![CDATA[private void addEmailToPerson(Long personId, String emailAddress) { + + Session session = HibernateUtil.getSessionFactory().getCurrentSession(); + session.beginTransaction(); + + Person aPerson = (Person) session.load(Person.class, personId); + + // The getEmailAddresses() might trigger a lazy load of the collection + aPerson.getEmailAddresses().add(emailAddress); + + session.getTransaction().commit(); +}]]></programlisting> + + <para> + This time we didnt' use a <emphasis>fetch</emphasis> query to initialize the collection. + Hence, the call to its getter method will trigger an additional select to initialize + it, so we can add an element to it. Monitor the SQL log and try to optimize this with + an eager fetch. + </para> + + </sect2> + + <sect2 id="tutorial-associations-bidirectional" revision="1"> + <title>Associações bidirecionais</title> + + <para> + Agora iremos mapear uma associação bidirecional – fazendo a associação entre pessoas e + eventos, de ambos os lados, em Java. Logicamente, o esquema do banco de dados não muda, + nós continuamos tendo multiplicidades muitos-para-muitos. Um banco de dados é mais flexível do que + uma linguagem de programação para redes, ele não precisa de nenhuma direção de navegação – os + dados podem ser acessados em qualquer caminho possível. + </para> + + <para> + Primeiramente, adicione uma coleção de participantes à classe <literal>Event</literal>: + </para> + + <programlisting><![CDATA[private Set participants = new HashSet(); + +public Set getParticipants() { + return participants; +} + +public void setParticipants(Set participants) { + this.participants = participants; +}]]></programlisting> + + <para> + Agora mapeie este lado da associação em <literal>Event.hbm.xml</literal>. + </para> + + <programlisting><![CDATA[<set name="participants" table="PERSON_EVENT" inverse="true"> + <key column="EVENT_ID"/> + <many-to-many column="PERSON_ID" class="events.Person"/> +</set>]]></programlisting> + + <para> + Como você pode ver, esses é uma mapeamento normal usando <literal>set</literal> em ambos documenentos + de mapeamento. Observe que o nome das colunas em <literal>key</literal> e <literal>many-to-many</literal> + estão trocados em ambos os documentos de mapeamento. A adição mais importante feita está no atributo + <literal>inverse="true"</literal> no elemento set do mapeamento da coleção da classe <literal>Event</literal>. + </para> + + <para> + Isso significa que o Hibernate deve pegar o outro lado – a classe <literal>Person</literal> – + quando necessitar encontrar informação sobre a relação entre as duas entidades. Isso será muito + mais facilmente compreendido quando você analisar como a relação bidirecional entre as entidades é criada. + </para> + + </sect2> + + <sect2 id="tutorial-associations-usingbidir"> + <title>Trabalhando com links bidirecionais</title> + + <para> + Primeiro tenha em mente que o Hibernate não afeta a semântica normal do Java. Como nós criamos + um link entre uma <literal>Person</literal> e um <literal>Event</literal> no exemplo unidirecional? + Nós adicionamos uma instância de <literal>Event</literal>, da coleção de referências de eventos, + a uma instância de <literal>Person</literal>. Então, obviamente, se nós queremos que este link funcione + bidirecionalmente, nós devemos fazer a mesma coisa para o outro lado – adicionando uma referência de + <literal>Person</literal> na coleção de um <literal>Event</literal>. Esse acerto de link de ambos + os lados é absolutamente necessário e você nunca deve esquecer de faze-lo. + </para> + + <para> + Muitos desenvolvedores programam de maneira defensiva e criam métodos + gerenciador de links que ajusta corretamente ambos os lados: + </para> + + <programlisting><![CDATA[protected Set getEvents() { + return events; +} + +protected void setEvents(Set events) { + this.events = events; +} + +public void addToEvent(Event event) { + this.getEvents().add(event); + event.getParticipants().add(this); +} + +public void removeFromEvent(Event event) { + this.getEvents().remove(event); + event.getParticipants().remove(this); +}]]></programlisting> + + <para> + Notice that the get and set methods for the collection are now protected - this allows classes in the + same package and subclasses to still access the methods, but prevents everybody else from messing + with the collections directly (well, almost). You should probably do the same with the collection + on the other side. + </para> + + <para> + What about the <literal>inverse</literal> mapping attribute? For you, and for Java, a bi-directional + link is simply a matter of setting the references on both sides correctly. Hibernate however doesn't + have enough information to correctly arrange SQL <literal>INSERT</literal> and <literal>UPDATE</literal> + statements (to avoid constraint violations), and needs some help to handle bi-directional associations + properly. Making one side of the association <literal>inverse</literal> tells Hibernate to basically + ignore it, to consider it a <emphasis>mirror</emphasis> of the other side. That's all that is necessary + for Hibernate to work out all of the issues when transformation a directional navigation model to + a SQL database schema. The rules you have to remember are straightforward: All bi-directional associations + need one side as <literal>inverse</literal>. In a one-to-many association it has to be the many-side, + in many-to-many association you can pick either side, there is no difference. + </para> + + </sect2> + + <para> + Let's turn this into a small web application. + </para> + + </sect1> + + <sect1 id="tutorial-webapp"> + <title>Part 3 - The EventManager web application</title> + + <para> + A Hibernate web application uses <literal>Session</literal> and <literal>Transaction</literal> + almost like a standalone application. However, some common patterns are useful. We now write + an <literal>EventManagerServlet</literal>. This servlet can list all events stored in the + database, and it provides an HTML form to enter new events. + </para> + + <sect2 id="tutorial-webapp-servlet" revision="1"> + <title>Writing the basic servlet</title> + + <para> + Create a new class in your source directory, in the <literal>events</literal> + package: + </para> + + <programlisting><![CDATA[package events; + +// Imports + +public class EventManagerServlet extends HttpServlet { + + // Servlet code +}]]></programlisting> + + <para> + The servlet handles HTTP <literal>GET</literal> requests only, hence, the method + we implement is <literal>doGet()</literal>: + </para> + + <programlisting><![CDATA[protected void doGet(HttpServletRequest request, + HttpServletResponse response) + throws ServletException, IOException { + + SimpleDateFormat dateFormatter = new SimpleDateFormat("dd.MM.yyyy"); + + try { + // Begin unit of work + HibernateUtil.getSessionFactory() + .getCurrentSession().beginTransaction(); + + // Process request and render page... + + // End unit of work + HibernateUtil.getSessionFactory() + .getCurrentSession().getTransaction().commit(); + + } catch (Exception ex) { + HibernateUtil.getSessionFactory() + .getCurrentSession().getTransaction().rollback(); + throw new ServletException(ex); + } + +}]]></programlisting> + + <para> + The pattern we are applying here is called <emphasis>session-per-request</emphasis>. + When a request hits the servlet, a new Hibernate <literal>Session</literal> is + opened through the first call to <literal>getCurrentSession()</literal> on the + <literal>SessionFactory</literal>. Then a database transaction is started&mdash;all + data access as to occur inside a transaction, no matter if data is read or written + (we don't use the auto-commit mode in applications). + </para> + + <para> + Next, the possible actions of the request are processed and the response HTML + is rendered. We'll get to that part soon. + </para> + + <para> + Finally, the unit of work ends when processing and rendering is complete. If any + problem occured during processing or rendering, an exception will be thrown + and the database transaction rolled back. This completes the + <literal>session-per-request</literal> pattern. Instead of the transaction + demarcation code in every servlet you could also write a servlet filter. + See the Hibernate website and Wiki for more information about this pattern, + called <emphasis>Open Session in View</emphasis>&mdash;you'll need it as soon + as you consider rendering your view in JSP, not in a servlet. + </para> + + </sect2> + + <sect2 id="tutorial-webapp-processing" revision="1"> + <title>Processing and rendering</title> + + <para> + Let's implement the processing of the request and rendering of the page. + </para> + +<programlisting><![CDATA[// Write HTML header +PrintWriter out = response.getWriter(); +out.println("<html><head><title>Event Manager</title></head><body>"); + +// Handle actions +if ( "store".equals(request.getParameter("action")) ) { + + String eventTitle = request.getParameter("eventTitle"); + String eventDate = request.getParameter("eventDate"); + + if ( "".equals(eventTitle) || "".equals(eventDate) ) { + out.println("<b><i>Please enter event title and date.</i></b>"); + } else { + createAndStoreEvent(eventTitle, dateFormatter.parse(eventDate)); + out.println("<b><i>Added event.</i></b>"); + } +} + +// Print page +printEventForm(out); +listEvents(out, dateFormatter); + +// Write HTML footer +out.println("</body></html>"); +out.flush(); +out.close();]]></programlisting> + + <para> + Granted, this coding style with a mix of Java and HTML would not scale + in a more complex application&mdash;keep in mind that we are only illustrating + basic Hibernate concepts in this tutorial. The code prints an HTML + header and a footer. Inside this page, an HTML form for event entry and + a list of all events in the database are printed. The first method is + trivial and only outputs HTML: + </para> + + <programlisting><![CDATA[private void printEventForm(PrintWriter out) { + out.println("<h2>Add new event:</h2>"); + out.println("<form>"); + out.println("Title: <input name='eventTitle' length='50'/><br/>"); + out.println("Date (e.g. 24.12.2009): <input name='eventDate' length='10'/><br/>"); + out.println("<input type='submit' name='action' value='store'/>"); + out.println("</form>"); +}]]></programlisting> + + <para> + The <literal>listEvents()</literal> method uses the Hibernate + <literal>Session</literal> bound to the current thread to execute + a query: + </para> + + <programlisting><![CDATA[private void listEvents(PrintWriter out, SimpleDateFormat dateFormatter) { + + List result = HibernateUtil.getSessionFactory() + .getCurrentSession().createCriteria(Event.class).list(); + if (result.size() > 0) { + out.println("<h2>Events in database:</h2>"); + out.println("<table border='1'>"); + out.println("<tr>"); + out.println("<th>Event title</th>"); + out.println("<th>Event date</th>"); + out.println("</tr>"); + for (Iterator it = result.iterator(); it.hasNext();) { + Event event = (Event) it.next(); + out.println("<tr>"); + out.println("<td>" + event.getTitle() + "</td>"); + out.println("<td>" + dateFormatter.format(event.getDate()) + "</td>"); + out.println("</tr>"); + } + out.println("</table>"); + } +}]]></programlisting> + + <para> + Finally, the <literal>store</literal> action is dispatched to the + <literal>createAndStoreEvent()</literal> method, which also uses + the <literal>Session</literal> of the current thread: + </para> + + <programlisting><![CDATA[protected void createAndStoreEvent(String title, Date theDate) { + Event theEvent = new Event(); + theEvent.setTitle(title); + theEvent.setDate(theDate); + + HibernateUtil.getSessionFactory() + .getCurrentSession().save(theEvent); +}]]></programlisting> + + <para> + That's it, the servlet is complete. A request to the servlet will be processed + in a single <literal>Session</literal> and <literal>Transaction</literal>. As + earlier in the standalone application, Hibernate can automatically bind these + ojects to the current thread of execution. This gives you the freedom to layer + your code and access the <literal>SessionFactory</literal> in any way you like. + Usually you'd use a more sophisticated design and move the data access code + into data access objects (the DAO pattern). See the Hibernate Wiki for more + examples. + </para> + + </sect2> + + <sect2 id="tutorial-webapp-deploy"> + <title>Deploying and testing</title> + + <para> + To deploy this application you have to create a web archive, a WAR. Add the + following Ant target to your <literal>build.xml</literal>: + </para> + +<programlisting><![CDATA[<target name="war" depends="compile"> + <war destfile="hibernate-tutorial.war" webxml="web.xml"> + <lib dir="${librarydir}"> + <exclude name="jsdk*.jar"/> + </lib> + + <classes dir="${targetdir}"/> + </war> +</target>]]></programlisting> + + <para> + This target creates a file called <literal>hibernate-tutorial.war</literal> + in your project directory. It packages all libraries and the <literal>web.xml</literal> + descriptor, which is expected in the base directory of your project: + </para> + + <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<web-app version="2.4" + xmlns="http://java.sun.com/xml/ns/j2ee" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"> + + <servlet> + <servlet-name>Event Manager</servlet-name> + <servlet-class>events.EventManagerServlet</servlet-class> + </servlet> + + <servlet-mapping> + <servlet-name>Event Manager</servlet-name> + <url-pattern>/eventmanager</url-pattern> + </servlet-mapping> +</web-app>]]></programlisting> + + <para> + Before you compile and deploy the web application, note that an additional library + is required: <literal>jsdk.jar</literal>. This is the Java servlet development kit, + if you don't have this library already, get it from the Sun website and copy it to + your library directory. However, it will be only used for compliation and excluded + from the WAR package. + </para> + + <para> + To build and deploy call <literal>ant war</literal> in your project directory + and copy the <literal>hibernate-tutorial.war</literal> file into your Tomcat + <literal>webapp</literal> directory. If you don't have Tomcat installed, download + it and follow the installation instructions. You don't have to change any Tomcat + configuration to deploy this application though. + </para> + + <para> + Once deployed and Tomcat is running, access the application at + <literal>http://localhost:8080/hibernate-tutorial/eventmanager</literal>. Make + sure you watch the Tomcat log to see Hibernate initialize when the first + request hits your servlet (the static initializer in <literal>HibernateUtil</literal> + is called) and to get the detailed output if any exceptions occurs. + </para> + + </sect2> + + </sect1> + + <sect1 id="tutorial-summary" revision="1"> + <title>Summary</title> + + <para> + This tutorial covered the basics of writing a simple standalone Hibernate application + and a small web application. + </para> + + <para> + If you already feel confident with Hibernate, continue browsing through the reference + documentation table of contents for topics you find interesting - most asked are + transactional processing (<xref linkend="transactions"/>), fetch + performance (<xref linkend="performance"/>), or the usage of the API (<xref linkend="objectstate"/>) + and the query features (<xref linkend="objectstate-querying"/>). + </para> + + <para> + Don't forget to check the Hibernate website for more (specialized) tutorials. + </para> + + </sect1> + +</chapter> Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/xml.xml (from rev 12794, core/trunk/documentation/manual/pt-BR/src/main/docbook/modules/xml.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/xml.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/xml.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,289 @@ +<chapter id="xml"> + <title>Mapeamento XML</title> + + <para><emphasis> + Note that this is an experimental feature in Hibernate 3.0 and is under + extremely active development. + Veja que essa é uma feature experimental no Hibernate 3.0 e o + desenvolvimento esta bastante ativo. + + </emphasis></para> + + <sect1 id="xml-intro" revision="1"> + <title>Trabalhando com dados em XML</title> + + <para> + O Hibernate permite que se trabalhe com dados persistentes em XML quase + da mesma maneira como você trabalhar com POJOs persistentes. Uma árvore XML + parseada, pode ser imaginada como apenas uma maneira de representar os + dados relacionais como objetos, ao invés dos POJOs. + </para> + + <para> + O Hibernate suporta a API dom4j para manipular árvores XML. Você pode escrever + queries que retornem árvores dom4j do banco de dados e automaticamente + sincronizar com o banco de dados qualquer modificação feita nessas árvores. + Você pode até mesmo pegar um documento XML, parsear usando o dom4j, e escrever + as alterações no banco de dados usando quaisquer operações básicas do Hibernate: + <literal>persist(), saveOrUpdate(),merge(), delete(), replicate()</literal> + (merging ainda não é suportado) + </para> + + <para> + Essa funcionalidade tem várias aplicações incluindo importação/exportação de dados, + externalização de dados de entidade via JMS or SOAP e relatórios usando XSLT. + </para> + + <para> + Um mapeamento simples pode ser usado para simultaneamente mapear propriedades + da classe e nós de um documento XML para um banco de dados ou, se não houver + classe para mapear, pode ser usado simplesmente para mapear o XML. + </para> + + <sect2 id="xml-intro-mapping"> + <title>Especificando o mapeamento de uma classe e de um arquivo XML simultaneamente</title> + + <para> + Segue um exemplo de como mapear um POJO e um XML ao mesmo tempo: + </para> + + <programlisting><![CDATA[<class name="Account" + table="ACCOUNTS" + node="account"> + + <id name="accountId" + column="ACCOUNT_ID" + node="@id"/> + + <many-to-one name="customer" + column="CUSTOMER_ID" + node="customer/@id" + embed-xml="false"/> + + <property name="balance" + column="BALANCE" + node="balance"/> + + ... + +</class>]]></programlisting> + </sect2> + + <sect2 id="xml-onlyxml"> + <title>Especificando somente um mapeamento XML</title> + + <para> + Segue um exemplo que não contém uma classe POJO: + </para> + + <programlisting><![CDATA[<class entity-name="Account" + table="ACCOUNTS" + node="account"> + + <id name="id" + column="ACCOUNT_ID" + node="@id" + type="string"/> + + <many-to-one name="customerId" + column="CUSTOMER_ID" + node="customer/@id" + embed-xml="false" + entity-name="Customer"/> + + <property name="balance" + column="BALANCE" + node="balance" + type="big_decimal"/> + + ... + +</class>]]></programlisting> + + <para> + Esse mapeamento permite que você acesse os dados como uma árvore dom4j ou um + grafo de de pares nome de propriedade/valor (<literal>Map</literal>s do Java). + Os nomes de propriedades são somente construções lógicas que podem ser + referenciadas em consultas HQL. + </para> + + </sect2> + + </sect1> + + <sect1 id="xml-mapping" revision="1"> + <title>Mapeando metadados com XML</title> + + <para> + Muitos elementos do mapeamento do Hibernate aceitam o atributo <literal>node</literal>. + Por meio dele, você pode especificar o nome de um atributo ou elemento XML que contém + a propriedade ou os dados da entidade. O formato do atributo <literal>node</literal> + deve ser o seguinte: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para><literal>"element-name"</literal> - mapeia para o elemento XML com determinado nome</para> + </listitem> + <listitem> + <para><literal>"@attribute-name"</literal> - mapeia para o atributo XML com determinado nome</para> + </listitem> + <listitem> + <para><literal>"."</literal> - mapeia para o elemento pai</para> + </listitem> + <listitem> + <para> + <literal>"element-name/@attribute-name"</literal> - + mapeia para para o atributo com determinado nome do elemento com determinado nome + </para> + </listitem> + </itemizedlist> + + <para> + Para coleções e associações simples, existe o atributo adicional <literal>embed-xml</literal>. + Se o atributo <literal>embed-xml="true"</literal>, que é o valor padrão, a árvore XML para a + entidade associada (ou coleção de determinado tipo de valor) será embutida diretamente na + árvore XML que contém a associação. Por outro lado, se <literal>embed-xml="false"</literal>, + então apenas o valor do identificador referenciado irá aparecer no XML para associações + simples e coleções simplesmentenão irão aparecer. + </para> + + <para> + Você precisa tomar cuidado em não deixar o<literal>embed-xml="true"</literal> + para muitas associações, pois o XML não suporta bem referências circulares. + </para> + + <programlisting><![CDATA[<class name="Customer" + table="CUSTOMER" + node="customer"> + + <id name="id" + column="CUST_ID" + node="@id"/> + + <map name="accounts" + node="." + embed-xml="true"> + <key column="CUSTOMER_ID" + not-null="true"/> + <map-key column="SHORT_DESC" + node="@short-desc" + type="string"/> + <one-to-many entity-name="Account" + embed-xml="false" + node="account"/> + </map> + + <component name="name" + node="name"> + <property name="firstName" + node="first-name"/> + <property name="initial" + node="initial"/> + <property name="lastName" + node="last-name"/> + </component> + + ... + +</class>]]></programlisting> + + <para> + Nesse caso, decidimos embutir a colenção de account ids, e não os dados de accounts. + A query HQL a seguir: + </para> + + <programlisting><![CDATA[from Customer c left join fetch c.accounts where c.lastName like :lastName]]></programlisting> + + <para> + Retornaria um conjunto de dados como esse: + </para> + + <programlisting><![CDATA[<customer id="123456789"> + <account short-desc="Savings">987632567</account> + <account short-desc="Credit Card">985612323</account> + <name> + <first-name>Gavin</first-name> + <initial>A</initial> + <last-name>King</last-name> + </name> + ... +</customer>]]></programlisting> + + <para> + Se você setar <literal>embed-xml="true"</literal> em um mapeamento + <literal>&lt;one-to-many&gt;</literal>, os dados se pareceriam com o seguinte: + </para> + + <programlisting><![CDATA[<customer id="123456789"> + <account id="987632567" short-desc="Savings"> + <customer id="123456789"/> + <balance>100.29</balance> + </account> + <account id="985612323" short-desc="Credit Card"> + <customer id="123456789"/> + <balance>-2370.34</balance> + </account> + <name> + <first-name>Gavin</first-name> + <initial>A</initial> + <last-name>King</last-name> + </name> + ... +</customer>]]></programlisting> + + </sect1> + + + <sect1 id="xml-manipulation" revision="1"> + <title>Manipulando dados em XML</title> + + <para> + Vamos reler e atualizar documentos em XML em nossa aplicação. Nós fazemos isso + obtendo uma session do dom4j: + </para> + + <programlisting><![CDATA[Document doc = ....; + +Session session = factory.openSession(); +Session dom4jSession = session.getSession(EntityMode.DOM4J); +Transaction tx = session.beginTransaction(); + +List results = dom4jSession + .createQuery("from Customer c left join fetch c.accounts where c.lastName like :lastName") + .list(); +for ( int i=0; i<results.size(); i++ ) { + //add the customer data to the XML document + Element customer = (Element) results.get(i); + doc.add(customer); +} + +tx.commit(); +session.close();]]></programlisting> + + <programlisting><![CDATA[Session session = factory.openSession(); +Session dom4jSession = session.getSession(EntityMode.DOM4J); +Transaction tx = session.beginTransaction(); + +Element cust = (Element) dom4jSession.get("Customer", customerId); +for ( int i=0; i<results.size(); i++ ) { + Element customer = (Element) results.get(i); + //change the customer name in the XML and database + Element name = customer.element("name"); + name.element("first-name").setText(firstName); + name.element("initial").setText(initial); + name.element("last-name").setText(lastName); +} + +tx.commit(); +session.close();]]></programlisting> + + <para> + É extremamente útil combinar essa funcionalidade com a operação <literal>replicate()</literal> + do Hibernate para implementar importação/exportação baseadas em XML. + </para> + + </sect1> + +</chapter> + Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/images/AuthorWork.png (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/images/AuthorWork.png) =================================================================== (Binary files differ) Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/images/AuthorWork.zargo (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/images/AuthorWork.zargo) =================================================================== (Binary files differ) Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/images/CustomerOrderProduct.png (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/images/CustomerOrderProduct.png) =================================================================== (Binary files differ) Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/images/CustomerOrderProduct.zargo (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/images/CustomerOrderProduct.zargo) =================================================================== (Binary files differ) Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/images/EmployerEmployee.png (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/images/EmployerEmployee.png) =================================================================== (Binary files differ) Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/images/EmployerEmployee.zargo (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/images/EmployerEmployee.zargo) =================================================================== (Binary files differ) Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/images/full_cream.png (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/images/full_cream.png) =================================================================== (Binary files differ) Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/images/full_cream.svg (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/images/full_cream.svg) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/images/full_cream.svg (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/images/full_cream.svg 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,429 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN" +"http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd" +[ + <!ATTLIST svg + xmlns:xlink CDATA #FIXED "http://www.w3.org/1999/xlink"> +]> +<!-- Created with Sodipodi ("http://www.sodipodi.com/") --> +<svg + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink" + width="354.331" + height="336.614" + id="svg1"> + <defs + id="defs3"> + <linearGradient + x1="0" + y1="0" + x2="1" + y2="0" + id="linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop128" /> + <stop + style="stop-color:#ffffff;stop-opacity:1;" + offset="1" + id="stop129" /> + </linearGradient> + <linearGradient + x1="0" + y1="0" + x2="1" + y2="0" + id="linearGradient130" + xlink:href="#linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad" /> + <radialGradient + cx="0.5" + cy="0.5" + fx="0.5" + fy="0.5" + r="0.5" + id="radialGradient131" + xlink:href="#linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad" /> + </defs> + <g + transform="matrix(0.823795,0,0,0.823795,0.120302,5.25349)" + style="font-size:12;" + id="g659"> + <rect + width="212.257" + height="57.2441" + x="17.9576" + y="100.132" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect137" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + transform="matrix(0.743454,0,0,0.482981,6.46949,52.2178)" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect132" /> + </g> + <rect + width="325.86" + height="63.6537" + x="17.4083" + y="15.194" + style="font-size:12;fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect136" /> + <rect + width="325.86" + height="63.6537" + x="13.6713" + y="12.4966" + style="font-size:12;fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect126" /> + <g + transform="matrix(1.14345,0,0,0.729078,-1.67818,105.325)" + style="font-size:12;" + id="g164"> + <rect + width="285.502" + height="77.2688" + x="16.6979" + y="222.966" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect138" /> + <rect + width="285.502" + height="77.2688" + x="14.7335" + y="221.002" + transform="translate(-1.30962,-1.30992)" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect133" /> + </g> + <text + x="170.824753" + y="58.402939" + transform="scale(0.823795,0.823795)" + style="font-size:18;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text183"> + <tspan + x="170.824997" + y="58.402901" + id="tspan360"> +Application</tspan> + </text> + <text + x="178.076340" + y="364.281433" + transform="scale(0.823795,0.823795)" + style="font-size:18;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text197"> + <tspan + x="178.076004" + y="364.281006" + id="tspan421"> +Database</tspan> + </text> + <text + x="68.605331" + y="138.524582" + transform="scale(0.823795,0.823795)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text216"> + <tspan + x="68.605301" + y="138.524994" + id="tspan384"> +SessionFactory</tspan> + </text> + <rect + width="67.0014" + height="101.35" + x="196.927" + y="89.2389" + style="font-size:12;fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect387" /> + <rect + width="67.0014" + height="101.35" + x="194.633" + y="86.4389" + style="font-size:12;fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect388" /> + <text + x="249.108841" + y="173.885559" + transform="scale(0.823795,0.823795)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text389"> + <tspan + x="249.108994" + y="173.886002" + id="tspan392"> +Session</tspan> + </text> + <rect + width="73.0355" + height="101.35" + x="270.995" + y="90.0018" + style="font-size:12;fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect395" /> + <rect + width="73.0355" + height="101.35" + x="267.869" + y="87.2018" + style="font-size:12;fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect396" /> + <text + x="328.593658" + y="174.715622" + transform="scale(0.823795,0.823795)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text397"> + <tspan + x="328.593994" + y="174.716003" + id="tspan563"> +Transaction</tspan> + </text> + <g + transform="matrix(0.29544,0,0,0.397877,9.70533,103.96)" + style="font-size:12;" + id="g565"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect566" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect567" /> + </g> + <text + x="25.592752" + y="204.497803" + transform="scale(0.823795,0.823795)" + style="font-size:10;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text568"> + <tspan + x="25.592800" + y="204.498001" + id="tspan662"> +TransactionFactory</tspan> + </text> + <g + transform="matrix(0.298082,0,0,0.397877,99.6898,103.96)" + style="font-size:12;" + id="g573"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect574" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect575" /> + </g> + <text + x="134.030670" + y="205.532791" + transform="scale(0.823795,0.823795)" + style="font-size:10;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text576"> + <tspan + x="134.031006" + y="205.533005" + id="tspan664"> +ConnectionProvider</tspan> + </text> + <g + transform="matrix(1.14345,0,0,0.729078,-1.67818,38.9539)" + style="font-size:12;" + id="g587"> + <rect + width="285.502" + height="77.2688" + x="16.6979" + y="222.966" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect588" /> + <rect + width="285.502" + height="77.2688" + x="14.7335" + y="221.002" + transform="translate(-1.30962,-1.30992)" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect589" /> + </g> + <rect + width="90.951" + height="44.4829" + x="25.6196" + y="206.028" + style="font-size:12;fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect594" /> + <rect + width="90.951" + height="44.4829" + x="24.4229" + y="204.135" + style="font-size:12;fill:#b3b3b3;fill-rule:evenodd;stroke-width:1pt;" + id="rect595" /> + <text + x="85.575645" + y="282.300354" + transform="scale(0.823795,0.823795)" + style="font-size:18;font-weight:normal;stroke-width:1pt;font-family:Helvetica;text-anchor:middle;" + id="text596"> + <tspan + x="85.575600" + y="282.299988" + id="tspan607"> +JNDI</tspan> + </text> + <rect + width="90.951" + height="44.4829" + x="236.937" + y="206.791" + style="font-size:12;fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect610" /> + <rect + width="90.951" + height="44.4829" + x="235.741" + y="204.898" + style="font-size:12;fill:#b3b3b3;fill-rule:evenodd;stroke-width:1pt;" + id="rect611" /> + <text + x="342.093201" + y="283.226410" + transform="scale(0.823795,0.823795)" + style="font-size:18;font-weight:normal;stroke-width:1pt;font-family:Helvetica;text-anchor:middle;" + id="text612"> + <tspan + x="342.092987" + y="283.226013" + id="tspan621"> +JTA</tspan> + </text> + <rect + width="90.951" + height="44.4829" + x="130.134" + y="206.791" + style="font-size:12;fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect616" /> + <rect + width="90.951" + height="44.4829" + x="128.937" + y="204.898" + style="font-size:12;fill:#b3b3b3;fill-rule:evenodd;stroke-width:1pt;" + id="rect617" /> + <text + x="212.445343" + y="283.226410" + transform="scale(0.823795,0.823795)" + style="font-size:18;font-weight:normal;stroke-width:1pt;font-family:Helvetica;text-anchor:middle;" + id="text618"> + <tspan + x="212.445007" + y="283.226013" + id="tspan623"> +JDBC</tspan> + </text> + <g + transform="matrix(0.823795,0,0,0.823795,0.120302,6.19341)" + style="font-size:12;" + id="g637"> + <g + transform="matrix(0.499515,0,0,0.415467,-0.237339,5.61339)" + id="g167"> + <rect + width="199.065" + height="61.5532" + x="61.8805" + y="68.4288" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect134" /> + <rect + width="199.065" + height="61.5532" + x="59.2613" + y="65.8095" + style="fill:#e0e0e0;fill-rule:evenodd;stroke-width:1pt;" + id="rect135" /> + </g> + <text + x="33.749969" + y="50.589706" + style="font-size:11;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text188"> + <tspan + x="33.750000" + y="50.589699" + id="tspan635"> +Transient Objects</tspan> + </text> + </g> + <g + transform="matrix(0.823795,0,0,0.823795,0.120302,5.25349)" + style="font-size:12;" + id="g644"> + <g + transform="matrix(0.297486,0,0,0.516482,230.251,36.9178)" + id="g364"> + <rect + width="199.065" + height="61.5532" + x="61.8805" + y="68.4288" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect365" /> + <rect + width="199.065" + height="61.5532" + x="59.2613" + y="65.8095" + style="fill:#e0e0e0;fill-rule:evenodd;stroke-width:1pt;" + id="rect366" /> + </g> + <text + x="277.123230" + y="85.155571" + style="font-size:11;font-weight:normal;stroke-width:1pt;font-family:Helvetica;text-anchor:middle;" + id="text367"> + <tspan + x="277.122986" + y="85.155602" + id="tspan631"> +Persistent</tspan> + <tspan + x="277.122986" + y="96.155602" + id="tspan633"> +Objects</tspan> + </text> + </g> +</svg> Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/images/hibernate_logo_a.png (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/images/hibernate_logo_a.png) =================================================================== (Binary files differ) Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/images/lite.png (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/images/lite.png) =================================================================== (Binary files differ) Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/images/lite.svg (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/images/lite.svg) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/images/lite.svg (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/images/lite.svg 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,334 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN" +"http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd" +[ + <!ATTLIST svg + xmlns:xlink CDATA #FIXED "http://www.w3.org/1999/xlink"> +]> +<!-- Created with Sodipodi ("http://www.sodipodi.com/") --> +<svg + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink" + width="318.898" + height="248.031" + id="svg1"> + <defs + id="defs3"> + <linearGradient + x1="0" + y1="0" + x2="1" + y2="0" + id="linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop128" /> + <stop + style="stop-color:#ffffff;stop-opacity:1;" + offset="1" + id="stop129" /> + </linearGradient> + <linearGradient + x1="0" + y1="0" + x2="1" + y2="0" + id="linearGradient130" + xlink:href="#linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad" /> + <radialGradient + cx="0.5" + cy="0.5" + fx="0.5" + fy="0.5" + r="0.5" + id="radialGradient131" + xlink:href="#linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad" /> + </defs> + <rect + width="291.837" + height="57.0074" + x="17.3169" + y="18.646" + style="font-size:12;fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect136" /> + <rect + width="291.837" + height="57.0074" + x="13.9703" + y="16.2302" + style="font-size:12;fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect126" /> + <g + transform="matrix(0.326107,0,0,0.765831,9.59261,8.98517)" + style="font-size:12;" + id="g161"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect137" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect132" /> + </g> + <g + transform="matrix(1.02406,0,0,0.652953,0.223384,39.9254)" + style="font-size:12;" + id="g164"> + <rect + width="285.502" + height="77.2688" + x="16.6979" + y="222.966" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect138" /> + <rect + width="285.502" + height="77.2688" + x="14.7335" + y="221.002" + transform="translate(-1.30962,-1.30992)" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect133" /> + </g> + <g + transform="matrix(0.449834,0,0,0.338463,-3.15909,9.73319)" + style="font-size:12;" + id="g167"> + <rect + width="199.065" + height="61.5532" + x="61.8805" + y="68.4288" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect134" /> + <rect + width="199.065" + height="61.5532" + x="59.2613" + y="65.8095" + style="fill:#e0e0e0;fill-rule:evenodd;stroke-width:1pt;" + id="rect135" /> + </g> + <text + x="302.277679" + y="65.943230" + transform="scale(0.73778,0.73778)" + style="font-size:18;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text183"> + <tspan + x="302.277954" + y="65.943184" + id="tspan360"> +Application</tspan> + </text> + <text + x="36.235924" + y="63.796055" + transform="scale(0.73778,0.73778)" + style="font-size:14;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text188"> + <tspan + x="36.235950" + y="63.796051" + id="tspan427"> +Transient Objects</tspan> + </text> + <text + x="180.416245" + y="290.543701" + transform="scale(0.73778,0.73778)" + style="font-size:18;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text197"> + <tspan + x="180.415939" + y="290.543549" + id="tspan421"> +Database</tspan> + </text> + <text + x="25.037701" + y="179.154755" + transform="scale(0.73778,0.73778)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text216"> + <tspan + x="25.037655" + y="179.154648" + id="tspan384"> +SessionFactory</tspan> + </text> + <g + transform="matrix(0.252763,0,0,0.765831,109.104,8.98517)" + style="font-size:12;" + id="g386"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect387" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect388" /> + </g> + <g + transform="matrix(0.297394,0,0,0.572692,101.502,21.6359)" + style="font-size:12;" + id="g364"> + <rect + width="199.065" + height="61.5532" + x="61.8805" + y="68.4288" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect365" /> + <rect + width="199.065" + height="61.5532" + x="59.2613" + y="65.8095" + style="fill:#e0e0e0;fill-rule:evenodd;stroke-width:1pt;" + id="rect366" /> + </g> + <text + x="202.746506" + y="102.992203" + transform="scale(0.73778,0.73778)" + style="font-size:14;font-weight:normal;stroke-width:1pt;font-family:Helvetica;text-anchor:middle;" + id="text367"> + <tspan + x="202.746948" + y="102.992249" + id="tspan423"> +Persistent</tspan> + <tspan + x="202.746948" + y="116.992355" + id="tspan425"> +Objects</tspan> + </text> + <text + x="174.458496" + y="180.080795" + transform="scale(0.73778,0.73778)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text389"> + <tspan + x="174.458618" + y="180.080338" + id="tspan392"> +Session</tspan> + </text> + <g + transform="matrix(0.127369,0,0,0.765831,188.675,8.98517)" + style="font-size:12;" + id="g394"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect395" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect396" /> + </g> + <text + x="260.413269" + y="179.154739" + transform="scale(0.73778,0.73778)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text397"> + <tspan + x="260.412964" + y="179.154343" + id="tspan400"> +JDBC</tspan> + </text> + <g + transform="matrix(0.127369,0,0,0.765831,229.156,8.98517)" + style="font-size:12;" + id="g405"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect406" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect407" /> + </g> + <text + x="320.606903" + y="179.154739" + transform="scale(0.73778,0.73778)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text408"> + <tspan + x="320.606964" + y="179.154343" + id="tspan417"> +JNDI</tspan> + </text> + <g + transform="matrix(0.127369,0,0,0.765831,269.281,8.98517)" + style="font-size:12;" + id="g411"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect412" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect413" /> + </g> + <text + x="377.096313" + y="179.154739" + transform="scale(0.73778,0.73778)" + style="font-size:16;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text414"> + <tspan + x="377.096008" + y="179.154999" + id="tspan145"> +JTA</tspan> + </text> +</svg> Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/images/overview.png (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/images/overview.png) =================================================================== (Binary files differ) Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/images/overview.svg (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/images/overview.svg) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/images/overview.svg (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/images/overview.svg 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,250 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN" +"http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd" +[ + <!ATTLIST svg + xmlns:xlink CDATA #FIXED "http://www.w3.org/1999/xlink"> +]> +<!-- Created with Sodipodi ("http://www.sodipodi.com/") --> +<svg + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink" + width="248.031" + height="248.031" + id="svg1"> + <defs + id="defs3"> + <linearGradient + x1="0" + y1="0" + x2="1" + y2="0" + id="linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad"> + <stop + style="stop-color:#000000;stop-opacity:1;" + offset="0" + id="stop128" /> + <stop + style="stop-color:#ffffff;stop-opacity:1;" + offset="1" + id="stop129" /> + </linearGradient> + <linearGradient + x1="0" + y1="0" + x2="1" + y2="0" + id="linearGradient130" + xlink:href="#linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad" /> + <radialGradient + cx="0.5" + cy="0.5" + fx="0.5" + fy="0.5" + r="0.5" + id="radialGradient131" + xlink:href="#linearGradient127" + gradientUnits="objectBoundingBox" + spreadMethod="pad" /> + </defs> + <g + transform="matrix(0.771934,0,0,0.771934,4.36019,-3.02123)" + style="font-size:12;" + id="g158"> + <rect + width="285.502" + height="77.2688" + x="16.6979" + y="17.3527" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect136" /> + <rect + width="285.502" + height="77.2688" + x="14.7335" + y="15.3883" + transform="translate(-1.30962,-1.30992)" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect126" /> + </g> + <g + transform="matrix(0.771934,0,0,0.771934,4.36019,3.04452)" + style="font-size:12;" + id="g161"> + <rect + width="285.502" + height="118.523" + x="16.6979" + y="99.2053" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect137" /> + <rect + width="285.502" + height="118.523" + x="13.4238" + y="95.9309" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect132" /> + </g> + <g + transform="matrix(0.771934,0,0,0.771934,4.36019,8.0993)" + style="font-size:12;" + id="g164"> + <rect + width="285.502" + height="77.2688" + x="16.6979" + y="222.966" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect138" /> + <rect + width="285.502" + height="77.2688" + x="14.7335" + y="221.002" + transform="translate(-1.30962,-1.30992)" + style="fill:#d2d2d2;fill-rule:evenodd;stroke-width:1pt;" + id="rect133" /> + </g> + <g + transform="matrix(0.771934,0,0,0.543505,2.59104,21.1103)" + style="font-size:12;" + id="g167"> + <rect + width="199.065" + height="61.5532" + x="61.8805" + y="68.4288" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect134" /> + <rect + width="199.065" + height="61.5532" + x="59.2613" + y="65.8095" + style="fill:#e0e0e0;fill-rule:evenodd;stroke-width:1pt;" + id="rect135" /> + </g> + <text + x="105.392174" + y="56.568123" + transform="scale(0.771934,0.771934)" + style="font-size:24;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text183"> + <tspan + x="105.392273" + y="56.568146" + id="tspan186"> +Application</tspan> + </text> + <text + x="81.820183" + y="103.149330" + transform="scale(0.771934,0.771934)" + style="font-size:20;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text188"> + <tspan + x="81.820213" + y="103.149727" + id="tspan206"> +Persistent Objects</tspan> + </text> + <text + x="111.548180" + y="278.927887" + transform="scale(0.771934,0.771934)" + style="font-size:24;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text197"> + <tspan + x="111.547874" + y="278.927551" + id="tspan200"> +Database</tspan> + </text> + <text + x="94.436180" + y="153.805740" + transform="scale(0.771934,0.771934)" + style="font-size:24;font-weight:normal;stroke-width:1pt;font-family:Helvetica;" + id="text216"> + <tspan + x="94.436180" + y="153.805740" + id="tspan221"> +HIBERNATE</tspan> + </text> + <g + transform="matrix(0.771934,0,0,0.771934,2.59083,1.02261)" + style="font-size:12;" + id="g254"> + <g + transform="translate(4.58374,2.61928)" + id="g176"> + <g + transform="matrix(0.571429,0,0,0.67347,-10.6174,117.093)" + id="g170"> + <rect + width="199.065" + height="61.5532" + x="61.8805" + y="68.4288" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect171" /> + <rect + width="199.065" + height="61.5532" + x="59.2613" + y="65.8095" + style="fill:#e0e0e0;fill-rule:evenodd;stroke-width:1pt;" + id="rect172" /> + </g> + <g + transform="matrix(0.571429,0,0,0.67347,138.682,117.093)" + id="g173"> + <rect + width="199.065" + height="61.5532" + x="61.8805" + y="68.4288" + style="fill:#757575;fill-rule:evenodd;stroke-width:1pt;" + id="rect174" /> + <rect + width="199.065" + height="61.5532" + x="59.2613" + y="65.8095" + style="fill:#e0e0e0;fill-rule:evenodd;stroke-width:1pt;" + id="rect175" /> + </g> + </g> + <text + x="47.259438" + y="182.367538" + style="font-weight:bold;stroke-width:1pt;font-family:Courier;" + id="text191"> + <tspan + x="47.259399" + y="182.367996" + id="tspan212"> +hibernate.</tspan> + <tspan + x="47.259399" + y="194.367996" + id="tspan214"> +properties</tspan> + </text> + <text + x="198.523010" + y="188.260941" + style="font-weight:normal;stroke-width:1pt;font-family:helvetica;" + id="text194"> + <tspan + id="tspan195"> +XML Mapping</tspan> + </text> + </g> +</svg> Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/legal_notice.xml (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/legal_notice.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/legal_notice.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/legal_notice.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,52 @@ +<?xml version='1.0'?> +<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<!-- + ~ Copyright (c) 2007, Red Hat Middleware, LLC. All rights reserved. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, v. 2.1. This program is distributed in the + ~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied + ~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + ~ Lesser General Public License for more details. You should have received a + ~ copy of the GNU Lesser General Public License, v.2.1 along with this + ~ distribution; if not, write to the Free Software Foundation, Inc., + ~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + ~ + ~ Red Hat Author(s): Steve Ebersole + --> +<legalnotice id="Legal_Notice"> + <title>Legal Notice</title> + <para> + <address> + <street>1801 Varsity Drive</street> + <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country> + <phone>Phone: +1 919 754 3700</phone> + <phone>Phone: 888 733 4281</phone> + <fax>Fax: +1 919 754 3701</fax> + <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country> + </address> + </para> + <para> + Copyright <trademark class="copyright"></trademark> 2007 by Red Hat, Inc. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, V1.0 or later (the latest version is presently available at <ulink url="http://www.opencontent.org/openpub/">http://www.opencon...>). + </para> + <para> + Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. + </para> + <para> + Distribution of the work or derivative of the work in any standard (paper) book form for commercial purposes is prohibited unless prior permission is obtained from the copyright holder. + </para> + <para> + Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries. + </para> + <para> + All other trademarks referenced herein are the property of their respective owners. + </para> + <para> + The GPG fingerprint of the security(a)redhat.com key is: + </para> + <para> + CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E + </para> +</legalnotice> \ No newline at end of file Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/legal_notice2.xml (from rev 14073, core/trunk/documentation/manual/en-US/src/main/docbook/legal_notice.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/legal_notice2.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/legal_notice2.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,15 @@ +<?xml version='1.0'?> +<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<legalnotice id="Legal_Notice"> + <title>Translation-specific Legal Notice</title> + <para> + <emphasis>Advertencia! Esta é uma versão traduzida do inglês da + documentação de referencia do Hibernate. A versão traduziada pode estar + desatualizada. Sem dúvida, as diferenças devem ser pequenas e serão corrigidas o + mais breve possivel. Consulte a documentação de referencia em inglês, se estiver + faltando alguma informação ou você encotrar erros de tradução. Se quiser + colaborar com ama tradução em particular, entre em contato com um dos tradutores + abaixo:</emphasis>. Gamarra + </para> +</legalnotice> \ No newline at end of file Deleted: core/trunk/documentation/manual/pt-BR/src/main/docbook/master.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/master.xml 2007-10-09 19:14:22 UTC (rev 14079) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/master.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -1,261 +0,0 @@ -<?xml version='1.0' encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN" - "../support/docbook-dtd/docbookx.dtd" -[ -<!ENTITY tutorial SYSTEM "modules/tutorial.xml"> -<!ENTITY architecture SYSTEM "modules/architecture.xml"> -<!ENTITY configuration SYSTEM "modules/configuration.xml"> -<!ENTITY persistent-classes SYSTEM "modules/persistent_classes.xml"> -<!ENTITY basic-mapping SYSTEM "modules/basic_mapping.xml"> -<!ENTITY collection-mapping SYSTEM "modules/collection_mapping.xml"> -<!ENTITY association-mapping SYSTEM "modules/association_mapping.xml"> -<!ENTITY component-mapping SYSTEM "modules/component_mapping.xml"> -<!ENTITY inheritance-mapping SYSTEM "modules/inheritance_mapping.xml"> -<!ENTITY session-api SYSTEM "modules/session_api.xml"> -<!ENTITY transactions SYSTEM "modules/transactions.xml"> -<!ENTITY events SYSTEM "modules/events.xml"> -<!ENTITY batch SYSTEM "modules/batch.xml"> -<!ENTITY query-hql SYSTEM "modules/query_hql.xml"> -<!ENTITY query-criteria SYSTEM "modules/query_criteria.xml"> -<!ENTITY query-sql SYSTEM "modules/query_sql.xml"> -<!ENTITY filters SYSTEM "modules/filters.xml"> -<!ENTITY xml SYSTEM "modules/xml.xml"> -<!ENTITY performance SYSTEM "modules/performance.xml"> -<!ENTITY toolset-guide SYSTEM "modules/toolset_guide.xml"> -<!ENTITY example-parentchild SYSTEM "modules/example_parentchild.xml"> -<!ENTITY example-weblog SYSTEM "modules/example_weblog.xml"> -<!ENTITY example-mappings SYSTEM "modules/example_mappings.xml"> -<!ENTITY best-practices SYSTEM "modules/best_practices.xml"> -]> - -<book lang="en"> - - <bookinfo> - <title>HIBERNATE - Relational Persistence for Idiomatic Java</title> - <subtitle>Documenta��o da Refer�ncia do Hibernate</subtitle> - <releaseinfo>3.2 cr2</releaseinfo> - </bookinfo> - - <toc/> - - <preface id="preface" revision="2"> - <title>Pref�cio</title> - - <para> - <emphasis>Advertencia! Esta � uma vers�o traduzida do ingl�s da - documenta��o de referencia do Hibernate. A vers�o traduziada pode estar - desatualizada. Sem d�vida, as diferen�as devem ser pequenas e ser�o corrigidas o - mais breve possivel. Consulte a documenta��o de referencia em ingl�s, se estiver - faltando alguma informa��o ou voc� encotrar erros de tradu��o. Se quiser - colaborar com ama tradu��o em particular, entre em contato com um dos tradutores - abaixo:</emphasis>. Gamarra - - </para> - - <para> - Tradutor(es) em ordem alfab�tica: - </para> - - <itemizedlist> - <listitem> - <para> - <emphasis>Alvaro Netto</emphasis> alvaronetto(a)cetip.com.br - </para> - </listitem> - <listitem> - <para> - <emphasis>Anderson Braulio</emphasis> andersonbraulio(a)gmail.com - </para> - </listitem> - <listitem> - <para> - <emphasis>Daniel Vieira Costa</emphasis> danielvc(a)gmail.com - </para> - </listitem> - <listitem> - <para> - <emphasis>Francisco gamarra</emphasis> francisco.gamarra(a)gmail.com - </para> - </listitem> - <listitem> - <para> - <emphasis>Gamarra</emphasis> mauricio.gamarra(a)gmail.com - </para> - </listitem> - <listitem> - <para> - <emphasis>Luiz Carlos Rodrigues</emphasis> luizcarlos_rodrigues(a)yahoo.com.br - </para> - </listitem> - <listitem> - <para> - <emphasis>Marcel Castelo</emphasis> marcel.castelo(a)gmail.com - </para> - </listitem> - - <listitem> - <para> - <emphasis>Paulo C�sar</emphasis> paulocol(a)gmail.com - </para> - </listitem> - <listitem> - <para> - <emphasis>Pablo L. de Miranda</emphasis> pablolmiranda(a)gmail.com - </para> - </listitem> - <listitem> - <para> - <emphasis>Renato Deggau</emphasis> rdeggau(a)gmail.com - </para> - </listitem> - <listitem> - <para> - <emphasis>Rog�rio Ara�jo</emphasis> rgildoaraujo(a)yahoo.com.br - </para> - </listitem> - <listitem> - <para> - <emphasis>Wanderson Siqueira</emphasis> wandersonxs(a)gmail.com - </para> - </listitem> - - - </itemizedlist> - - <para> - Trabalhando com software orientado a objetos e banco de dados relacional, podemos - ter alguns inc�modos hoje em dia em ambientes empresariais. Hibernate � uma ferramenta - que mapeia o objeto/relacional para o ambiente Java. O termo de mapeamento de - objeto/relacional (ou ORM � Object/Relational Mapping) se refere a t�cnica de mapear - uma representa��o de dados de um modelo de objeto para dados de modelo - relacional com o esquema baseado em SQL - </para> - - <para> - O Hibernate n�o somente cuida do mapeamento de classes em Java - para tabelas de banco de dados (e de tipos de dados em Java para tipos de dados em SQL), como tamb�m - fornece facilidade de consultas e recupera��o de dados, podendo tamb�m reduzir significantemente o - tempo de desenvolvimento gasto com a manipula��o manual de dados no SQL e JDBC. - </para> - - <para> - O objetivo do Hibernate � de aliviar o desenvolvedor de 95 por cento das tarefas de programa��o - relacionadas aos dados comuns de persist�ncia. O Hibernate talvez n�o seja a melhor solu��o para - aplica��es de dados-data-centric que somente usa stored-procedures para implementar a l�gica - de neg�cio no banco de dados, isto � muito utilizado com o dom�nio de modelos orientado a objetos e - l�gicas de neg�cio em camadas do meio (middle-tier) baseadas em Java. Por�m, o Hibernate - poder� certamente ajuda-lo a remover ou encapsular o c�digo SQL de um vendedor espec�fico, - ajudando tamb�m com a tarefa comum da tradu��o do resultado ajustado de uma representa��o - para um gr�fico de objetos. - </para> - - <para> - Se voc� for novo no Hibernate e no mapeamento Objeto/Relacional, ou at� mesmo em Java, - por favor, siga os seguintes passos. - </para> - - <orderedlist> - <listitem> - <para> - Leia <xref linkend="tutorial"/> para um tutorial com instru��es passo-a-passo. - O c�digo fonte para do tutorial est� inclu�do na distribui��o no diret�rio - <literal>doc/reference/tutorial/</literal>. - </para> - </listitem> - <listitem> - <para> - Leia o <xref linkend="architecture"/> para entender o ambiente onde o Hibernate pode ser utilizado. - </para> - </listitem> - <listitem> - <para> - D� uma olhada no diret�rio de exemplo <literal>eg/</literal> da distribui��o - do Hibernate, ele cont�m uma simples aplica��o standalone. - Copie seu driver JDBC para o diret�rio <literal>lib/</literal> e edite o arquivo - <literal>etc/hibernate.properties</literal>, especificando corretamente os valores - para seu banco de dados. Usando o prompt de commando no diretorio de distribuicao, - digite <literal>ant eg</literal> (usando Ant), ou no Windows, digite - <literal>build eg</literal>. - </para> - </listitem> - <listitem> - <para> - Use esta documenta��o de referencia como sua fonte primaria de informa��o. - Considere ler tamb�m o livro <emphasis>Java Persistence with Hibernate</emphasis> - (http://www.manning.com/bauer2) caso voc� precise de mais ajuda com o - desenvolvimento de aplica��es ou caso prefira um tutorial passo-a-passo. - Tamb�m visite o site http://caveatemptor.hibernate.org e fa�a o download - da aplica��o de exemplo do Java Persistence with Hibernate. - </para> - </listitem> - <listitem> - <para> - FAQs (perguntas feitas com mais freq��ncia) est�o respondidas no site do Hibernate - </para> - </listitem> - <listitem> - <para> - Demonstra��es, exemplos e tutorials est�o dispon�veis no site do Hibernate. - </para> - </listitem> - <listitem> - <para> - A �rea da comunidade no site do Hibernate � uma boa fonte de recursos - para padr�es de projeto e v�rias solu��es de integra��o (Tomcat, JBoss AS, Struts, EJB, etc.). - </para> - </listitem> - </orderedlist> - - <para> - Caso voc� tenha d�vidas, use o f�rum dos usu�rios encontrado no site do Hibernate. - N�s tamb�m fornecemos um sistema para controle de bug�s (JIRA) para relat�rios de erros - e requisi��es de features. Se voc� est� interessado no desenvolvimento do Hibernate, - junte-se a lista de e-mail dos desenvolvedores. - </para> - - <para> - Suporte comercial de desenvolvimento, suporte de produ��o e treinamento para o Hibernate - est� dispon�vel atrav�s do JBoss Inc. (veja http://www.hibernate.org/SupportTraining). - O Hibernate � um Projeto Profissional de C�digo Aberto e um componente cr�tico da su�te - de produtos JBoss Enterprise Middleware System (JEMS). - </para> - - </preface> - - &tutorial; - - &architecture; - - &configuration; - - &persistent-classes; - - &basic-mapping; - &collection-mapping; - &association-mapping; - &component-mapping; - &inheritance-mapping; - - &session-api; - &transactions; - &events; - &batch; - - &query-hql; - &query-criteria; - &query-sql; - &filters; - &xml; - - &performance; - - &toolset-guide; - - &example-parentchild; - &example-weblog; - &example-mappings; - - &best-practices; - -</book> - Copied: core/trunk/documentation/manual/pt-BR/src/main/docbook/translators.xml (from rev 14074, core/trunk/documentation/manual/fr-FR/src/main/docbook/translators.xml) =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/translators.xml (rev 0) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/translators.xml 2007-10-09 19:32:35 UTC (rev 14080) @@ -0,0 +1,93 @@ +<?xml version='1.0'?> + +<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<!-- + ~ Copyright (c) 2007, Red Hat Middleware, LLC. All rights reserved. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, v. 2.1. This program is distributed in the + ~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied + ~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + ~ Lesser General Public License for more details. You should have received a + ~ copy of the GNU Lesser General Public License, v.2.1 along with this + ~ distribution; if not, write to the Free Software Foundation, Inc., + ~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + ~ + ~ Red Hat Author(s): Steve Ebersole + --> +<authorgroup id="AuthorGroup"> + + <othercredit class="translator"> + <firstname>Alvaro</firstname> + <surname>Netto</surname> + <email&gt;alvaronetto(a)cetip.com.br&lt;/email&gt; + </othercredit> + + <othercredit class="translator"> + <firstname>Anderson</firstname> + <surname>Braulio</surname> + <email&gt;andersonbraulio(a)gmail.com&lt;/email&gt; + </othercredit> + + <othercredit class="translator"> + <firstname>Daniel Vieira</firstname> + <surname>Costa</surname> + <email&gt;danielvc(a)gmail.com&lt;/email&gt; + </othercredit> + + <othercredit class="translator"> + <firstname>Francisco</firstname> + <surname>gamarra</surname> + <email&gt;francisco.gamarra(a)gmail.com&lt;/email&gt; + </othercredit> + + <othercredit class="translator"> + <firstname>Gamarra</firstname> + <email&gt;mauricio.gamarra(a)gmail.com&lt;/email&gt; + </othercredit> + + <othercredit class="translator"> + <firstname>Luiz Carlos</firstname> + <surname>Rodrigues</surname> + <email&gt;luizcarlos_rodrigues(a)yahoo.com.br&lt;/email&gt; + </othercredit> + + <othercredit class="translator"> + <firstname>Marcel</firstname> + <surname>Castelo</surname> + <email&gt;marcel.castelo(a)gmail.com&lt;/email&gt; + </othercredit> + + <othercredit class="translator"> + <firstname>Paulo</firstname> + <surname>César</surname> + <email&gt;paulocol(a)gmail.com&lt;/email&gt; + </othercredit> + + <othercredit class="translator"> + <firstname>Pablo L.</firstname> + <surname>de Miranda</surname> + <email&gt;pablolmiranda(a)gmail.com&lt;/email&gt; + </othercredit> + + <othercredit class="translator"> + <firstname>Renato</firstname> + <surname>Deggau</surname> + <email&gt;rdeggau(a)gmail.com&lt;/email&gt; + </othercredit> + + <othercredit class="translator"> + <firstname>Rogério</firstname> + <surname>Araújo</surname> + <email&gt;rgildoaraujo(a)yahoo.com.br&lt;/email&gt; + </othercredit> + + <othercredit class="translator"> + <firstname>Wanderson</firstname> + <surname>Siqueira</surname> + <email&gt;wandersonxs(a)gmail.com&lt;/email&gt; + </othercredit> + +</authorgroup> \ No newline at end of file