[hibernate-commits] Hibernate SVN: r14080 - in
core/trunk/documentation/manual/pt-BR/src/main: docbook and 2
other directories.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Tue Oct 9 15:32:35 EDT 2007
Author: steve.ebersole at 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>©rightYear;</year>
+ <holder>©rightHolder;</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ão Geral</title>
+
+ <para>
+ Uma visã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á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><key></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><column></literal>, mas sim o elemento
+ <literal><key></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><class></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><hibernate-mapping></literal>.
+ </para>
+ </callout>
+ <callout arearefs="class6">
+ <para>
+ <literal>catalog</literal> (opcional): Sobrepõe o nome do catálogo especificado
+ pelo elemento root <literal><hibernate-mapping></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><union-subclass></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><subclass></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><class></literal> como uma
+ <literal><subclass></literal> ou <literal><joined-subclass></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><subclass></literal> or
+ <literal><joined-subclass></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><subselect></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><id></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="element-name|@attribute-name|element/@attribute|."
+
+ <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><composite-id></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><generator></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><param></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><generator></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><one-to-one></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</litera