[hibernate-commits] Hibernate SVN: r14136 - core/trunk/documentation/manual/pt-BR/src/main/docbook/content.

Author: xhuang(a)jboss.com Date: 2007-10-25 20:48:48 -0400 (Thu, 25 Oct 2007) New Revision: 14136 Modified: 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/xml.xml Log: Remove ^M characters, match with latest English XML Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/association_mapping.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/association_mapping.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/association_mapping.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="associations"> +<chapter id="associations"> <title>Mapeamento de Associações</title> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/basic_mapping.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/basic_mapping.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/basic_mapping.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,3494 +1,3660 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="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> - +<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-id-enhanced"> + <title>Enhanced identifier generators</title> + + <para> + Starting with release 3.2.3, there are 2 new generators which represent a re-thinking of 2 different + aspects of identifier generation. The first aspect is database portability; the second is optimization + (not having to query the database for every request for a new identifier value). These two new + generators are intended to take the place of some of the named generators described above (starting + in 3.3.x); however, they are included in the current releases and can be referenced by FQN. + </para> + + <para> + The first of these new generators is <literal>org.hibernate.id.enhanced.SequenceStyleGenerator</literal> + which is intended firstly as a replacement for the <literal>sequence</literal> generator and secondly as + a better portability generator than <literal>native</literal> (because <literal>native</literal> + (generally) chooses between <literal>identity</literal> and <literal>sequence</literal> which have + largely different semantics which can cause subtle isssues in applications eyeing portability). + <literal>org.hibernate.id.enhanced.SequenceStyleGenerator</literal> however achieves portability in + a different manner. It chooses between using a table or a sequence in the database to store its + incrementing values depending on the capabilities of the dialect being used. The difference between this + and <literal>native</literal> is that table-based and sequence-based storage have the same exact + semantic (in fact sequences are exactly what Hibernate tries to emmulate with its table-based + generators). This generator has a number of configuration parameters: + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>sequence_name</literal> (optional, defaults to <literal>hibernate_sequence</literal>): + The name of the sequence (or table) to be used. + </para> + </listitem> + <listitem> + <para> + <literal>initial_value</literal> (optional, defaults to <literal>1</literal>): The initial + value to be retrieved from the sequence/table. In sequence creation terms, this is analogous + to the clause typical named "STARTS WITH". + </para> + </listitem> + <listitem> + <para> + <literal>increment_size</literal> (optional, defaults to <literal>1</literal>): The value by + which subsequent calls to the sequence/table should differ. In sequence creation terms, this + is analogous to the clause typical named "INCREMENT BY". + </para> + </listitem> + <listitem> + <para> + <literal>force_table_use</literal> (optional, defaults to <literal>false</literal>): Should + we force the use of a table as the backing structure even though the dialect might support + sequence? + </para> + </listitem> + <listitem> + <para> + <literal>value_column</literal> (optional, defaults to <literal>next_val</literal>): Only + relevant for table structures! The name of the column on the table which is used to + hold the value. + </para> + </listitem> + <listitem> + <para> + <literal>optimizer</literal> (optional, defaults to <literal>none</literal>): + See <xref linkend="mapping-declaration-id-enhanced-optimizers"/> + </para> + </listitem> + </itemizedlist> + </para> + <para> + The second of these new generators is <literal>org.hibernate.id.enhanced.TableGenerator</literal> which + is intended firstly as a replacement for the <literal>table</literal> generator (although it actually + functions much more like <literal>org.hibernate.id.MultipleHiLoPerTableGenerator</literal>) and secondly + as a re-implementation of <literal>org.hibernate.id.MultipleHiLoPerTableGenerator</literal> utilizing the + notion of pluggable optimiziers. Essentially this generator defines a table capable of holding + a number of different increment values simultaneously by using multiple distinctly keyed rows. This + generator has a number of configuration parameters: + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>table_name</literal> (optional, defaults to <literal>hibernate_sequences</literal>): + The name of the table to be used. + </para> + </listitem> + <listitem> + <para> + <literal>value_column_name</literal> (optional, defaults to <literal>next_val</literal>): + The name of the column on the table which is used to hold the value. + </para> + </listitem> + <listitem> + <para> + <literal>segment_column_name</literal> (optional, defaults to <literal>sequence_name</literal>): + The name of the column on the table which is used to hold the "segement key". This is the + value which distinctly identifies which increment value to use. + </para> + </listitem> + <listitem> + <para> + <literal>segment_value</literal> (optional, defaults to <literal>default</literal>): + The "segment key" value for the segment from which we want to pull increment values for + this generator. + </para> + </listitem> + <listitem> + <para> + <literal>segment_value_length</literal> (optional, defaults to <literal>255</literal>): + Used for schema generation; the column size to create this segment key column. + </para> + </listitem> + <listitem> + <para> + <literal>initial_value</literal> (optional, defaults to <literal>1</literal>): + The initial value to be retrieved from the table. + </para> + </listitem> + <listitem> + <para> + <literal>increment_size</literal> (optional, defaults to <literal>1</literal>): + The value by which subsequent calls to the table should differ. + </para> + </listitem> + <listitem> + <para> + <literal>optimizer</literal> (optional, defaults to <literal></literal>): + See <xref linkend="mapping-declaration-id-enhanced-optimizers"/> + </para> + </listitem> + </itemizedlist> + </para> + </sect2> + + <sect2 id="mapping-declaration-id-enhanced-optimizers"> + <title>Identifier generator optimization</title> + <para> + For identifier generators which store values in the database, it is inefficient for them to hit the + database on each and every call to generate a new identifier value. Instead, you'd ideally want to + group a bunch of them in memory and only hit the database when you have exhausted your in-memory + value group. This is the role of the pluggable optimizers. Currently only the two enhanced generators + (<xref linkend="mapping-declaration-id-enhanced"/> support this notion. + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>none</literal> (generally this is the default if no optimizer was specified): This + says to not perform any optimizations, and hit the database each and every request. + </para> + </listitem> + <listitem> + <para> + <literal>hilo</literal>: applies a hi/lo algorithm around the database retrieved values. The + values from the database for this optimizer are expected to be sequential. The values + retrieved from the database structure for this optimizer indicates the "group number"; the + <literal>increment_size</literal> is multiplied by that value in memory to define a group + "hi value". + </para> + </listitem> + <listitem> + <para> + <literal>pooled</literal>: like was discussed for <literal>hilo</literal>, this optimizers + attempts to minimize the number of hits to the database. Here, however, we simply store + the starting value for the "next group" into the database structure rather than a sequential + value in combination with an in-memory grouping algorithm. <literal>increment_size</literal> + here refers to the values coming from the database. + </para> + </listitem> + </itemizedlist> + </para> + </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> + Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/batch.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/batch.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/batch.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,360 +1,364 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="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> +<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 id="disablebatching" revision="1"> + Note that Hibernate disables insert batching at the JDBC level transparently if you + use an <literal>identiy</literal> identifier generator. +</para> + + <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> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/best_practices.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/best_practices.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/best_practices.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="best-practices" revision="3"> +<chapter id="best-practices" revision="3"> <title>Boas práticas</title> <variablelist spacing="compact"> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/collection_mapping.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/collection_mapping.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/collection_mapping.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="collections"> +<chapter id="collections"> <title>Mapeamento de Coleções</title> <sect1 id="collections-persistent" revision="3"> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/component_mapping.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/component_mapping.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/component_mapping.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="components"> +<chapter id="components"> <title>Mapeamento de Componentes</title> <para> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/configuration.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/configuration.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/configuration.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,1792 +1,1789 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="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> - +<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> + 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 <literal>JDBCTransactionFactory</literal>). + <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 <literal>hibernate.cfg.xml</literal>. + <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> + Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/events.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/events.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/events.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="events"> +<chapter id="events"> <title>Interceptadores e Eventos</title> <para> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_mappings.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_mappings.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_mappings.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="example-mappings"> +<chapter id="example-mappings"> <title>Exemplo: Vários Mapeamentos</title> <para> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_parentchild.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_parentchild.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_parentchild.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="example-parentchild"> +<chapter id="example-parentchild"> <title>Example: Parent/Child</title> <para> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_weblog.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_weblog.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/example_weblog.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="example-weblog"> +<chapter id="example-weblog"> <title>Example: Weblog Application</title> <sect1 id="example-weblog-classes"> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/filters.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/filters.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/filters.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="filters"> +<chapter id="filters"> <title>Filtrando dados</title> <para> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/inheritance_mapping.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/inheritance_mapping.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/inheritance_mapping.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="inheritance"> +<chapter id="inheritance"> <title>Mapeamento de Herança</title> <sect1 id="inheritance-strategies" revision="3"> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/performance.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/performance.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/performance.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="performance"> +<chapter id="performance"> <title>Aumentando a performance</title> <sect1 id="performance-fetching" revision="2"> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/persistent_classes.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/persistent_classes.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/persistent_classes.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="persistent-classes" revision="2"> +<chapter id="persistent-classes" revision="2"> <title>Persistent Classes</title> <para> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/preface.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/preface.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/preface.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!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"> +<preface id="preface" revision="2"> <title>Prefácio</title> <para> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_criteria.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_criteria.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_criteria.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="querycriteria"> +<chapter id="querycriteria"> <title>Consultas por critérios</title> <para> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_hql.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_hql.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_hql.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,1163 +1,1174 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="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> - +<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-identifier-property"> + <title>Refering to identifier property</title> + + <para> + There are, generally speaking, 2 ways to refer to an entity's identifier property: + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + The special property (lowercase) <literal>id</literal> may be used to reference the identifier + property of an entity <emphasis>provided that entity does not define a non-identifier property + named id</emphasis>. + </para> + </listitem> + <listitem> + <para> + If the entity defines a named identifier property, you may use that property name. + </para> + </listitem> + </itemizedlist> + + <para> + References to composite identifier properties follow the same naming rules. If the + entity has a non-identifier property named id, the composite identifier property can only + be referenced by its defined named; otherwise, the special <literal>id</literal> property + can be used to rerference the identifier property. + </para> + + <para> + Note: this has changed significantly starting in version 3.2.2. In previous versions, + <literal>id</literal> <emphasis>always</emphasis> referred to the identifier property no + matter what its actual name. A ramification of that decision was that non-identifier + properties named <literal>id</literal> could never be referenced in Hibernate queries. + </para> + </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> + Note that subqueries can also utilize <literal>row value constructor</literal> syntax. See + <xref linkend="queryhql-tuple"/> for more details. + </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> + Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_sql.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_sql.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/query_sql.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="querysql" revision="2"> +<chapter id="querysql" revision="2"> <title>Native SQL</title> <para>You may also express queries in the native SQL dialect of your Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/session_api.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/session_api.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/session_api.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,1248 +1,1270 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="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> - +<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> + + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>persist()</literal> makes a transient instance persistent. + However, it doesn't guarantee that the identifier value will be assigned to + the persistent instance immediately, the assignment might happen at flush time. + <literal>persist()</literal> also guarantees that it will not execute an + <literal>INSERT</literal> statement if it is called outside of transaction + boundaries. This is useful in long-running conversations with an extended + Session/persistence context. + </para> + </listitem> + <listitem> + <para> + <literal>save()</literal> does guarantee to return an identifier. If an INSERT + has to be executed to get the identifier ( e.g. "identity" generator, not + "sequence"), this INSERT happens immediately, no matter if you are inside or + outside of a transaction. This is problematic in a long-running conversation + with an extended Session/persistence context. + </para> + </listitem> + </itemizedlist> + <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> + Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/toolset_guide.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/toolset_guide.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/toolset_guide.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="toolsetguide" revision="2"> +<chapter id="toolsetguide" revision="2"> <title>Toolset Guide</title> <para> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/transactions.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/transactions.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/transactions.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,1150 +1,1148 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="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> - +<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>. + + 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> + Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/tutorial.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/tutorial.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/tutorial.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,1533 +1,1550 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="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> +<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 + </para> + + <para> + <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> + Related to the unit of work scope, should the Hibernate <literal>Session</literal> be used to + execute one or several database operations? The above example uses one <literal>Session</literal> + for one operation. This is pure coincidence, the example is just not complex enough to show any + other approach. The scope of a Hibernate <literal>Session</literal> is flexible but you should + never design your application to use a new Hibernate <literal>Session</literal> for + <emphasis>every</emphasis> database operation. So even if you see it a few more times in + the following (very trivial) examples, consider <emphasis>session-per-operation</emphasis> + an anti-pattern. A real (web) application is shown later in this tutorial. + </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> + Do <emphasis>not</emphasis> use a new Hibernate <literal>Session</literal> for + every database operation. Use one Hibernate <literal>Session</literal> that is + scoped to the whole request. Use <literal>getCurrentSession()</literal>, so that + it is automatically bound to the current Java thread. + </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> Modified: core/trunk/documentation/manual/pt-BR/src/main/docbook/content/xml.xml =================================================================== --- core/trunk/documentation/manual/pt-BR/src/main/docbook/content/xml.xml 2007-10-26 00:46:38 UTC (rev 14135) +++ core/trunk/documentation/manual/pt-BR/src/main/docbook/content/xml.xml 2007-10-26 00:48:48 UTC (rev 14136) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="xml"> +<chapter id="xml"> <title>Mapeamento XML</title> <para><emphasis>